docs: sync 46 hand-written docs with actual implementation (reader-facing audit)#1866
Merged
Conversation
…cing audit)
A multi-agent audit read each hand-written doc, located the real
implementation in packages/, and adversarially verified every finding
against the code. This applies 299 verified fixes across 46 docs in
getting-started, concepts, and guides. Auto-generated references/ docs
(DO-NOT-EDIT, produced from packages/spec) were intentionally excluded.
Recurring classes of fix:
- broken-example / inaccurate: code samples calling APIs that don't exist
or changed — e.g. `os studio` (no such command → `os dev --ui`),
`client.meta.getObject()` → `meta.getItem('object', …)`,
`client.ai.chat()` removed, `client.workflow.approve/reject` moved to
the request-id `client.approvals.*` API (ADR-0019), `defineProfile` /
`defineAction` / `defineHook` helpers that don't exist.
- security model: replaced Salesforce-styled fabricated API (Profile type,
objectPermissions/fieldPermissions) with the real PermissionSet schema
(objects/fields, allowCreate/allowRead/…, isProfile); fixed sharing
rules, OWD enums, role hierarchy.
- outdated: Salesforce UPPERCASE formulas → CEL; portal path /_studio →
/_console; REST path /api/v1/{object} → /api/v1/data/{object};
AUTH_SECRET → canonical OS_AUTH_SECRET; PORT → OS_PORT.
- fabricated features removed/qualified: RAG/NLQ/Predictive sections in
ai-capabilities; VITE_RUNTIME_MODE & ?mode= switch in deployment-vercel
(real flag is VITE_USE_MOCK_SERVER); GraphQL presented as contract-only.
- broken links/paths repointed (objectstack-ai/spec → …/framework).
Navigation-safe: no files moved, frontmatter preserved on every doc.
Verified: `next build` compiles all 1107 pages clean; spot-checked
rendering in the browser.
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
size/xl
documentation
The formula skill description used "Use whenever", which build-skill-docs.ts's `Use when` split regex doesn't match, so the generated catalog duplicated the "Do not use" clause. Fix the source phrasing to "Use when" and regenerate, so content/docs/guides/skills.mdx stays in sync (check:skill-docs passes) instead of hand-patching the generated block. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
xuyushun441-sys
added a commit
that referenced
this pull request
Jun 15, 2026
…te (#1869) * fix(cli): drop stale `ownership` key from init scaffold object template The `os init` scaffold emitted `ownership: 'own'` on the starter object in both the `app` and `plugin` templates. `ownership` is no longer a valid ObjectSchema field — it's removed from ObjectSchemaBase, and `ObjectSchema.create()` now rejects unknown top-level keys (ADR-0032 / #1535). A user copying the scaffolded object into `ObjectSchema.create({...})` would hit a validation error; the plain-literal form merely hid the problem while teaching a dead field. Remove the key from both templates. Rest of the scaffold output is unchanged; init.test.ts (28 tests) passes and end-to-end render of both templates confirms no `ownership` remains. Surfaced during the docs audit in #1866 (getting-started/quick-start.mdx). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> * chore: add changeset for init scaffold ownership fix Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
os-zhuang
added a commit
that referenced
this pull request
Jun 15, 2026
…(audit pass 2) (#1904) 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>
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 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
2 participants
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.
Why
A reader following the docs hits APIs and commands that don't exist or have changed. This PR is the result of a multi-agent audit: each hand-written doc was read from a developer-reader's perspective, cross-checked against the real implementation in
packages/, and every finding was adversarially verified against the code before being applied.Scope
getting-started/,concepts/,guides/.references/pages (markedDO-NOT-EDIT, generated frompackages/specviabuild-docs.ts) — fixing those means changing the generator / zod.describe()strings, a separate effort.Recurring classes of fix
os studio→os dev --ui;client.meta.getObject()→meta.getItem('object', …);client.ai.chat()removed;client.workflow.approve/reject→ request-idclient.approvals.*(ADR-0019); non-existentdefineProfile/defineAction/defineHookhelpers.Profiletype,objectPermissions/fieldPermissions) with the realPermissionSetschema (objects/fields,allowCreate/allowRead/…,isProfile); corrected sharing rules, OWD enums, role hierarchy./_studio→/_console; REST/api/v1/{object}→/api/v1/data/{object};AUTH_SECRET→ canonicalOS_AUTH_SECRET;PORT→OS_PORT.ai-capabilities;VITE_RUNTIME_MODE&?mode=switch indeployment-vercel(real flag isVITE_USE_MOCK_SERVER); GraphQL framed as contract-only (IGraphQLService), not a shipped generator.objectstack-ai/spec→…/framework; dead anchors/files).Safety & verification
next buildcompiles all 1107 pages clean (exit 0).Follow-ups (out of scope, code-side)
skills/objectstack-formula/SKILL.mdfrontmatterUse whenever→Use whensogen:skill-docsstops duplicating the "Do not use" clause.ai-capabilities.mdxfrontmatter still mentions "RAG pipelines" (left as-is per preserve-frontmatter rule).os initscaffold still emits anownershipliteral in the generated object.🤖 Generated with Claude Code