@astryxdesign/cli 0.0.15 → 0.1.0-canary.0b5b49f

package/CHANGELOG.md

@@ -1,5 +1,93 @@
 # @xds/cli
 
+# 0.1.0
+
+#### Breaking Changes
+
+- Read project config from `astryx.config.mjs` (was `xds.config.mjs`)
+  The CLI now resolves its optional project config from `astryx.config.mjs`
+  instead of `xds.config.mjs` — a hard cut, no fallback. Consumers with an
+  `xds.config.mjs` must rename it to `astryx.config.mjs` (the config shape and
+  all fields are unchanged). Part of removing `xds` naming from the public API.
+- Rename the CLI command/bin from `xds` to `astryx`
+  The CLI binary is now `astryx` (was `xds`); `bin/xds.mjs` is renamed to
+  `bin/astryx.mjs`, the dual `xds`+`astryx` bin entries collapse to a single
+  `astryx`, and the program/manifest name is `astryx`. Invoke the CLI as
+  `npx astryx <command>` (e.g. `npx astryx component Button`). The swizzle
+  default output dir moves from `./components/xds` to `./components/astryx`.
+  Consumers using `npx xds`, an `xds` npm-script alias, or the `xds` MCP server
+  name should switch to `astryx`. Part of removing `xds` naming from the public API.
+- Rename the exported `XDSError` class to `AstryxError`
+  The CLI's programmatic API error class is renamed `XDSError` -> `AstryxError`
+  (exported from `@xds/cli` + declared in its types). Consumers that catch or
+  reference `XDSError` from the CLI's API should switch to `AstryxError`. Part of
+  removing `xds` naming from the public API.
+- Remove the XDS-prefix compatibility layer — astryx is now the only public surface
+  This release erases all `xds` naming from the public API; there is no compatibility
+  window. Consumers must migrate (we own all consumers pre-OSS):
+- Remove the daily, brutalist, and default themes; neutral is the new baseline
+  Three theme packages are removed from the repo and will no longer be published:
+
+#### Fixes
+
+- `theme build` generates valid bare type imports (IconRegistry/DefinedTheme)
+  `astryx theme build` emitted `.d.ts` files importing `XDSIconRegistry` /
+  `XDSDefinedTheme` from `@xds/core`, but those aliases were removed — the
+  generated types failed to resolve. Generate `IconRegistry` / `DefinedTheme`
+  (the bare names `@xds/core` now exports) instead.
+
+#### Documentation
+
+- Update CLI theme docs to the current theme set
+  Refreshes the `astryx docs theme`, `getting-started`, `styling`,
+  `styling-libraries`, and `migration` reference docs to reflect the published
+  themes: `neutral`, `butter`, `chocolate`, `gothic`, `matcha`, `stone`, and
+  `y2k`. The removed `theme-default`, `theme-brutalist`, and `theme-daily`
+  packages are dropped from the docs, and install/import examples now use
+  `@astryxdesign/theme-neutral` as the recommended starting theme.
+
+#### Other Changes
+
+- **Component names:** the `XDS*` aliases are gone — use bare names (`Button` not
+  `XDSButton`, `useTheme` not `useXDSTheme`, `ButtonProps` not `XDSButtonProps`). The
+  `drop-xds-prefix-imports` codemod automates this.
+- **CSS classes:** components emit only `.astryx-*` (the dual `.xds-*` class is gone).
+  Update custom CSS selectors `.xds-button` -> `.astryx-button` (prop/state value classes
+  like `.primary`/`.sm` are unchanged).
+- **data attributes:** only `data-astryx-theme` / `data-astryx-media` are written; update
+  custom selectors and SSR root attributes off `data-xds-*`.
+- **CSS layers:** `@layer xds-base` / `xds-theme` are renamed to `astryx-base` /
+  `astryx-theme`; update your `@layer` order line and any PostCSS `layersBefore` config.
+  `@astryxdesign/build`'s default library layer is now `astryx-base`.
+- **Pre-compiled stylesheet:** the `@astryxdesign/core/xds.css` export is removed — import
+  `@astryxdesign/core/astryx.css`.
+- **CSS custom properties:** the `--xds-*` padding fallback is gone; set `--astryx-*`.
+- **CLI config key:** `@astryxdesign/cli` reads the package.json `"astryx"` field (was `"xds"`).
+  Rename the block; a stale `"xds"` key silently drops the package from discovery.
+- `@astryxdesign/theme-daily`
+- `@astryxdesign/theme-brutalist`
+- `@astryxdesign/theme-default`
+- import {defaultTheme} from '@astryxdesign/theme-default/built';
+  - 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/*`
+  All published packages move to the new `@astryxdesign` scope (e.g. `@xds/core` → `@astryxdesign/core`), along with the workspace lockfile, build/runtime scope-directory scans, and docsite slug derivation. Consumers must update their imports and dependency names. The internal ESLint plugin namespace (`@xds/*` rules) is intentionally untouched and tracked separately. Existing `@xds/*` codemods continue to target the old scope so projects still on `@xds/*` can migrate.
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @cixzhang
+- @ejhammond
+
+---
+
 # 0.0.15
 
 #### Breaking Changes

package/README.md

@@ -341,7 +341,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-default`, then import its CSS or set xds.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

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-default, and @astryxdesign/cli in this project. Run `npx astryx 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.',
         },
       ],
     },
@@ -36,7 +36,7 @@ export const docs = {
           type: 'code',
           lang: 'bash',
           label: 'Terminal',
-          code: `npm install @astryxdesign/core @astryxdesign/theme-default @astryxdesign/cli`,
+          code: `npm install @astryxdesign/core @astryxdesign/theme-neutral @astryxdesign/cli`,
         },
         {
           type: 'prose',
@@ -63,11 +63,11 @@ export const docs = {
           label: 'globals.css',
           code: `@import '@astryxdesign/core/reset.css';
 @import '@astryxdesign/core/astryx.css';
-@import '@astryxdesign/theme-default/theme.css';`,
+@import '@astryxdesign/theme-neutral/theme.css';`,
         },
         {
           type: 'prose',
-          text: 'Available themes: @astryxdesign/theme-default (blue accent), @astryxdesign/theme-neutral (grayscale), @astryxdesign/theme-brutalist (zero radius, monospace). See `npx 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.',
         },
       ],
     },
@@ -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/migration.doc.mjs

@@ -91,15 +91,15 @@ npx astryx component Button --json`,
           lang: 'tsx',
           label: 'Root provider with explicit mode',
           code: `import {Theme} from '@astryxdesign/core/theme';
-import {defaultTheme} from '@astryxdesign/theme-default/built';
+import {neutralTheme} from '@astryxdesign/theme-neutral/built';
 import {useState} from 'react';
-import '@astryxdesign/theme-default/theme.css';
+import '@astryxdesign/theme-neutral/theme.css';
 
 export function AppRoot({children}: {children: React.ReactNode}) {
   const [mode, setMode] = useState<'system' | 'light' | 'dark'>('system');
 
   return (
-    <Theme theme={defaultTheme} mode={mode}>
+    <Theme theme={neutralTheme} mode={mode}>
       <SettingsContext.Provider value={{mode, setMode}}>
         {children}
       </SettingsContext.Provider>
@@ -121,7 +121,7 @@ export function AppRoot({children}: {children: React.ReactNode}) {
 @import "tailwindcss/preflight.css" layer(base);
 @import "@astryxdesign/core/reset.css";
 @import "@astryxdesign/core/astryx.css";
-@import "@astryxdesign/theme-default/theme.css";
+@import "@astryxdesign/theme-neutral/theme.css";
 @import "@astryxdesign/core/tailwind-theme.css";
 @import "tailwindcss/utilities.css" layer(utilities);`,
         },

package/docs/styling-libraries.doc.mjs

@@ -162,7 +162,7 @@ const styles = stylex.create({
 @import "tailwindcss/preflight.css" layer(base);
 @import "@astryxdesign/core/reset.css";
 @import "@astryxdesign/core/astryx.css";
-@import "@astryxdesign/theme-default/theme.css";
+@import "@astryxdesign/theme-neutral/theme.css";
 @import "@astryxdesign/core/tailwind-theme.css";
 @import "tailwindcss/utilities.css" layer(utilities);`,
         },
@@ -374,9 +374,9 @@ tokens: {
           lang: 'ts',
           label: 'Resolve tokens without React context',
           code: `import {resolveThemeTokens} from '@astryxdesign/core/theme/tokens';
-import {defaultTheme} from '@astryxdesign/theme-default';
+import {neutralTheme} from '@astryxdesign/theme-neutral';
 
-const tokens = resolveThemeTokens(defaultTheme, {mode: 'light'});
+const tokens = resolveThemeTokens(neutralTheme, {mode: 'light'});
 
 const chartOptions = {
   textColor: tokens['--color-text-primary'],

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)'"],
           ],
@@ -104,7 +103,7 @@ const overrides = stylex.create({
 @import "tailwindcss/preflight.css" layer(base);
 @import "@astryxdesign/core/reset.css";
 @import "@astryxdesign/core/astryx.css";
-@import "@astryxdesign/theme-default/theme.css";
+@import "@astryxdesign/theme-neutral/theme.css";
 @import "@astryxdesign/core/tailwind-theme.css";
 @import "tailwindcss/utilities.css" layer(utilities);`,
         },

package/docs/theme.doc.dense.mjs

@@ -6,7 +6,7 @@ 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: '@astryxdesign/theme-{name} = source (runtime). @astryxdesign/theme-{name}/built = optimized (+ 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: '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

@@ -19,11 +19,11 @@ export const docs = {
           lang: 'tsx',
           label: 'Basic theme setup (runtime injection)',
           code: `import {Theme} from '@astryxdesign/core';
-import {defaultTheme} from '@astryxdesign/theme-default';
+import {neutralTheme} from '@astryxdesign/theme-neutral';
 
 function App() {
   return (
-    <Theme theme={defaultTheme}>
+    <Theme theme={neutralTheme}>
       <YourApp />
     </Theme>
   );
@@ -34,12 +34,12 @@ function App() {
           lang: 'tsx',
           label: 'Optimized setup (pre-built CSS)',
           code: `import {Theme} from '@astryxdesign/core';
-import {defaultTheme} from '@astryxdesign/theme-default/built';
-import '@astryxdesign/theme-default/theme.css';
+import {neutralTheme} from '@astryxdesign/theme-neutral/built';
+import '@astryxdesign/theme-neutral/theme.css';
 
 function App() {
   return (
-    <Theme theme={defaultTheme}>
+    <Theme theme={neutralTheme}>
       <YourApp />
     </Theme>
   );
@@ -59,20 +59,40 @@ function App() {
           type: 'table',
           headers: ['Theme', 'Import', 'Description'],
           rows: [
-            [
-              'Default',
-              "import {defaultTheme} from '@astryxdesign/theme-default'",
-              'Blue accent, system fonts, light/dark',
-            ],
             [
               'Neutral',
               "import {neutralTheme} from '@astryxdesign/theme-neutral'",
-              'Grayscale, shadcn-inspired',
+              'Muted, minimal aesthetic with system fonts. A good starting point.',
+            ],
+            [
+              'Butter',
+              "import {butterTheme} from '@astryxdesign/theme-butter'",
+              'Golden, buttery surfaces with blue accents; Sarina + Outfit type.',
+            ],
+            [
+              'Chocolate',
+              "import {chocolateTheme} from '@astryxdesign/theme-chocolate'",
+              'Warm brown tones and cozy beige; Fraunces + Albert Sans type.',
+            ],
+            [
+              'Gothic',
+              "import {gothicTheme} from '@astryxdesign/theme-gothic'",
+              'Dark-only atmospheric theme; deep blue-gray surfaces, distressed display type.',
+            ],
+            [
+              'Matcha',
+              "import {matchaTheme} from '@astryxdesign/theme-matcha'",
+              'Earthy green theme with Figtree typography.',
+            ],
+            [
+              'Stone',
+              "import {stoneTheme} from '@astryxdesign/theme-stone'",
+              'Warm stone and slate tones; Montserrat + Figtree type.',
             ],
             [
-              'Brutalist',
-              "import {brutalistTheme} from '@astryxdesign/theme-brutalist'",
-              'Zero radius, monospace, heavy borders',
+              'Y2K',
+              "import {y2kTheme} from '@astryxdesign/theme-y2k'",
+              'Playful Y2K pop; periwinkle body, holographic accents, Poppins + Crimson Text.',
             ],
           ],
         },
@@ -194,14 +214,14 @@ const myTheme = defineTheme({
         {
           type: 'code',
           lang: 'tsx',
-          label: 'Extending the default theme',
+          label: 'Extending the neutral theme',
           code: `import {defineTheme} from '@astryxdesign/core/theme';
-import {defaultTheme} from '@astryxdesign/theme-default';
+import {neutralTheme} from '@astryxdesign/theme-neutral';
 import {myIcons} from './icons';
 
 const brandTheme = defineTheme({
   name: 'brand',
-  extends: defaultTheme,
+  extends: neutralTheme,
   icons: myIcons,
   tokens: {
     '--color-accent': ['#7B61FF', '#9B85FF'],
@@ -525,9 +545,9 @@ const pandaOrEmotionTheme = {
           lang: 'ts',
           label: 'Resolve token values without a hook',
           code: `import {resolveThemeTokens} from '@astryxdesign/core/theme/tokens';
-import {defaultTheme} from '@astryxdesign/theme-default';
+import {neutralTheme} from '@astryxdesign/theme-neutral';
 
-const lightTokens = resolveThemeTokens(defaultTheme, {mode: 'light'});
+const lightTokens = resolveThemeTokens(neutralTheme, {mode: 'light'});
 const chartTheme = {
   textColor: lightTokens['--color-text-primary'],
   seriesColor: lightTokens['--color-data-categorical-blue'],

package/docs/theme.doc.zh.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.0.15",
+  "version": "0.1.0-canary.0b5b49f",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -50,13 +50,13 @@
   "dependencies": {
     "@clack/prompts": "^1.5.1",
     "commander": "^12.1.0",
-    "jiti": "^2.7.0"
+    "jiti": "^2.7.0",
+    "jscodeshift": "^17.3.0"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-default": "*",
-    "@astryxdesign/theme-neutral": "*"
+    "@astryxdesign/core": "0.1.0-canary.0b5b49f",
+    "@astryxdesign/lab": "0.1.0-canary.0b5b49f",
+    "@astryxdesign/theme-neutral": "0.1.0-canary.0b5b49f"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {
@@ -65,18 +65,14 @@
     "@astryxdesign/lab": {
       "optional": true
     },
-    "@astryxdesign/theme-default": {
-      "optional": true
-    },
     "@astryxdesign/theme-neutral": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "*",
-    "@astryxdesign/lab": "*",
-    "@astryxdesign/theme-default": "*",
-    "@astryxdesign/theme-neutral": "*"
+    "@astryxdesign/core": "0.1.0-canary.0b5b49f",
+    "@astryxdesign/lab": "0.1.0-canary.0b5b49f",
+    "@astryxdesign/theme-neutral": "0.1.0-canary.0b5b49f"
   },
   "scripts": {
     "astryx": "node bin/astryx.mjs",

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-default`, then import its CSS or set xds.theme.',
+      fix: 'Install a theme, e.g. `npm install @astryxdesign/theme-neutral`, then import its CSS or set xds.theme.',
     };
   }
 
@@ -355,8 +355,8 @@ export function checkAgentDocs(ctx) {
     try {
       const content = fs.readFileSync(path.join(ctx.cwd, rel), 'utf-8');
       return (
-        content.includes('<!-- XDS:START -->') &&
-        content.includes('<!-- XDS:END -->')
+        (content.includes('<!-- ASTRYX:START -->') || content.includes('<!-- XDS:START -->')) &&
+        (content.includes('<!-- ASTRYX:END -->') || content.includes('<!-- XDS:END -->'))
       );
     } catch {
       return false;
@@ -368,7 +368,7 @@ export function checkAgentDocs(ctx) {
       id: 'agent-docs',
       label: 'AI agent docs',
       status: 'warn',
-      message: `Agent docs present (${present.join(', ')}) but no XDS section markers found.`,
+      message: `Agent docs present (${present.join(', ')}) but no Astryx section markers found.`,
       fix: 'Add the XDS section to your agent docs with `astryx init --features agents`.',
     };
   }

package/src/commands/agent-docs.mjs

@@ -31,8 +31,11 @@ const AGENTS_MD = 'AGENTS.md';
 const CLAUDE_MD = 'CLAUDE.md';
 const CLAUDE_DIR_MD = path.join('.claude', 'CLAUDE.md');
 
-const XDS_MARKER_START = '<!-- XDS:START -->';
-const XDS_MARKER_END = '<!-- XDS:END -->';
+const MARKER_START = '<!-- ASTRYX:START -->';
+const MARKER_END = '<!-- ASTRYX:END -->';
+// Legacy markers — read during migration so the script finds existing XDS blocks
+const LEGACY_MARKER_START = '<!-- XDS:START -->';
+const LEGACY_MARKER_END = '<!-- XDS:END -->';
 
 /**
  * Agent tool presets — maps tool names to their file search paths.
@@ -99,7 +102,7 @@ export function resolveAgentPaths(targetDir, agent) {
  */
 export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPrefix()} = {}) {
   const run = `${runPrefix} astryx`;
-  const lines = [XDS_MARKER_START];
+  const lines = [MARKER_START];
 
   // Component count from live discovery
   let componentCount = '90+';
@@ -177,7 +180,7 @@ export function generateCompressedIndex(version, {coreDir, runPrefix = getRunPre
   lines.push(`${run} swizzle <Name>            eject source (--gap to report why)`);
   lines.push(`${run} upgrade --apply            codemods after version bump`);
   lines.push(`after @astryxdesign/core bump, always run ${run} upgrade --apply`);
-  lines.push(XDS_MARKER_END);
+  lines.push(MARKER_END);
 
   return lines.join('\n');
 }
@@ -218,14 +221,21 @@ export function injectXdsBlock(filePath, compressedIndex, {createIfMissing = fal
   if (fs.existsSync(filePath)) {
     content = fs.readFileSync(filePath, 'utf-8');
 
-    const startIdx = content.indexOf(XDS_MARKER_START);
-    const endIdx = content.indexOf(XDS_MARKER_END);
+    // Find existing section — try new markers first, fall back to legacy XDS markers
+    let startIdx = content.indexOf(MARKER_START);
+    let endIdx = content.indexOf(MARKER_END);
+    let markerEndLength = MARKER_END.length;
+    if (startIdx === -1) {
+      startIdx = content.indexOf(LEGACY_MARKER_START);
+      endIdx = content.indexOf(LEGACY_MARKER_END);
+      markerEndLength = LEGACY_MARKER_END.length;
+    }
 
     if (startIdx !== -1 && endIdx !== -1) {
       content =
         content.slice(0, startIdx) +
         compressedIndex +
-        content.slice(endIdx + XDS_MARKER_END.length);
+        content.slice(endIdx + markerEndLength);
     } else if (onlyReplace) {
       // File exists but has no Astryx markers — skip it
       return false;
@@ -277,13 +287,20 @@ export function removeXdsBlock(filePath, {deleteIfEmpty = false} = {}) {
   if (!fs.existsSync(filePath)) return false;
 
   let content = fs.readFileSync(filePath, 'utf-8');
-  const startIdx = content.indexOf(XDS_MARKER_START);
-  const endIdx = content.indexOf(XDS_MARKER_END);
+  // Find existing section — try new markers first, fall back to legacy
+  let startIdx = content.indexOf(MARKER_START);
+  let endIdx = content.indexOf(MARKER_END);
+  let markerEndLen = MARKER_END.length;
+  if (startIdx === -1) {
+    startIdx = content.indexOf(LEGACY_MARKER_START);
+    endIdx = content.indexOf(LEGACY_MARKER_END);
+    markerEndLen = LEGACY_MARKER_END.length;
+  }
 
   if (startIdx === -1 || endIdx === -1) return false;
 
   const before = content.slice(0, startIdx).trimEnd();
-  const after = content.slice(endIdx + XDS_MARKER_END.length).trimStart();
+  const after = content.slice(endIdx + markerEndLen).trimStart();
   content = before + (after ? '\n\n' + after : '') + '\n';
 
   if (deleteIfEmpty) {