@tikoci/rosetta 0.8.1 → 0.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tikoci/rosetta",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "RouterOS documentation as SQLite FTS5 — RAG search + command glossary via MCP",
   "type": "module",
   "license": "MIT",

package/src/browse.ts

@@ -13,6 +13,7 @@
 
 import * as readline from "node:readline";
 import { db, getDbStats, initDb } from "./db.ts";
+import { MCP_INSTRUCTIONS, MCP_STATIC_RESOURCES } from "./mcp-meta.ts";
 import { resolveVersion } from "./paths.ts";
 import type {
   CalloutResult,
@@ -34,6 +35,7 @@ import {
   fetchCurrentVersions,
   getDudePage,
   getPage,
+  getPageCallouts,
   getSkill,
   getTestResultMeta,
   listGlossary,
@@ -100,9 +102,13 @@ function mdToAnsi(s: string): string {
     if (h) {
       const level = h[1].length;
       const text = h[2];
+      // Insert a blank line before headings (unless one already precedes
+      // them) so `══ Summary` doesn't glue onto the previous paragraph.
+      if (out.length > 0 && out[out.length - 1].trim() !== "") out.push("");
       if (level === 1) out.push(bold(`══ ${text}`));
       else if (level === 2) out.push(bold(`── ${text}`));
       else out.push(bold(text));
+      out.push("");
       continue;
     }
     // Bullets
@@ -215,16 +221,16 @@ async function paged(output: string): Promise<boolean> {
     process.stdout.write(`${output}\n`);
     return false;
   }
+  const totalPages = Math.ceil(lines.length / pageSize);
   let offset = 0;
   while (offset < lines.length) {
     const chunk = lines.slice(offset, offset + pageSize);
     process.stdout.write(`${chunk.join("\n")}\n`);
     const newOffset = offset + pageSize;
     if (newOffset >= lines.length) return false;
-    const totalPages = Math.ceil(lines.length / pageSize);
     const curPage = Math.floor(newOffset / pageSize);
     const prompt = dim(
-      `── page ${curPage}/${totalPages}  line ${newOffset}/${lines.length}  [SPACE next | ENTER line | b back | g/G top/end | q quit]`,
+      `── page ${curPage}/${totalPages}  line ${newOffset}/${lines.length}  [SPACE next | ENTER line | b back | 1-${Math.min(9, totalPages)} jump | g/G top/end | q quit]`,
     );
     process.stdout.write(prompt);
     const key = await waitForKey();
@@ -240,6 +246,14 @@ async function paged(output: string): Promise<boolean> {
       offset += 1;
       continue;
     }
+    // Digit 1-9 jumps to that page (1-indexed). If the page is past EOF,
+    // clamp to the last page.
+    if (/^[1-9]$/.test(key)) {
+      const target = Number.parseInt(key, 10);
+      offset = Math.min(lines.length - pageSize, (target - 1) * pageSize);
+      if (offset < 0) offset = 0;
+      continue;
+    }
     // SPACE / f / anything else → next page
     offset = newOffset;
   }
@@ -340,7 +354,7 @@ function renderWelcome(): string {
     ...(stats.skills > 0 ? [`${fmt(stats.skills)} agent skills ${dim("(tikoci — community content)")}`] : []),
     "",
     ...(dbWarning ? [dbWarning, ""] : []),
-    `Type a search query, or ${bold("help")} for commands.`,
+    `Type a search query, command, or ${bold("help")} for full list.`,
   ];
   return box(lines, "rosetta");
 }
@@ -1040,14 +1054,14 @@ function renderHelp(): string {
   cmd("search <query>", "s", "Explicit page search", "routeros_search");
   cmd("page <id|title>", "", "View full page", "routeros_get_page");
   cmd("prop <name>", "p", "Look up property (scoped to current page)", "routeros_lookup_property");
-  cmd("props <query>", "sp", "Search properties by FTS", "routeros_search_properties");
+  cmd("props <query>", "sp", "Search properties by FTS");
   cmd("glossary [term]", "g", "Look up RouterOS jargon / list glossary");
   cmd("cmd [path]", "tree", "Browse command tree", "routeros_command_tree");
   cmd("device <query>", "dev", "Look up device specs", "routeros_device_lookup");
   cmd("tests [device] [type]", "", "Cross-device benchmarks", "routeros_search_tests");
-  cmd("callouts [query]", "cal", "Search callouts (type filter: cal warning)", "routeros_search_callouts");
+  cmd("callouts [query]", "cal", "Search callouts (cal warning, or `cal` on a page)");
   cmd("changelog [query]", "cl", "Search changelogs (cl 7.22, cl breaking)", "routeros_search_changelogs");
-  cmd("videos <query>", "vid", "Search video transcripts", "routeros_search_videos");
+  cmd("videos <query>", "vid", "Search video transcripts");
   cmd("dude <query>", "", "Search archived Dude wiki docs", "routeros_dude_search");
   cmd("skills", "", "List agent skill guides", "rosetta://skills");
   cmd("skill <name>", "", "View a skill guide", "rosetta://skills/{name}");
@@ -1055,25 +1069,29 @@ function renderHelp(): string {
   cmd("vcheck <path>", "vc", "Version range for a command path", "routeros_command_version_check");
   cmd("versions", "ver", "Live-fetch current RouterOS versions", "routeros_current_versions");
   cmd("stats", "", "Database health / counts", "routeros_stats");
-  cmd("back", "b", "Go to previous view");
+  cmd("back", "b", "Re-render previous view (not just print a breadcrumb)");
   cmd("help", "?", "This help");
   cmd("quit", "q", "Exit");
 
   out.push("");
-  out.push(`  ${bold("MCP probe (dot-commands)")}  ${dim("— see what an agent sees")}`);
-  out.push(`  ${cyan(pad(".routeros_search <q> [limit=N]", 38))} ${dim("Same query path as MCP, raw JSON output")}`);
-  out.push(`  ${cyan(pad(".routeros_get_page <id> [section=]", 38))} ${dim("Probe page response with JSON")}`);
-  out.push(`  ${cyan(pad(".routeros_lookup_property name= ...", 38))} ${dim("Direct property lookup")}`);
-  out.push(`  ${cyan(pad(".help", 38))} ${dim("Full list of dot-commands")}`);
+  out.push(`  ${bold("MCP probe (dot-commands)")}  ${dim("— see exactly what an agent sees")}`);
+  out.push(`  ${cyan(pad(".help", 38))} ${dim("Full list of all 13 tool dot-commands + meta")}`);
+  out.push(`  ${cyan(pad(".instructions", 38))} ${dim("MCP server instructions string (sent on init)")}`);
+  out.push(`  ${cyan(pad(".resources", 38))} ${dim("Registered MCP resources (rosetta:// URIs)")}`);
+  out.push(`  ${cyan(pad(".routeros_search <q> [limit=N]", 38))} ${dim("Raw JSON output, same query path as MCP")}`);
   out.push("");
-  out.push(`  ${dim("Navigation: type a number to select from results.")}`);
-  out.push(`  ${dim("After viewing a page, [p] = properties for that page.")}`);
+  out.push(`  ${dim("Navigation: type a number to select from results; in pager, 1–9 jumps to page N.")}`);
+  out.push(`  ${dim("After viewing a page, [p] = properties, [cal] = page callouts, [b] = re-render previous view.")}`);
   out.push(`  ${dim("URLs are clickable in supported terminals (iTerm2, etc.).")}`);
   out.push(`  ${dim("cmd supports @version suffix: cmd /ip/address @7.15")}`);
   out.push("");
   out.push(`  ${bold("CLI flags")}`);
   out.push(`  ${cyan(pad("--db <path>", 26))} ${dim("")} Use a specific database file`);
-  out.push(`  ${cyan(pad("--once", 26))} ${dim("")} Search once and exit (for piping)`);
+  out.push(`  ${cyan(pad("--once", 26))} ${dim("")} Execute any command once and exit (for piping)`);
+  out.push(`  ${cyan(pad("browse <cmd> [args]", 26))} ${dim("")} Pass any TUI command directly from the shell:`)
+  out.push(`  ${cyan(pad("", 26))} ${dim("")}   ${dim("browse changelog 7.20..7.22")}`);
+  out.push(`  ${cyan(pad("", 26))} ${dim("")}   ${dim("browse cmd /ip/firewall")}`);
+  out.push(`  ${cyan(pad("", 26))} ${dim("")}   ${dim("browse .routeros_search vrrp")}`);
 
   return out.join("\n");
 }
@@ -1091,7 +1109,7 @@ function renderHelp(): string {
 
 type DotArgs = Record<string, string | number | boolean>;
 
-function parseDotArgs(rest: string, primary?: string): DotArgs {
+function parseDotArgs(rest: string, primary?: string, aliases?: Record<string, string>): DotArgs {
   const args: DotArgs = {};
   const positional: string[] = [];
   // Split on whitespace but allow key="quoted value"
@@ -1103,7 +1121,10 @@ function parseDotArgs(rest: string, primary?: string): DotArgs {
       if (v === "true") v = true;
       else if (v === "false") v = false;
       else if (/^-?\d+$/.test(v)) v = Number.parseInt(v, 10);
-      args[m[1]] = v;
+      // Normalize alias keys to canonical names so callers can paste the
+      // exact form printed in `next_steps` (e.g. `id=N` for get_page).
+      const key = aliases?.[m[1]] ?? m[1];
+      args[key] = v;
     } else {
       positional.push(t.replace(/^"|"$/g, ""));
     }
@@ -1119,6 +1140,11 @@ type DotTool = {
   primary?: string;
   /** Short one-line description shown by `.help`. */
   desc: string;
+  /** Optional alias→canonical key map (e.g. `{ id: "page" }` so the form
+   *  printed in `next_steps` works verbatim). */
+  aliases?: Record<string, string>;
+  /** TUI command this tool maps to, for cross-referencing in `.help`. */
+  tui?: string;
   /** Run the tool — return any JSON-serializable object. */
   run: (args: DotArgs) => unknown;
 };
@@ -1126,12 +1152,15 @@ type DotTool = {
 const dotTools: Record<string, DotTool> = {
   routeros_search: {
     primary: "query",
+    tui: "s <query>",
     desc: "Unified search — same as `s <query>` but with raw JSON response",
     run: (a) => searchAll(String(a.query ?? ""), a.limit ? Number(a.limit) : undefined),
   },
   routeros_get_page: {
     primary: "page",
-    desc: "Full page by id or title (args: page=, max_length=, section=)",
+    aliases: { id: "page" },
+    tui: "page <id|title>",
+    desc: "Full page by id or title (args: page= or id=, max_length=, section=)",
     run: (a) => {
       const p = a.page;
       const id = typeof p === "number" ? p : /^\d+$/.test(String(p)) ? Number.parseInt(String(p), 10) : String(p);
@@ -1144,11 +1173,13 @@ const dotTools: Record<string, DotTool> = {
   },
   routeros_lookup_property: {
     primary: "name",
+    tui: "p <name>",
     desc: "Property by exact name (args: name=, command_path=)",
     run: (a) => lookupProperty(String(a.name ?? ""), a.command_path ? String(a.command_path) : undefined),
   },
   routeros_command_tree: {
     primary: "path",
+    tui: "cmd [path]",
     desc: "Browse command tree (args: path=, version=, arch=)",
     run: (a) => {
       const path = String(a.path ?? "");
@@ -1158,6 +1189,7 @@ const dotTools: Record<string, DotTool> = {
   },
   routeros_search_changelogs: {
     primary: "query",
+    tui: "cl [query]",
     desc: "Search changelogs (args: query=, version=, from_version=, to_version=, category=, breaking_only=, limit=)",
     run: (a) => searchChangelogs(String(a.query ?? ""), {
       version: a.version ? String(a.version) : undefined,
@@ -1170,6 +1202,7 @@ const dotTools: Record<string, DotTool> = {
   },
   routeros_command_version_check: {
     primary: "command_path",
+    tui: "vc <command_path>",
     desc: "Version range for a command path (args: command_path=)",
     run: (a) => {
       const p = String(a.command_path ?? "");
@@ -1177,6 +1210,7 @@ const dotTools: Record<string, DotTool> = {
     },
   },
   routeros_command_diff: {
+    tui: "diff <from> <to> [path]",
     desc: "Diff command tree between versions (args: from_version=, to_version=, path_prefix=, arch=)",
     run: (a) => diffCommandVersions(
       String(a.from_version ?? ""),
@@ -1187,6 +1221,7 @@ const dotTools: Record<string, DotTool> = {
   },
   routeros_device_lookup: {
     primary: "query",
+    tui: "device <query>",
     desc: "Device lookup with FTS+filters (args: query=, architecture=, license_level=, has_wireless=, ...)",
     run: (a) => searchDevices(String(a.query ?? ""), {
       architecture: a.architecture ? String(a.architecture) : undefined,
@@ -1199,6 +1234,7 @@ const dotTools: Record<string, DotTool> = {
     }, a.limit ? Number(a.limit) : undefined),
   },
   routeros_search_tests: {
+    tui: "tests [device] [type]",
     desc: "Cross-device benchmarks (args: device=, test_type=, mode=, configuration=, packet_size=, sort_by=, limit=)",
     run: (a) => searchDeviceTests({
       device: a.device ? String(a.device) : undefined,
@@ -1211,6 +1247,7 @@ const dotTools: Record<string, DotTool> = {
   },
   routeros_dude_search: {
     primary: "query",
+    tui: "dude <query>",
     desc: "Search archived Dude wiki (args: query=, limit=)",
     run: (a) => searchDude(String(a.query ?? ""), a.limit ? Number(a.limit) : undefined),
   },
@@ -1223,34 +1260,90 @@ const dotTools: Record<string, DotTool> = {
     },
   },
   routeros_stats: {
+    tui: "stats",
     desc: "DB health / counts",
     run: () => getDbStats(),
   },
   routeros_current_versions: {
+    tui: "versions",
     desc: "Live-fetch RouterOS versions per channel",
     run: async () => await fetchCurrentVersions(),
   },
 };
 
+/** Convert FTS5 snippet markers `**word**` inside JSON string values to ANSI
+ *  bold so dot-command output highlights matched terms (matching what the
+ *  TUI search/changelog/video renderers do). Operates only on quoted JSON
+ *  string contents — keys and structure use their own quoting. */
+function highlightSnippetMarkers(json: string): string {
+  return json.replace(/"((?:\\.|[^"\\])*)"/g, (full, body) => {
+    if (!body.includes("**")) return full;
+    const replaced = body.replace(/\*\*([^*"]+)\*\*/g, (_m: string, t: string) => `${ESC}[1m${t}${ESC}[0m`);
+    return `"${replaced}"`;
+  });
+}
+
 async function dispatchDotCommand(input: string): Promise<void> {
-  // .help / .tools — list available probes
+  // .help / .tools — list all dot-commands
   if (input === ".help" || input === ".?" || input === ".tools") {
     const out: string[] = [];
     out.push(`  ${bold("MCP probe — direct tool invocation")}`);
     out.push(`  ${dim("Format: .<tool_name> [positional...] [key=value ...]")}`);
     out.push(`  ${dim("Output: raw JSON, exactly what an MCP client would receive.")}`);
     out.push("");
+    out.push(`  ${bold("Tool dot-commands")} ${dim(`(${Object.keys(dotTools).length} tools)`)}`);
     for (const [name, t] of Object.entries(dotTools)) {
-      out.push(`  ${cyan(`.${name}`)}`);
+      const tuiHint = t.tui ? `  ${dim(`= ${t.tui}`)}` : "";
+      out.push(`  ${cyan(`.${name}`)}${tuiHint}`);
       out.push(`     ${dim(t.desc)}`);
     }
     out.push("");
+    out.push(`  ${bold("Meta dot-commands")}`);
+    out.push(`  ${cyan(".instructions")}     ${dim("Show MCP server instructions string sent to clients on init")}`);
+    out.push(`  ${cyan(".resources")}        ${dim("List MCP resources (rosetta:// URIs)")}`);
+    out.push(`  ${cyan(".help")} / ${cyan(".tools")} / ${cyan(".?")}  ${dim("This list")}`);
+    out.push("");
     out.push(`  ${dim("Example: .routeros_search firewall filter limit=20")}`);
     out.push(`  ${dim("Example: .routeros_get_page 28282 max_length=4000")}`);
+    out.push(`  ${dim("Example: .routeros_get_page id=81362945       (paste from next_steps)")}`);
     out.push(`  ${dim("Example: .routeros_lookup_property name=disabled command_path=/ip/firewall/filter")}`);
     await paged(out.join("\n"));
     return;
   }
+  // .instructions — print MCP server `instructions` string
+  if (input === ".instructions") {
+    const out: string[] = [];
+    out.push(`  ${bold("MCP server instructions")} ${dim("(sent to clients on initialize)")}`);
+    out.push("");
+    out.push(MCP_INSTRUCTIONS);
+    await paged(out.join("\n"));
+    return;
+  }
+  // .resources — list registered MCP resources
+  if (input === ".resources" || input === ".refs") {
+    const out: string[] = [];
+    out.push(`  ${bold("MCP resources")} ${dim("(static + per-skill)")}`);
+    out.push("");
+    for (const r of MCP_STATIC_RESOURCES) {
+      out.push(`  ${cyan(r.uri)}`);
+      out.push(`     ${bold(r.title)}  ${dim(`[${r.mimeType}]`)}`);
+      out.push(`     ${dim(r.description)}`);
+    }
+    try {
+      const skills = listSkills();
+      if (skills.length > 0) {
+        out.push("");
+        out.push(`  ${bold(`Skill resources`)} ${dim(`(${skills.length} from tikoci/routeros-skills — community content, NOT official MikroTik docs)`)}`);
+        for (const s of skills) {
+          out.push(`  ${cyan(`rosetta://skills/${s.name}`)}  ${dim(`${s.word_count}w`)}  ${dim(s.description)}`);
+        }
+      }
+    } catch {
+      // skills table may not exist
+    }
+    await paged(out.join("\n"));
+    return;
+  }
   const m = input.match(/^\.([a-z_]\w*)\s*(.*)$/i);
   if (!m) {
     console.log(dim(`  Bad dot-command syntax. Try '.help' for the list.`));
@@ -1263,11 +1356,11 @@ async function dispatchDotCommand(input: string): Promise<void> {
     return;
   }
   try {
-    const args = parseDotArgs(m[2] ?? "", tool.primary);
+    const args = parseDotArgs(m[2] ?? "", tool.primary, tool.aliases);
     const result = await tool.run(args);
     const json = JSON.stringify(result, null, 2);
     const banner = dim(`── .${name}  args=${JSON.stringify(args)}`);
-    await paged(`${banner}\n${json}`);
+    await paged(`${banner}\n${highlightSnippetMarkers(json)}`);
   } catch (e) {
     console.log(red(`  Error invoking .${name}: ${(e as Error).message}`));
   }
@@ -1314,9 +1407,11 @@ async function dispatch(input: string): Promise<void> {
     case "back":
       if (!popCtx()) {
         console.log(dim("  Already at top."));
-      } else {
-        console.log(dim(`  ← back to ${ctx.type}`));
+        return;
       }
+      // Re-render the now-current context so the user lands back where
+      // they came from instead of dropping to a bare prompt.
+      await renderCurrentContext();
       return;
 
     case "stats":
@@ -1388,14 +1483,16 @@ async function dispatch(input: string): Promise<void> {
     case "cal":
     case "callouts": {
       if (!rest && ctx.type === "page") {
-        // Show callouts for current page
-        const results = searchCallouts("", undefined, 50);
-        const pageCallouts = results.filter((c) => c.page_id === (ctx as { pageId: number }).pageId);
+        // Page-scoped: query callouts directly by page_id (the
+        // FTS-with-empty-query path always returned [] before).
+        const pageCallouts = getPageCallouts((ctx as { pageId: number }).pageId);
         if (pageCallouts.length > 0) {
           await paged(renderCallouts(pageCallouts));
           pushCtx({ type: "callouts", query: "", results: pageCallouts });
-          return;
+        } else {
+          console.log(dim("  This page has no callouts."));
         }
+        return;
       }
       await doSearchCallouts(rest);
       return;
@@ -1557,6 +1654,68 @@ async function handleNumberSelect(idx: number): Promise<void> {
 
 // ── Action functions ──
 
+/**
+ * Re-render the current context, used by `b` / `back` so users land back on
+ * the parent view instead of dropping to a bare prompt. Pure rendering — no
+ * pushCtx (we just popped).
+ */
+async function renderCurrentContext(): Promise<void> {
+  switch (ctx.type) {
+    case "home":
+      console.log(dim("  ← back to home. Type 'help' for commands."));
+      return;
+    case "search":
+      await paged(renderSearchResults(ctx.response));
+      return;
+    case "page":
+    case "sections": {
+      const page = getPage(ctx.pageId);
+      if (page) await paged(renderPage(page));
+      return;
+    }
+    case "commands": {
+      const children = browseCommands(ctx.path);
+      await paged(renderCommandTree(ctx.path, children));
+      return;
+    }
+    case "devices":
+      await paged(renderDeviceResults(ctx.results, "search", ctx.results.length));
+      return;
+    case "device":
+      await paged(renderDeviceCard(ctx.device));
+      return;
+    case "callouts":
+      await paged(renderCallouts(ctx.results));
+      return;
+    case "changelogs":
+      await paged(renderChangelogs(ctx.results));
+      return;
+    case "videos":
+      await paged(renderVideos(ctx.results));
+      return;
+    case "dude":
+      await paged(renderDudeResults(ctx.results));
+      return;
+    case "skills":
+      await doListSkills();
+      return;
+    case "properties": {
+      const lines: string[] = [`  ${bold("Properties")}`, ""];
+      for (let i = 0; i < ctx.results.length; i++) {
+        const p = ctx.results[i];
+        lines.push(`  ${cyan(String(i + 1).padStart(2))}. ${bold(p.name)}  ${dim(`@ ${p.page_title}`)}`);
+      }
+      await paged(lines.join("\n"));
+      return;
+    }
+    case "tests":
+    case "diff":
+    case "vcheck":
+      console.log(dim(`  ← back to ${ctx.type}. Re-run the command to see the result again.`));
+      return;
+  }
+}
+
 async function doSearch(query: string): Promise<void> {
   const resp = searchAll(query);
   await paged(renderSearchResults(resp));
@@ -1660,7 +1819,7 @@ async function doGlossary(rest: string): Promise<void> {
   }
   const aliases = entry.aliases ? `\n  ${dim("Aliases:")} ${entry.aliases}` : "";
   const hint = entry.search_hint ? `\n  ${dim("Search:")} ${cyan(entry.search_hint)}` : "";
-  console.log(`\n  ${bold(entry.term)} ${dim(`[${entry.category}]`)}\n  ${entry.definition}${aliases}${hint}\n`);
+  console.log(`\n  ${bold(entry.term)} ${dim(`[${entry.category}]`)}\n  ${mdToAnsi(entry.definition)}${aliases}${hint}\n`);
 }
 
 async function doCommandTree(path: string): Promise<void> {
@@ -1952,9 +2111,14 @@ async function main() {
     console.log("");
   }
 
-  // Initial query from CLI args
+  // Initial command from CLI args — run through the same dispatch as the REPL
+  // so any TUI command works, not just searches:
+  //   browse changelog 7.20..7.22     → shows changelog range
+  //   browse cmd /ip/firewall          → shows command tree
+  //   browse .routeros_search vrrp     → MCP probe output
+  //   browse dhcp server               → (bare text) search as before
   if (initialQuery) {
-    await doSearch(initialQuery);
+    await dispatch(initialQuery);
     if (onceMode) process.exit(0);
   }
 

package/src/canonicalize.test.ts

@@ -215,11 +215,11 @@ describe('subshells [...]', () => {
     const findCmd = result.commands.find(c => c.verb === 'find');
     const setCmd = result.commands.find(c => c.verb === 'set');
     expect(findCmd).toBeDefined();
-    expect(findCmd!.subshell).toBe(true);
-    expect(findCmd!.path).toBe('/ip/address');
+    expect(findCmd?.subshell).toBe(true);
+    expect(findCmd?.path).toBe('/ip/address');
     expect(setCmd).toBeDefined();
-    expect(setCmd!.path).toBe('/ip/address');
-    expect(setCmd!.verb).toBe('set');
+    expect(setCmd?.path).toBe('/ip/address');
+    expect(setCmd?.verb).toBe('set');
   });
 
   test('nested subshells: /ip route get [find gateway=1.1.1.1]', () => {
@@ -228,18 +228,18 @@ describe('subshells [...]', () => {
     const findCmd = result.commands.find(c => c.verb === 'find');
     const getCmd = result.commands.find(c => c.verb === 'get');
     expect(findCmd).toBeDefined();
-    expect(findCmd!.path).toBe('/ip/route');
-    expect(findCmd!.subshell).toBe(true);
+    expect(findCmd?.path).toBe('/ip/route');
+    expect(findCmd?.subshell).toBe(true);
     expect(getCmd).toBeDefined();
-    expect(getCmd!.path).toBe('/ip/route');
+    expect(getCmd?.path).toBe('/ip/route');
   });
 
   test('subshell with absolute path inside', () => {
     const result = canonicalize('/interface set [/ip address find] name=test', '/system');
     const findCmd = result.commands.find(c => c.verb === 'find');
     expect(findCmd).toBeDefined();
-    expect(findCmd!.path).toBe('/ip/address');
-    expect(findCmd!.subshell).toBe(true);
+    expect(findCmd?.path).toBe('/ip/address');
+    expect(findCmd?.subshell).toBe(true);
   });
 
   test('complex bridge example with nested subshells', () => {
@@ -249,12 +249,12 @@ describe('subshells [...]', () => {
     );
     const setCmd = result.commands.find(c => c.verb === 'set' && !c.subshell);
     expect(setCmd).toBeDefined();
-    expect(setCmd!.path).toBe('/interface/bridge');
+    expect(setCmd?.path).toBe('/interface/bridge');
 
     // The subshell commands should inherit /interface/bridge context
     const findCmd = result.commands.find(c => c.verb === 'find');
     expect(findCmd).toBeDefined();
-    expect(findCmd!.subshell).toBe(true);
+    expect(findCmd?.subshell).toBe(true);
   });
 });
 
@@ -266,7 +266,7 @@ describe('{ } blocks', () => {
     const result = canonicalize('/ip/address { print }');
     const printCmd = result.commands.find(c => c.verb === 'print');
     expect(printCmd).toBeDefined();
-    expect(printCmd!.path).toBe('/ip/address');
+    expect(printCmd?.path).toBe('/ip/address');
   });
 
   test('path persists after block exit', () => {
@@ -281,7 +281,7 @@ describe('{ } blocks', () => {
     const result = canonicalize('{\n  :local a 3;\n  /ip/address/print\n}');
     const printCmd = result.commands.find(c => c.verb === 'print');
     expect(printCmd).toBeDefined();
-    expect(printCmd!.path).toBe('/ip/address');
+    expect(printCmd?.path).toBe('/ip/address');
   });
 });
 
@@ -314,14 +314,14 @@ describe('ICE commands', () => {
     const result = canonicalize(':put [/system/resource/get version]');
     const getCmd = result.commands.find(c => c.verb === 'get');
     expect(getCmd).toBeDefined();
-    expect(getCmd!.path).toBe('/system/resource');
+    expect(getCmd?.path).toBe('/system/resource');
   });
 
   test(':local and :global are skipped', () => {
     const result = canonicalize(':local myVar "test"\n/ip/address/print');
     const printCmd = result.commands.find(c => c.verb === 'print');
     expect(printCmd).toBeDefined();
-    expect(printCmd!.path).toBe('/ip/address');
+    expect(printCmd?.path).toBe('/ip/address');
   });
 });
 
@@ -393,12 +393,12 @@ describe('real-world examples', () => {
     );
     const addCmd = result.commands.find(c => c.verb === 'add' && !c.subshell);
     expect(addCmd).toBeDefined();
-    expect(addCmd!.path).toBe('/ip/firewall/filter');
-    expect(addCmd!.args.some(a => a.startsWith('chain='))).toBe(true);
+    expect(addCmd?.path).toBe('/ip/firewall/filter');
+    expect(addCmd?.args.some(a => a.startsWith('chain='))).toBe(true);
 
     const findCmd = result.commands.find(c => c.verb === 'find');
     expect(findCmd).toBeDefined();
-    expect(findCmd!.subshell).toBe(true);
+    expect(findCmd?.subshell).toBe(true);
   });
 
   test('from Console page: /ip/firewall/filter/add chain=forward', () => {
@@ -413,7 +413,7 @@ describe('real-world examples', () => {
     const result = canonicalize('/ip dhcp-server set myServer lease-script=myLeaseScript');
     const setCmd = result.commands.find(c => c.verb === 'set');
     expect(setCmd).toBeDefined();
-    expect(setCmd!.path).toBe('/ip/dhcp-server');
+    expect(setCmd?.path).toBe('/ip/dhcp-server');
   });
 
   test('scripting: :put with nested subshells', () => {
@@ -422,8 +422,8 @@ describe('real-world examples', () => {
     const getCmd = result.commands.find(c => c.verb === 'get');
     expect(findCmd).toBeDefined();
     expect(getCmd).toBeDefined();
-    expect(findCmd!.path).toBe('/ip/route');
-    expect(getCmd!.path).toBe('/ip/route');
+    expect(findCmd?.path).toBe('/ip/route');
+    expect(getCmd?.path).toBe('/ip/route');
   });
 
   test('firewall rule with find subshell', () => {
@@ -433,10 +433,10 @@ describe('real-world examples', () => {
     const setCmd = result.commands.find(c => c.verb === 'set' && !c.subshell);
     const findCmd = result.commands.find(c => c.verb === 'find');
     expect(setCmd).toBeDefined();
-    expect(setCmd!.path).toBe('/ip/address');
+    expect(setCmd?.path).toBe('/ip/address');
     expect(findCmd).toBeDefined();
-    expect(findCmd!.path).toBe('/ip/address');
-    expect(findCmd!.subshell).toBe(true);
+    expect(findCmd?.path).toBe('/ip/address');
+    expect(findCmd?.subshell).toBe(true);
   });
 
   test('interface set with name', () => {
@@ -456,9 +456,9 @@ describe('real-world examples', () => {
     const printCmd = result.commands.find(c => c.verb === 'print');
     const addCmd = result.commands.find(c => c.verb === 'add');
     expect(printCmd).toBeDefined();
-    expect(printCmd!.path).toBe('/ip/address');
+    expect(printCmd?.path).toBe('/ip/address');
     expect(addCmd).toBeDefined();
-    expect(addCmd!.path).toBe('/ip/route');
+    expect(addCmd?.path).toBe('/ip/route');
   });
 
   test('user example: bridge pvid subshell', () => {
@@ -471,7 +471,7 @@ describe('real-world examples', () => {
     );
     const setCmd = result.commands.find(c => c.verb === 'set' && !c.subshell);
     expect(setCmd).toBeDefined();
-    expect(setCmd!.path).toBe('/interface/bridge');
+    expect(setCmd?.path).toBe('/interface/bridge');
   });
 });
 
@@ -515,6 +515,6 @@ describe('edge cases', () => {
     const result = canonicalize('/interface/print where name~"ether"');
     const printCmd = result.commands.find(c => c.verb === 'print');
     expect(printCmd).toBeDefined();
-    expect(printCmd!.path).toBe('/interface');
+    expect(printCmd?.path).toBe('/interface');
   });
 });

package/src/mcp-meta.ts

@@ -0,0 +1,57 @@
+/**
+ * mcp-meta.ts — small constants shared between the MCP server (`mcp.ts`)
+ * and the TUI dot-commands (`browse.ts`).
+ *
+ * Lives in its own module so importing it from `browse.ts` does not pull
+ * in `mcp.ts`'s top-level CLI dispatch / async IIFE (which would try to
+ * launch the MCP server as a side effect of importing).
+ */
+
+/** MCP `instructions` string sent to clients on init. The TUI's
+ *  `.instructions` dot-command shows the same text an agent sees. */
+export const MCP_INSTRUCTIONS =
+  "RouterOS documentation search. Start with routeros_search for any RouterOS question — it runs a classifier (detects command paths, versions, devices, topics) + BM25 FTS, and returns pages plus a `related` block (command_node, properties, devices, callouts, videos, changelogs, skills) + next-step hints. One call usually answers the question. Drill into specific pages with routeros_get_page; for hardware specs use routeros_device_lookup; for version-specific command changes use routeros_command_diff. Only v7 data exists (7.9+) — v6 is out of scope.";
+
+/** Static metadata for the registered MCP resources. Kept in sync with the
+ *  `server.registerResource` calls in `mcp.ts`; exposed for the TUI
+ *  `.resources` dot-command. Per-skill resources are discovered dynamically
+ *  via `listSkills()` at call time. */
+export const MCP_STATIC_RESOURCES: ReadonlyArray<{
+  uri: string;
+  title: string;
+  description: string;
+  mimeType: string;
+}> = [
+  {
+    uri: "rosetta://datasets/device-test-results.csv",
+    title: "Device Test Results CSV",
+    description: "Full joined benchmark dataset as CSV.",
+    mimeType: "text/csv",
+  },
+  {
+    uri: "rosetta://datasets/devices.csv",
+    title: "Devices CSV",
+    description: "Device catalog with normalized RAM/storage and URLs.",
+    mimeType: "text/csv",
+  },
+  {
+    uri: "rosetta://schema.sql",
+    title: "Database Schema DDL",
+    description: "Full SQLite DDL for ros-help.db.",
+    mimeType: "application/sql",
+  },
+  {
+    uri: "rosetta://schema-guide.md",
+    title: "Schema Guide",
+    description:
+      "Table relationships, FTS5 quirks, BM25 weights, query patterns.",
+    mimeType: "text/markdown",
+  },
+  {
+    uri: "rosetta://skills",
+    title: "RouterOS Agent Skills",
+    description:
+      "List of community-created agent skill guides (tikoci/routeros-skills).",
+    mimeType: "text/markdown",
+  },
+];

package/src/mcp.ts

@@ -26,6 +26,7 @@
  *   TLS_KEY_PATH  — TLS private key path (lower precedence than --tls-key)
  */
 
+import { MCP_INSTRUCTIONS } from "./mcp-meta.ts";
 import { resolveVersion } from "./paths.ts";
 
 const RESOLVED_VERSION = resolveVersion(import.meta.dirname);
@@ -243,6 +244,11 @@ const {
 
 initDb();
 
+/** MCP `instructions` string sent to clients on init. Exported so the TUI's
+ *  `.instructions` dot-command can show the same text an agent sees. */
+// MCP_INSTRUCTIONS now lives in mcp-meta.ts (importing it from browse.ts
+// must not trigger this file's top-level CLI dispatch IIFE).
+
 /** Factory: create a new McpServer with all tools registered.
  *  Called once for stdio, or per-session for HTTP transport. */
 function createServer() {
@@ -251,7 +257,7 @@ const server = new McpServer({
   name: "rosetta",
   version: RESOLVED_VERSION,
 }, {
-  instructions: "RouterOS documentation search. Start with routeros_search for any RouterOS question — it runs a classifier (detects command paths, versions, devices, topics) + BM25 FTS, and returns pages plus a `related` block (command_node, properties, devices, callouts, videos, changelogs, skills) + next-step hints. One call usually answers the question. Drill into specific pages with routeros_get_page; for hardware specs use routeros_device_lookup; for version-specific command changes use routeros_command_diff. Only v7 data exists (7.9+) — v6 is out of scope.",
+  instructions: MCP_INSTRUCTIONS,
 });
 
 server.registerResource(

package/src/query.test.ts

@@ -2047,21 +2047,21 @@ describe("lookupGlossary", () => {
   test("finds exact term match", () => {
     const result = lookupGlossary("chr");
     expect(result).not.toBeNull();
-    expect(result!.term).toBe("chr");
-    expect(result!.definition).toContain("Cloud Hosted Router");
-    expect(result!.category).toBe("product");
+    expect(result?.term).toBe("chr");
+    expect(result?.definition).toContain("Cloud Hosted Router");
+    expect(result?.category).toBe("product");
   });
 
   test("case-insensitive lookup", () => {
     const result = lookupGlossary("CHR");
     expect(result).not.toBeNull();
-    expect(result!.term).toBe("chr");
+    expect(result?.term).toBe("chr");
   });
 
   test("finds term by alias", () => {
     const result = lookupGlossary("openvpn");
     expect(result).not.toBeNull();
-    expect(result!.term).toBe("ovpn");
+    expect(result?.term).toBe("ovpn");
   });
 
   test("returns null for unknown term", () => {
@@ -2075,8 +2075,8 @@ describe("lookupGlossary", () => {
   test("search_hint field is populated", () => {
     const result = lookupGlossary("capsman");
     expect(result).not.toBeNull();
-    expect(result!.search_hint).toBeTruthy();
-    expect(result!.search_hint).toContain("CAPsMAN");
+    expect(result?.search_hint).toBeTruthy();
+    expect(result?.search_hint).toContain("CAPsMAN");
   });
 });
 

package/src/query.ts

@@ -1106,6 +1106,27 @@ function runCalloutsFtsQuery(
   }
 }
 
+/**
+ * All callouts for a given page, sorted by source order. TUI-facing helper
+ * for `cal` invoked inside a page context — replaces the broken
+ * `searchCallouts("", undefined, …)` empty-FTS path which always returns [].
+ *
+ * Page metadata (`page_title`, `page_url`) is included so the rendering path
+ * can reuse `renderCallouts()` without a second join.
+ */
+export function getPageCallouts(pageId: number, limit = 100): CalloutResult[] {
+  return db
+    .prepare(
+      `SELECT c.type, c.content, pg.title as page_title, pg.url as page_url,
+              pg.id as page_id, substr(c.content, 1, 200) as excerpt
+       FROM callouts c
+       JOIN pages pg ON pg.id = c.page_id
+       WHERE c.page_id = ?
+       ORDER BY c.sort_order LIMIT ?`,
+    )
+    .all(pageId, limit) as CalloutResult[];
+}
+
 /** Diff two RouterOS versions — which command paths were added/removed between them. */
 export type CommandDiffResult = {
   from_version: string;