An open source design system that's fully customizable and agent ready
TypeScript
docs: recommend npm run xds script alias for reliable CLI invocation (#2181)
Cindy Zhangd424f076b6f0
diff --git a/README.md b/README.mdindex 93b5ec0dbc..46a1564ec5 100644--- a/README.md+++ b/README.md@@ -26,6 +26,16 @@ yarn add @xds/core @xds/theme-defaultyarn add -D @xds/cli```+For reliable CLI access, add this script to your `package.json`:++```json+"scripts": {+ "xds": "node node_modules/@xds/cli/bin/xds.mjs"+}+```++Then use the CLI as `npm run xds -- component --list`. This avoids path errors when AI assistants or new developers invoke the CLI directly.+Then follow the [setup guide](packages/core/README.md#quick-start) to import styles, configure the theme provider, and start using components.## Packagesdiff --git a/packages/cli/docs/getting-started.doc.mjs b/packages/cli/docs/getting-started.doc.mjsindex 02564e55c4..d23e657ec6 100644--- a/packages/cli/docs/getting-started.doc.mjs+++ b/packages/cli/docs/getting-started.doc.mjs@@ -148,17 +148,29 @@ yarn dev`,content: [{type: 'prose',- text: 'The CLI is your reference for components, tokens, templates, and docs. Use it to discover what\u2019s available.',+ text: 'The CLI is your reference for components, tokens, templates, and docs. For reliable invocation (especially with AI assistants), add this script to your package.json:',+ },+ {+ type: 'code',+ lang: 'json',+ label: 'package.json',+ code: `"scripts": {+ "xds": "node node_modules/@xds/cli/bin/xds.mjs"+}`,+ },+ {+ type: 'prose',+ text: 'Then discover what\'s available:',},{type: 'code',lang: 'bash',label: 'Terminal',- code: `npx xds component # list all components-npx xds component Button # props, usage, theming for Button-npx xds docs # list all doc topics-npx xds template --list # available page templates-npx xds docs tokens # spacing, color, radius reference`,+ code: `npm run xds -- component # list all components+npm run xds -- component Button # props, usage, theming for Button+npm run xds -- docs # list all doc topics+npm run xds -- template --list # available page templates+npm run xds -- docs tokens # spacing, color, radius reference`,},],},diff --git a/packages/cli/docs/working-with-ai.doc.mjs b/packages/cli/docs/working-with-ai.doc.mjsindex d739d9aaa7..863897af1a 100644--- a/packages/cli/docs/working-with-ai.doc.mjs+++ b/packages/cli/docs/working-with-ai.doc.mjs@@ -111,6 +111,36 @@ If you don't know all three, run \`npx xds init --features agents\` to generate},],},+ {+ title: 'The npm run xds Pattern',+ content: [+ {+ type: 'prose',+ text: 'AI agents frequently invoke the CLI with incorrect paths (e.g. node_modules/@xds/cli/bin/docs.mjs instead of xds.mjs), leading to silent failures. Adding an npm script alias with the correct path eliminates this entirely.',+ },+ {+ type: 'code',+ lang: 'json',+ label: 'package.json',+ code: `"scripts": {+ "xds": "node node_modules/@xds/cli/bin/xds.mjs"+}`,+ },+ {+ type: 'prose',+ text: 'With this alias, agents use `npm run xds -- component --list` instead of guessing the binary path. The `--` separator is standard npm convention for passing flags to scripts.',+ },+ {+ type: 'code',+ lang: 'bash',+ label: 'Reliable CLI invocation',+ code: `npm run xds -- component --list+npm run xds -- component Dialog --dense+npm run xds -- docs styling --dense+npm run xds -- docs tokens --dense`,+ },+ ],+ },{title: 'The --dense Flag',content: [