@hanna84/mcp-writing 2.12.22 → 2.14.0

package/CHANGELOG.md

@@ -4,11 +4,31 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### [v2.14.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.13.0...v2.14.0)
+
+- feat(reference): add reference link indexing for Phase 4B [`#147`](https://github.com/hannasdev/mcp-writing.git
+/pull/147)
+
+#### [v2.13.0](https://github.com/hannasdev/mcp-writing.git
+/compare/v2.12.22...v2.13.0)
+
+> 30 April 2026
+
+- feat: add reference document search [`#146`](https://github.com/hannasdev/mcp-writing.git
+/pull/146)
+- Release 2.13.0 [`0df673a`](https://github.com/hannasdev/mcp-writing.git
+/commit/0df673a183f180a16cd5a9490c2829932b4aa744)
+
 #### [v2.12.22](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.12.21...v2.12.22)
 
+> 30 April 2026
+
 - docs(prd): refine reference docs into reference graph model [`#143`](https://github.com/hannasdev/mcp-writing.git
 /pull/143)
+- Release 2.12.22 [`d363c63`](https://github.com/hannasdev/mcp-writing.git
+/commit/d363c63ddcaf6de694f24d9ed66e2f703f439bf4)
 
 #### [v2.12.21](https://github.com/hannasdev/mcp-writing.git
 /compare/v2.12.20...v2.12.21)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "2.12.22",
+  "version": "2.14.0",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "homepage": "https://hannasdev.github.io/mcp-writing/",
   "type": "module",

package/src/core/db.js

@@ -106,7 +106,9 @@ export const SCHEMA = `
     doc_id      TEXT NOT NULL PRIMARY KEY,
     project_id  TEXT,
     universe_id TEXT,
+    type        TEXT,
     title       TEXT NOT NULL,
+    summary     TEXT,
     file_path   TEXT NOT NULL
   );
 
@@ -116,10 +118,26 @@ export const SCHEMA = `
     PRIMARY KEY (doc_id, tag)
   );
 
+  CREATE TABLE IF NOT EXISTS reference_links (
+    source_kind   TEXT NOT NULL,
+    source_project_id TEXT NOT NULL DEFAULT '',
+    source_id     TEXT NOT NULL,
+    target_doc_id TEXT NOT NULL,
+    relation      TEXT NOT NULL,
+    PRIMARY KEY (source_kind, source_project_id, source_id, target_doc_id, relation)
+  );
+
+  CREATE INDEX IF NOT EXISTS idx_reference_links_target_doc_id
+    ON reference_links(target_doc_id);
+
   CREATE VIRTUAL TABLE IF NOT EXISTS scenes_fts USING fts5(
     scene_id, project_id, logline, title, keywords
   );
 
+  CREATE VIRTUAL TABLE IF NOT EXISTS reference_docs_fts USING fts5(
+    doc_id, project_id, title, summary, tags
+  );
+
   CREATE TABLE IF NOT EXISTS schema_version (
     id      INTEGER PRIMARY KEY CHECK (id = 1),
     version INTEGER NOT NULL
@@ -169,6 +187,93 @@ const MIGRATIONS = [
       db.exec(`ALTER TABLE scenes_fts_migrating RENAME TO scenes_fts;`);
     }
   },
+  // 3: add lightweight reference-doc metadata columns and FTS table
+  (db) => {
+    const referenceDocColumns = db.prepare(`PRAGMA table_info(reference_docs)`).all();
+    if (!referenceDocColumns.some(c => c.name === "type")) {
+      db.exec(`ALTER TABLE reference_docs ADD COLUMN type TEXT;`);
+    }
+    if (!referenceDocColumns.some(c => c.name === "summary")) {
+      db.exec(`ALTER TABLE reference_docs ADD COLUMN summary TEXT;`);
+    }
+
+    const ftsSql = db.prepare(`
+      SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'reference_docs_fts'
+    `).get()?.sql;
+    if (typeof ftsSql !== "string") {
+      db.exec(`
+        CREATE VIRTUAL TABLE reference_docs_fts USING fts5(
+          doc_id, project_id, title, summary, tags
+        );
+      `);
+    }
+  },
+  // 4: add explicit reference links table
+  (db) => {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS reference_links (
+        source_kind   TEXT NOT NULL,
+        source_project_id TEXT NOT NULL DEFAULT '',
+        source_id     TEXT NOT NULL,
+        target_doc_id TEXT NOT NULL,
+        relation      TEXT NOT NULL,
+        PRIMARY KEY (source_kind, source_project_id, source_id, target_doc_id, relation)
+      );
+    `);
+
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_reference_links_target_doc_id
+        ON reference_links(target_doc_id);
+    `);
+  },
+  // 5: ensure reference_links has project-scoped source key and target_doc_id index
+  (db) => {
+    const tables = db.prepare(`
+      SELECT name
+      FROM sqlite_master
+      WHERE type = 'table' AND name = 'reference_links'
+    `).all();
+
+    if (tables.length === 0) {
+      db.exec(`
+        CREATE TABLE reference_links (
+          source_kind   TEXT NOT NULL,
+          source_project_id TEXT NOT NULL DEFAULT '',
+          source_id     TEXT NOT NULL,
+          target_doc_id TEXT NOT NULL,
+          relation      TEXT NOT NULL,
+          PRIMARY KEY (source_kind, source_project_id, source_id, target_doc_id, relation)
+        );
+      `);
+    } else {
+      const columns = db.prepare(`PRAGMA table_info(reference_links)`).all();
+      if (!columns.some(c => c.name === "source_project_id")) {
+        db.exec(`
+          CREATE TABLE reference_links_migrating (
+            source_kind   TEXT NOT NULL,
+            source_project_id TEXT NOT NULL DEFAULT '',
+            source_id     TEXT NOT NULL,
+            target_doc_id TEXT NOT NULL,
+            relation      TEXT NOT NULL,
+            PRIMARY KEY (source_kind, source_project_id, source_id, target_doc_id, relation)
+          );
+        `);
+        db.exec(`
+          INSERT OR IGNORE INTO reference_links_migrating
+            (source_kind, source_project_id, source_id, target_doc_id, relation)
+          SELECT source_kind, '', source_id, target_doc_id, relation
+          FROM reference_links;
+        `);
+        db.exec(`DROP TABLE reference_links;`);
+        db.exec(`ALTER TABLE reference_links_migrating RENAME TO reference_links;`);
+      }
+    }
+
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_reference_links_target_doc_id
+        ON reference_links(target_doc_id);
+    `);
+  },
 ];
 
 // The version every database should reach after openDb. Not the current DB value —

package/src/sync/sync.js

@@ -170,6 +170,156 @@ export function isWorldFile(syncDir, filePath) {
   return rel.includes(`${path.sep}world${path.sep}`) || rel.includes("/world/");
 }
 
+export function isReferenceFile(syncDir, filePath) {
+  const rel = path.relative(syncDir, filePath).split(path.sep).join("/").toLowerCase();
+  return rel.startsWith("world/reference/") || rel.includes("/world/reference/") || rel.startsWith("notes/") || rel.includes("/notes/");
+}
+
+export function inferReferenceDocType(syncDir, filePath) {
+  const rel = path.relative(syncDir, filePath).split(path.sep).join("/").toLowerCase();
+  if (rel.startsWith("world/reference/") || rel.includes("/world/reference/")) return "world";
+  if (rel.startsWith("notes/continuity/") || rel.includes("/notes/continuity/")) return "continuity";
+  if (rel.startsWith("notes/research/") || rel.includes("/notes/research/")) return "research";
+  if (rel.startsWith("notes/style/") || rel.includes("/notes/style/")) return "style";
+  return "reference";
+}
+
+function inferReferenceScopeFromSyncDir(syncDir) {
+  const parts = path.resolve(syncDir).split(path.sep).filter(Boolean);
+  const projectSlug = parts.at(-1);
+  const parent = parts.at(-2);
+  const universeId = parts.at(-2);
+  const universeProjectSlug = parts.at(-1);
+  const universeMarker = parts.at(-3);
+
+  if (parent === "projects" && projectSlug) {
+    return { universe_id: null, project_id: projectSlug };
+  }
+
+  if (parent === "universes" && projectSlug) {
+    return { universe_id: projectSlug, project_id: null };
+  }
+
+  if (universeMarker === "universes" && universeId && universeProjectSlug) {
+    return { universe_id: universeId, project_id: `${universeId}/${universeProjectSlug}` };
+  }
+
+  return null;
+}
+
+function inferReferenceProjectAndUniverse(syncDir, filePath) {
+  const rel = path.relative(syncDir, filePath).split(path.sep).join("/").toLowerCase();
+  const scoped = inferReferenceScopeFromSyncDir(syncDir);
+  if (
+    scoped
+    && (rel.startsWith("world/reference/") || rel.startsWith("notes/"))
+  ) {
+    return scoped;
+  }
+
+  return inferProjectAndUniverse(syncDir, filePath);
+}
+
+function slugifyReferencePart(value) {
+  return String(value ?? "")
+    .toLowerCase()
+    .replace(/\.(md|txt)$/i, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function deriveReferenceDocId(syncDir, filePath, meta = {}) {
+  if (typeof meta.doc_id === "string" && meta.doc_id.trim()) return meta.doc_id.trim();
+
+  const rel = path.relative(syncDir, filePath).split(path.sep).join("/");
+  const slug = rel
+    .split("/")
+    .map(slugifyReferencePart)
+    .filter(Boolean)
+    .join("-");
+  return `ref-${slug}`;
+}
+
+export function deriveReferenceTitle(filePath, meta = {}, content = "") {
+  if (typeof meta.title === "string" && meta.title.trim()) return meta.title.trim();
+
+  const heading = content.match(/^\s*#\s+(.+?)\s*$/m)?.[1]?.trim();
+  if (heading) return heading;
+
+  const base = path.basename(filePath, path.extname(filePath));
+  return base
+    .replace(/[-_]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function normalizeReferenceTags(tags) {
+  const values = Array.isArray(tags)
+    ? tags
+    : typeof tags === "string"
+      ? tags.split(",")
+      : [];
+
+  return [...new Set(
+    values
+      .map(tag => String(tag).trim())
+      .filter(Boolean)
+  )];
+}
+
+export function normalizeReferenceIdList(values) {
+  const rawValues = Array.isArray(values)
+    ? values
+    : typeof values === "string"
+      ? values.split(",")
+      : [];
+
+  return [...new Set(
+    rawValues
+      .map(value => String(value).trim())
+      .filter(Boolean)
+  )];
+}
+
+export function deriveReferenceSummary(meta = {}, content = "") {
+  if (typeof meta.summary === "string" && meta.summary.trim()) return meta.summary.trim();
+
+  const body = content
+    .split("\n")
+    .map(line => line.trim())
+    .filter(line => line && !line.startsWith("#"))
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
+
+  if (!body) return null;
+  return body.length <= 240 ? body : `${body.slice(0, 237).trimEnd()}...`;
+}
+
+function indexReferenceLinksForSource(db, {
+  sourceKind,
+  sourceProjectId = "",
+  sourceId,
+  targetDocIds,
+  relation,
+}) {
+  db.prepare(`
+    DELETE FROM reference_links
+    WHERE source_kind = ? AND source_project_id = ? AND source_id = ?
+  `).run(sourceKind, sourceProjectId, sourceId);
+
+  const insertReferenceLink = db.prepare(`
+    INSERT OR IGNORE INTO reference_links
+      (source_kind, source_project_id, source_id, target_doc_id, relation)
+    VALUES (?, ?, ?, ?, ?)
+  `);
+
+  for (const targetDocId of targetDocIds) {
+    if (sourceKind === "reference" && sourceId === targetDocId) continue;
+    insertReferenceLink.run(sourceKind, sourceProjectId, sourceId, targetDocId, relation);
+  }
+}
+
 export function worldEntityKindForPath(syncDir, filePath) {
   const rel = path.relative(syncDir, filePath);
   if (rel.includes(`${path.sep}characters${path.sep}`) || rel.includes("/characters/")) return "character";
@@ -463,8 +613,171 @@ export function indexWorldFile(db, syncDir, file, meta) {
   }
 }
 
+export function indexReferenceFile(db, syncDir, file, meta = {}, content = "") {
+  const { universe_id, project_id } = inferReferenceProjectAndUniverse(syncDir, file);
+  const docId = deriveReferenceDocId(syncDir, file, meta);
+  const type = inferReferenceDocType(syncDir, file);
+  const title = deriveReferenceTitle(file, meta, content);
+  const summary = deriveReferenceSummary(meta, content);
+  const tags = normalizeReferenceTags(meta.tags);
+  const relatedReferenceIds = normalizeReferenceIdList(
+    meta.related_reference_ids ?? meta.related_references ?? meta.related_docs ?? meta.related
+  );
+
+  db.prepare(`
+    INSERT INTO reference_docs (doc_id, project_id, universe_id, type, title, summary, file_path)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT (doc_id) DO UPDATE SET
+      project_id = excluded.project_id,
+      universe_id = excluded.universe_id,
+      type = excluded.type,
+      title = excluded.title,
+      summary = excluded.summary,
+      file_path = excluded.file_path
+  `).run(
+    docId,
+    project_id ?? null,
+    universe_id ?? null,
+    type,
+    title,
+    summary ?? null,
+    file
+  );
+
+  db.prepare(`DELETE FROM reference_doc_tags WHERE doc_id = ?`).run(docId);
+  for (const tag of tags) {
+    db.prepare(`INSERT OR IGNORE INTO reference_doc_tags (doc_id, tag) VALUES (?, ?)`).run(docId, tag);
+  }
+
+  db.prepare(`DELETE FROM reference_docs_fts WHERE doc_id = ?`).run(docId);
+  db.prepare(`
+    INSERT INTO reference_docs_fts (doc_id, project_id, title, summary, tags)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(
+    docId,
+    project_id ?? "",
+    title,
+    summary ?? "",
+    tags.join(" ")
+  );
+
+  indexReferenceLinksForSource(db, {
+    sourceKind: "reference",
+    sourceProjectId: project_id ?? "",
+    sourceId: docId,
+    targetDocIds: relatedReferenceIds,
+    relation: "related",
+  });
+
+  return docId;
+}
+
+function pruneMissingReferenceDocs(db, seenDocIds) {
+  const rows = db.prepare(`SELECT doc_id, project_id FROM reference_docs`).all();
+  for (const row of rows) {
+    if (seenDocIds.has(row.doc_id)) continue;
+    db.prepare(`
+      DELETE FROM reference_links
+      WHERE source_kind = 'reference' AND source_project_id = ? AND source_id = ?
+    `).run(row.project_id ?? "", row.doc_id);
+    db.prepare(`DELETE FROM reference_links WHERE target_doc_id = ?`).run(row.doc_id);
+    db.prepare(`DELETE FROM reference_doc_tags WHERE doc_id = ?`).run(row.doc_id);
+    db.prepare(`DELETE FROM reference_docs_fts WHERE doc_id = ?`).run(row.doc_id);
+    db.prepare(`DELETE FROM reference_docs WHERE doc_id = ?`).run(row.doc_id);
+  }
+}
+
+function canPruneReferenceDocs(syncDir) {
+  const resolvedSyncDir = path.resolve(syncDir);
+  const scopedRoot = inferReferenceScopeFromSyncDir(resolvedSyncDir);
+  if (scopedRoot) return true;
+
+  // Flat project roots and broad workspace roots can safely prune because
+  // they can observe the full set of reference docs in their scope.
+  const hasBroadRootChild = ["projects", "universes", "scenes"].some((name) => {
+    try {
+      return fs.statSync(path.join(resolvedSyncDir, name)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+
+  return hasBroadRootChild;
+}
+
+function inferSceneProjectScopeFromSyncDir(syncDir) {
+  const parts = path.resolve(syncDir).split(path.sep).filter(Boolean);
+  if (parts.length < 2) return null;
+
+  const tail = parts.at(-1);
+  const parent = parts.at(-2);
+
+  if (parent === "projects" && tail) {
+    return tail;
+  }
+
+  if (tail === "scenes" && parts.length >= 3 && parts.at(-3) === "projects") {
+    return parts.at(-2);
+  }
+
+  if (parts.length >= 3 && parts.at(-3) === "universes") {
+    return `${parts.at(-2)}/${parts.at(-1)}`;
+  }
+
+  if (tail === "scenes" && parts.length >= 4 && parts.at(-4) === "universes") {
+    return `${parts.at(-3)}/${parts.at(-2)}`;
+  }
+
+  return null;
+}
+
+function canPruneScenes(syncDir) {
+  const resolvedSyncDir = path.resolve(syncDir);
+
+  if (inferSceneProjectScopeFromSyncDir(resolvedSyncDir)) {
+    return true;
+  }
+
+  const hasBroadRootChild = ["projects", "universes", "scenes"].some((name) => {
+    try {
+      return fs.statSync(path.join(resolvedSyncDir, name)).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+
+  return hasBroadRootChild;
+}
+
+function pruneMissingScenes(db, seenSceneKeys, syncDir) {
+  const projectScope = inferSceneProjectScopeFromSyncDir(syncDir);
+  const rows = projectScope
+    ? db.prepare(`SELECT scene_id, project_id FROM scenes WHERE project_id = ?`).all(projectScope)
+    : db.prepare(`SELECT scene_id, project_id FROM scenes`).all();
+
+  for (const row of rows) {
+    const key = `${row.scene_id}::${row.project_id}`;
+    if (seenSceneKeys.has(key)) continue;
+
+    db.prepare(`DELETE FROM scenes_fts WHERE scene_id = ? AND project_id = ?`).run(row.scene_id, row.project_id);
+    db.prepare(`
+      DELETE FROM reference_links
+      WHERE source_kind = 'scene' AND source_project_id = ? AND source_id = ?
+    `).run(row.project_id ?? "", row.scene_id);
+    db.prepare(`DELETE FROM scenes WHERE scene_id = ? AND project_id = ?`).run(row.scene_id, row.project_id);
+
+    const remainingScene = db.prepare(`SELECT 1 FROM scenes WHERE scene_id = ? LIMIT 1`).get(row.scene_id);
+    if (!remainingScene) {
+      db.prepare(`DELETE FROM scene_characters WHERE scene_id = ?`).run(row.scene_id);
+      db.prepare(`DELETE FROM scene_places WHERE scene_id = ?`).run(row.scene_id);
+      db.prepare(`DELETE FROM scene_tags WHERE scene_id = ?`).run(row.scene_id);
+    }
+  }
+}
+
 export function indexSceneFile(db, syncDir, file, meta, prose) {
   const { universe_id, project_id } = inferProjectAndUniverse(syncDir, file);
+  const referenceIds = normalizeReferenceIdList(meta.reference_ids ?? meta.references);
 
   if (universe_id) {
     db.prepare(`INSERT OR IGNORE INTO universes (universe_id, name) VALUES (?, ?)`).run(
@@ -589,6 +902,14 @@ export function indexSceneFile(db, syncDir, file, meta, prose) {
     keywordTokens,
   );
 
+  indexReferenceLinksForSource(db, {
+    sourceKind: "scene",
+    sourceProjectId: project_id ?? "",
+    sourceId: meta.scene_id,
+    targetDocIds: referenceIds,
+    relation: "informs",
+  });
+
   return { isStale };
 }
 
@@ -638,7 +959,10 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
   let skipped = 0;
   let sidecarsMigrated = 0;
   const seenSceneIds = new Map(); // scene_id+project_id → file path, for duplicate detection
+  const seenSceneKeys = new Set();
   const indexedSceneIds = new Set(); // scene_id only — for orphaned sidecar move detection
+  const indexedReferenceDocIds = new Set();
+  let sceneIndexFailures = 0;
   const warnings = [];
 
   const scanFiles = [];
@@ -650,9 +974,20 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
     scanFiles.push(file);
   }
 
-  // --- Pass 1: world files (characters/places must be indexed before scenes
-  // so that character name → ID resolution in scene_characters works) ---
+  // --- Pass 1: world files and reference docs (characters/places must be indexed
+  // before scenes so that character name -> ID resolution in scene_characters works) ---
   for (const file of scanFiles) {
+    if (isReferenceFile(syncDir, file)) {
+      try {
+        const { data, content } = parseFile(file);
+        const docId = indexReferenceFile(db, syncDir, file, data, content);
+        indexedReferenceDocIds.add(docId);
+      } catch (err) {
+        process.stderr.write(`[mcp-writing] Failed to index ${file}: ${err.message}\n`);
+      }
+      continue;
+    }
+
     if (!isWorldFile(syncDir, file)) continue;
     try {
       const { meta } = readMeta(file, syncDir, { writable });
@@ -667,9 +1002,13 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
     }
   }
 
+  if (canPruneReferenceDocs(syncDir)) {
+    pruneMissingReferenceDocs(db, indexedReferenceDocIds);
+  }
+
   // --- Pass 2: scene files ---
   for (const file of scanFiles) {
-    if (isWorldFile(syncDir, file)) continue;
+    if (isWorldFile(syncDir, file) || isReferenceFile(syncDir, file)) continue;
     try {
       const { meta, sourceMeta, sidecarGenerated, derived, mismatches } = readMeta(file, syncDir, { writable });
       if (sidecarGenerated) sidecarsMigrated++;
@@ -692,6 +1031,7 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
       } else {
         seenSceneIds.set(key, file);
       }
+      seenSceneKeys.add(key);
 
       if (mismatches.part || mismatches.chapter) {
         const details = [];
@@ -708,10 +1048,15 @@ export function syncAll(db, syncDir, { quiet = false, writable = false } = {}) {
       if (isStale) staleMarked++;
       indexed++;
     } catch (err) {
+      sceneIndexFailures++;
       process.stderr.write(`[mcp-writing] Failed to index ${file}: ${err.message}\n`);
     }
   }
 
+  if (canPruneScenes(syncDir) && sceneIndexFailures === 0) {
+    pruneMissingScenes(db, seenSceneKeys, syncDir);
+  }
+
   // --- Orphaned sidecar detection ---
   const sidecars = walkSidecars(syncDir).filter(sidecar => !isNestedMirrorPath(syncDir, sidecar));
   for (const sidecar of sidecars) {

package/src/tools/search.js

@@ -424,6 +424,67 @@ export function registerSearchTools(s, {
     }
   );
 
+  // ---- search_reference ----------------------------------------------------
+  s.tool(
+    "search_reference",
+    "Full-text search across indexed reference document titles, summaries, and tags. Use this to discover world-building notes, continuity references, research docs, and other reference material without loading full file contents.",
+    {
+      query: z.string().describe("Search terms (e.g. 'vampirism' or 'blood replacement'). FTS5 syntax supported."),
+      type: z.string().optional().describe("Optional reference type filter (for example: 'world', 'continuity', 'research', 'style')."),
+      tag: z.string().optional().describe("Optional exact tag filter."),
+    },
+    async ({ query, type, tag }) => {
+      let matchRows;
+      try {
+        matchRows = db.prepare(`
+          SELECT doc_id, rank
+          FROM reference_docs_fts
+          WHERE reference_docs_fts MATCH ?
+          ORDER BY rank
+        `).all(query);
+      } catch (err) {
+        return errorResponse("INVALID_QUERY", "Invalid reference search query syntax. Use plain keywords or quoted phrases.", { detail: err.message });
+      }
+
+      if (matchRows.length === 0) {
+        return errorResponse("NO_RESULTS", "No reference documents matched the search query.");
+      }
+
+      const rows = [];
+      const docStmt = db.prepare(`
+        SELECT doc_id, project_id, universe_id, type, title, summary, file_path
+        FROM reference_docs
+        WHERE doc_id = ?
+      `);
+      const tagsStmt = db.prepare(`
+        SELECT tag
+        FROM reference_doc_tags
+        WHERE doc_id = ?
+        ORDER BY tag
+      `);
+
+      for (const match of matchRows) {
+        const doc = docStmt.get(match.doc_id);
+        if (!doc) continue;
+
+        const tags = tagsStmt.all(match.doc_id).map(row => row.tag);
+        if (type && doc.type !== type) continue;
+        if (tag && !tags.includes(tag)) continue;
+
+        rows.push({
+          ...doc,
+          tags,
+        });
+      }
+
+      if (rows.length === 0) {
+        return errorResponse("NO_RESULTS", "No reference documents matched the provided filters.");
+      }
+
+      return { content: [{ type: "text", text: JSON.stringify(rows, null, 2) }] };
+    }
+  );
+
   // ---- list_threads --------------------------------------------------------
   s.tool(
     "list_threads",