@tikoci/rosetta 0.5.2 → 0.6.1

package/src/mcp.ts

@@ -8,6 +8,7 @@
  * CLI flags (for compiled binary or `bun run src/mcp.ts`):
  *   browse             Interactive terminal browser (REPL)
  *   --setup [--force]  Download database + print MCP client config
+ *   --refresh          Shortcut for --setup --force (refresh DB)
  *   --version          Print version
  *   --help             Print usage
  *   --http             Start with Streamable HTTP transport (instead of stdio)
@@ -59,6 +60,7 @@ if (args.includes("--help") || args.includes("-h")) {
   console.log("  rosetta browse       Interactive terminal browser");
   console.log("  rosetta --setup      Download database + print MCP client config");
   console.log("  rosetta --setup --force  Re-download database");
+  console.log("  rosetta --refresh    Shortcut for --setup --force");
   console.log("  rosetta --version    Print version");
   console.log("  rosetta --help       Print this help");
   console.log();
@@ -95,6 +97,12 @@ if (args.includes("--setup")) {
   process.exit(0);
 }
 
+if (args.includes("--refresh")) {
+  const { runSetup } = await import("./setup.ts");
+  await runSetup(true);
+  process.exit(0);
+}
+
 // ── MCP Server ──
 
 const useHttp = args.includes("--http");
@@ -158,12 +166,12 @@ if (_dbSchemaVersion !== SCHEMA_VERSION) {
     log("Database updated successfully.");
   } catch (e) {
     log(`Auto-download failed: ${e}`);
-    log(`Run: ${process.argv[0]} --setup --force`);
+    log(`Run: ${process.argv[0]} --refresh`);
   }
 }
 
 // Now import db.ts (opens the DB) and query.ts
-const { getDbStats, initDb } = await import("./db.ts");
+const { db, getDbStats, initDb } = await import("./db.ts");
 const {
   browseCommands,
   browseCommandsAtVersion,
@@ -182,6 +190,8 @@ const {
   searchPages,
   searchProperties,
   searchVideos,
+  searchDude,
+  getDudePage,
 } = await import("./query.ts");
 
 initDb();
@@ -229,6 +239,200 @@ server.registerResource(
   }),
 );
 
+server.registerResource(
+  "schema-sql",
+  "rosetta://schema.sql",
+  {
+    title: "Database Schema DDL",
+    description: "Full SQLite DDL (CREATE TABLE/VIRTUAL TABLE/TRIGGER/INDEX statements) for ros-help.db. Read this before constructing raw SQL queries.",
+    mimeType: "application/sql",
+  },
+  async () => {
+    const rows = db
+      .prepare(
+        "SELECT sql FROM sqlite_master WHERE sql IS NOT NULL ORDER BY type DESC, name ASC",
+      )
+      .all() as Array<{ sql: string }>;
+    const ddl = rows.map((r) => `${r.sql};`).join("\n\n");
+    return {
+      contents: [{
+        uri: "rosetta://schema.sql",
+        mimeType: "application/sql",
+        text: ddl,
+      }],
+    };
+  },
+);
+
+server.registerResource(
+  "schema-guide",
+  "rosetta://schema-guide.md",
+  {
+    title: "Schema Guide",
+    description: "How to query ros-help.db: table relationships, FTS5 tokenizer differences, BM25 weights, and example query patterns.",
+    mimeType: "text/markdown",
+  },
+  async () => ({
+    contents: [{
+      uri: "rosetta://schema-guide.md",
+      mimeType: "text/markdown",
+      text: `# ros-help.db Schema Guide
+
+Read \`rosetta://schema.sql\` for full DDL. This guide explains relationships, FTS5 quirks, and good query patterns.
+
+## Table Map
+
+| Table | Rows (approx) | Description |
+|-------|-------------|-------------|
+| \`pages\` | 317 | One row per Confluence HTML page. Primary content store. |
+| \`sections\` | 2,984 | h1–h3 chunks of pages with anchor IDs for deep-linking. |
+| \`properties\` | 4,860 | CLI property rows extracted from confluenceTable elements. |
+| \`callouts\` | 1,034 | Note/Warning/Info/Tip blocks from Confluence callout macros. |
+| \`commands\` | ~40K | RouterOS command tree entries (dir/cmd/arg) from inspect.json. |
+| \`command_versions\` | 1.67M | Junction: which command paths exist in which RouterOS versions. |
+| \`ros_versions\` | 46 | Metadata per extracted RouterOS version (7.9–7.23beta2). |
+| \`devices\` | 144 | MikroTik hardware specs from product matrix CSV. |
+| \`device_test_results\` | 2,874 | Ethernet/IPSec benchmark rows from mikrotik.com product pages. |
+| \`changelogs\` | varies | Parsed per-entry changelog lines from MikroTik download server. |
+| \`videos\` | 518 | MikroTik YouTube video metadata. |
+| \`video_segments\` | ~1,890 | Chapter-level transcript segments (one per chapter or one per video). |
+
+## Foreign Keys
+
+\`\`\`
+pages ←── sections.page_id
+pages ←── properties.page_id
+pages ←── callouts.page_id
+pages ←── commands.page_id          (nullable — not all commands link to a page)
+devices ←── device_test_results.device_id
+ros_versions ←── command_versions.ros_version
+videos ←── video_segments.video_id  (INTEGER FK to videos.id, NOT videos.video_id TEXT)
+\`\`\`
+
+## FTS5 Virtual Tables
+
+Each table has a companion \`*_fts\` virtual table kept in sync via INSERT/UPDATE/DELETE triggers.
+
+| FTS table | Source | Tokenizer | Indexed columns |
+|-----------|--------|-----------|----------------|
+| \`pages_fts\` | \`pages\` | \`porter unicode61\` | title (3×), path (2×), text (1×), code (0.5×) |
+| \`properties_fts\` | \`properties\` | \`porter unicode61\` | name, description |
+| \`callouts_fts\` | \`callouts\` | \`porter unicode61\` | content |
+| \`changelogs_fts\` | \`changelogs\` | \`porter unicode61\` | category, description |
+| \`videos_fts\` | \`videos\` | \`porter unicode61\` | title, description |
+| \`video_segments_fts\` | \`video_segments\` | \`porter unicode61\` | chapter_title, transcript |
+| \`devices_fts\` | \`devices\` | **\`unicode61\` only** | product_name, product_code, architecture, cpu |
+
+**Why devices use \`unicode61\` without porter:** Model numbers like "RB5009" and "hAP ax3" must not be stemmed. Porter would corrupt them.
+
+## BM25 Column Weights (pages_fts)
+
+The MCP tools use \`bm25(pages_fts, 3.0, 2.0, 1.0, 0.5)\` — title gets 3× weight, path 2×, body text 1×, code blocks 0.5×. In SQLite FTS5 BM25, **lower (more negative) scores rank better**.
+
+\`\`\`sql
+SELECT p.id, p.title, p.url,
+       bm25(pages_fts, 3.0, 2.0, 1.0, 0.5) AS rank
+FROM pages_fts
+JOIN pages p ON p.id = pages_fts.rowid
+WHERE pages_fts MATCH 'firewall filter'
+ORDER BY rank          -- ascending = best match first
+LIMIT 10;
+\`\`\`
+
+## FTS5 Query Syntax
+
+\`\`\`sql
+-- Phrase search (exact sequence)
+WHERE pages_fts MATCH '"firewall filter"'
+
+-- AND (default — all terms must appear)
+WHERE pages_fts MATCH 'dhcp relay'
+
+-- OR
+WHERE pages_fts MATCH 'dhcp OR relay'
+
+-- Column-scoped search
+WHERE pages_fts MATCH 'title:firewall'
+
+-- NEAR (terms within N tokens of each other)
+WHERE pages_fts MATCH 'NEAR(firewall filter, 5)'
+
+-- Prefix match
+WHERE pages_fts MATCH 'route*'
+\`\`\`
+
+Porter stemming is automatic — "configuring" matches "configuration", "configured", "configure".
+
+## Common Join Patterns
+
+### Page + its properties
+\`\`\`sql
+SELECT p.title, pr.name, pr.type, pr.default_val, pr.description
+FROM pages p
+JOIN properties pr ON pr.page_id = p.id
+WHERE p.id = 328220;
+\`\`\`
+
+### FTS search → full section content
+\`\`\`sql
+SELECT p.title, s.heading, s.text, s.anchor_id
+FROM pages_fts
+JOIN pages p ON p.id = pages_fts.rowid
+JOIN sections s ON s.page_id = p.id
+WHERE pages_fts MATCH 'mangle routing mark'
+ORDER BY bm25(pages_fts, 3.0, 2.0, 1.0, 0.5)
+LIMIT 5;
+\`\`\`
+
+### Command path → linked documentation page
+\`\`\`sql
+SELECT c.path, c.type, p.title, p.url
+FROM commands c
+LEFT JOIN pages p ON p.id = c.page_id
+WHERE c.path = '/ip/firewall/filter';
+\`\`\`
+
+### Commands available in a specific RouterOS version
+\`\`\`sql
+SELECT c.path, c.type
+FROM commands c
+JOIN command_versions cv ON cv.command_path = c.path
+WHERE cv.ros_version = '7.22'
+  AND c.path LIKE '/ip/firewall/%'
+ORDER BY c.path;
+\`\`\`
+
+### Device hardware lookup + benchmarks
+\`\`\`sql
+SELECT d.product_name, d.ram_mb, d.cpu,
+       t.test_type, t.mode, t.packet_size, t.throughput_mbps
+FROM devices d
+JOIN device_test_results t ON t.device_id = d.id
+WHERE d.product_name LIKE '%RB5009%'
+ORDER BY t.test_type, t.packet_size;
+\`\`\`
+
+### Changelog entries for a version range, breaking changes only
+\`\`\`sql
+SELECT version, released, category, description
+FROM changelogs
+WHERE is_breaking = 1
+  AND version >= '7.20' AND version <= '7.22'
+ORDER BY version, sort_order;
+\`\`\`
+
+## Gotchas
+
+- **Version sorting:** \`ORDER BY version\` is lexicographic, not numeric. '7.9' > '7.10' lexicographically. Use the \`compareVersions()\` helper in query.ts or fetch all and sort in application code.
+- **content= FTS tables:** Do not SELECT directly from \`*_fts\` tables — they are content tables and must be JOINed via rowid to the source table to get non-indexed columns.
+- **video_segments.video_id** is an INTEGER FK to \`videos.id\`, not the TEXT \`videos.video_id\` (YouTube ID). Join on \`video_segments.video_id = videos.id\`.
+- **NULL page_id in commands:** ~8% of command dirs have no linked page (\`page_id IS NULL\`). Use LEFT JOIN when joining commands to pages.
+- **devices_fts LIKE fallback:** For model numbers ending in ™/® or containing superscripts, FTS may miss them. Use \`LIKE '%RB5009%'\` as a fallback on \`devices.product_name\`.
+`,
+    }],
+  }),
+);
+
 // ---- routeros_search ----
 
 server.registerTool(
@@ -725,6 +929,87 @@ and explanations that complement the text documentation.
   },
 );
 
+// ---- routeros_dude_search ----
+
+server.registerTool(
+  "routeros_dude_search",
+  {
+    description: `Search archived "The Dude" network monitor documentation (from wiki.mikrotik.com via Wayback Machine).
+
+The Dude GUI client is retired, but the Dude server/database remains in RouterOS under /dude.
+These are archived wiki pages covering the Dude v6 GUI (primary) and legacy v3/v4 (reference).
+Many pages include GUI screenshots — use routeros_dude_get_page to see image references.
+
+Separate from routeros_search (which covers current RouterOS v7 docs only).
+For current RouterOS /dude command-line interface, use routeros_command_tree with path "/dude".
+
+→ routeros_dude_get_page: read full page text + screenshot list
+→ routeros_command_tree: browse /dude commands in current RouterOS
+→ routeros_search: search current RouterOS v7 documentation`,
+    inputSchema: {
+      query: z.string().describe("Search terms (e.g., 'probes SNMP', 'device discovery', 'notifications')"),
+      limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(20)
+        .default(8)
+        .optional()
+        .describe("Max results (1–20, default 8)"),
+    },
+  },
+  async ({ query, limit }) => {
+    const results = searchDude(query, limit ?? 8);
+    if (results.length === 0) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No Dude wiki results for: "${query}"\n\nTry:\n- Broader search terms (e.g., 'monitor' instead of 'monitoring')\n- routeros_search for current RouterOS documentation\n- routeros_command_tree with path "/dude" for current /dude commands`,
+          },
+        ],
+      };
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+    };
+  },
+);
+
+// ---- routeros_dude_get_page ----
+
+server.registerTool(
+  "routeros_dude_get_page",
+  {
+    description: `Get full content of an archived Dude wiki page by ID or title.
+
+Returns the complete page text, code blocks, and a list of GUI screenshots with local file paths.
+Screenshots are downloaded images from the archived wiki — use a file viewer for multimodal analysis.
+
+→ routeros_dude_search: find pages by topic
+→ routeros_command_tree: browse /dude commands in current RouterOS`,
+    inputSchema: {
+      id: z.union([z.number().int(), z.string()]).describe("Page ID (number) or title/slug (string)"),
+    },
+  },
+  async ({ id }) => {
+    const page = getDudePage(typeof id === "string" && /^\d+$/.test(id) ? Number.parseInt(id, 10) : id);
+    if (!page) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `No Dude page found for: "${id}"\n\nTry routeros_dude_search to find available pages.`,
+          },
+        ],
+      };
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(page, null, 2) }],
+    };
+  },
+);
+
 // ---- routeros_command_version_check ----
 
 server.registerTool(

package/src/paths.ts

@@ -79,7 +79,7 @@ export function detectMode(srcDir: string): InvocationMode {
  * Stamped into the DB via `PRAGMA user_version` by initDb() and checked at MCP
  * startup to detect stale DBs for bunx users who auto-update the package.
  */
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 
 /**
  * Resolve the version string.

package/src/query.test.ts

@@ -32,6 +32,8 @@ const {
   getTestResultMeta,
   normalizeDeviceQuery,
   searchVideos,
+  searchDude,
+  getDudePage,
 } = await import("./query.ts");
 const { parseChangelog } = await import("./extract-changelogs.ts");
 const { parseVtt, segmentTranscript } = await import("./extract-videos.ts");
@@ -75,12 +77,12 @@ beforeAll(() => {
     (id, page_id, name, type, default_val, description, section, sort_order)
     VALUES (2, 1, 'address-pool', 'string', '', 'Name of the address pool to use', NULL, 1)`);
 
-  db.run(`INSERT INTO ros_versions (version, channel, extra_packages, extracted_at)
-    VALUES ('7.22', 'stable', 0, '2024-01-01T00:00:00Z')`);
-  db.run(`INSERT INTO ros_versions (version, channel, extra_packages, extracted_at)
-    VALUES ('7.9', 'stable', 0, '2023-01-01T00:00:00Z')`);
-  db.run(`INSERT INTO ros_versions (version, channel, extra_packages, extracted_at)
-    VALUES ('7.10.2', 'stable', 0, '2023-06-01T00:00:00Z')`);
+  db.run(`INSERT INTO ros_versions (version, arch, channel, extra_packages, extracted_at)
+    VALUES ('7.22', 'x86', 'stable', 0, '2024-01-01T00:00:00Z')`);
+  db.run(`INSERT INTO ros_versions (version, arch, channel, extra_packages, extracted_at)
+    VALUES ('7.9', 'x86', 'stable', 0, '2023-01-01T00:00:00Z')`);
+  db.run(`INSERT INTO ros_versions (version, arch, channel, extra_packages, extracted_at)
+    VALUES ('7.10.2', 'x86', 'stable', 0, '2023-06-01T00:00:00Z')`);
 
   db.run(`INSERT INTO commands
     (id, path, name, type, parent_path, page_id, description, ros_version)
@@ -350,6 +352,41 @@ beforeAll(() => {
     (id, video_id, chapter_title, start_s, end_s, transcript, sort_order)
     VALUES
     (3, 2, NULL, 0, NULL, 'BGP peering and route reflection allow scalable routing in large networks.', 0)`);
+
+  // Dude wiki page fixtures for searchDude tests
+  db.run(`INSERT INTO dude_pages
+    (id, slug, title, path, version, url, wayback_url, text, code, word_count)
+    VALUES
+    (1, 'Probes', 'Probes', 'The Dude > v6 > Probes', 'v6',
+     'https://wiki.mikrotik.com/wiki/Manual:The_Dude_v6/Probes',
+     'https://web.archive.org/web/2024/https://wiki.mikrotik.com/wiki/Manual:The_Dude_v6/Probes',
+     'Probes are used to monitor specific services on devices. SNMP probes query MIB values. TCP probes check port availability. The Dude supports custom probe definitions with thresholds and alerts.',
+     NULL, 30)`);
+  db.run(`INSERT INTO dude_pages
+    (id, slug, title, path, version, url, wayback_url, text, code, word_count)
+    VALUES
+    (2, 'Device_discovery', 'Device Discovery', 'The Dude > v6 > Device Discovery', 'v6',
+     'https://wiki.mikrotik.com/wiki/Manual:The_Dude_v6/Device_discovery',
+     'https://web.archive.org/web/2024/https://wiki.mikrotik.com/wiki/Manual:The_Dude_v6/Device_discovery',
+     'Device discovery scans networks using SNMP, TCP, and ICMP. The Dude can automatically discover routers, switches, and other network devices on specified subnets.',
+     '/dude discovery add address=10.0.0.0/24', 25)`);
+  db.run(`INSERT INTO dude_pages
+    (id, slug, title, path, version, url, wayback_url, text, code, word_count)
+    VALUES
+    (3, 'Notifications', 'Notifications', 'The Dude > v3 > Notifications', 'v3',
+     'https://wiki.mikrotik.com/wiki/Manual:The_Dude/Notifications',
+     'https://web.archive.org/web/2024/https://wiki.mikrotik.com/wiki/Manual:The_Dude/Notifications',
+     'The Dude can send email and SMS notifications when device status changes. Configure SMTP settings for email alerts.',
+     NULL, 20)`);
+  db.run(`INSERT INTO dude_images (page_id, filename, alt_text, caption, local_path, original_url, sort_order)
+    VALUES (1, 'Dude-probes-all.JPG', 'Probes list', 'All probes view', 'dude/images/Dude-probes-all.JPG',
+     'https://wiki.mikrotik.com/wiki/File:Dude-probes-all.JPG', 0)`);
+  db.run(`INSERT INTO dude_images (page_id, filename, alt_text, caption, local_path, original_url, sort_order)
+    VALUES (1, 'Dude-probe-settings.JPG', 'Probe settings', 'Probe configuration dialog', 'dude/images/Dude-probe-settings.JPG',
+     'https://wiki.mikrotik.com/wiki/File:Dude-probe-settings.JPG', 1)`);
+  db.run(`INSERT INTO dude_images (page_id, filename, alt_text, caption, local_path, original_url, sort_order)
+    VALUES (2, 'Dude-discovery.JPG', 'Discovery settings', NULL, 'dude/images/Dude-discovery.JPG',
+     'https://wiki.mikrotik.com/wiki/File:Dude-discovery.JPG', 0)`);
 });
 
 // ---------------------------------------------------------------------------
@@ -1502,6 +1539,13 @@ describe("schema", () => {
     expect(triggers).toContain("video_segs_au");
   });
 
+  test("content-sync triggers exist for dude_pages", () => {
+    const triggers = triggerNames();
+    expect(triggers).toContain("dude_pages_ai");
+    expect(triggers).toContain("dude_pages_ad");
+    expect(triggers).toContain("dude_pages_au");
+  });
+
   test("PRAGMA user_version matches SCHEMA_VERSION", () => {
     const result = checkSchemaVersion();
     expect(result.ok).toBe(true);
@@ -1667,3 +1711,77 @@ describe("searchVideos", () => {
     expect(results.length).toBeLessThanOrEqual(1);
   });
 });
+
+// ---------------------------------------------------------------------------
+// searchDude: FTS against dude_pages_fts (integration, uses fixture DB)
+// ---------------------------------------------------------------------------
+
+describe("searchDude", () => {
+  test("finds pages matching query", () => {
+    const results = searchDude("probes SNMP");
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].title).toBe("Probes");
+  });
+
+  test("returns image_count for pages with images", () => {
+    const results = searchDude("probes");
+    expect(results[0].image_count).toBe(2);
+  });
+
+  test("returns version field", () => {
+    const results = searchDude("probes");
+    expect(results[0].version).toBe("v6");
+  });
+
+  test("finds v3 pages", () => {
+    const results = searchDude("notifications email");
+    expect(results.length).toBeGreaterThan(0);
+    expect(results[0].version).toBe("v3");
+  });
+
+  test("AND→OR fallback finds results", () => {
+    const results = searchDude("device discovery subnet ICMP");
+    expect(results.length).toBeGreaterThan(0);
+  });
+
+  test("returns empty array for empty query", () => {
+    expect(searchDude("")).toEqual([]);
+  });
+
+  test("respects limit parameter", () => {
+    const results = searchDude("dude", 1);
+    expect(results.length).toBeLessThanOrEqual(1);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getDudePage: full page retrieval with images (integration, uses fixture DB)
+// ---------------------------------------------------------------------------
+
+describe("getDudePage", () => {
+  test("returns page by ID with images", () => {
+    const page = getDudePage(1);
+    expect(page).not.toBeNull();
+    expect(page!.title).toBe("Probes");
+    expect(page!.images.length).toBe(2);
+    expect(page!.images[0].filename).toBe("Dude-probes-all.JPG");
+  });
+
+  test("returns page by title", () => {
+    const page = getDudePage("Probes");
+    expect(page).not.toBeNull();
+    expect(page!.id).toBe(1);
+  });
+
+  test("returns page by slug", () => {
+    const page = getDudePage("Device_discovery");
+    expect(page).not.toBeNull();
+    expect(page!.title).toBe("Device Discovery");
+    expect(page!.images.length).toBe(1);
+  });
+
+  test("returns null for non-existent page", () => {
+    expect(getDudePage(999)).toBeNull();
+    expect(getDudePage("NonExistent")).toBeNull();
+  });
+});

package/src/query.ts

@@ -615,7 +615,7 @@ export function diffCommandVersions(
   pathPrefix?: string,
 ): CommandDiffResult {
   const allVersionRows = db
-    .prepare("SELECT version FROM ros_versions")
+    .prepare("SELECT DISTINCT version FROM ros_versions")
     .all() as Array<{ version: string }>;
   const knownVersions = allVersionRows.map((r) => r.version).sort(compareVersions);
 
@@ -689,7 +689,7 @@ export function checkCommandVersions(
   const versions = rows.map((r) => r.ros_version).sort(compareVersions);
 
   const allVersionRows = db
-    .prepare("SELECT version FROM ros_versions")
+    .prepare("SELECT DISTINCT version FROM ros_versions")
     .all() as Array<{ version: string }>;
   const allVersions = allVersionRows.map((r) => r.version).sort(compareVersions);
   const minTracked = allVersions[0] ?? null;
@@ -1490,6 +1490,97 @@ function runVideosFtsQuery(ftsQuery: string, limit: number): VideoSearchResult[]
 
 // ── Current versions ──
 
+// ── Dude wiki search ──
+
+export type DudeSearchResult = {
+  id: number;
+  title: string;
+  path: string;
+  version: string;
+  url: string;
+  word_count: number | null;
+  image_count: number;
+  excerpt: string;
+};
+
+export type DudeImageResult = {
+  id: number;
+  filename: string;
+  alt_text: string | null;
+  caption: string | null;
+  local_path: string;
+  original_url: string | null;
+  wayback_url: string | null;
+};
+
+export type DudePageResult = {
+  id: number;
+  slug: string;
+  title: string;
+  path: string;
+  version: string;
+  url: string;
+  wayback_url: string;
+  text: string;
+  code: string | null;
+  last_edited: string | null;
+  word_count: number | null;
+  images: DudeImageResult[];
+};
+
+/** Search archived Dude wiki pages via FTS, with AND→OR fallback. */
+export function searchDude(query: string, limit = 8): DudeSearchResult[] {
+  const terms = extractTerms(query);
+  if (terms.length === 0) return [];
+
+  let ftsQuery = buildFtsQuery(terms, "AND");
+  if (!ftsQuery) return [];
+  let results = runDudeFtsQuery(ftsQuery, limit);
+
+  if (results.length === 0 && terms.length > 1) {
+    ftsQuery = buildFtsQuery(terms, "OR");
+    results = runDudeFtsQuery(ftsQuery, limit);
+  }
+
+  return results;
+}
+
+function runDudeFtsQuery(ftsQuery: string, limit: number): DudeSearchResult[] {
+  if (!ftsQuery) return [];
+  try {
+    return db
+      .prepare(
+        `SELECT dp.id, dp.title, dp.path, dp.version, dp.url, dp.word_count,
+                (SELECT COUNT(*) FROM dude_images di WHERE di.page_id = dp.id) as image_count,
+                snippet(dude_pages_fts, 2, '**', '**', '...', 25) as excerpt
+         FROM dude_pages_fts fts
+         JOIN dude_pages dp ON dp.id = fts.rowid
+         WHERE dude_pages_fts MATCH ?
+         ORDER BY rank
+         LIMIT ?`,
+      )
+      .all(ftsQuery, limit) as DudeSearchResult[];
+  } catch {
+    return [];
+  }
+}
+
+/** Get a Dude wiki page by ID or title, with associated images. */
+export function getDudePage(idOrTitle: number | string): DudePageResult | null {
+  const row =
+    typeof idOrTitle === "number"
+      ? db.prepare("SELECT * FROM dude_pages WHERE id = ?").get(idOrTitle)
+      : db.prepare("SELECT * FROM dude_pages WHERE title = ? COLLATE NOCASE OR slug = ? COLLATE NOCASE").get(idOrTitle, idOrTitle);
+  if (!row) return null;
+  const page = row as DudePageResult;
+  page.images = db
+    .prepare("SELECT id, filename, alt_text, caption, local_path, original_url, wayback_url FROM dude_images WHERE page_id = ? ORDER BY sort_order")
+    .all(page.id) as DudeImageResult[];
+  return page;
+}
+
+// ── Current versions (live fetch) ──
+
 const VERSION_BASE_URL = "https://upgrade.mikrotik.com/routeros/NEWESTa7";
 
 /** Fetch current RouterOS versions from MikroTik's upgrade server. */

package/src/release.test.ts

@@ -202,6 +202,21 @@ describe("Makefile", () => {
     expect(phonyBlock).toContain("extract-videos");
   });
 
+  test("has extract-dude target", () => {
+    expect(makefile).toContain("extract-dude:");
+  });
+
+  test("has extract-dude-from-cache target", () => {
+    expect(makefile).toContain("extract-dude-from-cache:");
+  });
+
+  test("extract-dude is in PHONY", () => {
+    const phonyStart = makefile.indexOf(".PHONY:");
+    const phonyEnd = makefile.indexOf("\n\n", phonyStart);
+    const phonyBlock = makefile.slice(phonyStart, phonyEnd);
+    expect(phonyBlock).toContain("extract-dude");
+  });
+
   test("release depends on preflight", () => {
     expect(makefile).toMatch(/^release:.*preflight/m);
   });
@@ -210,6 +225,14 @@ describe("Makefile", () => {
     expect(makefile).toMatch(/^release:.*build-release/m);
   });
 
+  test("extract target includes Dude cache import", () => {
+    expect(makefile).toMatch(/^extract:.*extract-dude-from-cache/m);
+  });
+
+  test("extract-full target includes Dude cache import", () => {
+    expect(makefile).toMatch(/^extract-full:.*extract-dude-from-cache/m);
+  });
+
   test("preflight checks dirty tree", () => {
     expect(makefile).toContain("git diff --quiet");
   });
@@ -255,6 +278,11 @@ describe("release.yml", () => {
     expect(src).toContain("link-commands.ts");
   });
 
+  test("imports Dude wiki from cache", () => {
+    const src = readText(".github/workflows/release.yml");
+    expect(src).toContain("extract-dude-from-cache");
+  });
+
   test("runs quality gate before release", () => {
     const src = readText(".github/workflows/release.yml");
     expect(src).toContain("bun run typecheck");
@@ -292,6 +320,10 @@ describe("CLI flags", () => {
   test("supports --setup flag", () => {
     expect(src).toContain("--setup");
   });
+
+  test("supports --refresh flag", () => {
+    expect(src).toContain("--refresh");
+  });
 });
 
 // ---------------------------------------------------------------------------