@astryxdesign/cli 0.1.0 → 0.1.1-canary.13763f6

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # @xds/cli
 
+# 0.1.1
+
+#### New Features
+
+- Add `astryx build` command for page composition, with natural-language search ranking.
+  `build "<idea>"` returns a composition kit — the closest page template, the
+  blocks that cover parts, and components to fill gaps, plus a Compose suggestion.
+  `build` with no args prints the how-to-build playbook. The shared search ranking
+  now handles oblique natural-language queries via tokenization + stopwords, a
+  synonym/intent map, light stemming, and page-template keyword enrichment.
+- Make generated agent docs build-first and restructure `init` output.
+  The generated `CLAUDE.md` now leads with the `build` workflow (search reframed as
+  a neutral universal find), and includes a required-CSS setup note
+  (`reset.css` + `astryx.css`) so components never render unstyled. `init` now
+  points agents at `astryx build`/`astryx search` instead of dumping page-template
+  names.
+- Improve `astryx build` output into a complete composition kit.
+  `build "<idea>"` now returns an agent-ready kit grouped by role: a START line
+  (scaffold vs compose), the closest PAGE template, an always-on FRAME (page
+  shell) and FOUNDATION (layout/typography/action primitives), idea-specific
+  BLOCKS and DOMAIN COMPONENTS (with a relevance floor to cut noise), and a SETUP
+  reminder. The always-on FRAME/FOUNDATION groups fix low recall of the
+  structural primitives every page needs but that never keyword-match an idea
+  (measured: component recall 15% to 71% on an agent-grounded eval).
+- Densify agent docs + tailor styling guidance to the project's configured system
+  Tightened the generated `CLAUDE.md`/`AGENTS.md` block from ~48 lines to ~26
+  (the per-topic `docs` dump collapsed to one line, `build`/`search`/`component`
+  no longer duplicated between workflow and reference, run-prefix stated once,
+  filler prose removed) — same information, far denser.
+
+#### Fixes
+
+- `npx astryx` now works when the CLI is installed as a real npm package.
+  The bin imported its `../src/*` modules relative to the invoked path, so running
+  through the `node_modules/.bin/astryx` symlink made them resolve outside the
+  package (`ERR_MODULE_NOT_FOUND: .../node_modules/src/...`) on Node versions that
+  don't realpath the bin entry. It now resolves siblings via the bin's real path
+  (realpath of `import.meta.url`), working whether invoked via symlink, copy, or
+  Windows shim. Also fixes the non-interactive `init`/`theme` error to say
+  `astryx <command>` instead of the stale `xds <command>`.
+- Add a v0.1.0 upgrade codemod that migrates legacy `@xds/*` module specifiers and config surfaces to the Astryx v0.1.0 names.
+  [breaking] Remove legacy `astryx.versionFile` update-hint support from package.json.
+
+#### Documentation
+
+- Add npm install step to the Theme System guide
+  The Quick Start section jumped straight to `import {neutralTheme} from '@astryxdesign/theme-neutral'`, which fails with `Cannot find module` for anyone who hasn't already installed the theme package. Prepend a one-line preamble + `npm install` code block, and add a short prose note above the Available Themes table pointing at the install command pattern. Reported in #3082.
+
+#### Other Changes
+
+- StyleX compiler wired → `xstyle` / StyleX token imports
+- Tailwind → utility classes backed by `@astryxdesign/core/tailwind-theme.css`
+- neither → `style`/`className` with `var(--token)` design tokens, plus an
+  explicit note NOT to use `xstyle`/utilities (they would not compile)
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @ejhammond
+- @joeyfarina
+- @josephfarina
+- @nynexman4464
+
+---
+
 # 0.1.0
 
 #### Breaking Changes
@@ -71,9 +137,11 @@
   - import {neutralTheme} from '@astryxdesign/theme-neutral/built';
 - <Theme theme={defaultTheme}>...</Theme>
   - <Theme theme={neutralTheme}>...</Theme>
+
   ```
 
   ```
+
 - Remove the internal `drop-xds-meta-prefix` codemod from the OSS repo (#2970)
   This codemod has been moved to its own package's tooling, where it belongs. It was registered as an optional, version-independent transform and is not part of any standard upgrade path, so removing it does not affect the public `0.0.13 → 0.0.15` migration.
 - Rename the npm package scope from `@xds/*` to `@astryxdesign/*`

package/README.md

@@ -11,7 +11,7 @@ npx astryx docs migration
 npx astryx template --list
 ```
 
-### Finding things: `astryx search`
+## Finding things: `astryx search`
 
 When you don't know whether what you need is a component, a hook, a docs topic,
 or a template, search across all of them at once. Results are ranked by
@@ -50,20 +50,20 @@ Options:
 
 ## Commands
 
-| Command       | Description                                                                             |
-| ------------- | --------------------------------------------------------------------------------------- |
+| Command       | Description                                                                                          |
+| ------------- | ---------------------------------------------------------------------------------------------------- |
 | `init`        | Initialize the design system in your project: installs packages, sets up theming, adds AI agent docs |
-| `component`   | List components or print detailed docs, props, usage examples, and source               |
-| `search`      | Find components, hooks, docs, and templates in one ranked, cross-domain result set       |
-| `docs`        | Print reference documentation (tokens, theme, color, typography, spacing, etc.)         |
-| `template`    | Inject page or block templates into your project                                        |
-| `hook`        | List hooks and print hook documentation                                                 |
-| `swizzle`     | Copy component source into your project for deep customization                          |
-| `upgrade`     | Run codemods to migrate between versions                                                |
-| `theme build` | Compile a defineTheme file to production CSS and JS                                     |
-| `discover`    | Discover external packages and components                                               |
-| `gap-report`  | Report a gap when a component doesn't meet your needs                                   |
-| `doctor`      | Diagnose your XDS setup and report problems with fixes (CI-friendly via exit code)      |
+| `component`   | List components or print detailed docs, props, usage examples, and source                            |
+| `search`      | Find components, hooks, docs, and templates in one ranked, cross-domain result set                   |
+| `docs`        | Print reference documentation (tokens, theme, color, typography, spacing, etc.)                      |
+| `template`    | Inject page or block templates into your project                                                     |
+| `hook`        | List hooks and print hook documentation                                                              |
+| `swizzle`     | Copy component source into your project for deep customization                                       |
+| `upgrade`     | Run codemods to migrate between versions                                                             |
+| `theme build` | Compile a defineTheme file to production CSS and JS                                                  |
+| `discover`    | Discover external packages and components                                                            |
+| `gap-report`  | Report a gap when a component doesn't meet your needs                                                |
+| `doctor`      | Diagnose your XDS setup and report problems with fixes (CI-friendly via exit code)                   |
 
 ### Global options
 
@@ -122,46 +122,46 @@ if (isError(result)) {
 
 ### Error codes
 
-| Code | Meaning |
-| --- | --- |
-| `ERR_UNKNOWN` | Generic fallback for any error without a more specific code. |
-| `ERR_UNKNOWN_COMMAND` | A top-level command name was not recognized (e.g. `astryx bogus`). |
-| `ERR_UNKNOWN_SUBCOMMAND` | A subcommand under a group was not recognized (e.g. `astryx theme bogus`). |
-| `ERR_INVALID_OPTION` | An unknown flag was passed, or `--json` was used on a command that doesn't support it. |
-| `ERR_INVALID_ARGUMENT` | An option/argument value was rejected, or required flags were missing. |
-| `ERR_MISSING_ARGUMENT` | A required positional argument was omitted (e.g. `astryx theme build` with no file). |
-| `ERR_INVALID_LANG` | `--lang` was given a value outside its choices (`en`, `zh`, `dense`). |
-| `ERR_INVALID_DETAIL` | `--detail` was given a value outside its choices (`full`, `compact`, `brief`). |
-| `ERR_NODE_VERSION` | The running Node.js version is below the supported minimum. |
-| `ERR_CORE_NOT_FOUND` | `@astryxdesign/core` could not be located (not installed / not in a monorepo). |
-| `ERR_UNKNOWN_COMPONENT` | No component matched the requested name. |
-| `ERR_UNKNOWN_HOOK` | No hook matched the requested name. |
-| `ERR_UNKNOWN_TOPIC` | No docs topic matched the requested name. |
-| `ERR_UNKNOWN_SECTION` | A docs topic exists but the requested section within it does not. |
-| `ERR_UNKNOWN_CATEGORY` | A `--category` filter value did not match any known category. |
-| `ERR_UNKNOWN_TEMPLATE` | No template matched the requested name. |
-| `ERR_UNKNOWN_PACKAGE` | No package matched the requested name (discover). |
-| `ERR_UNKNOWN_AGENT` | An unrecognized `--agent` value was passed (agent docs / init). |
-| `ERR_UNKNOWN_FEATURE` | An unrecognized `--features` value was passed to `init`. |
-| `ERR_UNKNOWN_CODEMOD` | A `--codemod` value did not match any registered codemod (upgrade). |
-| `ERR_NOT_FOUND` | A discover/lookup query matched nothing in any package. |
-| `ERR_NO_DOC` | A component exists but has no typed `.doc.mjs` file. |
-| `ERR_NO_SHOWCASE` | No showcase exists for the requested component. |
-| `ERR_NO_SOURCE` | No source file could be located for the component/template. |
-| `ERR_INVALID_DOC` | A component's docs failed validation (malformed `.doc.mjs`). |
-| `ERR_FILE_NOT_FOUND` | A required input file did not exist. |
-| `ERR_FILE_EXISTS` | Refused to overwrite an existing file in non-interactive mode. |
-| `ERR_PATH_TRAVERSAL` | A path escaped its allowed root, or a name contained traversal markers. |
-| `ERR_WRITE_FAILED` | Writing output files failed (and was rolled back). |
-| `ERR_THEME_INVALID` | A theme definition was missing a required property (e.g. `name`). |
-| `ERR_THEME_LOAD` | A theme file could not be loaded / parsed into a `defineTheme` result. |
-| `ERR_TEMPLATE_CONFIG` | `template.get` is not configured in `astryx.config.mjs` (fetch-by-id). |
-| `ERR_TEMPLATE_GET` | A configured `template.get` threw or returned an invalid value. |
-| `ERR_VERSION_DETECT` | The current `@astryxdesign/core` version could not be detected. |
-| `ERR_INVALID_VERSION` | A `--from`/`--to` value was not a valid semver string. |
-| `ERR_DEP_MISSING` | A required external dependency (e.g. jscodeshift) is missing. |
-| `ERR_GH_CLI` | GitHub CLI (`gh`) is not installed or not authenticated. |
-| `ERR_GAP_REPORT_FAILED` | Filing a gap report failed (disabled, or the integration errored). |
+| Code                     | Meaning                                                                                |
+| ------------------------ | -------------------------------------------------------------------------------------- |
+| `ERR_UNKNOWN`            | Generic fallback for any error without a more specific code.                           |
+| `ERR_UNKNOWN_COMMAND`    | A top-level command name was not recognized (e.g. `astryx bogus`).                     |
+| `ERR_UNKNOWN_SUBCOMMAND` | A subcommand under a group was not recognized (e.g. `astryx theme bogus`).             |
+| `ERR_INVALID_OPTION`     | An unknown flag was passed, or `--json` was used on a command that doesn't support it. |
+| `ERR_INVALID_ARGUMENT`   | An option/argument value was rejected, or required flags were missing.                 |
+| `ERR_MISSING_ARGUMENT`   | A required positional argument was omitted (e.g. `astryx theme build` with no file).   |
+| `ERR_INVALID_LANG`       | `--lang` was given a value outside its choices (`en`, `zh`, `dense`).                  |
+| `ERR_INVALID_DETAIL`     | `--detail` was given a value outside its choices (`full`, `compact`, `brief`).         |
+| `ERR_NODE_VERSION`       | The running Node.js version is below the supported minimum.                            |
+| `ERR_CORE_NOT_FOUND`     | `@astryxdesign/core` could not be located (not installed / not in a monorepo).         |
+| `ERR_UNKNOWN_COMPONENT`  | No component matched the requested name.                                               |
+| `ERR_UNKNOWN_HOOK`       | No hook matched the requested name.                                                    |
+| `ERR_UNKNOWN_TOPIC`      | No docs topic matched the requested name.                                              |
+| `ERR_UNKNOWN_SECTION`    | A docs topic exists but the requested section within it does not.                      |
+| `ERR_UNKNOWN_CATEGORY`   | A `--category` filter value did not match any known category.                          |
+| `ERR_UNKNOWN_TEMPLATE`   | No template matched the requested name.                                                |
+| `ERR_UNKNOWN_PACKAGE`    | No package matched the requested name (discover).                                      |
+| `ERR_UNKNOWN_AGENT`      | An unrecognized `--agent` value was passed (agent docs / init).                        |
+| `ERR_UNKNOWN_FEATURE`    | An unrecognized `--features` value was passed to `init`.                               |
+| `ERR_UNKNOWN_CODEMOD`    | A `--codemod` value did not match any registered codemod (upgrade).                    |
+| `ERR_NOT_FOUND`          | A discover/lookup query matched nothing in any package.                                |
+| `ERR_NO_DOC`             | A component exists but has no typed `.doc.mjs` file.                                   |
+| `ERR_NO_SHOWCASE`        | No showcase exists for the requested component.                                        |
+| `ERR_NO_SOURCE`          | No source file could be located for the component/template.                            |
+| `ERR_INVALID_DOC`        | A component's docs failed validation (malformed `.doc.mjs`).                           |
+| `ERR_FILE_NOT_FOUND`     | A required input file did not exist.                                                   |
+| `ERR_FILE_EXISTS`        | Refused to overwrite an existing file in non-interactive mode.                         |
+| `ERR_PATH_TRAVERSAL`     | A path escaped its allowed root, or a name contained traversal markers.                |
+| `ERR_WRITE_FAILED`       | Writing output files failed (and was rolled back).                                     |
+| `ERR_THEME_INVALID`      | A theme definition was missing a required property (e.g. `name`).                      |
+| `ERR_THEME_LOAD`         | A theme file could not be loaded / parsed into a `defineTheme` result.                 |
+| `ERR_TEMPLATE_CONFIG`    | `template.get` is not configured in `astryx.config.mjs` (fetch-by-id).                 |
+| `ERR_TEMPLATE_GET`       | A configured `template.get` threw or returned an invalid value.                        |
+| `ERR_VERSION_DETECT`     | The current `@astryxdesign/core` version could not be detected.                        |
+| `ERR_INVALID_VERSION`    | A `--from`/`--to` value was not a valid semver string.                                 |
+| `ERR_DEP_MISSING`        | A required external dependency (e.g. jscodeshift) is missing.                          |
+| `ERR_GH_CLI`             | GitHub CLI (`gh`) is not installed or not authenticated.                               |
+| `ERR_GAP_REPORT_FAILED`  | Filing a gap report failed (disabled, or the integration errored).                     |
 
 ## Capability manifest (agent discovery)
 
@@ -186,25 +186,59 @@ Shape:
     "version": "0.0.14",
     "description": "Design system CLI — components, themes, and tooling",
     "globalOptions": [
-      {"flag": "--json", "type": "boolean", "description": "Output as typed JSON…"},
-      {"flag": "--lang <locale>", "type": "enum", "choices": ["en", "zh", "dense"]},
-      {"flag": "--detail <level>", "type": "enum", "choices": ["full", "compact", "brief"], "default": "full"}
+      {
+        "flag": "--json",
+        "type": "boolean",
+        "description": "Output as typed JSON…",
+      },
+      {
+        "flag": "--lang <locale>",
+        "type": "enum",
+        "choices": ["en", "zh", "dense"],
+      },
+      {
+        "flag": "--detail <level>",
+        "type": "enum",
+        "choices": ["full", "compact", "brief"],
+        "default": "full",
+      },
     ],
     "commands": [
       {
         "name": "component",
         "description": "List components or print component docs",
-        "arguments": [{"name": "name", "required": false, "variadic": false, "description": ""}],
-        "options": [{"flag": "--props", "type": "boolean", "description": "Print only the props table"}],
+        "arguments": [
+          {
+            "name": "name",
+            "required": false,
+            "variadic": false,
+            "description": "",
+          },
+        ],
+        "options": [
+          {
+            "flag": "--props",
+            "type": "boolean",
+            "description": "Print only the props table",
+          },
+        ],
         "json": true,
-        "responseTypes": ["component.list", "component.detail", "component.detail.props", "…"],
-        "examples": ["astryx component Button --props --json"]
-      }
+        "responseTypes": [
+          "component.list",
+          "component.detail",
+          "component.detail.props",
+          "…",
+        ],
+        "examples": ["astryx component Button --props --json"],
+      },
       // …one entry per command; subcommands (e.g. `theme build`) nest under `subcommands`
     ],
     "jsonSupported": ["component", "docs", "…"],
-    "responseTypes": {"component": ["component.list", "…"], "theme build": ["theme.build"]}
-  }
+    "responseTypes": {
+      "component": ["component.list", "…"],
+      "theme build": ["theme.build"],
+    },
+  },
 }
 ```
 
@@ -225,7 +259,15 @@ For the standalone manifest envelope (`type: "manifest"`), use `astryx manifest
 The same logic that powers `xds --json` is available as importable, type-safe functions:
 
 ```typescript
-import {component, docs, discover, template, hook, search, AstryxError} from '@astryxdesign/cli/api';
+import {
+  component,
+  docs,
+  discover,
+  template,
+  hook,
+  search,
+  AstryxError,
+} from '@astryxdesign/cli/api';
 
 // Same result as: xds --json component Button
 const btn = await component('Button');
@@ -359,16 +401,16 @@ No failures — but review the ⚠ warnings above when you can.
 
 ### Checks
 
-| Check                | Status it can return | What it verifies                                            |
-| -------------------- | -------------------- | ----------------------------------------------------------- |
-| Node.js version      | pass / fail          | Running Node meets the CLI's minimum                        |
-| @astryxdesign/core installed  | pass / fail          | `@astryxdesign/core` is resolvable from the project                  |
-| Version alignment    | pass / warn / info   | Installed `@astryxdesign/core` is in step with `@astryxdesign/cli`            |
-| Theme packages       | pass / warn          | An `@astryxdesign/theme-*` package is installed and a theme is wired |
-| astryx.config.mjs       | pass / fail / info   | Config (if present) loads cleanly with a valid shape        |
-| AI agent docs        | pass / warn / info   | Agent docs exist and contain the XDS section markers        |
-| Peer dependencies    | pass / warn / info   | `@astryxdesign/core`'s peer deps (react, …) are installed            |
-| Package manager      | info                 | Reports the detected package manager                        |
+| Check                        | Status it can return | What it verifies                                                     |
+| ---------------------------- | -------------------- | -------------------------------------------------------------------- |
+| Node.js version              | pass / fail          | Running Node meets the CLI's minimum                                 |
+| @astryxdesign/core installed | pass / fail          | `@astryxdesign/core` is resolvable from the project                  |
+| Version alignment            | pass / warn / info   | Installed `@astryxdesign/core` is in step with `@astryxdesign/cli`   |
+| Theme packages               | pass / warn          | An `@astryxdesign/theme-*` package is installed and a theme is wired |
+| astryx.config.mjs            | pass / fail / info   | Config (if present) loads cleanly with a valid shape                 |
+| AI agent docs                | pass / warn / info   | Agent docs exist and contain the XDS section markers                 |
+| Peer dependencies            | pass / warn / info   | `@astryxdesign/core`'s peer deps (react, …) are installed            |
+| Package manager              | info                 | Reports the detected package manager                                 |
 
 ### CI gate
 

package/bin/astryx.mjs

@@ -12,10 +12,25 @@
 //
 // `node-version.mjs` is intentionally dependency-free so it loads on the
 // unsupported runtimes this guard protects against.
-import {
-  isNodeVersionSupported,
-  unsupportedNodeMessage,
-} from '../src/lib/node-version.mjs';
+//
+// Sibling `src/` modules are resolved by this bin's REAL path. When the CLI is
+// installed as a package, `npx astryx` runs this file through the
+// `node_modules/.bin/astryx` symlink, and some Node versions resolve relative
+// specifiers from the symlink's directory (→ `node_modules/src/...`) rather
+// than the real package — breaking bare `../src/...` imports with a cryptic
+// ERR_MODULE_NOT_FOUND. realpath-ing `import.meta.url` makes these imports
+// resolve correctly however the bin is invoked (symlink, copy, or Windows
+// shim). Uses only built-ins, so the version gate below still runs first.
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {realpathSync} from 'node:fs';
+import {dirname, join} from 'node:path';
+
+const binDir = dirname(realpathSync(fileURLToPath(import.meta.url)));
+const importSrc = rel =>
+  import(pathToFileURL(join(binDir, '..', 'src', rel)).href);
+
+const {isNodeVersionSupported, unsupportedNodeMessage} =
+  await importSrc('lib/node-version.mjs');
 
 if (!isNodeVersionSupported(process.versions.node)) {
   const msg = unsupportedNodeMessage(process.versions.node);
@@ -39,9 +54,9 @@ if (!isNodeVersionSupported(process.versions.node)) {
 
 // Imports that transitively load `styleText` must happen AFTER the gate above,
 // so they are dynamically imported here rather than at the top of the module.
-const {program} = await import('../src/index.mjs');
-const {isJsonMode, toErrorEnvelope} = await import('../src/lib/json.mjs');
-const {handleCommanderError} = await import('../src/lib/json-shim.mjs');
+const {program} = await importSrc('index.mjs');
+const {isJsonMode, toErrorEnvelope} = await importSrc('lib/json.mjs');
+const {handleCommanderError} = await importSrc('lib/json-shim.mjs');
 
 /**
  * Top-level error boundary (contract guarantee #4): an uncaught throw must

package/docs/getting-started.doc.mjs

@@ -88,7 +88,7 @@ import {VStack} from '@astryxdesign/core/Layout';
 export default function Page() {
   return (
     <VStack gap={2}>
-      <Button label="Hello XDS" onClick={() => alert('Hi!')} />
+      <Button label="Hello Astryx" onClick={() => alert('Hi!')} />
     </VStack>
   );
 }`,
@@ -96,11 +96,11 @@ export default function Page() {
       ],
     },
     {
-      title: 'Customize with xstyle',
+      title: 'Customize with StyleX',
       content: [
         {
           type: 'prose',
-          text: 'Every component accepts an `xstyle` prop for StyleX style overrides created via `stylex.create()`.',
+          text: 'Astryx components support various styling solutions, from plain CSS and `className` to Tailwind and CSS-in-JS. See the [styling docs](/docs/styling) for the full guide. Astryx also has a deep integration with [StyleX](https://stylexjs.com/), an atomic CSS-in-JS library: create styles with `stylex.create()` and pass them to components with the `xstyle` prop.',
         },
         {
           type: 'code',
@@ -127,19 +127,19 @@ const overrides = stylex.create({
           type: 'table',
           headers: ['Example', 'Stack', 'Path'],
           rows: [
-            ['Next.js', 'Next.js + theme CSS', 'apps/example-nextjs'],
-            ['Next.js + StyleX', 'Next.js + StyleX for custom styles', 'apps/example-nextjs-stylex'],
-            ['Next.js + Tailwind', 'Next.js + Tailwind bridge', 'apps/example-nextjs-tailwind'],
-            ['Next.js Source', 'Next.js importing from source', 'apps/example-nextjs-source'],
-            ['Vite', 'Vite', 'apps/example-vite'],
+            ['Next.js', 'Next.js + theme CSS', '[apps/example-nextjs](https://github.com/facebook/astryx/tree/main/apps/example-nextjs)'],
+            ['Next.js + StyleX', 'Next.js + StyleX for custom styles', '[apps/example-nextjs-stylex](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-stylex)'],
+            ['Next.js + Tailwind', 'Next.js + Tailwind bridge', '[apps/example-nextjs-tailwind](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-tailwind)'],
+            ['Next.js Source', 'Next.js importing from source', '[apps/example-nextjs-source](https://github.com/facebook/astryx/tree/main/apps/example-nextjs-source)'],
+            ['Vite', 'Vite', '[apps/example-vite](https://github.com/facebook/astryx/tree/main/apps/example-vite)'],
           ],
         },
         {
           type: 'code',
           lang: 'bash',
           label: 'Clone and run an example',
-          code: `git clone https://github.com/facebookexperimental/xds.git
-cd xds/apps/example-nextjs
+          code: `git clone https://github.com/facebook/astryx.git
+cd astryx/apps/example-nextjs
 pnpm install
 pnpm dev`,
         },
@@ -157,7 +157,7 @@ pnpm dev`,
           lang: 'json',
           label: 'package.json',
           code: `"scripts": {
-  "xds": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
+  "astryx": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
 }`,
         },
         {

package/docs/icons.doc.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Icons reference doc: semantic icon names available in XDS
+ * @file Icons reference doc: semantic icon names available in Astryx
  */
 
 /** @type {import('../../core/src/docs-types').ReferenceDoc} */

package/docs/migration.doc.mjs

@@ -234,7 +234,7 @@ export function AppRoot({children}: {children: React.ReactNode}) {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: `We are migrating this existing Tailwind/shadcn app to XDS incrementally.
+          code: `We are migrating this existing Tailwind/shadcn app to Astryx incrementally.
 
 First run:
 - npx astryx docs migration --dense
@@ -242,7 +242,7 @@ First run:
 - 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 XDS components, remove hardcoded colors, verify light and dark mode, and take screenshots before moving to the next surface.`,
+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/shape.doc.mjs

@@ -44,7 +44,7 @@ export const docs = {
           type: 'code',
           lang: 'css',
           label: 'Concentric radius formula',
-          code: `/* Automatic in XDS Card */
+          code: `/* Automatic in Astryx Card */
 --card-concentric-radius: max(0px, calc(var(--_card-radius) - var(--card-padding)));`,
         },
       ],

package/docs/styling.doc.mjs

@@ -22,9 +22,8 @@ export const docs = {
           type: 'table',
           headers: ['Approach', 'Use for', 'Example'],
           rows: [
-            ['xstyle prop', 'Overriding a specific component', 'xstyle={styles.override}'],
+            ['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"'],
-            ['stylex.create', 'Reusable styles, pseudo-classes, typed tokens', 'stylex.create({ card: { ... } })'],
             ['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)'"],
           ],
@@ -232,7 +231,7 @@ const overrides = stylex.create({
       content: [
         {
           type: 'prose',
-          text: 'When external CSS needs to target an XDS component by prop or state, combine the stable component class with reflected data attributes. The component class identifies the component (`.astryx-button`, `.astryx-card`); data attributes identify the axis and value (`data-variant`, `data-size`, `data-level`, etc.). This is the preferred selector surface for new CSS because it is explicit and collision-resistant.',
+          text: 'When external CSS needs to target an Astryx component by prop or state, combine the stable component class with reflected data attributes. The component class identifies the component (`.astryx-button`, `.astryx-card`); data attributes identify the axis and value (`data-variant`, `data-size`, `data-level`, etc.). This is the preferred selector surface for new CSS because it is explicit and collision-resistant.',
         },
         {
           type: 'code',
@@ -274,7 +273,7 @@ const overrides = stylex.create({
       content: [
         {
           type: 'prose',
-          text: 'XDS still emits legacy bare prop/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked` for compatibility with existing apps and built themes. Do not write new CSS against these bare classes. The stable base component classes (`.astryx-button`, `.astryx-card`, etc.) are not deprecated; only the unprefixed prop/state classes are the legacy surface.',
+          text: 'Astryx still emits legacy bare prop/state classes such as `.primary`, `.sm`, `.level-2`, and `.checked` for compatibility with existing apps and built themes. Do not write new CSS against these bare classes. The stable base component classes (`.astryx-button`, `.astryx-card`, etc.) are not deprecated; only the unprefixed prop/state classes are the legacy surface.',
         },
         {
           type: 'code',

package/docs/theme.doc.dense.mjs

@@ -5,8 +5,8 @@
 export const docsDense = {
   description: 'Theme provider, custom themes, light/dark, component overrides',
   sections: [
-    { title: 'Quick Start', content: [null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },
-    { title: 'Themes', content: [null, { type: 'prose', text: 'published: neutral (start here), butter, chocolate, gothic (dark-only), matcha, stone, y2k. @astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },
+    { title: 'Quick Start', content: [null, null, null, null, { type: 'prose', text: 'default import = runtime injection. /built import = pre-compiled CSS (pair with theme.css).' }] },
+    { title: 'Themes', content: [null, null, { type: 'prose', text: 'published: neutral (start here), butter, chocolate, gothic (dark-only), matcha, stone, y2k. @astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ theme.css).' }] },
     { title: 'Props', content: [null] },
     { title: 'Custom Theme', content: [{ type: 'prose', text: 'CLI wizard or manual defineTheme. only override tokens that differ.' }, null] },
     { 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] },

package/docs/theme.doc.mjs

@@ -14,6 +14,12 @@ export const docs = {
       title: 'Quick Start',
   category: 'guide',
       content: [
+        {
+          type: 'code',
+          lang: 'bash',
+          label: 'Install a theme package',
+          code: 'npm install @astryxdesign/theme-neutral',
+        },
         {
           type: 'code',
           lang: 'tsx',
@@ -45,6 +51,10 @@ function App() {
   );
 }`,
         },
+        {
+          type: 'prose',
+          text: 'Each theme ships as its own npm package. Install the one you want, then wrap your app in `<Theme>` — the same pattern works for every theme; just swap the package and import name.',
+        },
         {
           type: 'prose',
           text: 'The default import uses runtime style injection, which works everywhere with no build step. The `/built` import skips injection and relies on the pre-compiled CSS file for better performance and SSR support.',
@@ -55,6 +65,10 @@ function App() {
       title: 'Available Themes',
   category: 'guide',
       content: [
+        {
+          type: 'prose',
+          text: 'Install the theme package you want with `npm install @astryxdesign/theme-{name}`, then import its theme object as shown below.',
+        },
         {
           type: 'table',
           headers: ['Theme', 'Import', 'Description'],

package/docs/theme.doc.zh.mjs

@@ -5,8 +5,8 @@
 export const docsZh = {
   description: 'Theme 提供者、自定义主题、亮/暗模式和组件样式覆盖。',
   sections: [
-    { title: '快速开始', content: [null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS（需配合 theme.css）。' }] },
-    { title: '可用主题', content: [null, { type: 'prose', text: '已发布主题：neutral（推荐起点）、butter、chocolate、gothic（仅暗色）、matcha、stone、y2k。@astryxdesign/theme-{name} = 源码版（运行时注入）。@astryxdesign/theme-{name}/built = 优化版（配合 theme.css）。' }] },
+    { title: '快速开始', content: [null, null, null, null, { type: 'prose', text: '默认导入使用运行时样式注入。/built 导入使用预编译 CSS（需配合 theme.css）。' }] },
+    { title: '可用主题', content: [null, null, { type: 'prose', text: '已发布主题：neutral（推荐起点）、butter、chocolate、gothic（仅暗色）、matcha、stone、y2k。@astryxdesign/theme-{name} = 源码版（运行时注入）。@astryxdesign/theme-{name}/built = 优化版（配合 theme.css）。' }] },
     { title: 'Theme 属性', content: [null] },
     { title: '创建自定义主题', content: [{ type: 'prose', text: '使用 CLI 向导（推荐）或手动 defineTheme。只覆盖与默认值不同的令牌。' }, null] },
     { title: 'defineTheme', content: [{ type: 'prose', text: '支持比例配置（typography、radius、motion）+ 显式令牌覆盖 + 组件覆盖。' }, null, null] },

package/docs/working-with-ai.doc.mjs

@@ -34,7 +34,7 @@ export const docs = {
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: 'Install @astryxdesign/cli and run `npx astryx agent-docs` to set up your XDS context. Read the generated file.',
+          code: 'Install @astryxdesign/cli and run `npx astryx agent-docs` to set up your Astryx context. Read the generated file.',
         },
         {
           type: 'prose',
@@ -103,7 +103,7 @@ npx astryx agent-docs --agent-docs-path ~/.cursor/rules/xds.mdc`,
           type: 'code',
           lang: 'text',
           label: 'Paste this into your AI',
-          code: `Before writing any XDS code, check your knowledge:
+          code: `Before writing any Astryx code, check your knowledge:
 
 1. What is the correct import path for Button?
 2. How do you make an Dialog non-dismissible?
@@ -165,7 +165,7 @@ npx astryx docs tokens --dense`,
       content: [
         {
           type: 'prose',
-          text: 'XDS ships a Model Context Protocol (MCP) server that any MCP-compatible AI tool can connect to. Instead of manually pasting CLI output, the AI can query the XDS design system directly, searching for components, reading full documentation, and pulling code examples on demand.',
+          text: 'Astryx ships a Model Context Protocol (MCP) server that any MCP-compatible AI tool can connect to. Instead of manually pasting CLI output, the AI can query the Astryx design system directly, searching for components, reading full documentation, and pulling code examples on demand.',
         },
         {
           type: 'prose',
@@ -183,7 +183,7 @@ npx astryx docs tokens --dense`,
   "mcpServers": {
     "xds": {
       "type": "url",
-      "url": "https://astryx.meta.com/mcp"
+      "url": "https://astryx.atmeta.com/mcp"
     }
   }
 }`,