docs(getting-started): map every authorable defineStack collection to its directory and guide

[os-elon]

Fixes#10218

getting-started/quick-start.mdx → "Reading a project's layout" showed seven
directories. Those seven turn out to be a precise set, just not the one the page
claims: they are exactly the defaultDir values in
packages/cli/src/commands/generate.ts — the os g generator defaults
(objects, views, actions, flows, agents, dashboards, apps). The
page presented the generator's seven as the layout of "any ObjectStack project"
while defineStack() declares 32 authorable collections.

What the schema actually declares

Enumerated from the runtime shape, not transcribed:

node -e "import('packages/spec/dist/index.js').then(m =>
console.log(Object.keys(m.ObjectStackSchema.shape).length))"
→ 44

44 declared keys, 32 authorable collections, 12 excluded. The page names all 12
exclusions and why.

One correction to the card's candidate exclusion list

The card asked for each classification to be verified rather than copied. Ten of
its twelve hold. surface / history / guidance are not stack keys at all —
they are the first argument to the strictObject(meta, shape) helper
(packages/spec/src/shared/strict-object.ts), which carries the surface name,
the history sentence and the retired-key guidance map used to build the
unknown-key error. They never appear in Object.keys(shape), so classifying them
as "config or code wiring" would have described them as a thing an author could
write. The remaining nine on the card's list (manifest, server, api,
plugins, tiers, devPlugins, requires, onEnable, plus viewItems and
runtimeModule) are real keys and are excluded as stated.

Three exclusions the card did not name are added, one of them load-bearing:

Key	Why excluded
functions	Callables the runtime invokes by name — code, not metadata. objectstack build lowers each to a handler ref. Same class as onEnable.
i18n	TranslationConfigSchema — a single config object. The authored content is translations, which is in the table.
manifest	Named by the card; kept excluded — package config, not a metadata collection.

viewItems verified as z.never() at stack.zod.ts:322; runtimeModule's own
.describe() reads "Set by objectstack build; do not author by hand."

The layout tree

Derived from examples/, as the card asked, and the derivation found two
conventions shipping side by side:

• examples/app-todo and examples/app-crm lay out one directory per collection
  (src/objects/, src/views/, src/flows/, src/security/, …).
• examples/app-showcase groups by domain: src/data/, src/ui/,
  src/automation/, src/security/, src/system/, src/docs/.

Both trees are now on the page. The flat one is the union of what todo and crm
actually ship plus the os g defaults — no directory in it was invented; the
grouped one is app-showcase's real subdirectory list. That the two disagree
about paths and agree exactly about keys is the point the section already made
about there being no filename-suffix magic, so the cross-link into the table is
written as that consequence rather than as a "see also".

Two observations from the derivation, recorded because they are the kind of thing
that reads as an error later:

• No example ships src/agents/, and none writes agents: or skills: in
  its objectstack.config.ts. src/agents/ stays in the tree because
  generate.ts:130 writes there and content/docs/deployment/cli.mdx:1046
  documents it. The agents row carries the ADR-0063 clause — platform-internal,
  third parties extend through skills.
• src/data/ means two different things. Seed records in todo/crm; the whole
  data domain (objects, extensions, hooks, mappings, analytics, seed) in showcase.
  Both trees show it in its own context rather than picking a winner.

The map

One table, 32 rows, defineStack() key → one clause → guide. Ordered
data → interface → automation → integration → access → AI.

Twenty-one rows reach a hand-written guide. Eleven have none and link only the
generated reference under /docs/references/…, per the card's rule:
objectExtensions, mappings, analyticsCubes, reports, themes, books,
jobs, emailTemplates, apis, capabilities, tools. Every one of those was
resolved by locating the schema symbol in the generated
corpus (e.g. CapabilityDeclarationSchema → references/security/misc.mdx,
CubeSchema → references/data/analytics.mdx), not guessed from the key name.
A line under the table says what a Reference link means, so the honest gap is
visible instead of looking like an arbitrary link choice.

No path in the diff was invented: all 39 internal /docs/… links on the page
were resolved against files present on main before commit, and
check:doc-anchors re-verifies the one intra-page fragment.

Three near-misses worth naming, since each would have shipped a plausible-looking
wrong link: content/docs/api/plugin-endpoints.mdx is about plugin-contributed
routes, not the apis: collection; permissions/permission-metadata.mdx's
reports: is a permission-set grant key, not the stack collection; and
ai/actions-as-tools.mdx teaches actions becoming tools, not the tools: record.
All three route to the generated reference instead.

Gates

node scripts/pm/dispatch-gates.mjs with no path args — the script derives the
change set itself (1 path, three-dot against merge base d7283250d). It named 11
families. All 11 green at a992871c3, the final commit:

check:cross-package-test-inputs · check:doc-anchors · check:docs-audit-scope ·
check:docs-redirects · check:published-readme-links · check:role-word ·
node scripts/check-cross-package-test-inputs.mjs · spec check:empty-state ·
spec check:liveness · spec check:strictness-ledger · spec check:variant-docs

Also green, named at dispatch but not by the re-derivation:
check:doc-authoring (380 files clean) and spec check:skill-examples
(209 prose examples type-check).

check:docs-audit-scope stayed green with no .claude/workflows/docs-accuracy-audit.js
regeneration, which is the outcome the card asked to have confirmed either way.
That is consistent with the gate's own definition — its scope is
content/docs/**/*.mdx minus references/, so it reacts to a page being added or
removed, and this diff edits one existing page and adds none. Its verdict line is
unchanged at 180 hand-written doc(s). So this PR's path surface is clean and it
is not human-merge-only.

check:role-word deserves one note: quick-start.mdx sits in
scripts/role-word-baseline.json at exactly 1, and that ratchet fails in both
directions. The additions carry zero new occurrences and the pre-existing one on
line 39 is untouched, so the count is still 1 and the baseline needs no edit.

No changeset: content/docs/ only, no published package changes — skip-changeset.

content/docs/getting-started/quick-reference.mdx is untouched, per the card. Its
(N of M schemas) counts and check:quick-reference-counts are unaffected. I
agree with the card's placement call: the map is a navigation aid for someone
reading a project, which is what quick-start.mdx is for, and it carries no
counted table.

---

Generated by Claude Code