An open source design system that's fully customizable and agent ready
TypeScript
[Spec] AST-046: rules for splitting a docs topic into a namespace (#7210)
Joeycf59be87e25c
diff --git a/docs/specs/AST-046-docs-tree/spec.md b/docs/specs/AST-046-docs-tree/spec.mdindex 5fb0fb913f..3b82b5cf0a 100644--- a/docs/specs/AST-046-docs-tree/spec.md+++ b/docs/specs/AST-046-docs-tree/spec.md@@ -1,13 +1,13 @@---schema_version: 4-template_version: 1+template_version: 2kind: system-specid: spec:AST-046-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: josephfarina+approved_at: 2026-10-08phase: implementingowners: [josephfarina]affects_architecture: [architecture:cli-surface]@@ -18,6 +18,8 @@ affects_consumer_docs: [cli/integrations, authoring]# Documentation tree system spec+<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->+## IntentA reader who opens the Astryx docs should find every doc in one tree and move@@ -40,18 +42,28 @@ This record owns how a doc gets its one home in the tree, how a route is formed,how `astryx docs` reads the tree, and what `astryx doctor` checks. It rolls outin phases: phase 1 places the CLI's own docs and the namespace docs and guideseach integration ships, and gives every other doc a home in a generated-Unorganized level; later phases move those docs into real sections and move-the docsite onto the tree.+Unorganized level; later phases move those docs into real sections.++A long flat topic can become a namespace of short guides, so a reader loads only+the guide that answers. The split keeps the unambiguous reads a released+command makes inside the topic's own package: the name, each section read by+its key or by a title only one guide matches, each reference, and each address+on the docsite still lead to the same content (FR13, FR6, FR14). A title+fragment that matches sections in two guides asks instead of guessing (FR6),+and references from other packages are an open question (OQ2).## Non-goals-- The docsite's page layout. In phase 1 the docsite keeps its flat pages; a- guide the tree places keeps a flat page named after its route. The docsite- moves onto the tree in a later phase, as its own change.+- How a docsite page looks, and how the docsite shows flat topics. FR14 states+ which page holds a namespace's content and where each of its addresses leads;+ the page design is the docsite's.- A top-level browse of every provider. It is a later phase.- Aliases and audiences. `aliases` and `audience` stay reserved fields that adoc may not set.- Rendering `collection` blocks. A topic that uses one fails to load.+- Equivalent internal implementations remain valid when they satisfy this+ contract. The compiler's modules, the docsite's build scripts, and the files+ a split creates are implementation.## Requirements@@ -98,8 +110,23 @@ the docsite onto the tree.its route (`spec:AST-047` FR3). `--json` MUST return `docs.node` for anamespace or typed doc: its identity, route, kind, package, title, summary,breadcrumb, and either its slots with their children or its content.-- **FR6 — A route has no sections.** A section argument on a namespace or typed- doc MUST fail with `ERR_UNKNOWN_SECTION` and name its children. An unknown+- **FR6 — A section read names one section.** A section argument on a typed+ doc MUST fail with `ERR_UNKNOWN_SECTION` and name the doc. On a namespace,+ the read `astryx docs <namespace> <section>` MUST take, from each guide below+ the namespace at any depth, the section that guide's own section read+ returns for the query; within one guide, that read decides between the+ guide's sections, as it does on any topic. Across guides the read MUST then+ decide in two steps: when the section returned by exactly one guide has the+ query as its key (its `id`, or the key its title derives), that section+ answers, even when other guides return a section too; otherwise, when+ exactly one guide returns a section, that section answers. The response MUST+ be the one a section read of that guide returns (`docs.detail.section`), so+ an unambiguous section read that worked on a topic before it became a+ namespace (FR13) returns the same section in the same shape. When no guide+ returns a section, or more than one does at the step that decides, the read+ MUST fail with `ERR_UNKNOWN_SECTION`, the error a topic's unknown section+ gives; its suggestions MUST name the route of each guide that returned a+ section, or of every guide below the namespace when none did. An unknownroute MUST fail with `ERR_UNKNOWN_TOPIC` and suggest the children of thedeepest namespace the route reaches.- **FR7 — The topic list names the tree.** `astryx docs --json` MUST list each@@ -111,15 +138,15 @@ the docsite onto the tree.- **FR8 — Doctor proves the tree.** `astryx doctor` MUST warn when the tree hasan error diagnostic, when a CLI typed doc whose group the tree reads has noroute, and when a link between docs names no doc (`spec:AST-047` FR9). These- checks are new, so they warn: a project that passed before keeps passing. The progressive-disclosure check MUST hold each guide the tree+ checks warn, so a project that passed without them keeps passing. The progressive-disclosure check MUST hold each guide the treeplaces to the same size budget as every topic.- **FR9 — Phase 1 places the CLI's own docs.** The CLI MUST ship the `cli`namespace with the `integrations` namespace and the `commands` and `api`namespaces under it. Every command doc MUST have a route under`cli/commands`, and every function, schema, and enum doc in the `cli/api`group a route under `cli/api/<kind>s`. The integration guides MUST live under- `cli/integrations`, one short guide per task; the old flat name- `cli-integrations` is gone. Under `spec:AST-017/FR45`, a CLI route or name MAY+ `cli/integrations`, one short guide per task, and no flat topic is named+ `cli-integrations`. Under `spec:AST-017/FR45`, a CLI route or name MAYchange like this when every reference changes with it: links name docs byidentity (`spec:AST-047` FR9), and the graph walk fails on a referenceleft behind (`spec:AST-047` FR11, FR12).@@ -151,9 +178,8 @@ the docsite onto the tree.`astryx integration add doc <name> --parent <namespace>` MUST write a guideplaced in that namespace, found by its name, and the namespace doc when thepackage has none. A CLI release that does not read the docs tree can hide every doc topic of a- package that ships a namespace doc or a placed guide, with nothing saying why- (published 0.6.3 does so for a namespace doc, and earlier builds of main for a- placed guide too), so such a package MUST declare a `@astryxdesign/cli` peer+ package that ships a namespace doc or a placed guide, with nothing saying+ why, so such a package MUST declare a `@astryxdesign/cli` peerrange that admits only CLIs that read it: `integration add doc --parent` MUST declare it,and `astryx integration verify` MUST fail without it. The same checkcovers a template that sets `replaces` (`spec:AST-035`), a doc section that@@ -166,20 +192,62 @@ the docsite onto the tree.each. A topic keeps its own name as its route, so no name changes; a read ofit offers Up to the level and Previous and Next among its topics, as any treenode does. Placing a topic in a real section takes it out of the level.+- **FR13 — A flat topic becomes a namespace without breaking an unambiguous+ read.** A+ provider's flat topic MAY become a namespace of guides only when every rule+ below holds for the result:+ - The namespace takes the topic's name, so its route and `astryx docs <name>`+ are unchanged, and no flat topic keeps the name, so the name has one owner+ (FR4).+ - Every section of the topic lands in exactly one guide, with its title, its+ `id`, and the key a reader addresses it by unchanged; when regrouping would+ change a section's derived key, the section's `id` pins the old key. No+ section is dropped, merged into another, or copied into two guides. No two+ guides below the namespace share a section key, so a section read names one+ guide (FR6).+ - Each guide answers one task or one decision a reader brings, and its title+ and summary name it. A guide is not a fragment cut at a size, and each+ meets the size budget of FR8.+ - Every link, `{@link}` target, and token reference the provider's docs make+ to the topic still resolves: each names the namespace, or the guide that+ holds what it pointed at, and the graph walk fails on one left behind+ (`spec:AST-047` FR11). A token reference that names the namespace reads its+ guides as one topic, their sections in tree order.+ - A read in another language (`--dense`, `--zh`) of a guide, or of one of its+ sections, returns the text the topic's read in that language returned for+ each section the guide holds.+ - Each piece of content appears once: the topic list names the namespace in+ `meta.namespaces` and no topic in `data` by that name (FR7), search returns+ each section once, from the guide that holds it (FR10), and no flat topic+ keeps a copy of guide content for references or pages to read.+- **FR14 — The docsite shows a root namespace as one page.** The docsite MUST+ read the tree through the CLI's public docs API. A root namespace with a+ guide below it MUST be one page at the namespace's slug: the namespace's own+ content, then every guide below it in tree order, as the read+ `astryx docs <namespace> --depth all --detail full` returns it. A nested+ namespace's own content opens its guides on that page, and typed docs below+ the namespace open only in `astryx docs`. A topic that becomes a namespace (FR13) therefore keeps its+ address, its sidebar group, and its text. The slug of each guide and nested+ namespace below it (its route with `/` as `-`) MUST be a temporary redirect+ to where its text starts on the page. A root namespace whose slug is a+ package's page (`cli` is the CLI package's page) keeps one page per guide,+ at the guide's slug, and has no namespace page. A namespace page's sidebar+ group MUST be the namespace's own `category`; without one, `foundations`+ when every guide below it is a foundations doc, and `guide` otherwise. A+ namespace with no guide below it, such as the Unorganized level (FR12), has+ no page. The docsite build MUST fail when a slug is both a page and a+ redirect, or both a flat topic and a namespace page.### Platform support- Supported feature/engine floor: every supported CLI runtime.- Unsupported behavior: none.-- Browser evidence: not applicable; the docsite is unchanged in phase 1.+- Browser evidence: none beyond the docsite's page and redirect tests (FR14);+ the record makes no browser-specific claim.## Current-state impact-Before this record, `astryx docs` read only flat topics. The CLI's typed docs-were sections of one generated `cli` topic, and the NamespaceDoc type and the-`placement` field existed but nothing read them.--Phase 1 changes:+Phase 1 changes these surfaces:- the CLI ships its namespace docs and the guides they place in`assets/docs/tree/`, each named after its doc; the flat topic list does not@@ -188,30 +256,37 @@ Phase 1 changes:`collectDocInputs` lists the tree files as a `tree` root;- the four tree diagnostics (`invalid_namespace`, `invalid_placement`,`overlapping_adoption`, `duplicate_route`) join the compiler's codes;-- `astryx docs`, `docs()`, and `astryx doctor` read the tree as FR5–FR8 state;+- `astryx docs`, `docs()`, and `astryx doctor` read the tree as FR5–FR8 state,+ and a section read on a namespace resolves through its guides (FR6);- `astryx search` finds sections and tree nodes, as FR10 states;- an integration's namespace docs and placed guides join the tree, and`astryx doctor integration docs` checks them, as FR11 states;- `cli-integrations` moves to `cli/integrations`, and every reference moveswith it;- every flat topic sits in the generated Unorganized level, as FR12 states;-- the docsite reads the placed guides through `docs()`, and- `/docs/cli-integrations` redirects to the first of them.+- a flat topic that becomes a namespace keeps its unambiguous reads inside+ its own package, as FR13 and FR6 state;+- the docsite reads the tree through `docs()`: each root namespace is one page+ and its guides' slugs redirect into it (FR14); the `cli` namespace's guides+ keep their own pages, and `/docs/cli-integrations` redirects to the first of+ them.`architecture:cli-surface` INV25 and INV26 carry this record into the code.## Verification-| Contract | Verification | Representative states | Mutation or failure expectation |-| ------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |-| FR1, FR3, FR4 | Tree builder fixture tests | three authored levels; adoption with and without `groupBy`; reversed input order; order and title sort | A route that ignores the parent, a folder that implies a parent, or a tree that depends on input order |-| FR2 | Tree builder failure fixtures | no slot; unknown slot; a slot that refuses the kind; another package's parent; not a reference; two adopters; a cycle | A failed placement that falls back to adoption, or a failure without a diagnostic |-| FR5, FR6, FR7 | `docs()` dispatcher tests and CLI runs | `cli`, `cli/api`, one function, the placed guide and its sections, the old name, a typo route | A namespace that inlines grandchildren, a lost section read, or a wrong error code |-| FR8 | Doctor tests | this repo; a fixture tree with a broken placement | A broken tree or an unplaced CLI doc that passes |-| FR9 | Real-tree tests and the route inventory | every command, function, schema, and enum doc; every exported API function | A CLI typed doc without its route, or a route inventory row the tree contradicts |-| FR10 | Search tests and CLI runs | a guide section; a typed doc by its own name; an error code; a topic hit; no core installed | A section hit whose command reads the whole topic, or a docs-only search that needs core |-| FR11 | Integration tree tests | a namespace and two placed guides from a package whose provider id differs from its name; a broken link; a claim on the `cli` route | A node named by the package name, a broken link that passes either doctor, or an integration that takes a CLI route |-| FR12 | `docs()` tests, the graph walk, and search tests | the level and its children in list order; a topic's Up, Previous, and Next; a flat topic hit's parent; an integration's flat topic | A flat topic without a home, a topic whose name changes, or a level that lists a placed guide |+| Contract | Verification | Representative states | Mutation or failure expectation |+| ------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| FR1, FR3, FR4 | Tree builder fixture tests | three authored levels; adoption with and without `groupBy`; reversed input order; order and title sort | A route that ignores the parent, a folder that implies a parent, or a tree that depends on input order |+| FR2 | Tree builder failure fixtures | no slot; unknown slot; a slot that refuses the kind; another package's parent; not a reference; two adopters; a cycle | A failed placement that falls back to adoption, or a failure without a diagnostic |+| FR5, FR6, FR7 | `docs()` dispatcher tests and CLI runs | `cli`, `cli/api`, one function, the placed guide and its sections, the old name, a typo route; a section on a namespace that one guide, no guide, and two guides hold | A namespace that inlines grandchildren, a lost section read, a section read that picks one of two guides, or a wrong error code |+| FR8 | Doctor tests | this repo; a fixture tree with a broken placement | A broken tree or an unplaced CLI doc that passes |+| FR9 | Real-tree tests and the route inventory | every command, function, schema, and enum doc; every exported API function | A CLI typed doc without its route, or a route inventory row the tree contradicts |+| FR10 | Search tests and CLI runs | a guide section; a typed doc by its own name; an error code; a topic hit; no core installed | A section hit whose command reads the whole topic, or a docs-only search that needs core |+| FR11 | Integration tree tests | a namespace and two placed guides from a package whose provider id differs from its name; a broken link; a claim on the `cli` route | A node named by the package name, a broken link that passes either doctor, or an integration that takes a CLI route |+| FR12 | `docs()` tests, the graph walk, and search tests | the level and its children in list order; a topic's Up, Previous, and Next; a flat topic hit's parent; an integration's flat topic | A flat topic without a home, a topic whose name changes, or a level that lists a placed guide |+| FR13 | Split tests over the topic before and after, the graph walk, and search tests | each old section key read through the namespace; a link and a token reference to the old topic; a `--dense` read; the topic list and a search for one section | A dropped, merged, or copied section; a changed title or `id`; a reference left on the old identity; a name listed twice; a section found twice |+| FR14 | Docsite page-generation and route-resolution tests | a split namespace; a nested namespace; a package-page namespace; a namespace with a `category`, and one whose guides are all foundations docs; the Unorganized level | An old address that stops resolving or lands in another sidebar group, a permanent guide redirect, a guide page on a non-package namespace, or a slug that is both a page and a redirect |## Decision log@@ -220,9 +295,9 @@ Phase 1 changes:**Reference:** `spec:AST-046/DEC-1`**Decider:** `josephfarina`, `2026-09-22`-The compiler, the CLI reader, and Doctor come first; the docsite moves onto the-tree late, and current docsite pages stay up until then. Starting with the CLI's-own docs tests the contract on docs one team owns.+The compiler, the CLI reader, and Doctor come first; the docsite follows the+tree only as far as FR14 states, and every current docsite address keeps+working. Starting with the CLI's own docs tests the contract on docs one team owns.Rejected: one change that moves every doc and the docsite at once. It is toolarge to review, and every route changes before the contract is proven.@@ -264,8 +339,62 @@ the tree in the same change as the CLI's.Rejected: a later phase for integration namespaces.+### DEC-5 — A split keeps the topic's name and its unambiguous reads++**Reference:** `spec:AST-046/DEC-5`+**Decider:** `josephfarina`, `2026-10-08`++A long topic gets short guides without a breaking change. The `docs` command's+response schemas are a contract (`spec:AST-017/FR45`), and a split moves no+content, so it keeps the topic's unambiguous released reads working inside its+own package, even where FR45 would let a route stop resolving. The one+deliberate exception is a title fragment that matches sections in two guides,+which asks instead of guessing (DEC-6); references from other packages are an+open question (OQ2). The namespace takes the topic's name, so its+route and every command that opens it stay the same;+sections keep their titles and ids, so section reads and links keep resolving;+each piece of content appears once, so a reader never weighs two copies. A+guide is shaped by the task or decision it answers, which is what search and a+reader's next step look for.++Rejected: keeping the flat topic beside the namespace, as an alias or a data+copy; the name has two owners and lists and search show the content twice.++### DEC-6 — A section read on a namespace resolves through its guides++**Reference:** `spec:AST-046/DEC-6`+**Decider:** `josephfarina`, `2026-10-08`++A released `astryx docs <topic> <section>` command keeps working after its+topic becomes a namespace when its section is unambiguous: its exact key, or a+title fragment that only one guide's read matches. Each guide's own read+decides between that guide's sections, as a topic's read does. Any other case fails with the error an unknown section already+gives, naming the guides, so the reader is one step from the answer.++Rejected: failing every section argument on a namespace; it breaks released+section reads of each split topic.+Rejected: the first match in tree order; it picks a guide silently when two+match.++### DEC-7 — The docsite shows a root namespace as one page++**Reference:** `spec:AST-046/DEC-7`+**Decider:** `josephfarina`, `2026-10-08`++A person reading the docsite keeps one full page per topic, at the same address+and in the same sidebar group, however the CLI splits it; an agent reads the+guides one at a time. Guide addresses redirect temporarily, so a later site+version can give guides their own pages without breaking a saved link. A+namespace whose slug is a package's page keeps one page per guide, because that+slug already belongs to the package.++Rejected: one docsite page per guide; it moves each split topic's address and+thins its page.+## Open questions-- The layout of the docsite's tree pages: children listed on the namespace page,- or inlined on it. The data is the same either way; the docsite phase decides.-- Where the `authoring` group's docs live in the tree.+- **OQ1 — Where the `authoring` group's docs live in the tree.** (`human-api`)+- **OQ2 — What another provider's doc reads when it links to, extends, or+ replaces a topic that becomes a namespace.** (`human-api`) FR13 moves every+ reference inside the topic's own provider; a reference in another package+ cannot move with it.