@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

package/assets/docs/styling.doc.mjs

@@ -30,7 +30,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'All approaches resolve to the same design tokens, so theming and dark mode work regardless of which you choose. For external styling libraries, run `astryx docs styling-libraries`; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',
+          text: 'All approaches resolve to the same design tokens, so theming and dark mode work regardless of which you choose. For external styling libraries, run {@link generic:styling-libraries}; it covers Tailwind, StyleX, Panda, Chakra, MUI, CSS-in-JS, CSS Modules, Sass, and `useTheme()` for non-CSS processing.',
         },
       ],
     },
@@ -118,7 +118,7 @@ const overrides = stylex.create({
         },
         {
           type: 'prose',
-          text: 'The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use. This is the paved Tailwind path; for other styling libraries that follow the same aliasing pattern, run `astryx docs styling-libraries`.',
+          text: 'The bridge is pure CSS with zero JS. Theme changes (dark mode, custom themes) apply automatically because the utilities reference the same CSS custom properties that components use. This is the paved Tailwind path; for other styling libraries that follow the same aliasing pattern, run {@link generic:styling-libraries}.',
         },
       ],
     },
@@ -263,7 +263,7 @@ const overrides = stylex.create({
         },
         {
           type: 'prose',
-          text: 'For systematic theming, use defineTheme component overrides instead of raw CSS selectors. defineTheme keeps the higher-level `prop:value` API (`variant:primary`, `size:sm`) and handles selector generation for you. Run `astryx docs theme` for the full theming guide.',
+          text: 'For systematic theming, use defineTheme component overrides instead of raw CSS selectors. defineTheme keeps the higher-level `prop:value` API (`variant:primary`, `size:sm`) and handles selector generation for you. Run {@link generic:theme} for the full theming guide.',
         },
       ],
     },
@@ -338,7 +338,7 @@ const styles = stylex.create({
         },
         {
           type: 'prose',
-          text: 'See `astryx docs tokens` for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See `astryx docs theme` for how to override tokens via defineTheme.',
+          text: 'See {@link generic:tokens} for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See {@link generic:theme} for how to override tokens via defineTheme.',
         },
       ],
     },

package/assets/docs/theme.doc.mjs

@@ -76,7 +76,7 @@ function App() {
             [
               'Neutral',
               "import {neutralTheme} from '@astryxdesign/theme-neutral'",
-              'Muted, minimal aesthetic with system fonts. A good starting point.',
+              'Muted, minimal aesthetic with Figtree typography. A good starting point.',
             ],
             [
               'Butter',
@@ -152,7 +152,7 @@ function App() {
         },
         {
           type: 'prose',
-          text: 'The copy is editable project source, not a reference back into node_modules. Every file named by the theme catalog comes with it, including nested token or palette modules. A second add refuses to overwrite those files unless you pass `--overwrite`.',
+          text: 'The copy is editable project source, not a reference back into node_modules. The complete theme directory comes with it, including its typed `.doc.mjs`, nested token and palette modules, and receipts. A second add refuses to overwrite those files unless you pass `--overwrite`.',
         },
       ],
     },
@@ -391,7 +391,7 @@ const brandTheme = defineTheme({
       content: [
         {
           type: 'prose',
-          text: 'The `components` field in defineTheme uses semantic component keys and style keys, not raw CSS selectors. Use `base` for all instances, `variant:value` or `stateName` for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in `astryx docs styling`.',
+          text: 'The `components` field in defineTheme uses semantic component keys and style keys, not raw CSS selectors. Use `base` for all instances, `variant:value` or `stateName` for specific props/states, and let the theme pipeline choose the underlying selector. For raw external CSS escape hatches, prefer the data-attribute selector surface documented in {@link generic:styling}.',
         },
         {
           type: 'code',
@@ -572,7 +572,7 @@ import './themes/ocean.css';
         },
         {
           type: 'prose',
-          text: "The build also warns when the theme names font families it does not load (webfonts like Fraunces) and prints the `<link>`/`@font-face` to add. The built CSS only sets font-family, so loading the font files stays the app's job. See `astryx docs typography` for the full recipe.",
+          text: "The build also warns when the theme names font families it does not load (webfonts like Fraunces) and prints the `<link>`/`@font-face` to add. The built CSS only sets font-family, so loading the font files stays the app's job. See {@link generic:typography} for the full recipe.",
         },
       ],
     },
@@ -811,7 +811,7 @@ function ChartConfig() {
         },
         {
           type: 'prose',
-          text: 'See `astryx docs styling-libraries` for styling-library interop and `astryx docs tokens` for the full token reference.',
+          text: 'See {@link generic:styling-libraries} for styling-library interop and {@link generic:tokens} for the full token reference.',
         },
       ],
     },

package/assets/docs/tokens.doc.mjs

@@ -1102,7 +1102,7 @@ export const docs = {
         },
         {
           "type": "prose",
-          "text": "See `astryx docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `astryx docs theme` for overriding tokens with defineTheme."
+          "text": "See {@link generic:styling} for how to apply tokens via xstyle, className, and compound component patterns. See {@link generic:theme} for overriding tokens with defineTheme."
         }
       ]
     }

package/assets/docs/tree/api.doc.mjs

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/api`: the programmatic API of `@astryxdesign/cli/api`.
+ *
+ * Adopts each function, schema, and enum doc whose `namespace` is `cli/api`,
+ * one generated level per kind: `cli/api/functions`, `cli/api/schemas`, and
+ * `cli/api/enums`.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'api',
+  title: 'API',
+  summary:
+    'The programmatic API: functions, the JSON output envelope, error codes, and response types.',
+  keywords: ['api', 'functions', 'schemas', 'enums', 'json'],
+  placement: {parent: 'namespace:cli', slot: 'reference', order: 20},
+  slots: {
+    kinds: {title: 'Reference', accepts: {kinds: ['namespace']}},
+  },
+  adopts: [
+    {
+      source: {group: 'cli/api', kinds: ['function', 'schema', 'enum']},
+      into: 'kinds',
+      groupBy: 'kind',
+    },
+  ],
+};

package/assets/docs/tree/cli.doc.mjs

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli`: the top of the CLI's docs tree (spec:AST-046).
+ *
+ * A namespace declares a level and its slots. It never lists its children:
+ * a guide places itself here with `placement`, and the `commands` and `api`
+ * namespaces adopt the CLI's typed docs by the `namespace` group each declares.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'cli',
+  title: 'Astryx CLI',
+  summary:
+    'Commands, programmatic APIs, integration authoring, and output contracts.',
+  keywords: ['cli', 'commands', 'api', 'reference'],
+  slots: {
+    guides: {title: 'Guides', accepts: {kinds: ['generic', 'namespace']}},
+    reference: {title: 'Reference', accepts: {kinds: ['namespace']}},
+  },
+};

package/assets/docs/tree/commands.doc.mjs

@@ -0,0 +1,25 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file `astryx docs cli/commands`: every command the CLI ships.
+ *
+ * Adopts each command doc whose `namespace` is `cli/commands`, so a new
+ * command appears here with no edit to this file.
+ */
+
+/** @type {import('@astryxdesign/cli/authoring').NamespaceDoc} */
+export const docs = {
+  type: 'namespace',
+  name: 'commands',
+  title: 'Commands',
+  summary:
+    'Every command and subcommand: usage, options, examples, and exit codes.',
+  keywords: ['commands', 'usage', 'options', 'flags'],
+  placement: {parent: 'namespace:cli', slot: 'reference', order: 10},
+  slots: {
+    commands: {title: 'Commands', accepts: {kinds: ['command']}},
+  },
+  adopts: [
+    {source: {group: 'cli/commands', kinds: ['command']}, into: 'commands'},
+  ],
+};

package/assets/docs/{cli-integrations.doc.mjs → tree/integrations.doc.mjs}

@@ -1,13 +1,20 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+/**
+ * @file `astryx docs cli/integrations`: the guide to building an integration
+ * package. It lives in the docs tree under the `cli` namespace (spec:AST-046),
+ * so its only route is `cli/integrations`.
+ */
 
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
 export const docs = {
-  name: 'cli-integrations',
+  type: 'generic',
+  name: 'integrations',
+  placement: {parent: 'namespace:cli', slot: 'guides', order: 10},
   title: 'CLI Integrations',
   category: 'guide',
   description:
-    'Author an npm package that contributes components, templates, themes, docs, and upgrade codemods to Astryx.',
+    'Build an Astryx integration: an npm package that contributes components, templates, themes, docs, and upgrade codemods.',
 
   sections: [
     {
@@ -20,11 +27,11 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'The authoring CLI owns the integration file. The first `astryx integration add` creates `astryx.integration.mjs`; each later add declares its root only after writing a valid contribution behind it. Identity (name and version) still comes from package.json. For the consumer side, run `astryx docs getting-started`.',
+          text: 'The authoring CLI owns the integration file. The first `astryx integration add` creates `astryx.integration.mjs`; each later add declares its root only after writing a valid contribution behind it. Identity (name and version) still comes from package.json. For the consumer side, run {@link generic:getting-started}.',
         },
         {
           type: 'prose',
-          text: 'Every file an integration author writes is documented field by field in `npx astryx docs authoring`: the manifest, astryx.config, codemods, identity, and each doc type. `npx astryx docs authoring --index` lists them, and `npx astryx docs authoring <key>` reads one.',
+          text: 'Every file an integration author writes is documented field by field in {@link generic:authoring}: the manifest, astryx.config, codemods, identity, and each doc type. `npx astryx docs authoring --index` lists them, and `npx astryx docs authoring <key>` reads one.',
         },
         {
           type: 'prose',
@@ -84,7 +91,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'A useful theme package usually ships more than colors. Start with the source theme, author the palette request at `themes/ocean/palette.config.json`, then add the guides its consumers need. The `integration add` commands keep the package manifest in sync; add palette outputs to the theme catalog after generation.',
+          text: 'A useful theme package usually ships more than colors. Start with the source theme, author the palette request at `themes/ocean/palette.config.json`, then add the guides its consumers need. The `integration add` commands keep the package manifest in sync. Palette outputs live inside the theme directory, which ships as one unit, so there is nothing to register after generation.',
         },
         {
           type: 'code',
@@ -94,7 +101,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "Edit the generated theme and guide files before publishing. The shown palette command writes `themes/ocean/tokens/ocean.palette.ts` and its sibling `themes/ocean/tokens/ocean.palette.receipt.json`. The TypeScript candidate directly exports `black`, `white`, and `palette`; import what the theme uses from `./tokens/ocean.palette`. Keep the request at `themes/ocean/palette.config.json`, and list the theme source, request, candidate, and receipt in the catalog entry's `files` array. Add any optional wrapper, refs, icon, or preview modules only when you author them, and list each one too. `integration pack --check` runs the real package lifecycle and compares local discovery with the npm tarball, so a missing source file or files allowlist entry fails before a consumer sees it.",
+          text: 'Edit the generated theme descriptor, source, and guide files before publishing. The shown palette command writes `themes/ocean/tokens/ocean.palette.ts` and its sibling `themes/ocean/tokens/ocean.palette.receipt.json`, a reproducibility receipt. The TypeScript candidate directly exports `black`, `white`, and `palette`; import what the theme uses from `./tokens/ocean.palette`. Keep the request at `themes/ocean/palette.config.json`. The whole theme directory is copied and packed as one unit, so an optional wrapper, refs, icon, or preview module you add inside it ships with the theme. `integration pack --check` runs the real package lifecycle and compares local discovery with the npm tarball, so a missing source or descriptor fails before a consumer sees it.',
         },
         {
           type: 'code',
@@ -104,7 +111,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'The package must be a direct dependency for automatic discovery. No `astryx.config` entry is needed unless the app must control integration order. `theme add` copies every file listed by the selected catalog entry, including nested token modules, and refuses to overwrite existing project files.',
+          text: "The package must be a direct dependency for automatic discovery. No `astryx.config` entry is needed unless the app must control integration order. `theme add` copies the selected theme's complete directory, including its typed `.doc.mjs`, nested token modules, and receipts, and refuses to overwrite existing project files.",
         },
       ],
     },
@@ -119,7 +126,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'text',
-          code: "Kind        Metadata suffix            type stamp     Source file\n────────    ─────────────────────────  ─────────────  ──────────────────────\nComponent   Name.doc.{ts,mjs,js}       'component'    Name.tsx (same stem)\nTemplate    Name.template.{ts,mjs,js}  'page'/'block' Name.tsx (same stem)\nDoc topic   topic.doc.{ts,mjs,js}      'generic'      (none — docs are prose)\nCodemod     <version>/<id>.{ts,mjs,js} 'code'/'config' (the codemod IS the source)\nTheme       manifest.json entry         —             <slug>/<entry>.ts",
+          code: "Kind        Metadata file              type stamp     Source file\n────────    ─────────────────────────  ─────────────  ──────────────────────\nComponent   Name.doc.mjs               'component'    Name.tsx (same stem)\nTemplate    Name.doc.mjs               'page'/'block' Name.tsx (same stem)\nDoc topic   topic.doc.mjs              'generic'      (none — docs are prose)\nCodemod     <version>/<id>.{ts,mjs,js} 'code'/'config' (the codemod IS the source)\nTheme       <slug>/nameTheme.doc.mjs   'theme'        <slug>/nameTheme.ts (same stem)\n\nReleased .doc.js files, template .doc.ts files, and .template.{ts,mjs,js}\ntemplates still load. A component or topic .doc.ts loads only from a package\nlinked from outside node_modules; installed, it is listed but cannot be read.",
         },
         {
           type: 'prose',
@@ -152,7 +159,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "Export your components from your library however you like, and consumers still import them from your package. For each component the CLI should document, ship a `.doc.{ts,mjs,js}` file with the same stem, for example `AcmeCarousel.tsx` alongside `AcmeCarousel.doc.ts`. The doc file must default-export an object with `type: 'component'` — not `'generic'` (that is for reference docs) and not `'page'`/`'block'` (those are for templates).",
+          text: "Export your components from your library however you like, and consumers still import them from your package. For each component the CLI should document, ship a strongly typed `.doc.mjs` file with the same stem, for example `AcmeCarousel.tsx` alongside `AcmeCarousel.doc.mjs`. The doc file must default-export an object with `type: 'component'` — not `'generic'` (that is for reference docs) and not `'page'`/`'block'` (those are for templates). Released `.doc.js` docs remain readable for compatibility. A `.doc.ts` component doc reads only when the package is linked from outside node_modules, not once it is installed. New authoring uses `.doc.mjs`.",
         },
         {
           type: 'prose',
@@ -161,7 +168,7 @@ export const docs = {
         {
           type: 'code',
           lang: 'typescript',
-          code: "// AcmeCarousel.doc.ts\nexport default {\n  type: 'component',\n  name: 'AcmeCarousel',\n  description: 'A carousel that cycles through slides.',\n  // props, usage, examples, ...\n} satisfies import('@astryxdesign/cli/authoring').ComponentDoc;",
+          code: "// AcmeCarousel.doc.mjs\n/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */\nexport default {\n  type: 'component',\n  name: 'AcmeCarousel',\n  displayName: 'Acme Carousel',\n  usage: {description: 'A carousel that cycles through slides.'},\n  props: [],\n};",
         },
       ],
     },
@@ -171,20 +178,41 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "Templates are usually not exported from the package directly. Instead, consumers browse them through the CLI and materialize them into their app. Define a template as a plain object with `type: 'page'` (full pages) or `type: 'block'` (smaller chunks) as its default export in a `.template.{ts,mjs,js}` file next to the source, for example `AcmeLandingPage.tsx` and `AcmeLandingPage.template.ts`. Do not use the `.doc.{ts,mjs,js}` suffix — that is for component docs and reference docs.",
+          text: "Templates are usually not exported from the package directly. Instead, consumers browse them through the CLI and materialize them into their app. Define a template as a strongly typed plain object stamped with `type: 'page'` (full pages) or `type: 'block'` (smaller chunks) in a same-stem `.doc.mjs`, for example `AcmeLandingPage.tsx` and `AcmeLandingPage.doc.mjs`. Released `.template.*` files remain readable for compatibility.",
         },
         {
           type: 'prose',
-          text: 'A template id is its source-relative path with the metadata suffix removed; the display `name` is not its identity and may repeat. If an integration id matches a Core id, unqualified lookup fails closed instead of choosing one. Run `astryx doctor integration templates <package>` before publishing: it recommends renaming, but an intentional overlap is allowed when callers always pass `--package <package>`.',
+          text: "A template id is its exact source-relative path with the metadata suffix removed; the display `name` is not its identity and may repeat. Run `astryx --json template --list --package @astryxdesign/core` and copy the Core entry's `id` exactly. To replace one, generate the source/metadata pair with `integration add template`, then set `replaces` in that template's own metadata to the exact Core id. The declaration lives on the template, as `replaces` does on a doc topic; the manifest only points at the templates root.",
+        },
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Create the integration template',
+          code: 'astryx integration add template acme-app-shell --type page',
+        },
+        {
+          type: 'code',
+          lang: 'typescript',
+          label: 'Declare the replacement',
+          code: "// templates/acme-app-shell.doc.mjs\n/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */\nexport default {\n  type: 'page',\n  name: 'acme-app-shell',\n  displayName: 'Acme App Shell',\n  description: 'An app shell with Acme navigation.',\n  replaces: 'shell-side-nav',\n};",
         },
         {
           type: 'code',
           lang: 'typescript',
-          code: "// AcmeLandingPage.template.ts\nexport default {\n  type: 'page',\n  // name, description, preview, ...\n};",
+          label: 'Use product navigation in the replacement source',
+          code: "// templates/acme-app-shell.tsx\nimport {AppShell} from '@astryxdesign/core/AppShell';\nimport {Card} from '@astryxdesign/core/Card';\nimport {AcmeSideNav, AcmeTopNav} from '@acme/navigation';\n\nexport default function AcmeAppShell() {\n  return (\n    <AppShell\n      sideNav={<AcmeSideNav />}\n      topNav={<AcmeTopNav />}>\n      <Card>Product content</Card>\n    </AppShell>\n  );\n}",
+        },
+        {
+          type: 'prose',
+          text: 'With that declaration, `astryx template shell-side-nav` selects `acme-app-shell`; template listing, search, build suggestions, and block-layout lookup use the same effective identity. `astryx template shell-side-nav --package @astryxdesign/core` still selects the original, and `astryx template acme-app-shell --package @acme/navigation` explicitly selects the integration template. In the `template.list` JSON response, a winning replacement entry carries `replaces` naming the Core id it supersedes, and the Core entry is omitted from the default listing. A page can replace only a Core page, and a block can replace only a Core block. Missing Core targets, type mismatches, a declaration on a template that cannot be used, and more than one replacement from one package fail closed: Core stays the default and `astryx doctor integration templates <package>` reports the error. If multiple explicitly configured packages each replace the target, the package configured later wins with a warning. An explicitly configured replacement always wins over an autolinked one. If only autolinked packages conflict, the package listed later in package.json dependencies wins with a warning; add the intended package to `astryx.config` to make the choice explicit. Without `replaces`, valid template selection keeps the existing package-aware ambiguity behavior; contribution failure isolation still follows the rules below.',
+        },
+        {
+          type: 'prose',
+          text: "`replaces` is part of the strict template metadata object, so a CLI older than 0.7.0 rejects it: on those CLIs the package's templates and doc topics are withheld with one warning, while its components still load. Declare `@astryxdesign/cli >=0.7.0` when a package uses `replaces`.",
         },
         {
           type: 'prose',
-          text: 'The CLI needs both files at consume time. `integration add` includes the templates root when package.json already has a files allowlist. It never creates an exports map, because doing that can make previously-open deep imports private; when a map already exists, it adds the generated source subpath without replacing author-owned entries. Use consumer-safe extensionless subpaths in the exports map (e.g. `"./templates/AcmeDashboard"` instead of `"./templates/AcmeDashboard.tsx"`), so consumers import without knowing the file extension. `integration pack --check` proves the source and metadata survive the tarball and verifies every component through the public import its metadata advertises.',
+          text: 'The CLI needs both files at consume time. `integration add` includes the templates root when package.json already has a files allowlist. It never creates an exports map, because doing that can make previously-open deep imports private; when a map already exists, it adds the generated source subpath without replacing author-owned entries. Use consumer-safe extensionless subpaths in the exports map (e.g. `"./templates/AcmeDashboard"` instead of `"./templates/AcmeDashboard.tsx"`), so consumers import without knowing the file extension. `integration pack --check` proves the source and metadata, including `replaces`, survive the tarball and verifies every component through the public import its metadata advertises.',
         },
       ],
     },
@@ -194,12 +222,12 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "Point the integration file's `docs` field at a directory of reference docs and every `{topic}.doc.{ts,mjs,js}` under it becomes a topic the CLI serves: `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object with `type: 'generic'` as its default export — not `'component'` (that is for component docs with a same-stem source file). This is the same shape core's own topics use.",
+          text: "Point the integration file's `docs` field at a directory of reference docs and every strongly typed `{topic}.doc.mjs` under it becomes a topic the CLI serves: `astryx docs` lists it, `astryx docs <topic>` prints it, `astryx search` indexes it, and `astryx init` names it in the agent block. A topic is a plain object stamped `type: 'generic'` — not `'component'` (that is for component docs with a same-stem source file) — the same shape core's own topics use.",
         },
         {
           type: 'code',
           lang: 'typescript',
-          code: "// docs/deploying.doc.ts\nexport default {\n  type: 'generic',\n  name: 'deploying',\n  title: 'Deploying',\n  description: 'Ship an app built with Acme widgets.',\n  category: 'guide',\n  sections: [\n    {title: 'Overview', content: [{type: 'prose', text: '...'}]},\n  ],\n};",
+          code: "// docs/deploying.doc.mjs\n/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */\nexport default {\n  type: 'generic',\n  name: 'deploying',\n  title: 'Deploying',\n  description: 'Ship an app built with Acme widgets.',\n  category: 'guide',\n  sections: [\n    {title: 'Overview', content: [{type: 'prose', text: '...'}]},\n  ],\n};",
         },
         {
           type: 'prose',
@@ -212,7 +240,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "`extends: 'x'` merges onto a topic instead of owning it: a section with the same key as one in the base (its `id`, or the key its title derives) or the same title replaces that section, and a section the base does not have is appended. Reach for it to correct or add to a topic you do not want to fork: a fork of someone else's guide stops receiving their fixes the day you write it.",
+          text: "`extends: 'x'` merges onto a topic instead of owning it: a section with the same key as one in the base (its `id`, or the key its title derives) or the same title replaces that section, and a section the base does not have is appended. The topic keeps its own title and description; only `replaces` renames it. Reach for it to correct or add to a topic you do not want to fork: a fork of someone else's guide stops receiving their fixes the day you write it.",
         },
         {
           type: 'list',
@@ -233,38 +261,25 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: "A theme contribution is editable `defineTheme` source, not compiled CSS. Add `themes: './themes'` to `astryx.integration.*`, place the source under one directory per slug, and list it in `themes/manifest.json`. If package.json has a `files` allowlist, include both the integration manifest and the themes root; packages with no allowlist already publish both. Do not add an `exports` map only for theme discovery.",
+          text: "A theme contribution is editable `defineTheme` source, not compiled CSS. Add `themes: './themes'` to `astryx.integration.*`. Give each lower-kebab slug its own directory containing a theme source and mandatory same-stem, strongly typed `.doc.mjs`. If package.json has a `files` allowlist, include both the integration manifest and the themes root; packages with no allowlist already publish both. Do not add an `exports` map only for theme discovery.",
         },
         {
           type: 'code',
           lang: 'text',
-          code: 'themes/\n  manifest.json\n  ocean/\n    oceanTheme.ts\n    palette.config.json\n    tokens/\n      ocean.palette.ts\n      ocean.palette.receipt.json',
+          code: 'themes/\n  ocean/\n    oceanTheme.ts\n    oceanTheme.doc.mjs\n    palette.config.json\n    tokens/\n      ocean.palette.ts\n      ocean.palette.receipt.json',
         },
         {
           type: 'prose',
-          text: 'The root catalog `manifest.json` must be `{ "version": 1, "themes": [...] }`. Each entry in the `themes` array requires every field shown below — omitting any one is a hard validation error:',
-        },
-        {
-          type: 'list',
-          style: 'unordered',
-          items: [
-            '`slug` — lowercase kebab-case starting with a letter (e.g. `"ocean"`). Must be unique within the catalog.',
-            '`displayName` — human-readable label (e.g. `"Ocean"`).',
-            '`description` — string description of the theme.',
-            '`maintained` — boolean indicating active maintenance.',
-            '`entry` — source file relative to `themes/<slug>/` (e.g. `"oceanTheme.ts"`).',
-            '`exportName` — a valid JS identifier naming the runtime export in the entry file (e.g. `"oceanTheme"`). Astryx parses the source without executing it and rejects missing or type-only exports.',
-            '`files` — non-empty array of filenames relative to `themes/<slug>/`. Must include the entry file and every local static import the entry source uses. Astryx validates that every listed file exists on disk and that every local import in the entry names a file in this list.',
-          ],
+          text: '`ThemeDoc` owns `name` (the slug), `displayName`, `description`, and `maintained`. The descriptor/source stem supplies the source entry and required named runtime export. Astryx parses the source without executing it, confines every local static import and re-export to the theme directory, copies that complete directory, and rejects missing or type-only exports.',
         },
         {
           type: 'code',
-          lang: 'json',
-          code: '{\n  "version": 1,\n  "themes": [{\n    "slug": "ocean",\n    "displayName": "Ocean",\n    "description": "Ocean theme with OKLCH palettes.",\n    "maintained": true,\n    "entry": "oceanTheme.ts",\n    "exportName": "oceanTheme",\n    "files": [\n      "oceanTheme.ts",\n      "palette.config.json",\n      "tokens/ocean.palette.ts",\n      "tokens/ocean.palette.receipt.json"\n    ]\n  }]\n}',
+          lang: 'javascript',
+          code: "/** @type {import('@astryxdesign/cli/authoring').ThemeDoc} */\nexport default {\n  type: 'theme',\n  name: 'ocean',\n  displayName: 'Ocean',\n  description: 'Ocean theme.',\n  maintained: true,\n};",
         },
         {
           type: 'prose',
-          text: 'The generated candidate is already importable: it exports `black`, `white`, `palette`, and a default palette value. Import it directly from `./tokens/ocean.palette`. A wrapper or palette-refs module is optional application code, not generator output; list it only if you create it.',
+          text: 'The generated palette candidate is already importable: it exports `black`, `white`, `palette`, and a default palette value. Import it directly from `./tokens/ocean.palette`. A wrapper or palette-refs module is optional application code, not generator output.',
         },
         {
           type: 'prose',
@@ -343,6 +358,19 @@ export const docs = {
           lang: 'bash',
           code: '# Preview what would change (dry-run, the default)\nastryx upgrade --from 0.1.0\n\n# Apply the migration\nastryx upgrade --from 0.1.0 --apply',
         },
+        {
+          type: 'prose',
+          text: 'Core and integration upgrade codemods do not edit existing consumer files that the working tree protects. Protection is VCS-neutral: Astryx reads nested `.gitattributes` rules for `linguist-generated` and `linguist-vendored`, leading `@generated` and `@partially-generated` comments, standard `Code generated … DO NOT EDIT.` comments, `.gitignore`, and `.hgignore` directly from disk. Later attribute rules, explicit false or unset values, and ignore negation keep their normal semantics. Installed dependencies, VCS metadata, paths outside the project, and symbolic links are also protected. Directory or file names such as `dist` and `generated` are not evidence by themselves.',
+        },
+        {
+          type: 'prose',
+          text: 'A protected file is transformed only in memory. If it would change, the upgrade applies eligible owned-source edits, runs `hooks.postCodemod` regeneration, and checks the protected file again. A remaining change makes the run incomplete and exits nonzero with `ERR_CODEMOD_PROTECTED`; JSON output lists `modifiedFiles` and `protectedFiles` with every effective declaration. Generated headers may include `Command: <exact command>` so the result can tell a consumer how to regenerate when no hook resolves the output. Dry-run uses the same classification without writing.',
+        },
+        {
+          type: 'code',
+          lang: 'text',
+          code: '# .gitattributes\ngenerated/** linguist-generated=true\nvendor/** linguist-vendored=true\n\n# A later rule can explicitly return an authored file to normal handling\ngenerated/hand-authored.ts linguist-generated=false',
+        },
         {
           type: 'prose',
           text: 'All authoring types are exported from `@astryxdesign/cli/authoring`: `ComponentDoc`, `HookDoc`, and `ReferenceDoc` for docs, `TemplateDoc` for templates, and `AstryxConfig`, `AstryxIntegration`, and `AstryxCodemod` for the project files. Consumers can also run their own post-codemod hooks, such as a reinstall or rebuild, via `hooks.postCodemod` in their `astryx.config`.',
@@ -426,7 +454,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Discovery is resilient. A broken or misconfigured integration is skipped with a single non-blocking warning on stderr instead of crashing the CLI, and it never corrupts a `--json` stdout envelope. Everyday commands keep working with the remaining valid contributions.',
+          text: "Discovery is resilient. A manifest that fails to load is skipped because none of its roots are trustworthy. An error in one contribution kind is reported without hiding the integration's other valid kinds. Invalid template and component files are omitted without hiding valid siblings; other kinds keep their existing all-or-nothing behavior. Everyday commands keep working with the remaining valid contributions, warnings go to stderr, and `--json` stdout stays clean.",
         },
         {
           type: 'prose',

package/assets/docs/tree/integrations.test.mjs

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, expect, it} from 'vitest';
+import {docs as integrationGuide} from './integrations.doc.mjs';
+import {doc as integrationSchema} from '../../../authoring/integration/integration.doc.mjs';
+import {doc as templateSchema} from '../../../authoring/doctypes/template/template.doc.mjs';
+
+function guideText() {
+  return integrationGuide.sections
+    .flatMap(section => section.content)
+    .flatMap(block => {
+      if (block.type === 'prose') return [block.text];
+      if (block.type === 'code') return [block.label ?? '', block.code];
+      if (block.type === 'list') return block.items;
+      return [];
+    })
+    .join('\n');
+}
+
+describe('integration template replacement docs', () => {
+  it('documents the complete author and consumer contract', () => {
+    const text = guideText();
+
+    for (const required of [
+      "replaces: 'shell-side-nav'",
+      'acme-app-shell',
+      'astryx --json template --list --package @astryxdesign/core',
+      'astryx template shell-side-nav --package @astryxdesign/core',
+      'astryx template acme-app-shell --package @acme/navigation',
+      'templates/acme-app-shell.doc.mjs',
+      'AcmeSideNav',
+      'AcmeTopNav',
+      '<Card>Product content</Card>',
+      'fail closed',
+      'configured later wins',
+      'wins over an autolinked one',
+      'listed later in package.json dependencies',
+      'valid siblings',
+      'Without `replaces`',
+      '@astryxdesign/cli >=0.7.0',
+      'templates and doc topics are withheld',
+      '`template.list` JSON response',
+    ]) {
+      expect(text, required).toContain(required);
+    }
+  });
+
+  it('declares a replacement on the template, never in the manifest', () => {
+    expect(guideText()).not.toContain('templateReplacements');
+    expect(
+      integrationSchema.fields.some(field => /replac/i.test(field.name)),
+    ).toBe(false);
+
+    const field = templateSchema.fields.find(
+      candidate => candidate.name === 'replaces',
+    );
+    expect(field).toMatchObject({type: 'string'});
+    expect(field.description).toContain('Integration templates only');
+    expect(field.description).toContain('--package @astryxdesign/core');
+    expect(field.description).toContain('0.7.0');
+  });
+});