@astryxdesign/cli 0.6.4-canary.fdc76dc → 0.6.5-canary.00f1ed9

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # @xds/cli
 
+# 0.6.5
+
+#### New Features
+
+- `astryx component` accepts several exact selectors in one call. The JSON response keeps one ordered row per selector, including missing and ambiguous components, and text mode prints every row before exiting nonzero when any lookup fails. The `component()` API accepts selector arrays and always returns `component.batch` for an array, including empty and one-item arrays. Batches accept up to 100 selectors and reject larger arrays before lookup. The public API also exports shared `BatchResponse` and `BatchRow` types for typed receipts.
+- `astryx discover` browses integrations: the ones a project has and, through discover sources, the ones it could add, with every version and what each one adds. It searches every kind of item and filters with `--type`, `--installed`, `--available`, and `--limit`. A project sets a source as `discover` in `astryx.config`, and an integration exports one as a `discover` named export. Discover only reads: it prints the command that adds a package and never runs it. Existing `--json` fields keep their meaning. A free-text query now always lists its matches, even an exact component name, and `astryx discover <package>/<Name>` opens one.
+- `astryx integration verify` is the new name of `astryx integration pack --check`.
+  The check you run before publishing an integration now has a name that says what it does. `astryx integration verify` packs the package with npm, installs the tarball into a temporary app, and checks that the app sees the same components, templates, themes, docs, and codemods. It takes no flags. `astryx integration pack --check` still works as a deprecated alias: it runs the same check with the same output, JSON, and exit codes, prints a note that names `integration verify`, and shows as deprecated in help. It will be removed in a later release. The `integrationPackCheck()` API and its `integration.pack-check` JSON response do not change. With `--json`, a command group given an unknown subcommand now reports `ERR_UNKNOWN_SUBCOMMAND` and lists its subcommands, where it used to say JSON output is not supported.
+
+#### Fixes
+
+- Fix the CLI's topic docs and how they print.
+- `astryx doctor` no longer reports an integration it could not check as absent or complete (#6619)
+- `upgrade`'s `filesChanged` counts files, not (codemod, file) pairs (#6622)
+  One source file that four codemods each changed was reported as four files changed, so `filesChanged` matched `transformsApplied` and the documented meaning, "Total files changed", was not true. The human summary said the same thing: "Found 4 changes across 4 files" for one file.
+
+  `filesChanged` is now the count of distinct files. `transformsApplied` is unchanged: a code or config codemod counts once for each file it changed, and a project codemod counts once. A file that both a core codemod and an integration codemod changed counts once in `filesChanged`.
+- A parse error prints the Astryx error format in text mode.
+  `astryx theme list --lang zh-Hans` printed Commander's own line — `error: option '--lang <locale>' argument 'zh-Hans' is invalid…` — while every other CLI error prints `Error: …`. `--json` was already correct (`ERR_INVALID_LANG`), so the two modes agreed only on the exit code.
+
+  Commander writes that line before any Astryx code runs, so the JSON shim — the one place that already sees every parse failure — now suppresses it and writes the Astryx line itself, from the same message, for both modes. Every parse failure is covered: unknown option, unknown command, missing argument, and an invalid value for a global option. `--help` and `--version` are untouched and still exit 0.
+- The CLI reference now matches what the commands do. Every `--help` ends with the command's examples and a `More:` line that names its full docs page. Function docs show each parameter's default, mark required parameters, list the error codes each function throws, and use examples that run. The response-type list adds `help`, `version`, and `upgrade.registry`, and `astryx manifest` now lists `upgrade.registry` for `upgrade`. The `--zh`, `--dense`, `--lang`, and `--detail` descriptions name the commands they change, and command summaries say when to use each command. When `astryx template` refuses to overwrite a file, it now says to re-run with `--overwrite` (or `-f`). The `upgrade` command page (`astryx docs cli/commands/upgrade`) now explains which files codemods never edit, what happens when one of them needs a change, and how to regenerate it.
+- `astryx integration pack --check` now checks the tarball when a `prepack`, `prepare`, or `postpack` script prints to stdout. Before, any lifecycle output made the check fail with "npm pack produced unparseable JSON output" before it looked at the tarball. A failing lifecycle script still fails the check, and its output stays in the `pack_failed` message.
+- `astryx doctor integration docs` fails when a namespace doc or a placement fails, as its help says.
+  Such a failure hides the doc from the docs tree, so it now exits 1 with an `invalid_doc_graph` error instead of a warning. A link that names no doc still only warns, since it prints as written. `doctor integration docs` and `doctor integration components` also no longer print an `[ok]` line after a check that failed.
+
+  A mistyped subcommand under `doctor` now fails and lists the subcommands the group has: `astryx doctor integrations` used to run the project checks, and `astryx doctor integration bogus` exited 0 in text though it exited 1 with `--json`.
+- A package that ships a theme, or a doc section with an `id`, now declares the CLI that can read it.
+  A stable CLI before 0.7.0 rejects both: it cannot read the typed theme descriptors that `astryx integration add theme` writes, and it rejects a section `id`. Either way it hides the package's themes or doc topics with no warning. `astryx integration add theme` now adds `"@astryxdesign/cli": ">=0.7.0"` to `peerDependencies`, marked optional, and `astryx integration verify` fails with `themes_need_cli` or `section_ids_need_cli` when a package needs that peer range and does not declare it.
+- `astryx integration verify` resolves every public import in the packed package, not in your source folder.
+  Before, its temporary app resolved your package's own name through the source `package.json`, so an `exports` target left out of the tarball still passed. It now fails with `component_export_missing`, as an app that installs the tarball would.
+- `astryx theme add` and `astryx theme build` now undo a failed write completely. Before, when one file failed to write after others were written, the written files kept their new content. Now every replaced file gets its previous content back, every new file is removed, and the error names any file that could not be restored. Both commands also refuse to replace a destination that is a symbolic link. (#6852)
+
+#### Other Changes
+
+- A code block's label now prints above the block instead of as a `// label` line inside it, so copied bash, CSS, JSON, and HTML stay valid. Table cells escape `|`, so a union type stays in one column.
+- `astryx search dark mode` searches for both words; it used to drop every word after the first. A result that matches every word of a query, one of them by name or keyword, now outranks one that matches only some, and a section whose title or heading holds the whole query ranks near the top. Topics can declare search `keywords`, now a documented ReferenceDoc field, and a namespace's `keywords` now count too. A query keeps its phrase when common words such as `make`, `build`, or `an` drop out, so `astryx search make an integration` finds the integration guides, a plural of a doc's name matches it, one step below the exact name, and a component's name typed as words, such as `command palette`, finds the component. Outside an app, where `@astryxdesign/core` is not installed, `astryx search` searches the docs instead of failing, and says so; `--type component`, `hook`, or `template` still needs Core.
+- Snippets that failed when copied now work: StyleX token imports, the `fr-FR.json` locale path, Tailwind `rounded-lg`, `--color-background-muted`, icon and color values, and the Cursor rule path.
+- Claims that did not match the code are corrected: the 30 shipped locales and how RTL mirroring works, what `astryx init` writes, `--detail brief` for a shorter read, the Neutral and Matcha fonts, the components that need anchor positioning, `gap` steps, Card's radius, and the Next.js StyleX example. The deprecated bare classes are still emitted and will be removed in a later release.
+- `astryx docs tokens` lists all 258 tokens, adding the data visualization and syntax groups, and shows both halves of every `light-dark()` value.
+- Long sections are split, vague titles renamed, and the `--dense` and Chinese versions no longer drop blocks. Eleven long section keys are shorter, such as `astryx docs styling stylex-setup`, and every old key still resolves. An integration section that extends a Core topic by a section's old title still replaces that section.
+- `astryx integration add codemod --to` help says it takes the Core version whose upgrade runs the codemod.
+- The agent block that `astryx init` writes now says `upgrade --from <old version> --apply`; `upgrade --apply` alone stops with "Missing required --from".
+- The contributor-only sections, on adding a semantic icon and on strings and text direction inside components, moved to CONTRIBUTING.md.
+- An installed dependency whose `astryx.integration.*` manifest cannot be loaded is still kept out of the loaded set, but `implicit-integrations` now names it and says it contributes nothing. Before, doctor said that no installed dependency ships a manifest. The check stays informational, and `astryx doctor integration validate <package>` gives the details.
+- `implicit-integrations` lists only the roots that exist on disk. A package whose declared roots are missing is reported as contributing nothing, with the missing roots named. Before, it listed every root the manifest declared.
+- `provider-identity` says how many loaded integrations it could not read, instead of counting only the readable ones.
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @josephfarina
+
+---
+
 # 0.6.4
 
 #### New Features

package/README.md

@@ -303,11 +303,12 @@ Shape:
 ```
 
 The manifest is **derived from Commander metadata** (commands, arguments, options)
-so it can't drift from the real command definitions. The two facts Commander
-doesn't track (`--json` support and emitted response types) are layered on from
-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.
+so it can't drift from the real command definitions. The facts Commander doesn't
+track come from each command's docs: examples from its CommandDoc, and emitted
+response types from the returns of the FunctionDoc it wraps (plus the few
+envelopes the CLI layer builds itself). `--json` support comes from the
+`JSON_SUPPORTED` allowlist. Drift tests (`manifest.test.mjs`) fail CI when a
+command is added without describing it.
 
 **Backwards-compat:** the bare `astryx --json` envelope keeps `type: "help"` and its
 original shallow fields (`name`, `version`, `commands` as a `string[]` of names,
@@ -450,9 +451,9 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `gap-report.categories`           | The fixed gap category values and human-readable labels.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `gap-report.file`                 | An aggregate receipt: overall status, the selected package, issuesUrl (or null), deliveries in handler order, each {handlerType: project \| integration \| fallback, handler, audience, status, url, message}, and filedCount/routedOnlyCount totals.                                                                                                                                                                                                                                                                                                                                                                 |
 | `template.list`                   | The effective discovered TemplateListEntry[] for pages and blocks. A winning replacement entry includes optional `replaces`, naming the Core id omitted from the default list.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `template.show`                   | The resolved template's raw source plus its description, kind, and the component names it composes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `template.show`                   | The resolved template's source, exactly as a copy writes it, plus its description, kind, the component names it composes, and demoMediaReplaced (how many Astryx demo media references were replaced with placeholders for you to swap for your own media).                                                                                                                                                                                                                                                                                                                                                           |
 | `template.skeleton`               | A layout skeleton (structural tags with spatial annotations) plus the template's description and the components it composes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `template.copy`                   | A scaffold receipt: template id, output directory, written file name, and file count.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `template.copy`                   | A scaffold receipt: template id, output directory, written file name, file count, and demoMediaReplaced (how many Astryx demo media references were replaced with placeholders for you to swap for your own media).                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `template.cdn`                    | A write receipt for the no-build-step CDN starter page: the path (relative to cwd), the Astryx version every CDN URL was pinned to, whether it was written, and the reason it was not. `exists` when a file was already there, which is a success.                                                                                                                                                                                                                                                                                                                                                                    |
 | `hook.list`                       | The hook catalog grouped by category: `detail` (the level: names \| compact \| full) and `components`, the grouped map of hook names, brief entries, or a full HookDoc per entry.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `hook.detail`                     | One hook's full authored HookDoc.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -468,18 +469,18 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `upgrade.list`                    | Every available codemod, oldest→newest, as {name, title, version, optional}; returned for --list without running anything.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `upgrade.registry`                | The copied-composition receipt for --registry: applied, ok, the counts (found, current, wouldUpdate, updated, wouldMerge, merged, wouldRefreshReceipt, receiptsRefreshed, conflicts, missing, invalid, failed), and items.                                                                                                                                                                                                                                                                                                                                                                                            |
 | `upgrade.status`                  | A short-circuit outcome with no codemods run (up_to_date, no_codemods, or config_fixable), each carrying the agent-docs summary.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `upgrade.run`                     | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `upgrade.run`                     | The run receipt: from/to versions, codemod count, integrations processed, the agent-docs summary, sourcePathFound (false when the resolved source directory does not exist, so no source file was read), and (apply mode) filesChanged, transformsApplied, and per-codemod errors.                                                                                                                                                                                                                                                                                                                                    |
 | `manifest`                        | The CLI capability manifest: name, version, apiVersion, description, globalOptions, commands (each name, description, arguments, options, json, aliases?, responseTypes?, examples?, exitCodes? as [{code, when}], subcommands?), jsonSupported, and the flat responseTypes index.                                                                                                                                                                                                                                                                                                                                    |
 | `help`                            | Help, in one of two shapes. A bare `astryx --json` returns the root manifest: name, version, commands (the command names), jsonSupported, and manifest (the full payload `astryx manifest --json` returns). `--help --json` on any command, or `astryx help [command] --json`, returns that command's help: command, description, usage, options (each flags, description, and defaultValue and choices when set), and subcommands (each name and description). data.manifest marks the first shape; data.usage marks the second.                                                                                     |
 | `version`                         | The CLI version, for `astryx --version --json`: {version}.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `doctor`                          | The health-check report: `checks` (each with id, label, status: pass \| warn \| fail \| info, a message, and an optional fix, always present on warn and fail) plus a `summary` of counts per status.                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | `integration.add`                 | A contribution-writer receipt: kind, name, optional root {path, created}, integration-manifest path, every affected project-relative path, written, and dryRun.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `integration.pack-check`          | The packed-package check: name, version, packable, tarball {filename, fileCount, size, unpackedSize} or null, inventory {manifest, roots [{kind, path, expectedFiles, missingFiles, complete}], expectedFiles, packedFiles}, contributions {local, packed}, each null or {themes [{slug, exportName}], components, templates [{id, type, name}], codemods [{version, id}], docs, agentDocsAppend}, and issues [{code, severity, message}].                                                                                                                                                                            |
-| `integration.validate`            | The validation result: the package name and version (both null when no local manifest is found) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `integration.template-conflicts`  | The integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `integration.component-conflicts` | The integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command.                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `integration.doc-conflicts`       | The integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`).                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `layout.expand`                   | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, and written (the output path, or null when nothing was written).                                                                                                                                                                                                                                                                                                                                                                                  |
+| `integration.validate`            | The validation result: validated (false when no integration manifest was found, so nothing was checked and the empty issues list proves nothing), the package name and version (both null when validated is false) plus issues, an AstryxIntegrationIssue[] of {code, severity: warning \| error, message}.                                                                                                                                                                                                                                                                                                           |
+| `integration.template-conflicts`  | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking Core template-id conflicts as {id, severity: warning, integrationPackage, integrationType, integrationName, coreMatches, message, command}.                                                                                                                                                                                                                                                                                                                         |
+| `integration.component-conflicts` | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and non-blocking conflicts where an integration component name is also owned by Core; each conflict includes the exact package-qualified command.                                                                                                                                                                                                                                                                                                                                    |
+| `integration.doc-conflicts`       | validated (false when no integration manifest was found, so nothing was inspected), the integration identity, structural issues, and Core doc overlaps. Each finding includes `severity` (`info` \| `error`) and `relationship` (`replaces` \| `extends` \| `accidental`).                                                                                                                                                                                                                                                                                                                                            |
+| `layout.expand`                   | The expansion: parsed form, generated TSX code, componentsUsed, states (count of useState hooks scaffolded), todos, blocksReferenced (each {name, mode}), warnings, written (the output path, or null when nothing was written), and demoMediaReplaced (count of demo media placeholders).                                                                                                                                                                                                                                                                                                                            |
 | `layout.check`                    | The validation result: a valid flag, the detected form, errors (each with line/col, message, formatted text, and suggestions), warnings, and the expression re-printed in both canonical surfaces (compact and outline).                                                                                                                                                                                                                                                                                                                                                                                              |
 | `layout.grammar`                  | The XLE/XLO grammar cheatsheet: a text field with the full reference plus an aliases map (short name → canonical component) generated from this install's registry.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 

package/api/build/_adapter.d.mts

@@ -7,8 +7,15 @@
  * @property {string} name The template's own id, as search reports it.
  * @property {string} command `astryx template <id> --type page`, the command that selects exactly this template: an integration replacement is selected by the Core id it replaces, and `--type page` keeps a block with the same id from making it ambiguous. Search prints template commands the same way.
  * @property {string} displayName Human-facing name.
- * @property {string} description What the page is: its layout and the ideas it serves.
+ * @property {string} description What the page is and how it is laid out.
  * @property {string} category The template's own `Family - Variant` label; empty when it declares none.
+ * @property {string[]} keywords The ideas the page serves, as its own descriptor names them; empty when it declares none.
+ */
+/**
+ * A component the project can use, as the ranker reads it.
+ * @typedef {object} ComponentWords
+ * @property {string} name The component's name, e.g. `DateRangeInput`.
+ * @property {string[]} keywords The keywords its own doc declares.
  */
 /**
  * Every ready page template the project can scaffold, in discovery order. This
@@ -23,6 +30,16 @@
  * @returns {Promise<PageTemplate[]>}
  */
 export function loadPageTemplates(cwd: string): Promise<PageTemplate[]>;
+/**
+ * The components the project can use, Core's and its integrations', each with
+ * the keywords its own doc declares: what the ranker reads to tell a part of a
+ * page from a page. Search's own discovery, so both agree on what exists; empty
+ * when Core cannot be found.
+ *
+ * @param {string} cwd
+ * @returns {Promise<ComponentWords[]>}
+ */
+export function loadComponents(cwd: string): Promise<ComponentWords[]>;
 /**
  * A page template the kit can recommend starting from.
  */
@@ -40,11 +57,28 @@ export type PageTemplate = {
      */
     displayName: string;
     /**
-     * What the page is: its layout and the ideas it serves.
+     * What the page is and how it is laid out.
      */
     description: string;
     /**
      * The template's own `Family - Variant` label; empty when it declares none.
      */
     category: string;
+    /**
+     * The ideas the page serves, as its own descriptor names them; empty when it declares none.
+     */
+    keywords: string[];
+};
+/**
+ * A component the project can use, as the ranker reads it.
+ */
+export type ComponentWords = {
+    /**
+     * The component's name, e.g. `DateRangeInput`.
+     */
+    name: string;
+    /**
+     * The keywords its own doc declares.
+     */
+    keywords: string[];
 };

package/api/build/_adapter.mjs

@@ -2,20 +2,23 @@
 
 /**
  * @file The build subject's environment access: the page templates a project
- * can scaffold.
+ * can scaffold, and the components it can use.
  *
- * @input Template discovery for `cwd` — the CLI's own templates plus any that
- *   the project's configured integrations contribute.
+ * @input Template and component discovery for `cwd` — the CLI's own templates
+ *   and Core's components, plus any that the project's configured integrations
+ *   contribute.
  * @output Ready page templates as `{name, displayName, description, category,
- *   command}`, where `command` is the `astryx template` command that selects
- *   exactly that template.
- * @position Beside build.mjs (api/build/). The kit leaf reads templates only
- *   through here, because a subject's `_adapter.mjs` is its only environment
- *   access. Search keeps its own discovery; this adds none of its own, it
- *   reuses the template subject's.
+ *   keywords, command}`, where `command` is the `astryx template` command that
+ *   selects exactly that template; components as `{name, keywords}`.
+ * @position Beside build.mjs (api/build/). The kit leaf reads templates and
+ *   components only through here, because a subject's `_adapter.mjs` is its
+ *   only environment access. This adds no discovery of its own: templates come
+ *   from the template subject's, components from search's.
  */
 
 import {discoverTemplates} from '../template/template.mjs';
+import {componentKeywords} from '../search/search.mjs';
+import {findCoreDir} from '../../foundation/fs/paths.mjs';
 
 /**
  * A page template the kit can recommend starting from.
@@ -23,8 +26,16 @@ import {discoverTemplates} from '../template/template.mjs';
  * @property {string} name The template's own id, as search reports it.
  * @property {string} command `astryx template <id> --type page`, the command that selects exactly this template: an integration replacement is selected by the Core id it replaces, and `--type page` keeps a block with the same id from making it ambiguous. Search prints template commands the same way.
  * @property {string} displayName Human-facing name.
- * @property {string} description What the page is: its layout and the ideas it serves.
+ * @property {string} description What the page is and how it is laid out.
  * @property {string} category The template's own `Family - Variant` label; empty when it declares none.
+ * @property {string[]} keywords The ideas the page serves, as its own descriptor names them; empty when it declares none.
+ */
+
+/**
+ * A component the project can use, as the ranker reads it.
+ * @typedef {object} ComponentWords
+ * @property {string} name The component's name, e.g. `DateRangeInput`.
+ * @property {string[]} keywords The keywords its own doc declares.
  */
 
 /**
@@ -53,8 +64,28 @@ export async function loadPageTemplates(cwd) {
       displayName: t.displayName || t.name,
       description: t.description || '',
       category: t.category || '',
+      keywords: t.keywords ?? [],
       // The id `template()` resolves back to this entry: an active replacement
       // owns the Core id it names, so that id selects it, not its own.
       command: `astryx template ${t.replaces ?? t.dirName} --type page`,
     }));
 }
+
+/**
+ * The components the project can use, Core's and its integrations', each with
+ * the keywords its own doc declares: what the ranker reads to tell a part of a
+ * page from a page. Search's own discovery, so both agree on what exists; empty
+ * when Core cannot be found.
+ *
+ * @param {string} cwd
+ * @returns {Promise<ComponentWords[]>}
+ */
+export async function loadComponents(cwd) {
+  const coreDir = findCoreDir(cwd);
+  if (!coreDir) return [];
+  try {
+    return await componentKeywords(coreDir, cwd);
+  } catch {
+    return [];
+  }
+}

package/api/build/build.doc.mjs

@@ -19,8 +19,8 @@ export const doc = {
     'The "build a page" entry point. Called with no query it returns the ' +
     'how-to-build-a-page playbook as data: the workflow steps with their ' +
     'commands, the on-system rules, and related lookups. Called with a query it names the page template to ' +
-    'START from (always one: the page template a ranker built for long descriptions puts first, else the app ' +
-    'shell) and the next two templates, ' +
+    'START from (always one: the page template a ranker built for long descriptions puts first; for a part ' +
+    'of a page, the page it names; else the app shell) and the next two templates, ' +
     'and the unified search grouped around it: the other close page templates, drop-in blocks, and ' +
     'idea-specific components/hooks, plus the always-on frame + foundation. A template carries the page ' +
     'frame and spacing, so the kit never recommends composing a page from components.',

package/api/build/build.test.mjs

@@ -8,7 +8,7 @@ import {describe, it, expect, vi} from 'vitest';
 import * as path from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {build} from './build.mjs';
-import {search} from '../search/search.mjs';
+import {search, searchedComponents} from '../search/search.mjs';
 
 // api/build/ -> up 3 = packages/cli, up 4 = repo root (has packages/core).
 const REPO = path.resolve(
@@ -152,6 +152,16 @@ describe('build API', () => {
   });
 });
 
+describe('build kit — reuses the components its search gathered', () => {
+  it('keeps them beside the search response, out of its JSON', async () => {
+    const all = await search('date picker', {cwd: REPO});
+    expect(searchedComponents(all)?.map(c => c.name)).toContain('DateRangeInput');
+    expect(JSON.stringify(all)).not.toContain('"keywords"');
+    const pagesOnly = await search('date picker', {cwd: REPO, type: 'template'});
+    expect(searchedComponents(pagesOnly)).toBeNull();
+  }, 60_000);
+});
+
 describe('build kit — coverage gates the pages group', () => {
   it('does not call a one-word coincidence a direct match', async () => {
     // A page's keywords include every component its source renders, so any
@@ -259,7 +269,7 @@ describe('build kit — a thin kit says what to try next', () => {
     // A skeleton is a 35-line excerpt: a reader who studies it and composes
     // the rest loses the spacing the template exists to carry. A loose match
     // is still the best start there is, so `start` scaffolds it.
-    const r = await build('executive summary', {cwd: REPO});
+    const r = await build('quarterly business review', {cwd: REPO});
     expect(r.type).toBe('build.kit');
     if (r.type !== 'build.kit') return;
     expect(r.data.directMatch).toBe(false);
@@ -357,9 +367,35 @@ describe('build kit — every page starts from a template', () => {
     const placed = await build('an empty state for a settings page', {cwd: REPO});
     if (placed.type !== 'build.kit') throw new Error(placed.type);
     expect(placed.data.start).toMatchObject({name: 'settings', basis: 'closest'});
+    expect(placed.data.start?.reason).toMatch(/part of a page, so it starts from the page it names/);
     const loose = await build('a date range picker', {cwd: REPO});
     if (loose.type !== 'build.kit') throw new Error(loose.type);
     expect(loose.data.start).toMatchObject({name: 'shell-top-nav', basis: 'fallback'});
+    expect(loose.data.start?.reason).toMatch(/part of a page and names no page, so it starts from the app shell/);
+  });
+
+  it('starts a change to an existing page from the app shell', async () => {
+    // The page is the builder's to keep; no template scaffolds it.
+    const r = await build('add a sort toggle to the existing reports dashboard', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error(r.type);
+    expect(r.data.start).toMatchObject({name: 'shell-top-nav', basis: 'fallback'});
+    expect(r.data.start?.reason).toMatch(/changes a page you already have, so keep it/);
+    expect(r.data.start?.reason).not.toMatch(/too little of the idea fits/);
+    // A direct match the response reports is still named.
+    if (r.data.directMatch) expect(r.data.start?.reason).toContain(`\`${r.data.pages[0].name}\``);
+  });
+
+  it('does not call a new page that mentions something existing a change', async () => {
+    for (const idea of [
+      'a new dashboard inspired by the existing one',
+      'a new dashboard based on the existing dashboard',
+      'clone the existing dashboard as a new page',
+    ]) {
+      const r = await build(idea, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error(r.type);
+      expect(r.data.start?.name).toBe('dashboard');
+      expect(r.data.start?.reason).not.toMatch(/already have/);
+    }
   });
 
   it('names a direct match the ranker outweighed in the reason', async () => {

package/api/build/kit/kit.mjs

@@ -27,13 +27,13 @@
  * the invocation stays the renderer's job.
  */
 
-import {search} from '../../search/search.mjs';
+import {search, searchedComponents} from '../../search/search.mjs';
 import {findCoreDir} from '../../../foundation/fs/paths.mjs';
 import {AstryxError} from '../../error.mjs';
 import {ERROR_CODES} from '../../../foundation/response/error-codes.mjs';
 import {getResultCoverage} from '../../search/coverage.mjs';
-import {loadPageTemplates} from '../_adapter.mjs';
-import {pickAlternatives, pickStart, rankPages} from './rank.mjs';
+import {loadComponents, loadPageTemplates} from '../_adapter.mjs';
+import {ideaKind, pickAlternatives, pickStart, rankPages} from './rank.mjs';
 
 /** A page at/above this score is a confident direct match. */
 const PAGE_DIRECT = 95;
@@ -118,6 +118,24 @@ const asTemplate = t => ({
   command: `${t.command} <path>`,
 });
 
+/**
+ * Why a part of a page, or a change to a page the builder already has, starts
+ * where it does (spec:AST-048/FR3, FR9): the rest of the start's reason, or
+ * null for a whole page.
+ * @param {import('./rank.mjs').IdeaKind} kind
+ * @param {boolean} inPage whether the start is the page the idea names
+ * @returns {string | null}
+ */
+function placement(kind, inPage) {
+  if (kind === 'edit')
+    return 'the idea changes a page you already have, so keep it and add blocks to it; a new page starts from the app shell.';
+  if (kind === 'part')
+    return inPage
+      ? 'the idea is a part of a page, so it starts from the page it names.'
+      : 'the idea is a part of a page and names no page, so it starts from the app shell.';
+  return null;
+}
+
 /**
  * The template to start from: the ready page the ranker puts first when it
  * has the evidence to lead, else the first fallback shell the project can
@@ -129,12 +147,13 @@ const asTemplate = t => ({
  * the reason names it, so the reader knows why the kit starts elsewhere.
  *
  * @param {import('./rank.mjs').RankedPage[]} ranked
+ * @param {import('./rank.mjs').IdeaKind} kind
  * @param {SearchResultEntry[]} pages
  * @param {boolean} directMatch
  * @param {PageTemplate[]} catalog
  * @returns {Omit<BuildStart, 'alternatives'> | null}
  */
-function chooseStart(ranked, pages, directMatch, catalog) {
+function chooseStart(ranked, kind, pages, directMatch, catalog) {
   const direct = directMatch ? pages[0].name : null;
   const unready =
     direct && !catalog.some(t => t.name === direct) ? direct : null;
@@ -142,20 +161,32 @@ function chooseStart(ranked, pages, directMatch, catalog) {
   // match the ranker outweighed is named, and so are the loose page matches
   // search listed when the kit falls back to the shell.
   const loose = pages.map(p => `\`${p.name}\``).join(', ');
-  const pick = pickStart(ranked);
+  /**
+   * A part's or an edit's reason, naming a direct match that is not the start.
+   * @param {string} place
+   * @param {string} startName
+   */
+  const placed = (place, startName) =>
+    direct && direct !== startName
+      ? `Search matched \`${direct}\` by name, but ${place}`
+      : place[0].toUpperCase() + place.slice(1);
+  const pick = pickStart(ranked, kind);
   const closest = pick && catalog.find(t => t.name === pick.name);
-  if (closest) {
+  if (pick && closest) {
     const agrees = closest.name === direct;
+    const place = placement(kind, pick.base && pick.familyNamed);
     return {
       ...asTemplate(closest),
       basis: agrees ? 'direct' : 'closest',
-      reason: agrees
-        ? 'Matches the idea.'
-        : unready
-          ? `\`${unready}\` matches but is not ready yet; this is the closest ready template.`
-          : direct
-            ? `Search matched \`${direct}\` by name, but this template fits more of the idea.`
-            : 'The closest template; none is exactly this page.',
+      reason: unready
+        ? `\`${unready}\` matches but is not ready yet; this is the closest ready template.`
+        : place
+          ? placed(place, closest.name)
+          : agrees
+            ? 'Matches the idea.'
+            : direct
+              ? `Search matched \`${direct}\` by name, but this template fits more of the idea.`
+              : 'The closest template; none is exactly this page.',
     };
   }
   for (const id of FALLBACK_STARTS) {
@@ -164,18 +195,21 @@ function chooseStart(ranked, pages, directMatch, catalog) {
       // The shell can also be the ranker's best guess without the evidence to
       // lead ("horizontal site navigation"); say so rather than "no match".
       const nearest = ranked[0]?.name === shell.name && ranked[0].hits > 0;
+      const place = placement(kind, false);
       return {
         ...asTemplate(shell),
         basis: 'fallback',
         reason: unready
           ? `\`${unready}\` matches but is not ready yet, so start from the app shell.`
-          : direct
-            ? `Search matched \`${direct}\` by name, but too little of the idea fits it, so start from the app shell.`
-            : nearest
-              ? 'No template is a clear match; the app shell is the closest.'
-              : loose
-                ? `Search matched ${loose} only loosely, so start from the app shell.`
-                : 'No template matched, so start from the app shell.',
+          : place
+            ? placed(place, shell.name)
+            : direct
+              ? `Search matched \`${direct}\` by name, but too little of the idea fits it, so start from the app shell.`
+              : nearest
+                ? 'No template is a clear match; the app shell is the closest.'
+                : loose
+                  ? `Search matched ${loose} only loosely, so start from the app shell.`
+                  : 'No template matched, so start from the app shell.',
       };
     }
   }
@@ -301,8 +335,18 @@ export async function buildKit(query, options = {}) {
   const wantsPages = !type || type === 'template';
   const catalog = wantsPages ? await loadPageTemplates(cwd) : [];
   const ranked = wantsPages ? rankPages(query, catalog) : [];
+  // A part of a page starts where it lives (spec:AST-048/FR3); the project's
+  // own components say what a part is. The search above already gathered them
+  // unless it was narrowed to templates.
+  const kind = wantsPages
+    ? ideaKind(
+        query,
+        catalog,
+        searchedComponents(result) ?? (await loadComponents(cwd)),
+      )
+    : 'page';
   const chosen = wantsPages
-    ? chooseStart(ranked, matchedPages, directMatch, catalog)
+    ? chooseStart(ranked, kind, matchedPages, directMatch, catalog)
     : null;
   // Name the ranker's next two templates beside the start: the reader judges
   // meaning better than keywords do, and an acceptable template is in these

package/api/build/kit/rank.d.mts

@@ -1,10 +1,6 @@
 // @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
-/**
- * @typedef {import('../_adapter.mjs').PageTemplate} PageTemplate
- * @typedef {{name: string, score: number, hits: number, familyNamed: boolean, containerMatched: boolean}} RankedPage
- */
 /**
  * Rank page templates against an idea, best first. Ties go to the template
  * with the shorter id (the family's broader page), then by name.
@@ -14,6 +10,17 @@
  * @returns {RankedPage[]}
  */
 export function rankPages(query: string, pages: PageTemplate[]): RankedPage[];
+/**
+ * What an idea asks for (spec:AST-048/FR3): a whole `page`; a `part` of one,
+ * when its head noun names one of the system's components and it lists fewer
+ * than PAGE_PIECES pieces; or an `edit` of a page the builder already has.
+ *
+ * @param {string} query
+ * @param {PageTemplate[]} pages
+ * @param {ComponentWords[]} components
+ * @returns {IdeaKind}
+ */
+export function ideaKind(query: string, pages: PageTemplate[], components: ComponentWords[]): IdeaKind;
 /**
  * The next closest templates after the start, best first: the ones a reader
  * should check the idea against when the start's shape is wrong. Each matched
@@ -26,19 +33,28 @@ export function rankPages(query: string, pages: PageTemplate[]): RankedPage[];
  */
 export function pickAlternatives(ranked: RankedPage[], startName: string, count?: number): RankedPage[];
 /**
- * The template to start from, or null when the best one has too little
- * evidence to lead and the page should start from the app shell. Evidence is
- * two matched terms, the idea naming the template's family, or its container.
+ * The template to start from, or null for the kit's neutral app shell. A page
+ * needs evidence to lead: two matched terms, the idea naming the template's
+ * family, or its container. A part starts from the base template of the family
+ * the idea places it in, else from the app shell (spec:AST-048/FR3); an edit of
+ * a page the builder already has starts from the app shell (FR9). Either way,
+ * the app shell is the shell template the idea describes when one leads.
  *
  * @param {RankedPage[]} ranked
+ * @param {IdeaKind} [kind]
  * @returns {RankedPage | null}
  */
-export function pickStart(ranked: RankedPage[]): RankedPage | null;
+export function pickStart(ranked: RankedPage[], kind?: IdeaKind): RankedPage | null;
 export type PageTemplate = import("../_adapter.mjs").PageTemplate;
+export type ComponentWords = import("../_adapter.mjs").ComponentWords;
 export type RankedPage = {
     name: string;
     score: number;
     hits: number;
     familyNamed: boolean;
     containerMatched: boolean;
+    family: string;
+    base: boolean;
+    matched: Set<string>;
 };
+export type IdeaKind = "page" | "part" | "edit";