@astryxdesign/cli 0.1.2-canary.05be2c6 → 0.1.2-canary.071c5bf

package/CHANGELOG.md

@@ -110,6 +110,7 @@ Thanks to everyone who contributed to this release:
 Thanks to everyone who contributed to this release:
 
 - @ejhammond
+- @joeyfarina
 - @josephfarina
 - @nynexman4464
 

package/README.md

@@ -62,7 +62,8 @@ Options:
 | `upgrade`     | Run codemods to migrate between versions                                                             |
 | `theme build` | Compile a defineTheme file to production CSS and JS                                                  |
 | `discover`    | Discover external packages and components                                                            |
-| `doctor`      | Diagnose your Astryx setup and report problems with fixes (CI-friendly via exit code)                |
+| `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
 
@@ -160,6 +161,7 @@ if (isError(result)) {
 | `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)
 
@@ -170,7 +172,7 @@ discriminators each command can emit. Think of it as an OpenAPI spec for the CLI
 
 ```bash
 astryx manifest --json        # dedicated surface — type: "manifest"
-astryx --json                 # bare invocation — embeds the same payload under data.manifest
+xds --json                 # bare invocation — embeds the same payload under data.manifest
 ```
 
 Shape:
@@ -180,7 +182,7 @@ Shape:
   "apiVersion": 1,
   "type": "manifest",
   "data": {
-    "name": "astryx",
+    "name": "xds",
     "version": "0.0.14",
     "description": "Design system CLI — components, themes, and tooling",
     "globalOptions": [
@@ -247,14 +249,14 @@ the `JSON_SUPPORTED` allowlist and a small declarative `RESPONSE_TYPES` map in
 `src/lib/manifest.mjs`, guarded by a drift test (`manifest.test.mjs`) so adding a
 command without describing it fails CI.
 
-**Backwards-compat:** the bare `astryx --json` envelope keeps `type: "help"` and its
+**Backwards-compat:** the bare `xds --json` envelope keeps `type: "help"` and its
 original shallow fields (`name`, `version`, `commands` as a `string[]` of names,
 `jsonSupported`); the full structured manifest is additive under `data.manifest`.
 For the standalone manifest envelope (`type: "manifest"`), use `astryx manifest --json`.
 
 ## Programmatic API
 
-The same logic that powers `astryx --json` is available as importable, type-safe functions:
+The same logic that powers `xds --json` is available as importable, type-safe functions:
 
 ```typescript
 import {
@@ -267,20 +269,20 @@ import {
   AstryxError,
 } from '@astryxdesign/cli/api';
 
-// Same result as: astryx --json component Button
+// Same result as: xds --json component Button
 const btn = await component('Button');
 btn.type; // 'component.detail'
 btn.data.name; // 'Button' (typed as ComponentDoc)
 
-// Same result as: astryx --json component --list
+// Same result as: xds --json component --list
 const list = await component(undefined, {list: true});
 list.data; // Record<string, string[]>
 
-// Same result as: astryx --json docs principles
+// Same result as: xds --json docs principles
 const principles = await docs('principles');
-principles.data.title; // 'Principles'
+principles.data.title; // 'XDS Principles'
 
-// Same result as: astryx --json hook useMediaQuery
+// Same result as: xds --json hook useMediaQuery
 const useMediaQuery = await hook('useMediaQuery');
 useMediaQuery.data.params; // typed as HookParamDoc[]
 
@@ -294,7 +296,7 @@ try {
 }
 ```
 
-The CLI command handlers are thin wrappers around these functions: they parse args, call the API, then format the output (JSON or text). This guarantees that `@astryxdesign/cli/api` and `astryx --json` always return identical data.
+The CLI command handlers are thin wrappers around these functions: they parse args, call the API, then format the output (JSON or text). This guarantees that `@astryxdesign/cli/api` and `xds --json` always return identical data.
 
 ### Consumer utilities
 
@@ -324,41 +326,43 @@ detail.data.name; // already narrowed
 
 Every response has a `type` string that uniquely identifies it:
 
-| Command                                           | Type                        | Response                          |
-| ------------------------------------------------- | --------------------------- | --------------------------------- |
-| `astryx --json component [--list]`                | `component.list`            | `ComponentListResponse`           |
-| `astryx --json component --list --detail compact` | `component.brief`           | `ComponentBriefResponse`          |
-| `astryx --json component --list --detail full`    | `component.full`            | `ComponentFullResponse`           |
-| `astryx --json component <name>`                  | `component.detail`          | `ComponentDetailResponse`         |
-| `astryx --json component <name> --props`          | `component.detail.props`    | `ComponentDetailPropsResponse`    |
-| `astryx --json component <name> --source`         | `component.detail.source`   | `ComponentDetailSourceResponse`   |
-| `astryx --json component <name> --showcase`       | `component.detail.showcase` | `ComponentDetailShowcaseResponse` |
-| `astryx --json component <name> --blocks`         | `component.detail.blocks`   | `ComponentDetailBlocksResponse`   |
-| `astryx --json discover`                          | `discover.list`             | `DiscoverListResponse`            |
-| `astryx --json discover @scope/name`              | `discover.detail`           | `DiscoverDetailResponse`          |
-| `astryx --json discover @scope/name/Comp`         | `discover.detail.doc`       | `DiscoverDetailDocResponse`       |
-| `astryx --json discover <search>`                 | `discover.search`           | `DiscoverSearchResponse`          |
-| `astryx --json docs`                              | `docs.list`                 | `DocsListResponse`                |
-| `astryx --json docs <topic>`                      | `docs.detail`               | `DocsDetailResponse`              |
-| `astryx --json docs <topic> <section>`            | `docs.detail.section`       | `DocsDetailSectionResponse`       |
-| `astryx --json template [--list]`                 | `template.list`             | `TemplateListResponse`            |
-| `astryx --json template <name>`                   | `template.show`             | `TemplateShowResponse`            |
-| `astryx --json template <name> --skeleton`        | `template.skeleton`         | `TemplateSkeletonResponse`        |
-| `astryx --json template <name> [path]`            | `template.copy`             | `TemplateCopyResponse`            |
-| `astryx --json hook [--list]`                     | `hook.list`                 | `HookListResponse`                |
-| `astryx --json hook --list --detail compact`      | `hook.brief`                | `HookBriefResponse`               |
-| `astryx --json hook --list --detail full`         | `hook.full`                 | `HookFullResponse`                |
-| `astryx --json hook <name>`                       | `hook.detail`               | `HookDetailResponse`              |
-| `astryx --json hook <name> --params`              | `hook.detail.params`        | `HookDetailParamsResponse`        |
-| `astryx --json search <query>`                    | `search`                    | `SearchResponse`                  |
-| `astryx --json swizzle [--list]`                  | `swizzle.list`              | `SwizzleListResponse`             |
-| `astryx --json swizzle <component>`               | `swizzle.copy`              | `SwizzleCopyResponse`             |
-| `astryx --json theme build <file>`                | `theme.build`               | `ThemeBuildResponse`              |
-| `astryx --json upgrade --list`                    | `upgrade.list`              | `UpgradeListResponse`             |
-| `astryx --json upgrade [--apply]`                 | `upgrade.run`               | `UpgradeRunResponse`              |
-| `astryx --json doctor`                            | `doctor`                    | `DoctorResponse`                  |
-| any error                                         | —                           | `CLIError`                        |
-| unsupported command                               | —                           | `CLIUnsupportedError`             |
+| Command                                        | Type                        | Response                          |
+| ---------------------------------------------- | --------------------------- | --------------------------------- |
+| `xds --json component [--list]`                | `component.list`            | `ComponentListResponse`           |
+| `xds --json component --list --detail compact` | `component.brief`           | `ComponentBriefResponse`          |
+| `xds --json component --list --detail full`    | `component.full`            | `ComponentFullResponse`           |
+| `xds --json component <name>`                  | `component.detail`          | `ComponentDetailResponse`         |
+| `xds --json component <name> --props`          | `component.detail.props`    | `ComponentDetailPropsResponse`    |
+| `xds --json component <name> --source`         | `component.detail.source`   | `ComponentDetailSourceResponse`   |
+| `xds --json component <name> --showcase`       | `component.detail.showcase` | `ComponentDetailShowcaseResponse` |
+| `xds --json component <name> --blocks`         | `component.detail.blocks`   | `ComponentDetailBlocksResponse`   |
+| `xds --json discover`                          | `discover.list`             | `DiscoverListResponse`            |
+| `xds --json discover @scope/name`              | `discover.detail`           | `DiscoverDetailResponse`          |
+| `xds --json discover @scope/name/Comp`         | `discover.detail.doc`       | `DiscoverDetailDocResponse`       |
+| `xds --json discover <search>`                 | `discover.search`           | `DiscoverSearchResponse`          |
+| `xds --json docs`                              | `docs.list`                 | `DocsListResponse`                |
+| `xds --json docs <topic>`                      | `docs.detail`               | `DocsDetailResponse`              |
+| `xds --json docs <topic> <section>`            | `docs.detail.section`       | `DocsDetailSectionResponse`       |
+| `xds --json template [--list]`                 | `template.list`             | `TemplateListResponse`            |
+| `xds --json template <name>`                   | `template.show`             | `TemplateShowResponse`            |
+| `xds --json template <name> --skeleton`        | `template.skeleton`         | `TemplateSkeletonResponse`        |
+| `xds --json template <name> [path]`            | `template.copy`             | `TemplateCopyResponse`            |
+| `xds --json hook [--list]`                     | `hook.list`                 | `HookListResponse`                |
+| `xds --json hook --list --detail compact`      | `hook.brief`                | `HookBriefResponse`               |
+| `xds --json hook --list --detail full`         | `hook.full`                 | `HookFullResponse`                |
+| `xds --json hook <name>`                       | `hook.detail`               | `HookDetailResponse`              |
+| `xds --json hook <name> --params`              | `hook.detail.params`        | `HookDetailParamsResponse`        |
+| `xds --json search <query>`                    | `search`                    | `SearchResponse`                  |
+| `xds --json swizzle [--list]`                  | `swizzle.list`              | `SwizzleListResponse`             |
+| `xds --json swizzle <component>`               | `swizzle.copy`              | `SwizzleCopyResponse`             |
+| `xds --json theme build <file>`                | `theme.build`               | `ThemeBuildResponse`              |
+| `xds --json upgrade --list`                    | `upgrade.list`              | `UpgradeListResponse`             |
+| `xds --json upgrade [--apply]`                 | `upgrade.run`               | `UpgradeRunResponse`              |
+| `xds --json gap-report --list-categories`      | `gap-report.categories`     | `GapReportCategoriesResponse`     |
+| `xds --json gap-report --component X ...`      | `gap-report.file`           | `GapReportFileResponse`           |
+| `xds --json doctor`                            | `doctor`                    | `DoctorResponse`                  |
+| any error                                      | —                           | `CLIError`                        |
+| unsupported command                            | —                           | `CLIUnsupportedError`             |
 
 ## Doctor
 
@@ -379,7 +383,7 @@ astryx doctor — diagnosing your setup
       @astryxdesign/core v0.0.14 is in step with @astryxdesign/cli v0.0.14.
   ⚠ Theme packages
       No @astryxdesign/theme-* packages are installed.
-      → fix: Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set astryx.theme.
+      → fix: Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set xds.theme.
   ℹ astryx.config.mjs
       No astryx.config.mjs found — using defaults.
   ℹ AI agent docs
@@ -404,7 +408,7 @@ No failures — but review the ⚠ warnings above when you can.
 | 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 Astryx section markers              |
+| 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                                 |
 
@@ -430,6 +434,8 @@ export default {
   templates: {
     get: async id => fetchTemplateFromAPI(id),
   },
-  issuesUrl: 'https://github.com/your-org/your-repo/issues',
+  gapReport: {
+    url: 'https://your-api.com/gaps',
+  },
 };
 ```

package/docs/principles.doc.dense.mjs

@@ -6,9 +6,9 @@ export const docsDense = {
   description: 'core design principles + rules for the design system',
   sections: [
     { title: 'Philosophy', content: [{ type: 'list', items: ['components over primitives', 'semantic tokens over hardcoded values', 'theme-agnostic code', 'open internals'] }] },
-    { 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'] }] },
+    { title: 'Rules', content: [{ type: 'list', items: ['use components', 'StyleX or Tailwind for styling', 'semantic tokens only', 'CSS vars for colors', 'controlled form inputs', 'useLinkComponent() for navigation'] }] },
     { title: 'Styling', content: [{ type: 'prose', text: 'xstyle prop for component overrides. StyleX or Tailwind for layout. See astryx docs styling.' }] },
-    { 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'] }] },
+    { 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()', 'read docs before inventing props'] }] },
     { title: 'Tokens', content: [{ type: 'prose', text: 'run npx astryx docs tokens for full reference' }] },
   ],
 };

package/docs/principles.doc.mjs

@@ -39,8 +39,6 @@ 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 \`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 \`npx astryx docs styling\`)',
             'Semantic tokens, not hardcoded values (see \`npx astryx docs tokens\`)',
             'CSS custom properties for colors, not hex values',
@@ -76,8 +74,6 @@ 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 \`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',
           ],
         },

package/docs/principles.doc.zh.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.2-canary.05be2c6",
+  "version": "0.1.2-canary.071c5bf",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -75,9 +75,9 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.1.2-canary.05be2c6",
-    "@astryxdesign/lab": "0.1.2-canary.05be2c6",
-    "@astryxdesign/theme-neutral": "0.1.2-canary.05be2c6",
+    "@astryxdesign/core": "0.1.2-canary.071c5bf",
+    "@astryxdesign/lab": "0.1.2-canary.071c5bf",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.071c5bf",
     "gpt-tokenizer": "^2.0.0"
   },
   "peerDependenciesMeta": {
@@ -92,9 +92,9 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "0.1.2-canary.05be2c6",
-    "@astryxdesign/lab": "0.1.2-canary.05be2c6",
-    "@astryxdesign/theme-neutral": "0.1.2-canary.05be2c6",
+    "@astryxdesign/core": "0.1.2-canary.071c5bf",
+    "@astryxdesign/lab": "0.1.2-canary.071c5bf",
+    "@astryxdesign/theme-neutral": "0.1.2-canary.071c5bf",
     "gpt-tokenizer": "^2.0.0"
   },
   "scripts": {

package/src/api/doctor.mjs

@@ -240,7 +240,7 @@ export function checkThemes(ctx) {
       label: 'Theme packages',
       status: 'warn',
       message: 'No @astryxdesign/theme-* packages are installed.',
-      fix: 'Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set astryx.theme.',
+      fix: 'Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set xds.theme.',
     };
   }
 
@@ -354,7 +354,7 @@ export function checkAgentDocs(ctx) {
       label: 'AI agent docs',
       status: 'warn',
       message: `Agent docs present (${present.join(', ')}) but no Astryx section markers found.`,
-      fix: 'Add the Astryx section to your agent docs with `astryx init --features agents`.',
+      fix: 'Add the XDS section to your agent docs with `astryx init --features agents`.',
     };
   }
 
@@ -362,7 +362,7 @@ export function checkAgentDocs(ctx) {
     id: 'agent-docs',
     label: 'AI agent docs',
     status: 'pass',
-    message: `Astryx agent docs section present in ${withMarkers.join(', ')}.`,
+    message: `XDS agent docs section present in ${withMarkers.join(', ')}.`,
   };
 }
 

package/src/api/index.mjs

@@ -21,7 +21,6 @@
 
 export {component} from './component.mjs';
 export {docs} from './docs.mjs';
-export {blog} from './blog.mjs';
 export {discover} from './discover.mjs';
 export {template} from './template.mjs';
 export {themeAdd, listThemes} from './theme-add.mjs';

package/src/codemods/transforms/{v0.1.0 → v0.0.15}/drop-xds-prefix-imports.mjs

@@ -4,23 +4,12 @@
  * @file Codemod: Drop the `XDS` prefix from @xds/core imports and their usages
  *
  * Part of the XDS-prefix migration (P2380608025). Rewrites consumer code from
- * the prefixed names to their bare equivalents:
+ * the prefixed names to the bare compatibility aliases shipped in P1:
  *
  *   XDSButton      -> Button
  *   XDSButtonProps -> ButtonProps
  *   useXDSTheme    -> useTheme
  *   useXDSToast    -> useToast
- *   XDSIconRegistry-> IconRegistry
- *
- * Mandatory in v0.1.0: the prefixed compatibility aliases (which made both
- * prefixed and bare names valid during the 0.0.x compat window) were dropped
- * in v0.1.0, so the un-prefixing is now required for code to keep type-
- * checking against @astryxdesign/core.
- *
- * Ordering: within the v0.1.0 manifest this runs BEFORE
- * migrate-xds-module-specifiers so it still matches `@xds/core` imports (its
- * source matcher) and un-prefixes the identifiers first; the specifier codemod
- * then rewrites the module paths `@xds/*` -> `@astryxdesign/*`.
  *
  * Safety: this codemod ONLY renames identifiers that are imported from
  * `@xds/core` (bare or subpath, e.g. `@xds/core/Button`). It tracks the local
@@ -47,9 +36,9 @@ export const meta = {
   title: 'Drop XDS prefix from @xds/core imports (XDSButton -> Button)',
   description:
     'Rewrites @xds/core imports and their usages from the prefixed names ' +
-    '(XDSButton, useXDSTheme, XDSIconRegistry, XDSButtonProps) to their bare ' +
-    'names (Button, useTheme, IconRegistry, ButtonProps). Only renames ' +
-    'bindings imported from @xds/core, leaving unrelated identifiers untouched.',
+    '(XDSButton, useXDSTheme, XDSButtonProps) to the bare compatibility ' +
+    'aliases (Button, useTheme, ButtonProps). Only renames bindings imported ' +
+    'from @xds/core, leaving unrelated identifiers untouched.',
   pr: '#2880',
 };
 

package/src/codemods/transforms/v0.0.15/index.mjs

@@ -34,6 +34,10 @@ import migrateSelectorChildrenToRenderOption, {
   meta as migrateSelectorChildrenToRenderOptionMeta,
 } from './migrate-selector-children-to-render-option.mjs';
 
+import dropXdsPrefixImports, {
+  meta as dropXdsPrefixImportsMeta,
+} from './drop-xds-prefix-imports.mjs';
+
 export default [
   {
     name: 'rename-date-picker-to-input',
@@ -71,4 +75,13 @@ export default [
     transform: migrateSelectorChildrenToRenderOption,
     meta: migrateSelectorChildrenToRenderOptionMeta,
   },
+  {
+    // XDS-prefix migration (P2380608025). Optional + not tied to a version
+    // bump: consumers run it explicitly during their migration, e.g.
+    //   astryx upgrade --codemod drop-xds-prefix-imports --codemod-only --apply
+    name: 'drop-xds-prefix-imports',
+    transform: dropXdsPrefixImports,
+    meta: dropXdsPrefixImportsMeta,
+    optional: true,
+  },
 ];

package/src/codemods/transforms/v0.1.0/index.mjs

@@ -6,60 +6,14 @@
  * Lists all codemods for the v0.1.0 release in the order they should run.
  */
 
-import dropXdsPrefixImports, {
-  meta as dropXdsPrefixImportsMeta,
-} from './drop-xds-prefix-imports.mjs';
-
 import migrateXdsModuleSpecifiers, {
   meta as migrateXdsModuleSpecifiersMeta,
 } from './migrate-xds-module-specifiers.mjs';
 
-import migrateXdsDeclareModule, {
-  meta as migrateXdsDeclareModuleMeta,
-} from './migrate-xds-declare-module.mjs';
-
-import migrateXdsCssSurfaces, {
-  meta as migrateXdsCssSurfacesMeta,
-} from './migrate-xds-css-surfaces.mjs';
-
 export default [
-  {
-    // XDS-prefix migration (P2380608025). Mandatory in v0.1.0: the release
-    // dropped the prefixed compatibility aliases (useXDSTheme, XDSButton,
-    // XDSIconRegistry, ...), so consumers upgrading from 0.0.x MUST rewrite
-    // prefixed imports to their bare names.
-    //
-    // Ordered BEFORE migrate-xds-module-specifiers so it sees `@xds/core`
-    // imports (its source matcher) and un-prefixes the identifiers first;
-    // the specifier codemod then rewrites the paths to `@astryxdesign/core`.
-    // The runner preserves this array order (see runner.mjs).
-    name: 'drop-xds-prefix-imports',
-    transform: dropXdsPrefixImports,
-    meta: dropXdsPrefixImportsMeta,
-  },
   {
     name: 'migrate-xds-module-specifiers',
     transform: migrateXdsModuleSpecifiers,
     meta: migrateXdsModuleSpecifiersMeta,
   },
-  {
-    // Cleans up TypeScript `declare module "@xds/core/..."` augmentations,
-    // which reference the package by string specifier and so are dead after
-    // the scope rename. Mandatory in v0.1.0. Ordered AFTER the specifier
-    // codemod: it uses the same @xds -> @astryxdesign mapping and repairs an
-    // adjacent surface the specifier codemod does not visit (module-decl ids
-    // are not import/export/require sources).
-    name: 'migrate-xds-declare-module',
-    transform: migrateXdsDeclareModule,
-    meta: migrateXdsDeclareModuleMeta,
-  },
-  {
-    // Rewrites consumer CSS surfaces broken by the v0.1.0 DOM-namespace rename
-    // (core no longer dual-emits `xds-*`): the `.xds-*` class-selector prefix,
-    // `[data-xds-*]` attribute selectors, and `@layer xds-*` layer names all
-    // become their `astryx-*` forms. Mandatory in v0.1.0.
-    name: 'migrate-xds-css-surfaces',
-    transform: migrateXdsCssSurfaces,
-    meta: migrateXdsCssSurfacesMeta,
-  },
 ];

package/src/commands/agent-docs.mjs

@@ -180,9 +180,6 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPre
   // Rules — the top error-preventers.
   lines.push('RULES:');
   lines.push('- No <div> — components do all layout/spacing. Full page → AppShell; sidebar nav → SideNav.');
-  lines.push('- Frame first: pick the shell (AppShell / Layout+LayoutPanel) and budget regions in px BEFORE writing content (`astryx docs layout`).');
-  lines.push('- Dense data = rows (Table, List/Item) edge-to-edge — never Card-wrapped list items. Card = dashboard widgets, galleries, settings groups only.');
-  lines.push('- Status → StatusDot/Token; Badge only for counts and enumerated states, never decoration.');
   // Styling guidance tailored to the project's configured system — never
   // recommend a path that isn't compiled here (xstyle needs the StyleX compiler;
   // utilities need Tailwind). Tokens are always the source of truth.
@@ -210,7 +207,7 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPre
       .sort();
     if (topics.length > 0) lines.push(`  docs <topic>       ${topics.join(', ')}`);
   }
-  lines.push('  swizzle <Name>     eject component source for deep customization');
+  lines.push('  swizzle <Name>     eject component source (--gap reports why)');
   lines.push('  upgrade --apply    run after any @astryxdesign/core bump');
   lines.push(MARKER_END);
 

package/src/commands/build-theme.mjs

@@ -15,7 +15,6 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {pathToFileURL, fileURLToPath} from 'node:url';
-import {spawn} from 'node:child_process';
 import {createJiti} from 'jiti';
 import {getRunPrefix} from '../utils/package-manager.mjs';
 import {
@@ -598,104 +597,6 @@ function validatePrivateVars(themeDef) {
   return errors;
 }
 
-/**
- * Path to this CLI's real entry (bin/astryx.mjs), resolved from this module's
- * location (src/commands/build-theme.mjs → ../../bin/astryx.mjs). Used to
- * re-invoke `theme build` as a child process in watch mode.
- */
-function resolveCliBin() {
-  const commandsDir = path.dirname(fileURLToPath(import.meta.url));
-  return path.resolve(commandsDir, '../../bin/astryx.mjs');
-}
-
-/**
- * Run a single `theme build` as a child process, reusing the exact
- * single-build code path (and its error handling) rather than duplicating it.
- * Resolves with the child's exit code; never rejects.
- *
- * @param {string} file - The theme file argument, as the user passed it.
- * @param {object} options - Parsed command options (only `out` is forwarded).
- * @returns {Promise<number>}
- */
-function runThemeBuildOnceChild(file, options) {
-  const cliBin = resolveCliBin();
-  const args = [cliBin, 'theme', 'build', file];
-  if (options.out) args.push('--out', options.out);
-  return new Promise(resolve => {
-    const child = spawn(process.execPath, args, {
-      stdio: 'inherit',
-      env: process.env,
-    });
-    child.on('close', code => resolve(code ?? 0));
-    child.on('error', () => resolve(1));
-  });
-}
-
-/**
- * Watch a theme file and rebuild on change. Runs an initial build, then
- * rebuilds (debounced) whenever the file changes, until interrupted with
- * Ctrl-C. Each rebuild runs in a child process so a build error (which the
- * single-build path reports via a hard exit) is contained and the watcher
- * keeps running.
- *
- * @param {string} file - The theme file argument, as the user passed it.
- * @param {string} filePath - Absolute path to the theme file.
- * @param {object} options - Parsed command options.
- * @returns {Promise<void>} Resolves when the watcher is stopped (Ctrl-C).
- */
-async function runThemeBuildWatch(file, filePath, options) {
-  const rel = path.relative(process.cwd(), filePath);
-
-  // Initial build.
-  await runThemeBuildOnceChild(file, options);
-
-  humanLog(`\n👀 Watching ${rel} for changes — press Ctrl-C to stop.`);
-
-  let building = false;
-  let queued = false;
-  let debounce = null;
-
-  const rebuild = async () => {
-    if (building) {
-      // Coalesce changes that land mid-build into a single follow-up run.
-      queued = true;
-      return;
-    }
-    building = true;
-    humanLog(`\n♻️  Change detected — rebuilding ${rel}...`);
-    await runThemeBuildOnceChild(file, options);
-    building = false;
-    humanLog(`\n👀 Watching ${rel} for changes — press Ctrl-C to stop.`);
-    if (queued) {
-      queued = false;
-      rebuild();
-    }
-  };
-
-  // Some editors replace the file (rename) rather than writing in place, which
-  // can drop the watch. Watch the containing directory and filter to our file
-  // so edits survive atomic-save/rename.
-  const watchDir = path.dirname(filePath);
-  const baseName = path.basename(filePath);
-  const watcher = fs.watch(watchDir, (_eventType, changed) => {
-    if (changed && changed !== baseName) return;
-    clearTimeout(debounce);
-    // Debounce: editors often emit several events per save.
-    debounce = setTimeout(rebuild, 100);
-  });
-
-  await new Promise(resolve => {
-    const stop = () => {
-      clearTimeout(debounce);
-      watcher.close();
-      humanLog('\nStopped watching.');
-      resolve();
-    };
-    process.once('SIGINT', stop);
-    process.once('SIGTERM', stop);
-  });
-}
-
 export function registerTheme(program) {
   const theme = program
     .command('theme')
@@ -720,10 +621,6 @@ export function registerTheme(program) {
     .command('build <file>')
     .description('Compile a defineTheme file to CSS + JS')
     .option('-o, --out <path>', 'Output CSS file path')
-    .option(
-      '-w, --watch',
-      'Rebuild automatically when the theme file changes (Ctrl-C to stop)',
-    )
     .action(async (file, options) => {
       const filePath = path.resolve(process.cwd(), file);
       const json = program.opts().json || false;
@@ -733,20 +630,6 @@ export function registerTheme(program) {
         return;
       }
 
-      // Watch mode: run an initial build, then rebuild on every change to the
-      // theme file. Watch is a human-interactive, long-running mode — it is not
-      // supported in --json (machine) mode, which expects a single envelope.
-      if (options.watch) {
-        if (json) {
-          cliError('--watch is not supported with --json', {
-            code: ERROR_CODES.ERR_THEME_INVALID,
-          });
-          return;
-        }
-        await runThemeBuildWatch(file, filePath, options);
-        return;
-      }
-
       if (!json) humanLog(`\nBuilding theme from ${path.relative(process.cwd(), filePath)}...`);
 
       // Extract theme definition

package/src/index.mjs

@@ -245,7 +245,6 @@ const commands = [
   {name: 'init', path: './commands/init.mjs', register: 'registerInit'},
   {name: 'component', path: './commands/component/index.mjs', register: 'registerComponent'},
   {name: 'docs', path: './commands/docs.mjs', register: 'registerDocs'},
-  {name: 'blog', path: './commands/blog.mjs', register: 'registerBlog'},
   {name: 'swizzle', path: './commands/swizzle.mjs', register: 'registerSwizzle'},
   // agent-docs folded into init — functions still importable from agent-docs.mjs
   {name: 'template', path: './commands/template.mjs', register: 'registerTemplate'},