@astryxdesign/cli 0.1.0-canary.e2d38fb → 0.1.0-canary.e457dac

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,59 +186,25 @@ 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"]}
+  }
 }
 ```
 
@@ -259,15 +225,7 @@ 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');
@@ -401,16 +359,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/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, 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: '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: '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,12 +14,6 @@ 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',
@@ -51,10 +45,6 @@ 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.',
@@ -65,10 +55,6 @@ 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, 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: '快速开始', 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: '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

@@ -183,7 +183,7 @@ npx astryx docs tokens --dense`,
   "mcpServers": {
     "xds": {
       "type": "url",
-      "url": "https://astryx.atmeta.com/mcp"
+      "url": "https://astryx.meta.com/mcp"
     }
   }
 }`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.0-canary.e2d38fb",
+  "version": "0.1.0-canary.e457dac",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -15,7 +15,7 @@
     "url": "https://github.com/facebook/astryx/issues"
   },
   "keywords": [
-    "astryx",
+    "xds",
     "cli",
     "design-system",
     "init",
@@ -54,9 +54,9 @@
     "jscodeshift": "^17.3.0"
   },
   "peerDependencies": {
-    "@astryxdesign/core": "0.1.0-canary.e2d38fb",
-    "@astryxdesign/lab": "0.1.0-canary.e2d38fb",
-    "@astryxdesign/theme-neutral": "0.1.0-canary.e2d38fb"
+    "@astryxdesign/core": "0.1.0-canary.e457dac",
+    "@astryxdesign/lab": "0.1.0-canary.e457dac",
+    "@astryxdesign/theme-neutral": "0.1.0-canary.e457dac"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {
@@ -70,9 +70,9 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/core": "0.1.0-canary.e2d38fb",
-    "@astryxdesign/lab": "0.1.0-canary.e2d38fb",
-    "@astryxdesign/theme-neutral": "0.1.0-canary.e2d38fb"
+    "@astryxdesign/core": "0.1.0-canary.e457dac",
+    "@astryxdesign/lab": "0.1.0-canary.e457dac",
+    "@astryxdesign/theme-neutral": "0.1.0-canary.e457dac"
   },
   "scripts": {
     "astryx": "node bin/astryx.mjs",

package/src/api/search.mjs

@@ -41,184 +41,14 @@ import {
 } from '../lib/component-discovery.mjs';
 import {discoverHooks, findHookDoc} from '../lib/hook-discovery.mjs';
 import {levenshteinDistance} from '../lib/string-utils.mjs';
-import {discoverTemplates, extractComponents} from './template.mjs';
+import {discoverTemplates} from './template.mjs';
 import {AstryxError} from './error.mjs';
 
 const DOCS_DIR = path.join(CLI_ROOT, 'docs');
 
-/**
- * Synonym / intent map: product-language terms an agent is likely to type,
- * expanded to the catalog's vocabulary so oblique queries still rank. Keys and
- * values are matched bidirectionally (typing any value also pulls in the key
- * and its siblings). Lowercase, single words or short phrases.
- */
-const SYNONYMS = {
-  dashboard: ['overview', 'analytics', 'kpi', 'kpis', 'metrics', 'stats', 'reporting', 'insights', 'control'],
-  login: ['signin', 'auth', 'authentication', 'sso', 'credentials', 'account'],
-  signup: ['register', 'registration', 'onboarding'],
-  payment: ['checkout', 'billing', 'card', 'pay', 'purchase', 'order'],
-  pricing: ['plans', 'plan', 'tiers', 'tier', 'subscription', 'subscriptions'],
-  chat: ['messaging', 'message', 'messages', 'conversation', 'inbox', 'dm'],
-  settings: ['preferences', 'config', 'configuration', 'account'],
-  calendar: ['schedule', 'scheduling', 'events', 'event', 'month', 'agenda'],
-  table: ['list', 'rows', 'records', 'grid', 'spreadsheet', 'datatable'],
-  gallery: ['photos', 'photo', 'images', 'image', 'pictures'],
-  hero: ['banner', 'splash', 'headline', 'landing'],
-  form: ['fields', 'input', 'inputs', 'survey'],
-  profile: ['bio', 'avatar', 'user'],
-  documentation: ['docs', 'reference', 'guide', 'api'],
-  navigation: ['nav', 'menu', 'sidebar'],
-};
-
-// Flatten into a token -> Set(expansions) lookup (bidirectional).
-const SYNONYM_INDEX = (() => {
-  const idx = new Map();
-  const add = (a, b) => {
-    if (!idx.has(a)) idx.set(a, new Set());
-    idx.get(a).add(b);
-  };
-  for (const [key, vals] of Object.entries(SYNONYMS)) {
-    for (const v of vals) {
-      add(key, v);
-      add(v, key);
-      for (const v2 of vals) if (v2 !== v) add(v, v2);
-    }
-  }
-  return idx;
-})();
-
-/**
- * Light stemmer: strips common English suffixes so "charts"/"charting" and
- * "chart" share a root. Deliberately crude (no Porter) — good enough to bridge
- * plural/gerund gaps without a dependency.
- * @param {string} w
- * @returns {string}
- */
-export function stem(w) {
-  let s = w;
-  for (const suf of ['ing', 'ed', 'ies', 'es', 's']) {
-    if (s.length > suf.length + 2 && s.endsWith(suf)) {
-      s = suf === 'ies' ? s.slice(0, -3) + 'y' : s.slice(0, -suf.length);
-      break;
-    }
-  }
-  return s;
-}
-
-
 /** Valid domain filters for `--type`. */
 export const SEARCH_DOMAINS = ['component', 'hook', 'doc', 'template'];
 
-/**
- * Filler words stripped from multi-word queries so natural-language phrasing
- * ("a page where you can see business stats") ranks on its content words.
- */
-const STOPWORDS = new Set([
-  'a', 'an', 'the', 'of', 'for', 'to', 'with', 'and', 'or', 'in', 'on', 'at',
-  'by', 'that', 'this', 'my', 'your', 'our', 'their', 'is', 'are', 'be', 'it',
-  'its', 'as', 'from', 'page', 'screen', 'app', 'application', 'view', 'where',
-  'you', 'can', 'some', 'like', 'just', 'basically', 'kinda', 'want', 'wants',
-  'need', 'needs', 'something', 'thing', 'things', 'build', 'make', 'create',
-  'i', 'me', 'we', 'us', 'so', 'up', 'out', 'over', 'side', 'one', 'big',
-]);
-
-/**
- * Split a query into meaningful content tokens (lowercased, stopwords + very
- * short words removed). Empty for single-word queries (callers fall back to
- * whole-phrase scoring).
- * @param {string} term - Already-lowercased query.
- * @returns {string[]}
- */
-export function tokenizeQuery(term) {
-  return term
-    .split(/\s+/)
-    // Strip only leading/trailing punctuation; keep joined identifiers intact
-    // (e.g. "foo_bar" stays one token) so gibberish stays gibberish.
-    .map(t => t.replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, ''))
-    .filter(t => t.length >= 2 && !STOPWORDS.has(t));
-}
-
-/**
- * Score a candidate against a query, handling multi-word natural language.
- * Tries the whole phrase (so exact/near matches still win) AND a per-token
- * pass (so "data table with filters" matches `table-page` via table+filter),
- * and returns whichever is stronger.
- *
- * @param {string} term - Lowercased full query.
- * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
- * @param {object} candidate
- * @returns {{score: number, reason: string} | null}
- */
-/**
- * Minimum per-token score (in the multi-word pass) to count as a real match.
- * 50 = a genuine name/keyword/description hit; below that is loose Levenshtein
- * fuzz that would otherwise turn gibberish queries into noise.
- */
-const MIN_TOKEN_SCORE = 50;
-
-/**
- * Best score for a token against a candidate, fanning out through synonyms
- * (synonym hits are discounted so a direct hit always wins).
- * @returns {{score: number, reason: string} | null}
- */
-function bestForToken(tok, candidate) {
-  let best = scoreCandidate(tok, candidate);
-  const syns = SYNONYM_INDEX.get(tok);
-  if (syns) {
-    for (const s of syns) {
-      const h = scoreCandidate(s, candidate);
-      if (h) {
-        const score = Math.round(h.score * 0.85);
-        if (!best || score > best.score) best = {score, reason: `${h.reason} (~${tok})`};
-      }
-    }
-  }
-  return best;
-}
-
-export function scoreQuery(term, tokens, candidate) {
-  const full = scoreCandidate(term, candidate);
-
-  // 0–1 content tokens: keep whole-phrase fuzzy matching (typo tolerance for
-  // single words), but if stopwords left exactly one DIFFERENT token (e.g.
-  // "pricing page" → "pricing"), score that token too and take the stronger.
-  if (tokens.length <= 1) {
-    const single = tokens.length === 1 ? bestForToken(tokens[0], candidate) : null;
-    if (full && (!single || full.score >= single.score)) return full;
-    return single;
-  }
-
-  // Multi-word natural language: score each content token, counting only
-  // strong hits, then reward coverage so candidates matching more terms win.
-  let sum = 0;
-  let matched = 0;
-  const hitTerms = [];
-  for (const tok of tokens) {
-    const h = bestForToken(tok, candidate);
-    if (h && h.score >= MIN_TOKEN_SCORE) {
-      sum += h.score;
-      matched++;
-      hitTerms.push(tok);
-    }
-  }
-  if (matched === 0) return full;
-
-  // Reward the AVERAGE strength of the concepts that matched (not divided by
-  // total query length — that penalizes verbose / low-fidelity prompts), plus
-  // a bonus per additional matched concept and a coverage term. A candidate
-  // that matches several of the query's concepts beats one matching a single
-  // incidental word.
-  const avgMatched = sum / matched;
-  const coverage = matched / tokens.length;
-  const tokenScore = Math.round(avgMatched + Math.min(matched - 1, 3) * 12 + coverage * 15);
-
-  if (full && full.score >= tokenScore) return full;
-  return {
-    score: tokenScore,
-    reason: `matches ${matched}/${tokens.length} terms: ${hitTerms.join(', ')}`,
-  };
-}
-
 /**
  * Score a single candidate against the search term across name, keywords,
  * and prose signals. Returns the best (highest) score plus a human reason,
@@ -277,13 +107,10 @@ export function scoreCandidate(term, {name, keywords = [], description = '', pro
     else if (dist === 2) consider(30, `keyword "${kw}" (distance ${dist})`);
   }
 
-  // ── Prose / description signals (stem-tolerant whole word) ──────
-  // Match the term's stem as a whole word, tolerating plural/gerund suffixes
-  // so "chart" matches "charts" and "filter" matches "filtering".
+  // ── Prose / description signals (whole-word boundary) ───────────
   if (term.length >= 3) {
-    const root = stem(term);
-    const escaped = root.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const re = new RegExp(`\\b${escaped}(s|es|ing|ed|ies)?\\b`);
+    const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`\\b${escaped}\\b`);
     if (description && re.test(description.toLowerCase())) {
       consider(50, `description mentions "${term}"`);
     } else {
@@ -413,30 +240,14 @@ async function gatherTemplates(cwd) {
   } catch {
     return [];
   }
-  return templates.map(t => {
-    // Blocks ship componentsUsed; page templates don't, so derive them from the
-    // source. Category words (e.g. "Dashboard - Analytics") are strong intent
-    // signal for pages, which otherwise only index on name + description.
-    let keywords = Array.isArray(t.componentsUsed) ? [...t.componentsUsed] : [];
-    if (t.type === 'page') {
-      if (t.filePath) {
-        try {
-          keywords = keywords.concat(extractComponents(t.filePath));
-        } catch {
-          // Best-effort: skip keyword enrichment if the source can't be read.
-        }
-      }
-      if (t.category) keywords = keywords.concat(t.category.split(/[^A-Za-z0-9]+/).filter(Boolean));
-    }
-    return {
-      domain: 'template',
-      name: t.dirName,
-      keywords,
-      description: t.description || '',
-      _displayName: t.name,
-      _kind: t.type, // 'page' | 'block'
-    };
-  });
+  return templates.map(t => ({
+    domain: 'template',
+    name: t.dirName,
+    keywords: Array.isArray(t.componentsUsed) ? t.componentsUsed : [],
+    description: t.description || '',
+    _displayName: t.name,
+    _kind: t.type, // 'page' | 'block'
+  }));
 }
 
 /**
@@ -514,7 +325,6 @@ export async function search(query, options = {}) {
   }
 
   const term = String(query).trim().toLowerCase();
-  const tokens = tokenizeQuery(term);
 
   const coreDir = findCoreDir(cwd);
   if (!coreDir) {
@@ -532,13 +342,9 @@ export async function search(query, options = {}) {
 
   const all = [...components, ...hooks, ...docTopics, ...templates];
 
-  // Score every candidate on its own merits. The consumer groups results by
-  // role (page / block / component) and takes the top of each, so there's no
-  // cross-role competition to engineer — a target page only needs to be the
-  // strongest PAGE, not outrank every component.
   const scored = [];
   for (const candidate of all) {
-    const hit = scoreQuery(term, tokens, candidate);
+    const hit = scoreCandidate(term, candidate);
     if (hit) scored.push(toResult(candidate, hit.score, hit.reason));
   }
 

package/src/api/template.mjs

@@ -95,7 +95,6 @@ async function discoverPages() {
       dirName: dir.name,
       name: doc?.name || dir.name,
       description: doc?.description || '',
-      category: doc?.category || '',
       isReady: doc?.isReady ?? true,
       scaffold: doc?.scaffold ?? false,
       filePath: path.join(dirPath, 'page.tsx'),
@@ -246,7 +245,7 @@ const UBIQUITOUS = new Set([
   'StackItem', 'Icon',
 ]);
 
-export function extractComponents(pagePath) {
+function extractComponents(pagePath) {
   const src = fs.readFileSync(pagePath, 'utf-8');
   // Match JSX opening tags, e.g. `<Section` or the legacy `<XDSSection`.
   // Templates author bare component names post un-prefix migration