docs(getting-started): the project-layout map shows 7 directories for a stack that declares ~30 collections

[os-elon]

Part of #10206

The gap

getting-started/quick-start.mdx → "Reading a project's layout" is the page that teaches a developer to navigate any ObjectStack project. It shows seven directories:

src/objects/ src/actions/ src/views/ src/apps/ src/flows/ src/dashboards/ src/agents/

defineStack() declares roughly thirty authorable collections. Author a report, a job, a theme, an email template, an import mapping, a permission set, a position, a doc, a book, a seed, a translation, a declarative endpoint, a capability, a connector, a webhook, a sharing rule, a dataset or a skill, and this page tells you nothing about where it goes or which key carries it.

The page is correct as far as it goes and says something important — "There is no filename-suffix magic — metadata is wired in through those explicit imports" — which is exactly why the collection names matter more here than file patterns do.

File surface

• content/docs/getting-started/quick-start.mdx — edit only

⛔ Nothing else. In particular do not touch getting-started/quick-reference.mdx — its tables carry (N of M schemas) counts checked by pnpm check:quick-reference-counts, and it is a curated fast-lookup surface with its own discipline. If you believe the map belongs there instead, say so in the report and put it here anyway.

What to write

1. Extend the layout tree to the directories a real app uses. Derive the convention from the shipped examples (examples/app-showcase, and the other apps under examples/) rather than inventing one — the point of the page is that it matches what an agent actually generates.

2. Add an authorable-collection map: one table, defineStack() key → what it declares → where the guide is. Derive the key list from StackSchema in packages/spec/src/stack.zod.ts at the time you write it, not from this issue and not from memory.

   Rules for the table:

   • Cover every key a customer authors. Exclude the machine-only and config-only ones and say in one line that you did: viewItems is z.never() (a machine-assembled channel that refuses authored input), and runtimeModule is set by objectstack build; surface / history / guidance / manifest / server / api / plugins / tiers / devPlugins / requires / onEnable are config or code wiring, not metadata items. Verify each of these classifications against the schema before you commit to it — do not copy this list on faith.
   • Link each row to its guide. Several rows have no guide yet — they are being written under [epic] Docs coverage for the authorable metadata surface — every type a customer authors needs a findable page #10206 right now. For those, link the generated reference under /docs/references/... and nothing else. ⛔ Do not invent or pre-link a page path that does not exist on main at the time your PR opens; check:doc-anchors will catch some of these and a stale link is worse than an honest reference link.

3. Cross-link the map from the layout section so a reader who is looking for "where does X go" reaches it.

⛔ Non-goals

• Do not touch packages/spec/** or any file outside getting-started/.
• Do not restate what each collection does beyond one clause — this is a routing table, not a second set of guides.

Gates (derived at dispatch time via node scripts/pm/dispatch-gates.mjs, not recalled)

check:doc-anchors, check:docs-audit-scope, check:docs-redirects, check:published-readme-links, check:role-word, check:cross-package-test-inputs, and the spec liveness set (check:empty-state, check:liveness, check:strictness-ledger, check:variant-docs). Re-derive against your actual diff.

Acceptance

• A developer holding a piece of metadata can answer "which directory, which defineStack() key, which guide" from this one page.
• Every link in the map resolves against main.
• The exclusions are stated, not silent.
• Named gates green.

[os-elon]

Claim: PM loop round 3 (epic #10206)
Session: session_01GawRwpD44VwBDVy3hs77AX
Branch: claude/issue-10218-project-layout-map
Worktree: objectstack-issue-10218
Domain: domain:devx
File surface: content/docs/getting-started/quick-start.mdx only (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — no path-derived mandate; tier is this seat's call.
Clause-②: no — documentation only.
Serial constraints cleared: content/docs/getting-started/** — no in-flight claim, no open PR. Batch-3 sibling #10222 owns content/docs/ai/**; disjoint. ⚠️ This card edits an EXISTING page and adds none, so check:docs-audit-scope should stay green and no .claude/ regeneration is expected — if it fires anyway, that is a signal worth reporting, not a routine step. On that basis this PR is expected to be the second one in this epic (after #10209) that is not human-merge-only.

---

Generated by Claude Code