@niroai/niro 0.17.0 → 0.18.0

package/src/lib/guide.js

@@ -0,0 +1,293 @@
+/**
+ * The documentation pages that ship in the package (docs/*.md and docs/llms.txt), read for `niro guide`.
+ *
+ * Nothing here names a page. The pages are whatever is in the folder when the command runs, grouped the
+ * way docs/index.md groups them (its "## All pages" section), each with the one line docs/llms.txt gives
+ * it. That way a page added, renamed or rewritten needs no code change (Niraj, 2026-11-10: "6 yes").
+ *
+ * Every shipped .md page is listed, matched and searched. A page index.md does not group goes under
+ * "Other pages", so a new page is never silently missing. Only the written rule below (HIDDEN_PAGES)
+ * hides one, and a hidden page still opens by its exact name. The search is in src/lib/guideSearch.js.
+ */
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const DOCS_DIR = path.join(__dirname, "..", "..", "docs");
+const START_PAGE = "index";
+const OTHER_GROUP = "Other pages";
+
+/**
+ * Pages kept out of the list, the search and the agent index (scripts/gen-llms-full.js reads this too):
+ * cloud-README.md is an archive describing hosted Niro, not this package, so answering from it would
+ * describe the other product. A page is hidden only by being named here, with its reason.
+ */
+const HIDDEN_PAGES = new Set(["cloud-README.md"]);
+
+/** A page's name, as typed after `niro guide`: the file name without `.md`. A .txt file keeps its suffix. */
+function pageName(file) {
+  return file.endsWith(".md") ? file.slice(0, -3) : file;
+}
+
+/** The pages `[text](page.md)` links name in `text`, in order, each once. Web links are not pages. */
+function linkedPages(text) {
+  const seen = [];
+  for (const m of text.matchAll(/\]\(([^)\s#]+\.md)(?:#[^)\s]*)?\)/g)) {
+    if (/^[a-z]+:/i.test(m[1])) continue;
+    const name = pageName(path.basename(m[1]));
+    if (!seen.includes(name)) seen.push(name);
+  }
+  return seen;
+}
+
+/**
+ * A line of the "All pages" section that starts a group, or null. Any of the shapes an index writer uses:
+ * `**Reference:**`, `**Tasks** (one page per job):`, `**Tasks:** start here`, `### Tasks`, `Tasks:`.
+ * A list item or a line with a page link never starts one.
+ */
+function groupHeading(line) {
+  const t = line.trim();
+  if (!t || /^([-*+]|\d+[.)])\s/.test(t) || t.startsWith("|") || t.startsWith("<!--") || linkedPages(t).length) return null;
+  let name = null;
+  if (/^#{3,6}\s/.test(t)) name = t.replace(/^#+\s*/, "").replace(/\s*#*$/, "");
+  else if (/^\*\*[^*]+\*\*/.test(t)) name = t.match(/^\*\*([^*]+)\*\*/)[1];
+  else if (/:$/.test(t)) name = t;
+  if (name === null) return null;
+  name = name.replace(/\*\*/g, "").replace(/\s*\([^)]*\)\s*:?$/, "").replace(/[\s:]+$/, "").trim();
+  return name || null;
+}
+
+/**
+ * Groups from index.md. In its "## All pages" section a group heading (groupHeading) starts a group and
+ * every page linked below it, nested bullets included, belongs to it. Without that section, every page
+ * index.md links goes in one group, so a rewritten index still lists its pages.
+ */
+function indexGroups(indexText) {
+  const lines = indexText.split("\n");
+  const start = lines.findIndex((l) => /^##\s+all pages\s*$/i.test(l.trim()));
+  if (start === -1) {
+    const pages = linkedPages(indexText);
+    return pages.length ? [{ name: "Pages", pages }] : [];
+  }
+  const groups = [];
+  let current = null;
+  for (const line of lines.slice(start + 1)) {
+    if (/^##\s/.test(line)) break;
+    const heading = groupHeading(line);
+    if (heading) {
+      current = { name: heading, pages: [] };
+      groups.push(current);
+      continue;
+    }
+    const pages = linkedPages(line);
+    if (!pages.length) continue;
+    if (!current) {
+      current = { name: "Pages", pages: [] };
+      groups.push(current);
+    }
+    for (const p of pages) if (!current.pages.includes(p)) current.pages.push(p);
+  }
+  return groups;
+}
+
+/** One-line descriptions from llms.txt: `- [page.md](page.md): what it holds`. */
+function summaries(llmsText) {
+  const out = new Map();
+  for (const m of llmsText.matchAll(/^\s*-\s*\[[^\]]*\]\(([^)\s#]+\.md)\)\s*:\s*(.+)$/gm)) {
+    const name = pageName(path.basename(m[1]));
+    if (!out.has(name)) out.set(name, m[2].trim());
+  }
+  return out;
+}
+
+/** A page's title: its first `# ` line, without backticks. */
+function titleOf(text, fallback) {
+  const m = text.match(/^#\s+(.+)$/m);
+  return m ? m[1].replace(/`/g, "").trim() : fallback;
+}
+
+/** A page's text, or the reason it cannot be read (a folder named x.md, a link to nothing). */
+function readPage(file) {
+  try {
+    return { text: fs.readFileSync(file, "utf8"), error: null };
+  } catch (err) {
+    return { text: "", error: err.code || err.message };
+  }
+}
+
+/**
+ * Everything `niro guide` needs about the folder, read now.
+ * Returns { start, groups: [{name, pages: [name]}], pages: Map(name -> {page, file, title, summary, text, unreadable, listed}) }.
+ */
+function load(docsDir = DOCS_DIR) {
+  let files;
+  try {
+    files = fs.readdirSync(docsDir).filter((f) => f.endsWith(".md") || f.endsWith(".txt")).sort();
+  } catch (err) {
+    throw new Error(`The documentation pages are not where they should be (${docsDir}): ${err.code || err.message}. Reinstall niro with npm install -g @niroai/niro.`);
+  }
+  const pages = new Map();
+  for (const file of files) {
+    const read = readPage(path.join(docsDir, file));
+    const name = pageName(file);
+    pages.set(name, { page: name, file, title: titleOf(read.text, name), summary: "", text: read.text, unreadable: read.error, listed: false });
+  }
+  const groups = indexGroups(pages.has(START_PAGE) ? pages.get(START_PAGE).text : "")
+    .map((g) => ({ name: g.name, pages: g.pages.filter((p) => pages.has(p) && !HIDDEN_PAGES.has(pages.get(p).file)) }))
+    .filter((g) => g.pages.length);
+  const llms = pages.has("llms.txt") ? pages.get("llms.txt").text : "";
+  const described = summaries(llms);
+  const inGroups = new Set(groups.flatMap((g) => g.pages));
+  // Every other .md page, so a page the indexes do not name yet still lists and searches.
+  const other = [...pages.values()]
+    .filter((p) => p.file.endsWith(".md") && !inGroups.has(p.page) && !HIDDEN_PAGES.has(p.file) && !p.unreadable)
+    .map((p) => p.page);
+  if (other.length) groups.push({ name: OTHER_GROUP, pages: other });
+  for (const g of groups) {
+    for (const p of g.pages) {
+      const page = pages.get(p);
+      page.listed = true;
+      page.summary = described.get(p) || page.title;
+    }
+  }
+  return { start: pages.has(START_PAGE) ? START_PAGE : null, groups, pages };
+}
+
+/**
+ * A page as plain text for a terminal. Source notes go, links name the page to run next, headings are
+ * underlined, code fences lose their markers. `style.bold` (identity by default) marks bold text.
+ */
+function render(markdown, { bold = (s) => s } = {}) {
+  let text = markdown.replace(/\r\n/g, "\n").replace(/<!--[\s\S]*?-->/g, "");
+  const sections = sectionsBySlug(text);
+  const out = [];
+  let inFence = false;
+  for (const raw of text.split("\n")) {
+    if (/^\s*(```|~~~)/.test(raw)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) {
+      out.push(`    ${raw}`);
+      continue;
+    }
+    let line = renderLinks(raw, sections);
+    const heading = line.match(/^(#{1,6})\s+(.+?)\s*#*\s*$/);
+    if (heading) {
+      const words = heading[2].replace(/\*\*/g, "");
+      if (out.length && out[out.length - 1] !== "") out.push("");
+      out.push(bold(words));
+      if (heading[1].length <= 2) out.push((heading[1].length === 1 ? "=" : "-").repeat(Math.min(words.length, 72)));
+      continue;
+    }
+    line = line.replace(/\*\*([^*]+)\*\*/g, (_m, s) => bold(s));
+    out.push(line.replace(/\s+$/, ""));
+  }
+  // Removed notes leave blank lines behind: never more than one in a row, none at either end.
+  const squeezed = [];
+  for (const l of out) if (!(l === "" && (squeezed.length === 0 || squeezed[squeezed.length - 1] === ""))) squeezed.push(l);
+  while (squeezed.length && squeezed[squeezed.length - 1] === "") squeezed.pop();
+  return squeezed.join("\n");
+}
+
+/** The id a heading gets as a link target (`## Other MCP clients` -> other-mcp-clients), as GitHub makes it. */
+function slug(heading) {
+  return heading.toLowerCase().replace(/[*`]/g, "").replace(/[^\p{L}\p{N}\s_-]/gu, "").trim().replace(/\s/g, "-");
+}
+
+/** Headings of a page by their link id, for `[x](#id)` links. */
+function sectionsBySlug(markdown) {
+  const out = new Map();
+  for (const m of markdown.matchAll(/^#{1,6}\s+(.+?)\s*#*\s*$/gm)) {
+    const text = m[1].replace(/\*\*/g, "").replace(/`/g, "");
+    if (!out.has(slug(m[1]))) out.set(slug(m[1]), text);
+  }
+  return out;
+}
+
+/**
+ * `[text](page.md)` -> `text (niro guide page)`; `[page.md](page.md)` -> `niro guide page`; web links keep their
+ * address; `[text](#part)` on the same page -> `text (see "Heading" on this page)`.
+ */
+function renderLinks(line, sections = new Map()) {
+  return line.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (whole, label, target) => {
+    if (target.startsWith("#")) {
+      const heading = sections.get(target.slice(1).toLowerCase()) || label.replace(/`/g, "");
+      return `${label} (see "${heading}" on this page)`;
+    }
+    if (/^[a-z]+:/i.test(target)) return label === target ? target : `${label} (${target})`;
+    const file = target.split("#")[0];
+    if (!/\.(md|txt)$/.test(file)) return whole;
+    const command = `niro guide ${pageName(path.basename(file))}`;
+    const plainLabel = label.replace(/`/g, "");
+    return plainLabel === path.basename(file) || plainLabel === pageName(path.basename(file)) ? command : `${label} (${command})`;
+  });
+}
+
+/** Lower case, no `*` or backticks, spaces collapsed: how a line and a query are compared. */
+function flatten(s) {
+  return s.toLowerCase().replace(/[*`]/g, "").replace(/\s+/g, " ").trim();
+}
+
+/**
+ * One word's plural made singular, so "worktrees" meets "worktree" and "addresses" meets "address". Only a
+ * word of five letters or more loses an "s", so "news" stays "news" and never meets "new"; a word ending in
+ * "ss", "us" or "is" keeps it ("address", "status", "analysis").
+ */
+function stem(w) {
+  if (w.length < 5) return w;
+  if (/(ss|sh|ch|x|z)es$/.test(w)) return w.slice(0, -2);
+  if (/ies$/.test(w)) return `${w.slice(0, -3)}y`;
+  if (/(ss|us|is)$/.test(w)) return w;
+  return w.endsWith("s") ? w.slice(0, -1) : w;
+}
+
+/** Words for matching: lower case, split on anything that is not a letter or digit, plurals made singular. */
+function words(s) {
+  return flatten(s)
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter(Boolean)
+    .map(stem);
+}
+
+/** The words worth matching: one- and two-letter words ("a", "is") are dropped, unless there is nothing else. */
+function keyWords(s) {
+  const all = [...new Set(words(s))];
+  const long = all.filter((w) => w.length > 2);
+  return long.length ? long : all;
+}
+
+function containsAll(have, want) {
+  const set = new Set(have);
+  return want.every((w) => set.has(w));
+}
+
+/**
+ * The page for `topic`. Returns { page } for one, { matches: [page...] } for several, { matches: [] } for none.
+ * Order: exact name (any file), exact title, then every topic word in the name, the title or the one line,
+ * collected from all three before choosing, so `copilot` lists both Copilot pages. A topic of one- and
+ * two-letter words only ("a", "is") opens nothing by its words.
+ */
+function find(guide, topic) {
+  const wanted = topic.trim().replace(/\.md$/i, "");
+  const lower = wanted.toLowerCase();
+  for (const [name, page] of guide.pages) if (name.toLowerCase() === lower) return { page };
+  const order = new Map(guide.groups.flatMap((g) => g.pages).map((p, i) => [p, i]));
+  const listed = [...guide.pages.values()].filter((p) => p.listed).sort((a, b) => order.get(a.page) - order.get(b.page));
+  const byTitle = listed.filter((p) => flatten(p.title) === flatten(wanted));
+  if (byTitle.length === 1) return { page: byTitle[0] };
+  if (byTitle.length > 1) return { matches: byTitle };
+  const want = keyWords(wanted);
+  if (!want.length || want.every((w) => w.length <= 2)) return { matches: [] };
+  const fields = [(p) => p.page.replace(/-/g, " "), (p) => p.title, (p) => p.summary];
+  const hits = [];
+  for (const field of fields) for (const p of listed) if (!hits.includes(p) && containsAll(words(field(p)), want)) hits.push(p);
+  if (hits.length === 1) return { page: hits[0] };
+  return { matches: hits };
+}
+
+module.exports = {
+  DOCS_DIR, OTHER_GROUP, HIDDEN_PAGES, load, render, renderLinks, find, flatten, words, keyWords, stem, containsAll,
+  indexGroups, groupHeading, summaries, linkedPages, pageName,
+};

package/src/lib/guideSearch.js

@@ -0,0 +1,252 @@
+/**
+ * `niro guide --search`: find the pages that answer what was typed, most often a pasted message.
+ *
+ * Three ways a line can answer, tried together over every listed page (src/lib/guide.js):
+ *   1. phrase:  the line holds what was typed as whole words (ignoring case, `*`, backticks and spaces), so
+ *               "it broke" is not found inside "await broker";
+ *   2. message: a message the line quotes ("...") matches a sentence of what was typed, from its start (after
+ *               an optional short `Label:`), with the page's placeholders standing for the values: `<folder>`,
+ *               `N` or `Nms` for one value without spaces, `...` and `[is not]` for any text. A pasted message
+ *               carries real values (a path, a number), which is why the phrase alone found 9 of 11 such
+ *               messages nothing (check of 01798af). Each sentence is tried on its own, at most 400 characters,
+ *               because a placeholder matching any text anywhere in a long paste took minutes (check of f1abc9f);
+ *   3. words:   no line answers either way, so pages are ranked by how many of the typed words one line holds,
+ *               with a floor: the line must hold at least 60 percent of the typed words that occur anywhere in
+ *               the pages. Paths and anything holding a digit are values: they are left out of that count, and
+ *               a quoted message's placeholders count for them. When a typed word is on no page the answer is
+ *               only "closest", and when fewer than half the typed words are on any page there is no answer,
+ *               so an error from another tool ("Segmentation fault (core dumped)") is not answered on "core".
+ * A page whose heading holds the answer (an FAQ entry quoting the message) comes first.
+ */
+"use strict";
+
+const { render, renderLinks, flatten, words, keyWords } = require("./guide");
+
+const WORD_FLOOR = 0.6;
+/**
+ * Words a question is phrased with that say nothing about what it asks: "how do I uninstall" is a search for
+ * "uninstall". They are left out of the word match (step 3) whenever another word is left, because a line rarely
+ * holds "how" beside the word that matters, so a question in plain words found nothing (Niraj, 2026-11-11:
+ * `niro guide --search "how do I uninstall"` answered "No page matches" while "uninstall" found 27 pages).
+ * "niro" is one too: every page is about Niro, so it only ever pushed a line under the floor.
+ */
+const FILLER = new Set([
+  "a", "about", "am", "an", "and", "any", "are", "be", "can", "could", "did", "do", "does", "for", "from", "have",
+  "how", "i", "if", "in", "is", "it", "me", "mean", "means", "my", "niro", "of", "on", "or", "please", "should",
+  "so", "that", "the", "there", "this", "to", "want", "was", "we", "what", "when", "where", "which", "why", "will",
+  "with", "would", "you", "your",
+]);
+/** Fewer of the typed words than this share on any page, and there is no answer at all. */
+const KNOWN_FLOOR = 0.5;
+/** The longest piece of a paste (one sentence, or as many as the message has) tried against a quoted message. */
+const SENTENCE_LIMIT = 400;
+/** An optional short label before a message: `Error:`, `niro:`, `WARNING:`. */
+const LABEL = "^(?:[^:]{1,30}:\\s*)?";
+
+/**
+ * A placeholder inside a quoted message: `<anything>`, `...`, `[optional words]`, or a lone capital letter
+ * other than A and I (the two that are English words), optionally with a unit or a "v" (`N`, `Nms`, `vX`).
+ */
+const PLACEHOLDER = /<[^<>\n]+>|\.\.\.|…|\[[^\]\n]*\]|\b(?:v)?[B-HJ-Z](?:ms|s)?\b/g;
+
+/** The messages a line quotes: text between double quotes. */
+function quoted(line) {
+  return [...line.matchAll(/"([^"\n]{3,})"/g)].map((m) => m[1]);
+}
+
+/** How many placeholders the messages a line quotes hold. */
+function placeholderCount(line) {
+  return quoted(line).reduce((n, q) => n + (q.match(PLACEHOLDER) || []).length, 0);
+}
+
+function escape(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Text split into sentences: at a line break, or after `.`, `!` or `?` and a space. */
+function sentences(text) {
+  return text.split(/\n|(?<=[.!?])\s+/).map((t) => t.trim()).filter(Boolean);
+}
+
+/**
+ * The pieces of a paste a quoted message of `count` sentences is tried against: every run of `count`
+ * sentences in a row, flattened, at most SENTENCE_LIMIT characters.
+ */
+function pieces(sentenceList, count) {
+  const out = [];
+  for (let i = 0; i + count <= sentenceList.length; i += 1) {
+    const piece = flatten(sentenceList.slice(i, i + count).join(" "));
+    if (piece.length <= SENTENCE_LIMIT) out.push(piece);
+  }
+  return out;
+}
+
+/**
+ * A quoted message as { re, sentences }: a pattern over a flattened sentence, from its start after an optional
+ * label, with `<x>` and `N` matching one value without spaces and `...` and `[x]` any text; and how many
+ * sentences the message has. Null when the message is too short to be told apart from an ordinary sentence
+ * (fewer than 2 fixed words with a placeholder, 3 without one).
+ */
+function messagePattern(message) {
+  const pieces = [];
+  let fixedWords = 0;
+  let wild = 0;
+  let last = 0;
+  const literal = (text, isLast) => {
+    let flat = flatten(text);
+    if (isLast) flat = flat.replace(/[.!?:;,]+$/, "");
+    if (!flat) return;
+    fixedWords += words(flat).length;
+    pieces.push(escape(flat).replace(/ /g, "\\s+"));
+  };
+  for (const m of message.matchAll(PLACEHOLDER)) {
+    literal(message.slice(last, m.index), false);
+    const any = m[0].startsWith("[") || m[0] === "..." || m[0] === "…";
+    pieces.push(any ? "(?:.*?)" : "\\S+");
+    wild += 1;
+    last = m.index + m[0].length;
+  }
+  literal(message.slice(last), true);
+  if (fixedWords < (wild ? 2 : 3)) return null;
+  try {
+    return { re: new RegExp(LABEL + pieces.join("\\s*"), "i"), sentences: sentences(message).length };
+  } catch {
+    return null;
+  }
+}
+
+/** A page's headings, flattened, so a search can tell a heading that quotes a message from a line that mentions it. */
+function headings(markdown) {
+  const out = new Set();
+  for (const m of markdown.matchAll(/^#{1,6}\s+(.+?)\s*#*\s*$/gm)) out.add(flatten(renderLinks(m[1])));
+  return out;
+}
+
+/** Each listed page's lines as shown, each text once, with what a search needs to know about them. */
+function pageLines(guide) {
+  return [...guide.pages.values()]
+    .filter((p) => p.listed)
+    .map((p) => {
+      const heads = headings(p.text);
+      const lines = [];
+      const seen = new Set();
+      render(p.text).split("\n").forEach((text, i) => {
+        const flat = flatten(text);
+        if (!flat || /^[=-]+$/.test(flat) || seen.has(flat)) return;
+        seen.add(flat);
+        lines.push({ n: i + 1, text: text.trim(), flat, heading: heads.has(flat), words: new Set(words(flat)) });
+      });
+      return { p, lines };
+    });
+}
+
+/**
+ * Search every listed page. Returns { match, results } where match is "phrase" (the phrase or a quoted
+ * message answered), "words" (a line holds every word), "pages" (no line, but a page holds every word across its
+ * lines), "closest" (lines, or pages, hold most of the words) or null,
+ * and results is [{ page, title, lines: [{ line, text }], total }] best first. `lines` holds at most
+ * `perPage`; `line` counts lines of the page as `niro guide <page>` shows it.
+ */
+function search(guide, query, { perPage = 3 } = {}) {
+  const phrase = flatten(query);
+  if (!phrase) return { match: null, results: [] };
+  const pages = pageLines(guide);
+  const headingFirst = (a, b) => Number(b.heading) - Number(a.heading) || a.n - b.n;
+  const result = (p, hits, best) => ({
+    page: p.page,
+    title: p.title,
+    lines: hits.slice(0, perPage).map(({ n, text }) => ({ line: n, text })),
+    total: hits.length,
+    best,
+    headed: hits.some((h) => h.heading) ? 1 : 0,
+  });
+  const done = (match, list) => ({
+    match,
+    results: list
+      .sort((a, b) => b.best - a.best || b.headed - a.headed || b.total - a.total || a.page.localeCompare(b.page))
+      .map(({ best, headed, ...r }) => r),
+  });
+
+  // 1 and 2: the phrase as whole words, or a quoted message matching a sentence of what was typed.
+  // A phrase of one or two letters is inside nearly every line, so it is not looked for as a phrase.
+  const wholePhrase = phrase.length >= 3
+    ? new RegExp(`(?<![\\p{L}\\p{N}])${escape(phrase)}(?![\\p{L}\\p{N}])`, "u")
+    : null;
+  const typed = sentences(query);
+  const piecesBy = new Map();
+  const patterns = new Map();
+  const messageHit = (line) =>
+    quoted(line.text).some((q) => {
+      if (!patterns.has(q)) patterns.set(q, messagePattern(q));
+      const pattern = patterns.get(q);
+      if (pattern === null) return false;
+      if (!piecesBy.has(pattern.sentences)) piecesBy.set(pattern.sentences, pieces(typed, pattern.sentences));
+      return piecesBy.get(pattern.sentences).some((piece) => pattern.re.test(piece));
+    });
+  const exact = [];
+  for (const { p, lines } of pages) {
+    const hits = lines.filter((l) => (wholePhrase !== null && l.flat.includes(phrase) && wholePhrase.test(l.flat)) || messageHit(l)).sort(headingFirst);
+    if (hits.length) exact.push(result(p, hits, 0));
+  }
+  if (exact.length) return done("phrase", exact);
+
+  // 3: the words. A path or anything holding a digit is a value, never a word a page could hold
+  // (`/home/dev/app` would otherwise count "home" and "app"), so it only counts towards placeholders.
+  const tokens = query.split(/\s+/).filter(Boolean);
+  const isValue = (t) => /[\/\\]|\d/.test(t);
+  const valueCount = tokens.filter(isValue).length;
+  const typedWords = keyWords(tokens.filter((t) => !isValue(t)).join(" "));
+  const meaningful = typedWords.filter((w) => !FILLER.has(w));
+  const want = meaningful.length ? meaningful : typedWords;
+  const vocabulary = new Set();
+  for (const { lines } of pages) for (const l of lines) for (const w of l.words) vocabulary.add(w);
+  const known = want.filter((w) => vocabulary.has(w) && w.length > 1);
+  const unknown = want.length - known.length;
+  const values = unknown + valueCount;
+  if (!known.length || known.length < want.length * KNOWN_FLOOR) return { match: null, results: [] };
+  const floor = Math.max(1, Math.ceil(known.length * WORD_FLOOR));
+  let every = false;
+  const found = [];
+  for (const { p, lines } of pages) {
+    const scored = [];
+    for (const l of lines) {
+      const held = known.filter((w) => l.words.has(w)).length;
+      if (held < floor) continue;
+      if (held === known.length) every = true;
+      scored.push({ ...l, score: held + Math.min(values, placeholderCount(l.text)) });
+    }
+    if (!scored.length) continue;
+    scored.sort((a, b) => b.score - a.score || headingFirst(a, b));
+    found.push(result(p, scored, scored[0].score));
+  }
+  // The words searched for, said back when filler was left out, so "how do I uninstall" reads as a search for
+  // "uninstall" rather than a claim that 27 pages hold "how".
+  const dropped = meaningful.length && meaningful.length < typedWords.length ? { searched: tokens.filter((t) => !isValue(t) && words(t).some((w) => !FILLER.has(w))).join(" ") } : {};
+  if (found.length) return { ...done(every && unknown === 0 ? "words" : "closest", found), ...dropped };
+  const paged = byPage(pages, known, floor, unknown, result, done);
+  return paged.results.length ? { ...paged, ...dropped } : paged;
+}
+
+/**
+ * The last way: no single line holds enough of the words, so a page counts the words it holds on any of its lines,
+ * at the same floor, and the pages holding the most come first. Each page shows the lines holding the most words.
+ * Match "pages", which the command words as "No page holds every word" when no page holds them all.
+ */
+function byPage(pages, known, floor, unknown, result, done) {
+  const found = [];
+  let every = false;
+  for (const { p, lines } of pages) {
+    const held = known.filter((w) => lines.some((l) => l.words.has(w))).length;
+    if (held < floor) continue;
+    if (held === known.length) every = true;
+    const hits = lines
+      .map((l) => ({ ...l, score: known.filter((w) => l.words.has(w)).length }))
+      .filter((l) => l.score > 0)
+      .sort((a, b) => b.score - a.score || Number(b.heading) - Number(a.heading) || a.n - b.n);
+    found.push(result(p, hits, held));
+  }
+  if (!found.length) return { match: null, results: [] };
+  return { ...done(every && unknown === 0 ? "pages" : "closest", found), byPage: true };
+}
+
+module.exports = { search, FILLER, messagePattern, placeholderCount, quoted, sentences, WORD_FLOOR, KNOWN_FLOOR, SENTENCE_LIMIT };

package/src/lib/integrationRequest.js

@@ -0,0 +1,89 @@
+/**
+ * Ask Niro to support a language, framework or tool it does not read yet.
+ *
+ * Two ways in, one request: `niro request-integration <name>` in a terminal, and the
+ * `request_integration` MCP tool, which niro-cli's bridge adds to the engine's tools and answers
+ * itself (the engine never goes on the network). Both POST /api/integrations/request on the
+ * orchestrator with the `niro login` session, which emails Niro's team and stores the request
+ * under the signed-in account (Divya, 2026-11-11: "requests should also be stored").
+ *
+ * Nothing is sent without the user's yes: the command asks, and the tool answers a call without
+ * `confirm: true` with a preview for the assistant to show the user.
+ */
+const api = require("./api");
+const credentials = require("./credentials");
+
+const KINDS = ["language", "framework", "tool"];
+const MAX_NAME = 80;
+const MAX_REASON = 1000;
+
+const TOOL = {
+  name: "request_integration",
+  description:
+    "Ask Niro's team to support a language, framework or tool Niro does not read yet (for example Scala, Dart, " +
+    "or a web framework whose routes are missing). The request goes to Niro with the user's signed-in account and " +
+    "is stored. Call it first without confirm: that sends nothing and returns what would be sent; show it to the " +
+    "user, and call again with confirm: true only after the user says yes.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      kind: { type: "string", enum: KINDS, description: "What is being asked for." },
+      name: { type: "string", description: "The language, framework or tool, as people name it (Scala, Quarkus)." },
+      reason: { type: "string", description: "Optional: what the user would use it for, in their words." },
+      confirm: { type: "boolean", description: "true only after the user has said yes to sending it." },
+    },
+    required: ["kind", "name"],
+  },
+};
+
+/** The request with surrounding spaces gone, and why it cannot be sent (null when it can). */
+function check(args = {}) {
+  const request = {
+    kind: String(args.kind || "").trim().toLowerCase(),
+    name: String(args.name || "").trim(),
+    reason: String(args.reason || "").trim(),
+  };
+  let problem = null;
+  if (!KINDS.includes(request.kind)) problem = "kind must be language, framework or tool";
+  else if (!request.name || request.name.length > MAX_NAME) problem = `name is required, at most ${MAX_NAME} characters`;
+  else if (request.reason.length > MAX_REASON) problem = `reason is at most ${MAX_REASON} characters`;
+  return { request, problem };
+}
+
+/** The signed-in account's email, or null when nobody is signed in. */
+function account() {
+  const creds = credentials.load();
+  // Any credential the request layer can use (an expired session is renewed from the CLI token).
+  const usable = creds && (creds.token || creds.cliToken || creds.niroApiKey);
+  return usable ? creds.email || "your Niro account" : null;
+}
+
+async function post(body) {
+  await api.request("POST", "/api/integrations/request", { body });
+}
+
+const result = (text, isError = false) => ({ content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) });
+
+/** Answer a `request_integration` tool call. `send` is the POST, replaced in tests. */
+async function callTool(args, { send = post } = {}) {
+  const { request, problem } = check(args);
+  if (problem) return result(`Not sent: ${problem}.`, true);
+  const who = account();
+  if (!who) return result("Not sent: nobody is signed in to Niro on this machine. Ask the user to run `niro start`.", true);
+  const what = `${request.name} (${request.kind})`;
+  if (args.confirm !== true) {
+    return result([
+      `Not sent yet. This would ask Niro's team to support ${what}, from ${who}.`,
+      request.reason ? `Reason: ${request.reason}` : "No reason given; the user may add one.",
+      "Show this to the user. If they agree, call request_integration again with the same values and confirm: true.",
+    ].join("\n"));
+  }
+  try {
+    await send({ ...request, source: "assistant" });
+  } catch (err) {
+    return result(`Could not send the request: ${err.message}`, true);
+  }
+  return result(`Sent: ${what}, from ${who}. Niro's team sees it and it is kept with the user's account.`);
+}
+
+module.exports = { TOOL, KINDS, check, account, post, callTool };