@tikoci/rosetta 0.8.9 → 0.8.11

package/README.md

@@ -255,7 +255,7 @@ Type a search query to find documentation pages, then select a numbered result t
 
 Type `help` for the full command list. URLs are clickable in terminals that support OSC 8 hyperlinks (iTerm2, Windows Terminal, GNOME Terminal, etc.).
 
-The browser is also useful as a test harness — it interacts with the data the same way an AI agent would through MCP, so gaps or rough edges visible here often point to MCP tool improvements too.
+The browser is also useful as an audit surface — it shares core query functions with MCP and exposes every MCP tool as a raw dot-command, so gaps or rough edges visible here often point to agent-facing improvements too.
 
 > **From a router:** If rosetta is installed as a `/app`, access the browser via `/container/shell app-rosetta` then `/app/rosetta browse`.
 
@@ -275,13 +275,14 @@ Ask your AI assistant questions like:
 
 ## MCP Tools
 
-The server exposes 13 tools designed to work together — agents start with `routeros_search` and drill into specific data as needed:
+The server exposes 14 tools designed to work together — agents start with `routeros_search` and drill into specific data as needed:
 
 | Tool | What it does |
 |------|-------------|
 | `routeros_search` | **Start here.** Unified search with input classifier — returns pages + related callouts, videos, properties, changelogs, devices, skills |
 | `routeros_get_page` | Full page content by ID or title, section-aware for large pages |
 | `routeros_lookup_property` | Property by exact name — type, default, description |
+| `routeros_explain_command` | Read-only explanation for a CLI command — canonical path/verb, args, warnings, docs, changelogs |
 | `routeros_command_tree` | Browse the command hierarchy (`/ip/firewall/filter` style) |
 | `routeros_search_changelogs` | Changelogs filtered by version range, category, breaking flag |
 | `routeros_command_version_check` | Which RouterOS versions include a command path |

package/package.json

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

package/src/browse.ts

@@ -33,6 +33,7 @@ import {
   checkCommandVersions,
   compareVersions,
   diffCommandVersions,
+  explainCommand,
   fetchCurrentVersions,
   getDudePage,
   getPage,
@@ -1105,7 +1106,7 @@ function renderHelp(): string {
 
   out.push("");
   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(".help", 38))} ${dim("Full list of all 14 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")}`);
@@ -1118,7 +1119,7 @@ function renderHelp(): string {
   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("")} 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("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")}`);
@@ -1207,6 +1208,15 @@ const dotTools: Record<string, DotTool> = {
     desc: "Property by exact name (args: name=, command_path=)",
     run: (a) => lookupProperty(String(a.name ?? ""), a.command_path ? String(a.command_path) : undefined),
   },
+  routeros_explain_command: {
+    primary: "command",
+    desc: "Explain CLI command: canonical path/verb, args, warnings, docs, changelogs (args: command=, ros_version=, model=)",
+    run: (a) => explainCommand(
+      String(a.command ?? ""),
+      a.ros_version ? String(a.ros_version) : undefined,
+      a.model ? String(a.model) : undefined,
+    ),
+  },
   routeros_command_tree: {
     primary: "path",
     tui: "cmd [path]",

package/src/canonicalize-resolver.ts

@@ -0,0 +1,59 @@
+/**
+ * DB-backed verb resolver for {@link canonicalize}.
+ *
+ * `canonicalize.ts` is intentionally pure — it knows nothing about the DB.
+ * This module is the rosetta-side adapter: given a `Database`, it returns
+ * an `isVerb(token, parentPath)` function that consults the `commands`
+ * table to decide whether a token at a given menu is a path-specific verb
+ * (`type='cmd'`). The pure canonicalizer still keeps its universal verb
+ * fallback active for helpers that RouterOS introspection does not enumerate
+ * everywhere (for example `find`).
+ *
+ * Why path-aware lookup matters:
+ *   /interface/wifi-qcom/info   ← `info` is a cmd at /interface/wifi-qcom
+ *   /interface/wireless/info    ← `info` is a dir at /interface/wireless
+ * The pure-module universal-verb-set heuristic can't tell these apart;
+ * the DB can.
+ *
+ * The resolver caches per-call results in-memory — most realistic inputs
+ * touch a small number of (token, parentPath) pairs and the cache turns
+ * a sub-millisecond SQL query into a hash lookup.
+ *
+ * Cross-ref: rosetta issue #5 (H4), DESIGN.md "canonicalize: vendoring
+ * intent and DB-backed resolver".
+ */
+
+import type { Database } from "bun:sqlite";
+
+/**
+ * Build an `isVerb` resolver bound to a rosetta DB. Returns a synchronous
+ * function suitable for {@link CanonicalizeOptions.isVerb}.
+ *
+ * The resolver is path-aware: `(token, parentPath) => boolean`. A token
+ * counts as a path-specific verb if there exists a `commands` row with
+ * `name=token`, `parent_path=parentPath`, `type='cmd'`. Returning `false`
+ * means "no DB-specific hit"; the canonicalizer may still accept the token
+ * via its built-in universal verb set.
+ */
+export function makeDbVerbResolver(
+  db: Database,
+): (token: string, parentPath: string) => boolean {
+  const stmt = db.prepare(
+    "SELECT 1 FROM commands WHERE name = ? AND parent_path = ? AND type = 'cmd' LIMIT 1",
+  );
+  // Per-resolver cache. Lifetime = lifetime of the resolver, which is the
+  // lifetime of the process for searchAll's call site. A long-running TUI
+  // session benefits; a one-shot CLI invocation pays a single SQL query
+  // per unique (token, parentPath) pair regardless.
+  const cache = new Map<string, boolean>();
+
+  return (token: string, parentPath: string): boolean => {
+    const key = `${parentPath}\x00${token}`;
+    const cached = cache.get(key);
+    if (cached !== undefined) return cached;
+    const row = stmt.get(token, parentPath);
+    const result = row !== null && row !== undefined;
+    cache.set(key, result);
+    return result;
+  };
+}

package/src/canonicalize.fuzz.test.ts

@@ -0,0 +1,371 @@
+/**
+ * Fuzz / robustness tests for canonicalize.ts.
+ *
+ * These probe the parser against pathological inputs — prose, markdown,
+ * malformed scripts, RouterOS scripting constructs — to document where it
+ * is robust, where it is wrong-but-quiet, and where the behaviour is
+ * underspecified.
+ *
+ * Inputs originated from `lsp-routeros-ts/docs/canonicalize-audit.md`
+ * (2026-04-25 audit) and were ported here so future fixes have a
+ * regression surface.
+ *
+ * Conventions:
+ * - `test(...)` — current behaviour (anchor test). Update if a fix
+ *   intentionally changes it; add a comment noting the audit finding number.
+ * - `test.todo(...)` — known-bad behaviour the audit recommended fixing.
+ *   Promote to `test(...)` once the fix lands.
+ *
+ * Cross-ref:
+ * - `lsp-routeros-ts/docs/canonicalize-audit.md` (findings #1–#12, hardenings H1–H8)
+ */
+import { describe, expect, test } from 'bun:test';
+import { canonicalize, extractMentions, extractPaths } from './canonicalize.ts';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function paths(input: string, cwd = '/'): string[] {
+  return canonicalize(input, cwd).commands.map(c =>
+    c.verb ? `${c.path}/${c.verb}` : c.path,
+  );
+}
+
+// ===========================================================================
+// Crash-resistance — none of these may throw
+// ===========================================================================
+describe('does not crash on malformed input', () => {
+  const torture = [
+    '',
+    '   \t  ',
+    '# comment only',
+    '/',
+    '\n\n\n',
+    '/system/script/add source="never ends',  // unclosed quote
+    '/ip/address/set [find interface=ether1', // unclosed [
+    '/ip/address { print',                    // unclosed {
+    '/ip/address/print ]',                    // stray ]
+    '/ip/address/print }',                    // stray }
+    ';;;;',
+    '\\',
+    '$$$$',
+    ':::::',
+    '////',
+    '[]{}();',
+  ];
+  for (const input of torture) {
+    test(`no throw: ${JSON.stringify(input).slice(0, 60)}`, () => {
+      expect(() => canonicalize(input)).not.toThrow();
+    });
+  }
+});
+
+// ===========================================================================
+// H7 — BOM and zero-width characters (FIXED 2026-04-25 in tokenizer)
+// ===========================================================================
+describe('H7: BOM and zero-width characters', () => {
+  test('BOM-prefixed input is stripped before parsing', () => {
+    // U+FEFF byte-order mark prepended
+    const result = canonicalize('/ip/address/print');
+    expect(result.commands.length).toBe(1);
+    expect(result.commands[0].path).toBe('/ip/address');
+    expect(result.commands[0].verb).toBe('print');
+  });
+
+  test('zero-width space is treated as whitespace', () => {
+    // U+200B zero-width space between `ip` and `/`
+    const result = canonicalize('/ip​/address/print');
+    expect(result.commands.length).toBe(1);
+    expect(result.commands[0].path).toBe('/ip/address');
+    expect(result.commands[0].verb).toBe('print');
+  });
+});
+
+// ===========================================================================
+// Markdown backticks (FIXED 2026-04-25 — backticks now whitespace)
+// ===========================================================================
+describe('markdown backticks treated as whitespace', () => {
+  test('inline backtick-wrapped path extracts cleanly', () => {
+    const result = canonicalize('Use `/ip/address/print` to list');
+    // "Use" still becomes a phantom (finding #1, see H1 lenient mode).
+    // But the backticks no longer pollute the path.
+    const cmd = result.commands.find(c => c.verb === 'print');
+    expect(cmd).toBeDefined();
+    expect(cmd?.path).toContain('/ip/address');
+  });
+
+  test('markdown fence wrapper does not break extraction', () => {
+    const result = canonicalize('```routeros\n/ip/address/print\n```');
+    const cmd = result.commands.find(c => c.verb === 'print');
+    expect(cmd?.path).toBe('/ip/address');
+  });
+});
+
+// ===========================================================================
+// Universal verbs added 2026-04-25 — clear, unset, reset-counters,
+// reset-counters-all (verified universal in rosetta DB; safe to add)
+// ===========================================================================
+describe('expanded universal verbs', () => {
+  test('unset is recognised', () => {
+    const r = canonicalize('/ip/address/unset disabled');
+    expect(r.commands[0].path).toBe('/ip/address');
+    expect(r.commands[0].verb).toBe('unset');
+  });
+
+  test('clear is recognised', () => {
+    const r = canonicalize('/system/logging/action/clear name=test');
+    const c = r.commands.find(x => x.verb === 'clear');
+    expect(c?.path).toBe('/system/logging/action');
+  });
+
+  test('reset-counters is recognised', () => {
+    const r = canonicalize('/interface/reset-counters ether1');
+    expect(r.commands[0].verb).toBe('reset-counters');
+    expect(r.commands[0].path).toBe('/interface');
+  });
+
+  test('reset-counters-all is recognised', () => {
+    const r = canonicalize('/ip/firewall/filter/reset-counters-all');
+    expect(r.commands[0].verb).toBe('reset-counters-all');
+    expect(r.commands[0].path).toBe('/ip/firewall/filter');
+  });
+});
+
+// ===========================================================================
+// Variables: today they tolerate as-is in args; not mistaken for paths
+// when AFTER a verb (because then verb is set and they fall into the
+// args branch). This is the safe case.
+// ===========================================================================
+describe('variables in args (safe positions)', () => {
+  test('$var after verb stays in args', () => {
+    const r = canonicalize('/ip/address/remove $myAddr');
+    expect(r.commands[0].args).toEqual(['$myAddr']);
+  });
+
+  test('$var inside subshell after verb', () => {
+    const r = canonicalize('/ip/address set [find interface=$iface] disabled=yes');
+    const find = r.commands.find(c => c.verb === 'find');
+    expect(find?.args.some(a => a.includes('$iface'))).toBe(true);
+  });
+});
+
+// ===========================================================================
+// Common scripting constructs that work today
+// ===========================================================================
+describe(':foreach extracts inner commands', () => {
+  test('extracts find subshell + remove command', () => {
+    const r = canonicalize(':foreach i in=[/ip address find] do={ /ip address remove $i }');
+    const find = r.commands.find(c => c.verb === 'find' && c.subshell);
+    const remove = r.commands.find(c => c.verb === 'remove');
+    expect(find?.path).toBe('/ip/address');
+    expect(remove?.path).toBe('/ip/address');
+  });
+});
+
+describe(':do { } while=', () => {
+  test('extracts inner run command', () => {
+    const r = canonicalize(':do { /system/script/run myscript } while=($i < 5)');
+    const run = r.commands.find(c => c.verb === 'run');
+    expect(run?.path).toBe('/system/script');
+  });
+});
+
+describe('scheduler one-liner', () => {
+  test('three semicolon-separated commands extract cleanly', () => {
+    const ps = paths('/ip/firewall/filter/print; /ip/address/print; /system/identity/print');
+    expect(ps).toEqual([
+      '/ip/firewall/filter/print',
+      '/ip/address/print',
+      '/system/identity/print',
+    ]);
+  });
+});
+
+// ===========================================================================
+// Anchor tests for known-bad behaviour (audit findings)
+// These DOCUMENT current behaviour. When a hardening lands, flip them.
+// ===========================================================================
+describe('finding #1 — mid-line slash does not restart path (anchor)', () => {
+  test('leading prose word becomes phantom path segment', () => {
+    // Today: "Run" gets jammed into the path.
+    // After H1 (lenient mode): would be dropped.
+    const r = canonicalize('Run /ip/address/print');
+    expect(r.commands[0].path).toBe('/Run/ip/address');
+    expect(r.commands[0].verb).toBe('print');
+  });
+
+  test('two paths joined by " and " merge into one command', () => {
+    // Today: only the first command is recognised; the second path
+    // becomes positional args.
+    // After H1 (lenient mode): both should extract independently.
+    const r = canonicalize('/ip/address/print and /ip/route/print');
+    expect(r.commands.length).toBe(1);
+    expect(r.commands[0].path).toBe('/ip/address');
+    expect(r.commands[0].args).toContain('and');
+  });
+});
+
+describe('finding #4 — menu-specific verbs', () => {
+  // Today (no resolver): zero commands. /interface/wifi-qcom/info is not in
+  // the universal verb set so the parser treats it as a path without a verb.
+  // H4 fixed this for callers that wire a resolver.
+  test('/interface/wifi-qcom/info without resolver produces no command (anchor)', () => {
+    const r = canonicalize('/interface/wifi-qcom/info');
+    expect(r.commands.length).toBe(0);
+  });
+
+  // H4 — supplying a path-aware resolver makes /interface/wifi-qcom/info
+  // classify correctly. The resolver returns true for `info` at
+  // /interface/wifi-qcom only, mirroring a DB/live-router path-specific hit.
+  const wifiQcomResolver = (token: string, parentPath: string) =>
+    parentPath === '/interface/wifi-qcom' && token === 'info';
+
+  test('H4: /interface/wifi-qcom/info with resolver classifies as cmd', () => {
+    const r = canonicalize('/interface/wifi-qcom/info', '/', { isVerb: wifiQcomResolver });
+    expect(r.commands.length).toBe(1);
+    expect(r.commands[0].path).toBe('/interface/wifi-qcom');
+    expect(r.commands[0].verb).toBe('info');
+  });
+
+  test('H4: /interface/wireless/info with same resolver stays a path (info is a dir there)', () => {
+    // Resolver only returns true for `info` at /interface/wifi-qcom, not /interface/wireless.
+    // The token `info` at /interface/wireless is therefore navigation, not
+    // a verb — exactly the disambiguation H4 enables.
+    const r = canonicalize('/interface/wireless/info', '/', { isVerb: wifiQcomResolver });
+    expect(r.commands.length).toBe(0);
+    expect(r.finalPath).toBe('/interface/wireless/info');
+  });
+
+  test('H4: universal-verb-set still works when resolver is supplied', () => {
+    // The DB resolver supplements path-specific verbs, but it is not allowed
+    // to disable universal helpers. RouterOS command data does not enumerate
+    // all helper verbs (notably `find`) under every parent path.
+    const r = canonicalize('/ip/address/print', '/', {
+      isVerb: () => false,
+    });
+    expect(r.commands[0]?.path).toBe('/ip/address');
+    expect(r.commands[0]?.verb).toBe('print');
+  });
+});
+
+describe('finding #3 — paren expression scope needs re-audit (anchor)', () => {
+  test(':if with paren expression preserves recognized inner command', () => {
+    // The original audit used /log/info here, but the zero-command result was
+    // confounded by finding #4 (menu-specific verb recognition). With a
+    // recognized command in the body, current code does preserve the block.
+    // H3 stays as a re-audit item for expression-scope correctness.
+    const r = canonicalize(':if ($x = 1) do={ /ip/address/print }');
+    expect(r.commands[0]?.path).toBe('/ip/address');
+    expect(r.commands[0]?.verb).toBe('print');
+  });
+});
+
+describe('finding #7 — pure path mention not in extractPaths (anchor)', () => {
+  test('bare path mention returns empty extractPaths', () => {
+    // extractPaths only includes commands that have a verb. Use
+    // extractMentions for navigation-only references — see H6 below.
+    const ps = extractPaths('/ip/firewall/filter');
+    expect(ps).toEqual([]);
+  });
+});
+
+// ===========================================================================
+// H6 — extractMentions surfaces bare path mentions
+// ===========================================================================
+describe('H6: extractMentions for navigation-only references', () => {
+  test('bare /ip/firewall/filter is reported as a mention', () => {
+    const m = extractMentions('/ip/firewall/filter');
+    expect(m).toEqual(['/ip/firewall/filter']);
+  });
+
+  test('two semicolon-separated bare paths surface both', () => {
+    // Note: prose like "See /ip/firewall/filter and /ip/firewall/nat" is
+    // still mishandled by the mid-line-slash issue (finding #1, H1). Use
+    // explicit separators here — that's what extractMentions can support
+    // before lenient mode lands.
+    const m = extractMentions('/ip/firewall/filter ; /ip/firewall/nat');
+    expect(m).toContain('/ip/firewall/filter');
+    expect(m).toContain('/ip/firewall/nat');
+  });
+
+  test('command path also surfaces as mention (dir + dir/verb)', () => {
+    const m = extractMentions('/ip/address/print');
+    // Contains both the verbed path and the dir.
+    expect(m).toContain('/ip/address/print');
+    expect(m).toContain('/ip/address');
+  });
+
+  test('mentions are deduped in order of first appearance', () => {
+    const m = extractMentions('/ip/address ; /ip/address/print');
+    // /ip/address shows up twice (nav + dir-of-cmd) but is only emitted once.
+    expect(m.filter(p => p === '/ip/address').length).toBe(1);
+  });
+});
+
+describe('finding #8 — source={…} block-as-value misread (anchor)', () => {
+  test('outer add command is dropped when source is a block', () => {
+    // Today: extracts only the inner /ip/address/print and DROPS the
+    // outer /system/script/add.
+    // After H5: { after key= should be a quoted block value, not
+    // a scope to recurse into.
+    const r = canonicalize('/system/script/add name=foo source={ /ip/address/print }');
+    const inner = r.commands.find(c => c.verb === 'print');
+    const outer = r.commands.find(c => c.verb === 'add');
+    expect(inner).toBeDefined();        // current behaviour
+    expect(outer).toBeUndefined();      // ← this is the bug
+  });
+});
+
+// ===========================================================================
+// Hardenings not yet shipped — todo() so they show in the runner output
+// ===========================================================================
+// ===========================================================================
+// H8 — confidence flag on each CanonicalCommand
+// ===========================================================================
+describe('H8: confidence flag', () => {
+  test('high: absolute path with explicit verb', () => {
+    const r = canonicalize('/ip/address/print');
+    expect(r.commands[0].confidence).toBe('high');
+  });
+
+  test('medium: relative path with cwd', () => {
+    const r = canonicalize('print', '/ip/address');
+    expect(r.commands[0].confidence).toBe('medium');
+  });
+
+  test('low: verb inferred at flush time when no path context exists', () => {
+    // Bare word `print` with cwd='/' gates out of the explicit-verb check
+    // (the parser only treats a word as a verb if it has path context).
+    // It falls through to the path-segment branch and flushCommand's
+    // trailing-segment-as-verb fallback promotes it. That is exactly the
+    // looser/prose-shaped path H8 flags as 'low'.
+    const r = canonicalize('print');
+    expect(r.commands[0]?.verb).toBe('print');
+    expect(r.commands[0]?.confidence).toBe('low');
+  });
+
+  test('subshell command keeps confidence on the inner command', () => {
+    const r = canonicalize('/ip/address set [find interface=ether1] disabled=yes');
+    const find = r.commands.find(c => c.subshell);
+    const set = r.commands.find(c => c.verb === 'set');
+    expect(find?.confidence).toBeDefined();
+    expect(set?.confidence).toBe('high');
+  });
+});
+
+// ===========================================================================
+// Hardenings not yet shipped — todo() so they show in the runner output
+// ===========================================================================
+describe('hardenings not yet shipped', () => {
+  test.todo('H1: lenient mode drops leading prose word', () => {
+    // const r = canonicalize('Run /ip/address/print', '/', { mode: 'lenient' });
+    // expect(r.commands).toEqual([
+    //   { path: '/ip/address', verb: 'print', args: [], confidence: 'low' },
+    // ]);
+  });
+  test.todo('H1: lenient mode splits "/a/b/c and /d/e/f" into two commands', () => {});
+  test.todo('H2: $variable becomes Tok.Var, never a path segment', () => {});
+  test.todo('H3: re-audit paren expression scope independent of menu-specific verbs', () => {});
+  test.todo('H5: source={ … } in /system/script/add is a value, not a scope', () => {});
+});

package/src/canonicalize.test.ts

@@ -3,6 +3,7 @@ import {
   _normalizePath,
   _tokenize,
   canonicalize,
+  extractMentions,
   extractPaths,
   primaryPath,
 } from './canonicalize.ts';
@@ -518,3 +519,70 @@ describe('edge cases', () => {
     expect(printCmd?.path).toBe('/interface');
   });
 });
+
+// ===========================================================================
+// CanonicalizeOptions — pluggable isVerb resolver (H4)
+// ===========================================================================
+describe('CanonicalizeOptions.isVerb', () => {
+  test('resolver receives non-universal token and parent path', () => {
+    const calls: Array<{ token: string; parentPath: string }> = [];
+    canonicalize('/interface/wifi-qcom/info', '/', {
+      isVerb: (token, parentPath) => {
+        calls.push({ token, parentPath });
+        return token === 'info' && parentPath === '/interface/wifi-qcom';
+      },
+    });
+    expect(calls.some(c => c.token === 'info' && c.parentPath === '/interface/wifi-qcom')).toBe(true);
+  });
+
+  test('resolver call site is path-aware: same token, different parent', () => {
+    // Call with a resolver that ONLY recognizes `info` at /interface/wifi-qcom.
+    const isVerb = (token: string, parentPath: string) =>
+      token === 'info' && parentPath === '/interface/wifi-qcom';
+
+    const atWifiQcom = canonicalize('/interface/wifi-qcom/info', '/', { isVerb });
+    expect(atWifiQcom.commands[0]?.verb).toBe('info');
+    expect(atWifiQcom.commands[0]?.path).toBe('/interface/wifi-qcom');
+
+    // Same token at a different path → not a verb, treated as navigation.
+    const atWifi = canonicalize('/interface/wireless/info', '/', { isVerb });
+    expect(atWifi.commands.length).toBe(0);
+    expect(atWifi.finalPath).toBe('/interface/wireless/info');
+  });
+
+  test('universal verbs remain active when a resolver is supplied', () => {
+    const result = canonicalize('/ip/address set [find interface=ether1] disabled=yes', '/', {
+      isVerb: () => false,
+    });
+    const setCmd = result.commands.find(c => c.verb === 'set' && !c.subshell);
+    const findCmd = result.commands.find(c => c.verb === 'find' && c.subshell);
+    expect(setCmd?.path).toBe('/ip/address');
+    expect(findCmd?.path).toBe('/ip/address');
+  });
+
+  test('omitting options preserves backward-compatible behaviour', () => {
+    const r1 = canonicalize('/ip/address/print');
+    const r2 = canonicalize('/ip/address/print', '/');
+    expect(r1.commands[0]?.verb).toBe('print');
+    expect(r2.commands[0]?.verb).toBe('print');
+  });
+});
+
+// ===========================================================================
+// extractMentions (H6) — sanity unit tests
+// ===========================================================================
+describe('extractMentions', () => {
+  test('verbed command surfaces both dir and dir/verb', () => {
+    const m = extractMentions('/ip/address/print');
+    expect(m).toContain('/ip/address');
+    expect(m).toContain('/ip/address/print');
+  });
+
+  test('bare path surfaces as a single mention', () => {
+    expect(extractMentions('/ip/firewall/filter')).toEqual(['/ip/firewall/filter']);
+  });
+
+  test('empty input → empty mentions', () => {
+    expect(extractMentions('')).toEqual([]);
+  });
+});