@systemdox/mcp-server 0.1.51 → 0.1.53

package/dist/cli.js

@@ -592,9 +592,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;
   }
 }
@@ -2857,6 +2857,21 @@ var init_get_guardrails = __esm({
   }
 });
 
+// src/lib/spec-label.ts
+function isDecisionDraft(name) {
+  return name.startsWith(DECISION_PREFIX);
+}
+function specLabel(spec) {
+  return isDecisionDraft(spec.name) ? "decision record" : `${spec.requirementCount} requirements`;
+}
+var DECISION_PREFIX;
+var init_spec_label = __esm({
+  "src/lib/spec-label.ts"() {
+    "use strict";
+    DECISION_PREFIX = "ADR: ";
+  }
+});
+
 // src/tools/get-specs.ts
 import { z as z2 } from "zod";
 function registerGetSpecs(server, apiClient2) {
@@ -2923,7 +2938,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: [
@@ -2941,11 +2956,16 @@ ${text3}`
 var init_get_specs = __esm({
   "src/tools/get-specs.ts"() {
     "use strict";
+    init_spec_label();
   }
 });
 
 // src/tools/get-docs.ts
 import { z as z3 } from "zod";
+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);
@@ -3006,11 +3026,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((item2) => matchGlob(item2.path, path));
       }
@@ -3040,16 +3066,20 @@ ${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."
           }
         ]
       };
     }
   );
 }
+var PATH_FILTER_LIMIT;
 var init_get_docs = __esm({
   "src/tools/get-docs.ts"() {
     "use strict";
+    PATH_FILTER_LIMIT = "1000";
   }
 });
 
@@ -3152,7 +3182,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}`);
       }
@@ -3581,6 +3613,32 @@ function scoreSeverity(item2) {
   if (!item2.severity) return 0.5;
   return SEVERITY_SCORES[item2.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(item2, keywords) {
+  const share = titleShare(item2.title, keywords);
+  const score = Math.max(
+    item2.relevance ?? 0,
+    share >= MIN_TITLE_SHARE ? share : 0
+  );
+  return RECORD_PATH.test(item2.path ?? "") ? score * RECORD_FACTOR : score;
+}
 function extractKeywords(text3) {
   const stopWords = /* @__PURE__ */ new Set([
     "the",
@@ -3677,7 +3735,8 @@ function scoreItems(items, taskDescription, filePaths) {
     const keywordScore = scoreKeywordMatch(item2, keywords);
     const recencyScore = scoreRecency(item2);
     const severityScore = scoreSeverity(item2);
-    const score = pathScore * WEIGHT_PATH + keywordScore * WEIGHT_KEYWORD + recencyScore * WEIGHT_RECENCY + severityScore * WEIGHT_SEVERITY;
+    const isReference2 = item2.type === "spec" || item2.type === "doc";
+    const score = isReference2 && keywords.length > 0 ? scoreReference(item2, keywords) : pathScore * WEIGHT_PATH + keywordScore * WEIGHT_KEYWORD + recencyScore * WEIGHT_RECENCY + severityScore * WEIGHT_SEVERITY;
     return {
       type: item2.type,
       id: item2.id,
@@ -3686,7 +3745,7 @@ function scoreItems(items, taskDescription, filePaths) {
       score,
       tokenEstimate: estimateTokens(item2.content)
     };
-  }).sort((a, b) => b.score - a.score);
+  }).filter((item2) => item2.score > 0).sort((a, b) => b.score - a.score);
 }
 function selectWithinBudget(items, maxTokens) {
   const selected = [];
@@ -3698,7 +3757,7 @@ function selectWithinBudget(items, maxTokens) {
   }
   return { selected, tokensUsed, totalItems: items.length };
 }
-var WEIGHT_PATH, WEIGHT_KEYWORD, WEIGHT_RECENCY, WEIGHT_SEVERITY, SEVERITY_SCORES, CHARS_PER_TOKEN;
+var WEIGHT_PATH, WEIGHT_KEYWORD, WEIGHT_RECENCY, WEIGHT_SEVERITY, SEVERITY_SCORES, MIN_TITLE_SHARE, RECORD_PATH, RECORD_FACTOR, CHARS_PER_TOKEN;
 var init_scoring = __esm({
   "src/lib/scoring.ts"() {
     "use strict";
@@ -3713,6 +3772,9 @@ var init_scoring = __esm({
       medium: 0.5,
       low: 0.25
     };
+    MIN_TITLE_SHARE = 1 / 3;
+    RECORD_PATH = /(^|\/)changelog\//;
+    RECORD_FACTOR = 0.5;
     CHARS_PER_TOKEN = 4;
   }
 });
@@ -3736,7 +3798,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}
@@ -3747,6 +3809,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) {
@@ -3768,6 +3845,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)}`
@@ -3846,7 +3938,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
@@ -3859,6 +3953,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",
@@ -3869,12 +3965,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 {
@@ -3885,7 +3981,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), {
@@ -3904,7 +4000,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
       };
     })
   ];
@@ -3912,9 +4010,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);
   }
@@ -4033,9 +4138,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(
@@ -4069,11 +4175,13 @@ _Ranked lower \u2014 fetch with \`get_specs\` / \`get_docs\` if you need them._
 _Context: ${itemsWithBody} full text, ${itemsListed} listed, ${stats.itemsOmitted} omitted \xB7 ~${tokensUsed} of ${budget} tokens` + (bodyFailures > 0 ? ` \xB7 ${bodyFailures} body fetch(es) failed` : "") + (failures.length > 0 ? ` \xB7 ${failures.length} of 5 reads failed` : "") + `_`;
   return { text: body + footer, stats };
 }
-var DEFAULT_BUDGET, RESERVE_TOKENS, GUARDRAIL_SHARE, MIN_BODY_TOKENS, MAX_HYDRATED, MAX_TAIL, TAIL_SHARE, TRUNCATION_NOTICE_TOKENS, SECTION_STOP_WORDS;
+var DEFAULT_BUDGET, RESERVE_TOKENS, GUARDRAIL_SHARE, MIN_BODY_TOKENS, MAX_HYDRATED, MAX_TAIL, TAIL_SHARE, TRUNCATION_NOTICE_TOKENS, STACK_SHARE, MIN_REFERENCES, SEARCH_RESULTS, MAX_QUERY_CHARS, SECTION_STOP_WORDS;
 var init_context_builder = __esm({
   "src/lib/context-builder.ts"() {
     "use strict";
+    init_language();
     init_scoring();
+    init_spec_label();
     init_scoring();
     DEFAULT_BUDGET = 4e3;
     RESERVE_TOKENS = 200;
@@ -4083,6 +4191,10 @@ var init_context_builder = __esm({
     MAX_TAIL = 10;
     TAIL_SHARE = 0.15;
     TRUNCATION_NOTICE_TOKENS = 30;
+    STACK_SHARE = 0.1;
+    MIN_REFERENCES = 3;
+    SEARCH_RESULTS = 30;
+    MAX_QUERY_CHARS = 300;
     SECTION_STOP_WORDS = /* @__PURE__ */ new Set([
       "the",
       "a",
@@ -5234,7 +5346,7 @@ var init_server = __esm({
     init_create_prompt_template();
     init_skills2();
     init_team_setup();
-    SERVER_VERSION = true ? "0.1.51" : "0.0.0-dev";
+    SERVER_VERSION = true ? "0.1.53" : "0.0.0-dev";
   }
 });
 

package/dist/http.js

@@ -851,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",
@@ -915,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: [
@@ -933,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);
@@ -993,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));
       }
@@ -1027,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."
           }
         ]
       };
@@ -1128,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}`);
       }
@@ -1500,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);
@@ -1552,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",
@@ -1648,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,
@@ -1657,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 = [];
@@ -1679,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}]
 
@@ -1697,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}
@@ -1708,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) {
@@ -1729,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)}`
@@ -1829,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
@@ -1842,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",
@@ -1852,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 {
@@ -1868,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), {
@@ -1887,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
       };
     })
   ];
@@ -1895,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);
   }
@@ -2016,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(
@@ -3001,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;
   }
 }
@@ -3890,7 +3994,7 @@ function registerTeamSetupTools(server, apiClient, { localFiles }) {
 }
 
 // src/server.ts
-var SERVER_VERSION = true ? "0.1.51" : "0.0.0-dev";
+var SERVER_VERSION = true ? "0.1.53" : "0.0.0-dev";
 function createServer(apiClient, { localFiles = false, instructions, keyProblem } = {}) {
   const server = new McpServer(
     {