feat(docs-metadata): ADR-0046 — package docs as flat Markdown metadata#1789
Merged
Conversation
Revised ADR-0046 (simplified from the directory/docSet design) plus the
full P1 framework implementation:
- spec: DocSchema { name, label?, content } (system/), StackDefinition.docs,
'doc' metadata type + registry entry (inert data, runtime-creatable for
AI drafting) + canonical schema map, docs→doc plural mapping
- cli: os build compiles flat src/docs/*.md into docs[] (frontmatter
title / first # heading → label) and enforces the ADR lint: flat
directory, namespace-prefixed snake_case names, namespace required when
docs ship, MDX/image ban, same-package relative-link resolution; same
rules wired into os lint
- objectql: docs joins the generic metadata registration loop (manifest +
nested plugins)
- runtime: docs count as app payload; GET /metadata/doc list omits
content by default (?include=content opts in) so unbounded manuals stay
off hot paths
- examples/app-todo: two cross-referencing docs as a living sample
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
This was referenced Jun 12, 2026
Merged
xuyushun441-sys
added a commit
that referenced
this pull request
Jun 12, 2026
The runtime dispatcher's /metadata/doc route already slims doc list responses (#1789), but the console reads the REST server's /meta/:type route, which still returned full bodies. Apply the same rule here: list responses carry name + label only, ?include=content opts back in, and GET /meta/doc/:name always returns the full body. Found during live verification of the console /docs/:name route — the list endpoint is the path that must stay content-free because manuals are the one metadata payload that grows unbounded. Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 task
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.
Summary
Revises ADR-0046 (package documentation as metadata) to the simplified flat design and ships the full P1 framework implementation.
ADR revision
src/docs/*.mddirectory — no docSets, nometa.json, no directory taxonomy; flatness is the contract that keeps cross-references stable/docs/<name>); names are namespace-prefixedorg/type/namehas no package coordinate → silent last-write-wins overwrite), hence build/publish-lint enforcementcontent; list endpoint servesname+labelwithoutcontentImplementation
DocSchema { name, label?, content },StackDefinition.docs,docmetadata type + registry entry (inert, runtime-creatable for AI drafting per ADR-0033) + canonical schema map,docs → docplural mappingos buildcompiles flatsrc/docs/*.md(frontmattertitle:/ first#heading → label) and enforces the ADR lint — flat directory, namespace-prefixed snake_case names, namespace required when docs ship, MDX/image ban, same-package link resolution; same rules inos lintdocsjoins the generic metadata registration loop (manifest + nested plugins)GET /metadata/doclist omitscontentby default (?include=contentopts in)Test plan
packages/spec/src/system/doc.test.ts,packages/cli/src/utils/collect-docs.test.ts(12 cases)pnpm buildon app-todo embeds both docs intodist/objectstack.jsonwith correct labels; subdirectory + broken-link cases fail the build with corrective messages🤖 Generated with Claude Code