@systemdox/mcp-server 0.1.50 → 0.1.52

package/dist/lib/context-builder.js

@@ -82,6 +82,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(text) {
   return Math.ceil(text.length / CHARS_PER_TOKEN);
@@ -134,6 +137,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(text) {
+  return new Set(
+    text.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(text) {
   const stopWords = /* @__PURE__ */ new Set([
     "the",
@@ -230,7 +259,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,
@@ -239,7 +269,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 = [];
@@ -252,6 +282,15 @@ function selectWithinBudget(items, maxTokens) {
   return { selected, tokensUsed, totalItems: items.length };
 }
 
+// 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/lib/context-builder.ts
 var DEFAULT_BUDGET = 4e3;
 var RESERVE_TOKENS = 200;
@@ -261,6 +300,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 text = `## ${g.title} [${g.severity}]
 
@@ -279,7 +322,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}
@@ -290,6 +333,21 @@ function formatStack(entries) {
     (e) => `- ${e.name}${e.version ? ` v${e.version}` : ""}${e.notes ? ` \u2014 ${e.notes}` : ""}`
   ).join("\n");
 }
+function selectStack(entries, words, maxTokens) {
+  const named = (e) => {
+    const entry = `${e.name} ${e.notes ?? ""}`.toLowerCase();
+    return words.some((w) => entry.includes(w));
+  };
+  const ordered = [...entries.filter(named), ...entries.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: entries.length - shown.length };
+}
 function formatRules(rules) {
   const byCategory = /* @__PURE__ */ new Map();
   for (const r of rules) {
@@ -311,6 +369,21 @@ function formatRules(rules) {
 
 ${text.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)}`
@@ -411,7 +484,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
@@ -424,6 +499,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",
@@ -434,12 +511,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 {
@@ -450,7 +527,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), {
@@ -469,7 +546,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
       };
     })
   ];
@@ -477,9 +556,16 @@ async function buildContext(api, { taskDescription, filePaths = [], maxTokens })
   const sections = [];
   let overhead = 0;
   if (stack.length > 0) {
+    const { text, hidden } = selectStack(
+      stack,
+      [...extractKeywords(taskDescription), ...detectLanguages(filePaths)],
+      Math.floor(budget * STACK_SHARE)
+    );
     const section = `## Tech Stack
 
-${formatStack(stack)}`;
+${text}` + (hidden > 0 ? `
+
+_${hidden} more with \`get_tech_stack\`._` : "");
     sections.push(section);
     overhead += estimateTokens(section);
   }
@@ -598,9 +684,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(

package/dist/lib/scoring.d.ts

@@ -15,6 +15,10 @@ interface ScorableItem {
     category?: string;
     severity?: string;
     updatedAt?: string;
+    /** Where a document's repository file lives. */
+    path?: string;
+    /** 0 to 1, from the order the document search returned it in. */
+    relevance?: number;
 }
 export declare function estimateTokens(text: string): number;
 /**
@@ -26,6 +30,7 @@ export declare function truncateToTokens(text: string, maxTokens: number): {
     text: string;
     truncated: boolean;
 };
+export declare function extractKeywords(text: string): string[];
 export declare function scoreItems(items: ScorableItem[], taskDescription: string, filePaths: string[]): ScoredItem[];
 export declare function selectWithinBudget(items: ScoredItem[], maxTokens: number): {
     selected: ScoredItem[];

package/dist/lib/skills.d.ts

@@ -103,5 +103,12 @@ export declare function installSkill(version: SkillVersionFiles, dest: string, {
 }): Promise<InstallResult>;
 /** A fence longer than any backtick run in `text`, so content cannot close it. */
 export declare function fenceFor(text: string): string;
+/**
+ * What follows an install. Claude Code watches its skills folders, so a running
+ * session needs no restart, unless the top-level folder did not exist when the
+ * session started (code.claude.com/docs/en/skills, "Edit a skill during a
+ * session"): `/reload-skills` covers that, and reading the file works anywhere.
+ */
+export declare function afterInstall(skillMd: string): string;
 /** Human summary of an install, shared by the tool and the CLI. */
 export declare function describeInstall(name: string, r: InstallResult): string;

package/dist/lib/skills.js

@@ -182,6 +182,9 @@ function fenceFor(text) {
   const longest = Math.max(0, ...(text.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)).`
@@ -191,7 +194,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");
 }
 export {
@@ -201,6 +204,7 @@ export {
   MAX_FILE_BYTES,
   MAX_TOTAL_BYTES,
   SkillInstallRefused,
+  afterInstall,
   defaultSkillDir,
   describeInstall,
   fenceFor,

package/dist/lib/spec-label.d.ts

@@ -0,0 +1,5 @@
+export declare function isDecisionDraft(name: string): boolean;
+export declare function specLabel(spec: {
+    name: string;
+    requirementCount: number;
+}): string;

package/dist/server.js

@@ -188,6 +188,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",
@@ -252,7 +263,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: [
@@ -270,6 +281,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);
@@ -330,11 +346,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));
       }
@@ -364,7 +386,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."
           }
         ]
       };
@@ -465,7 +489,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}`);
       }
@@ -837,6 +863,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);
@@ -889,6 +918,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",
@@ -985,7 +1040,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,
@@ -994,7 +1050,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 = [];
@@ -1016,6 +1072,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}]
 
@@ -1034,7 +1094,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}
@@ -1045,6 +1105,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) {
@@ -1066,6 +1141,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)}`
@@ -1166,7 +1256,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
@@ -1179,6 +1271,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",
@@ -1189,12 +1283,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 {
@@ -1205,7 +1299,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), {
@@ -1224,7 +1318,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
       };
     })
   ];
@@ -1232,9 +1328,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);
   }
@@ -1353,9 +1456,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(
@@ -1607,6 +1711,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)).`
@@ -1616,7 +1723,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");
 }
 
@@ -2498,7 +2605,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}
 
@@ -2655,9 +2762,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;
   }
 }
@@ -3544,7 +3651,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/setup-mcp.js

@@ -2,6 +2,7 @@
 
 // src/setup-mcp.ts
 import { existsSync as existsSync3, readFileSync } from "fs";
+import { mkdir as mkdir4 } from "fs/promises";
 import { join as join4 } from "path";
 
 // src/lib/cache.ts
@@ -591,6 +592,7 @@ async function setupMcpServer(opts) {
   }
   try {
     if ((await readCredentials())[workspace]?.apiKey !== apiKey) await writeCredentials(workspace, apiKey);
+    await mkdir4(join4(homeDir(), ".claude", "skills"), { recursive: true });
     const several = Object.keys(await readCredentials()).length > 1;
     for (const target of selected) {
       const removed = await writeServerEntry(target.path, apiUrl, several ? workspace : void 0);

package/dist/tools/get-docs.js

@@ -2,6 +2,11 @@
 
 // src/tools/get-docs.ts
 import { z } 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);
@@ -62,11 +67,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));
       }
@@ -96,7 +107,9 @@ ${doc.content}`;
 
 ${text}
 
-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."
           }
         ]
       };