An open source design system that's fully customizable and agent ready
TypeScript
docs(cli): classify documentation route moves as nonbreaking (#6753)
Cindy Zhang91bc3ee0b59a
diff --git a/.changeset/cli-integrations-route.md b/.changeset/cli-integrations-route.mdindex 98161c01d7..94a6a06420 100644--- a/.changeset/cli-integrations-route.md+++ b/.changeset/cli-integrations-route.md@@ -1,9 +1,9 @@----'@astryxdesign/cli': minor+'@astryxdesign/cli': patch----[breaking] The integration guide moved from `astryx docs cli-integrations` to `astryx docs cli/integrations`. (#6626)+[feat] The integration guide moved from `astryx docs cli-integrations` to `astryx docs cli/integrations`. (#6626)-The guide now lives in the CLI's docs tree, under `cli`. The old name is gone: `astryx docs cli-integrations` and `docs('cli-integrations')` fail with an unknown topic. Use `astryx docs cli/integrations`, including section reads such as `astryx docs cli/integrations components`. The docsite page stays at `/docs/cli-integrations`.+Documentation names and routes are mutable catalog data under `spec:AST-017/FR45`, so the move is nonbreaking and needs no compatibility alias. The guide now lives in the CLI's docs tree, under `cli`. Use `astryx docs cli/integrations`, including section reads such as `astryx docs cli/integrations components`. The old name no longer resolves. The docsite page stays at `/docs/cli-integrations`.@josephfarinadiff --git a/docs/specs/AST-017/spec.md b/docs/specs/AST-017/spec.mdindex f3a61f3047..f23751a1e8 100644--- a/docs/specs/AST-017/spec.md+++ b/docs/specs/AST-017/spec.md@@ -45,6 +45,7 @@ affects_consumer_docs: [release-process, templates]"DEC-11","DEC-12","DEC-13",+ "DEC-14","FR3","FR4","FR5",@@ -79,7 +80,8 @@ affects_consumer_docs: [release-process, templates]"FR41","FR42","FR43",- "FR44"+ "FR44",+ "FR45"]}}@@ -360,10 +362,11 @@ independent for each invocation.- **FR25 — Stable Core and every published stable package default to compatibility.**Outside approved cleanup, changes to behavior, types, exports, CSS or tokens,documented markup or selectors, accessibility semantics, persistence, CLI,- configuration, schemas, build tooling, docs routes, and package files MUST be- additive, implementation-equivalent, or a victim-free contract restoration under- FR5. An internal label, low adoption, or lack of a source-level API change does not- weaken this rule.+ configuration, schemas, build tooling, contractual documentation operations, and+ package files MUST be additive, implementation-equivalent, or a victim-free+ contract restoration under FR5. Documentation catalog names and routes follow+ FR45. An internal label, low adoption, or lack of a source-level API change does+ not weaken this rule.- **FR26 — Public lifecycle state is explicit.** Each public surface is`experimental`, `stable`, `correction-transition`, `deprecated`,`cleanup-approved`, or `removed`; private and unreleased surfaces remain outside the@@ -512,6 +515,15 @@ independent for each invocation.forward with a compatible patch that restores aliases or the prior safecompatibility mode; critical-harm recovery follows FR35 and never restores theharmful behavior.+- **FR45 — Documentation catalog display names and routes are mutable data.** A+ display name or docs-tree route identifies an entry in the current documentation+ catalog; it is not a contractual CLI operation or machine-readable schema. Renaming+ or moving an entry is nonbreaking even when its former value stops resolving, and+ requires no compatibility alias or codemod. Release metadata identifies the+ replacement value. The `docs` command name, options, exit behavior, and response+ schemas remain contractual under FR3 and FR13. Template identifiers, slugs, display+ names, and names are outside this requirement and remain governed separately by FR9,+ FR11, and applicable registry identity contracts.### Platform support@@ -590,7 +602,9 @@ lifecycle around it:cleanup, closed release metadata, and independently patch-compatible fixes;- minor frequency remains planning guidance and creates no deprecation or pair wait;- contributor declarations preserve established Changeset tags while adding semantic- lifecycle metadata and require no migration of existing Changesets; and+ lifecycle metadata and require no migration of existing Changesets;+- documentation catalog display names and routes remain mutable data while the stable+ `docs` command and machine-readable schemas stay contractual; and- exact-main release comparison rejects unclassified deltas.These are specification changes only. They do not alter a published package and need@@ -617,6 +631,7 @@ they land, maintainers apply these requirements in review and release approval.| FR32–FR35 | Latest-stable victim fixture, pre-existing authority, owner reviews, correction record, record-to-surface state mapping, and emergency attestation | victim-free `[fix]`, `[fix]` plus incompatible-fix metadata, coexistence, cleanup transition, critical-harm emergency | A released victim uses bare `[fix]`, a new Changeset tag replaces metadata, a correction record disagrees with its public-surface state, or urgency bypasses migration || FR36–FR40 | Minor plan, locked final-patch receipt, three-way delta classification, and separated release notes | ordinary cadence, immediate pair, cleanup, release metadata, pre/post-lock compatible fix | Cadence becomes eligibility, the final patch is recut for bookkeeping, a feature or incompatible fix enters the incidental-fix lane, or release notes merge cleanup with fixes || FR41–FR44 | Schema validation, PR declaration, semantic stable/base/head comparisons, exact-main gate, and immutable publish/rollback receipt | duplicate ids, missing evidence, route/schema removal, old-client metadata, partial publish, safe rollback | A label passes without semantics, a delta maps zero or multiple times, fixed-group membership drifts, or a release rebuilds under one identity |+| FR45 | Docs route inventory, repository-reference checks, and Changeset review | catalog entry rename, former-route miss, stable command and JSON schema | Catalog routing is frozen as API, or a rename silently changes the contractual command or response schema |## Decision log@@ -867,6 +882,26 @@ Rejected: an inferred elapsed-time gate, a special exception merely to publish aready pair, and using cadence to waive replacement, migration, cleanup, or exact-mainevidence.+### DEC-14 — Documentation catalog display names and routes are mutable data++**Reference:** `spec:AST-017/DEC-14`+**Decider:** `josephfarina`, `2026-09-29`++Treat a documentation catalog display name or tree route as data identifying a current+entry. It may change in a patch release even when its former value stops resolving.+Release metadata identifies the replacement; no compatibility alias or codemod is+required.++Keep the surrounding operation contractual: incompatible changes to the `docs`+command, its options, exit behavior, or machine-readable response schemas still+follow FR1–FR8 and FR13. Template identifiers, slugs, display names, and names remain+outside this documentation rule and follow FR9, FR11, and applicable registry identity+contracts.++Rejected: treating every route-shaped positional value as stable CLI API. That would+freeze documentation organization rather than protect the command and schema+contracts readers and automation rely on.+## Open questionsNone.diff --git a/docs/specs/AST-046-docs-tree/spec.md b/docs/specs/AST-046-docs-tree/spec.mdindex 4795d373ff..2c48cf1d8e 100644--- a/docs/specs/AST-046-docs-tree/spec.md+++ b/docs/specs/AST-046-docs-tree/spec.md@@ -118,9 +118,10 @@ the docsite onto the tree.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 guide's route MUST be- `cli/integrations`; its old flat name `cli-integrations` is gone. A CLI route- or name MAY change like this when every reference changes with it: links name- docs by identity (`spec:AST-047` FR9), and the graph walk fails on a reference+ `cli/integrations`; its old flat name `cli-integrations` is gone. Under+ `spec:AST-017/FR45`, a CLI route or name MAY change like this when every+ reference changes with it: links name docs by identity (`spec:AST-047` FR9),+ and the graph walk fails on a referenceleft behind (`spec:AST-047` FR11, FR12).- **FR10 — Search finds the smallest part that answers.** `astryx search` MUSTindex each section of each topic and placed guide, and each namespace and