@astryxdesign/cli 0.6.3 → 0.6.4-canary.0e1fbdb

package/api/search/search.mjs

@@ -17,21 +17,43 @@
  * 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".
+ *
+ * A multi-word query has a reserved top tier (see {@link scoreQuery}): the
+ * whole query as a candidate's name or keyword (190-200), then the whole query
+ * as a phrase inside a doc's title or one of its headings (170), then a whole
+ * title of two words or more inside the query (160-169), then a candidate that
+ * matches every word of the query, at least one of them by name or keyword
+ * (151-159). Below those sits everything else: a partial match, or every word
+ * matched only in prose or through the components a page renders. A section titled "Light/Dark Mode" answers `dark
+ * mode` better than any doc that merely names `mode` in code, however exactly;
+ * "Dark mode" answers `how do I add dark mode`; and a guide whose title and
+ * description hold both words of `troubleshoot integration` answers it better
+ * than a doc named `integration`.
+ *
  * 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 +72,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 +88,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';
@@ -82,19 +117,33 @@ import {setResultCoverage} from './coverage.mjs';
  * @property {string} [description]
  * @property {string[]} [prose]
  * @property {string[]} [guidance]
+ * @property {string[]} [titles] - A doc's title and the headings inside it:
+ *   the lines a reader scans to pick it. The whole query standing in one of
+ *   them, or one of them standing whole in the query, is a top-tier match.
  * @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 +215,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 +410,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)
@@ -303,6 +429,120 @@ function bestForToken(tok, candidate) {
   return best;
 }
 
+/**
+ * The score of a whole-query phrase inside a doc's title or heading: a keyword
+ * substring hit (70) promoted by the same 100 as the exact tier. Below an
+ * exact name or keyword (190-200), above the token-sum path (~151 at most).
+ */
+const TITLE_PHRASE_SCORE = 170;
+
+/**
+ * The score of a whole title inside a longer query, before its coverage bonus:
+ * one step below {@link TITLE_PHRASE_SCORE}. The bonus (one per query term the
+ * candidate matches, at most 9) orders the sections that share a common title,
+ * so "best practices for spacing" puts Spacing's Best Practices first.
+ */
+const TITLE_IN_QUERY_SCORE = 160;
+
+/**
+ * The score of a candidate that matches every content word of a multi-word
+ * query, before a bonus of up to 8 for how strong its strongest match is: just
+ * above anything that matches only some of the words. The token-sum path tops
+ * out near 150 for a partial match (a 100 on one word, the per-word bonus, and
+ * the coverage term), so an AND-match with one keyword-strength hit (see
+ * {@link STRONG_TOKEN_SCORE}) always outranks an OR-match, and stays below the
+ * title tiers.
+ */
+const FULL_COVERAGE_SCORE = 151;
+
+/**
+ * The strongest single-word hit an every-word match needs to take that tier: a
+ * keyword substring. Two passing mentions in prose, or the components a page
+ * happens to render, are breadth, not relevance; they stay on the token sum,
+ * below an exact name or keyword hit on one of the words.
+ */
+const STRONG_TOKEN_SCORE = 70;
+
+/**
+ * The words of a title or query, lowercased, without punctuation or code ticks.
+ * @param {string} text
+ * @returns {string[]}
+ */
+function phraseWords(text) {
+  return unlinkText(text).toLowerCase().match(/[a-z0-9]+/g) ?? [];
+}
+
+/**
+ * Whether two words are the same word, allowing a plural on either side, so
+ * `data attributes selector` still reads "Data attribute selectors".
+ * @param {string} a
+ * @param {string} b
+ */
+function samePhraseWord(a, b) {
+  return (
+    a === b ||
+    `${a}s` === b ||
+    `${b}s` === a ||
+    `${a}es` === b ||
+    `${b}es` === a
+  );
+}
+
+/**
+ * Whether `plural` is the plural of `word`: `integrations` of `integration`,
+ * `boxes` of `box`. `es` only follows s, x, z, ch, or sh, so `notes` is not a
+ * plural of `not`.
+ * @param {string} plural
+ * @param {string} word
+ */
+function pluralOf(plural, word) {
+  if (word.length < 3) return false;
+  if (plural === `${word}s`) return true;
+  return /(?:s|x|z|ch|sh)$/.test(word) && plural === `${word}es`;
+}
+
+/**
+ * The first title or heading that holds every word of the query, in order and
+ * side by side, or null.
+ * @param {string} term - Lowercased full query.
+ * @param {string[] | undefined} titles
+ * @returns {string | null}
+ */
+export function headingWithPhrase(term, titles) {
+  const query = phraseWords(term);
+  if (query.length < 2 || !titles) return null;
+  for (const title of titles) {
+    const words = phraseWords(String(title ?? ''));
+    for (let i = 0; i + query.length <= words.length; i++) {
+      if (query.every((word, j) => samePhraseWord(words[i + j], word)))
+        return title;
+    }
+  }
+  return null;
+}
+
+/**
+ * The first title or heading of two words or more that the query holds whole,
+ * in order and side by side, or null. A question such as "how do I add dark
+ * mode" names the "Dark mode" section outright, around words no title has.
+ * @param {string} term - Lowercased full query.
+ * @param {string[] | undefined} titles
+ * @returns {string | null}
+ */
+export function titleInQuery(term, titles) {
+  const query = phraseWords(term);
+  if (!titles) return null;
+  for (const title of titles) {
+    const words = phraseWords(String(title ?? ''));
+    if (words.length < 2 || words.length > query.length) continue;
+    for (let i = 0; i + words.length <= query.length; i++) {
+      if (words.every((word, j) => samePhraseWord(query[i + j], word)))
+        return title;
+    }
+  }
+  return null;
+}
+
 /**
  * @param {string} term - Lowercased full query.
  * @param {string[]} tokens - Content tokens from tokenizeQuery(term).
@@ -322,17 +562,26 @@ 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});
+  // A query of several words keeps its phrase tiers below even when stopwords
+  // leave one content word: "make an integration" is still the phrase an
+  // author declares as a keyword, and "build an integration" still names a
+  // title outright, though each tokenizes to `integration` alone.
+  const phrase = phraseWords(term).length >= 2;
 
-  // 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) {
+  /** 0–1 content tokens: 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. */
+  const fewTokens = () => {
     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;
-  }
+  };
+  if (tokens.length <= 1 && !phrase) return fewTokens();
 
   // The full (untokenized) query matching a candidate's name or a declared
   // keyword VERBATIM — full.score 90 or 100, the only two scoreCandidate
@@ -349,6 +598,22 @@ export function scoreQuery(term, tokens, candidate) {
     return asFull({score: full.score + 100, reason: full.reason});
   }
 
+  // The whole query standing as a phrase in a doc's title or one of its
+  // headings is the next tier down, and still above the token-sum path. The
+  // reader named what the section is about, in order: `dark mode` is the
+  // "Light/Dark Mode" section. Without this, the title scores a keyword
+  // substring (70) and loses to a doc that happens to name `mode` exactly in
+  // a code tick (90 on one token, 98 with coverage), so API enum docs outrank
+  // the guide section.
+  const heading = headingWithPhrase(term, candidate.titles);
+  if (heading != null) {
+    return asFull({
+      score: TITLE_PHRASE_SCORE,
+      reason: `title "${heading}" holds the whole query`,
+    });
+  }
+  if (tokens.length <= 1) return fewTokens();
+
   // Multi-word natural language: score each content token, counting only
   // strong hits, then reward coverage so candidates matching more terms win.
   let strongest = 0;
@@ -356,15 +621,49 @@ 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++;
       hitTerms.push(tok);
     }
   }
+  // The reverse of the title tier, a step lower: the query holds a whole title
+  // of two words or more, so the reader asked a question around the section's
+  // name ("how do I add dark mode"). Coverage breaks ties between sections
+  // that share a title such as "Best Practices".
+  const named = titleInQuery(term, candidate.titles);
+  if (named != null) {
+    return {
+      score: TITLE_IN_QUERY_SCORE + Math.min(matched, 9),
+      reason: `the query names the title "${named}"`,
+      matched,
+      total,
+    };
+  }
   if (matched === 0) return full ? asFull(full) : null;
 
+  const reason = `matches ${matched}/${tokens.length} terms: ${hitTerms.join(', ')}`;
+
+  // Every word matched is its own tier. Summed per word, a doc that matches
+  // both words of `troubleshoot integration` in its title and description
+  // (50 + bonus + coverage = 77) lost to thirty docs that each match
+  // `integration` alone, by name or in a code tick (98-108). The reader asked for
+  // both; a candidate that has both comes first, ordered among its peers by
+  // how strong its strongest match is. It needs one keyword-strength hit:
+  // every word mentioned in prose, or rendered by a page, is breadth, and
+  // stays on the token sum below an exact hit on one word.
+  if (matched === tokens.length && strongest >= STRONG_TOKEN_SCORE) {
+    return {
+      score:
+        FULL_COVERAGE_SCORE +
+        Math.floor((strongest - MIN_TOKEN_SCORE) / 6.25),
+      reason,
+      matched,
+      total,
+    };
+  }
+
   // Base the score on the STRONGEST concept that matched, plus a bonus per
   // additional matched concept and a coverage term.
   //
@@ -386,14 +685,8 @@ export function scoreQuery(term, tokens, candidate) {
   const tokenScore = Math.round(
     strongest + Math.min(matched - 1, 3) * 12 + coverage * 15,
   );
-
   if (full && full.score >= tokenScore) return asFull(full);
-  return {
-    score: tokenScore,
-    reason: `matches ${matched}/${tokens.length} terms: ${hitTerms.join(', ')}`,
-    matched,
-    total,
-  };
+  return {score: tokenScore, reason, matched, total};
 }
 
 /**
@@ -404,23 +697,28 @@ export function scoreQuery(term, tokens, candidate) {
  * @param {string} term - Lowercased search term.
  * @param {object} candidate
  * @param {string} candidate.name - Primary identifier (component/hook name, topic, template name).
+ * @param {string} [candidate.domain] - A component, hook, or template name
+ *   also matches typed as words: `command palette` is CommandPalette.
  * @param {string[]} [candidate.keywords] - Authored intent (componentsUsed, category words).
  * @param {string[]} [candidate.weakKeywords] - Derived signal (components a page renders).
  * @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(
   term,
   {
     name,
+    domain,
     keywords = [],
     weakKeywords = [],
     description = '',
     prose = [],
     guidance = [],
   },
+  {fuzzy = true} = {},
 ) {
   let best = 0;
   let reason = '';
@@ -436,25 +734,41 @@ export function scoreCandidate(
   };
 
   const nameLower = name.toLowerCase();
+  // A placed guide's name is its route, and the route's last segment is its
+  // name too, as a flat topic's is: `codemods` is cli/integrations/codemods.
+  const leafLower = nameLower.slice(nameLower.lastIndexOf('/') + 1);
 
   // ── Name signals ────────────────────────────────────────────────
-  if (nameLower === term) {
+  // A plural of the name is the name: `integration` is the `integrations`
+  // guides, `tab` the `tabs` doc.
+  // A component, hook, or template name typed as words is its name:
+  // `command palette` is CommandPalette. A doc's name is a route or key,
+  // matched as written.
+  const spelled =
+    domain !== 'doc' &&
+    !/[\s_-]/.test(nameLower) &&
+    nameLower === term.replace(/\s+/g, '');
+  if (nameLower === term || leafLower === term || spelled) {
     consider(100, 'exact name');
+  } else if (pluralOf(nameLower, term) || pluralOf(term, nameLower)) {
+    // One point under the exact spelling, so the doc named `tokens` still
+    // outranks the Token component for `tokens`.
+    consider(99, 'plural of the 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 +778,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 +798,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 +841,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 +960,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 +1025,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 +1044,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 +1060,287 @@ 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 : []),
+        // A namespace doc's own keywords, which it declares for search.
+        ...(Array.isArray(node.keywords) ? node.keywords : []),
+        ...defined,
+        ...codeTerms({content}),
+      ],
+      description: node.summary || '',
+      prose: sectionProse({title: node.title, content}),
+      titles: [node.title],
+      _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;
+  // A placed guide also answers to its last route segment's words:
+  // `quick start` is cli/integrations/quick-start.
+  const leaf = name.slice(name.lastIndexOf('/') + 1);
+  /** @type {Candidate[]} */
+  const out = [
+    {
+      domain: 'doc',
+      name,
+      keywords: [
+        ...(leaf !== name ? [leaf.replaceAll('-', ' ')] : []),
+        ...(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),
+      titles: [
+        doc?.title || title || name,
+        // A topic read whole answers for the headings inside it.
+        ...(split ? [] : sections.flatMap(s => [s.title, ...headings(s)])),
+      ].filter(Boolean),
+      _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),
+      titles: [section.title, ...headings(section)].filter(Boolean),
+      _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 +1354,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 +1373,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 +1389,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 +1415,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 +1437,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 +1454,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 +1471,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 +1506,27 @@ 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: asked for by name, it is
+  // an error without core; an open search then covers the docs alone.
+  const docsOnly = type === 'doc';
+  const coreDir = docsOnly ? null : findCoreDir(cwd);
+  if (type && !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 wants = d => (!type && (coreDir != null || d === 'doc')) || 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 +1568,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
+      ),
     },
   };
 }