[epic] Docs coverage for the authorable metadata surface — every type a customer authors needs a findable page

[os-elon]

Epic PM session: session_01GawRwpD44VwBDVy3hs77AX
Declared file territory: content/docs/** (no packages/**, no apps/docs/**, no content/blog/**)

Maintainer authorization (verbatim, 2026-08-20): 「我记得系统可以用 react 格式写 page，但是没有看到任何文档，综合评估一下客户开发元数据app需要的所有的元数据类型，还有哪些缺少文档。」 / 「你应该作为一个开发者的立场来审核 docs 官网，当我有开发需求时能否找到对应的页面」 / 「使用项目经理技能，创建相关的文档issue主任务 epic ，并集中处理派发所有相关的子任务。」

What was measured

The audit asked one question per authorable metadata type: a developer with that need opens the docs site — can they reach a page that teaches it? Authority for "what a customer authors" is two lists, not intuition:

• MetadataTypeSchema in packages/spec/src/kernel/metadata-plugin.zod.ts — 27 kinds;
• the defineStack() collections in packages/spec/src/stack.zod.ts — what an app actually declares (viewItems excluded: it is z.never(), a machine-assembled channel).

Generated reference pages (content/docs/references/**, 199 pages / 1589 schemas, built by packages/spec/scripts/build-docs.ts) cover the surface well. The gap is hand-written guides and navigation.

Finding 1 — the entire Reference tree is absent from the sidebar

Root content/docs/meta.json lists 16 entries and does not list references, and no meta.json in the tree uses the "..." rest entry. Verified against the real page-tree builder in fumadocs-core@16.14.4 (dist/loader-*.js, src/source/page-tree/builder.ts): under if (metadata.pages) only listed items are pushed into node.children; unlisted ones are added only when a ... entry is present. The else branch (no pages key at all) is what adds everything.

Every other section lists its own pages in full — references is the single exception in the repo:

references: UNLISTED -> index
--- root ---
unlisted dirs: ['references']
unlisted files: []

So 199 reference pages are reachable only through inline links from content/docs/index.mdx and getting-started/quick-reference.mdx, and a reader who lands on one gets no sidebar context to browse from. → sub-issue: nav

Finding 2 — kind:'react' page authoring is undocumented on this site

The react tier is real and gated: packages/spec/src/ui/react-blocks.ts (ADR-0081), @object-ui/react-runtime, and os validate step 3d (validateReactPageProps), dogfooded in docs/audits/2026-06-react-tier-authoring-dogfood.md. On the docs site a developer can find only:

where	what
references/ui/page.mdx L87/L89	two generated schema rows for kind / source
ui/pages.mdx L147	one bullet, stated negatively (record:* blocks are rejected on a react page)
deployment/validating-metadata.mdx §10b et al.	the validation rules, i.e. how it fails

and the Page Properties table in ui/pages.mdx does not list kind or source at all, so the guide reads as if regions + components were the only way to author a page. kind:'html' is equally invisible.

The real material exists in two places a customer does not read: objectui/content/docs/guide/react-pages.md (a different site; @object-ui/react-runtime's README links it as a relative path that does not resolve from this repo) and skills/objectstack-ui/references/react-blocks.md (generated, AI-facing). → sub-issue: react pages

Finding 3 — eleven authorable surfaces have a generated reference and no how-to

type / collection	generated reference	guide gap
report	references/ui/report.mdx (148 lines)	no ui/reports.mdx; the only prose is the "Binding a report" section of data-modeling/analytics.mdx
job	references/system/job.mdx (182 lines)	automation/index.mdx has one bullet, no card, no page
email_template	references/system/email-template.mdx (95 lines)	kernel/runtime-services/email-service.mdx covers sending; nothing covers authoring a template
theme	references/ui/theme.mdx (137 lines)	one sentence in ui/index.mdx
mapping	references/shared/mapping.mdx (83 lines)	nothing on authoring an import mapping or using mappingName on POST /data/:object/import
book	references/system/book.mdx (172 lines)	ui/doc-pages.mdx mentions "book" zero times; ADR-0046 §6 is invisible
capability	references/security/misc.mdx#CapabilityDeclaration	permissions docs cover consuming capabilities; nothing covers declaring capabilities: in a package
api (ADR-0121)	references/api/endpoint.mdx (69 lines)	only protocol/kernel/http-protocol.mdx (implementer-facing). api/plugin-endpoints.mdx is a catalog of built-in plugin routes — a different thing with a confusingly close name
objectExtensions	—	the one example lives in protocol/objectql/schema.mdx L683, not in data-modeling where the need arises
tool	references/ai/tool.mdx	ai/actions-as-tools.mdx covers actions materialising as tools, not authoring a tool record
analyticsCubes	—	data-modeling/analytics.mdx names "Cube" once as a runtime; the collection itself is undocumented — measure before documenting, filed separately as a finding

Finding 4 — the project-layout map covers 7 of ~30 collections

getting-started/quick-start.mdx "Reading a project's layout" shows objects/ actions/ views/ apps/ flows/ dashboards/ agents/. A developer who authors a report, a job, a theme or an email template has no page telling them where it goes or which defineStack() key carries it. → sub-issue: layout map

Sub-issues

Dispatched by section so that each card owns exactly one meta.json — see each card for its file surface.

• nav: restore the Reference tree to the sidebar
• ui: page authoring modes + React pages guide
• automation: scheduled jobs + email templates
• data-modeling: import mappings + object extensions
• api: declarative HTTP endpoints (ADR-0121)
• permissions: declaring package capabilities
• ai: authoring tool metadata
• getting-started: project layout + authorable-collection map
• ui: reports, theming, and the book navigation spine

Out of scope

• content/docs/references/** page bodies — generated from packages/spec; a wrong row there is a domain:spec card, not a docs card.
• content/docs/releases/** — release notes are written centrally at release time (CLAUDE.md).
• The releases nav-group placement question (docs(nav): releases sits in the Platform group but every release page declares itself written for app developers #8966) — that hold stands, see the decline recorded on that card.
• Any change to packages/spec schemas. If a guide cannot be written because the schema is wrong or dead, the dev reports it and the card is transferred to the domain:spec seat.