@systemdox/mcp-server 0.1.50 → 0.1.52

package/dist/http.js

@@ -466,6 +466,9 @@ function fenceFor(text3) {
   const longest = Math.max(0, ...(text3.match(/`+/g) ?? []).map((r) => r.length));
   return "`".repeat(Math.max(3, longest + 1));
 }
+function afterInstall(skillMd) {
+  return `No restart is needed: a running Claude Code session picks it up. If one does not list it yet, read ${skillMd} and follow it, or run /reload-skills.`;
+}
 function describeInstall(name, r) {
   const lines = [
     `Installed ${name} version ${r.version} into ${r.dest} (${r.written.length} file(s)).`
@@ -475,7 +478,7 @@ function describeInstall(name, r) {
     lines.push(`Kept, edited here and no longer in the skill: ${r.keptEdited.join(", ")}`);
   }
   if (r.keptUntracked.length) lines.push(`Kept, added here: ${r.keptUntracked.join(", ")}`);
-  lines.push("Start a new Claude Code session to load it.");
+  lines.push(afterInstall(join(r.dest, "SKILL.md")));
   return lines.join("\n");
 }
 
@@ -848,6 +851,17 @@ ${text3}`
 
 // src/tools/get-specs.ts
 import { z as z2 } from "zod";
+
+// src/lib/spec-label.ts
+var DECISION_PREFIX = "ADR: ";
+function isDecisionDraft(name) {
+  return name.startsWith(DECISION_PREFIX);
+}
+function specLabel(spec) {
+  return isDecisionDraft(spec.name) ? "decision record" : `${spec.requirementCount} requirements`;
+}
+
+// src/tools/get-specs.ts
 function registerGetSpecs(server, apiClient) {
   server.registerTool(
     "get_specs",
@@ -912,7 +926,7 @@ ${spec.taskContent}`);
         };
       }
       const text3 = filtered.map(
-        (s) => `- **${s.name}** (${s.draftId}) \u2014 ${s.status}, ${s.requirementCount} requirements` + (s.repoFullName ? `, repo: ${s.repoFullName}` : "")
+        (s) => `- **${s.name}** (${s.draftId}) \u2014 ${s.status}, ${specLabel(s)}` + (s.repoFullName ? `, repo: ${s.repoFullName}` : "")
       ).join("\n");
       return {
         content: [
@@ -930,6 +944,11 @@ ${text3}`
 
 // src/tools/get-docs.ts
 import { z as z3 } from "zod";
+var PATH_FILTER_LIMIT = "1000";
+function literalPrefix(pattern) {
+  const wildcard = pattern.indexOf("*");
+  return wildcard < 0 ? pattern : pattern.slice(0, wildcard);
+}
 function matchGlob(path, pattern) {
   const regex = pattern.replace(/\./g, "\\.").replace(/\*\*/g, "{{GLOBSTAR}}").replace(/\*/g, "[^/]*").replace(/\{\{GLOBSTAR\}\}/g, ".*");
   return new RegExp(`^${regex}$`).test(path);
@@ -990,11 +1009,17 @@ ${doc.content}`;
       const params = {};
       if (repo) params.repo = repo;
       if (search) params.q = search;
+      if (path) {
+        params.limit = PATH_FILTER_LIMIT;
+        const prefix = literalPrefix(path);
+        if (prefix) params.pathPrefix = prefix;
+      }
       const response = await apiClient.get(
         "/v1/docs",
         params
       );
       let items = response.items;
+      const unread = path ? response.total - response.items.length : 0;
       if (path) {
         items = items.filter((item) => matchGlob(item.path, path));
       }
@@ -1024,7 +1049,9 @@ ${doc.content}`;
 
 ${text3}
 
-Use doc_id for full content, or doc_id + section to fetch one section.`
+` + (unread > 0 ? `${unread} more were not read. Start the path with a folder to narrow it.
+
+` : "") + "Use doc_id for full content, or doc_id + section to fetch one section."
           }
         ]
       };
@@ -1125,7 +1152,9 @@ ${deps}`);
       }
       if (ctx.adrs.length > 0) {
         const adrs = ctx.adrs.map((a) => `- ${a.title}${a.repo ? ` (${a.repo})` : ""}`).join("\n");
-        sections.push(`## Architecture Decision Records (${ctx.adrs.length})
+        const total = ctx.adrTotal ?? ctx.adrs.length;
+        const count = total > ctx.adrs.length ? `${ctx.adrs.length} newest of ${total}` : `${ctx.adrs.length}`;
+        sections.push(`## Architecture Decision Records (${count})
 
 ${adrs}`);
       }
@@ -1497,6 +1526,9 @@ var SEVERITY_SCORES = {
   medium: 0.5,
   low: 0.25
 };
+var MIN_TITLE_SHARE = 1 / 3;
+var RECORD_PATH = /(^|\/)changelog\//;
+var RECORD_FACTOR = 0.5;
 var CHARS_PER_TOKEN = 4;
 function estimateTokens(text3) {
   return Math.ceil(text3.length / CHARS_PER_TOKEN);
@@ -1549,6 +1581,32 @@ function scoreSeverity(item) {
   if (!item.severity) return 0.5;
   return SEVERITY_SCORES[item.severity] ?? 0.5;
 }
+function stem(word) {
+  return word.length > 3 ? word.replace(/s$/, "") : word;
+}
+function stems(text3) {
+  return new Set(
+    text3.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).map(stem)
+  );
+}
+function titleShare(title, keywords) {
+  const wanted = stems(keywords.join(" "));
+  if (wanted.size === 0) return 0;
+  const held = stems(title);
+  let matches = 0;
+  for (const word of wanted) {
+    if (held.has(word)) matches++;
+  }
+  return matches / wanted.size;
+}
+function scoreReference(item, keywords) {
+  const share = titleShare(item.title, keywords);
+  const score = Math.max(
+    item.relevance ?? 0,
+    share >= MIN_TITLE_SHARE ? share : 0
+  );
+  return RECORD_PATH.test(item.path ?? "") ? score * RECORD_FACTOR : score;
+}
 function extractKeywords(text3) {
   const stopWords = /* @__PURE__ */ new Set([
     "the",
@@ -1645,7 +1703,8 @@ function scoreItems(items, taskDescription, filePaths) {
     const keywordScore = scoreKeywordMatch(item, keywords);
     const recencyScore = scoreRecency(item);
     const severityScore = scoreSeverity(item);
-    const score = pathScore * WEIGHT_PATH + keywordScore * WEIGHT_KEYWORD + recencyScore * WEIGHT_RECENCY + severityScore * WEIGHT_SEVERITY;
+    const isReference = item.type === "spec" || item.type === "doc";
+    const score = isReference && keywords.length > 0 ? scoreReference(item, keywords) : pathScore * WEIGHT_PATH + keywordScore * WEIGHT_KEYWORD + recencyScore * WEIGHT_RECENCY + severityScore * WEIGHT_SEVERITY;
     return {
       type: item.type,
       id: item.id,
@@ -1654,7 +1713,7 @@ function scoreItems(items, taskDescription, filePaths) {
       score,
       tokenEstimate: estimateTokens(item.content)
     };
-  }).sort((a, b) => b.score - a.score);
+  }).filter((item) => item.score > 0).sort((a, b) => b.score - a.score);
 }
 function selectWithinBudget(items, maxTokens) {
   const selected = [];
@@ -1676,6 +1735,10 @@ var MAX_HYDRATED = 8;
 var MAX_TAIL = 10;
 var TAIL_SHARE = 0.15;
 var TRUNCATION_NOTICE_TOKENS = 30;
+var STACK_SHARE = 0.1;
+var MIN_REFERENCES = 3;
+var SEARCH_RESULTS = 30;
+var MAX_QUERY_CHARS = 300;
 function formatGuardrail(g) {
   let text3 = `## ${g.title} [${g.severity}]
 
@@ -1694,7 +1757,7 @@ ${g.fix}
 }
 function formatSpecHeadline(s) {
   return `### ${s.name}
-\`draft_id: ${s.draftId}\` \xB7 ${s.status} \xB7 ${s.requirementCount} requirements`;
+\`draft_id: ${s.draftId}\` \xB7 ${s.status} \xB7 ${specLabel(s)}`;
 }
 function formatDocHeadline(d) {
   return `### ${d.title}
@@ -1705,6 +1768,21 @@ function formatStack(entries2) {
     (e) => `- ${e.name}${e.version ? ` v${e.version}` : ""}${e.notes ? ` \u2014 ${e.notes}` : ""}`
   ).join("\n");
 }
+function selectStack(entries2, words, maxTokens) {
+  const named = (e) => {
+    const entry = `${e.name} ${e.notes ?? ""}`.toLowerCase();
+    return words.some((w) => entry.includes(w));
+  };
+  const ordered = [...entries2.filter(named), ...entries2.filter((e) => !named(e))];
+  const shown = [];
+  for (const entry of ordered) {
+    if (shown.length > 0 && estimateTokens(formatStack([...shown, entry])) > maxTokens) {
+      break;
+    }
+    shown.push(entry);
+  }
+  return { text: formatStack(shown), hidden: entries2.length - shown.length };
+}
 function formatRules(rules) {
   const byCategory = /* @__PURE__ */ new Map();
   for (const r of rules) {
@@ -1726,6 +1804,21 @@ function formatRules(rules) {
 
 ${text3.trim()}`;
 }
+async function findDocs(api, taskDescription) {
+  const query = taskDescription.trim().slice(0, MAX_QUERY_CHARS);
+  if (query) {
+    try {
+      const found = await api.get("/v1/docs", {
+        q: query,
+        limit: String(SEARCH_RESULTS)
+      });
+      if (found.items.length > 0) return { ...found, searched: true };
+    } catch {
+    }
+  }
+  const listed = await api.get("/v1/docs");
+  return { ...listed, searched: false };
+}
 async function fetchSpecBody(api, draftId) {
   const spec = await api.get(
     `/v1/specs/${encodeURIComponent(draftId)}`
@@ -1826,7 +1919,9 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
   const [rawGuardrails, rawSpecs, docs, stack, rules, docRepos] = await Promise.all([
     api.get("/v1/guardrails").catch(orEmpty([])),
     api.get("/v1/specs").catch(orEmpty([])),
-    api.get("/v1/docs").catch(orEmpty({ items: [] })),
+    findDocs(api, taskDescription).catch(
+      orEmpty({ items: [], searched: false })
+    ),
     api.get("/v1/ai/settings/stack").catch(orEmpty([])),
     api.get("/v1/standards/rules").catch(orEmpty([])),
     // Capability states — FAIL-OPEN: an unreadable config (older backend, a
@@ -1839,6 +1934,8 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
   const specs = disabled("requirements") && disabled("design") && disabled("specs") ? [] : rawSpecs;
   const refs = /* @__PURE__ */ new Map();
   const key = (type, id) => `${type}:${id}`;
+  const docTitles = new Set(docs.items.map((d) => d.title));
+  const isCopyOfDoc = (s) => isDecisionDraft(s.name) && docTitles.has(s.name.slice("ADR: ".length));
   const scorable = [
     ...guardrails.map((g) => ({
       type: "guardrail",
@@ -1849,12 +1946,12 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
       severity: g.severity,
       updatedAt: g.updatedAt
     })),
-    ...specs.filter((s) => s.status !== "archived").map((s) => {
+    ...specs.filter((s) => s.status !== "archived" && !isCopyOfDoc(s)).map((s) => {
       refs.set(key("spec", s.draftId), {
         type: "spec",
         id: s.draftId,
         title: s.name,
-        listLine: `- **${s.name}** \u2014 \`draft_id: ${s.draftId}\` (${s.status}, ${s.requirementCount} requirements)`,
+        listLine: `- **${s.name}** \u2014 \`draft_id: ${s.draftId}\` (${s.status}, ${specLabel(s)})`,
         fetchHint: `get_specs(draft_id="${s.draftId}")`
       });
       return {
@@ -1865,7 +1962,7 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
         updatedAt: s.updatedAt
       };
     }),
-    ...docs.items.map((d) => {
+    ...docs.items.map((d, position) => {
       const section = selectSection(d.outline, taskDescription);
       const pointer = section ? formatSectionPointer(d.repo_full_name, d.path, section) : void 0;
       refs.set(key("doc", d.id), {
@@ -1884,7 +1981,9 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
         title: d.title,
         content: formatDocHeadline(d),
         category: d.doc_type === "adr" ? "architecture" : void 0,
-        updatedAt: d.synced_at
+        updatedAt: d.synced_at,
+        path: d.path,
+        relevance: docs.searched ? 1 - position / (2 * docs.items.length) : void 0
       };
     })
   ];
@@ -1892,9 +1991,16 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
   const sections = [];
   let overhead = 0;
   if (stack.length > 0) {
+    const { text: text3, hidden } = selectStack(
+      stack,
+      [...extractKeywords(taskDescription), ...detectLanguages(filePaths)],
+      Math.floor(budget * STACK_SHARE)
+    );
     const section = `## Tech Stack
 
-${formatStack(stack)}`;
+${text3}` + (hidden > 0 ? `
+
+_${hidden} more with \`get_tech_stack\`._` : "");
     sections.push(section);
     overhead += estimateTokens(section);
   }
@@ -2013,9 +2119,10 @@ _Highest-ranked items \u2014 docs are scoped to their most relevant section. Eac
   const tailLines = [];
   for (const meta of tailCandidates) {
     const cost = estimateTokens(meta.listLine);
-    if (cost > remaining) break;
+    const named = blocks.length + tailLines.length;
+    if (cost > remaining && named >= MIN_REFERENCES) break;
     tailLines.push(meta.listLine);
-    remaining -= cost;
+    remaining = Math.max(0, remaining - cost);
   }
   if (tailLines.length > 0) {
     sections.push(
@@ -2841,7 +2948,7 @@ ${fence}
 ${f.content}${f.content.endsWith("\n") ? "" : "\n"}${fence}`;
       }).join("\n\n");
       return text(
-        `Skill **${version.name}** version ${version.version}: write these ${version.files.length} file(s) into ${dest}/ exactly as shown (the content between the fences), creating folders as needed. If a file there differs from ${MANIFEST_FILE}'s hash for it, it was edited: ask before replacing it. Then write ${MANIFEST_FILE} with this content, and tell the user to start a new Claude Code session.
+        `Skill **${version.name}** version ${version.version}: write these ${version.files.length} file(s) into ${dest}/ exactly as shown (the content between the fences), creating folders as needed. If a file there differs from ${MANIFEST_FILE}'s hash for it, it was edited: ask before replacing it. Then write ${MANIFEST_FILE} with this content. ${afterInstall(`${dest}/SKILL.md`)}
 
 ### ${MANIFEST_FILE}
 
@@ -2998,9 +3105,9 @@ function localDate(now) {
   return `${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())}`;
 }
 function conflictCopyName(path, date, taken) {
-  const stem = path.replace(/\.md$/, "");
+  const stem2 = path.replace(/\.md$/, "");
   for (let n = 1; ; n++) {
-    const name = `${stem}.local-${date}${n === 1 ? "" : `-${n}`}.md`;
+    const name = `${stem2}.local-${date}${n === 1 ? "" : `-${n}`}.md`;
     if (!taken.has(name.toLowerCase())) return name;
   }
 }
@@ -3887,7 +3994,7 @@ function registerTeamSetupTools(server, apiClient, { localFiles }) {
 }
 
 // src/server.ts
-var SERVER_VERSION = true ? "0.1.50" : "0.0.0-dev";
+var SERVER_VERSION = true ? "0.1.52" : "0.0.0-dev";
 function createServer(apiClient, { localFiles = false, instructions, keyProblem } = {}) {
   const server = new McpServer(
     {

package/dist/index.js

@@ -447,6 +447,9 @@ function fenceFor(text3) {
   const longest = Math.max(0, ...(text3.match(/`+/g) ?? []).map((r) => r.length));
   return "`".repeat(Math.max(3, longest + 1));
 }
+function afterInstall(skillMd) {
+  return `No restart is needed: a running Claude Code session picks it up. If one does not list it yet, read ${skillMd} and follow it, or run /reload-skills.`;
+}
 function describeInstall(name, r) {
   const lines = [
     `Installed ${name} version ${r.version} into ${r.dest} (${r.written.length} file(s)).`
@@ -456,7 +459,7 @@ function describeInstall(name, r) {
     lines.push(`Kept, edited here and no longer in the skill: ${r.keptEdited.join(", ")}`);
   }
   if (r.keptUntracked.length) lines.push(`Kept, added here: ${r.keptUntracked.join(", ")}`);
-  lines.push("Start a new Claude Code session to load it.");
+  lines.push(afterInstall(join(r.dest, "SKILL.md")));
   return lines.join("\n");
 }
 
@@ -867,6 +870,17 @@ ${text3}`
 
 // src/tools/get-specs.ts
 import { z as z2 } from "zod";
+
+// src/lib/spec-label.ts
+var DECISION_PREFIX = "ADR: ";
+function isDecisionDraft(name) {
+  return name.startsWith(DECISION_PREFIX);
+}
+function specLabel(spec) {
+  return isDecisionDraft(spec.name) ? "decision record" : `${spec.requirementCount} requirements`;
+}
+
+// src/tools/get-specs.ts
 function registerGetSpecs(server, apiClient2) {
   server.registerTool(
     "get_specs",
@@ -931,7 +945,7 @@ ${spec.taskContent}`);
         };
       }
       const text3 = filtered.map(
-        (s) => `- **${s.name}** (${s.draftId}) \u2014 ${s.status}, ${s.requirementCount} requirements` + (s.repoFullName ? `, repo: ${s.repoFullName}` : "")
+        (s) => `- **${s.name}** (${s.draftId}) \u2014 ${s.status}, ${specLabel(s)}` + (s.repoFullName ? `, repo: ${s.repoFullName}` : "")
       ).join("\n");
       return {
         content: [
@@ -949,6 +963,11 @@ ${text3}`
 
 // src/tools/get-docs.ts
 import { z as z3 } from "zod";
+var PATH_FILTER_LIMIT = "1000";
+function literalPrefix(pattern) {
+  const wildcard = pattern.indexOf("*");
+  return wildcard < 0 ? pattern : pattern.slice(0, wildcard);
+}
 function matchGlob(path, pattern) {
   const regex = pattern.replace(/\./g, "\\.").replace(/\*\*/g, "{{GLOBSTAR}}").replace(/\*/g, "[^/]*").replace(/\{\{GLOBSTAR\}\}/g, ".*");
   return new RegExp(`^${regex}$`).test(path);
@@ -1009,11 +1028,17 @@ ${doc.content}`;
       const params = {};
       if (repo) params.repo = repo;
       if (search) params.q = search;
+      if (path) {
+        params.limit = PATH_FILTER_LIMIT;
+        const prefix = literalPrefix(path);
+        if (prefix) params.pathPrefix = prefix;
+      }
       const response = await apiClient2.get(
         "/v1/docs",
         params
       );
       let items = response.items;
+      const unread = path ? response.total - response.items.length : 0;
       if (path) {
         items = items.filter((item) => matchGlob(item.path, path));
       }
@@ -1043,7 +1068,9 @@ ${doc.content}`;
 
 ${text3}
 
-Use doc_id for full content, or doc_id + section to fetch one section.`
+` + (unread > 0 ? `${unread} more were not read. Start the path with a folder to narrow it.
+
+` : "") + "Use doc_id for full content, or doc_id + section to fetch one section."
           }
         ]
       };
@@ -1144,7 +1171,9 @@ ${deps}`);
       }
       if (ctx.adrs.length > 0) {
         const adrs = ctx.adrs.map((a) => `- ${a.title}${a.repo ? ` (${a.repo})` : ""}`).join("\n");
-        sections.push(`## Architecture Decision Records (${ctx.adrs.length})
+        const total = ctx.adrTotal ?? ctx.adrs.length;
+        const count = total > ctx.adrs.length ? `${ctx.adrs.length} newest of ${total}` : `${ctx.adrs.length}`;
+        sections.push(`## Architecture Decision Records (${count})
 
 ${adrs}`);
       }
@@ -1516,6 +1545,9 @@ var SEVERITY_SCORES = {
   medium: 0.5,
   low: 0.25
 };
+var MIN_TITLE_SHARE = 1 / 3;
+var RECORD_PATH = /(^|\/)changelog\//;
+var RECORD_FACTOR = 0.5;
 var CHARS_PER_TOKEN = 4;
 function estimateTokens(text3) {
   return Math.ceil(text3.length / CHARS_PER_TOKEN);
@@ -1568,6 +1600,32 @@ function scoreSeverity(item) {
   if (!item.severity) return 0.5;
   return SEVERITY_SCORES[item.severity] ?? 0.5;
 }
+function stem(word) {
+  return word.length > 3 ? word.replace(/s$/, "") : word;
+}
+function stems(text3) {
+  return new Set(
+    text3.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean).map(stem)
+  );
+}
+function titleShare(title, keywords) {
+  const wanted = stems(keywords.join(" "));
+  if (wanted.size === 0) return 0;
+  const held = stems(title);
+  let matches = 0;
+  for (const word of wanted) {
+    if (held.has(word)) matches++;
+  }
+  return matches / wanted.size;
+}
+function scoreReference(item, keywords) {
+  const share = titleShare(item.title, keywords);
+  const score = Math.max(
+    item.relevance ?? 0,
+    share >= MIN_TITLE_SHARE ? share : 0
+  );
+  return RECORD_PATH.test(item.path ?? "") ? score * RECORD_FACTOR : score;
+}
 function extractKeywords(text3) {
   const stopWords = /* @__PURE__ */ new Set([
     "the",
@@ -1664,7 +1722,8 @@ function scoreItems(items, taskDescription, filePaths) {
     const keywordScore = scoreKeywordMatch(item, keywords);
     const recencyScore = scoreRecency(item);
     const severityScore = scoreSeverity(item);
-    const score = pathScore * WEIGHT_PATH + keywordScore * WEIGHT_KEYWORD + recencyScore * WEIGHT_RECENCY + severityScore * WEIGHT_SEVERITY;
+    const isReference = item.type === "spec" || item.type === "doc";
+    const score = isReference && keywords.length > 0 ? scoreReference(item, keywords) : pathScore * WEIGHT_PATH + keywordScore * WEIGHT_KEYWORD + recencyScore * WEIGHT_RECENCY + severityScore * WEIGHT_SEVERITY;
     return {
       type: item.type,
       id: item.id,
@@ -1673,7 +1732,7 @@ function scoreItems(items, taskDescription, filePaths) {
       score,
       tokenEstimate: estimateTokens(item.content)
     };
-  }).sort((a, b) => b.score - a.score);
+  }).filter((item) => item.score > 0).sort((a, b) => b.score - a.score);
 }
 function selectWithinBudget(items, maxTokens) {
   const selected = [];
@@ -1695,6 +1754,10 @@ var MAX_HYDRATED = 8;
 var MAX_TAIL = 10;
 var TAIL_SHARE = 0.15;
 var TRUNCATION_NOTICE_TOKENS = 30;
+var STACK_SHARE = 0.1;
+var MIN_REFERENCES = 3;
+var SEARCH_RESULTS = 30;
+var MAX_QUERY_CHARS = 300;
 function formatGuardrail(g) {
   let text3 = `## ${g.title} [${g.severity}]
 
@@ -1713,7 +1776,7 @@ ${g.fix}
 }
 function formatSpecHeadline(s) {
   return `### ${s.name}
-\`draft_id: ${s.draftId}\` \xB7 ${s.status} \xB7 ${s.requirementCount} requirements`;
+\`draft_id: ${s.draftId}\` \xB7 ${s.status} \xB7 ${specLabel(s)}`;
 }
 function formatDocHeadline(d) {
   return `### ${d.title}
@@ -1724,6 +1787,21 @@ function formatStack(entries2) {
     (e) => `- ${e.name}${e.version ? ` v${e.version}` : ""}${e.notes ? ` \u2014 ${e.notes}` : ""}`
   ).join("\n");
 }
+function selectStack(entries2, words, maxTokens) {
+  const named = (e) => {
+    const entry = `${e.name} ${e.notes ?? ""}`.toLowerCase();
+    return words.some((w) => entry.includes(w));
+  };
+  const ordered = [...entries2.filter(named), ...entries2.filter((e) => !named(e))];
+  const shown = [];
+  for (const entry of ordered) {
+    if (shown.length > 0 && estimateTokens(formatStack([...shown, entry])) > maxTokens) {
+      break;
+    }
+    shown.push(entry);
+  }
+  return { text: formatStack(shown), hidden: entries2.length - shown.length };
+}
 function formatRules(rules) {
   const byCategory = /* @__PURE__ */ new Map();
   for (const r of rules) {
@@ -1745,6 +1823,21 @@ function formatRules(rules) {
 
 ${text3.trim()}`;
 }
+async function findDocs(api, taskDescription) {
+  const query = taskDescription.trim().slice(0, MAX_QUERY_CHARS);
+  if (query) {
+    try {
+      const found = await api.get("/v1/docs", {
+        q: query,
+        limit: String(SEARCH_RESULTS)
+      });
+      if (found.items.length > 0) return { ...found, searched: true };
+    } catch {
+    }
+  }
+  const listed = await api.get("/v1/docs");
+  return { ...listed, searched: false };
+}
 async function fetchSpecBody(api, draftId) {
   const spec = await api.get(
     `/v1/specs/${encodeURIComponent(draftId)}`
@@ -1845,7 +1938,9 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
   const [rawGuardrails, rawSpecs, docs, stack, rules, docRepos] = await Promise.all([
     api.get("/v1/guardrails").catch(orEmpty([])),
     api.get("/v1/specs").catch(orEmpty([])),
-    api.get("/v1/docs").catch(orEmpty({ items: [] })),
+    findDocs(api, taskDescription).catch(
+      orEmpty({ items: [], searched: false })
+    ),
     api.get("/v1/ai/settings/stack").catch(orEmpty([])),
     api.get("/v1/standards/rules").catch(orEmpty([])),
     // Capability states — FAIL-OPEN: an unreadable config (older backend, a
@@ -1858,6 +1953,8 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
   const specs = disabled("requirements") && disabled("design") && disabled("specs") ? [] : rawSpecs;
   const refs = /* @__PURE__ */ new Map();
   const key = (type, id) => `${type}:${id}`;
+  const docTitles = new Set(docs.items.map((d) => d.title));
+  const isCopyOfDoc = (s) => isDecisionDraft(s.name) && docTitles.has(s.name.slice("ADR: ".length));
   const scorable = [
     ...guardrails.map((g) => ({
       type: "guardrail",
@@ -1868,12 +1965,12 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
       severity: g.severity,
       updatedAt: g.updatedAt
     })),
-    ...specs.filter((s) => s.status !== "archived").map((s) => {
+    ...specs.filter((s) => s.status !== "archived" && !isCopyOfDoc(s)).map((s) => {
       refs.set(key("spec", s.draftId), {
         type: "spec",
         id: s.draftId,
         title: s.name,
-        listLine: `- **${s.name}** \u2014 \`draft_id: ${s.draftId}\` (${s.status}, ${s.requirementCount} requirements)`,
+        listLine: `- **${s.name}** \u2014 \`draft_id: ${s.draftId}\` (${s.status}, ${specLabel(s)})`,
         fetchHint: `get_specs(draft_id="${s.draftId}")`
       });
       return {
@@ -1884,7 +1981,7 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
         updatedAt: s.updatedAt
       };
     }),
-    ...docs.items.map((d) => {
+    ...docs.items.map((d, position) => {
       const section = selectSection(d.outline, taskDescription);
       const pointer = section ? formatSectionPointer(d.repo_full_name, d.path, section) : void 0;
       refs.set(key("doc", d.id), {
@@ -1903,7 +2000,9 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
         title: d.title,
         content: formatDocHeadline(d),
         category: d.doc_type === "adr" ? "architecture" : void 0,
-        updatedAt: d.synced_at
+        updatedAt: d.synced_at,
+        path: d.path,
+        relevance: docs.searched ? 1 - position / (2 * docs.items.length) : void 0
       };
     })
   ];
@@ -1911,9 +2010,16 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
   const sections = [];
   let overhead = 0;
   if (stack.length > 0) {
+    const { text: text3, hidden } = selectStack(
+      stack,
+      [...extractKeywords(taskDescription), ...detectLanguages(filePaths)],
+      Math.floor(budget * STACK_SHARE)
+    );
     const section = `## Tech Stack
 
-${formatStack(stack)}`;
+${text3}` + (hidden > 0 ? `
+
+_${hidden} more with \`get_tech_stack\`._` : "");
     sections.push(section);
     overhead += estimateTokens(section);
   }
@@ -2032,9 +2138,10 @@ _Highest-ranked items \u2014 docs are scoped to their most relevant section. Eac
   const tailLines = [];
   for (const meta of tailCandidates) {
     const cost = estimateTokens(meta.listLine);
-    if (cost > remaining) break;
+    const named = blocks.length + tailLines.length;
+    if (cost > remaining && named >= MIN_REFERENCES) break;
     tailLines.push(meta.listLine);
-    remaining -= cost;
+    remaining = Math.max(0, remaining - cost);
   }
   if (tailLines.length > 0) {
     sections.push(
@@ -2860,7 +2967,7 @@ ${fence}
 ${f.content}${f.content.endsWith("\n") ? "" : "\n"}${fence}`;
       }).join("\n\n");
       return text(
-        `Skill **${version.name}** version ${version.version}: write these ${version.files.length} file(s) into ${dest}/ exactly as shown (the content between the fences), creating folders as needed. If a file there differs from ${MANIFEST_FILE}'s hash for it, it was edited: ask before replacing it. Then write ${MANIFEST_FILE} with this content, and tell the user to start a new Claude Code session.
+        `Skill **${version.name}** version ${version.version}: write these ${version.files.length} file(s) into ${dest}/ exactly as shown (the content between the fences), creating folders as needed. If a file there differs from ${MANIFEST_FILE}'s hash for it, it was edited: ask before replacing it. Then write ${MANIFEST_FILE} with this content. ${afterInstall(`${dest}/SKILL.md`)}
 
 ### ${MANIFEST_FILE}
 
@@ -3017,9 +3124,9 @@ function localDate(now) {
   return `${now.getFullYear()}-${p(now.getMonth() + 1)}-${p(now.getDate())}`;
 }
 function conflictCopyName(path, date, taken) {
-  const stem = path.replace(/\.md$/, "");
+  const stem2 = path.replace(/\.md$/, "");
   for (let n = 1; ; n++) {
-    const name = `${stem}.local-${date}${n === 1 ? "" : `-${n}`}.md`;
+    const name = `${stem2}.local-${date}${n === 1 ? "" : `-${n}`}.md`;
     if (!taken.has(name.toLowerCase())) return name;
   }
 }
@@ -3906,7 +4013,7 @@ function registerTeamSetupTools(server, apiClient2, { localFiles }) {
 }
 
 // src/server.ts
-var SERVER_VERSION = true ? "0.1.50" : "0.0.0-dev";
+var SERVER_VERSION = true ? "0.1.52" : "0.0.0-dev";
 function createServer(apiClient2, { localFiles = false, instructions, keyProblem: keyProblem2 } = {}) {
   const server = new McpServer(
     {

package/dist/install-skill.js

@@ -385,6 +385,9 @@ async function installSkill(version, dest, { overwrite = false } = {}) {
     keptEdited
   };
 }
+function afterInstall(skillMd) {
+  return `No restart is needed: a running Claude Code session picks it up. If one does not list it yet, read ${skillMd} and follow it, or run /reload-skills.`;
+}
 function describeInstall(name, r) {
   const lines = [
     `Installed ${name} version ${r.version} into ${r.dest} (${r.written.length} file(s)).`
@@ -394,7 +397,7 @@ function describeInstall(name, r) {
     lines.push(`Kept, edited here and no longer in the skill: ${r.keptEdited.join(", ")}`);
   }
   if (r.keptUntracked.length) lines.push(`Kept, added here: ${r.keptUntracked.join(", ")}`);
-  lines.push("Start a new Claude Code session to load it.");
+  lines.push(afterInstall(join(r.dest, "SKILL.md")));
   return lines.join("\n");
 }