@astryxdesign/cli 0.1.7-canary.fb9c68c → 0.1.7

package/README.md

@@ -2,19 +2,15 @@
 
 The CLI is the primary interface for working with the design system, for humans and machines alike. It provides component documentation, design tokens, page templates, theming tools, and upgrade codemods, all accessible via terminal commands, a typed JSON API, or programmatic imports. AI agents and build tools use the same API that powers the CLI, enabling end-to-end frontend development loops.
 
-Run it one-off with the scoped package (works whether or not it's installed):
-
 ```bash
-npx @astryxdesign/cli --help
-npx @astryxdesign/cli search button
-npx @astryxdesign/cli component Button
-npx @astryxdesign/cli docs tokens
-npx @astryxdesign/cli docs migration
-npx @astryxdesign/cli template --list
+npx astryx --help
+npx astryx search button
+npx astryx component Button
+npx astryx docs tokens
+npx astryx docs migration
+npx astryx template --list
 ```
 
-Once it's a project dependency (`npm install -D @astryxdesign/cli`), drop the scope and use the shorter `astryx` — e.g. `npx astryx component Button` or `pnpm exec astryx component Button`. Bare `astryx` resolves to an unrelated npm package until the CLI is installed, so prefer the scoped form above for first-run/one-off use.
-
 ## Finding things: `astryx search`
 
 When you don't know whether what you need is a component, a hook, a docs topic,
@@ -24,29 +20,27 @@ fuzzy matching for typos) and tagged with their domain plus the follow-up
 command to run:
 
 ```bash
-$ astryx search button
+$ npx astryx search button
 
 Results for "button" (20):
 
   [component]  Button
                Button triggers an action when clicked. Use it for form submissions…
-               → astryx component Button
+               → npx astryx component Button
 
   [component]  IconButton
                A button that shows only an icon with no visible text…
-               → astryx component IconButton
+               → npx astryx component IconButton
 
   [hook]       useClickableContainer
                Makes a container element clickable while preserving nested…
-               → astryx hook useClickableContainer
+               → npx astryx hook useClickableContainer
 
   [template]   Banner — Collapsible
                Combine an action button, dismiss control, and expandable detail area…
-               → astryx template BannerCollapsibleContent
+               → npx astryx template BannerCollapsibleContent
 ```
 
-(The CLI prints the follow-up commands with your actual runner — `npx astryx …` when installed, or `npx @astryxdesign/cli …` when run one-off.)
-
 Options:
 
 - `--type <component|hook|doc|template>`: restrict to a single domain
@@ -421,7 +415,7 @@ failures (warnings are fine) and `1` when any check fails. That makes it
 usable directly as a CI step:
 
 ```yaml
-- run: npx @astryxdesign/cli doctor
+- run: npx astryx doctor
 ```
 
 Use `--json` for a structured envelope (`{ apiVersion, type: "doctor",
@@ -429,103 +423,13 @@ data: { checks, summary } }`) that AI agents and scripts can parse.
 
 ## Configuration
 
-The CLI reads an optional `astryx.config.{ts,mjs,js}` from your project root
-(a sibling of `package.json`). Every field is optional; with no config file the
-CLI runs on defaults.
+The CLI reads from an optional `astryx.config.mjs` in your project root:
 
-```typescript
-import {createConfig} from '@astryxdesign/core/config';
-
-export default createConfig({
-  integrations: ['@acme/astryx-widgets'],
+```javascript
+export default {
+  templates: {
+    get: async id => fetchTemplateFromAPI(id),
+  },
   issuesUrl: 'https://github.com/your-org/your-repo/issues',
-});
-```
-
-`createConfig` is a type-preserving helper: it returns its argument unchanged
-and exists only to give the config file editor autocomplete and type-checking. A
-plain `export default {}` object works identically. It's exported from
-`@astryxdesign/core` (not the CLI) so your config file gets type feedback
-without depending on the CLI; the same helper is re-exported from
-`@astryxdesign/cli/config` for back-compat.
-
-| Field                         | Type                           | Purpose                                                                                         |
-| ----------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------- |
-| `integrations`                | `string[]`                     | Integration package names to load (see [Integrations](#integrations)).                          |
-| `issuesUrl`                   | `string`                       | Where "report an issue" links point for your project. Defaults to the core issue tracker.       |
-| `hooks.postCodemod`           | `PostCodemodHook[]`            | Commands to run after `astryx upgrade` applies codemods (e.g. reinstall, rebuild, reformat).    |
-| `experimental.xle.components` | `Record<string, XleComponent>` | Register app-local components so layout (XLE) expressions can reference them by name. Unstable. |
-
-The config is validated against a strict schema when the CLI loads it, so an
-unknown field is a hard error rather than a silent no-op. `astryx doctor`
-reports whether the config loads cleanly.
-
-## Integrations
-
-An **integration** is any npm package that contributes its own components,
-templates, and upgrade codemods to Astryx. The CLI surfaces them next to core's,
-through the same commands, so a consumer can `astryx component`,
-`astryx template`, and `astryx upgrade` across core and every integration
-uniformly. Use it to ship a first-party add-on, publish a third-party component
-library, or share an internal design-system package across apps.
-
-The system runs on two files, each with a small typed API:
-
-| File                             | Written by | Role                                      |
-| -------------------------------- | ---------- | ----------------------------------------- |
-| `astryx.config.{ts,mjs,js}`      | Consumer   | Lists which integration packages to load. |
-| `astryx.integration.{ts,mjs,js}` | Author     | Declares what a package contributes.      |
-
-The consumer side is the `integrations` field of [`astryx.config`](#configuration).
-The author side is the integration manifest below.
-
-### The integration manifest
-
-A package becomes an integration by exporting a manifest from
-`astryx.integration.{ts,mjs,js}` at its root (a sibling of `package.json`). The
-manifest points at where each kind of contribution lives; identity (name,
-version) comes from `package.json`, not the manifest.
-
-```typescript
-import {createIntegration} from '@astryxdesign/core/authoring';
-
-export default createIntegration({
-  components: './components',
-  templates: './templates',
-  codemods: './codemods',
-  issuesUrl: 'https://github.com/acme/widgets/issues',
-});
-```
-
-| Field        | Type     | Purpose                                                               |
-| ------------ | -------- | --------------------------------------------------------------------- |
-| `components` | `string` | Directory holding the package's components and their `.doc.*` files.  |
-| `templates`  | `string` | Directory holding the package's page/block templates.                 |
-| `codemods`   | `string` | Directory holding upgrade codemods run by `astryx upgrade`.           |
-| `issuesUrl`  | `string` | Where "report an issue" links for this package's contributions point. |
-
-Every field is optional; declare only the roots the package ships.
-`createIntegration` is a type-preserving helper (editor autocomplete and
-type-checking); it lives in `@astryxdesign/core/authoring` and is re-exported
-from `@astryxdesign/cli/integration` for back-compat.
-
-### How it works
-
-Every command loads the consumer's `astryx.config`, resolves each listed
-integration's manifest from `node_modules`, and discovers its contributions.
-Everything is validated against one strict schema at the load boundary, so the
-CLI presents core and integration contributions through a single, uniform
-surface.
-
-Discovery is resilient: a broken or misconfigured integration is skipped with a
-one-line warning on stderr instead of crashing the CLI, and it never corrupts a
-`--json` envelope. To inspect problems, run
-`astryx validate-integration <package>` for a detailed report on one package, or
-`astryx doctor` for an overall health check.
-
-For the full authoring walkthrough (component doc format, template packaging
-and `exports` requirements, and codemod authoring), see the guide:
-
-```bash
-astryx docs cli-integrations
+};
 ```

package/docs/getting-started.doc.mjs

@@ -21,7 +21,7 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: 'Install @astryxdesign/core, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project, then run `npx @astryxdesign/cli init` to set up agent docs. Read the generated files to learn the conventions.',
+          code: 'Install @astryxdesign/core, @astryxdesign/theme-neutral, and @astryxdesign/cli in this project. Run `npx astryx init` to set up agent docs. Read the generated files to learn the conventions.',
         },
       ],
     },
@@ -40,7 +40,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: "Then run `astryx init` to install the AI agent cheat sheet (AGENTS.md/CLAUDE.md). It's non-interactive — no prompts — so it's safe for AI agents, CI, and scripts. Add `--all` for pointers to the theme and page-building workflows.",
+          text: 'Then run the init wizard to set up AI agent docs, pick a starter template, and learn about theming.',
         },
         {
           type: 'code',
@@ -67,11 +67,11 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'Available themes: @astryxdesign/theme-neutral (muted minimal, a good starting point), @astryxdesign/theme-butter, @astryxdesign/theme-chocolate, @astryxdesign/theme-gothic (dark-only), @astryxdesign/theme-matcha, @astryxdesign/theme-stone, and @astryxdesign/theme-y2k. See `astryx docs theme` for the full theming guide.',
+          text: 'Available themes: @astryxdesign/theme-neutral (muted minimal, a good starting point), @astryxdesign/theme-butter, @astryxdesign/theme-chocolate, @astryxdesign/theme-gothic (dark-only), @astryxdesign/theme-matcha, @astryxdesign/theme-stone, and @astryxdesign/theme-y2k. See `npx astryx docs theme` for the full theming guide.',
         },
         {
           type: 'prose',
-          text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in `astryx docs migration` before building screens.',
+          text: 'These stylesheets are cascade-layered: the reset loads in @layer reset and component styles in @layer astryx-base. If your project has existing global CSS, a legacy reset, or Tailwind, declare the layer order explicitly and assign every stylesheet to a layer deliberately: unlayered styles and later layers both override astryx-base regardless of specificity. See the Cascade Layer Safety section in `npx astryx docs migration` before building screens.',
         },
       ],
     },
@@ -172,11 +172,11 @@ pnpm dev`,
           type: 'code',
           lang: 'bash',
           label: 'Terminal',
-          code: `astryx component          # list all components
-astryx component Button   # props, usage, theming for Button
-astryx docs               # list all doc topics
-astryx template --list    # available page templates
-astryx docs tokens        # spacing, color, radius reference`,
+          code: `npx astryx component          # list all components
+npx astryx component Button   # props, usage, theming for Button
+npx astryx docs               # list all doc topics
+npx astryx template --list    # available page templates
+npx astryx docs tokens        # spacing, color, radius reference`,
         },
       ],
     },

package/docs/integration-authoring.md

@@ -0,0 +1,105 @@
+# Authoring an Astryx Integration
+
+> **Status:** working notes. This should eventually move to the public wiki
+> alongside the rest of the integration-authoring guidance; it lives here for
+> now so it ships and is versioned with the CLI.
+
+An **Integration** is an npm package that contributes components, templates, and/or
+codemods to a consumer's design-system workflow. Consumers install the 3rd party
+package, add a line to their astryx.config file:
+
+```js
+import {createConfig} from '@astryxdesign/cli/config';
+
+export default createConfig({
+  integrations: ['@acme/astryx-widgets'],
+  ...
+});
+```
+
+Then the integration's components and templates will be surfaced alongside Astryx
+components in the Astryx CLI.
+
+```sh
+astryx component AcmeCarousel --props
+astryx component --list --package @acme/astryx-widgets
+```
+
+## The Integration File
+
+In order to register your package as an Astryx Integration, create an
+`astryx.integration.{ts,mjs,js}` file as a sibling to your `package.json`. This file
+tells Astryx where to find your components, templates, codemods, etc.
+
+```js
+// astryx.integration.{ts,mjs,js}
+import {createIntegration} from '@astryxdesign/cli/integration';
+
+export default createIntegration({
+  components: './components',
+  templates: './templates',
+  codemods: './codemods',
+  issuesUrl: 'https://github.com/acme/widgets/issues',
+});
+```
+
+## Components
+
+Your components themselves may be exported from your library as you see fit (consumers
+will still import them from your package) but Astryx CLI will look for a .doc.{ts,mjs,js}
+file with the same stem e.g. `AcmeCarousel.tsx` and `AcmeCarousel.doc.ts`.
+
+```js
+// AcmeCarousel.doc.ts
+import {createComponentDoc} from '@astryxdesign/cli/doc';
+
+export default createComponentDoc({
+  name: 'AcmeCarousel',
+  description: '...',
+  ...
+});
+```
+
+## Templates
+
+Templates are typically not exported from the package directly, but instead accessed
+via the Astryx CLI. Consumers can look through your templates and materialize them
+into their apps.
+
+You define a template with the `createPageTemplate` (for full pages) or `createBlockTemplate`
+(for smaller chunks). e.g. `AcmeLandingPage.tsx`, `AcmeLandingPage.template.ts`
+
+```js
+// AcmeLandingPage.template.ts
+import {createPageTemplate} from '@astryxdesign/cli/template';
+
+export default createPageTemplate({
+  ...
+});
+```
+
+Note that, since the CLI needs access to the template source code, you need to make sure
+that it is included in your published package. This will also allow us to render previews
+of templates in the future by bundling your template into a doc site build.
+
+Typically, this is done via the package.json `exports` key.
+
+```jsonc
+{
+  "exports": {
+    // ...
+    "./templates/*.tsx": "./templates/*.tsx",
+  },
+}
+```
+
+In order to verify that it's working, you can test importing the template component like this:
+
+```ts
+import('@acme/astryx-widgets/templates/AcmeLandingPage.tsx');
+```
+
+Import **with the `.tsx` extension** — an extensionless specifier won't resolve
+under `moduleResolution: bundler`. The extensionful `"./templates/*.tsx"` export
+above is what lets that import type-check without consumers enabling
+`allowImportingTsExtensions`.

package/docs/migration.doc.mjs

@@ -54,18 +54,18 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           label: 'Migration-oriented CLI pass',
-          code: `astryx docs migration
-astryx docs theme
-astryx docs styling
-astryx template --list --type block
-astryx template AppShellTopNavWithSideNav --skeleton
-astryx template PopoverSettingsPanel --skeleton
-astryx component AppShell
-astryx component SideNav
-astryx component TopNav
-astryx component CommandPalette
-astryx component Button
-astryx component TextInput`,
+          code: `npx astryx docs migration
+npx astryx docs theme
+npx astryx docs styling
+npx astryx template --list --type block
+npx astryx template AppShellTopNavWithSideNav --skeleton
+npx astryx template PopoverSettingsPanel --skeleton
+npx astryx component AppShell
+npx astryx component SideNav
+npx astryx component TopNav
+npx astryx component CommandPalette
+npx astryx component Button
+npx astryx component TextInput`,
         },
         {
           type: 'prose',
@@ -75,8 +75,8 @@ astryx component TextInput`,
           type: 'code',
           lang: 'bash',
           label: 'Dense and JSON modes',
-          code: `astryx docs migration --dense
-astryx component Button --json`,
+          code: `npx astryx docs migration --dense
+npx astryx component Button --json`,
         },
       ],
     },
@@ -371,10 +371,10 @@ if (getComputedStyle(button).paddingInline === '0px') {
           code: `We are migrating this existing Tailwind/shadcn app to Astryx incrementally.
 
 First run:
-- astryx docs migration --dense
-- astryx docs theme --dense
-- astryx docs styling --dense
-- astryx template AppShellTopNavWithSideNav --skeleton
+- npx astryx docs migration --dense
+- npx astryx docs theme --dense
+- npx astryx docs styling --dense
+- npx astryx template AppShellTopNavWithSideNav --skeleton
 
 Then migrate one route or shell surface at a time. Keep business logic and routing intact. Replace shadcn/Radix/Tailwind primitives with Astryx components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.`,
         },

package/docs/principles.doc.dense.mjs

@@ -9,6 +9,6 @@ export const docsDense = {
     { section: 'Rules', title: 'Rules', content: [{ type: 'list', items: ['use components', 'frame-first layout: shell + region budgets before content (astryx docs layout)', 'dense data = rows (Table, List/Item) not Cards; Card = widgets/galleries/settings groups', 'StyleX or Tailwind for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },
     { section: 'Styling Approach', title: 'Styling', content: [{ type: 'prose', text: 'xstyle prop for component overrides. StyleX or Tailwind for layout. See astryx docs styling.' }] },
     { section: 'Anti-Patterns', title: 'Anti-Patterns', content: [{ type: 'list', items: ['no inline styles on raw elements', 'no hardcoded colors — use tokens or Tailwind semantic classes', 'no hardcoded spacing', 'no hardcoded <a> — use useLinkComponent()', 'no Card-wrapped list items — frame first, rows for dense data (astryx docs layout)', 'no decorative Badge — StatusDot/Token for status', 'read docs before inventing props'] }] },
-    { section: 'Design Tokens', title: 'Tokens', content: [{ type: 'prose', text: 'run astryx docs tokens for full reference' }] },
+    { section: 'Design Tokens', title: 'Tokens', content: [{ type: 'prose', text: 'run npx astryx docs tokens for full reference' }] },
   ],
 };

package/docs/principles.doc.mjs

@@ -39,10 +39,10 @@ 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\`)',
+            'Layout is frame-first: pick the shell and budget regions before writing content (see \`npx 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\`)',
+            'StyleX or Tailwind for custom styling; both are first-class (see \`npx astryx docs styling\`)',
+            'Semantic tokens, not hardcoded values (see \`npx astryx docs tokens\`)',
             'CSS custom properties for colors, not hex values',
             'Form inputs are controlled (value + onChange)',
             'Use useLinkComponent() for navigation so consumers can plug in their framework router via LinkProvider',
@@ -60,7 +60,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'See \`astryx docs styling\` for the complete guide with examples.',
+          text: 'See \`npx astryx docs styling\` for the complete guide with examples.',
         },
       ],
     },
@@ -76,7 +76,7 @@ export const docs = {
             'Hardcoded colors (#fff). Use var(--color-*) or Tailwind semantic classes (text-primary, bg-surface)',
             'Hardcoded spacing (16px). Use spacing tokens or Tailwind spacing utilities',
             'Hardcoded <a> elements. Use useLinkComponent() so consumers can swap in their framework router via LinkProvider',
-            'Wrapping every list item or page section in a Card. Decide the frame first; dense data renders as rows (see \`astryx docs layout\`)',
+            'Wrapping every list item or page section in a Card. Decide the frame first; dense data renders as rows (see \`npx astryx docs layout\`)',
             'Badge as decoration. Reserve Badge for counts and enumerated states; use StatusDot or Token for status',
             'Inventing props. Read component docs first',
           ],
@@ -89,7 +89,7 @@ export const docs = {
       content: [
         {
           type: 'prose',
-          text: 'The design system provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run \`astryx docs tokens\` for the full reference with all values.',
+          text: 'The design system provides semantic design tokens for spacing, color, radius, shadow, typography, and size. Tokens adapt to the active theme and color mode. Run \`npx astryx docs tokens\` for the full reference with all values.',
         },
       ],
     },

package/docs/principles.doc.zh.mjs

@@ -9,6 +9,6 @@ export const docsZh = {
     { section: 'Rules', title: '规则', content: [{ type: 'list', items: ['所有支持的场景都使用 XDS 组件', '布局采用框架优先：先选定外壳并规划区域尺寸，再编写内容（见 astryx docs layout）', '密集数据使用行（Table、List/Item）通栏渲染；Card 用于小部件、画廊和设置分组', '使用 StyleX 或 Tailwind 进行样式设置', '使用语义化令牌，不使用硬编码值', '使用 CSS 变量设置颜色，不使用十六进制值', '表单输入为受控组件（value + onChange）', '使用 useLinkComponent() 进行导航'] }] },
     { section: 'Styling Approach', title: '样式方法', content: [{ type: 'prose', text: '组件覆盖使用 xstyle 属性。布局使用 StyleX 或 Tailwind。详见 astryx docs styling。' }] },
     { section: 'Anti-Patterns', title: '反模式', content: [{ type: 'list', items: ['不要在原始元素上使用内联样式', '不要硬编码颜色 — 使用令牌或 Tailwind 语义类', '不要硬编码间距', '不要硬编码 <a> 元素 — 使用 useLinkComponent()', '不要把每个列表项都包在 Card 里 — 先定框架，密集数据用行渲染（见 astryx docs layout）', '不要把 Badge 当装饰 — 状态请使用 StatusDot 或 Token', '不要自创属性。先阅读组件文档'] }] },
-    { section: 'Design Tokens', title: '设计令牌', content: [{ type: 'prose', text: '运行 astryx docs tokens 查看完整参考' }] },
+    { section: 'Design Tokens', title: '设计令牌', content: [{ type: 'prose', text: '运行 npx astryx docs tokens 查看完整参考' }] },
   ],
 };

package/docs/styling-libraries.doc.mjs

@@ -24,7 +24,7 @@ export const docs = {
         },
         {
           type: 'prose',
-          text: 'For available token names and values, run `astryx docs tokens`. Focused references are also available with `astryx docs color`, `astryx docs spacing`, `astryx docs shape`, `astryx docs typography`, `astryx docs elevation`, and `astryx docs motion`.',
+          text: 'For available token names and values, run `npx astryx docs tokens`. Focused references are also available with `npx astryx docs color`, `npx astryx docs spacing`, `npx astryx docs shape`, `npx astryx docs typography`, `npx astryx docs elevation`, and `npx astryx docs motion`.',
         },
       ],
     },
@@ -452,10 +452,10 @@ function RevenueChart({data}: {data: Array<{x: string; y: number}>}) {
           type: 'list',
           style: 'ordered',
           items: [
-            'Import the reset/base CSS and a theme CSS file early enough for first paint. For production SSR, prefer built themes from `astryx theme build` or published `/built` theme imports plus `theme.css`.',
+            'Import the reset/base CSS and a theme CSS file early enough for first paint. For production SSR, prefer built themes from `npx astryx theme build` or published `/built` theme imports plus `theme.css`.',
             'Choose one owner for color mode. Theme uses `data-theme="light|dark"` and `color-scheme` to resolve `light-dark()` tokens.',
             'Map the external library\'s semantic layer to system variables by intent, not by exact naming. For example, MUI `background.paper` maps to `--color-background-surface`.',
-            'Use `astryx docs tokens` and focused token docs when building mappings. Keep mappings small at first: text, surface/body/card/popover, border, accent, status, spacing, radius, typography, shadow.',
+            'Use `npx astryx docs tokens` and focused token docs when building mappings. Keep mappings small at first: text, surface/body/card/popover, border, accent, status, spacing, radius, typography, shadow.',
             'Use token resolver APIs only for non-CSS APIs that need resolved values.',
           ],
         },

package/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 `npx astryx docs 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 `npx astryx docs 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 `npx astryx docs theme` for the full theming guide.',
         },
       ],
     },
@@ -334,7 +334,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 `npx astryx docs tokens` for the full token reference (all spacing, color, radius, shadow, and typography tokens with values). See `npx astryx docs theme` for how to override tokens via defineTheme.',
         },
       ],
     },

package/docs/theme.doc.dense.mjs

@@ -10,9 +10,9 @@ export const docsDense = {
     { section: 'Theme Props', title: 'Props', content: [null] },
     { section: 'Creating a Custom Theme', title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },
     { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: 'scale configs (color, typography, radius, motion) + explicit token overrides + component overrides. color derives full palette from accent hex via HCT.' }, null, null] },
-    { section: 'Component Style Overrides', title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-press-scale etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `astryx component <Name>` for details.' }, null, null, null, null] },
+    { section: 'Component Style Overrides', title: 'Component Overrides', content: [{ type: 'prose', text: 'components field uses semantic component keys + style keys (base, variant:value, stateName), not raw selectors. for external CSS, prefer data-* selectors from `astryx docs styling`. write standard CSS (borderRadius, padding) — pipeline expands to internal vars. public vars (--button-press-scale etc) set directly. private vars (--_*) cannot be set — use CSS properties. run `npx astryx component <Name>` for details.' }, null, null, null, null] },
     { section: 'Custom Variants', title: 'Custom Variants', content: [{ type: 'prose', text: 'any unknown prop:value in components becomes a new variant. astryx theme build generates TS augmentations. works on any extensible prop axis (variant, status, etc).' }, null, null, null, null] },
-    { section: 'Building Themes for Production', title: 'Build for Production', content: [{ type: 'prose', text: 'astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },
+    { section: 'Building Themes for Production', title: 'Build for Production', content: [{ type: 'prose', text: 'npx astryx theme build compiles defineTheme to static CSS. outputs .css + .js (__built:true) + .d.ts.' }, null, null, null, null] },
     { section: 'Runtime vs Built Themes', title: 'Runtime vs Built', content: [{ type: 'prose', text: 'runtime: useInsertionEffect injects styles client-side. built: static CSS on first paint. USE /built + theme.css FOR SSR.' }, null, null, null] },
     { section: 'Light/Dark Mode', title: 'Light/Dark', content: [{ type: 'prose', text: 'light-dark() in token values via [light, dark] tuples. mode=system follows OS.' }, null, null] },
     { section: 'Nesting Themes', title: 'Nesting', content: [{ type: 'prose', text: 'wrap sections in separate <Theme> providers' }, null] },

package/docs/theme.doc.mjs

@@ -148,7 +148,7 @@ function App() {
           type: 'code',
           lang: 'bash',
           label: 'Scaffold with CLI',
-          code: 'astryx theme',
+          code: 'npx astryx theme',
         },
       ],
     },
@@ -287,7 +287,7 @@ const brandTheme = defineTheme({
         },
         {
           type: 'prose',
-          text: 'Run `astryx component <Name>` to see a component\'s theming targets, public CSS variables, and which standard CSS properties are supported.',
+          text: 'Run `npx astryx component <Name>` to see a component\'s theming targets, public CSS variables, and which standard CSS properties are supported.',
         },
         {
           type: 'list',
@@ -361,13 +361,13 @@ const brandTheme = defineTheme({
       content: [
         {
           type: 'prose',
-          text: '`astryx theme build` compiles a defineTheme file into production-ready artifacts. Recommended for SSR apps (Next.js, Remix) where styles must be present on first paint.',
+          text: '`npx astryx theme build` compiles a defineTheme file into production-ready artifacts. Recommended for SSR apps (Next.js, Remix) where styles must be present on first paint.',
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Build a theme',
-          code: 'astryx theme build ./src/themes/ocean.ts',
+          code: 'npx astryx theme build ./src/themes/ocean.ts',
         },
         {
           type: 'prose',
@@ -432,7 +432,7 @@ import './themes/ocean.css';
             [
               'Import (custom theme)',
               'defineTheme() directly',
-              "Built .js + .css from `astryx theme build`",
+              "Built .js + .css from `npx astryx theme build`",
             ],
             [
               'How it works',
@@ -462,7 +462,7 @@ import './themes/ocean.css';
           items: [
             'Use the /built subpath + theme.css for production SSR apps.',
             'Use runtime themes during development for fast iteration.',
-            'Run `astryx theme build` for custom themes to get the built artifacts.',
+            'Run `npx astryx theme build` for custom themes to get the built artifacts.',
           ],
         },
         {
@@ -610,7 +610,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 `npx astryx docs styling-libraries` for styling-library interop and `npx astryx docs tokens` for the full token reference.',
         },
       ],
     },

package/docs/theme.doc.zh.mjs

@@ -10,7 +10,7 @@ export const docsZh = {
     { section: 'Theme Props', title: 'Theme 属性', content: [null] },
     { section: 'Creating a Custom Theme', title: '创建自定义主题', content: [{ type: 'prose', text: '使用 CLI 向导（推荐）或手动 defineTheme。只覆盖与默认值不同的令牌。' }, null] },
     { section: 'defineTheme', title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置（typography、radius、motion）+ 显式令牌覆盖 + 组件覆盖。' }, null, null] },
-    { section: 'Building Themes for Production', title: '生产构建', content: [{ type: 'prose', text: 'astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js（__built:true）+ .d.ts。' }, null, null, null, null] },
+    { section: 'Building Themes for Production', title: '生产构建', content: [{ type: 'prose', text: 'npx astryx theme build 将 defineTheme 编译为静态 CSS。输出 .css + .js（__built:true）+ .d.ts。' }, null, null, null, null] },
     { section: 'Runtime vs Built Themes', title: '运行时 vs 构建', content: [{ type: 'prose', text: '运行时：useInsertionEffect 在客户端注入样式。构建：静态 CSS 在首次渲染时就存在。SSR 应用请使用 /built + theme.css。' }, null, null, null] },
     { section: 'Light/Dark Mode', title: '亮/暗模式', content: [{ type: 'prose', text: "令牌值使用 [light, dark] 元组实现自动模式切换。Theme 上 mode='system'（默认）跟随系统偏好。" }, null, null] },
     { section: 'Nesting Themes', title: '嵌套主题', content: [{ type: 'prose', text: '将不同部分包裹在独立的 <Theme> 提供者中。' }, null] },

package/docs/tokens.doc.mjs

@@ -1068,7 +1068,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 `npx astryx docs styling` for how to apply tokens via xstyle, className, and compound component patterns. See `npx astryx docs theme` for overriding tokens with defineTheme."
         }
       ]
     }