Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

refactor(cli): fold agent-docs into init, add --features flag (#639)

Joey10e85e6bd4a5
diff --git a/CLAUDE.md b/CLAUDE.md
index fd46baac38..f2ba05b9e1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -84,21 +84,3 @@ Look for `<!-- SYNC: ... -->` comments and `SYNC:` in file headers as reminders.
- **`@example` code fences must use plain ` ``` `, not ` ```tsx `.**
Storybook's autodocs parser doesn't handle language-tagged fences in JSDoc correctly — the code block won't render as a proper code block. Always use untagged fences in `@example` blocks.
-
-<!-- XDS:START -->
-
-[XDS v0.0.3]|IMPORTANT: Prefer retrieval-led reasoning. Run CLI to read docs before generating code.
-|npx xds --detail compact component <Name> Docs (props, usage) — or --source for code
-|npx xds component --list All components by category
-|npx xds docs principles Design rules, anti-patterns, StyleX patterns
-|npx xds docs tokens Token reference (spacing, color, radius, type)
-|npx xds docs theme Theme system: XDSTheme, custom themes, overrides, nesting
-|npx xds template <name> [path] Scaffold page (blank, table, login)
-|npx xds swizzle <Name> --gap "<reason>" Copy component source for customization + file gap report
-|npx xds gap-report --component <Name> --category <cat> --reason "<why>" File gap without swizzle
-|npx xds upgrade Preview API migrations for your version
-|npx xds upgrade --apply Apply codemods to update breaking API changes
-|RULE: After bumping @xds/core version, ALWAYS run npx xds upgrade --apply to migrate breaking API changes.
-|RULE: When swizzling to unblock yourself, ALWAYS use --gap to explain what capability was missing.
-
-<!-- XDS:END -->
diff --git a/apps/sandbox/README.md b/apps/sandbox/README.md
index 7eb2867004..3dc9f25980 100644
--- a/apps/sandbox/README.md
+++ b/apps/sandbox/README.md
@@ -12,12 +12,12 @@ Before writing any code, install dependencies:
npm install
```
-This automatically generates `AGENTS.md` with the XDS component index via `xds agent-docs`. **Read `AGENTS.md` for all XDS component documentation** — it contains CLI commands to browse components, tokens, themes, and design rules.
+This automatically generates `AGENTS.md` with the XDS component index via `xds init --features agents`. **Read `AGENTS.md` for all XDS component documentation** — it contains CLI commands to browse components, tokens, themes, and design rules.
If `AGENTS.md` is missing, regenerate it:
```bash
-npx xds agent-docs
+npx xds init --features agents
```
## How it works
diff --git a/internal/vibe-tests/scripts/generate-skill-doc.sh b/internal/vibe-tests/scripts/generate-skill-doc.sh
index a3d8af74e3..9203d204cb 100644
--- a/internal/vibe-tests/scripts/generate-skill-doc.sh
+++ b/internal/vibe-tests/scripts/generate-skill-doc.sh
@@ -3,7 +3,7 @@
# @position internal/vibe-tests/scripts/generate-skill-doc.sh
#
# Generates a skill doc by combining CLI outputs:
-# - agent-docs framing (AGENTS.md index)
+# - init --features agents framing (AGENTS.md index)
# - component list --detail brief (component catalog)
# - docs principles (design rules)
# - docs tokens (token reference)
diff --git a/packages/cli/src/commands/init.mjs b/packages/cli/src/commands/init.mjs
index e929703545..179c6dc86e 100644
--- a/packages/cli/src/commands/init.mjs
+++ b/packages/cli/src/commands/init.mjs
@@ -1,21 +1,25 @@
/**
- * @file init command — Interactive initialization wizard
+ * @file init command — Interactive initialization wizard + feature installer
*
- * Orchestrates the full XDS setup flow using @clack/prompts:
- * 1. Intro
- * 2. Agent docs installation
- * 3. Swizzle awareness
- * 4. Template selection
- * 5. Success outro
+ * Interactive: `xds init` walks through all features
+ * Non-interactive: `xds init --features agents,theme,template`
+ * Re-runnable: safe to run multiple times, idempotent
+ *
+ * Features:
+ * agents — Install AGENTS.md/CLAUDE.md cheat sheet for AI coding agents
+ * theme — Scaffold a custom theme file
+ * template — Copy a starter page template
*/
import * as p from '@clack/prompts';
import * as path from 'node:path';
import * as fs from 'node:fs';
import {CLI_ROOT} from '../utils/paths.mjs';
-import {installAgentDocs} from './agent-docs.mjs';
+import {installAgentDocs, removeAgentDocs} from './agent-docs.mjs';
import {listTemplates} from './template.mjs';
+const VALID_FEATURES = ['agents', 'theme', 'template'];
+
function isCancel(value) {
if (p.isCancel(value)) {
p.cancel('Setup cancelled.');
@@ -24,12 +28,155 @@ function isCancel(value) {
return value;
}
+// ─── Feature: agents ─────────────────────────────────────────────────────────
+
+function runAgents(targetDir, {interactive = true} = {}) {
+ try {
+ installAgentDocs(targetDir);
+ if (interactive) {
+ p.log.success('AI agent docs installed');
+ } else {
+ console.log('✓ AI agent docs installed');
+ }
+ } catch {
+ const msg = 'Could not install agent docs. Try again with `npx xds init --features agents`.';
+ if (interactive) {
+ p.log.warning(msg);
+ } else {
+ console.error(msg);
+ }
+ }
+}
+
+// ─── Feature: theme ──────────────────────────────────────────────────────────
+
+async function runTheme({interactive = true} = {}) {
+ if (!interactive) {
+ console.log('✓ Theme scaffolding requires interactive mode. Run `npx xds theme` instead.');
+ return;
+ }
+
+ p.note(
+ 'Create a custom theme with your brand colors.\n' +
+ 'Run `npx xds theme` for the full theme wizard.\n' +
+ 'Run `npx xds theme --list` to see existing themes.',
+ 'Themes',
+ );
+}
+
+// ─── Feature: template ───────────────────────────────────────────────────────
+
+async function runTemplate(targetDir, {interactive = true, templateName} = {}) {
+ const templates = listTemplates();
+ if (templates.length === 0) return;
+
+ if (!interactive) {
+ if (!templateName) {
+ console.log(`✓ Available templates: ${templates.join(', ')}. Use npx xds template <name> [path].`);
+ return;
+ }
+
+ if (!templates.includes(templateName)) {
+ console.error(`Error: Unknown template "${templateName}". Available: ${templates.join(', ')}`);
+ return;
+ }
+
+ const outputDir = path.resolve(targetDir, `./src/pages/${templateName}`);
+ const templateDir = path.join(CLI_ROOT, 'templates', templateName);
+ fs.mkdirSync(outputDir, {recursive: true});
+
+ const files = fs.readdirSync(templateDir);
+ for (const file of files) {
+ const srcPath = path.join(templateDir, file);
+ if (fs.statSync(srcPath).isFile()) {
+ fs.copyFileSync(srcPath, path.join(outputDir, file));
+ }
+ }
+ console.log(`✓ Template created at ${path.relative(targetDir, outputDir)}/`);
+ return;
+ }
+
+ const TEMPLATE_OPTIONS = [
+ {value: 'skip', label: 'Skip — No template'},
+ {value: 'blank', label: 'Blank Page — Minimal scaffold'},
+ {value: 'table', label: 'Table Page — Data table with actions'},
+ {value: 'login', label: 'Login Page — Auth form with inputs'},
+ ];
+
+ const templateChoice = isCancel(
+ await p.select({
+ message: 'Start with a page template?',
+ options: TEMPLATE_OPTIONS,
+ }),
+ );
+
+ if (templateChoice === 'skip') return;
+
+ const targetPath = isCancel(
+ await p.text({
+ message: 'Where should the template be created?',
+ initialValue: `./src/pages/${templateChoice}`,
+ placeholder: `./src/pages/${templateChoice}`,
+ }),
+ );
+
+ const outputDir = path.resolve(targetDir, targetPath);
+ const templateDir = path.join(CLI_ROOT, 'templates', templateChoice);
+
+ fs.mkdirSync(outputDir, {recursive: true});
+
+ const files = fs.readdirSync(templateDir);
+ for (const file of files) {
+ const srcPath = path.join(templateDir, file);
+ if (fs.statSync(srcPath).isFile()) {
+ fs.copyFileSync(srcPath, path.join(outputDir, file));
+ }
+ }
+
+ p.log.success(`Template created at ${path.relative(targetDir, outputDir)}/`);
+}
+
+// ─── Command ─────────────────────────────────────────────────────────────────
+
export function registerInit(program) {
program
.command('init')
- .description('Interactive XDS initialization wizard')
- .action(async () => {
- // Step 1: Intro
+ .description('Initialize XDS in your project')
+ .option('--features <list>', 'Comma-separated features to install (agents, theme, template)')
+ .option('--all', 'Install all features, no prompts')
+ .option('--remove-agents', 'Remove AI agent docs from AGENTS.md/CLAUDE.md')
+ .action(async (options) => {
+ const targetDir = process.cwd();
+
+ // Remove mode
+ if (options.removeAgents) {
+ removeAgentDocs(targetDir);
+ console.log('✓ AI agent docs removed.');
+ return;
+ }
+
+ // Non-interactive: --features or --all
+ if (options.features || options.all) {
+ const features = options.all
+ ? VALID_FEATURES
+ : options.features.split(',').map(f => f.trim().toLowerCase());
+
+ const invalid = features.filter(f => !VALID_FEATURES.includes(f));
+ if (invalid.length > 0) {
+ console.error(`Error: Unknown features: ${invalid.join(', ')}`);
+ console.error(`Valid features: ${VALID_FEATURES.join(', ')}`);
+ process.exit(1);
+ }
+
+ for (const feature of features) {
+ if (feature === 'agents') runAgents(targetDir, {interactive: false});
+ if (feature === 'theme') await runTheme({interactive: false});
+ if (feature === 'template') await runTemplate(targetDir, {interactive: false});
+ }
+ return;
+ }
+
+ // Interactive wizard
p.intro('Welcome to XDS');
p.note(
@@ -37,81 +184,34 @@ export function registerInit(program) {
'About',
);
- // Step 2: Agent Docs
- const shouldInstallAgentDocs = isCancel(
+ // Feature: agents
+ const shouldInstallAgents = isCancel(
await p.confirm({
- message: 'Install AGENTS.md for AI coding agent support?',
+ message: 'Install AI agent support? (adds XDS cheat sheet to AGENTS.md)',
initialValue: true,
}),
);
- if (shouldInstallAgentDocs) {
+ if (shouldInstallAgents) {
const s = p.spinner();
s.start('Installing agent docs');
- try {
- installAgentDocs(process.cwd());
- s.stop('Agent docs installed');
- } catch {
- s.stop('Agent docs installation failed');
- p.log.warning(
- 'Could not install agent docs. Run `npx xds agent-docs` later to retry.',
- );
- }
+ runAgents(targetDir);
+ s.stop('Done');
}
- // Step 3: Swizzle Awareness
+ // Feature: swizzle awareness
p.note(
'You can customize any component with:\n npx xds swizzle XDSButton\n npx xds swizzle --list',
'Component Customization',
);
- // Step 4: Template Selection
- const templates = listTemplates();
-
- if (templates.length > 0) {
- const templateOptions = [
- {value: 'skip', label: 'Skip — No template'},
- {value: 'blank', label: 'Blank Page — Minimal scaffold'},
- {value: 'table', label: 'Table Page — Data table with actions'},
- {value: 'login', label: 'Login Page — Auth form with inputs'},
- ];
-
- const templateChoice = isCancel(
- await p.select({
- message: 'Start with a page template?',
- options: templateOptions,
- }),
- );
-
- if (templateChoice !== 'skip') {
- const targetPath = isCancel(
- await p.text({
- message: 'Where should the template be created?',
- initialValue: `./src/pages/${templateChoice}`,
- placeholder: `./src/pages/${templateChoice}`,
- }),
- );
-
- const outputDir = path.resolve(process.cwd(), targetPath);
- const templateDir = path.join(CLI_ROOT, 'templates', templateChoice);
-
- fs.mkdirSync(outputDir, {recursive: true});
-
- const files = fs.readdirSync(templateDir);
- for (const file of files) {
- const srcPath = path.join(templateDir, file);
- if (fs.statSync(srcPath).isFile()) {
- fs.copyFileSync(srcPath, path.join(outputDir, file));
- }
- }
-
- p.log.success(
- `Template created at ${path.relative(process.cwd(), outputDir)}/`,
- );
- }
- }
+ // Feature: template
+ await runTemplate(targetDir);
+
+ // Feature: theme awareness
+ await runTheme();
- // Step 5: Success
+ // Outro
p.outro('XDS initialized!');
console.log('');
diff --git a/packages/cli/src/commands/upgrade.mjs b/packages/cli/src/commands/upgrade.mjs
index 1f8df12d5e..a565d82b4b 100644
--- a/packages/cli/src/commands/upgrade.mjs
+++ b/packages/cli/src/commands/upgrade.mjs
@@ -155,7 +155,7 @@ export function registerUpgrade(program) {
p.log.success('Agent docs updated to match new version.');
} catch {
p.log.warn(
- 'Could not update agent docs. Run `npx xds agent-docs` to update manually.',
+ 'Could not update agent docs. Run `npx xds init --features agents` to update manually.',
);
}
}
diff --git a/packages/cli/src/index.mjs b/packages/cli/src/index.mjs
index 7bcdeb642c..05deacb398 100644
--- a/packages/cli/src/index.mjs
+++ b/packages/cli/src/index.mjs
@@ -35,7 +35,7 @@ const commands = [
{name: 'component', path: './commands/component/index.mjs', register: 'registerComponent'},
{name: 'docs', path: './commands/docs.mjs', register: 'registerDocs'},
{name: 'swizzle', path: './commands/swizzle.mjs', register: 'registerSwizzle'},
- {name: 'agent-docs', path: './commands/agent-docs.mjs', register: 'registerAgentDocs'},
+ // agent-docs folded into init — functions still importable from agent-docs.mjs
{name: 'template', path: './commands/template.mjs', register: 'registerTemplate'},
{name: 'gap-report', path: './commands/gap-report.mjs', register: 'registerGapReport'},
{name: 'upgrade', path: './commands/upgrade.mjs', register: 'registerUpgrade'},
@@ -73,7 +73,7 @@ program
│ npx xds --help See all commands │
│ │
│ Or run directly: │
- │ npx xds agent-docs Install AI agent docs │
+ │ npx xds init Setup + AI agent docs │
│ npx xds component Browse component docs │
│ npx xds docs Design system reference │
│ npx xds swizzle Customize a component │
diff --git a/packages/core/xds.md b/packages/core/xds.md
index 0830358a3d..3fe6d7785f 100644
--- a/packages/core/xds.md
+++ b/packages/core/xds.md
@@ -15,10 +15,10 @@ npx xds docs # principles and tokens reference
### For AI-assisted development
-Run `xds agent-docs` in your project to install the XDS component catalog into your AGENTS.md:
+Run `xds init --features agents` in your project to install the XDS component catalog into your AGENTS.md:
```bash
-npx xds agent-docs
+npx xds init --features agents
```
This adds an auto-generated component index that AI coding agents use to discover and correctly use XDS components. Re-run after updating XDS to keep the index current.