docs: finish implementation-accuracy audit — durable reference grouping + hand-written doc sync (#1880)#3243
Merged
Conversation
gen:docs rewrote each references/{cat}/meta.json as a flat alphabetical
list on every run, silently discarding the per-category grouping that was
added by hand in #1862. Move the grouping into build-docs.ts so it
survives regeneration: a SECTION_GROUPS map drives fumadocs "---Section---"
separators for the 9 large categories (ai, api, automation, cloud, data,
integration, kernel, system, ui); smaller categories keep the flat list.
The mapping degrades gracefully — pages present on disk but unmapped still
appear (under a trailing "More" separator) and names that produce no page
are ignored — so adding or removing a schema never drops it from the
sidebar. `gen:docs --check` stays green.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012urEihGTAsQP2xizAqfCwt
…iew config (#1880) Fill empty zod .describe() strings on the most author-facing view schema so the generated ui/view reference prose is useful: - CalendarConfig / GanttConfig field references (startDateField, endDateField, titleField, colorField, progressField, dependenciesField) - the type-specific view config objects (kanban / calendar / gantt / tree) Regenerated content/docs/references/ui/view.mdx from the updated schema. Part of the Wave 2.2 describe-string effort; the broader backlog (~1,180 empty descriptions, concentrated in internal protocol schemas such as data-engine) remains as tracked continuation of #1880. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012urEihGTAsQP2xizAqfCwt
…Wave 1, batch 1) First batch of evidence-backed accuracy fixes from the multi-agent doc audit (one agent per doc → locate implementation in packages/ → adversarial verify). The api section (11 docs) is fully audited and adversarially verified — 12 fixes, 0 verifier repairs; the ai/automation docs here are audit-verified. Representative fixes: removed the retired `feed` client namespace, corrected the connect discovery response shape (features → capabilities), and fixed the aiService.chatWithTools() call signature. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012urEihGTAsQP2xizAqfCwt
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
…batch 2) More evidence-backed accuracy fixes from the audit workflow. The adversarial verify phase was cut short by a session usage limit, so each fix here was additionally hand-checked against the spec before committing: - data-modeling/field-type-decision-tree: `password` is masked-on-read, not hashed — prefer `secret` for real credentials (#2036). - data-modeling/analytics: the `certified` measure flag is an ADR-0021 design goal, not yet implemented (DatasetMeasureSchema has no such field) — removed the example usage and corrected the guidance. - concepts/metadata-driven: config-key example `referenceFilters` → `lookupFilters` (referenceFilters removed in 16.x, #2377 / ADR-0049). - concepts/metadata-lifecycle: per-org overlay table listed removed `role`/`profile` types → `permission`/`position`. - concepts/index: dropped the auto-GraphQL claim (REST is auto-generated). - automation/webhooks: sys_webhook filter field `events[]` → `triggers`. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012urEihGTAsQP2xizAqfCwt
…lementation (#1880 Wave 1, batch 3) 30 docs audited AND adversarially verified this window; 20 carry evidence-backed fixes. Highlights: - field-types: `password` is masked-on-read (ADR-0100), not hashed — real credential hashing is owned by better-auth (sys_account.password); removed fabricated `fileAttachmentConfig` and `vectorConfig` (both removed in the 16.x line, #2377). - objects: removed non-existent `tags` / `recordName` props and the `softDelete` / `versioning` config blocks (removed in 16.0, #2377 / ADR-0049, now tombstoned); corrected `feeds` / `activities` capability defaults (both default `true`). - validation-rules, getting-started/cli, deployment/*, and others: assorted API name, flag, path and example corrections. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012urEihGTAsQP2xizAqfCwt
…ave 1, batch 4) 30 docs audited AND adversarially verified; 18 carry evidence-backed fixes (getting-started remainder + kernel contracts / runtime-services). Highlights: - kernel/contracts/data-engine: `@objectstack/spec` → `@objectstack/spec/data` subpath import; trimmed the error-code table to codes the engine actually emits (with HTTP mappings); removed the unsupported `top` → `limit` OData alias. - kernel/events, cluster, contracts/*, runtime-services/*: assorted API name, type, and import-path corrections. - getting-started: AI-primitives scope note (NLQ / RAG-orchestration / predictive pipelines were removed in v1); quick-reference and your-first-project example fixes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012urEihGTAsQP2xizAqfCwt
…1880 Wave 1, batch 5) Commits the 23 permissions/plugins/protocol docs whose audit completed cleanly this window. Highlights: - plugins/*: removed the fabricated `definePlugin()` helper from examples — a plugin is a plain default-export object; no such helper exists. - permissions/explain: corrected the explain `via` value to "direct grant" (adversarial-verify repair); permission-metadata, administrator-guide, authentication, field-level-security, sharing-rules: scope/flag/API fixes. - protocol/diagram, protocol/kernel/config-resolution: path/reference fixes. Some docs' verify pass was cut short by a weekly usage limit, so a subset is audit-only (hand-scanned: no define*/scale/count regressions; MDX build-safe). Two docs whose audit itself was interrupted (protocol/kernel/error-handling and http-protocol) are reverted and deferred for a clean re-audit after the limit resets. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012urEihGTAsQP2xizAqfCwt
…ave 1, batch 6) 30 docs audited AND adversarially verified (protocol, releases, ui); 28 carry fixes — 103 fixes total, 8 of them verifier repairs (the adversarial pass caught and corrected wrong audit edits, e.g. a bad `permissionSet:` stack key → `permissions:`, and a fabricated projection "id/audit columns" claim). Highlights: - protocol/kernel/*: removed the fabricated `definePlugin()` / `defineObject()` helpers (use ObjectSchema.create) and corrected `defineView` imports to `@objectstack/spec/ui`; aspirational manifest/lifecycle blocks left in place where the page already discloses them as design-intent. - protocol/knowledge: driver-turso / knowledge-turso are cloud-only (not open-core) → replaced with open-core-appropriate driver-mongodb / llamaindex. - releases/v13,v15 + objectql/* + ui/*: import-path, key-name, and example fixes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012urEihGTAsQP2xizAqfCwt
…-protocol (#1880 Wave 1, batch 7 — final) Final batch — completes the 164-doc hand-written implementation-accuracy audit. 13 docs audited AND adversarially verified. Includes a clean re-audit of the two protocol docs whose first pass was interrupted by a usage limit (their partial diffs were reverted earlier): - protocol/kernel/error-handling: replaced fabricated SCREAMING_SNAKE error codes with the real lowercase StandardErrorCode values (unauthenticated, permission_denied, resource_not_found, delete_restricted, rate_limit_exceeded, service_unavailable, …) and removed the fabricated "WebSocket-Specific Errors" / "Business Logic Errors" sections — the error contract is HTTP/REST, not multi-channel. - protocol/kernel/http-protocol: corrected discovery routes, response-shape names, and fetch examples to the real /api/v1 surface. - ui/{forms,views,dashboards,pages,setup-app,...}: example, flag and field-name corrections. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012urEihGTAsQP2xizAqfCwt
Bring the docs-audit branch up to date with main (29 commits) before merge. Conflict resolutions: - content/docs/automation/flows.mdx: took main's newer run-history paragraph (sys_automation_run durable history / bounded step log) which superseded this branch's audit wording of the same section. - content/docs/references/automation/meta.json: regenerated; added main's new `time-relative-trigger` schema to the automation "Flow & Execution" sidebar grouping in build-docs.ts. `gen:docs --check` green (254 files in sync). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012urEihGTAsQP2xizAqfCwt
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 103 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
os-zhuang
marked this pull request as ready for review
July 19, 2026 12:46
The audit reduced discouraged "role" wording in 10 docs; commit the improved baseline so `check:role-word` locks in the improvement (per the check's own ratchet-down instruction). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012urEihGTAsQP2xizAqfCwt
This was referenced Jul 19, 2026
Closed
This was referenced Jul 19, 2026
docs: fix cache-service frontmatter, knowledge dead links, TCK glossary term (#1880 follow-up)
#3279
Merged
Merged
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.
Continues the docs implementation-accuracy effort (#1880; follows #1866 / #1904). Wave 1 audit complete — 164/164 hand-written docs.
Summary
packages/→ surgical fix → adversarial verify), all in a dedicated worktree.permissionSet:stack key → the realpermissions:; a fabricated projection claim removed).build-docs.ts(fumadocs---Section---separators, drift-safe).gen:docs --checkgreen.ui/viewdescribe strings. The ~1,180-property describe backlog (mostly self-documentingz.literaldiscriminants) is tracked continuation.Representative fixes: removed the retired
feedclient namespace;passwordfields are masked-on-read, not hashed; thecertifiedmeasure flag is ADR-0021-not-yet-implemented; removedsoftDelete/versioning/fileAttachmentConfig/vectorConfig(all removed in 16.x, #2377);referenceFilters→lookupFilters; fabricateddefinePlugin()/defineObject()→ObjectSchema.create;error-handlingfabricated SCREAMING_SNAKE codes + WebSocket/Business-Logic sections → realStandardErrorCodevalues.Method / quality notes
percent0-1↔0-100 change I couldn't confirm in this repo — the scale lives in theobjectuirenderer).gen:schema && gen:docs && next build) green on every push.Flagged follow-ups from the issue — both resolved
os initscaffold no longer emits a staleownershipliteral (usessharingModel;ownershipis now a first-class field, Bug:ownership是一个未声明却被引擎依赖的对象属性 —— 四处对同名 key 的语义不一致(引擎读 / 校验拒 / 脚手架发 / CLI 误显) #3175).ai-capabilities.mdxwas removed in the docs reorg — moot.CODE / frontmatter follow-ups surfaced by the audit (out of scope for this docs-only PR)
Real implementation gaps the audit found but couldn't fix here:
os explain objectdocumentsownershipas "own" | "extend" — real values are user | org | none #3244 —os explain objectdocumentsownershipas"own" | "extend"(real:user | org | none). (filed)kernel/contracts/cache-service.mdxfrontmatter claims "namespaces, and bulk operations" the contract doesn't have (preserve-frontmatter rule blocked the body-only fix).OS_DATABASE_DRIVER=memoryhas no branch inserve.tsdispatch (falls through to SQLite in-memory).@objectstack/driver-sqldeclares peerDepsqlite3but loadsbetter-sqlite3at runtime.jsdialect is registered only as a stub (hasDialect('js')is false).protocol/knowledge.mdxhas brokenai-capabilities.mdxcross-references (target removed in the reorg).Wave 2.2 describe-string backlog (continuation of #1880)
~1,180 generated-reference properties still lack descriptions — most are self-documenting
z.literaldiscriminants; the genuine gaps concentrate in internal protocol schemas (e.g.data-engine). Left for a follow-up.Left as a draft for maintainer review — not auto-merging.
🤖 Generated with Claude Code
https://claude.ai/code/session_012urEihGTAsQP2xizAqfCwt