@astryxdesign/cli 0.3.0-canary.d52d2cb → 0.3.0-canary.dccdabe

package/README.md

@@ -72,7 +72,7 @@ Options:
 | `search`               | Search components, hooks, docs, and templates in one ranked list              |
 | `swizzle`              | Copy component source for customization                                       |
 | `template`             | Inject a page or block template                                               |
-| `theme`                | Theme tools — build, export, and manage themes                                |
+| `theme`                | Theme tools: build, export, and manage themes                                 |
 | `upgrade`              | Run codemods to migrate between versions                                      |
 | `validate-integration` | Validate an Astryx integration package (manifest + contributions)             |
 
@@ -385,7 +385,7 @@ Every response has a `type` discriminant. The full set is below (generated from
 
 | Type                        | What `data` carries                                                                                                                                                                                                                  |
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `component.list`            | The component catalog grouped by category: `detail` (the level — names \| compact \| full) and `components`, the grouped map of names+package, brief entries, or a full ComponentDoc per entry.                                      |
+| `component.list`            | The component catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of names+package, brief entries, or a full ComponentDoc per entry.                                       |
 | `component.detail`          | One component's authored ComponentDoc plus ownership metadata (owner package, import specifier, and whether source is available).                                                                                                    |
 | `component.detail.props`    | Just one component's props table (ComponentPropDoc[]).                                                                                                                                                                               |
 | `component.detail.source`   | One component's source file, as {component, source}.                                                                                                                                                                                 |
@@ -393,12 +393,12 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `component.detail.blocks`   | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                           |
 | `docs.list`                 | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.                                                                                                                                              |
 | `docs.detail`               | One topic's full ReferenceDoc, with token-ref blocks inlined.                                                                                                                                                                        |
-| `docs.detail.section`       | A single ReferenceSection of a topic — the first whose title contains the section query.                                                                                                                                             |
-| `blog.list`                 | The feed URL plus every post parsed from the RSS feed — each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                            |
+| `docs.detail.section`       | A single ReferenceSection of a topic: the first whose title contains the section query.                                                                                                                                              |
+| `blog.list`                 | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                             |
 | `blog.detail`               | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                            |
 | `discover.list`             | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                   |
 | `discover.detail`           | A single external package entry, for an @scope/name query.                                                                                                                                                                           |
-| `discover.detail.doc`       | The validated ComponentDoc for one external component — an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                      |
+| `discover.detail.doc`       | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                       |
 | `discover.search`           | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.                                                                                                                     |
 | `search`                    | The echoed query plus a ranked SearchResultEntry[] (domain, name, score, reason, description, follow-up command, and import path where relevant).                                                                                    |
 | `build.help`                | A marker (`playbook: true`) that the renderer expands into the how-to-build-a-page workflow; emitted when no query is given.                                                                                                         |
@@ -409,15 +409,15 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `template.show`             | The resolved template's raw source plus its description, kind, and the component names it composes.                                                                                                                                  |
 | `template.skeleton`         | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.                                                                                                         |
 | `template.copy`             | A scaffold receipt: template id, output directory, written file name, and file count.                                                                                                                                                |
-| `hook.list`                 | The hook catalog grouped by category: `detail` (the level — names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.                                                   |
+| `hook.list`                 | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.                                                    |
 | `hook.detail`               | One hook's full authored HookDoc.                                                                                                                                                                                                    |
 | `hook.detail.params`        | Just one hook's parameters table (HookParamDoc[]).                                                                                                                                                                                   |
 | `theme.build`               | A theme build receipt: name, token- and component-override counts, output size, the written outputs {css, js, dts, and variantsDts when applicable}, and any validation warnings.                                                    |
 | `theme.build.check`         | The --check receipt: theme name, an upToDate flag, the stale outputs (each {path, reason: missing \| outdated}), and the full list of checked paths. Writes nothing.                                                                 |
-| `theme.list`                | Every bundled theme as a ThemeListEntry[] — each with slug, displayName, description, and a maintained flag.                                                                                                                         |
+| `theme.list`                | Every bundled theme as a ThemeListEntry[]: each with slug, displayName, description, and a maintained flag.                                                                                                                          |
 | `theme.add`                 | A scaffold receipt: resolved slug, displayName, maintained flag, outputDir (relative to cwd), the theme entry file, its exportName, and the files written.                                                                           |
 | `upgrade.list`              | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.                                                                                                           |
-| `upgrade.status`            | A short-circuit outcome with no codemods run — up_to_date, no_codemods, or config_fixable — each carrying the agent-docs summary.                                                                                                    |
+| `upgrade.status`            | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.                                                                                                     |
 | `upgrade.run`               | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                          |
 | `manifest`                  | The self-describing CLI capability manifest: name, version, apiVersion, global options, the command tree (args, options, json flag, response types, examples), the jsonSupported allowlist, and the flat responseTypes index.        |
 | `doctor`                    | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and a fix when not passing) plus a `summary` of counts per status.                                                          |

package/api/blog/blog.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   displayName: 'blog()',
   summary: 'List blog posts, or read one, from the published RSS feed.',
   description:
-    'Reads the design system blog the same way any feed reader does — over the ' +
+    'Reads the design system blog the same way any feed reader does, over the ' +
     "published RSS feed, never the blog's source files. With no slug it lists every " +
     "post parsed from the feed; with a slug it reads that post's full plaintext body " +
     'via the .txt alternate the feed advertises. Both envelopes carry feedUrl so a ' +
@@ -35,7 +35,7 @@ export const doc = {
     {
       type: 'blog.list',
       description:
-        'The feed URL plus every post parsed from the feed — each with slug, title, description, date, type, authors, link, and its plaintext URL.',
+        'The feed URL plus every post parsed from the feed, each with slug, title, description, date, type, authors, link, and its plaintext URL.',
     },
     {
       type: 'blog.detail',

package/api/build/build.doc.mjs

@@ -54,7 +54,7 @@ export const doc = {
     {
       type: 'build.help',
       description:
-        'Emitted when the query is omitted — a pure marker (`data.playbook: true`) that the command renderer expands into the page-building workflow prose.',
+        'Emitted when the query is omitted: a pure marker (`data.playbook: true`) that the command renderer expands into the page-building workflow prose.',
     },
     {
       type: 'build.kit',

package/api/component/component.doc.mjs

@@ -108,7 +108,7 @@ export const doc = {
     {
       type: 'component.list',
       description:
-        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map — names+package, brief entries, or full ComponentDoc per entry.",
+        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: names+package, brief entries, or full ComponentDoc per entry.",
     },
     {
       type: 'component.detail',

package/api/discover/discover.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   summary: 'Browse and search components from configured external packages.',
   description:
     'Explores components contributed by configured external packages and integrations ' +
-    '— the ones that declare a components root. With no query it lists those packages; ' +
+    'the ones that declare a components root. With no query it lists those packages; ' +
     'an @scope/name query browses one package; @scope/name/Component (or a free-text ' +
     "term that resolves to a single component) returns that component's validated doc; " +
     'a free-text term with several matches returns the candidate list.',
@@ -68,7 +68,7 @@ export const doc = {
     {
       type: 'discover.detail.doc',
       description:
-        'The validated ComponentDoc for one external component — an @scope/name/Component query, or a free-text term that resolves to exactly one component.',
+        'The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term that resolves to exactly one component.',
     },
     {
       type: 'discover.search',

package/api/docs/docs.doc.mjs

@@ -13,7 +13,7 @@ export const doc = {
   name: 'docs',
   displayName: 'docs()',
   summary:
-    'Read the reference docs — list every topic, one topic, or a single section of a topic.',
+    'Read the reference docs: list every topic, one topic, or a single section of a topic.',
   description:
     'Routes on its arguments: no topic lists every reference-doc topic; a topic ' +
     'returns that full ReferenceDoc (with token-ref blocks inlined); a topic ' +
@@ -75,7 +75,7 @@ export const doc = {
     {
       type: 'docs.detail.section',
       description:
-        'A single ReferenceSection of the topic — the first whose title contains the section query.',
+        'A single ReferenceSection of the topic: the first whose title contains the section query.',
     },
   ],
   throws: [

package/api/doctor/doctor.doc.mjs

@@ -14,10 +14,10 @@ export const doc = {
   displayName: 'doctor()',
   summary: 'Read-only project + environment health check.',
   description:
-    'Runs a series of side-effect-free diagnostics — Node version, ' +
+    'Runs a series of side-effect-free diagnostics: Node version, ' +
     '@astryxdesign/core install and version alignment with the CLI, installed ' +
     'themes and wiring, astryx.config validity, agent docs, core peer ' +
-    'dependencies, and the detected package manager — and returns a structured ' +
+    'dependencies, and the detected package manager, and returns a structured ' +
     'report. It only reads (never installs, writes, or mutates), so it is safe ' +
     'as a CI gate and for agents to invoke.',
   importPath: '@astryxdesign/cli/api',
@@ -34,7 +34,7 @@ export const doc = {
     {
       type: 'doctor',
       description:
-        'The diagnostic report: `data.checks` — each with a stable id, label, `status` (`pass` | `warn` | `fail` | `info`), a one-line message, and a `fix` when the status is not `pass` — plus `data.summary` with counts per status.',
+        'The diagnostic report: `data.checks`, each with a stable id, label, `status` (`pass` | `warn` | `fail` | `info`), a one-line message, and a `fix` when the status is not `pass`; plus `data.summary` with counts per status.',
     },
   ],
   examples: [

package/api/hook/hook.doc.mjs

@@ -70,7 +70,7 @@ export const doc = {
     {
       type: 'hook.list',
       description:
-        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map — hook names, brief entries, or full HookDoc per entry.",
+        "The catalog grouped by category. data.detail is the level ('names' | 'compact' | 'full') and data.components is the grouped map: hook names, brief entries, or full HookDoc per entry.",
     },
     {
       type: 'hook.detail',

package/api/init/init.doc.mjs

@@ -69,7 +69,7 @@ export const doc = {
     {
       type: 'init.remove',
       description:
-        'Confirmation that the managed agent-docs block was removed (`data.removed: true`) — returned when `removeAgents` is set.',
+        'Confirmation that the managed agent-docs block was removed (`data.removed: true`), returned when `removeAgents` is set.',
     },
   ],
   throws: [

package/api/integration/summarizeIssues.doc.mjs

@@ -17,7 +17,7 @@ export const doc = {
     'Tally integration issues by severity into error and warning counts.',
   description:
     'A synchronous helper that reduces an AstryxIntegrationIssue[] (as returned ' +
-    'by validateIntegration) to counts of errors and warnings — the seam a ' +
+    'by validateIntegration) to counts of errors and warnings: the seam a ' +
     'caller uses to decide an exit code or print a summary line. Issues of any ' +
     'other severity are ignored.',
   importPath: '@astryxdesign/cli/api',

package/api/integration/validateIntegration.doc.mjs

@@ -45,7 +45,7 @@ export const doc = {
     {
       type: 'integration.validate',
       description:
-        'The result envelope: `data.name` and `data.version` of the validated package (both null when no local manifest is found), plus `data.issues` — an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
+        'The result envelope: `data.name` and `data.version` of the validated package (both null when no local manifest is found), plus `data.issues`, an AstryxIntegrationIssue[] of {code, severity: `warning` | `error`, message}.',
     },
   ],
   examples: [

package/api/json/assertResponse.doc.mjs

@@ -27,7 +27,7 @@ export const doc = {
       name: 'raw',
       type: 'unknown',
       description:
-        'The CLI stdout to parse — a JSON string, or an object that was already parsed.',
+        'The CLI stdout to parse: a JSON string, or an object that was already parsed.',
       required: true,
     },
     {
@@ -42,7 +42,7 @@ export const doc = {
     {
       type: 'any',
       description:
-        'The parsed envelope, guaranteed at runtime to carry the requested `type`. The published signature is untyped — cast to the matching *Response type for typed access.',
+        'The parsed envelope, guaranteed at runtime to carry the requested `type`. The published signature is untyped; cast to the matching *Response type for typed access.',
     },
   ],
   throws: [

package/api/json/isError.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   displayName: 'isError()',
   summary: 'Did the CLI return an error envelope?',
   description:
-    'Tests a parsed response for an `error` key. Branch on this before touching `data` — ' +
+    'Tests a parsed response for an `error` key. Branch on this before touching `data`: ' +
     'and prefer the stable `code` field over matching the human-readable message, which is ' +
     'not a contract. Note this returns a plain boolean, not a TypeScript type predicate, so ' +
     'it does not narrow on its own: cast to the matching *Response type to get typed access.',

package/api/json/parseResponse.doc.mjs

@@ -26,7 +26,7 @@ export const doc = {
       name: 'raw',
       type: 'unknown',
       description:
-        'The CLI stdout to parse — a JSON string, or an object that was already parsed.',
+        'The CLI stdout to parse: a JSON string, or an object that was already parsed.',
       required: true,
     },
   ],
@@ -34,7 +34,7 @@ export const doc = {
     {
       type: 'any',
       description:
-        'The { type, data, meta? } envelope, or a CLIError envelope. The published signature is intentionally untyped — narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
+        'The { type, data, meta? } envelope, or a CLIError envelope. The published signature is intentionally untyped; narrow it by casting to the matching *Response type exported from @astryxdesign/cli/json.',
     },
   ],
   throws: [

package/api/layout/layoutCheck.doc.mjs

@@ -18,7 +18,7 @@ export const doc = {
     'The validator behind `astryx layout check`. Parses and validates a compressed XLE/XLO ' +
     'expression without generating any TSX, and echoes it back in both canonical surfaces ' +
     '(compact and outline). Validation failures are reported in the layout.check envelope ' +
-    '(valid: false) with line/col and suggestions — not thrown — so callers can lint an ' +
+    '(valid: false) with line/col and suggestions (not thrown) so callers can lint an ' +
     'expression and surface fixes.',
   importPath: '@astryxdesign/cli/api',
   signature:

package/api/layout/layoutExpand.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   summary: 'Expand a validated layout expression into XDS TSX.',
   description:
     'The generator behind `astryx layout expand`. Parses and validates a compressed XLE/XLO ' +
-    'expression, then expands it into ready-to-use XDS TSX — auto-routing structural children ' +
+    'expression, then expands it into ready-to-use XDS TSX, auto-routing structural children ' +
     'into the right slots, scaffolding typed useState for interactive controls, and splicing or ' +
     'importing any referenced template blocks. Returns the code (and metadata) in a layout.expand ' +
     'envelope, optionally writing it to a path within cwd.',

package/api/layout/layoutGrammar.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   displayName: 'layoutGrammar()',
   summary: 'Return the XLE/XLO grammar cheatsheet for this install.',
   description:
-    'The reference behind `astryx layout grammar` — the agent cheatsheet for writing XLE/XLO ' +
+    'The reference behind `astryx layout grammar`: the agent cheatsheet for writing XLE/XLO ' +
     "layout expressions, with the alias table generated from this branch's registry rather than " +
     'hand-maintained, so short names always reflect the components actually installed.',
   importPath: '@astryxdesign/cli/api',

package/api/swizzle/swizzle.doc.mjs

@@ -88,7 +88,7 @@ export const doc = {
     },
     {
       code: 'ERR_AMBIGUOUS_COMPONENT',
-      when: 'more than one package provides the component — choose one with package',
+      when: 'more than one package provides the component; choose one with package',
     },
     {
       code: 'ERR_NO_SOURCE',

package/api/theme/listThemes.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   displayName: 'listThemes()',
   summary: 'Read the bundled-theme manifest and return its raw entries.',
   description:
-    "The shared data layer behind theme list/add — reads the CLI's bundled-theme manifest " +
+    "The shared data layer behind theme list/add: reads the CLI's bundled-theme manifest " +
     '(templates/themes/manifest.json, generated by scripts/generate-cli-themes.mjs) and returns ' +
     'the parsed entries. themeList() projects this into the theme.list envelope; themeAdd() ' +
     'resolves a slug against it. Returns synchronously.',
@@ -28,7 +28,7 @@ export const doc = {
     {
       type: 'BundledTheme[]',
       description:
-        'The parsed themes array from the bundle manifest — each BundledTheme has slug, displayName, description, maintained, entry, exportName, and files. Empty when the manifest has not been generated.',
+        'The parsed themes array from the bundle manifest: each BundledTheme has slug, displayName, description, maintained, entry, exportName, and files. Empty when the manifest has not been generated.',
     },
   ],
   throws: [

package/api/theme/themeAdd.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   summary: 'Scaffold a bundled theme into a project as editable source.',
   description:
     "Copies a bundled theme's source (from the CLI's templates/themes/<slug>) into the " +
-    "consumer's project so they own it — no theme package needed. Writes are staged to temp " +
+    "consumer's project so they own it, no theme package needed. Writes are staged to temp " +
     'files then renamed, rolling back partials on failure so a failed write never leaves a ' +
     'half-written theme. Returns a theme.add receipt describing where the files landed and how ' +
     'to import them.',

package/api/theme/themeBuild.doc.mjs

@@ -20,7 +20,7 @@ export const doc = {
     'emits the exact CSS the <Theme> runtime does), writes a scoped CSS file, a JS module ' +
     'that re-exports the built theme, and a .d.ts (plus an optional .variants.d.ts when the ' +
     'theme adds custom prop values). With {check: true} it writes nothing and instead compares ' +
-    'each output against disk, returning the drift — the CI guard for committed, generated theme CSS.',
+    'each output against disk, returning the drift: the CI guard for committed, generated theme CSS.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'themeBuild(file: string, options?: {out?: string, check?: boolean}, ctx?: {cwd?: string}): Promise<ThemeBuildResponse | ThemeBuildCheckResponse | null>',
@@ -51,7 +51,7 @@ export const doc = {
       name: 'options.check',
       type: 'boolean',
       description:
-        'Compile in memory and compare each output against what is on disk instead of writing — the CI drift guard.',
+        'Compile in memory and compare each output against what is on disk instead of writing: the CI drift guard.',
       default: 'false',
     },
     {
@@ -86,7 +86,7 @@ export const doc = {
     },
     {
       code: 'ERR_CORE_NOT_FOUND',
-      when: '@astryxdesign/core/theme cannot be imported — a built, resolvable @astryxdesign/core is required',
+      when: '@astryxdesign/core/theme cannot be imported; a built, resolvable @astryxdesign/core is required',
     },
     {
       code: 'ERR_WRITE_FAILED',

package/api/theme/themeList.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   displayName: 'themeList()',
   summary: 'List the themes bundled with this CLI build.',
   description:
-    'Projects the bundled-theme manifest into the theme.list envelope — the themes that themeAdd ' +
+    'Projects the bundled-theme manifest into the theme.list envelope: the themes that themeAdd ' +
     'can scaffold. A pure projection of the manifest read by listThemes(); no I/O beyond that read, ' +
     'and it returns synchronously.',
   importPath: '@astryxdesign/cli/api',
@@ -26,7 +26,7 @@ export const doc = {
     {
       type: 'theme.list',
       description:
-        'Every bundled theme as a ThemeListEntry[] — each entry has slug, displayName, description, and a maintained flag.',
+        'Every bundled theme as a ThemeListEntry[]: each entry has slug, displayName, description, and a maintained flag.',
     },
   ],
   throws: [

package/api/upgrade/upgrade.doc.mjs

@@ -86,7 +86,7 @@ export const doc = {
     {
       type: 'upgrade.list',
       description:
-        'Every available codemod, oldest→newest, as {name, title, version, optional} — returned when `list` is set; nothing is run.',
+        'Every available codemod, oldest→newest, as {name, title, version, optional}, returned when `list` is set; nothing is run.',
     },
     {
       type: 'upgrade.status',

package/assets/docs/browser-support.doc.mjs

@@ -15,7 +15,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Astryx is built on modern web platform features: the Popover API, CSS anchor positioning, and CSS `light-dark()`. These let components stay small, accessible, and dependency-free, but they also set a floor on which browsers render everything correctly.',
+          text: 'Astryx is built on modern web platform features: the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API, CSS anchor positioning, and CSS `light-dark()`. These let components stay small, accessible, and dependency-free, but they also set a floor on which browsers render everything correctly.',
         },
         {
           type: 'prose',
@@ -73,7 +73,7 @@ export const docs = {
               'Baseline 2026: the tightest requirement.',
             ],
             [
-              'Popover API',
+              '[`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API',
               'Opens, stacks, and light-dismisses layered surfaces via the top layer.',
               'Baseline 2025.',
             ],
@@ -86,7 +86,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'The gap that matters is between Tier 1 and Tier 2: the Popover API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.',
+          text: 'The gap that matters is between Tier 1 and Tier 2: the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API and `light-dark()` reached wide availability well before anchor positioning. So in Tier 2 browsers, layered surfaces open and dismiss correctly; they just are not positioned. This is the one feature most consumers will need to reason about.',
         },
       ],
     },
@@ -112,7 +112,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'If your product does not use any of these, it has no anchor-positioning requirement at all; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Layout, typography, forms, buttons, cards, tables, and navigation all work down to Tier 2 with no special handling.',
+          text: 'If your product does not use any of these, it has no anchor-positioning requirement at all; it needs only `light-dark()` (Tier 2 and up) for correct theme colors. Page layout, typography, forms, buttons, cards, tables, and navigation all work down to Tier 2 with no special handling.',
         },
       ],
     },
@@ -123,7 +123,7 @@ export const docs = {
           type: 'list',
           style: 'do',
           items: [
-            'Components never throw on missing platform APIs. Where a browser lacks the Popover API, layers fall back to plain visibility instead of crashing.',
+            'Components never throw on missing platform APIs. Where a browser lacks the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API, layers fall back to plain visibility instead of crashing.',
             'Tier 1 and Tier 2 are officially supported and tested.',
             'Non-layered components render correctly down to Tier 2.',
           ],
@@ -192,7 +192,7 @@ const hasLightDark = CSS.supports('color', 'light-dark(#000, #fff)');`,
         },
         {
           type: 'prose',
-          text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the Popover API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
+          text: 'This is not an arbitrary window: Baseline − 2 is close to where anchor positioning stops being available while the [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) API and `light-dark()` still are, so the tier boundary tracks a real capability edge, not a guessed date. The version floors above are reviewed and advanced roughly once a year as new Baseline years land. Always feature-detect rather than hardcoding version numbers, so your app adapts automatically as the platform moves.',
         },
       ],
     },

package/assets/docs/icons.doc.mjs

@@ -114,9 +114,9 @@ export const brandTheme = defineTheme({
           type: 'list',
           style: 'ordered',
           items: [
-            'Add the name to IconName type in packages/core/src/Icon/globalIconRegistry.tsx',
-            'Add the default SVG to packages/core/src/Icon/defaultIcons.tsx',
-            'Add a row to the Available Names table in packages/cli/docs/icons.doc.mjs',
+            'Add the name to IconName type in `packages/core/src/Icon/globalIconRegistry.tsx`',
+            'Add the default SVG to `packages/core/src/Icon/defaultIcons.tsx`',
+            'Add a row to the Available Names table in `packages/cli/assets/docs/icons.doc.mjs`',
           ],
         },
       ],

package/assets/docs/illustrations.doc.mjs

@@ -40,7 +40,7 @@ export const docs = {
             'Keep illustrations consistent in style across the product.',
             'Use simple, flat illustrations that work in both light and dark mode.',
             'Size illustrations proportionally to the container, typically 120\u2013240px.',
-            'Center illustrations with supporting text below.',
+            'Place illustrations centered with supporting text below.',
           ],
         },
         {
@@ -59,7 +59,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'Center illustrations inside Center with supporting text stacked below. Typical illustration sizes range from 120px for inline empty states to 240px for full-page onboarding screens. Always pair the illustration with a heading and optional body text to explain what the user should do next.',
+          text: 'Place illustrations inside Center with supporting text stacked below. Typical illustration sizes range from 120px for inline empty states to 240px for full-page onboarding screens. Always pair the illustration with a heading and optional body text to explain what the user should do next.',
         },
         {
           type: 'code',

package/assets/docs/internationalization.doc.mjs

@@ -300,7 +300,7 @@ export default function App() {
       content: [
         {
           type: 'prose',
-          text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Switch to it in development to catch hardcoded astryx strings and layout issues caused by longer text.',
+          text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Turn it on in development to catch hardcoded astryx strings and layout issues caused by longer text.',
         },
         {
           type: 'code',

package/assets/docs/migration.doc.mjs

@@ -350,7 +350,7 @@ if (getComputedStyle(button).paddingInline === '0px') {
             'Run the app in light and dark mode and check that surfaces, borders, text, icons, hover states, focus rings, and status colors flow together.',
             'Open the command palette from the shell, type into it, select items by keyboard, and confirm focus returns to the trigger.',
             'Check the SideNav at collapsed, expanded, active, hover, nested, and mobile states.',
-            'Verify settings popovers and dialogs in jsdom and in a real browser because native dialog and Popover APIs may need test shims.',
+            'Verify settings popovers and dialogs in jsdom and in a real browser because the native dialog and [`Popover`](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) APIs may need test shims.',
             'Search for leftover hardcoded Tailwind colors, arbitrary hex values, and one-off hover colors after each route migration.',
             'Run component tests, build, and at least one browser screenshot pass for each migrated route.',
           ],

package/assets/docs/principles.doc.mjs

@@ -39,7 +39,7 @@ export const docs = {
           style: 'ordered',
           items: [
             'Use components for everything they cover',
-            'Layout is frame-first: pick the shell and budget regions before writing content (see \`astryx docs layout\`)',
+            'Page layout is frame-first: pick the shell and budget regions before writing content (see \`astryx docs layout\`)',
             'Dense data renders as rows (Table, List/Item), edge-to-edge with dividers; Card is for widgets, galleries, and settings groups',
             'StyleX or Tailwind for custom styling; both are first-class (see \`astryx docs styling\`)',
             'Semantic tokens, not hardcoded values (see \`astryx docs tokens\`)',

package/assets/docs/styling-libraries.doc.mjs

@@ -56,7 +56,7 @@ export const docs = {
               '`@astryxdesign/core/tailwind-theme.css`',
             ],
             [
-              'Token resolver APIs',
+              'Design token resolver APIs',
               'JavaScript needs token values for charts, canvas, SVG, or config objects',
               "`resolveThemeToken(theme, '--color-data-categorical-blue', {mode})`",
             ],

package/assets/docs/styling.doc.mjs

@@ -22,10 +22,10 @@ export const docs = {
           type: 'table',
           headers: ['Approach', 'Use for', 'Example'],
           rows: [
-            ['StyleX', 'Component-specific overrides, reusable styles, pseudo-classes, and typed tokens', 'const styles = stylex.create(...); <Button xstyle={styles.save} />'],
-            ['Tailwind utilities', 'Layout, wrappers, and utility styling', 'className="flex gap-3 p-4"'],
-            ['className', 'Integrating with external CSS or Tailwind on components', 'className="my-card shadow-lg"'],
-            ['Styling-library token aliases', 'Keeping Panda, Chakra, MUI, Emotion, styled-components, UnoCSS, CSS Modules, or Sass in sync with the system', "colors.surface = 'var(--color-background-surface)'"],
+            ['StyleX', 'Component-specific overrides, reusable styles, pseudo-classes, and typed tokens', '`const styles = stylex.create(...); <Button xstyle={styles.save} />`'],
+            ['Tailwind utilities', 'Page layout, wrappers, and utility styling', '`className="flex gap-3 p-4"`'],
+            ['className', 'Integrating with external CSS or Tailwind on components', '`className="my-card shadow-lg"`'],
+            ['Styling-library token aliases', 'Keeping Panda, Chakra, MUI, Emotion, styled-components, UnoCSS, CSS Modules, or Sass in sync with the system', "`colors.surface = 'var(--color-background-surface)'`"],
           ],
         },
         {

package/assets/docs/theme.doc.mjs

@@ -106,7 +106,7 @@ function App() {
             [
               'Y2K',
               "import {y2kTheme} from '@astryxdesign/theme-y2k'",
-              'Playful Y2K pop; periwinkle body, holographic accents, Poppins + Crimson Text.',
+              'Playful Y2K pop; periwinkle body, holographic accents, Poppins + `Crimson Text`.',
             ],
           ],
         },
@@ -510,7 +510,7 @@ import './themes/ocean.css';
       content: [
         {
           type: 'prose',
-          text: 'Wrap different sections in separate <Theme> providers.',
+          text: 'Wrap different sections in separate [`<Theme>`](/components/Theme) providers.',
         },
         {
           type: 'code',
@@ -606,7 +606,7 @@ function ChartConfig() {
         },
         {
           type: 'prose',
-          text: 'Prefer CSS variables, StyleX token imports, xstyle, or className for ordinary styling. To change the theme or mode, manage state at the app level and pass it to <Theme>.',
+          text: 'Prefer CSS variables, StyleX token imports, xstyle, or className for ordinary styling. To change the theme or mode, manage state at the app level and pass it to `<Theme>`.',
         },
         {
           type: 'prose',

package/assets/docs/typography.doc.mjs

@@ -122,7 +122,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Display text often needs heading semantics for accessibility. Use the type prop on Heading to apply display styling while preserving the correct HTML element: <Heading level={1} type="display-1"> gives you display-1 styling with an <h1> tag, so screen readers see the correct document outline.',
+          text: 'Display text often needs heading semantics for accessibility. Use the type prop on Heading to apply display styling while preserving the correct HTML element: `<Heading level={1} type="display-1">` gives you display-1 styling with an `<h1>` tag, so screen readers see the correct document outline.',
         },
       ],
     },
@@ -205,7 +205,7 @@ const denseTheme = defineTheme({
           items: [
             'Use Heading for document headings and Text for everything else; they apply the full type scale automatically.',
             'Adjust typography holistically: change base and ratio in defineTheme to shift the entire ramp (e.g. { base: 16, ratio: 1.25 } for editorial, { base: 12, ratio: 1.125 } for dense UI).',
-            'Use display types with as="h1" (or h2/h3) when display text is a page heading; this preserves accessibility while giving you display-level sizing. Or better, use <Heading level={1} type="display-1"> which handles both semantics and styling.',
+            'Use display types with as="h1" (or h2/h3) when display text is a page heading; this preserves accessibility while giving you display-level sizing. Or better, use `<Heading level={1} type="display-1">` which handles both semantics and styling.',
             'Let line-height snap to the 4px grid via the type scale; expandTypeScale computes leading automatically from base and ratio.',
             'Use the supporting type for secondary information: timestamps, helper text, metadata, captions.',
             'Use accessibilityLevel on Heading when the visual hierarchy doesn\u0027t match the document outline (e.g. sidebar or card headings).',

package/authoring/codemod/codemod.doc.mjs

@@ -42,7 +42,7 @@ export const doc = {
       name: 'fileExtensions',
       type: 'string[]',
       description:
-        'File extensions this codemod applies to. Code codemods only — a ' +
+        'File extensions this codemod applies to. Code codemods only; a ' +
         'config codemod always targets astryx.config.*.',
       example: "['.tsx', '.ts']",
     },
@@ -140,7 +140,7 @@ export const doc = {
       type: 'prose',
       text:
         "The config-codemod variant (type: 'config') carries the same fields " +
-        'as a code codemod except fileExtensions — it always targets the ' +
+        'as a code codemod except fileExtensions: it always targets the ' +
         'astryx.config.* file rather than a set of source files.',
     },
     {

package/authoring/config/config.doc.mjs

@@ -46,7 +46,7 @@ export const doc = {
     {
       name: 'experimental',
       type: '{ xle?: { components?: Record<string, XleComponent> } }',
-      description: 'Unstable features — may change without a breaking bump.',
+      description: 'Unstable features; may change without a breaking bump.',
       fields: [
         {
           name: 'experimental.xle.components',

package/authoring/doctypes/command/command.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   displayName: 'CommandDoc',
   namespace: 'authoring',
   description:
-    'The doc-type for a CLI command — the terminal binding of an operation. A command ' +
+    'The doc-type for a CLI command: the terminal binding of an operation. A command ' +
     'is not its own behavior; it is a FunctionDoc exposed on the CLI, referenced via `fn`, ' +
     'carrying only CLI-surface facts (args, flags, subcommands, examples, exit codes). ' +
     'A `defineCommand` converter turns it into Commander config + `--help`.',
@@ -231,7 +231,7 @@ export const doc = {
   notes: [
     {
       type: 'prose',
-      text: 'A command carries only CLI-surface facts. Behavior, parameters, returns, and thrown errors live in the FunctionDoc it points at via `fn` — the function does not know it has a CLI.',
+      text: 'A command carries only CLI-surface facts. Behavior, parameters, returns, and thrown errors live in the FunctionDoc it points at via `fn`; the function does not know it has a CLI.',
     },
     {
       type: 'prose',

package/authoring/doctypes/component/component.doc.mjs

@@ -50,7 +50,7 @@ export const doc = {
       name: 'hiddenComponents',
       type: 'string[]',
       description:
-        'Sub-component names to hide from human-facing UI (CLI listings, docs catalogs). They stay public and importable — agents and tooling can still discover them via source.',
+        'Sub-component names to hide from human-facing UI (CLI listings, docs catalogs). They stay public and importable; agents and tooling can still discover them via source.',
     },
     {
       name: 'hidden',
@@ -104,7 +104,7 @@ export const doc = {
           name: 'theming.derived',
           type: 'ComponentThemingDerivedVar[]',
           description:
-            'Maps standard CSS properties to internal vars for theme-pipeline expansion. Ordered by priority — earlier entries emit first.',
+            'Maps standard CSS properties to internal vars for theme-pipeline expansion. Ordered by priority: earlier entries emit first.',
         },
       ],
     },
@@ -170,7 +170,7 @@ export const doc = {
       name: 'description',
       type: 'string',
       description:
-        "SubComponentDoc variant (required there): one-sentence description of the sub-component's role within the parent composition. Single/Multi docs have no top-level description — they derive their summary from `usage`.",
+        "SubComponentDoc variant (required there): one-sentence description of the sub-component's role within the parent composition. Single/Multi docs have no top-level description; they derive their summary from `usage`.",
     },
   ],
   examples: [
@@ -187,7 +187,7 @@ export const docs = {
       'A Switch toggles a single setting on or off. Use it for instant, binary preferences that apply immediately without a submit step.',
     bestPractices: [
       {guidance: true, description: 'Apply the change immediately when toggled.'},
-      {guidance: false, description: 'Use a Switch for actions that need confirmation — prefer a Checkbox in a form.'},
+      {guidance: false, description: 'Use a Switch for actions that need confirmation; prefer a Checkbox in a form.'},
     ],
   },
   props: [
@@ -226,9 +226,9 @@ export const docs = {
       type: 'list',
       style: 'unordered',
       items: [
-        'SingleComponentDoc — one primary component; put props directly on the doc via `props`. Use for Switch, Badge, Spinner, TextInput.',
-        'MultiComponentDoc — a directory exporting several components/hooks; list them in `components` (inline ComponentEntry or name-only ComponentRef). Use for Table, Dialog, TabList.',
-        'SubComponentDoc — a single sub-component in its own {Name}.doc.mjs inside the parent directory; set `subComponentOf` to the parent name. It inherits family fields and may omit `usage`.',
+        'SingleComponentDoc: one primary component; put props directly on the doc via `props`. Use for Switch, Badge, Spinner, TextInput.',
+        'MultiComponentDoc: a directory exporting several components/hooks; list them in `components` (inline ComponentEntry or name-only ComponentRef). Use for Table, Dialog, TabList.',
+        'SubComponentDoc: a single sub-component in its own {Name}.doc.mjs inside the parent directory; set `subComponentOf` to the parent name. It inherits family fields and may omit `usage`.',
       ],
     },
     {

package/authoring/doctypes/enum/enum.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   displayName: 'EnumDoc',
   namespace: 'authoring',
   description:
-    'The doc-type for a closed vocabulary — a fixed set of literal values such as ' +
+    'The doc-type for a closed vocabulary: a fixed set of literal values such as ' +
     'error codes or response-type discriminants. Colocated as a `.doc.mjs` next to ' +
     'the source of truth it documents.',
   appliesTo: '<enum>.doc.mjs',
@@ -59,7 +59,7 @@ export const doc = {
     {
       name: 'members',
       type: 'EnumMemberDoc[]',
-      description: 'The enumerated members — one entry per literal value.',
+      description: 'The enumerated members: one entry per literal value.',
       required: true,
       fields: [
         {

package/authoring/doctypes/function/function.doc.mjs

@@ -41,7 +41,7 @@ export const doc = {
       name: 'kind',
       type: "'hook' | 'api'",
       description:
-        'Which flavor — drives docsite sectioning; inferred from importPath if omitted.',
+        'Which flavor; drives docsite sectioning; inferred from importPath if omitted.',
     },
     {
       name: 'summary',
@@ -127,7 +127,7 @@ export const doc = {
         {
           name: 'returns[].name',
           type: 'string',
-          description: 'Field name (hooks) — omit for API envelope entries.',
+          description: 'Field name (hooks); omit for API envelope entries.',
         },
         {
           name: 'returns[].type',
@@ -191,7 +191,7 @@ export const doc = {
       name: 'usage',
       type: 'UsageDoc',
       description:
-        'Usage documentation (hooks) — description, best practices, anatomy. Same shape as HookDoc.usage.',
+        'Usage documentation (hooks): description, best practices, anatomy. Same shape as HookDoc.usage.',
     },
     {
       name: 'command',

package/authoring/doctypes/hook/hook.doc.mjs

@@ -43,7 +43,7 @@ export const doc = {
       name: 'group',
       type: 'string',
       description:
-        'Optional group for sidebar/docs organization — same as ComponentDoc.group.',
+        'Optional group for sidebar/docs organization; same as ComponentDoc.group.',
     },
     {
       name: 'keywords',
@@ -117,7 +117,7 @@ export const doc = {
     {
       name: 'usage',
       type: 'UsageDoc',
-      description: 'Usage documentation — description and best practices.',
+      description: 'Usage documentation: description and best practices.',
       required: true,
       fields: [
         {
@@ -190,7 +190,7 @@ export const docs = {
   notes: [
     {
       type: 'prose',
-      text: "A hook's discriminant is `type: 'function'` — HookDoc and FunctionDoc share the generalized function kind. HookDoc is the hook-flavored view: named `returns` fields and a required `usage` block.",
+      text: "A hook's discriminant is `type: 'function'`: HookDoc and FunctionDoc share the generalized function kind. HookDoc is the hook-flavored view: named `returns` fields and a required `usage` block.",
     },
     {
       type: 'prose',

package/authoring/doctypes/reference/reference.doc.mjs

@@ -14,7 +14,7 @@ export const doc = {
   displayName: 'ReferenceDoc',
   namespace: 'authoring',
   description:
-    'The doc-type for a reference/topic doc — tokens, principles, theming, patterns, ' +
+    'The doc-type for a reference/topic doc: tokens, principles, theming, patterns, ' +
     'accessibility, migration guides. Unlike ComponentDoc it is not tied to a component: ' +
     'drop a `.doc.mjs` in the docs directory and it shows up in `astryx docs`. Content is ' +
     'built from ordered sections of mixed content blocks.',
@@ -120,7 +120,7 @@ export const docs = {
   notes: [
     {
       type: 'prose',
-      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock — a discriminated union. New block types can be added without breaking existing docs. The same union is reused by the `notes` field on SchemaDoc and CommandDoc.',
+      text: 'Each `sections[].content` is an ordered array of ReferenceContentBlock, a discriminated union. New block types can be added without breaking existing docs. The same union is reused by the `notes` field on SchemaDoc and CommandDoc.',
     },
     {
       type: 'code',
@@ -140,7 +140,7 @@ export const docs = {
     },
     {
       type: 'prose',
-      text: "A section may set `previewType` to render a visual preview column for token tables — one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'.",
+      text: "A section may set `previewType` to render a visual preview column for token tables: one of 'swatch' | 'shadow-box' | 'radius-box' | 'spacing-bar' | 'size-bar' | 'border-line' | 'duration-bar' | 'easing-curve' | 'font-sample'.",
     },
   ],
 };

package/authoring/doctypes/schema/schema.doc.mjs

@@ -190,7 +190,7 @@ export const doc = {
       type: 'list',
       style: 'dont',
       items: [
-        'Set `required: false` for optional fields — omit `required` entirely instead.',
+        'Set `required: false` for optional fields; omit `required` entirely instead.',
       ],
     },
   ],

package/authoring/doctypes/template/template.doc.mjs

@@ -150,13 +150,13 @@ export const doc = {
       type: 'list',
       style: 'unordered',
       items: [
-        "PageTemplateDoc (type: 'page') — a full page template; `name` doubles as its display value.",
-        "BlockTemplateDoc (type: 'block') — an example of a component; requires `exampleFor` and `aspectRatio`.",
+        "PageTemplateDoc (type: 'page'): a full page template; `name` doubles as its display value.",
+        "BlockTemplateDoc (type: 'block'): an example of a component; requires `exampleFor` and `aspectRatio`.",
       ],
     },
     {
       type: 'prose',
-      text: "`category` uses the shared TemplateCategory taxonomy: 'Group - Variant' strings (e.g. 'Table - Bulk Actions'). Not every value maps to an existing template — unused values are reserved so authors get autocomplete for the full taxonomy.",
+      text: "`category` uses the shared TemplateCategory taxonomy: 'Group - Variant' strings (e.g. 'Table - Bulk Actions'). Not every value maps to an existing template; unused values are reserved so authors get autocomplete for the full taxonomy.",
     },
   ],
 };

package/clients/cli/commands/build.doc.mjs

@@ -17,7 +17,7 @@ export const doc = {
     'Build a page: composition kit for an idea, or the workflow playbook (no args)',
   description:
     'The assemble-a-page entry point. With no query it returns the how-to-build-a-page ' +
-    'playbook; with a query it groups the unified search hits into a composition kit — ' +
+    'playbook; with a query it groups the unified search hits into a composition kit: ' +
     'the closest templates, drop-in blocks, and idea-specific components and hooks.',
   fn: 'build',
   args: [{name: 'query', param: 'query', required: false}],

package/clients/cli/commands/component.doc.mjs

@@ -69,7 +69,7 @@ export const doc = {
     {code: 0, when: 'success'},
     {
       code: 1,
-      when: 'unknown component, category, or package — or @astryxdesign/core cannot be resolved',
+      when: 'unknown component, category, or package, or @astryxdesign/core cannot be resolved',
     },
   ],
   related: ['search', 'hook', 'docs', 'template', 'swizzle'],

package/clients/cli/commands/doctor.doc.mjs

@@ -15,8 +15,8 @@ export const doc = {
   namespace: 'cli',
   summary: 'Diagnose your XDS setup and report problems with fixes',
   description:
-    'Runs read-only diagnostics — Node version, @astryxdesign/core install and version ' +
-    'alignment, installed themes, config validity, agent docs, and the package manager — ' +
+    'Runs read-only diagnostics: Node version, @astryxdesign/core install and version ' +
+    'alignment, installed themes, config validity, agent docs, and the package manager, ' +
     'and reports pass/warn/fail with an actionable fix for each problem. Safe as a CI gate.',
   fn: 'doctor',
   examples: [

package/clients/cli/commands/layout-expand.doc.mjs

@@ -17,7 +17,7 @@ export const doc = {
   summary: 'Expand a layout expression into validated XDS TSX',
   description:
     'Parses and validates a compressed XLE/XLO expression, then expands it into ' +
-    'ready-to-use XDS TSX — routing children into slots, scaffolding typed useState for ' +
+    'ready-to-use XDS TSX, routing children into slots, scaffolding typed useState for ' +
     'interactive controls, and splicing referenced blocks. Writes to a path, or returns the code.',
   fn: 'layoutExpand',
   args: [

package/clients/cli/commands/layout.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   summary: 'Generate XDS layouts from compressed expressions (XLE/XLO)',
   description:
     'The layout command group. Running astryx layout with no subcommand prints the ' +
-    'subcommand list; the work happens in the subcommands — expand an expression into ' +
+    'subcommand list; the work happens in the subcommands: expand an expression into ' +
     'TSX (expand), validate one (check), or print the grammar cheatsheet (grammar).',
   subcommands: ['expand', 'check', 'grammar'],
   examples: [

package/clients/cli/commands/manifest.doc.mjs

@@ -3,7 +3,7 @@
 /**
  * @file CommandDoc for `astryx manifest`. A CLI-only capability manifest with no
  * wrapped API function (so no `fn`); it emits the full command surface — args,
- * flags, subcommands, and JSON response types — as a single typed envelope.
+ * flags, subcommands, and JSON response types, as a single typed envelope.
  * @position packages/cli/clients/cli/commands — command documentation
  */
 
@@ -15,8 +15,8 @@ export const doc = {
   namespace: 'cli',
   summary: 'Print the full CLI capability manifest (use with --json).',
   description:
-    'Emits the complete CLI surface — every command with its arguments, options, ' +
-    'subcommands, and JSON response types — as a single typed envelope for agents and ' +
+    'Emits the complete CLI surface: every command with its arguments, options, ' +
+    'subcommands, and JSON response types, as a single typed envelope for agents and ' +
     'tooling to introspect. Intended to be run with --json.',
   examples: [
     {label: 'Full manifest', cli: 'astryx manifest --json'},

package/clients/cli/commands/search.doc.mjs

@@ -15,7 +15,7 @@ export const doc = {
   namespace: 'cli',
   summary: 'Search components, hooks, docs, and templates in one ranked list',
   description:
-    'Terminal front-end to search() — prints one ranked, greppable list across ' +
+    'Terminal front-end to search(): prints one ranked, greppable list across ' +
     'every content domain, each row carrying a follow-up command to act on it.',
   fn: 'search',
   args: [{name: 'query', param: 'query', required: true}],

package/clients/cli/commands/theme-add.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   namespace: 'cli',
   summary: 'Scaffold a theme into your project as editable source',
   description:
-    "Copies a bundled theme's source into your project so you own it — no theme package " +
+    "Copies a bundled theme's source into your project so you own it, no theme package " +
     'needed. Writes are staged then renamed, rolling back on failure. Running it with no ' +
     'slug, or with --list, lists the bundled themes instead.',
   fn: 'themeAdd',

package/clients/cli/commands/theme-build.doc.mjs

@@ -17,7 +17,7 @@ export const doc = {
   summary: 'Compile a defineTheme file to CSS + JS',
   description:
     'Compiles a file that calls defineTheme() into a scoped CSS file, a JS module, and ' +
-    'type declarations — the exact CSS the <Theme> runtime emits. With --check it writes ' +
+    'type declarations: the exact CSS the <Theme> runtime emits. With --check it writes ' +
     'nothing and instead reports whether the committed outputs have drifted from source.',
   fn: 'themeBuild',
   args: [{name: 'file', param: 'file', required: true}],

package/clients/cli/commands/theme-list.doc.mjs

@@ -16,7 +16,7 @@ export const doc = {
   namespace: 'cli',
   summary: 'List themes available to add',
   description:
-    'Lists the themes bundled with this CLI build — the ones theme add can scaffold — ' +
+    'Lists the themes bundled with this CLI build (the ones theme add can scaffold), ' +
     'each with its slug, display name, description, and maintained flag.',
   fn: 'themeList',
   examples: [{label: 'List bundled themes', cli: 'astryx theme list --json'}],

package/clients/cli/commands/theme.doc.mjs

@@ -13,10 +13,10 @@ export const doc = {
   name: 'theme',
   displayName: 'astryx theme',
   namespace: 'cli',
-  summary: 'Theme tools — build, export, and manage themes',
+  summary: 'Theme tools: build, export, and manage themes',
   description:
     'The theme command group. Running astryx theme with no subcommand prints the ' +
-    'subcommand list; the work happens in the subcommands — compile a theme (build), ' +
+    'subcommand list; the work happens in the subcommands: compile a theme (build), ' +
     'scaffold one into your project (add), or list the bundled themes (list).',
   subcommands: ['build', 'add', 'list'],
   examples: [

package/clients/cli/commands/validate-integration.doc.mjs

@@ -16,8 +16,8 @@ export const doc = {
   namespace: 'cli',
   summary: 'Validate an Astryx integration package (manifest + contributions)',
   description:
-    'Validates ONE integration at a time — the local package rooted at cwd, or an ' +
-    'installed package resolved by name — schema-checking its manifest, verifying each ' +
+    'Validates ONE integration at a time: the local package rooted at cwd, or an ' +
+    'installed package resolved by name, schema-checking its manifest, verifying each ' +
     'declared contribution root, and reporting every finding. Safe as a CI gate.',
   fn: 'validateIntegration',
   args: [{name: 'package', param: 'pkg', required: false}],

package/foundation/response/response-types.doc.mjs

@@ -21,7 +21,7 @@ export const doc = {
     {
       value: 'component.list',
       description:
-        'The component catalog grouped by category: `detail` (the level — names | compact | full) and `components`, the grouped map of names+package, brief entries, or a full ComponentDoc per entry.',
+        'The component catalog grouped by category: `detail` (the level: names | compact | full) and `components`, the grouped map of names+package, brief entries, or a full ComponentDoc per entry.',
     },
     {
       value: 'component.detail',
@@ -61,14 +61,14 @@ export const doc = {
     {
       value: 'docs.detail.section',
       description:
-        'A single ReferenceSection of a topic — the first whose title contains the section query.',
+        'A single ReferenceSection of a topic: the first whose title contains the section query.',
     },
 
     // blog (read from the published RSS feed)
     {
       value: 'blog.list',
       description:
-        'The feed URL plus every post parsed from the RSS feed — each with slug, title, description, date, type, authors, link, and plaintext URL.',
+        'The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.',
     },
     {
       value: 'blog.detail',
@@ -89,7 +89,7 @@ export const doc = {
     {
       value: 'discover.detail.doc',
       description:
-        'The validated ComponentDoc for one external component — an @scope/name/Component query, or a free-text term resolving to exactly one component.',
+        'The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.',
     },
     {
       value: 'discover.search',
@@ -154,7 +154,7 @@ export const doc = {
     {
       value: 'hook.list',
       description:
-        'The hook catalog grouped by category: `detail` (the level — names | compact | full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.',
+        'The hook catalog grouped by category: `detail` (the level: names | compact | full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.',
     },
     {value: 'hook.detail', description: "One hook's full authored HookDoc."},
     {
@@ -176,7 +176,7 @@ export const doc = {
     {
       value: 'theme.list',
       description:
-        'Every bundled theme as a ThemeListEntry[] — each with slug, displayName, description, and a maintained flag.',
+        'Every bundled theme as a ThemeListEntry[]: each with slug, displayName, description, and a maintained flag.',
     },
     {
       value: 'theme.add',
@@ -193,7 +193,7 @@ export const doc = {
     {
       value: 'upgrade.status',
       description:
-        'A short-circuit outcome with no codemods run — up_to_date, no_codemods, or config_fixable — each carrying the agent-docs summary.',
+        'A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.',
     },
     {
       value: 'upgrade.run',

package/foundation/response/response.doc.mjs

@@ -47,7 +47,7 @@ export const doc = {
           name: 'data',
           type: 'unknown',
           description:
-            "The command's payload. Structural by design — narrowed by the " +
+            "The command's payload. Structural by design, narrowed by the " +
             'per-command return type, not by a map in the serializer.',
           required: true,
         },
@@ -63,7 +63,7 @@ export const doc = {
       name: 'Error envelope',
       type: '{ apiVersion: number; error: string; code: ErrorCode; suggestions?: Suggestion[] }',
       description:
-        'Emitted for every failure in --json mode — including uncaught throws ' +
+        'Emitted for every failure in --json mode, including uncaught throws ' +
         'and Commander parse errors, which are converted to this shape.',
       fields: [
         {
@@ -86,7 +86,7 @@ export const doc = {
           name: 'code',
           type: 'ErrorCode',
           description:
-            'Stable, machine-readable identifier — always present, append-only, ' +
+            'Stable, machine-readable identifier; always present, append-only, ' +
             'and never changes meaning. Branch on this.',
           required: true,
           example: "'ERR_UNKNOWN_COMPONENT'",
@@ -95,7 +95,7 @@ export const doc = {
           name: 'suggestions',
           type: 'Suggestion[]',
           description:
-            'Optional "did you mean…" hints, present only when candidates exist.',
+            'Optional "did you mean..." hints, present only when candidates exist.',
           fields: [
             {
               name: 'suggestions[].name',
@@ -146,7 +146,7 @@ export const doc = {
     {
       type: 'prose',
       text:
-        '`code` is the stable contract — see the error-codes enum (ErrorCode) ' +
+        '`code` is the stable contract; see the error-codes enum (ErrorCode) ' +
         'for the full append-only list. Branch on `code`, never on the `error` ' +
         'prose, which can be reworded or localized at any time.',
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.3.0-canary.d52d2cb",
+  "version": "0.3.0-canary.dccdabe",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -84,10 +84,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.3.0-canary.d52d2cb",
-    "@astryxdesign/core": "0.3.0-canary.d52d2cb",
-    "@astryxdesign/lab": "0.3.0-canary.d52d2cb",
-    "@astryxdesign/theme-neutral": "0.3.0-canary.d52d2cb",
+    "@astryxdesign/charts": "0.3.0-canary.dccdabe",
+    "@astryxdesign/core": "0.3.0-canary.dccdabe",
+    "@astryxdesign/lab": "0.3.0-canary.dccdabe",
+    "@astryxdesign/theme-neutral": "0.3.0-canary.dccdabe",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -105,10 +105,10 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.3.0-canary.d52d2cb",
-    "@astryxdesign/core": "0.3.0-canary.d52d2cb",
-    "@astryxdesign/lab": "0.3.0-canary.d52d2cb",
-    "@astryxdesign/theme-neutral": "0.3.0-canary.d52d2cb",
+    "@astryxdesign/charts": "0.3.0-canary.dccdabe",
+    "@astryxdesign/core": "0.3.0-canary.dccdabe",
+    "@astryxdesign/lab": "0.3.0-canary.dccdabe",
+    "@astryxdesign/theme-neutral": "0.3.0-canary.dccdabe",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {