docs: finish implementation-accuracy audit (remaining 82 hand-written docs + generated references)

[xuyushun441-sys]

Continuation of the docs implementation-accuracy effort. Two PRs already landed:

• docs(nav): group Protocol Reference modules and clarify top-level nav #1862 — nav reorg (Protocol Reference grouping, Protocol → Protocol Overview, removed empty contracts/)
• docs: sync 46 hand-written docs with actual implementation (reader-facing audit) #1866 — synced 46 hand-written docs (getting-started, concepts, 20 core guides) with actual code; 299 verified fixes

This issue tracks the remaining work, in two waves.

⚠️ Important: #1862's per-module grouping is NOT durable

packages/spec/scripts/build-docs.ts regenerates content/docs/references/** on every gen:docs (which runs in the docs production build: gen:schema && gen:docs && next build). It rmSyncs each category folder and rewrites references/{category}/meta.json as a flat alphabetical list (build-docs.ts:326, 379), plus regenerates every references/{category}/index.mdx (line 420) and references/meta.json (line 448).

So the section grouping added to references/{system,api,…}/meta.json in #1862 gets overwritten the next time anyone runs gen:docs, and likely isn't even reflected on the deployed (Vercel-built) site. The grouping must be moved into the generator to be durable. (The Protocol Overview rename and root content/docs/meta.json are safe — they are outside references/.)

Wave 1 — remaining hand-written docs (82 files)

Audit each against the real implementation in packages/, adversarially verify, apply fixes (surgical, preserve frontmatter, no file moves). Same process as #1866. Exclude references/*/index.mdx (generated).

The 82 files

• content/docs/index.mdx
• guides/ (top-level): airtable-dashboard-analysis, analytics-datasets, cloud-deployment, data-flow, driver-configuration, environment-variables, error-handling-client, error-handling-server, index, kernel-services, objectql-migration, plugin-chatbot-integration, production-readiness, publish-and-preview, single-project-mode, standards, troubleshooting
• guides/cheatsheets/: backward-compatibility, error-catalog, field-type-decision-tree, field-type-gallery, field-validation-rules, permissions-matrix, protocol-diagram, query-cheat-sheet, quick-reference, wire-format
• guides/contracts/: index, auth-service, cache-service, data-engine, metadata-service, storage-service
• guides/metadata/: index, app, dashboard, doc, field, flow, object, page, permission, validation, view, workflow
• guides/runtime-services/: index, audit-service, data-service, email-service, examples, queue-service, settings-service, sharing-service, storage-service, versioning
• protocol/: index, knowledge
• protocol/objectos/: index, config-resolution, error-handling, http-protocol, i18n-standard, lifecycle, metadata-service, plugin-spec, realtime-protocol, runtime-capabilities
• protocol/objectql/: index, query-syntax, schema, security, state-machine, types
• protocol/objectui/: index, actions, concept, layout-dsl, record-alert, widget-contract
• releases/: index, v9

Wave 2 — generated references (223 pages) + generator

These live under content/docs/references/** and are generated, so fixes go to the source, not the .mdx:

1. Make grouping durable — port docs(nav): group Protocol Reference modules and clarify top-level nav #1862's per-category section grouping into build-docs.ts (emit ---Section--- separators in each category meta.json instead of a flat sorted list). Define the grouping map there.
2. Improve generated content quality — fill in / improve zod .describe() strings across packages/spec/src/**/*.zod.ts so the generated reference prose is accurate and useful; improve the generator's output formatting where needed.
3. Re-run gen:docs, verify next build, browser spot-check.

Smaller follow-ups already flagged

• os init scaffold still emits a stale ownership literal on the starter object (not a valid ObjectSchema key). (noticed during docs: sync 46 hand-written docs with actual implementation (reader-facing audit) #1866 quick-start audit)
• ai-capabilities.mdx frontmatter still mentions "RAG pipelines" (body was corrected in docs: sync 46 hand-written docs with actual implementation (reader-facing audit) #1866; frontmatter left per preserve-frontmatter rule).

Method (reusable)

The #1866 pipeline worked well: a multi-agent audit workflow (one agent per doc → locate impl in packages/ → adversarially verify each finding), then an apply workflow (one agent per doc → surgical edits in a dedicated worktree), then next build + browser verify + PR. Note: editing must happen in a dedicated git worktree (the repo's guard-main-checkout hook blocks edits on the shared main checkout).