Repository navigation
docs: sync remaining 82 hand-written docs with actual implementation (audit pass 2) - #1904
Merged
Merged
Conversation
…(audit pass 2) Finishes the implementation-accuracy audit started in #1866 (which covered 46 docs in getting-started/concepts/guides). This pass covers the remaining 82 hand-written docs — guides (incl. cheatsheets/contracts/metadata/runtime-services), protocol (objectos/objectql/objectui), releases, and the docs index. A multi-agent audit read each doc, located the real implementation in packages/, and adversarially verified every finding against the code (a second verifier re-checked each applied fix and repaired over-corrections). This applies 486 verified fixes across 73 docs, plus 28 verifier repairs. Auto-generated references/ docs (DO-NOT-EDIT, produced from packages/spec) were excluded. Recurring classes of fix: - broken-example / inaccurate-api: code samples and method names that don't exist or changed — fabricated transaction methods (tx.insert/tx.update), non-existent helpers (definePlugin), wrong package names (@objectstack/services/service-cache -> @objectstack/service-cache), ViewFieldSchema -> FormFieldSchema, wrong @objectstack/spec subpath imports. - fabricated-feature: field-type props that aren't in the schema (sanitize/allowed_tags/protocols/region/rows), a phantom `Workflow` metadata type with *.workflow.ts conventions, fabricated CLI scaffold output. - naming/enum drift: max_length -> maxLength; relationship/complex type lists corrected to real enum values; OWDModel value spellings (public_read/...). - security model: FLS non-editable write rejects with PermissionDeniedError (403) rather than silent strip; PermissionSet over Salesforce-style shapes. - outdated paths/env: OS_EMAIL__PROVIDER double-underscore, /v1 REST prefixes, config-resolution precedence and envKey coercion examples. Navigation-safe: no files moved, frontmatter preserved on every doc. Verified: `next build` compiles all 1113 pages clean (exit 0). Residual items the audit could not confirm against code, plus the observation that committed references/ have drifted from spec, are recorded in docs/audits/2026-06-handwritten-docs-accuracy-followups.md for a follow-up pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
This was referenced Jun 15, 2026
os-zhuang
added a commit
that referenced
this pull request
Jun 15, 2026
…ation (#1906) * chore(docs): tooling to keep hand-written docs in sync with implementation Stands up recurring implementation-accuracy verification for the 128 hand-written docs as the platform evolves, layered cheapest-and-earliest first: 1. scripts/docs-audit/affected-docs.mjs — maps packages/** changes to the hand-written docs that reference the affected packages (by npm name / repo path), so an audit can be scoped to what actually changed instead of re-auditing everything. Supports --all and --json. 2. .github/workflows/docs-drift-check.yml — advisory CI gate: on PRs touching packages/**, posts a sticky PR comment listing the docs that reference the changed code. Flags drift at the source; never fails the build. 3. .claude/workflows/docs-accuracy-audit.js — the reusable multi-agent audit (audit + adversarial verifier per doc), parameterized by args.docs; defaults to all hand-written docs. Same pipeline that produced #1866 and #1904. 4. scripts/docs-audit/README.md — how the four parts fit together, including the scheduled-routine backstop. References (content/docs/references/, generated from packages/spec) are out of scope and handled by a separate regenerate pass. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore: add no-release changeset for docs-drift tooling Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Sep 14, 2026
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Finishes the implementation-accuracy audit started in #1866 (which covered 46 docs in getting-started/concepts/guides). This pass covers the remaining 82 hand-written docs — guides (incl. cheatsheets/contracts/metadata/runtime-services), protocol (objectos/objectql/objectui), releases, and the docs index.
What this does
A multi-agent audit read each doc, located the real implementation in
packages/, and adversarially verified every finding against the code — a second verifier re-checked each applied fix and repaired over-corrections.Recurring classes of fix
tx.insert/tx.update), non-existent helpers (definePlugin), wrong package names (@objectstack/services/service-cache→@objectstack/service-cache),ViewFieldSchema→FormFieldSchema, wrong@objectstack/specsubpath imports.sanitize/allowed_tags/protocols/region/rows), a phantomWorkflowmetadata type with*.workflow.tsconventions, fabricated CLI scaffold output.max_length→maxLength; relationship/complex type lists corrected to real enum values; OWDModel value spellings (public_read/…).PermissionDeniedError(403) rather than silent strip; realPermissionSetover Salesforce-style shapes.OS_EMAIL__PROVIDERdouble-underscore,/v1REST prefixes, config-resolution precedence and envKey coercion examples.Verification
next buildcompiles all 1113 pages clean (exit 0).references/, zero code touched.Follow-ups (out of scope here)
Residual items the audit could not confirm against code — plus the observation that committed
content/docs/references/have drifted from spec (16 files regenerate with diffs; 3 newly-added spec types missing entirely) — are recorded indocs/audits/2026-06-handwritten-docs-accuracy-followups.mdfor a dedicated regenerate-references pass.🤖 Generated with Claude Code