@astryxdesign/cli 0.6.3 → 0.6.4-canary.078fd25

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 ' +
-    'playbook signal that the renderer expands into the how-to-build-a-page ' +
-    'workflow. 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.',
+    '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, ' +
+    '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>',
@@ -36,6 +40,7 @@ export const doc = {
       type: 'string',
       description:
         'Directory to resolve @astryxdesign/core and templates from.',
+      default: 'process.cwd()',
     },
     {
       name: 'options.type',
@@ -54,23 +59,30 @@ export const doc = {
     {
       type: 'build.help',
       description:
-        'Emitted when the query is omitted: a pure marker (`data.playbook: true`) that the command renderer expands into the page-building workflow prose.',
+        'Emitted when the query is omitted: the page-building playbook — `playbook: true`, a `title`, the ordered `steps` (each a `title`, its `commands`, and optionally what the step `returns`), the on-system `rules`, and `related` lookups. Each command is a bare subcommand ({command, purpose?}) for the caller to render with its own CLI invocation.',
     },
     {
       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: [
     {
       code: 'ERR_INVALID_ARGUMENT',
-      when: 'options.type is not a known domain, or options.limit is not a positive integer',
+      when: 'a query is given and options.type is not a known domain, or options.limit is not a positive integer',
+    },
+    {
+      code: 'ERR_CORE_NOT_FOUND',
+      when: 'a query is given and @astryxdesign/core cannot be found from cwd',
     },
   ],
   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 signal + composition kit).
+ * @file Tests for the build API (playbook + the template-first kit).
  */
 
 import {describe, it, expect, vi} from 'vitest';
@@ -20,10 +20,30 @@ const REPO = path.resolve(
 vi.setConfig({testTimeout: 30000});
 
 describe('build API', () => {
-  it('no query → build.help playbook signal', async () => {
+  it('no query → build.help carries the playbook as data', async () => {
     const r = await build();
     expect(r.type).toBe('build.help');
-    expect(r.data).toEqual({playbook: true});
+    if (r.type !== 'build.help') return;
+    expect(r.data.playbook).toBe(true);
+    expect(r.data.title).toMatch(/build a page/i);
+    expect(r.data.steps.length).toBeGreaterThan(0);
+    for (const step of r.data.steps) {
+      expect(step.title).toBeTruthy();
+      expect(step.commands.length).toBeGreaterThan(0);
+    }
+    expect(r.data.rules.length).toBeGreaterThan(0);
+    // Bare subcommands: the caller adds its own invocation.
+    const commands = [...r.data.steps.flatMap(s => s.commands), ...r.data.related];
+    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 () => {
@@ -65,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);
@@ -159,6 +179,28 @@ describe('build kit — coverage gates the pages group', () => {
     }
   });
 
+  it('does not call a page that only mentions every word a direct match', async () => {
+    // `empty state` and `command palette` name components. A page whose text
+    // mentions both words, or that renders the component, is a layout
+    // reference, not the page the reader asked for.
+    for (const query of ['empty state', 'command palette']) {
+      const r = await build(query, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error('expected build.kit');
+      expect(r.data.directMatch, query).toBe(false);
+    }
+  });
+
+  it('keeps the page and component a query names first', async () => {
+    const pageOf = async (/** @type {string} */ query) => {
+      const r = await build(query, {cwd: REPO});
+      if (r.type !== 'build.kit') throw new Error('expected build.kit');
+      return r.data;
+    };
+    expect((await pageOf('checkout flow')).pages[0]).toMatchObject({name: 'checkout-wizard'});
+    expect((await pageOf('sign in with sso')).pages[0]).toMatchObject({name: 'login-sso'});
+    expect((await pageOf('search results')).domain.map(e => e.name)).toContain('PowerSearch');
+  });
+
   it('leaves single-concept queries alone (nothing to cover)', async () => {
     const r = await build('dashboard', {cwd: REPO});
     expect(r.type).toBe('build.kit');
@@ -190,7 +232,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);
@@ -213,12 +255,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/);
     }
@@ -227,12 +285,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 () => {
@@ -247,3 +306,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-/);
+  });
+});

package/api/build/build.type.d.mts

@@ -2,16 +2,104 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * xds --json build (no query) — the "how to build a page" playbook signal.
+ * A command the playbook tells the caller to run.
+ */
+export type BuildPlaybookCommand = {
+    /**
+     * Bare subcommand with `<placeholder>` arguments (e.g. `template <name> <path>`) and no package-manager prefix — render it with your own CLI invocation.
+     */
+    command: string;
+    /**
+     * What running it is for.
+     */
+    purpose?: string | undefined;
+};
+/**
+ * One step of the page-building workflow.
+ */
+export type BuildPlaybookStep = {
+    /**
+     * What to do.
+     */
+    title: string;
+    /**
+     * The commands for this step, in the order to run them.
+     */
+    commands: BuildPlaybookCommand[];
+    /**
+     * What the step's command gives back, when that decides the next step.
+     */
+    returns?: string | undefined;
+};
+/**
+ * astryx --json build (no query) — the "how to build a page" playbook.
  */
 export type BuildHelpResponse = {
     type: "build.help";
     data: {
         playbook: true;
+        title: string;
+        steps: BuildPlaybookStep[];
+        rules: string[];
+        related: BuildPlaybookCommand[];
     };
 };
 /**
- * xds --json build "<idea>" — the composition kit for what you're building.
+ * The page template a kit recommends starting from.
+ */
+export type BuildStart = {
+    /**
+     * Template id, as `astryx template <name>` takes it.
+     */
+    name: string;
+    /**
+     * Human-facing template name.
+     */
+    displayName: string;
+    /**
+     * What the page is: its layout and the ideas it serves.
+     */
+    description: string;
+    /**
+     * The scaffold command that selects exactly this template, `astryx template <id> --type page <path>`: `<id>` is the Core id an integration replacement stands in for, else the template's own id, `<path>` is a placeholder for the file or folder to write the template to, and the `astryx` prefix is for the caller to replace with its own invocation.
+     */
+    command: string;
+    /**
+     * Why this template. The page ranker picks every start: it weighs each matched word by how rare it is among page templates, favors the family the idea's head names and the container it names ("in a modal"), and discounts words that only modify another. `direct` when its pick is also search's direct match (`directMatch`); `closest` when it is not; `fallback` when no template has the evidence to lead and the page starts from the app shell.
+     */
+    basis: "direct" | "closest" | "fallback";
+    /**
+     * One sentence saying the same as `basis`, for a reader.
+     */
+    reason: string;
+    /**
+     * The ranker's next closest page templates (≤2), for when the start's layout is wrong.
+     */
+    alternatives: BuildAlternative[];
+};
+/**
+ * A page template to consider instead of the start.
+ */
+export type BuildAlternative = {
+    /**
+     * Template id, as `astryx template <name>` takes it.
+     */
+    name: string;
+    /**
+     * Human-facing template name.
+     */
+    displayName: string;
+    /**
+     * What the page is: its layout and the ideas it serves.
+     */
+    description: string;
+    /**
+     * The scaffold command, in the same form as the start's.
+     */
+    command: string;
+};
+/**
+ * astryx --json build "<idea>" — the page template to start from, and the kit around it.
  *
  * Entries are raw `SearchResultEntry` objects (no package-manager-prefixed
  * command strings — the CLI adds those); `frame`/`foundation` are static
@@ -24,6 +112,7 @@ export type BuildKitResponse = {
         hasResults: boolean;
         matchCount: number;
         directMatch: boolean;
+        start: BuildStart | null;
         pages: import("../search/search.type.mjs").SearchResultEntry[];
         blocks: import("../search/search.type.mjs").SearchResultEntry[];
         domain: import("../search/search.type.mjs").SearchResultEntry[];

package/api/build/build.type.mjs

@@ -2,21 +2,64 @@
 
 /**
  * @file Colocated types for the `build` command — source of truth for the
- * `build.help` (playbook signal) and `build.kit` (composition kit) JSON
- * responses. Re-exported by types/build.d.ts.
+ * `build.help` (playbook) and `build.kit` (composition kit) JSON responses.
  */
 
 /**
- * xds --json build (no query) — the "how to build a page" playbook signal.
+ * A command the playbook tells the caller to run.
+ *
+ * @typedef {object} BuildPlaybookCommand
+ * @property {string} command Bare subcommand with `<placeholder>` arguments (e.g. `template <name> <path>`) and no package-manager prefix — render it with your own CLI invocation.
+ * @property {string} [purpose] What running it is for.
+ */
+
+/**
+ * One step of the page-building workflow.
+ *
+ * @typedef {object} BuildPlaybookStep
+ * @property {string} title What to do.
+ * @property {BuildPlaybookCommand[]} commands The commands for this step, in the order to run them.
+ * @property {string} [returns] What the step's command gives back, when that decides the next step.
+ */
+
+/**
+ * astryx --json build (no query) — the "how to build a page" playbook.
  *
  * @typedef {object} BuildHelpResponse
  * @property {'build.help'} type
  * @property {object} data
  * @property {true} data.playbook Always true; marks this envelope as the playbook rather than a result set.
+ * @property {string} data.title The playbook's heading.
+ * @property {BuildPlaybookStep[]} data.steps The workflow, in order.
+ * @property {string[]} data.rules The rules that keep a page on-system.
+ * @property {BuildPlaybookCommand[]} data.related Lookups to reach for alongside the workflow.
+ */
+
+/**
+ * The page template a kit recommends starting from.
+ *
+ * @typedef {object} BuildStart
+ * @property {string} name Template id, as `astryx template <name>` takes it.
+ * @property {string} displayName Human-facing template name.
+ * @property {string} description What the page is: its layout and the ideas it serves.
+ * @property {string} command The scaffold command that selects exactly this template, `astryx template <id> --type page <path>`: `<id>` is the Core id an integration replacement stands in for, else the template's own id, `<path>` is a placeholder for the file or folder to write the template to, and the `astryx` prefix is for the caller to replace with its own invocation.
+ * @property {'direct' | 'closest' | 'fallback'} basis Why this template. The page ranker picks every start: it weighs each matched word by how rare it is among page templates, favors the family the idea's head names and the container it names ("in a modal"), and discounts words that only modify another. `direct` when its pick is also search's direct match (`directMatch`); `closest` when it is not; `fallback` when no template has the evidence to lead and the page starts from the app shell.
+ * @property {string} reason One sentence saying the same as `basis`, for a reader.
+ * @property {BuildAlternative[]} alternatives The ranker's next closest page templates (≤2), for when the start's layout is wrong.
+ */
+
+/**
+ * A page template to consider instead of the start.
+ *
+ * @typedef {object} BuildAlternative
+ * @property {string} name Template id, as `astryx template <name>` takes it.
+ * @property {string} displayName Human-facing template name.
+ * @property {string} description What the page is: its layout and the ideas it serves.
+ * @property {string} command The scaffold command, in the same form as the start's.
  */
 
 /**
- * xds --json build "<idea>" — the composition kit for what you're building.
+ * astryx --json build "<idea>" — the page template to start from, and the kit around it.
  *
  * Entries are raw `SearchResultEntry` objects (no package-manager-prefixed
  * command strings — the CLI adds those); `frame`/`foundation` are static
@@ -26,14 +69,15 @@
  * @property {'build.kit'} type
  * @property {object} data
  * @property {string} data.query
- * @property {boolean} data.hasResults False when search returned nothing (renderer shows "No matches").
+ * @property {boolean} data.hasResults False when search returned nothing. The kit still names a template in `start`.
  * @property {number} data.matchCount Total ranked search matches for the query — counted before the search `limit`, the kit's score floors, and its per-group caps, so it is never a cap read back.
  * @property {boolean} data.directMatch True when the top page template is a confident direct match.
- * @property {import('../search/search.type.mjs').SearchResultEntry[]} data.pages Closest page templates (≤3). Each entry's `command` carries `--skeleton` when `directMatch` is false, so it recommends reading the layout rather than scaffolding it.
+ * @property {BuildStart | null} data.start The page template to start from: the ranker's pick, else the app shell. Null only when the kit is narrowed to components or hooks (`type`), or when the project has no page template to offer.
+ * @property {import('../search/search.type.mjs').SearchResultEntry[]} data.pages Closest page templates by search (≤3). Each entry's `command` carries `--skeleton` when `directMatch` is false, so it previews the layout; `start.command` is the scaffold.
  * @property {import('../search/search.type.mjs').SearchResultEntry[]} data.blocks Drop-in block patterns covering parts of the idea (≤5).
  * @property {import('../search/search.type.mjs').SearchResultEntry[]} data.domain Idea-specific components/hooks (≤6), excluding frame/foundation.
- * @property {string[]} data.frame Always-on page-shell component names.
- * @property {string[]} data.foundation Always-on layout/typography/action component names.
+ * @property {string[]} data.frame Always-on page-shell component names. Every page template already uses them.
+ * @property {string[]} data.foundation Always-on layout/typography/action component names. Every page template already uses them.
  * @property {{reason: string, commands: string[]}} [data.hint] Present only when the kit is thin. `reason` says why, `commands` are bare subcommands (e.g. `component --list`) for the caller to render with its own invocation — so a reader is never handed a command that does not resolve in their project.
  */
 

package/api/build/help/help.d.mts

@@ -2,14 +2,21 @@
 // DO NOT EDIT — run `pnpm sync:api-types` to regenerate.
 
 /**
- * @file build.help leaf — the "how to build a page" playbook signal.
+ * @file build.help leaf — the "how to build a page" playbook.
  *
- * `build` with no query returns this envelope: a pure marker that the command
- * renderer expands into the workflow playbook prose. It carries no data beyond
- * `playbook: true`, so the JSON shape stays environment-agnostic and stable.
+ * `build` with no query returns this envelope. The playbook is data — steps,
+ * rules, and related lookups — so a `--json` or programmatic caller gets the
+ * same guidance the terminal shows. Commands are bare subcommands with no
+ * package-manager prefix, which keeps the JSON environment-agnostic; the CLI
+ * renders each one with the caller's invocation, as it does build.kit's
+ * `hint.commands`.
+ *
+ * The workflow starts every page from a template, because a template already
+ * has the frame, spacing, and section rhythm that a page composed from
+ * components has to rediscover.
  */
 /**
- * The page-building playbook signal (emitted when `build` runs with no query).
+ * The page-building playbook (emitted when `build` runs with no query).
  *
  * @returns {import('../build.type.mjs').BuildHelpResponse}
  */