docs(site): restructure IA into module-first single sidebar#2584
Merged
Conversation
Dissolve the six root tabs (Getting Started/Concepts/Guides/Reference/ Protocol/Releases) into one sidebar tree of 14 capability groups aligned with the Reference domains: Get Started, Core Concepts, Data Modeling, Automation, Permissions & Identity, UI Engine, API & SDK, AI, Plugins & Packages, Kernel & Services, Deployment & Operations, Protocol Spec, Reference, Releases. - move ~90 pages out of guides//concepts/ grab-bags into module groups - split 6 oversized multi-topic pages (security, data-modeling, ai-capabilities, business-logic, plugins, api-reference) along H2 boundaries; content moved verbatim and deduplicated - delete diverged duplicate pages (architecture fork, packages, concepts index); merge terminology into glossary - new landing page and five module overview pages - rewrite internal links (absolute + relative) to the new URL space - move internal-facing pages (airtable gap analysis, CRM standards) out of the site to docs/notes/ Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018r9mjpF7jr9BKdzEmUE4uZ
- apps/docs/redirects.mjs: permanent redirects for every moved URL (exact entries + folder wildcards + /docs/guides/:path* safety net), wired into next.config.mjs - build-docs.ts: references group is no longer a root sidebar tab; banner wording updated (guides/ no longer exists) - build-skill-docs.ts now emits content/docs/ai/skills-reference.mdx; check-doc-authoring.mjs SKIP_FILES follows - docs-accuracy-audit workflow page list regenerated (146 pages) - update stale content/docs paths in spec JSDoc (source of generated reference prose), skills corpus, package READMEs, ADRs, roadmaps Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018r9mjpF7jr9BKdzEmUE4uZ
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
os-zhuang
marked this pull request as ready for review
July 4, 2026 15:15
quick-reference had drifted from the generated reference tree: - delete 18 table rows whose schemas do not exist anywhere in packages/spec/src (fictional ai/hub/policy entries, plus a Workflow row duplicating State Machine) - relink 13 rows to the real generated pages (dataset lives in ui/, marketplace/tenant/plugin-security in cloud/, service-registry and plugin-registry in kernel/, connectors in integration/) - unlink 4 rows whose schema exists but has no generated page (driver/postgres, driver/mongo, shared mapping, connector-auth) - recount section headers; resolve the last relative links - drop the mcp README bullet advertising a guide that never existed Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018r9mjpF7jr9BKdzEmUE4uZ
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 7 package(s): 105 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
This was referenced Jul 4, 2026
This was referenced Jul 16, 2026
os-zhuang
added a commit
that referenced
this pull request
Jul 17, 2026
content/docs/references/** is generated from packages/spec and committed, but no CI job ever regenerated and diffed it, so the public reference docs drifted silently while main stayed green. #3076 added RowCrudActionOverride to the spec and the docs never learned the type existed. Regenerate: 7 files, every change traced to a spec change that shipped without re-running the generator — RowCrudActionOverride and ServiceSelfInfo missing outright, dashboard filterBindings/name missing, readonly (#2948/#3003) and allowTransfer (#3004) stale, and connector ADR-0096 → ADR-0097 (both ADRs exist and are distinct, so the published docs were pointing readers at the wrong one). Verified deterministic: two consecutive runs produce byte-identical output. Gate: build-docs.ts --check, following the sibling convention. Every write goes through emit() and every wiped folder through manageDir(), so check and write run identical generation logic and differ only in the final disposition — it cannot pass on output a real run would not produce. Verified output-identical to the previous generator across all 258 files, and proven to fail on stale content, a missing page, a stale leftover page, and a vacuous no-schema run. Not `git diff --exit-code`: that misses untracked files. Placement: lint.yml's "TypeScript Type Check" — no paths filter and a required status check, so the gate can neither go dormant nor be merged past. ci.yml's "Build Docs" is gated on a `docs` filter excluding packages/spec/**, so it skips exactly the spec-only PRs that cause this drift. Also un-dormants the sibling gates: check:spec-changes / check:upgrade-guide read the ADR-0087 registries but ran under a filter listing only skills/**, and that filter watched content/docs/guides/skills.mdx, a path #2584 moved. Job renamed check-skill-docs → check-generated. Co-Authored-By: Claude Opus 4.8 <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.
Docs IA restructure: module-first single sidebar
Complete restructure of the docs site information architecture, modeled on Better Auth's docs: one sidebar tree, two levels, capability modules visible at first glance — replacing the previous six
root: truetabs (Getting Started / Concepts / Guides / Reference / Protocol / Releases) where content for any one capability was scattered across up to six places.Preview: https://spec-git-claude-docs-site-structure-w9lfzp-object-stack.vercel.app/docs
New sidebar (14 groups)
data,automation,identity/security,ui,ai,api,kernel), so "module overview → module guides → schema reference" is one predictable path.references/tree (239 pages) is structurally untouched; its generator no longer emitsroot: true.What changed
Moves (~90 pages).
guides/(44 flat entries),guides/metadata/,guides/solutions/,guides/cheatsheets/and the Concepts grab-bag are dissolved into the module groups. Full mapping is encoded inapps/docs/redirects.mjs.Splits. Six oversized multi-topic pages were split along H2 boundaries (content moved verbatim, byte-diff-verified):
guides/security.mdx(777 L) →permissions/index + profiles / permission-sets / roles / sharing-rules / field-level-securityguides/data-modeling.mdx(774 L) →data-modeling/schema-design+ relationships + indexingguides/ai-capabilities.mdx(712 L) →ai/index + agents / actions-as-tools / knowledge-rag / natural-language-queriesguides/business-logic.mdx(675 L) →automation/hooks; flow/approval/validation/formula sections merged into their dedicated pages (deduped)guides/plugins.mdx(572 L) →plugins/index + merged interface/lifecycle intoplugins/anatomy(three duplicate explanations of the Plugin interface reduced to one, verified againstpackages/core/src/types.ts)guides/api-reference.mdx(540 L) →api/index + data-api / metadata-api / plugin-endpointsDedup / merges.
concepts/architecture.mdxwas a diverged verbatim fork ofgetting-started/architecture.mdx— one copy kept (nowconcepts/architecture)concepts/terminology.mdxmerged intogetting-started/glossary.mdx(terminology was the fresher fork; kept its Source/Artifact & three-layer entries plus glossary's fuller Driver entry)concepts/packages.mdx(dup ofguides/packages.mdx) deletedguides/airtable-dashboard-analysis.mdxandguides/standards.mdx(internal-facing) moved out of the site todocs/notes/New content. Docs landing page (module map) and five module overviews (
data-modeling,automation,permissions,ui,kernel), each linking group pages + matching Protocol Spec section + Reference domain.Redirects. Every old URL 301s to its new home — ~90 exact entries plus wildcards for the moved
runtime-services//contracts/folders and a/docs/guides/:path*safety net (apps/docs/redirects.mjs, wired intonext.config.mjs).Link rewrites. ~105 absolute
/docs/...links rewritten across content/blog per the same mapping; ~190 relative links resolved against their pre-move locations and rewritten as absolute URLs; stalecontent/docs/...file paths updated across skills corpus, package READMEs, ADRs, andpackages/spec/srcJSDoc (source of generated reference text).Broken-link purge.
getting-started/quick-reference.mdxhad drifted badly from the generated reference tree: 18 table rows documented schemas that do not exist anywhere inpackages/spec/src(deleted), 13 rows pointed at the wrong domain (relinked to the real pages — dataset lives inui/, marketplace/tenant incloud/, etc.), 4 rows reference real schemas with no generated page (unlinked, text kept). The mcp README bullet advertising a guide that never existed was dropped.Tooling repointed.
packages/spec/scripts/build-skill-docs.ts→ emitscontent/docs/ai/skills-reference.mdxpackages/spec/scripts/build-docs.ts→ references group no longer a root tab; banner wording updatedscripts/check-doc-authoring.mjsSKIP_FILES,.claude/workflows/docs-accuracy-audit.jspage list regenerated (146 hand-written pages)/content/docs/guides/<topic>/links pointed at directories that never existed)Verification
node scripts/check-doc-authoring.mjs— 180 files cleanpnpm --filter @objectstack/spec gen:schema && gen:docs && gen:skill-docs— regenerate cleanly into the new treenext buildpasses (385 paths); served the built site and spot-checked: 9 representative old URLs 308-redirect to their new homes, all 14 module/group indexes and split pages return 200, landing page renders all sidebar groupscontent/docs/guides|concepts/corereferences remain outside CHANGELOGs🤖 Generated with Claude Code
https://claude.ai/code/session_018r9mjpF7jr9BKdzEmUE4uZ