@astryxdesign/cli 0.6.3-canary.db4e378 → 0.6.3-canary.db52d98

package/README.md

@@ -15,6 +15,25 @@ npx @astryxdesign/cli template --list
 
 Once it's a project dependency (`npm install -D @astryxdesign/cli`), drop the scope and use the shorter `astryx` — e.g. `npx astryx component Button` or `pnpm exec astryx component Button`. Bare `astryx` resolves to an unrelated npm package until the CLI is installed, so prefer the scoped form above for first-run/one-off use.
 
+## Reading the CLI's own docs
+
+The CLI documents itself, so these commands print what the installed version does:
+
+- `astryx <command> --help`: one command's arguments and options.
+- `astryx manifest --json`: every command, option, and response type, as JSON.
+- `astryx docs cli`: the CLI's docs tree, one level at a time.
+  `astryx docs cli/commands` lists every command, `astryx docs cli/api` lists
+  the API's functions, schemas, and enums, and a route such as
+  `astryx docs cli/api/functions/search` prints one.
+- `astryx docs authoring --index`: the authoring reference, with one section for
+  each file an author writes: the `astryx.config.*` file, the
+  `astryx.integration.*` manifest, codemods, and every doc type (`ComponentDoc`,
+  `TemplateDoc`, `ThemeDoc`, and the rest). Read one section with
+  `astryx docs authoring <section>`, for example `astryx docs authoring config`.
+- `astryx docs cli/integrations`: the guide to building an integration package.
+- `astryx docs`: every docs topic, including the design-system guides (for
+  example `tokens`, `theme`, and `layout`).
+
 ## Finding things: `astryx search`
 
 When you don't know whether what you need is a component, a hook, a docs topic,
@@ -61,7 +80,7 @@ Options:
 | Command       | Description                                                                   |
 | ------------- | ----------------------------------------------------------------------------- |
 | `blog`        | Read the Astryx blog from the published feed                                  |
-| `build`       | Build a page: composition kit for an idea, or the workflow playbook (no args) |
+| `build`       | Build a page: the template to start from, or the workflow playbook (no query) |
 | `component`   | List components or print component docs                                       |
 | `discover`    | Discover external packages and components                                     |
 | `docs`        | Print reference docs                                                          |
@@ -170,6 +189,8 @@ if (isError(result)) {
 | `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_CODEMOD_FAILED`              | One or more codemods failed during an upgrade run.                                                                                                       |
+| `ERR_CODEMOD_PROTECTED`           | A required codemod change remains blocked by a protected consumer file.                                                                                  |
+| `ERR_CODEMOD_PROTECTION_SOURCE`   | A working-tree protection declaration could not be read or parsed.                                                                                       |
 | `ERR_NOT_FOUND`                   | A generic 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.                                                                                                          |
@@ -179,7 +200,7 @@ if (isError(result)) {
 | `ERR_FILE_EXISTS`                 | Refused to overwrite an existing file.                                                                                                                   |
 | `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 or contributed theme catalog is invalid.                                                                                              |
+| `ERR_THEME_INVALID`               | A theme definition or contributed theme descriptor is invalid.                                                                                           |
 | `ERR_THEME_LOAD`                  | A theme file could not be loaded / parsed into a defineTheme result.                                                                                     |
 | `ERR_PALETTE_GENERATION`          | A palette generation request or one of its constraints was invalid.                                                                                      |
 | `ERR_VERSION_DETECT`              | The current `@astryxdesign/core` version could not be detected.                                                                                          |
@@ -407,24 +428,25 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `component.detail.source`         | One component's source file, as {component, source}.                                                                                                                                                                                                                                                                                                                                                                                       |
 | `component.detail.showcase`       | One component's showcase example, as {component, aspectRatio, source}.                                                                                                                                                                                                                                                                                                                                                                     |
 | `component.detail.blocks`         | One component's example blocks, as {component, showcase, examples, related} of BlockEntry.                                                                                                                                                                                                                                                                                                                                                 |
-| `docs.list`                       | All reference-doc topics as DocsListEntry[] ({topic, description}), in discovery order.                                                                                                                                                                                                                                                                                                                                                    |
-| `docs.detail`                     | One topic's full ReferenceDoc, with token-ref blocks inlined.                                                                                                                                                                                                                                                                                                                                                                              |
-| `docs.index`                      | One topic's section index (--index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary).                                                                                                                                                                                                                                  |
-| `docs.detail.section`             | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined.                                                                                                                                                                                                                                                                                                                                                     |
+| `docs.list`                       | All reference-doc topics as DocsListEntry[] ({topic, description, package, replaces?}), in read order; meta.namespaces lists the docs tree's top-level namespaces, and meta.notLoaded each package whose docs did not load.                                                                                                                                                                                                                |
+| `docs.detail`                     | One topic's full ReferenceDoc (the JSON read of a topic, --full, --dense, or a topic with one section), with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).                                                                                                                                                                                             |
+| `docs.index`                      | One topic's section index, the text read of a topic with more than one section (and --index): the topic's name, title, and description, plus sections, each {id, title, summary} (pass the id as the section argument; summary is the section's one-line summary), and links ({up, previous, next}: the commands that open the level it sits in and its neighbors there).                                                                  |
+| `docs.detail.section`             | One ReferenceSection of a topic, found by key or title, with token-ref blocks inlined, plus links ({up, previous, next}: the commands that open its topic index and the sections before and after it).                                                                                                                                                                                                                                     |
+| `docs.node`                       | One node of the docs tree, read by its route: its id, kind, package, title, summary, and breadcrumb, plus a namespace's slots with their children (one level down) or a typed doc's content, and links ({up, previous, next, related}: the commands that open its parent, its neighbors, and the docs it names).                                                                                                                           |
 | `blog.list`                       | The feed URL plus every post parsed from the RSS feed, each with slug, title, description, date, type, authors, link, and plaintext URL.                                                                                                                                                                                                                                                                                                   |
 | `blog.detail`                     | One post's metadata plus the feed URL and the post's full plaintext body.                                                                                                                                                                                                                                                                                                                                                                  |
 | `discover.list`                   | The configured external packages (name, category, components, version, description); when empty it carries meta.configured to tell "nothing configured" from "nothing discovered".                                                                                                                                                                                                                                                         |
 | `discover.detail`                 | A single external package entry, for an @scope/name query.                                                                                                                                                                                                                                                                                                                                                                                 |
 | `discover.detail.doc`             | The validated ComponentDoc for one external component: an @scope/name/Component query, or a free-text term resolving to exactly one component.                                                                                                                                                                                                                                                                                             |
 | `discover.search`                 | The echoed query plus the matching {package, component} pairs, when a free-text term matches several components.                                                                                                                                                                                                                                                                                                                           |
-| `search`                          | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title (docs), or displayName and kind (templates).                                                                                                                                                                |
+| `search`                          | The echoed query, `matchCount` (total matches, before `limit`), and results, a ranked SearchResultEntry[] bounded by `limit`: each {domain, name, score, reason, description, command}, plus import (components, hooks), title, parent (the command that opens the level above), package (for a docs-tree hit), and, for a hit on one section, section (docs), or displayName and kind (templates).                                        |
 | `build.help`                      | The how-to-build-a-page playbook, emitted when no query is given: `playbook: true`, a title, the ordered steps (title, commands, optional returns), the on-system rules, and related lookups. Commands are bare subcommands for the caller to render with its own invocation.                                                                                                                                                              |
-| `build.kit`                       | The composition kit: echoed query, hasResults, matchCount (total matched, never a cap), directMatch, pages (closest templates), blocks (drop-in patterns) and domain (idea components/hooks) as SearchResultEntry[], frame and foundation name arrays, and hint {reason, commands} when thin.                                                                                                                                              |
+| `build.kit`                       | The template to start from and its kit: query, hasResults, matchCount (never a cap), directMatch, start {name, command, basis, reason, alternatives, ...}, pages (search's closest templates), blocks and domain as SearchResultEntry[], frame, foundation, and hint {reason, commands} when thin.                                                                                                                                         |
 | `swizzle.list`                    | The names of swizzlable components discoverable from cwd's @astryxdesign/core.                                                                                                                                                                                                                                                                                                                                                             |
 | `swizzle.copy`                    | An eject receipt: component name, owning package, output directory, files-copied count, the written file names, whether any file uses StyleX, and an optional maintainer note.                                                                                                                                                                                                                                                             |
 | `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`                   | Every discovered template (page + block); each entry carries id, name, description, kind, owning package, optional category and componentsUsed, and readiness flags.                                                                                                                                                                                                                                                                       |
+| `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.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.                                                                                                                                                                                                                                                                                                                                                      |
@@ -448,9 +470,9 @@ Every response has a `type` discriminant. The full set is below (generated from
 | `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 conflicts where an integration template id is also owned by Core; each conflict includes the exact package-qualified command.                                                                                                                                                                                                                                                |
+| `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 classified as intentional replacements, intentional extensions, or accidental same-name conflicts.                                                                                                                                                                                                                                                                      |
+| `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).                                                                                                                                                                                                       |
 | `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.                                                                                                                                                                                                                                                                        |
@@ -646,9 +668,10 @@ wrong type fails there; a field this CLI does not know is ignored with a
 warning naming it, so a manifest written against a newer CLI still contributes
 everything this one understands.
 
-Discovery is resilient: a broken or misconfigured integration is skipped with a
-one-line warning on stderr instead of crashing the CLI, and it never corrupts a
-`--json` envelope. To inspect problems, run
+Discovery is resilient. A manifest load failure skips that package with a warning.
+An invalid contribution kind remains reportable without hiding other valid kinds,
+and invalid template or component metadata is omitted without hiding valid siblings.
+Warnings go to stderr and never corrupt a `--json` envelope. To inspect problems, run
 `astryx doctor integration validate <package>` for structure, then use `templates`,
 `components`, or `docs` under the same `astryx doctor integration` group to check
 Core identity overlaps before publishing. Bare `astryx doctor` checks overall
@@ -658,5 +681,5 @@ For the full authoring walkthrough (component doc format, template packaging
 and `exports` requirements, and codemod authoring), see the guide:
 
 ```bash
-astryx docs cli-integrations
+astryx docs cli/integrations
 ```

package/api/blog/blog.doc.mjs

@@ -11,6 +11,7 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'blog',
+  namespace: 'cli/api',
   displayName: 'blog()',
   summary: 'List blog posts, or read one, from the published RSS feed.',
   description:

package/api/build/_adapter.d.mts

@@ -0,0 +1,50 @@
+// @generated by scripts/sync-api-types.mjs from the JSDoc in api/**/*.mjs.
+// DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
+
+/**
+ * A page template the kit can recommend starting from.
+ * @typedef {object} PageTemplate
+ * @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} category The template's own `Family - Variant` label; empty when it declares none.
+ */
+/**
+ * Every ready page template the project can scaffold, in discovery order. This
+ * is the default discovery view: an active integration replacement stands in
+ * for the Core template it replaces, as it does for `astryx template <id>`.
+ *
+ * Discovery failures leave the kit without a start rather than failing the
+ * command: the kit still carries its search matches, and `template --list`
+ * reports what went wrong.
+ *
+ * @param {string} cwd
+ * @returns {Promise<PageTemplate[]>}
+ */
+export function loadPageTemplates(cwd: string): Promise<PageTemplate[]>;
+/**
+ * A page template the kit can recommend starting from.
+ */
+export type PageTemplate = {
+    /**
+     * The template's own id, as search reports it.
+     */
+    name: string;
+    /**
+     * `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.
+     */
+    command: string;
+    /**
+     * Human-facing name.
+     */
+    displayName: string;
+    /**
+     * What the page is: its layout and the ideas it serves.
+     */
+    description: string;
+    /**
+     * The template's own `Family - Variant` label; empty when it declares none.
+     */
+    category: string;
+};

package/api/build/_adapter.mjs

@@ -0,0 +1,60 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The build subject's environment access: the page templates a project
+ * can scaffold.
+ *
+ * @input Template discovery for `cwd` — the CLI's own templates 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.
+ */
+
+import {discoverTemplates} from '../template/template.mjs';
+
+/**
+ * A page template the kit can recommend starting from.
+ * @typedef {object} PageTemplate
+ * @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} category The template's own `Family - Variant` label; empty when it declares none.
+ */
+
+/**
+ * Every ready page template the project can scaffold, in discovery order. This
+ * is the default discovery view: an active integration replacement stands in
+ * for the Core template it replaces, as it does for `astryx template <id>`.
+ *
+ * Discovery failures leave the kit without a start rather than failing the
+ * command: the kit still carries its search matches, and `template --list`
+ * reports what went wrong.
+ *
+ * @param {string} cwd
+ * @returns {Promise<PageTemplate[]>}
+ */
+export async function loadPageTemplates(cwd) {
+  let templates;
+  try {
+    templates = await discoverTemplates(cwd);
+  } catch {
+    return [];
+  }
+  return templates
+    .filter(t => t.type === 'page' && t.isReady !== false)
+    .map(t => ({
+      name: t.dirName,
+      displayName: t.displayName || t.name,
+      description: t.description || '',
+      category: t.category || '',
+      // 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`,
+    }));
+}

package/api/build/build.doc.mjs

@@ -11,15 +11,19 @@ export const doc = {
   type: 'function',
   kind: 'api',
   name: 'build',
+  namespace: 'cli/api',
   displayName: 'build()',
   summary:
-    'Page-building assistant: the how-to-build playbook, or a composition kit for an idea.',
+    'Page-building assistant: the how-to-build playbook, or the page template to start from for an idea.',
   description:
-    'The "assemble a page" entry point. Called with no query it returns the ' +
+    '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 runs the unified search and groups the ' +
-    'hits into a composition KIT: the closest page templates, drop-in blocks, ' +
-    'and idea-specific components/hooks, plus the always-on frame + foundation.',
+    '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, ' +
+    '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.',
   importPath: '@astryxdesign/cli/api',
   signature:
     'build(query?: string, options?: BuildOptions): Promise<BuildHelpResponse | BuildKitResponse>',
@@ -59,7 +63,7 @@ export const doc = {
     {
       type: 'build.kit',
       description:
-        'The grouped composition kit: the echoed query, hasResults/matchCount/directMatch fields, the closest page templates (≤3), drop-in block patterns (≤5), idea-specific components/hooks (≤6), and the always-on frame + foundation component-name arrays. Carries `hint` only when the kit came back thin — what to try instead, so a caller does not read a near-empty kit as "the package has nothing".',
+        "The page template to start from and the kit around it: the echoed query, hasResults/matchCount/directMatch fields, `start` (the template to scaffold, the `template <id> --type page <path>` command that selects it, whether the page ranker's pick is also search's direct match, the closest page, or the fallback app shell, and the ranker's next two `alternatives`), search's closest page templates (≤3), drop-in block patterns (≤5), idea-specific components/hooks (≤6), and the always-on frame + foundation component-name arrays. Carries `hint` only when the kit came back thin — what to try instead, so a caller does not read a near-empty kit as \"the package has nothing\".",
     },
   ],
   throws: [
@@ -70,7 +74,10 @@ export const doc = {
   ],
   examples: [
     {label: 'Get the playbook', code: 'const r = await build();'},
-    {label: 'Compose a page', code: "await build('analytics dashboard');"},
+    {
+      label: 'Find the template to start from',
+      code: "const {data} = await build('analytics dashboard');\n// data.start.command: 'astryx template dashboard --type page <path>'",
+    },
     {
       label: 'Restrict + limit',
       code: "await build('pricing', {type: 'template', limit: 10});",

package/api/build/build.test.mjs

@@ -1,7 +1,7 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
 /**
- * @file Tests for the build API (playbook + composition kit).
+ * @file Tests for the build API (playbook + the template-first kit).
  */
 
 import {describe, it, expect, vi} from 'vitest';
@@ -37,6 +37,15 @@ describe('build API', () => {
     for (const {command} of commands) expect(command).not.toMatch(/^(astryx|npx|pnpm|yarn|bunx?)\b/);
   });
 
+  it('the playbook scaffolds the named template before composing', async () => {
+    const r = await build();
+    if (r.type !== 'build.help') throw new Error(r.type);
+    const commands = r.data.steps.map(s => s.commands.map(c => c.command));
+    expect(commands[0][0]).toMatch(/^build /);
+    expect(commands[1]).toContain('template <name> <path>');
+    expect(JSON.stringify(r.data)).not.toMatch(/--skeleton|reference code/);
+  });
+
   it('query → build.kit with raw entries + static frame/foundation', async () => {
     const r = await build('dashboard', {cwd: REPO});
     expect(r.type).toBe('build.kit');
@@ -76,10 +85,10 @@ describe('build API', () => {
     expect(blocks.length).toBeLessThanOrEqual(5);
     expect(domain.length).toBeLessThanOrEqual(6);
 
-    // Score floors: pages ≥ PAGE_FLOOR(50); blocks/domain ≥ DOMAIN_FLOOR(55).
+    // Score floors: pages ≥ PAGE_FLOOR(50); blocks/domain ≥ DOMAIN_FLOOR(60).
     for (const p of pages) expect(p.score).toBeGreaterThanOrEqual(50);
-    for (const b of blocks) expect(b.score).toBeGreaterThanOrEqual(55);
-    for (const d of domain) expect(d.score).toBeGreaterThanOrEqual(55);
+    for (const b of blocks) expect(b.score).toBeGreaterThanOrEqual(60);
+    for (const d of domain) expect(d.score).toBeGreaterThanOrEqual(60);
 
     // directMatch iff the top page is a confident match (PAGE_DIRECT = 95).
     expect(directMatch).toBe(pages.length > 0 && pages[0].score >= 95);
@@ -201,7 +210,7 @@ describe('build kit — a thin kit says what to try next', () => {
   it('hints for a matched-then-filtered query: hasResults true, nothing offerable', async () => {
     // The case most likely to be misread, and the reason the threshold counts
     // what SURVIVED the floors rather than what search returned.
-    const r = await build('blockchain', {cwd: REPO});
+    const r = await build('hydration', {cwd: REPO});
     expect(r.type).toBe('build.kit');
     if (r.type !== 'build.kit') return;
     expect(r.data.hasResults).toBe(true);
@@ -224,12 +233,28 @@ describe('build kit — a thin kit says what to try next', () => {
     }
   });
 
+  it('still starts from the closest page on a loose match, and scaffolds it', async () => {
+    // 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});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.directMatch).toBe(false);
+    expect(r.data.start).toMatchObject({
+      name: 'dashboard-scorecard',
+      basis: 'closest',
+      command: 'astryx template dashboard-scorecard --type page <path>',
+    });
+  });
+
   it('recommends scaffolding on a direct match', async () => {
     const r = await build('contact form', {cwd: REPO});
     expect(r.type).toBe('build.kit');
     if (r.type !== 'build.kit') return;
     expect(r.data.directMatch).toBe(true);
     expect(r.data.pages.length).toBeGreaterThan(0);
+    expect(r.data.start).toMatchObject({name: r.data.pages[0].name, basis: 'direct'});
     for (const page of r.data.pages) {
       expect(page.command).not.toMatch(/--skeleton/);
     }
@@ -238,12 +263,13 @@ describe('build kit — a thin kit says what to try next', () => {
   it('keeps the recommendation package-manager-agnostic', async () => {
     // Appending a flag must not turn into prefixing an invocation; that stays
     // the renderer's job.
-    const r = await build('notifications', {cwd: REPO});
+    const r = await build('executive summary', {cwd: REPO});
     expect(r.type).toBe('build.kit');
     if (r.type !== 'build.kit') return;
     for (const page of r.data.pages) {
       expect(page.command).not.toMatch(/^(pnpm|npm|yarn|bun|npx)\b/);
     }
+    expect(r.data.start?.command).not.toMatch(/^(pnpm|npm|yarn|bun|npx)\b/);
   });
 
   it('keeps recovery commands bare, for the caller to render', async () => {
@@ -258,3 +284,155 @@ describe('build kit — a thin kit says what to try next', () => {
     }
   });
 });
+
+describe('build kit — every page starts from a template', () => {
+  it('falls back to the app shell when no page template matches', async () => {
+    // Before, an unmatched idea got "compose from AppShell": the one path
+    // with no frame, no spacing, and no section rhythm.
+    const r = await build('zzznomatch99', {cwd: REPO});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.hasResults).toBe(false);
+    expect(r.data.start).toMatchObject({
+      name: 'shell-top-nav',
+      basis: 'fallback',
+      command: 'astryx template shell-top-nav --type page <path>',
+    });
+    expect(r.data.start?.description).toBeTruthy();
+  });
+
+  it('starts a long idea from the family its words name', async () => {
+    // The coverage gate cannot tell layout words from subject matter: every
+    // dashboard covers one term of three, so search offers no page at all.
+    // The ranker still starts the page from the dashboard.
+    const r = await build('quarterly revenue dashboard', {cwd: REPO});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.start).toMatchObject({name: 'dashboard', basis: 'closest'});
+    expect(r.data.directMatch).toBe(false);
+  });
+
+  it('does not start from a direct match that is not ready yet, and says so', async () => {
+    const r = await build('incident console', {cwd: REPO});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.directMatch).toBe(true);
+    expect(r.data.pages[0].name).toBe('incident-console');
+    expect(r.data.start?.name).not.toBe('incident-console');
+    expect(r.data.start?.reason).toMatch(/`incident-console` matches but is not ready yet/);
+  });
+
+  it('does not start from a page that matched one incidental word', async () => {
+    // A work-item detail page mentions a feed in its description. That is a
+    // worse start for a news feed than the app shell.
+    const r = await build('news feed', {cwd: REPO});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.start?.basis).toBe('fallback');
+  });
+
+  it('starts a part from the page it is placed in, else from the app shell', async () => {
+    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'});
+    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'});
+  });
+
+  it('names a direct match the ranker outweighed in the reason', async () => {
+    const r = await build('dashboard with a login form', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error(r.type);
+    expect(r.data.directMatch).toBe(true);
+    expect(r.data.pages[0].name).toBe('login');
+    expect(r.data.start).toMatchObject({name: 'dashboard', basis: 'closest'});
+    expect(r.data.start?.reason).toContain('`login`');
+  });
+
+  it('names the loose page matches when it falls back to the shell', async () => {
+    const r = await build('news feed', {cwd: REPO});
+    if (r.type !== 'build.kit') throw new Error(r.type);
+    expect(r.data.pages.length).toBeGreaterThan(0);
+    expect(r.data.start?.basis).toBe('fallback');
+    for (const page of r.data.pages) expect(r.data.start?.reason).toContain(`\`${page.name}\``);
+  });
+
+  it('never gives a reason that denies a match the response reports', async () => {
+    for (const q of ['news feed', 'dashboard with a login form', 'user profile', 'incident console']) {
+      const r = await build(q, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error(r.type);
+      if (r.data.pages.length) expect(r.data.start?.reason).not.toMatch(/No template matched/);
+      if (r.data.directMatch) expect(r.data.start?.reason).not.toMatch(/none is exactly this page/);
+    }
+  });
+
+  it('names no start when the kit is narrowed to components', async () => {
+    const r = await build('dashboard', {cwd: REPO, type: 'component'});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.start).toBeNull();
+  });
+
+
+
+  it('keeps incidental description matches out of blocks and components', async () => {
+    // Toast, Popover and TextInput all say "brief" somewhere in their
+    // descriptions; none of them is part of a brief.
+    const r = await build('weekly brief', {cwd: REPO});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    const names = [...r.data.blocks, ...r.data.domain].map(e => e.name);
+    for (const noise of ['Toast', 'Popover', 'TextInput']) expect(names).not.toContain(noise);
+  });
+
+  it('names the ranker\'s next two templates beside every start', async () => {
+    for (const idea of ['quarterly revenue dashboard', 'contact form']) {
+      const r = await build(idea, {cwd: REPO});
+      expect(r.type).toBe('build.kit');
+      if (r.type !== 'build.kit') return;
+      const alternatives = r.data.start?.alternatives ?? [];
+      expect(alternatives.length).toBeGreaterThan(0);
+      expect(alternatives.length).toBeLessThanOrEqual(2);
+      for (const alt of alternatives) {
+        expect(alt.name).not.toBe(r.data.start?.name);
+        expect(alt.description).toBeTruthy();
+        expect(alt.command).toBe(`astryx template ${alt.name} --type page <path>`);
+      }
+    }
+  });
+
+  it('calls a start direct only when search and the ranker agree', async () => {
+    const r = await build('contact form', {cwd: REPO});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.directMatch).toBe(true);
+    expect(r.data.start).toMatchObject({name: r.data.pages[0].name, basis: 'direct'});
+  });
+
+  it('never lets a noisy search match pick the start', async () => {
+    // Search once matched "site" to the gallery's "side" and started a
+    // navigation bar from a gallery. The ranker alone picks the start now.
+    const r = await build('horizontal site navigation with a current section indicator', {cwd: REPO});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.start?.name).toBe('shell-top-nav');
+    expect(r.data.pages.map(p => p.name)).not.toContain('side-gallery');
+  });
+
+  it('starts a component in a container from a template with that frame', async () => {
+    // "in a modal": the modal is the frame, so the dialog template leads
+    // instead of the app shell.
+    const r = await build('saved drafts in a modal with resume and delete row actions', {cwd: REPO});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.start?.name).toBe('settings-dialog');
+  });
+
+  it('does not start from a template named only by a word that modifies another', async () => {
+    // "product" describes the response; it is not a product page.
+    const r = await build('an interactive command catalog with side-by-side product response and trace', {cwd: REPO});
+    expect(r.type).toBe('build.kit');
+    if (r.type !== 'build.kit') return;
+    expect(r.data.start?.name).not.toMatch(/^product-/);
+  });
+});