@astryxdesign/cli 0.6.3 → 0.6.4-canary.06c8fa3

package/api/search/search.mjs

@@ -17,21 +17,31 @@
  * component fuzzy resolver in lib/string-utils.mjs:
  *
  *   100  exact name match
+ *    95  name is the term's plural or stem form ("buttons" -> Button)
  *    90  exact keyword match
- *    80  name Levenshtein distance 1
- *    70  keyword substring / distance 1
- *    60  name substring (>=4 chars, >=50% coverage)
+ *    88  keyword is the term's plural or stem form
+ *    80  name Levenshtein distance 1 (one-word lookups, words of 5+ letters)
+ *    70  keyword word prefix / distance 1 (distance: one-word lookups, 5+ letters)
+ *    60  name word prefix (>=4 chars, >=50% coverage)
  *    60  exact weak-keyword match
  *    50  description / prose mentions the term
  *    45  usage guidance mentions the term
- *    40  name Levenshtein distance 2
- *    40  weak-keyword substring
- *    30  keyword Levenshtein distance 2
- *    20  name Levenshtein distance 3
+ *    40  name Levenshtein distance 2 (one-word lookups, 8+ letters)
+ *    40  weak-keyword word prefix
+ *    30  keyword Levenshtein distance 2 (one-word lookups, 8+ letters)
+ *    20  name Levenshtein distance 3 (one-word lookups, 11+ letters)
  *
  * Name + keyword signals always outweigh description/prose, so an exact match
  * sorts above an incidental mention.
  *
+ * A term matches inside a name or keyword only at the start of one of its
+ * words: "dash" finds "dashboard" and "input" finds "TextInput", but "file"
+ * does not find "profile". Edit distance is typo tolerance, so it applies only
+ * to a one-word lookup, where a typo is the likely explanation, and only to
+ * words long enough that one edit rarely makes another real word. In a
+ * sentence, a near miss is usually a different word: "site" is not "side",
+ * "cable" is not "table".
+ *
  * Description and guidance are separate tiers on purpose. A component's own
  * one-line description saying "notification" is a claim about what it IS; the
  * same word inside another component's best-practice advice is a passing
@@ -50,11 +60,11 @@
  * queries they have nothing to do with.
  */
 
-import {pathToFileURL} from 'node:url';
+import {readDocView} from '../../foundation/doc-compiler/read.mjs';
 import {findCoreDir} from '../../foundation/fs/paths.mjs';
 import {
   discoverComponents,
-  discoverIntegrationComponents,
+  discoverValidIntegrationComponents,
   findComponentReadme,
   resolveImportPath,
   resolveIntegrationImportPath,
@@ -66,7 +76,20 @@ import {
 import {loadIntegrationsSafely} from '../component/_adapter.mjs';
 import {levenshteinDistance} from '../../foundation/text/string-utils.mjs';
 import {discoverTemplates, extractComponents} from '../template/template.mjs';
-import {loadDocsCatalog, loadTopicDoc} from '../docs/_adapter.mjs';
+import {templateLookupIds} from '../../foundation/discovery/template-adapter.mjs';
+import {
+  guideEntry,
+  loadDocsCatalog,
+  lowerTopic,
+  projectTree,
+  holdsOwnName,
+} from '../docs/_adapter.mjs';
+import {unlinkText} from '../../foundation/doc-compiler/links.mjs';
+import {nodeView} from '../docs/node/node.mjs';
+import {
+  sectionKey,
+  sectionSummary,
+} from '../../foundation/discovery/docs-section-key.mjs';
 import {AstryxError} from '../error.mjs';
 import {ERROR_CODES} from '../../foundation/response/error-codes.mjs';
 import {setResultCoverage} from './coverage.mjs';
@@ -84,17 +107,28 @@ import {setResultCoverage} from './coverage.mjs';
  * @property {string[]} [guidance]
  * @property {string} [_import]
  * @property {string} [_title]
+ * @property {string} [_topic] - A doc result's topic or docs-tree route.
+ * @property {string} [_section] - A doc result's section key, when it is one section.
+ * @property {string} [_command] - The command that reads exactly this doc part.
+ * @property {string} [_parent] - The command that opens the level above a doc
+ *   part: its topic's section list, or the docs-tree namespace it sits in.
+ * @property {string} [_package] - The npm package that authored a docs-tree
+ *   doc part. Flat topics carry none: an extension's sections can come from
+ *   another package.
  * @property {string} [_displayName]
  * @property {'page'|'block'} [_kind]
+ * @property {string} [_resultName]
+ * @property {string} [_commandName]
  */
 
 /**
  * Synonym / intent map: product-language terms an agent is likely to type,
  * expanded to the catalog's vocabulary so oblique queries still rank. Keys and
  * values are matched bidirectionally (typing any value also pulls in the key
- * and its siblings). Lowercase, single words or short phrases.
+ * and its siblings). Lowercase, single words or short phrases. Exported for
+ * `build`, whose page ranker expands a query with the same vocabulary.
  */
-const SYNONYMS = {
+export const SYNONYMS = {
   dashboard: [
     'overview',
     'analytics',
@@ -166,14 +200,90 @@ export function stem(w) {
   return s;
 }
 
+/**
+ * The forms of a word that count as the same word: itself, its stem, and its
+ * singular when it ends in a plural suffix — so "tables" is "table",
+ * "statuses" is "status", and "filtering" is "filter".
+ * @param {string} w - Lowercase word.
+ * @returns {Set<string>}
+ */
+function wordForms(w) {
+  const forms = new Set([w, stem(w)]);
+  if (w.length > 3 && w.endsWith('s')) forms.add(w.slice(0, -1));
+  if (w.length > 4 && w.endsWith('es')) forms.add(w.slice(0, -2));
+  if (w.length > 4 && w.endsWith('ies')) forms.add(w.slice(0, -3) + 'y');
+  return forms;
+}
+
+/**
+ * Whether two lowercase words are the same word, up to plural and stem form.
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+export function sameWord(a, b) {
+  if (a === b) return true;
+  const forms = wordForms(a);
+  for (const f of wordForms(b)) if (forms.has(f)) return true;
+  return false;
+}
+
+/**
+ * The lowercase words of a name or keyword: split at non-alphanumerics and at
+ * camelCase boundaries, so "TextInput" is ["text", "input"] and
+ * "Dashboard - Analytics" is ["dashboard", "analytics"].
+ * @param {string} text
+ * @returns {string[]}
+ */
+function wordsOf(text) {
+  return String(text)
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z])([A-Z][a-z])/g, '$1 $2')
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+}
+
+/**
+ * Whether a term is found inside a name or keyword: it is one of its words, or
+ * the start of one (a truncation), and covers at least half of the whole
+ * string. Four letters minimum, so a short term never matches by accident.
+ * @param {string} term - Lowercase term.
+ * @param {string} text - The name or keyword as authored.
+ * @returns {boolean}
+ */
+function startsAWordOf(term, text) {
+  if (term.length < 4) return false;
+  if (term.length / String(text).length < 0.5) return false;
+  return wordsOf(text).some(w => w.startsWith(term) || sameWord(term, w));
+}
+
+/**
+ * The fewest letters both words need before an edit distance counts as a
+ * typo, by distance. Below them, one edit usually makes a different word.
+ */
+const TYPO_MIN_LENGTH = {1: 5, 2: 8, 3: 11};
+
+/**
+ * @param {string} a
+ * @param {string} b
+ * @param {number} dist
+ */
+const isTypo = (a, b, dist) =>
+  dist > 0 &&
+  dist <= 3 &&
+  Math.min(a.length, b.length) >=
+    TYPO_MIN_LENGTH[/** @type {1 | 2 | 3} */ (dist)];
+
 /** Valid domain filters for `--type`. */
 export const SEARCH_DOMAINS = ['component', 'hook', 'doc', 'template'];
 
 /**
  * Filler words stripped from multi-word queries so natural-language phrasing
  * ("a page where you can see business stats") ranks on its content words.
+ * Exported for `build`, whose page ranker strips the same words.
  */
-const STOPWORDS = new Set([
+export const STOPWORDS = new Set([
   'a',
   'an',
   'the',
@@ -285,14 +395,15 @@ const MIN_TOKEN_SCORE = 50;
  * (synonym hits are discounted so a direct hit always wins).
  * @param {string} tok
  * @param {Candidate} candidate
+ * @param {{fuzzy?: boolean}} [opts]
  * @returns {{score: number, reason: string} | null}
  */
-function bestForToken(tok, candidate) {
-  let best = scoreCandidate(tok, candidate);
+function bestForToken(tok, candidate, opts = {}) {
+  let best = scoreCandidate(tok, candidate, opts);
   const syns = SYNONYM_INDEX.get(tok);
   if (syns) {
     for (const s of syns) {
-      const h = scoreCandidate(s, candidate);
+      const h = scoreCandidate(s, candidate, opts);
       if (h) {
         const score = Math.round(h.score * 0.85);
         if (!best || score > best.score)
@@ -322,14 +433,17 @@ export function scoreQuery(term, tokens, candidate) {
     matched: total,
     total,
   });
-  const full = scoreCandidate(term, candidate);
+  // Typo tolerance is for one-word lookups. In a multi-word query a near miss
+  // is usually a different word, not a typo.
+  const fuzzy = tokens.length <= 1;
+  const full = scoreCandidate(term, candidate, {fuzzy});
 
   // 0–1 content tokens: keep whole-phrase fuzzy matching (typo tolerance for
   // single words), but if stopwords left exactly one DIFFERENT token (e.g.
   // "pricing page" → "pricing"), score that token too and take the stronger.
   if (tokens.length <= 1) {
     const single =
-      tokens.length === 1 ? bestForToken(tokens[0], candidate) : null;
+      tokens.length === 1 ? bestForToken(tokens[0], candidate, {fuzzy}) : null;
     if (full && (!single || full.score >= single.score)) return asFull(full);
     return single ? asFull(single) : null;
   }
@@ -356,7 +470,7 @@ export function scoreQuery(term, tokens, candidate) {
   /** @type {string[]} */
   const hitTerms = [];
   for (const tok of tokens) {
-    const h = bestForToken(tok, candidate);
+    const h = bestForToken(tok, candidate, {fuzzy});
     if (h && h.score >= MIN_TOKEN_SCORE) {
       if (h.score > strongest) strongest = h.score;
       matched++;
@@ -409,6 +523,7 @@ export function scoreQuery(term, tokens, candidate) {
  * @param {string} [candidate.description]
  * @param {string[]} [candidate.prose] - Extra free-text blobs (doc section text, best practices).
  * @param {string[]} [candidate.guidance] - Usage guidance (features, best practices) — scored a tier below description.
+ * @param {{fuzzy?: boolean}} [opts] - `fuzzy`: allow edit-distance (typo) matches. Default true; multi-word queries pass false.
  * @returns {{score: number, reason: string} | null}
  */
 export function scoreCandidate(
@@ -421,6 +536,7 @@ export function scoreCandidate(
     prose = [],
     guidance = [],
   },
+  {fuzzy = true} = {},
 ) {
   let best = 0;
   let reason = '';
@@ -441,20 +557,20 @@ export function scoreCandidate(
   if (nameLower === term) {
     consider(100, 'exact name');
   } else {
-    // Substring (both directions), min 4 chars, >=50% coverage.
-    const shorter = term.length < nameLower.length ? term : nameLower;
-    const longer = term.length < nameLower.length ? nameLower : term;
-    if (
-      shorter.length >= 4 &&
-      longer.includes(shorter) &&
-      shorter.length / longer.length >= 0.5
-    ) {
-      consider(60, `name contains "${shorter}"`);
+    if (sameWord(term, nameLower)) consider(95, `name "${name}"`);
+    // The term is a word of the name, or starts one: "input" in TextInput.
+    else if (startsAWordOf(term, name)) {
+      consider(60, `name contains "${term}"`);
+    }
+    if (fuzzy) {
+      const dist = levenshteinDistance(term, nameLower);
+      if (isTypo(term, nameLower, dist)) {
+        consider(
+          dist === 1 ? 80 : dist === 2 ? 40 : 20,
+          `similar name (distance ${dist})`,
+        );
+      }
     }
-    const dist = levenshteinDistance(term, nameLower);
-    if (dist === 1) consider(80, `similar name (distance ${dist})`);
-    else if (dist === 2) consider(40, `similar name (distance ${dist})`);
-    else if (dist === 3) consider(20, `similar name (distance ${dist})`);
   }
 
   // ── Keyword signals ─────────────────────────────────────────────
@@ -464,14 +580,17 @@ export function scoreCandidate(
       consider(90, `keyword "${kw}"`);
       continue;
     }
-    const s = term.length < kwLower.length ? term : kwLower;
-    const l = term.length < kwLower.length ? kwLower : term;
-    if (s.length >= 4 && l.includes(s) && s.length / l.length >= 0.5) {
-      consider(70, `keyword "${kw}"`);
+    if (sameWord(term, kwLower)) {
+      consider(88, `keyword "${kw}"`);
+      continue;
+    }
+    if (startsAWordOf(term, kw)) consider(70, `keyword "${kw}"`);
+    if (fuzzy) {
+      const dist = levenshteinDistance(term, kwLower);
+      if (isTypo(term, kwLower, dist) && dist <= 2) {
+        consider(dist === 1 ? 70 : 30, `keyword "${kw}" (distance ${dist})`);
+      }
     }
-    const dist = levenshteinDistance(term, kwLower);
-    if (dist === 1) consider(70, `keyword "${kw}" (distance ${dist})`);
-    else if (dist === 2) consider(30, `keyword "${kw}" (distance ${dist})`);
   }
 
   // ── Weak keyword signals (derived, not authored) ─────────────────
@@ -481,15 +600,11 @@ export function scoreCandidate(
   // No Levenshtein tier — fuzzy matching a derived signal is pure noise.
   for (const kw of weakKeywords) {
     const kwLower = String(kw).toLowerCase();
-    if (kwLower === term) {
+    if (kwLower === term || sameWord(term, kwLower)) {
       consider(60, `renders ${kw}`);
       continue;
     }
-    const s = term.length < kwLower.length ? term : kwLower;
-    const l = term.length < kwLower.length ? kwLower : term;
-    if (s.length >= 4 && l.includes(s) && s.length / l.length >= 0.5) {
-      consider(40, `renders ${kw}`);
-    }
+    if (startsAWordOf(term, kw)) consider(40, `renders ${kw}`);
   }
 
   // ── Prose / description / guidance signals (stem-tolerant whole word) ──
@@ -528,16 +643,26 @@ export function scoreCandidate(
 }
 
 /**
- * Load a doc module's `docs`/`doc` export, swallowing errors.
+ * A component or hook doc, compiled, or null when it cannot be read.
  * @param {string} docPath
  * @param {string} [exportName]
+ * @param {'components' | 'hooks'} [root]
  * @returns {Promise<any>}
  */
-async function loadModuleDoc(docPath, exportName = 'docs') {
+async function loadModuleDoc(
+  docPath,
+  exportName = 'docs',
+  root = 'components',
+) {
   try {
-    const mod = await import(pathToFileURL(docPath).href);
     // Support both the stamped default export and the legacy named export.
-    return mod?.default ?? mod[exportName] ?? null;
+    return (
+      (await readDocView(docPath, {
+        root,
+        loader: 'native',
+        exports: ['default', exportName],
+      })) ?? null
+    );
   } catch {
     return null;
   }
@@ -637,7 +762,8 @@ async function gatherIntegrationComponents(cwd) {
   /** @type {Candidate[]} */
   const candidates = [];
   for (const integration of loadedIntegrations) {
-    for (const rec of discoverIntegrationComponents(integration)) {
+    const {components} = await discoverValidIntegrationComponents(integration);
+    for (const rec of components) {
       const doc = await loadModuleDoc(rec.docPath);
       candidates.push({
         domain: 'component',
@@ -701,7 +827,7 @@ async function gatherHooks(coreDir) {
     let description = '';
     let importPath = '@astryxdesign/core/hooks';
     if (docPath) {
-      const doc = await loadModuleDoc(docPath);
+      const doc = await loadModuleDoc(docPath, 'docs', 'hooks');
       if (doc) {
         keywords = Array.isArray(doc.keywords) ? doc.keywords : [];
         description = doc.usage?.description || doc.description || '';
@@ -720,7 +846,11 @@ async function gatherHooks(coreDir) {
 }
 
 /**
- * Build doc-topic candidates: topic name + description + section prose.
+ * Build doc candidates at the grain a reader reads them: each section of a
+ * topic, whose command reads just that section; each topic as a whole, whose
+ * command lists its sections; and each docs-tree node by its route. The tree's
+ * guides split into sections like topics, and its typed docs also match by
+ * their own name, so `assertResponse` finds `cli/api/functions/assert-response`.
  *
  * Reads the project's catalog rather than the CLI's own docs directory, so a
  * topic an integration contributed (or replaced) is searchable exactly like a
@@ -732,44 +862,274 @@ async function gatherHooks(coreDir) {
 async function gatherDocs(cwd) {
   /** @type {Candidate[]} */
   const candidates = [];
-  let entries;
+  let catalog;
   try {
-    entries = (await loadDocsCatalog(cwd)).entries();
+    catalog = await loadDocsCatalog(cwd);
   } catch {
     return candidates;
   }
-  for (const entry of entries) {
-    let doc = null;
+  let tree = null;
+  try {
+    tree = await projectTree(catalog);
+  } catch {
+    // `astryx doctor` reports a tree that fails to build; search still
+    // indexes the topics.
+  }
+  for (const entry of catalog.entries()) {
+    // A topic whose name opens another doc (spec:AST-046 FR11) is not
+    // offered: every hit's command must open the hit.
+    if (tree && !holdsOwnName(tree, catalog, entry)) continue;
+    let lowered = null;
     try {
-      doc = await loadTopicDoc(entry);
+      lowered = await lowerTopic(catalog, entry);
     } catch {
       // A topic that cannot be loaded is reported by the commands that own
       // integration issues; search just cannot index it.
     }
-    let description = '';
-    /** @type {string[]} */
-    const prose = [];
-    if (doc) {
-      description = doc.description || '';
-      for (const section of doc.sections || []) {
-        if (section.title) prose.push(section.title);
-        for (const block of section.content || []) {
-          if (block.type === 'prose' && block.text) prose.push(block.text);
-        }
+    const doc = lowered?.doc ?? null;
+    // A flat topic lives in the Unorganized level; its hits say so, and name
+    // the package each section came from.
+    const home = tree?.get(entry.name);
+    const placed = home?.ref?.flatTopic === entry.name ? home : null;
+    /** @type {Map<string, string>} */
+    const packages = new Map([
+      [entry.providerId ?? entry.package, entry.package],
+      ...entry.extensions.map(
+        ext => /** @type {[string, string]} */ ([ext.providerId ?? ext.package, ext.package]),
+      ),
+    ]);
+    candidates.push(
+      ...topicCandidates(
+        entry.name,
+        doc,
+        entry.title,
+        '',
+        placed && tree
+          ? [
+              ...tree.ancestors(placed).map(a => a.title),
+              doc?.title || entry.title || entry.name,
+            ].join(' › ')
+          : undefined,
+        placed ? `astryx docs ${placed.parent}` : undefined,
+        entry.package,
+        key =>
+          packages.get(lowered?.sectionProviders?.[key] ?? '') ?? entry.package,
+      ),
+    );
+  }
+  if (tree == null) return candidates;
+  for (const node of tree.nodes.values()) {
+    // A flat topic is indexed above, as a topic.
+    if (node.ref?.flatTopic) continue;
+    // A tree hit names where it lives: its ancestors' titles, then its own.
+    const path = [...tree.ancestors(node).map(a => a.title), node.title];
+    if (node.kind === 'generic') {
+      let doc = null;
+      try {
+        doc = (await lowerTopic(catalog, guideEntry(node))).doc;
+      } catch {
+        // As above: the owning commands report it.
       }
+      candidates.push(
+        ...topicCandidates(
+          node.route,
+          doc,
+          node.title,
+          node.summary,
+          path.join(' › '),
+          node.parent == null ? undefined : `astryx docs ${node.parent}`,
+          node.provider,
+        ),
+      );
+      continue;
+    }
+    const selfDoc = /** @type {any} */ (node.ref)?.selfDoc;
+    // A typed doc's content is what `astryx docs <route>` prints. The first
+    // column of its tables names what the doc defines (an error code, an
+    // option, a parameter), so each is a keyword the doc answers to.
+    /** @type {any[]} */
+    const content = (await nodeView(catalog, tree, node)).content ?? [];
+    /** @type {string[]} */
+    const defined = [];
+    for (const block of content) {
+      if (block.type !== 'table' || !Array.isArray(block.rows)) continue;
+      for (const row of block.rows)
+        if (row[0] != null) defined.push(plain(row[0]));
     }
     candidates.push({
       domain: 'doc',
-      name: entry.name,
-      keywords: [],
-      description,
-      prose,
-      _title: doc?.title || entry.title || entry.name,
+      name: node.name,
+      keywords: [
+        node.route.slice(node.route.lastIndexOf('/') + 1),
+        ...(Array.isArray(selfDoc?.keywords) ? selfDoc.keywords : []),
+        ...defined,
+        ...codeTerms({content}),
+      ],
+      description: node.summary || '',
+      prose: sectionProse({title: node.title, content}),
+      _topic: node.route,
+      _title: path.join(' › '),
+      _command: `astryx docs ${node.route}`,
+      _parent: node.parent == null ? 'astryx docs' : `astryx docs ${node.parent}`,
+      _package: node.provider,
     });
   }
   return candidates;
 }
 
+/**
+ * The words one section says: its prose, headings, and list items.
+ * @param {any} section
+ * @returns {string[]}
+ */
+function sectionProse(section) {
+  /** @type {string[]} */
+  const prose = [];
+  if (section?.title) prose.push(section.title);
+  for (const block of section?.content || []) {
+    if ((block.type === 'prose' || block.type === 'heading') && block.text) {
+      prose.push(block.text);
+    } else if (block.type === 'list' && Array.isArray(block.items)) {
+      for (const item of block.items) {
+        const text = typeof item === 'string' ? item : item?.text;
+        if (typeof text === 'string') prose.push(text);
+      }
+    } else if (block.type === 'table' && Array.isArray(block.rows)) {
+      for (const row of block.rows) prose.push(row.map(plain).join(' '));
+    } else if (block.type === 'code' && typeof block.code === 'string') {
+      prose.push([block.label, block.code].filter(Boolean).join(' '));
+    }
+  }
+  return prose;
+}
+
+/**
+ * The identifiers a doc part names in code ticks (`token-ref`,
+ * `ERR_UNKNOWN_SECTION`). Each is a keyword: a reader who types one exactly
+ * wants the part that defines or explains it.
+ * @param {any} part - a section, or `{content}` of a typed doc
+ * @returns {string[]}
+ */
+function codeTerms(part) {
+  /** @type {Set<string>} */
+  const terms = new Set();
+  /** @param {unknown} text */
+  const scan = text => {
+    for (const m of String(text ?? '').matchAll(/`([^`\s]{2,40})`/g)) {
+      terms.add(m[1]);
+    }
+  };
+  for (const block of part?.content || []) {
+    if (block.type === 'prose') scan(block.text);
+    else if (block.type === 'list' && Array.isArray(block.items)) {
+      for (const item of block.items) {
+        scan(typeof item === 'string' ? item : item?.text);
+      }
+    } else if (block.type === 'table' && Array.isArray(block.rows)) {
+      for (const row of block.rows) for (const cell of row) scan(cell);
+    }
+  }
+  return [...terms];
+}
+
+/**
+ * The headings inside a section. Each names a subsection, so a query that
+ * names one should find the section as surely as one that names its title.
+ * @param {any} section
+ * @returns {string[]}
+ */
+function headings(section) {
+  return (section?.content || [])
+    .filter(
+      (/** @type {any} */ block) => block.type === 'heading' && block.text,
+    )
+    .map((/** @type {any} */ block) => String(block.text));
+}
+
+/**
+ * A table cell as plain words, without its code ticks.
+ * @param {unknown} cell
+ * @returns {string}
+ */
+function plain(cell) {
+  return unlinkText(String(cell ?? '')).replaceAll('`', '');
+}
+
+/**
+ * The candidates one topic yields: the topic itself, and one per section when
+ * it has more than one. A topic's command lists its sections, and a section's
+ * command reads only that section, so a hit never costs a whole-topic read.
+ * @param {string} name - the topic name, or a placed guide's route
+ * @param {any} doc - the lowered topic, or null when it did not load
+ * @param {string} [title]
+ * @param {string} [summary]
+ * @param {string} [path] - where the topic lives in the docs tree, as titles
+ *   joined by ` › `; a flat topic is its own title
+ * @param {string} [parent] - the command that opens the level above the
+ *   topic: its namespace, or the Unorganized level for a flat topic
+ * @param {string} [pkg] - the npm package that authored the topic
+ * @param {(key: string) => string} [sectionPackage] - the npm package a
+ *   section came from: an extension's section names the extension's package
+ * @returns {Candidate[]}
+ */
+function topicCandidates(
+  name,
+  doc,
+  title,
+  summary = '',
+  path,
+  parent,
+  pkg,
+  sectionPackage,
+) {
+  /** @type {any[]} */
+  const sections = doc?.sections ?? [];
+  const docTitle = path || doc?.title || title || name;
+  const split = sections.length > 1;
+  /** @type {Candidate[]} */
+  const out = [
+    {
+      domain: 'doc',
+      name,
+      keywords: [
+        ...(doc?.title || title ? [doc?.title || title] : []),
+        ...(Array.isArray(doc?.keywords) ? doc.keywords : []),
+      ],
+      description: doc?.description || summary,
+      prose: split
+        ? sections.map(section => section.title).filter(Boolean)
+        : sections.flatMap(sectionProse),
+      _topic: name,
+      _title: docTitle,
+      _command: split ? `astryx docs ${name} --index` : `astryx docs ${name}`,
+      ...(parent ? {_parent: parent} : {}),
+      ...(pkg ? {_package: pkg} : {}),
+    },
+  ];
+  if (!split) return out;
+  for (const section of sections) {
+    const key = sectionKey(section);
+    out.push({
+      domain: 'doc',
+      name: key,
+      keywords: [
+        ...(section.title ? [section.title] : []),
+        ...headings(section),
+        ...codeTerms(section),
+      ],
+      description: sectionSummary(section),
+      prose: sectionProse(section),
+      _topic: name,
+      _section: key,
+      _title: `${docTitle} › ${section.title}`,
+      _command: `astryx docs ${name} ${key}`,
+      _parent: `astryx docs ${name} --index`,
+      ...((sectionPackage?.(key) ?? pkg) ? {_package: sectionPackage?.(key) ?? pkg} : {}),
+    });
+  }
+  return out;
+}
+
 /**
  * Build template candidates (page + block) from the template discovery API.
  * @param {string} cwd
@@ -783,6 +1143,13 @@ async function gatherTemplates(cwd) {
     return [];
   }
   return templates.map(t => {
+    // A replacement's target is its canonical unqualified lookup id. Keep the
+    // integration-owned id as a keyword and response label, but score and print
+    // commands against the id that `template()` resolves back to this entry.
+    // This matters for replacement chains: one replacement's own id can be the
+    // target of another, so using that shadowed id as the command would select
+    // the other template.
+    const commandName = t.replaces ?? t.dirName;
     // Blocks ship an authored componentsUsed; page templates don't, so derive
     // them from the source. Category words (e.g. "Dashboard - Analytics") are
     // strong intent signal for pages, which otherwise only index on name +
@@ -795,6 +1162,7 @@ async function gatherTemplates(cwd) {
     const keywords = Array.isArray(t.componentsUsed)
       ? [...t.componentsUsed]
       : [];
+    keywords.push(...templateLookupIds(t).filter(id => id !== commandName));
     /** @type {string[]} */
     let weakKeywords = [];
     if (t.type === 'page') {
@@ -810,12 +1178,14 @@ async function gatherTemplates(cwd) {
     }
     return {
       domain: 'template',
-      name: t.dirName,
+      name: commandName,
       keywords,
       weakKeywords,
       description: t.description || '',
       _displayName: t.name,
       _kind: t.type, // 'page' | 'block'
+      _resultName: t.dirName,
+      _commandName: commandName,
     };
   });
 }
@@ -834,7 +1204,7 @@ async function gatherTemplates(cwd) {
 function toResult(c, score, reason, matchedTerms, queryTerms) {
   const base = {
     domain: c.domain,
-    name: c.name,
+    name: c._resultName ?? c.name,
     score,
     reason,
     description: c.description || '',
@@ -856,10 +1226,16 @@ function toResult(c, score, reason, matchedTerms, queryTerms) {
       };
       break;
     case 'doc':
+      // A doc result names its topic or route, plus the section when the
+      // hit is one section; its command reads exactly that part.
       result = {
         ...base,
+        name: c._topic ?? c.name,
+        ...(c._section ? {section: c._section} : {}),
         title: c._title,
-        command: `astryx docs ${c.name}`,
+        command: c._command ?? `astryx docs ${c.name}`,
+        ...(c._parent ? {parent: c._parent} : {}),
+        ...(c._package ? {package: c._package} : {}),
       };
       break;
     case 'template':
@@ -867,7 +1243,7 @@ function toResult(c, score, reason, matchedTerms, queryTerms) {
         ...base,
         displayName: c._displayName,
         kind: c._kind,
-        command: `astryx template ${c.name}`,
+        command: `astryx template ${c._commandName ?? c.name} --type ${c._kind}`,
       };
       break;
     default:
@@ -884,7 +1260,7 @@ function toResult(c, score, reason, matchedTerms, queryTerms) {
  * @param {string} [options.cwd]
  * @param {'component'|'hook'|'doc'|'template'} [options.type] - Restrict to one domain.
  * @param {number} [options.limit] - Max results (default 20).
- * @returns {Promise<{type: 'search', data: {query: string, matchCount: number, results: Array<object>}}>}
+ * @returns {Promise<import('./search.type.mjs').SearchResponse>}
  */
 export async function search(query, options = {}) {
   const {cwd = process.cwd(), type, limit = 20} = options;
@@ -919,17 +1295,26 @@ export async function search(query, options = {}) {
   const term = String(query).trim().toLowerCase();
   const tokens = tokenizeQuery(term);
 
-  const coreDir = findCoreDir(cwd);
-  if (!coreDir) {
-    throw new AstryxError('Could not find @astryxdesign/core package');
+  // `astryx docs` reads docs without @astryxdesign/core, so a docs-only
+  // search must too. Every other domain reads core.
+  const docsOnly = type === 'doc';
+  const coreDir = docsOnly ? null : findCoreDir(cwd);
+  if (!docsOnly && !coreDir) {
+    throw new AstryxError(
+      'Could not find @astryxdesign/core package',
+      undefined,
+      ERROR_CODES.ERR_CORE_NOT_FOUND,
+    );
   }
 
   // Gather candidates from each requested domain in parallel.
   /** @param {string} d */
   const wants = d => !type || type === d;
   const [components, hooks, docTopics, templates] = await Promise.all([
-    wants('component') ? gatherComponents(coreDir, cwd) : [],
-    wants('hook') ? gatherHooks(coreDir) : [],
+    wants('component')
+      ? gatherComponents(/** @type {string} */ (coreDir), cwd)
+      : [],
+    wants('hook') ? gatherHooks(/** @type {string} */ (coreDir)) : [],
     wants('doc') ? gatherDocs(cwd) : [],
     wants('template') ? gatherTemplates(cwd) : [],
   ]);
@@ -971,7 +1356,10 @@ export async function search(query, options = {}) {
     data: {
       query: String(query).trim(),
       matchCount: scored.length,
-      results: limited,
+      // toResult gives every domain its command and domain fields.
+      results: /** @type {import('./search.type.mjs').SearchResultEntry[]} */ (
+        limited
+      ),
     },
   };
 }