@systemdox/mcp-server 0.1.48 → 0.1.50

package/dist/cli.js

@@ -26,8 +26,7 @@ function requireHttpsApiUrl(apiUrl) {
   }
   return apiUrl;
 }
-function loadConfig() {
-  const apiKey = process.env.SYSTEMDOX_API_KEY;
+function loadConfig(apiKey = process.env.SYSTEMDOX_API_KEY) {
   if (!apiKey) {
     throw new Error(
       "SYSTEMDOX_API_KEY is required. Generate one at your SystemDox settings page."
@@ -125,6 +124,31 @@ async function apiKeyFor(workspace, env = process.env) {
   const entry = (await readCredentials())[workspace];
   return typeof entry?.apiKey === "string" && entry.apiKey ? entry.apiKey : void 0;
 }
+async function localApiKey(env = process.env) {
+  if (env.SYSTEMDOX_API_KEY) return env.SYSTEMDOX_API_KEY;
+  const keys = Object.entries(await readCredentials()).filter(
+    (e) => typeof e[1]?.apiKey === "string" && e[1].apiKey.length > 0
+  );
+  const wanted = env.SYSTEMDOX_WORKSPACE;
+  if (wanted) {
+    const key = keys.find(([ws]) => ws === wanted)?.[1].apiKey;
+    if (key) return key;
+    throw new Error(
+      `~/.claude/systemdox/credentials.json holds no key for ${wanted} (SYSTEMDOX_WORKSPACE). Set SYSTEMDOX_API_KEY, or run npx -y @systemdox/mcp-server setup.`
+    );
+  }
+  if (keys.length === 1) return keys[0][1].apiKey;
+  if (keys.length > 1) {
+    throw new Error(
+      `~/.claude/systemdox/credentials.json holds keys for ${keys.map(([ws]) => ws).join(", ")}: set SYSTEMDOX_WORKSPACE to the workspace to use, or SYSTEMDOX_API_KEY to its key.`
+    );
+  }
+  throw new Error("No SystemDox key. Set SYSTEMDOX_API_KEY, or run npx -y @systemdox/mcp-server setup.");
+}
+async function loadLocalConfig(env = process.env) {
+  const apiKey = await localApiKey(env);
+  return loadConfig(apiKey);
+}
 function apiUrlFrom(env = process.env) {
   return requireHttpsApiUrl(env.SYSTEMDOX_API_URL || API_URL_DEFAULT);
 }
@@ -277,14 +301,6 @@ var init_api_client = __esm({
         this.config = config2;
         this.cache = new ResponseCache(config2.cacheTtlMs);
       }
-      async validate() {
-        const res = await this.fetchRaw("/v1/health");
-        if (!res.ok) {
-          throw new Error(
-            `SystemDox API authentication failed (${res.status}). Check your SYSTEMDOX_API_KEY.`
-          );
-        }
-      }
       async get(path, params) {
         const url = this.buildUrl(path, params);
         const cacheKey = url.toString();
@@ -298,8 +314,8 @@ var init_api_client = __esm({
       }
       /** A read that skips the cache: an install must take the version that is
        * latest now, not the one cached before someone published another. */
-      async getFresh(path) {
-        const res = await this.fetchRaw(path);
+      async getFresh(path, signal) {
+        const res = await this.fetchRaw(path, void 0, signal);
         if (!res.ok) throw new SystemDoxApiError(res.status, await res.text());
         return await res.json();
       }
@@ -329,8 +345,8 @@ var init_api_client = __esm({
       // One method per operationId. Every read skips the cache: setup, sync and
       // plugin-path act on what the workspace holds now.
       /** getOwnTeamSetup: the key's own workspace, named in `workspace`. */
-      getOwnTeamSetup() {
-        return this.getFresh(TEAM_SETUP);
+      getOwnTeamSetup(signal) {
+        return this.getFresh(TEAM_SETUP, signal);
       }
       getTeamSetup(workspace) {
         return this.getFresh(`${TEAM_SETUP}/${seg(workspace)}`);
@@ -434,14 +450,15 @@ var init_api_client = __esm({
         }
         return url;
       }
-      async fetchRaw(path, params) {
+      async fetchRaw(path, params, signal) {
         const url = this.buildUrl(path, params);
         return fetch(url, {
           headers: {
             Authorization: `Bearer ${this.config.apiKey}`,
             "X-API-Key": this.config.apiKey,
             Accept: "application/json"
-          }
+          },
+          signal
         });
       }
     };
@@ -1006,11 +1023,11 @@ async function people(opts, ws, files, report, hint) {
           report.people.push({ kind: g.kind, answer: ANSWER_WORDS[result.stored[0].answer], label: result.stored[0].label, personId: result.stored[0].personId });
           break;
         }
-        const refused = result.refused[0];
-        if (refused?.code === "SYD-K021") {
-          out(`  ${refused.detail}. Add them in Staff first, or answer p to file them.`);
+        const refused2 = result.refused[0];
+        if (refused2?.code === "SYD-K021") {
+          out(`  ${refused2.detail}. Add them in Staff first, or answer p to file them.`);
           choices = choices.filter((c) => c !== "m");
-        } else if (refused) out(`  ${refused.detail}`);
+        } else if (refused2) out(`  ${refused2.detail}`);
       }
     }
     for (let i = 0; i < filed.length; i += 50) {
@@ -1141,17 +1158,6 @@ async function upload(client, ws, project, plan, team, report) {
   }
   await send();
 }
-async function keyFromEnvironment(env) {
-  if (env.SYSTEMDOX_API_KEY) return env.SYSTEMDOX_API_KEY;
-  const entries2 = Object.entries(await readCredentials()).filter(([, v]) => typeof v?.apiKey === "string" && v.apiKey);
-  if (entries2.length === 1) return entries2[0][1].apiKey;
-  if (entries2.length > 1) {
-    throw new SyncFailed(
-      `~/.claude/systemdox/credentials.json holds keys for ${entries2.map(([w]) => w).join(", ")}: set SYSTEMDOX_API_KEY to the key of the workspace to sync.`
-    );
-  }
-  throw new SyncFailed("No SystemDox key. Set SYSTEMDOX_API_KEY, or run npx -y @systemdox/mcp-server setup, then run this again.");
-}
 async function syncMemory(opts) {
   const { client, out } = opts;
   const now = opts.now?.() ?? /* @__PURE__ */ new Date();
@@ -1287,7 +1293,7 @@ async function runSyncMemory(argv, io, env = process.env) {
     args2 = parseSyncMemoryArgs(argv);
     if (!client) {
       const apiUrl = apiUrlFrom(env);
-      const apiKey = await keyFromEnvironment(env);
+      const apiKey = await localApiKey(env);
       client = new SystemDoxApiClient({ apiKey, apiUrl, cacheTtlMs: 0, defaultOrg: void 0 });
     }
   } catch (e) {
@@ -1380,6 +1386,7 @@ __export(setup_team_exports, {
   parseSetupArgs: () => parseSetupArgs,
   runTeamSetup: () => runTeamSetup,
   runTeamSetupCommand: () => runTeamSetupCommand,
+  setInJsonFile: () => setInJsonFile,
   setJsonMember: () => setJsonMember,
   withImportBlock: () => withImportBlock
 });
@@ -1759,9 +1766,9 @@ async function runTeamSetup(opts) {
       const id = `${ws}-setup@${marketplaceName}`;
       const installed = await readJsonQuietly(join3(pluginsDir, "installed_plugins.json"));
       if (!installed?.plugins?.[id]) {
-        const known = await readJsonQuietly(join3(pluginsDir, "known_marketplaces.json"));
+        const known2 = await readJsonQuietly(join3(pluginsDir, "known_marketplaces.json"));
         const install = `Run \`claude plugin install ${id}\` in your own terminal and accept the command it shows.`;
-        const steps = known && typeof known === "object" && known[marketplaceName] ? ["One step is left:", `1. ${install}`] : ["Two steps are left:", "1. Open Claude Code once in any folder, then close it.", `2. ${install}`];
+        const steps = known2 && typeof known2 === "object" && known2[marketplaceName] ? ["One step is left:", `1. ${install}`] : ["Two steps are left:", "1. Open Claude Code once in any folder, then close it.", `2. ${install}`];
         out("");
         steps.forEach((l) => out(l));
       }
@@ -1812,12 +1819,191 @@ ${lines.join("\n")}`)
   }
 });
 
+// src/setup-mcp.ts
+var setup_mcp_exports = {};
+__export(setup_mcp_exports, {
+  findConfigTargets: () => findConfigTargets,
+  serverEntry: () => serverEntry,
+  setupMcpServer: () => setupMcpServer,
+  writeServerEntry: () => writeServerEntry
+});
+import { existsSync as existsSync3, readFileSync } from "fs";
+import { join as join4 } from "path";
+async function validateApiKey(apiKey, apiUrl) {
+  try {
+    const res = await fetch(`${apiUrl.replace(/\/+$/, "")}/v1/health`, {
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "X-API-Key": apiKey,
+        Accept: "application/json"
+      }
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+function findConfigTargets(cwd = process.cwd()) {
+  const home = homeDir();
+  return [
+    // Claude Code: the project's .mcp.json, and ~/.claude.json (all projects)
+    { name: "Claude Code (project)", path: join4(cwd, ".mcp.json"), detected: true },
+    { name: "Claude Code (user \u2014 all projects)", path: join4(home, ".claude.json"), detected: true },
+    { name: "Cursor (project)", path: join4(cwd, ".cursor", "mcp.json"), detected: existsSync3(join4(cwd, ".cursor")) },
+    { name: "VS Code (project)", path: join4(cwd, ".vscode", "mcp.json"), detected: existsSync3(join4(cwd, ".vscode")) },
+    { name: "Cursor (global)", path: join4(home, ".cursor", "mcp.json"), detected: existsSync3(join4(home, ".cursor")) }
+  ];
+}
+function serverEntry(apiUrl, existing, workspace) {
+  const env = {};
+  const old = existing && typeof existing === "object" ? existing.env : void 0;
+  if (old && typeof old === "object" && !Array.isArray(old)) {
+    for (const [name, value] of Object.entries(old)) {
+      if (typeof value !== "string" || name === "SYSTEMDOX_API_URL" || name === "SYSTEMDOX_WORKSPACE") continue;
+      if (name === "SYSTEMDOX_API_KEY" && !isReference(value)) continue;
+      env[name] = value;
+    }
+  }
+  if (apiUrl !== API_URL_DEFAULT) env.SYSTEMDOX_API_URL = apiUrl;
+  if (workspace) env.SYSTEMDOX_WORKSPACE = workspace;
+  const entry = { command: "npx", args: ["@systemdox/mcp-server"] };
+  if (Object.keys(env).length) entry.env = env;
+  return entry;
+}
+function currentEntry(path) {
+  let text3;
+  try {
+    text3 = readFileSync(path, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return void 0;
+    throw e;
+  }
+  if (!text3.trim()) return void 0;
+  let config2;
+  try {
+    config2 = JSON.parse(text3);
+  } catch {
+    throw new Error(`${path} is not valid JSON: fix it, then run setup again.`);
+  }
+  const servers = config2 && typeof config2 === "object" ? config2.mcpServers : void 0;
+  return servers && typeof servers === "object" ? servers.systemdox : void 0;
+}
+async function writeServerEntry(path, apiUrl, workspace) {
+  const existing = currentEntry(path);
+  const env = existing && typeof existing === "object" ? existing.env : void 0;
+  const heldKey = !!env && typeof env === "object" && "SYSTEMDOX_API_KEY" in env && !isReference(env.SYSTEMDOX_API_KEY);
+  await setInJsonFile(path, ["mcpServers", "systemdox"], serverEntry(apiUrl, existing, workspace));
+  return heldKey;
+}
+async function keyWorkspace(opts, apiKey, apiUrl) {
+  const client = opts.client?.(apiKey, apiUrl) ?? new SystemDoxApiClient({ apiKey, apiUrl, cacheTtlMs: 0, defaultOrg: void 0 });
+  try {
+    const { workspace } = await client.getOwnTeamSetup();
+    if (isWorkspace(workspace)) return workspace;
+    opts.out(`  SystemDox named the workspace ${JSON.stringify(workspace)}, which is not a workspace name.`);
+  } catch (e) {
+    opts.out(`  SystemDox did not name your key's workspace (${e.message}).`);
+  }
+  const fromEnv = (opts.env ?? process.env).SYSTEMDOX_WORKSPACE;
+  if (isWorkspace(fromEnv)) return fromEnv;
+  const typed = (await opts.ask("  Your workspace (acme in acme.systemdox.com): ")).trim().toLowerCase();
+  return isWorkspace(typed) ? typed : void 0;
+}
+async function setupMcpServer(opts) {
+  const { out, err, ask } = opts;
+  out("\n  SystemDox MCP Server Setup\n");
+  const apiKey = (await ask("  Enter your SystemDox API key: ")).trim();
+  if (!apiKey) {
+    err("\n  Error: API key is required.\n  Generate one at your SystemDox settings page.\n");
+    return { code: 1 };
+  }
+  const apiUrl = (await ask(`  API URL [${API_URL_DEFAULT}]: `)).trim() || API_URL_DEFAULT;
+  try {
+    requireHttpsApiUrl(apiUrl);
+  } catch (e) {
+    err(`
+  Error: ${e.message}
+`);
+    return { code: 1 };
+  }
+  out("\n  Validating API key...");
+  if (!await (opts.validateKey ?? validateApiKey)(apiKey, apiUrl)) {
+    err("\n  Error: Invalid API key or cannot reach the SystemDox API.\n  Check your key and try again.\n");
+    return { code: 1 };
+  }
+  out("  API key validated successfully.\n");
+  const workspace = await keyWorkspace(opts, apiKey, apiUrl);
+  if (!workspace) {
+    err("\n  Error: that is not a workspace name (lower case letters, digits and -). Nothing was changed.\n");
+    return { code: 1 };
+  }
+  const detected = findConfigTargets(opts.cwd).filter((t) => t.detected);
+  out("  Available targets:");
+  detected.forEach((t, i) => out(`    ${i + 1}. ${t.name} (${t.path})`));
+  const choice = (await ask(`
+  Which target? [1-${detected.length}, or 'all']: `)).trim();
+  let selected;
+  if (choice.toLowerCase() === "all") {
+    selected = detected;
+  } else {
+    const idx = parseInt(choice, 10) - 1;
+    if (isNaN(idx) || idx < 0 || idx >= detected.length) {
+      err("\n  Invalid selection.\n");
+      return { code: 1 };
+    }
+    selected = [detected[idx]];
+  }
+  try {
+    if ((await readCredentials())[workspace]?.apiKey !== apiKey) await writeCredentials(workspace, apiKey);
+    const several = Object.keys(await readCredentials()).length > 1;
+    for (const target of selected) {
+      const removed = await writeServerEntry(target.path, apiUrl, several ? workspace : void 0);
+      out(`  Configured: ${target.name}`);
+      if (removed) out(`  The key now lives in ~/.claude/systemdox/credentials.json and was removed from ${target.path}.`);
+    }
+  } catch (e) {
+    err(`
+  Error: ${e.message}
+`);
+    return { code: 1 };
+  }
+  out(
+    `
+  Your key for ${workspace} is in ${credentialsPath()} (readable by you alone), not in these configs.
+
+  Done! Restart your AI coding tool to activate the SystemDox MCP server.
+  The server provides 25 tools: get_context, get_team_setup, get_checks,
+  get_project_rules, get_prompt_templates, get_specs, get_docs,
+  get_tech_stack, get_planning_context, get_plan_board, get_change,
+  get_document_links, trace_document_path, get_graph_stats,
+  create_check, create_project_rule, create_prompt_template,
+  update_spec, report_decision, publish_skill, list_skills,
+  install_skill, publish_setup_part, resolve_person, sync_memory.
+
+  get_guardrails and create_guardrail remain registered as deprecated
+  aliases of get_checks and create_check \u2014 existing configs keep working.
+`
+  );
+  return { code: 0, apiKey, apiUrl, workspace };
+}
+var isReference;
+var init_setup_mcp = __esm({
+  "src/setup-mcp.ts"() {
+    "use strict";
+    init_api_client();
+    init_config();
+    init_team_setup_files();
+    init_setup_team();
+    isReference = (value) => typeof value === "string" && /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(value);
+  }
+});
+
 // src/lib/skills.ts
 import { createHash as createHash3 } from "crypto";
 import { lstat, mkdir as mkdir4, readdir as readdir3, readFile as readFile4, rm as rm3, writeFile as writeFile4 } from "fs/promises";
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync4 } from "fs";
 import { homedir as homedir2 } from "os";
-import { dirname as dirname4, join as join4, relative, resolve as resolve3, sep } from "path";
+import { dirname as dirname4, join as join5, relative, resolve as resolve3, sep } from "path";
 function sha2563(content) {
   return createHash3("sha256").update(content, "utf8").digest("hex");
 }
@@ -1825,7 +2011,7 @@ function isValidName(name) {
   return name.length <= 64 && NAME_RE.test(name);
 }
 function isValidPath(path) {
-  return path.length > 0 && path.length <= 512 && !path.startsWith("/") && path.split("/").every((s) => SEGMENT_RE.test(s) && s !== "." && s !== "..");
+  return path.length > 0 && path.length <= 512 && !path.startsWith("/") && path.split("/").every((s) => SEGMENT_RE.test(s) && s !== "." && s !== ".." && s !== PLUGIN_MANIFEST_FOLDER);
 }
 function frontmatterName(skillMd) {
   const block = /^---\r?\n([\s\S]*?)\r?\n---/.exec(skillMd);
@@ -1834,12 +2020,12 @@ function frontmatterName(skillMd) {
   return line ? line[1].replace(/^(['"])(.*)\1$/, "$2") : void 0;
 }
 function defaultSkillDir(name) {
-  return join4(homedir2(), ".claude", "skills", name);
+  return join5(homedir2(), ".claude", "skills", name);
 }
 async function walk(root, { skipHidden }, dir = root, out = { files: [], links: [], hidden: [] }) {
   for (const entry of await readdir3(dir, { withFileTypes: true })) {
     if (SKIPPED.has(entry.name) || entry.name.endsWith(".pyc")) continue;
-    const full = join4(dir, entry.name);
+    const full = join5(dir, entry.name);
     const rel = relative(root, full).split(sep).join("/");
     if (entry.isSymbolicLink()) out.links.push(rel);
     else if (skipHidden && entry.name.startsWith(".")) out.hidden.push(rel);
@@ -1860,7 +2046,7 @@ async function readTextFiles(root, paths, what) {
     if (!isValidPath(path)) {
       throw new Error(`${path}: file names may use letters, digits, ".", "_" and "-" only`);
     }
-    const raw = await readFile4(join4(root, ...path.split("/")));
+    const raw = await readFile4(join5(root, ...path.split("/")));
     if (raw.includes(0)) throw new Error(`${path} is binary: ${what} holds text files only`);
     if (raw.length > MAX_FILE_BYTES) {
       throw new Error(`${path} is ${raw.length} bytes: a file holds at most ${MAX_FILE_BYTES}`);
@@ -1881,7 +2067,7 @@ async function readTextFiles(root, paths, what) {
 }
 async function readSkillDirectory(directory) {
   const root = resolve3(directory);
-  if (!existsSync3(join4(root, ENTRY_FILE))) {
+  if (!existsSync4(join5(root, ENTRY_FILE))) {
     throw new Error(`${root} has no ${ENTRY_FILE}: a skill folder holds SKILL.md at its root`);
   }
   const walked = await walk(root, { skipHidden: true });
@@ -1902,7 +2088,7 @@ function within(dest, path) {
 }
 async function readManifest(dest) {
   try {
-    return JSON.parse(await readFile4(join4(dest, MANIFEST_FILE), "utf8"));
+    return JSON.parse(await readFile4(join5(dest, MANIFEST_FILE), "utf8"));
   } catch {
     return void 0;
   }
@@ -1911,24 +2097,24 @@ async function installSkill(version, dest, { overwrite = false } = {}) {
   if (!isValidName(version.name)) throw new Error(`refusing to install ${JSON.stringify(version.name)}: not a skill name`);
   const incoming = new Map(version.files.map((f) => [f.path, f]));
   for (const f of version.files) within(dest, f.path);
-  if (existsSync3(dest) && (await lstat(dest)).isSymbolicLink()) {
+  if (existsSync4(dest) && (await lstat(dest)).isSymbolicLink()) {
     throw new Error(`${dest} is a link: install into a real folder`);
   }
-  const walked = existsSync3(dest) ? await walk(dest, { skipHidden: false }) : { files: [], links: [], hidden: [] };
+  const walked = existsSync4(dest) ? await walk(dest, { skipHidden: false }) : { files: [], links: [], hidden: [] };
   if (walked.links.length) {
     throw new Error(`${dest} holds links (${walked.links.join(", ")}): remove them, nothing was written`);
   }
   const present = walked.files;
   const manifest = await readManifest(dest);
-  const known = Object.fromEntries(
+  const known2 = Object.fromEntries(
     Object.entries(manifest?.files ?? {}).filter(([p, h]) => isValidPath(p) && typeof h === "string")
   );
   const edited = [];
   const untracked = [];
   for (const path of present) {
-    const content = await readFile4(join4(dest, ...path.split("/")), "utf8");
-    if (Object.hasOwn(known, path)) {
-      if (sha2563(content) !== known[path]) edited.push(path);
+    const content = await readFile4(join5(dest, ...path.split("/")), "utf8");
+    if (Object.hasOwn(known2, path)) {
+      if (sha2563(content) !== known2[path]) edited.push(path);
     } else if (!incoming.has(path) || sha2563(content) !== incoming.get(path).sha256) {
       if (incoming.has(path) || !manifest) edited.push(path);
       else untracked.push(path);
@@ -1945,7 +2131,7 @@ async function installSkill(version, dest, { overwrite = false } = {}) {
   }
   const removed = [];
   const keptEdited = [];
-  for (const path of Object.keys(known)) {
+  for (const path of Object.keys(known2)) {
     if (incoming.has(path) || !present.includes(path)) continue;
     if (edited.includes(path)) {
       keptEdited.push(path);
@@ -1960,7 +2146,7 @@ async function installSkill(version, dest, { overwrite = false } = {}) {
     installedAt: (/* @__PURE__ */ new Date()).toISOString(),
     files: Object.fromEntries(version.files.map((f) => [f.path, f.sha256]))
   };
-  await writeFile4(join4(dest, MANIFEST_FILE), JSON.stringify(next, null, 2) + "\n", "utf8");
+  await writeFile4(join5(dest, MANIFEST_FILE), JSON.stringify(next, null, 2) + "\n", "utf8");
   return {
     dest,
     version: version.version,
@@ -1986,12 +2172,13 @@ function describeInstall(name, r) {
   lines.push("Start a new Claude Code session to load it.");
   return lines.join("\n");
 }
-var MANIFEST_FILE, ENTRY_FILE, MAX_FILES, MAX_FILE_BYTES, MAX_TOTAL_BYTES, NAME_RE, SEGMENT_RE, SKIPPED, SkillInstallRefused;
+var MANIFEST_FILE, ENTRY_FILE, PLUGIN_MANIFEST_FOLDER, MAX_FILES, MAX_FILE_BYTES, MAX_TOTAL_BYTES, NAME_RE, SEGMENT_RE, SKIPPED, SkillInstallRefused;
 var init_skills = __esm({
   "src/lib/skills.ts"() {
     "use strict";
     MANIFEST_FILE = ".systemdox-skill.json";
     ENTRY_FILE = "SKILL.md";
+    PLUGIN_MANIFEST_FOLDER = ".claude-plugin";
     MAX_FILES = 100;
     MAX_FILE_BYTES = 256 * 1024;
     MAX_TOTAL_BYTES = 1024 * 1024;
@@ -2108,9 +2295,9 @@ __export(plugin_path_exports, {
   unpackZip: () => unpackZip
 });
 import { createHash as createHash4, randomBytes } from "crypto";
-import { existsSync as existsSync4 } from "fs";
+import { existsSync as existsSync5 } from "fs";
 import { mkdir as mkdir5, rename as rename2, writeFile as writeFile5 } from "fs/promises";
-import { dirname as dirname5, join as join5, resolve as resolve5, sep as sep2 } from "path";
+import { dirname as dirname5, join as join6, resolve as resolve5, sep as sep2 } from "path";
 import { inflateRawSync } from "zlib";
 function parsePluginPathArgs(argv) {
   const args2 = {};
@@ -2230,7 +2417,7 @@ async function runPluginPath(argv, io) {
   const folder = pluginDir(workspace, version);
   try {
     const state = await readState(workspace);
-    if (existsSync4(folder) && state.plugin?.[String(version)]?.sha256 === sha2564) {
+    if (existsSync5(folder) && state.plugin?.[String(version)]?.sha256 === sha2564) {
       io.out(folder);
       return 0;
     }
@@ -2269,17 +2456,17 @@ async function runPluginPath(argv, io) {
     );
     return 2;
   }
-  const tmp = join5(pluginRoot(workspace), `.${version}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
+  const tmp = join6(pluginRoot(workspace), `.${version}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);
   try {
     await unpackZip(zip, tmp);
-    if (existsSync4(folder) && (await readState(workspace)).plugin?.[String(version)]?.sha256 === sha2564) {
+    if (existsSync5(folder) && (await readState(workspace)).plugin?.[String(version)]?.sha256 === sha2564) {
       await removeFolder(tmp);
     } else {
-      if (existsSync4(folder)) await removeFolder(folder);
+      if (existsSync5(folder)) await removeFolder(folder);
       try {
         await rename2(tmp, folder);
       } catch (e) {
-        if (!existsSync4(folder)) throw e;
+        if (!existsSync5(folder)) throw e;
         await removeFolder(tmp);
       }
     }
@@ -2316,6 +2503,148 @@ var init_plugin_path = __esm({
   }
 });
 
+// src/lib/session-brief.ts
+import { existsSync as existsSync6 } from "fs";
+import { readFile as readFile5 } from "fs/promises";
+import { join as join7 } from "path";
+function noKey(reason) {
+  return `This computer has no SystemDox key it can use (${reason}), so the team's rules and skills cannot be read and every SystemDox tool fails. Tell the person once: \`${SETUP_COMMAND}\` in their own terminal asks for one.`;
+}
+function keyReason(message) {
+  if (/holds keys for/.test(message)) return "keys for several workspaces are stored; set SYSTEMDOX_WORKSPACE to the one to use";
+  if (/holds no key for/.test(message)) return "SYSTEMDOX_WORKSPACE names a workspace with no stored key";
+  if (/No SystemDox key/.test(message)) return "none is stored";
+  return "the stored keys could not be read";
+}
+function olderApi(setup) {
+  return `SystemDox workspace ${setup.workspace}. Before writing code in one of its repositories, call get_context with the task and the files you expect to touch, and obey what it returns. get_team_setup lists the team setup.`;
+}
+async function readJsonQuietly2(path) {
+  try {
+    return JSON.parse(await readFile5(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+async function computerState(setup) {
+  const id = `${setup.workspace}-setup@systemdox-${setup.workspace}`;
+  const installed = await readJsonQuietly2(join7(homeDir(), ".claude", "plugins", "installed_plugins.json"));
+  const entries2 = installed?.plugins?.[id];
+  const entry = Array.isArray(entries2) ? entries2.find((e) => (e?.scope ?? "user") === "user") : void 0;
+  const state = {
+    missing: [],
+    behind: [],
+    notFromSystemDox: [],
+    pluginInstalled: !!entry,
+    pluginVersion: entry?.version
+  };
+  const pluginCurrent = !!entry && !!setup.plugin && entry.version === `${setup.plugin.version}.0.0`;
+  for (const skill of setup.sessionBrief?.skills ?? []) {
+    const dir = defaultSkillDir(skill.name);
+    if (!existsSync6(dir)) {
+      if (!(pluginCurrent && setup.plugin?.skills?.[skill.name] !== void 0)) state.missing.push(skill.name);
+      continue;
+    }
+    const manifest = await readJsonQuietly2(join7(dir, MANIFEST_FILE));
+    if (typeof manifest?.version !== "number" || !Number.isInteger(manifest.version)) {
+      state.notFromSystemDox.push(skill.name);
+    } else if (manifest.version !== skill.latestVersion) {
+      state.behind.push({ name: skill.name, here: manifest.version, latest: skill.latestVersion });
+    }
+  }
+  return state;
+}
+function hasPersonParts(setup) {
+  return Object.keys(setup.parts ?? {}).length > 0 || (setup.memory ?? []).length > 0 || (setup.sessionBrief?.heldSkills ?? []).some((h) => h.reason === "not-plain");
+}
+function listWithin(items, room) {
+  const whole2 = items.join(", ");
+  if (whole2.length <= room) return whole2;
+  const kept = [];
+  let used = 0;
+  for (let i = 0; i < items.length; i++) {
+    const rest = items.length - i - 1;
+    const cost = items[i].length + (kept.length ? 2 : 0);
+    if (used + cost + ` and ${MORE(rest)}`.length > room) break;
+    kept.push(items[i]);
+    used += cost;
+  }
+  return kept.length ? `${kept.join(", ")} and ${MORE(items.length - kept.length)}` : `all ${MORE(items.length)}`;
+}
+function localSection(setup, state, room) {
+  const rest = hasPersonParts(setup) ? ` and that \`${SETUP_COMMAND}\` in their own terminal adds the rest of the team setup` : "";
+  const latest = new Map((setup.sessionBrief?.skills ?? []).map((s) => [s.name, s.latestVersion]));
+  const lines = [];
+  if (state.missing.length) {
+    lines.push({
+      head: "On this computer, missing: ",
+      items: state.missing.map((name) => `${name} version ${latest.get(name)}`),
+      tail: `. Install each now with install_skill at that version, before your first answer. Then tell the person what you installed${rest}. When a skill's line matches the request and it is not loaded yet, read ~/.claude/skills/<name>/SKILL.md and follow it.`
+    });
+  }
+  if (state.behind.length) {
+    lines.push({
+      head: "On this computer, behind: ",
+      items: state.behind.map((b) => `${b.name} (version ${b.here} here, latest ${b.latest})`),
+      tail: ". install_skill updates each to that latest version; if it refuses because files were edited, tell the person and leave them."
+    });
+  }
+  if (state.notFromSystemDox.length) {
+    lines.push({ head: "Not from SystemDox, left alone: ", items: state.notFromSystemDox, tail: "." });
+  }
+  const fixed = () => lines.reduce((n, l) => n + l.head.length + l.tail.length + LIST_MIN, 0) + Math.max(0, lines.length - 1);
+  while (lines.length && fixed() > room) lines.pop();
+  if (!lines.length) return "";
+  const share = Math.floor((room - fixed()) / lines.length) + LIST_MIN;
+  return lines.map((l) => `${l.head}${listWithin(l.items, share)}${l.tail}`).join("\n");
+}
+function fit(text3, section) {
+  const whole2 = section ? `${text3}
+
+${section}` : text3;
+  if (whole2.length <= INSTRUCTIONS_MAX) return whole2;
+  return text3.length <= INSTRUCTIONS_MAX ? text3 : `${text3.slice(0, INSTRUCTIONS_MAX - 1)}\u2026`;
+}
+async function readTeamSetup(apiClient2, { keyProblem: keyProblem2, timeoutMs = BRIEF_TIMEOUT_MS } = {}) {
+  if (keyProblem2) return { problem: noKey(keyProblem2) };
+  try {
+    const setup = await apiClient2.getOwnTeamSetup(AbortSignal.timeout(timeoutMs));
+    return typeof setup?.workspace === "string" ? { setup } : { problem: NOT_CHECKED };
+  } catch (err) {
+    const status = err?.status;
+    return { problem: status === 401 || status === 403 ? REFUSED : NOT_CHECKED };
+  }
+}
+async function sessionInstructions(apiClient2, options = {}) {
+  const read = await readTeamSetup(apiClient2, options);
+  if ("problem" in read) return read.problem;
+  const text3 = read.setup.sessionBrief?.text ?? olderApi(read.setup);
+  try {
+    if (!options.localFiles) return fit(text3, read.setup.sessionBrief?.skills?.length ? CANNOT_SEE : "");
+    const room = INSTRUCTIONS_MAX - text3.length - 2;
+    return fit(text3, localSection(read.setup, await computerState(read.setup), room));
+  } catch {
+    return fit(text3, "");
+  }
+}
+var INSTRUCTIONS_MAX, BRIEF_TIMEOUT_MS, NO_KEY, SETUP_COMMAND, REFUSED, NOT_CHECKED, CANNOT_SEE, MORE, LIST_MIN;
+var init_session_brief = __esm({
+  "src/lib/session-brief.ts"() {
+    "use strict";
+    init_skills();
+    init_team_setup_files();
+    INSTRUCTIONS_MAX = 2e3;
+    BRIEF_TIMEOUT_MS = 8e3;
+    NO_KEY = "no-key-on-this-computer";
+    SETUP_COMMAND = "npx -y @systemdox/mcp-server setup";
+    REFUSED = `SystemDox refused this computer's key, so the team's rules and skills cannot be read and every SystemDox tool fails. Tell the person once: a new key comes from the SystemDox console, Settings \u203A API keys, and \`${SETUP_COMMAND}\` in their own terminal stores it.`;
+    NOT_CHECKED = "SystemDox could not be read when this session started, so the team's skills were not checked. Call get_team_setup to check again before relying on them.";
+    CANNOT_SEE = "This server cannot see this computer's disk. For each skill listed under Team skills: if ~/.claude/skills/<name>/ is absent, or its .systemdox-skill.json names another version than get_team_setup lists, call install_skill with that version and write what it returns, unless the latest team plugin carries it. Leave a folder with no such file alone. If a file there differs from the hash that file holds for it, it was edited: ask the person before replacing it.";
+    MORE = (n) => `${n} more (get_team_setup lists them)`;
+    LIST_MIN = `all ${MORE(100)}`.length;
+  }
+});
+
 // src/lib/language.ts
 function detectLanguage(filePath) {
   const ext = filePath.slice(filePath.lastIndexOf("."));
@@ -2428,7 +2757,7 @@ var init_config_links = __esm({
 
 // src/tools/get-guardrails.ts
 import { z } from "zod";
-function registerGetGuardrails(server2, apiClient2) {
+function registerGetGuardrails(server, apiClient2) {
   const handler = async ({
     language,
     category,
@@ -2482,7 +2811,7 @@ ${text3}`
       ]
     };
   };
-  server2.registerTool(
+  server.registerTool(
     "get_checks",
     {
       title: "Get Checks",
@@ -2491,7 +2820,7 @@ ${text3}`
     },
     handler
   );
-  server2.registerTool(
+  server.registerTool(
     "get_guardrails",
     {
       title: "Get Checks (legacy name)",
@@ -2525,8 +2854,8 @@ var init_get_guardrails = __esm({
 
 // src/tools/get-specs.ts
 import { z as z2 } from "zod";
-function registerGetSpecs(server2, apiClient2) {
-  server2.registerTool(
+function registerGetSpecs(server, apiClient2) {
+  server.registerTool(
     "get_specs",
     {
       title: "Get Specs",
@@ -2616,8 +2945,8 @@ function matchGlob(path, pattern) {
   const regex = pattern.replace(/\./g, "\\.").replace(/\*\*/g, "{{GLOBSTAR}}").replace(/\*/g, "[^/]*").replace(/\{\{GLOBSTAR\}\}/g, ".*");
   return new RegExp(`^${regex}$`).test(path);
 }
-function registerGetDocs(server2, apiClient2) {
-  server2.registerTool(
+function registerGetDocs(server, apiClient2) {
+  server.registerTool(
     "get_docs",
     {
       title: "Get Docs",
@@ -2720,8 +3049,8 @@ var init_get_docs = __esm({
 });
 
 // src/tools/get-tech-stack.ts
-function registerGetTechStack(server2, apiClient2) {
-  server2.registerTool(
+function registerGetTechStack(server, apiClient2) {
+  server.registerTool(
     "get_tech_stack",
     {
       title: "Get Tech Stack",
@@ -2776,8 +3105,8 @@ var init_get_tech_stack = __esm({
 
 // src/tools/get-planning-context.ts
 import { z as z4 } from "zod";
-function registerGetPlanningContext(server2, apiClient2) {
-  server2.registerTool(
+function registerGetPlanningContext(server, apiClient2) {
+  server.registerTool(
     "get_planning_context",
     {
       title: "Get Planning Context",
@@ -2811,7 +3140,7 @@ ${r.conventions.map((c) => `- ${c}`).join("\n")}` : "")
 ${repos}`);
       }
       if (ctx.dependencies.length > 0) {
-        const deps = ctx.dependencies.map((d) => `- ${d.from} \u2192 ${d.to}`).join("\n");
+        const deps = ctx.dependencies.map((d) => `- ${d.from} \u2192 ${d.to}${d.provenance === "inferred" ? " (inferred)" : ""}`).join("\n");
         sections.push(`## Cross-Repo Dependencies
 
 ${deps}`);
@@ -2891,8 +3220,8 @@ function formatItem(item2) {
   ${meta.join(" \xB7 ")}` : "") + (item2.url ? `
   ${item2.url}` : "");
 }
-function registerGetPlanBoard(server2, apiClient2) {
-  server2.registerTool(
+function registerGetPlanBoard(server, apiClient2) {
+  server.registerTool(
     "get_plan_board",
     {
       title: "Get Plan Board",
@@ -3048,6 +3377,153 @@ var init_get_plan_board = __esm({
   }
 });
 
+// src/tools/get-change.ts
+import { z as z6 } from "zod";
+function briefVerdict(states) {
+  const waiting = BRIEF.filter(
+    (part) => !(part === "decision" && states.decision === null) && !PAST_REVIEW.has(String(states[part]))
+  ).map((part) => `${part} is ${states[part] ?? "unknown"}`);
+  return waiting.length === 0 ? "The brief is passed" : `The brief is not passed: ${waiting.join(", ")}`;
+}
+function prLink(pr) {
+  return `[${pr.repo}#${pr.number}](${pr.url}) ${pr.state}`;
+}
+function fileSource(file) {
+  if (file.pullRequest) return prLink(file.pullRequest);
+  return file.direct ? "committed directly" : "\u2014";
+}
+function partPullRequests(change, part) {
+  const files = part === "contract" ? change.contract.files : part === "behaviour" ? change.behaviour.files : part === "plan" ? [change.plan.file] : [];
+  const prs = part === "decision" ? [change.decision?.pullRequest ?? null] : part === "release" ? change.release.prs : files.map((file) => file?.pullRequest ?? null);
+  const unique = /* @__PURE__ */ new Map();
+  for (const pr of prs) {
+    if (pr && !unique.has(`${pr.repo}#${pr.number}`)) unique.set(`${pr.repo}#${pr.number}`, pr);
+  }
+  return [...unique.values()].sort((a, b) => Number(b.state === "open") - Number(a.state === "open"));
+}
+function countsLine(counts) {
+  const tags = ["proposed", "built", "defect", "unbuilt", "open", "untagged"].filter((tag) => counts[tag] > 0).map((tag) => `${counts[tag]} ${tag}`);
+  return `${counts.total} scenario(s)` + (tags.length > 0 ? `: ${tags.join(", ")}` : "");
+}
+function partsTable(change) {
+  const rows = PARTS.filter((part) => !(part === "decision" && change.states.decision === null)).map((part) => {
+    const prs = partPullRequests(change, part);
+    return `| ${part} | ${change.states[part]} | ${prs.length > 0 ? prs.map(prLink).join(", ") : "\u2014"} |`;
+  });
+  return ["| Part | State | Pull request |", "|---|---|---|", ...rows].join("\n");
+}
+function decisionSection(change) {
+  const decision = change.decision;
+  if (decision === null) return "## Decision\n\nNone: the proposal names no ADR (a small change).";
+  const status = decision.status || "no record in a connected repository";
+  return `## Decision
+
+${decision.adr} \xB7 ${status}${decision.title ? ` \u2014 ${decision.title}` : ""}`;
+}
+function contractSection(change) {
+  const files = change.contract.files;
+  return "## Contract\n\n" + (files.length > 0 ? files.map((file) => `- ${file.path} \u2014 ${fileSource(file)}`).join("\n") : "No contract file yet (openapi.yaml, asyncapi.yaml or contract.md).");
+}
+function behaviourSection(change) {
+  const { files, counts } = change.behaviour;
+  if (files.length === 0) {
+    return `## Behaviour
+
+No feature file names this change. A feature file joins it when its path or its first ten lines name \`${change.slug}\`${change.decision ? ` or ${change.decision.adr}` : ""}.`;
+  }
+  const blocks = files.map(
+    (file) => [
+      `### ${file.path}`,
+      "",
+      [file.title, file.runner ? `runner ${file.runner}` : "", fileSource(file), countsLine(file.counts)].filter(Boolean).join(" \xB7 "),
+      "",
+      ...file.scenarios.map((s) => `- ${s.id || "(no id)"} \xB7 ${s.state || "untagged"} \xB7 ${s.title}`)
+    ].join("\n")
+  );
+  return ["## Behaviour", countsLine(counts), ...blocks].join("\n\n");
+}
+function planSection(change) {
+  const { file, draftId, board } = change.plan;
+  const boardLine = board ? `[#${board.number} ${board.title}](${board.url}) \u2014 todo ${board.items.todo} \xB7 in progress ${board.items.inProgress} \xB7 done ${board.items.done}` + (board.items.truncated ? " (counted over its first 500 items)" : "") : "none";
+  return [
+    "## Plan",
+    "",
+    `- plan.md: ${file ? `${file.path} \u2014 ${fileSource(file)}` : "none"}`,
+    `- Draft: ${draftId ?? "none"}`,
+    `- Board: ${boardLine}`
+  ].join("\n");
+}
+function releaseSection(change) {
+  const lines = change.release.prs.map(
+    (pr) => `- ${prLink(pr)} \xB7 ${pr.title} \xB7 ` + (pr.approvingReview ? `approved by ${pr.approvingReview.by} at ${pr.approvingReview.at}` : "no approving review on its head yet")
+  );
+  return `## Release
+
+${lines.length > 0 ? lines.join("\n") : "No release pull request is open."}`;
+}
+function formatChange(change) {
+  const header = `# ${change.title}
+
+\`${change.key}\` \xB7 size: ${change.size}` + (change.archived ? " \xB7 archived: read-only, done" : "") + ` \xB7 synced ${change.syncedAt}`;
+  return [
+    header,
+    partsTable(change),
+    decisionSection(change),
+    contractSection(change),
+    behaviourSection(change),
+    planSection(change),
+    releaseSection(change),
+    // Compact: a change's every scenario with its steps rides in this block.
+    "```json\n" + JSON.stringify(change) + "\n```",
+    briefVerdict(change.states)
+  ].join("\n\n");
+}
+function registerGetChange(server, apiClient2) {
+  server.registerTool(
+    "get_change",
+    {
+      title: "Get Change",
+      description: `Read one change (a specs/changes/<slug>/ folder of a connected repository) as SystemDox last synced it from GitHub: the state of each part of its brief (decision, contract, behaviour, plan) and of its release, each with its pull request; the decision's ADR and status; the contract files; every feature file that names the change, with its scenarios as id \xB7 state \xB7 title; the plan (plan.md, the draft, the board); the release pull requests; and the Change object as JSON. The last line says "The brief is passed" or "The brief is not passed: <part> is <state>". Call it before building a story, and stop if the brief is not passed or the story's scenarios are not proposed. Read-only.`,
+      inputSchema: {
+        repo: z6.string().regex(REPO_RE, "the repository as owner/name, e.g. acme/booking-api").describe("The repository that holds the change, as owner/name"),
+        slug: z6.string().max(SLUG_MAX).regex(SLUG_RE2, "a change folder's name: lower-case words joined by -, e.g. customer-reminders").describe("The change's folder name: specs/changes/<slug>/")
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ repo, slug }) => {
+      const [owner, name] = repo.split("/");
+      let change;
+      try {
+        change = await apiClient2.getFresh(
+          `/v1/changes/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/${encodeURIComponent(slug)}`
+        );
+      } catch (err) {
+        if (err.status === 404) {
+          return {
+            content: [{ type: "text", text: `No such change ${repo}/${slug}` }],
+            isError: true
+          };
+        }
+        throw err;
+      }
+      return { content: [{ type: "text", text: formatChange(change) }] };
+    }
+  );
+}
+var GITHUB_NAME, REPO_RE, SLUG_RE2, SLUG_MAX, PARTS, BRIEF, PAST_REVIEW;
+var init_get_change = __esm({
+  "src/tools/get-change.ts"() {
+    "use strict";
+    GITHUB_NAME = "[A-Za-z0-9][A-Za-z0-9._-]{0,99}";
+    REPO_RE = new RegExp(`^${GITHUB_NAME}/${GITHUB_NAME}$`);
+    SLUG_RE2 = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+    SLUG_MAX = 64;
+    PARTS = ["decision", "contract", "behaviour", "plan", "release"];
+    BRIEF = ["decision", "contract", "behaviour", "plan"];
+    PAST_REVIEW = /* @__PURE__ */ new Set(["passed", "being built", "done"]);
+  }
+});
+
 // src/lib/scoring.ts
 function estimateTokens(text3) {
   return Math.ceil(text3.length / CHARS_PER_TOKEN);
@@ -3357,16 +3833,22 @@ async function hydrate(api, item2, meta) {
 }
 async function buildContext(api, { taskDescription, filePaths = [], maxTokens }) {
   const budget = maxTokens ?? DEFAULT_BUDGET;
+  const failures = [];
+  const orEmpty = (empty) => (err) => {
+    failures.push(err);
+    return empty;
+  };
   const [rawGuardrails, rawSpecs, docs, stack, rules, docRepos] = await Promise.all([
-    api.get("/v1/guardrails").catch(() => []),
-    api.get("/v1/specs").catch(() => []),
-    api.get("/v1/docs").catch(() => ({ items: [] })),
-    api.get("/v1/ai/settings/stack").catch(() => []),
-    api.get("/v1/standards/rules").catch(() => []),
+    api.get("/v1/guardrails").catch(orEmpty([])),
+    api.get("/v1/specs").catch(orEmpty([])),
+    api.get("/v1/docs").catch(orEmpty({ items: [] })),
+    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
     // blip) gates nothing, it can never hide working context.
     api.get("/v1/doc-repos").catch(() => null)
   ]);
+  if (failures.length === 5) throw failures[0];
   const disabled = (key2) => docRepos?.capabilities?.[key2]?.status === "disabled";
   const guardrails = disabled("fitness") ? [] : rawGuardrails;
   const specs = disabled("requirements") && disabled("design") && disabled("specs") ? [] : rawSpecs;
@@ -3573,12 +4055,13 @@ _Ranked lower \u2014 fetch with \`get_specs\` / \`get_docs\` if you need them._
     guardrails: selectedGuardrails.length
   };
   if (sections.length === 0) {
-    return { text: "No relevant context found for this task.", stats };
+    const text3 = failures.length ? `No context found for this task, but ${failures.length} of 5 reads failed, so this is not an all-clear: the team's rules may not have been read.` : "No relevant context found for this task.";
+    return { text: text3, stats };
   }
   const footer = `
 
 ---
-_Context: ${itemsWithBody} full text, ${itemsListed} listed, ${stats.itemsOmitted} omitted \xB7 ~${tokensUsed} of ${budget} tokens` + (bodyFailures > 0 ? ` \xB7 ${bodyFailures} body fetch(es) failed` : "") + `_`;
+_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;
@@ -3621,21 +4104,21 @@ var init_context_builder = __esm({
 });
 
 // src/tools/get-context.ts
-import { z as z6 } from "zod";
-function registerGetContext(server2, apiClient2) {
-  server2.registerTool(
+import { z as z7 } from "zod";
+function registerGetContext(server, apiClient2) {
+  server.registerTool(
     "get_context",
     {
       title: "Get Context",
       description: "Intelligent context aggregator: fetches checks, specs, docs, and tech stack, ranks them by relevance to your current task, and returns the full text of the highest-ranked items within a token budget \u2014 each with the ID needed to fetch the rest. Use this instead of calling individual tools when you want curated, relevant context.",
       inputSchema: {
-        task_description: z6.string().describe(
+        task_description: z7.string().describe(
           "What you're working on (e.g., 'add a new REST endpoint for user preferences')"
         ),
-        file_paths: z6.array(z6.string()).optional().describe(
+        file_paths: z7.array(z7.string()).optional().describe(
           "File paths being edited \u2014 used for language/category detection"
         ),
-        max_tokens: z6.number().optional().describe("Maximum token budget for the response (default: 4000)")
+        max_tokens: z7.number().optional().describe("Maximum token budget for the response (default: 4000)")
       }
     },
     async ({ task_description, file_paths, max_tokens }) => {
@@ -3657,9 +4140,254 @@ var init_get_context = __esm({
   }
 });
 
+// src/tools/get-team-setup.ts
+function describeSetup(setup) {
+  const lines = [`# Team setup of ${setup.workspace}`, ""];
+  const skills = setup.sessionBrief?.skills ?? [];
+  const held = setup.sessionBrief?.heldSkills ?? [];
+  lines.push(`## Skills a session installs by itself (${skills.length})`, "");
+  if (skills.length) {
+    for (const s of skills) lines.push(`- **${s.name}** version ${s.latestVersion}: ${s.description}`);
+  } else if (!setup.sessionBrief && setup.skills.length) {
+    lines.push(`- ${setup.skills.join(", ")}`);
+  } else {
+    lines.push("None.");
+  }
+  lines.push("");
+  if (held.length) {
+    lines.push(`## Skills that wait for the person (${held.length})`, "");
+    for (const h of held) lines.push(`- **${h.name}**: ${HELD_BECAUSE[h.reason] ?? h.reason}`);
+    lines.push("", "Do not install these yourself: each is the person's to decide.", "");
+  }
+  if (setup.plugin) {
+    lines.push(`## Team plugin`, "", `\`${setup.workspace}-setup\` version ${setup.plugin.version}.`);
+    for (const c of setup.plugin.hookCommands ?? []) lines.push(`- Hook: ${JSON.stringify(c)}`);
+    for (const m of setup.plugin.mcpServers ?? []) {
+      lines.push(`- MCP server ${JSON.stringify(m.name)}: ${JSON.stringify(m.url ?? [m.command, ...m.args ?? []].filter(Boolean).join(" "))}`);
+    }
+    lines.push("");
+  }
+  const parts = Object.entries(setup.parts ?? {});
+  if (parts.length) {
+    lines.push(`## Published parts`, "", ...parts.map(([p, v]) => `- ${p}: version ${v}`), "");
+  }
+  if (setup.memory?.length) {
+    lines.push(`## Team memory`, "", ...setup.memory.map((m) => `- ${m.project}: ${m.fileCount} file(s)`), "");
+  }
+  return lines;
+}
+function describeComputer(setup, state) {
+  const lines = ["## This computer", ""];
+  if (!setup.sessionBrief) {
+    return [...lines, "This SystemDox API is too old to compare this computer with the team setup."];
+  }
+  const skills = setup.sessionBrief.skills;
+  const latest = new Map(skills.map((s) => [s.name, s.latestVersion]));
+  lines.push(
+    state.missing.length ? `- Missing: ${state.missing.map((name) => `${name} version ${latest.get(name)}`).join(", ")}` : `- Missing: none of ${skills.length}`
+  );
+  if (state.behind.length) {
+    lines.push(`- Behind: ${state.behind.map((b) => `${b.name} (version ${b.here} here, latest ${b.latest})`).join(", ")}`);
+  }
+  if (state.notFromSystemDox.length) lines.push(`- Not from SystemDox, left alone: ${state.notFromSystemDox.join(", ")}`);
+  if (setup.plugin) {
+    lines.push(
+      state.pluginInstalled ? `- Team plugin: installed${state.pluginVersion ? `, ${state.pluginVersion}` : ""}; the latest is version ${setup.plugin.version}` : "- Team plugin: not installed"
+    );
+  }
+  lines.push("", "## What to do", "");
+  const steps = [];
+  if (state.missing.length) steps.push("Call install_skill for each missing skill, at the version named above. These are plain skills: installing writes files and runs nothing.");
+  if (state.behind.length) {
+    steps.push("Call install_skill for each skill behind, at the latest version named above. If it refuses because files were edited, tell the person and leave them.");
+  }
+  if (hasPersonParts(setup) && !state.pluginInstalled) {
+    steps.push(
+      `Hooks, MCP servers, team instructions and memory need the person: \`${SETUP_COMMAND}\` in their own terminal. Never answer its prompts for them.`
+    );
+  }
+  lines.push(...steps.length ? steps.map((s, i) => `${i + 1}. ${s}`) : ["Nothing."]);
+  return lines;
+}
+function registerGetTeamSetup(server, apiClient2, { localFiles, keyProblem: keyProblem2 }) {
+  server.registerTool(
+    "get_team_setup",
+    {
+      title: "Get Team Setup",
+      description: localFiles ? "What this workspace's team setup holds (skills, plugin, hooks, MCP servers, memory) and what this computer lacks, with what to do about it. Call it to check whether this computer is set up. Reads only." : "What this workspace's team setup holds (skills, plugin, hooks, MCP servers, memory), and how to check this computer against it. Reads only.",
+      inputSchema: {},
+      annotations: { readOnlyHint: true }
+    },
+    async () => {
+      const read = await readTeamSetup(apiClient2, { keyProblem: keyProblem2, timeoutMs: 15e3 });
+      if ("problem" in read) return { content: [{ type: "text", text: read.problem }] };
+      const lines = describeSetup(read.setup);
+      if (localFiles) lines.push(...describeComputer(read.setup, await computerState(read.setup)));
+      else lines.push(CANNOT_SEE);
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+}
+var HELD_BECAUSE;
+var init_get_team_setup = __esm({
+  "src/tools/get-team-setup.ts"() {
+    "use strict";
+    init_session_brief();
+    HELD_BECAUSE = {
+      "not-plain": `it is not a plain skill: it has frontmatter beyond a name and a description, files outside its own folders, or a command that runs as it loads. The team plugin carries it, and \`${SETUP_COMMAND}\` shows that before the person accepts`,
+      "outside-default-space": "it is outside the default space, so the team plugin does not carry it either. The person can read it in the console, then install it with `npx -y @systemdox/mcp-server install-skill <name>`",
+      "not-checked": "it could not be checked. Ask again later"
+    };
+  }
+});
+
+// src/tools/document-graph.ts
+import { z as z8 } from "zod";
+function place(file, line) {
+  return file ? `${file}:${line}` : "made by a person";
+}
+function known(provenance, confidence) {
+  return `${provenance} ${confidence}`;
+}
+function formatNeighbours(answer) {
+  const lines = [`# ${answer.doc.label}`, `\`${answer.doc.id}\``, ""];
+  if (answer.links.length === 0) lines.push("No links.");
+  for (const link of answer.links) {
+    lines.push(
+      `- ${link.direction} \xB7 ${link.relation} \xB7 ${known(link.provenance, link.confidence)} \xB7 ${link.other.label} \xB7 \`${link.other.id}\` \xB7 ${place(link.file, link.line)}`
+    );
+  }
+  if (answer.truncated) {
+    lines.push("", `Showing ${answer.links.length} of ${answer.total}. Raise limit to see more.`);
+  }
+  if (answer.ambiguous.length > 0) {
+    lines.push("", "## Ambiguous: not drawn, because each could mean several documents");
+    for (const entry of answer.ambiguous) {
+      const candidates = entry.candidates.map((c) => `${c.label} (${c.repo}, \`${c.id}\`)`);
+      lines.push(`- ${entry.reference} at ${place(entry.file, entry.line)}: ${candidates.join("; ")}`);
+    }
+  }
+  return lines.join("\n");
+}
+function formatPath(answer, maxHops) {
+  if (!answer.found) return `No path within ${maxHops} hops.`;
+  const lines = answer.steps.map((step, index) => {
+    const arrow = step.reversed ? "<-" : "->";
+    return `${index + 1}. ${step.from.label} ${arrow} ${step.relation} ${arrow} ${step.to.label} \xB7 ${known(step.provenance, step.confidence)} \xB7 ${place(step.file, step.line)}`;
+  });
+  return [...lines, "", `Path confidence: ${answer.confidence}`].join("\n");
+}
+function formatStats(stats, repoLinks) {
+  const { declared, extracted, inferred, ambiguous } = stats.links;
+  const lines = [
+    `# The graph: ${stats.nodeCount} documents, ${stats.edgeCount} links`,
+    "",
+    `Links: ${declared} declared \xB7 ${extracted} extracted \xB7 ${inferred} inferred \xB7 ${ambiguous} ambiguous (not drawn)`,
+    "",
+    "## Repositories"
+  ];
+  for (const repo of stats.repos) {
+    const state = repo.behind ? `BEHIND: pushed ${repo.headCommit || "unknown"} at ${repo.pushedAt}, index at ${repo.indexedCommit || "unknown"}` : `index at ${repo.indexedCommit || "unknown"}`;
+    lines.push(`- ${repo.repo}: ${repo.documents} documents, ${repo.links} links, ${state}`);
+  }
+  if (repoLinks.length > 0) {
+    lines.push("", "## Repository links");
+    for (const link of repoLinks) {
+      lines.push(
+        `- ${link.source} ${link.relation} ${link.target} \xB7 ${known(link.provenance, link.confidence)} \xB7 ${place(link.file, link.line)}`
+      );
+    }
+  }
+  return lines.join("\n");
+}
+function refused(err) {
+  const status = err.status;
+  if (status !== 404 && status !== 400) throw err;
+  return {
+    content: [{ type: "text", text: err.message }],
+    isError: true
+  };
+}
+function registerDocumentGraph(server, apiClient2) {
+  server.registerTool(
+    "get_document_links",
+    {
+      description: "What one document links to and from, strongest first. Each link says how it is known: declared (a person made it), extracted (the file says so), or inferred (a reading that could be wrong), with a confidence and the file and line it came from. A reference that could mean several documents is listed as ambiguous with its candidates, and is never drawn as a link. doc_id is the id get_docs returns. Read-only.",
+      inputSchema: {
+        doc_id: z8.string().min(1).max(400).describe("A document id, as get_docs returns it"),
+        direction: z8.enum(["out", "in", "both"]).optional().describe("Default both"),
+        relation: z8.enum(["links_to", "cites", "mentions", "satisfies", "references"]).optional().describe("Only links of this kind"),
+        limit: z8.number().int().min(1).max(MAX_LIMIT).optional().describe(`Most links to show (default ${DEFAULT_LIMIT2})`)
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ doc_id, direction, relation, limit }) => {
+      const params = { doc: doc_id, limit: String(limit ?? DEFAULT_LIMIT2) };
+      if (direction) params.direction = direction;
+      if (relation) params.relation = relation;
+      try {
+        const answer = await apiClient2.get("/v1/graph/neighbours", params);
+        return { content: [{ type: "text", text: formatNeighbours(answer) }] };
+      } catch (err) {
+        return refused(err);
+      }
+    }
+  );
+  server.registerTool(
+    "trace_document_path",
+    {
+      description: "The shortest way two documents connect, walking links in either direction. Each step says how it is known, and the path is only as strong as its weakest step. Read-only.",
+      inputSchema: {
+        from: z8.string().min(1).max(400).describe("A document id, as get_docs returns it"),
+        to: z8.string().min(1).max(400).describe("A document id, as get_docs returns it"),
+        max_hops: z8.number().int().min(1).max(MAX_HOPS).optional().describe(`Longest path to look for (default ${DEFAULT_HOPS})`)
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async ({ from, to, max_hops }) => {
+      const hops = max_hops ?? DEFAULT_HOPS;
+      try {
+        const answer = await apiClient2.get("/v1/graph/path", {
+          from,
+          to,
+          maxHops: String(hops)
+        });
+        return { content: [{ type: "text", text: formatPath(answer, hops) }] };
+      } catch (err) {
+        return refused(err);
+      }
+    }
+  );
+  server.registerTool(
+    "get_graph_stats",
+    {
+      description: "The state of the graph: links counted by how they are known, each repository's freshness (marked BEHIND when a push has not finished indexing), and how repositories depend on each other, from the files that declare it. Read-only.",
+      inputSchema: {},
+      annotations: { readOnlyHint: true }
+    },
+    async () => {
+      const [stats, repos] = await Promise.all([
+        apiClient2.getFresh("/v1/graph/stats"),
+        apiClient2.getFresh("/v1/graph/repos")
+      ]);
+      return { content: [{ type: "text", text: formatStats(stats, repos.links) }] };
+    }
+  );
+}
+var DEFAULT_LIMIT2, MAX_LIMIT, DEFAULT_HOPS, MAX_HOPS;
+var init_document_graph = __esm({
+  "src/tools/document-graph.ts"() {
+    "use strict";
+    DEFAULT_LIMIT2 = 50;
+    MAX_LIMIT = 200;
+    DEFAULT_HOPS = 6;
+    MAX_HOPS = 8;
+  }
+});
+
 // src/tools/create-guardrail.ts
-import { z as z7 } from "zod";
-function registerCreateGuardrail(server2, apiClient2) {
+import { z as z9 } from "zod";
+function registerCreateGuardrail(server, apiClient2) {
   const handler = async ({
     title,
     description,
@@ -3696,7 +4424,7 @@ function registerCreateGuardrail(server2, apiClient2) {
       ]
     };
   };
-  server2.registerTool(
+  server.registerTool(
     "create_check",
     {
       title: "Create Check",
@@ -3708,7 +4436,7 @@ function registerCreateGuardrail(server2, apiClient2) {
     },
     handler
   );
-  server2.registerTool(
+  server.registerTool(
     "create_guardrail",
     {
       title: "Create Check (legacy name)",
@@ -3738,32 +4466,32 @@ var init_create_guardrail = __esm({
       "data-access"
     ];
     inputSchema2 = () => ({
-      title: z7.string().describe("Short title for the check"),
-      description: z7.string().describe("Detailed description of what the check enforces and why"),
-      severity: z7.enum(["critical", "high", "medium", "low"]).describe("Severity level"),
-      category: z7.enum(CATEGORIES).optional().describe("Category (defaults to conventions)"),
-      pattern: z7.string().optional().describe("Bad code pattern that should be avoided"),
-      fix: z7.string().optional().describe("Correct code pattern to use instead"),
-      fitness_test: z7.string().optional().describe("Shell command to detect violations in CI")
+      title: z9.string().describe("Short title for the check"),
+      description: z9.string().describe("Detailed description of what the check enforces and why"),
+      severity: z9.enum(["critical", "high", "medium", "low"]).describe("Severity level"),
+      category: z9.enum(CATEGORIES).optional().describe("Category (defaults to conventions)"),
+      pattern: z9.string().optional().describe("Bad code pattern that should be avoided"),
+      fix: z9.string().optional().describe("Correct code pattern to use instead"),
+      fitness_test: z9.string().optional().describe("Shell command to detect violations in CI")
     });
   }
 });
 
 // src/tools/update-spec.ts
-import { z as z8 } from "zod";
-function registerUpdateSpec(server2, apiClient2) {
-  server2.registerTool(
+import { z as z10 } from "zod";
+function registerUpdateSpec(server, apiClient2) {
+  server.registerTool(
     "update_spec",
     {
       title: "Update Spec",
       description: "Update an existing SystemDox spec's proposal, tasks, or requirements. Only draft specs can be modified \u2014 published specs must be versioned first.",
       inputSchema: {
-        draft_id: z8.string().describe("ID of the spec to update"),
-        section: z8.enum(["proposal", "tasks", "requirements"]).describe("Which section to update"),
-        content: z8.string().describe(
+        draft_id: z10.string().describe("ID of the spec to update"),
+        section: z10.enum(["proposal", "tasks", "requirements"]).describe("Which section to update"),
+        content: z10.string().describe(
           "New markdown content for the section. For requirements, provide the full requirement content."
         ),
-        requirement_name: z8.string().optional().describe(
+        requirement_name: z10.string().optional().describe(
           "Name of the requirement (required when section is 'requirements')"
         )
       },
@@ -3818,19 +4546,19 @@ var init_update_spec = __esm({
 });
 
 // src/tools/report-decision.ts
-import { z as z9 } from "zod";
-function registerReportDecision(server2, apiClient2) {
-  server2.registerTool(
+import { z as z11 } from "zod";
+function registerReportDecision(server, apiClient2) {
+  server.registerTool(
     "report_decision",
     {
       title: "Report Decision",
       description: "Record an architecture decision made during development. Creates a draft ADR in SystemDox for human review.",
       inputSchema: {
-        title: z9.string().describe("Decision title (e.g., 'Use WebSocket for real-time updates')"),
-        context: z9.string().describe("What prompted this decision \u2014 the problem or constraint"),
-        decision: z9.string().describe("What was decided and why"),
-        consequences: z9.string().describe("What this decision means going forward \u2014 trade-offs, follow-up work"),
-        related_files: z9.array(z9.string()).optional().describe("File paths related to this decision")
+        title: z11.string().describe("Decision title (e.g., 'Use WebSocket for real-time updates')"),
+        context: z11.string().describe("What prompted this decision \u2014 the problem or constraint"),
+        decision: z11.string().describe("What was decided and why"),
+        consequences: z11.string().describe("What this decision means going forward \u2014 trade-offs, follow-up work"),
+        related_files: z11.array(z11.string()).optional().describe("File paths related to this decision")
       },
       annotations: {
         readOnlyHint: false
@@ -3886,15 +4614,15 @@ var init_report_decision = __esm({
 });
 
 // src/tools/get-project-rules.ts
-import { z as z10 } from "zod";
-function registerGetProjectRules(server2, apiClient2) {
-  server2.registerTool(
+import { z as z12 } from "zod";
+function registerGetProjectRules(server, apiClient2) {
+  server.registerTool(
     "get_project_rules",
     {
       title: "Get Project Rules",
       description: "Retrieve project rules defined in SystemDox Standards. These are team-defined principles covering deployment, architecture, security, testing, and process. Filter by category to get only relevant rules.",
       inputSchema: {
-        category: z10.enum(["deployment", "architecture", "security", "testing", "process", "other"]).optional().describe("Filter by rule category")
+        category: z12.enum(["deployment", "architecture", "security", "testing", "process", "other"]).optional().describe("Filter by rule category")
       }
     },
     async ({ category }) => {
@@ -3961,18 +4689,18 @@ var init_get_project_rules = __esm({
 });
 
 // src/tools/create-project-rule.ts
-import { z as z11 } from "zod";
-function registerCreateProjectRule(server2, apiClient2) {
-  server2.registerTool(
+import { z as z13 } from "zod";
+function registerCreateProjectRule(server, apiClient2) {
+  server.registerTool(
     "create_project_rule",
     {
       title: "Create Project Rule",
       description: "Create a new project rule in SystemDox Standards. Use this when you discover a team principle or convention that should be enforced across the project.",
       inputSchema: {
-        text: z11.string().describe(
+        text: z13.string().describe(
           "The rule statement \u2014 one enforceable principle per rule (e.g. 'All deployments MUST go through GitHub Actions workflows')"
         ),
-        category: z11.enum(["deployment", "architecture", "security", "testing", "process", "other"]).describe("Rule category")
+        category: z13.enum(["deployment", "architecture", "security", "testing", "process", "other"]).describe("Rule category")
       },
       annotations: {
         readOnlyHint: false
@@ -4002,8 +4730,8 @@ var init_create_project_rule = __esm({
 });
 
 // src/tools/get-prompt-templates.ts
-function registerGetPromptTemplates(server2, apiClient2) {
-  server2.registerTool(
+function registerGetPromptTemplates(server, apiClient2) {
+  server.registerTool(
     "get_prompt_templates",
     {
       title: "Get Prompt Templates",
@@ -4054,17 +4782,17 @@ var init_get_prompt_templates = __esm({
 });
 
 // src/tools/create-prompt-template.ts
-import { z as z12 } from "zod";
-function registerCreatePromptTemplate(server2, apiClient2) {
-  server2.registerTool(
+import { z as z14 } from "zod";
+function registerCreatePromptTemplate(server, apiClient2) {
+  server.registerTool(
     "create_prompt_template",
     {
       title: "Create Prompt Template",
       description: "Create a new reusable prompt template in SystemDox Standards. Use this to store preconfigured prompts for common AI tasks like code reviews, documentation generation, or analysis frameworks.",
       inputSchema: {
-        name: z12.string().describe("Short name for the template"),
-        description: z12.string().optional().describe("Brief description of when to use this template"),
-        prompt: z12.string().describe("The full prompt text that Gen AI will use when generating content")
+        name: z14.string().describe("Short name for the template"),
+        description: z14.string().optional().describe("Brief description of when to use this template"),
+        prompt: z14.string().describe("The full prompt text that Gen AI will use when generating content")
       },
       annotations: {
         readOnlyHint: false
@@ -4098,7 +4826,7 @@ var init_create_prompt_template = __esm({
 });
 
 // src/tools/skills.ts
-import { z as z13 } from "zod";
+import { z as z15 } from "zod";
 import { homedir as homedir3 } from "os";
 import { basename as basename2, resolve as resolve6 } from "path";
 function expandHome(path) {
@@ -4107,25 +4835,25 @@ function expandHome(path) {
 function text(t) {
   return { content: [{ type: "text", text: t }] };
 }
-function registerSkillTools(server2, apiClient2, { localFiles }) {
-  const fileSchema = z13.object({
-    path: z13.string().describe('Path inside the skill folder, forward slashes, e.g. "references/guide.md"'),
-    content: z13.string().describe("The file's full text, exactly as it is")
+function registerSkillTools(server, apiClient2, { localFiles }) {
+  const fileSchema = z15.object({
+    path: z15.string().describe('Path inside the skill folder, forward slashes, e.g. "references/guide.md"'),
+    content: z15.string().describe("The file's full text, exactly as it is")
   });
-  server2.registerTool(
+  server.registerTool(
     "publish_skill",
     {
       title: "Publish Skill",
       description: localFiles ? "Publish a Claude Code skill folder (SKILL.md plus its references and scripts) to SystemDox so it can be installed on any computer. Pass `directory` (e.g. ~/.claude/skills/<name>): the server reads the files itself, byte for byte. Publishing a name again makes a new version. Never retype the files into `files` when the folder is on this computer." : "Publish a Claude Code skill (SKILL.md plus its references and scripts) to SystemDox so it can be installed on any computer. Pass every file of the folder in `files`, exactly as it is. Publishing a name again makes a new version.",
       inputSchema: {
         ...localFiles ? {
-          directory: z13.string().optional().describe("The skill folder on this computer, holding SKILL.md at its root")
+          directory: z15.string().optional().describe("The skill folder on this computer, holding SKILL.md at its root")
         } : {},
-        files: z13.array(fileSchema).optional().describe(localFiles ? "Only when there is no folder to read" : "Every file of the skill folder"),
-        name: z13.string().optional().describe("The skill's name; defaults to SKILL.md's frontmatter name and must match it"),
-        spaceId: z13.string().optional().describe("Space for a NEW skill (default: your default space)"),
-        note: z13.string().max(500).optional().describe(`A short change note for this version, shown in the console's history (e.g. "Fix the GA4 step")`),
-        baseVersion: z13.number().int().positive().optional().describe(
+        files: z15.array(fileSchema).optional().describe(localFiles ? "Only when there is no folder to read" : "Every file of the skill folder"),
+        name: z15.string().optional().describe("The skill's name; defaults to SKILL.md's frontmatter name and must match it"),
+        spaceId: z15.string().optional().describe("Space for a NEW skill (default: your default space)"),
+        note: z15.string().max(500).optional().describe(`A short change note for this version, shown in the console's history (e.g. "Fix the GA4 step")`),
+        baseVersion: z15.number().int().positive().optional().describe(
           "The version these files were edited from. When given, the publish is refused (SYD-K017) if someone published a newer version since, instead of replacing their changes"
         )
       },
@@ -4163,7 +4891,7 @@ Left out (hidden files are never part of a skill): ${skipped.join(", ")}` : "")
       );
     }
   );
-  server2.registerTool(
+  server.registerTool(
     "list_skills",
     {
       title: "List Skills",
@@ -4175,7 +4903,7 @@ Left out (hidden files are never part of a skill): ${skipped.join(", ")}` : "")
       const { skills } = await apiClient2.get(SKILLS);
       if (!skills.length) {
         return text(
-          `No skills published yet. Publish one with publish_skill; they appear at ${configLink("/docs/skills", await workspaceBase(apiClient2))}`
+          `No skills published yet. Publish one with publish_skill; they appear at ${configLink("/docs/team-setup/skills", await workspaceBase(apiClient2))}`
         );
       }
       return text(
@@ -4185,16 +4913,16 @@ Left out (hidden files are never part of a skill): ${skipped.join(", ")}` : "")
       );
     }
   );
-  server2.registerTool(
+  server.registerTool(
     "install_skill",
     {
       title: "Install Skill",
       description: localFiles ? "Install a skill published to SystemDox onto this computer (default ~/.claude/skills/<name>/). Refuses, naming the files, when a file there was edited since it was installed, unless overwrite is true. Never runs anything." : "Fetch a skill published to SystemDox so you can install it: returns every file and the folder to write them into (default ~/.claude/skills/<name>/). Write each file exactly, then the manifest it shows.",
       inputSchema: {
-        name: z13.string().describe("The skill's name"),
-        version: z13.number().int().positive().optional().describe("A version number (default: the latest)"),
-        target: z13.string().optional().describe("Folder to install into, e.g. a repo's .claude/skills/<name>"),
-        ...localFiles ? { overwrite: z13.boolean().optional().describe("Replace files edited since they were installed") } : {}
+        name: z15.string().describe("The skill's name"),
+        version: z15.number().int().positive().optional().describe("A version number (default: the latest)"),
+        target: z15.string().optional().describe("Folder to install into, e.g. a repo's .claude/skills/<name>"),
+        ...localFiles ? { overwrite: z15.boolean().optional().describe("Replace files edited since they were installed") } : {}
       },
       annotations: { readOnlyHint: !localFiles }
     },
@@ -4249,22 +4977,22 @@ var init_skills2 = __esm({
 });
 
 // src/lib/team-setup-types.ts
-var PARTS, PERSON_ID_RE;
+var PARTS2, PERSON_ID_RE;
 var init_team_setup_types = __esm({
   "src/lib/team-setup-types.ts"() {
     "use strict";
     init_person_values();
-    PARTS = ["hooks", "mcp", "agents", "commands", "instructions"];
+    PARTS2 = ["hooks", "mcp", "agents", "commands", "instructions"];
     PERSON_ID_RE = new RegExp(`^${PERSON_ID}$`);
   }
 });
 
 // src/tools/team-setup.ts
-import { z as z14 } from "zod";
-import { existsSync as existsSync5 } from "fs";
+import { z as z16 } from "zod";
+import { existsSync as existsSync7 } from "fs";
 import { lstat as lstat2 } from "fs/promises";
 import { homedir as homedir4 } from "os";
-import { join as join6, resolve as resolve7 } from "path";
+import { join as join8, resolve as resolve7 } from "path";
 function expandHome2(path) {
   return path.replace(/^~(?=$|[\\/])/, homedir4());
 }
@@ -4290,21 +5018,21 @@ async function readPartDirectory(part, directory) {
     let present = true;
     for (let i = 1; i <= segments.length; i++) {
       const rel = segments.slice(0, i).join("/");
-      if (await isLink(join6(root, ...segments.slice(0, i)))) {
+      if (await isLink(join8(root, ...segments.slice(0, i)))) {
         links.push(rel);
         present = false;
         break;
       }
     }
-    if (present && existsSync5(join6(root, ...segments))) paths.push(path);
+    if (present && existsSync7(join8(root, ...segments))) paths.push(path);
   }
   for (const { dir, md } of layout.folders) {
-    const full = join6(root, dir);
+    const full = join8(root, dir);
     if (await isLink(full)) {
       links.push(dir);
       continue;
     }
-    if (!existsSync5(full)) continue;
+    if (!existsSync7(full)) continue;
     const walked = await walk(full, { skipHidden: true });
     links.push(...walked.links.map((p) => `${dir}/${p}`));
     leftOut.push(...walked.hidden.map((p) => `${dir}/${p}`));
@@ -4343,24 +5071,24 @@ function describePerson(id, person) {
   );
   return lines.join("\n");
 }
-function registerTeamSetupTools(server2, apiClient2, { localFiles }) {
-  const fileSchema = z14.object({
-    path: z14.string().describe(`Path inside the part's folder, forward slashes, e.g. "hooks/hooks.json"`),
-    content: z14.string().describe("The file's full text, exactly as it is")
+function registerTeamSetupTools(server, apiClient2, { localFiles }) {
+  const fileSchema = z16.object({
+    path: z16.string().describe(`Path inside the part's folder, forward slashes, e.g. "hooks/hooks.json"`),
+    content: z16.string().describe("The file's full text, exactly as it is")
   });
-  server2.registerTool(
+  server.registerTool(
     "publish_setup_part",
     {
       title: "Publish Setup Part",
       description: "Publish one part of your team's Claude Code setup to SystemDox: `hooks` (hooks/hooks.json and the scripts/ it calls), `mcp` (.mcp.json), `agents` (agents/*.md), `commands` (commands/*.md) or `instructions` (CLAUDE.md). Every part but instructions makes a new version of the team plugin, which each member accepts at their next update. Publishing hooks, mcp, agents or commands needs the admin role. " + (localFiles ? "Pass `directory`: the server reads only the files the part accepts, byte for byte, and refuses a link, a binary file or a file too large before anything is sent. Never retype the files into `files` when the folder is on this computer." : "Pass every file of the part in `files`, exactly as it is."),
       inputSchema: {
-        part: z14.enum(PARTS).describe("Which part of the setup"),
+        part: z16.enum(PARTS2).describe("Which part of the setup"),
         ...localFiles ? {
-          directory: z14.string().optional().describe(
+          directory: z16.string().optional().describe(
             "The folder on this computer: for hooks, the one holding hooks/hooks.json and scripts/; for mcp, the one holding .mcp.json; for instructions, the one holding CLAUDE.md; for agents or commands, the one holding agents/ or commands/"
           )
         } : {},
-        files: z14.array(fileSchema).optional().describe(localFiles ? "Only when there is no folder to read" : "Every file of the part")
+        files: z16.array(fileSchema).optional().describe(localFiles ? "Only when there is no folder to read" : "Every file of the part")
       },
       annotations: { readOnlyHint: false }
     },
@@ -4390,13 +5118,13 @@ function registerTeamSetupTools(server2, apiClient2, { localFiles }) {
       return text2(lines.join("\n"));
     }
   );
-  server2.registerTool(
+  server.registerTool(
     "resolve_person",
     {
       title: "Resolve Person",
       description: "Read back a person that a team memory names by identifier, written as `con_\u2026` (label), `ctc_\u2026` or `usr_\u2026`: their label, name, phone number and email address, from the vault that holds them. The details are for this session only: never write them into a memory file; the memory keeps the identifier. Writes nothing.",
       inputSchema: {
-        id: z14.string().regex(PERSON_ID_RE, "a con_, ctc_ or usr_ identifier, as written in the memory").describe("The identifier, e.g. con_01JC2Q8Y4M7T0X3K5N9P2R6S8V")
+        id: z16.string().regex(PERSON_ID_RE, "a con_, ctc_ or usr_ identifier, as written in the memory").describe("The identifier, e.g. con_01JC2Q8Y4M7T0X3K5N9P2R6S8V")
       },
       annotations: { readOnlyHint: true }
     },
@@ -4407,14 +5135,14 @@ function registerTeamSetupTools(server2, apiClient2, { localFiles }) {
     }
   );
   if (!localFiles) return;
-  server2.registerTool(
+  server.registerTool(
     "sync_memory",
     {
       title: "Sync Memory",
       description: `Sync one project's team memory on this computer with SystemDox: pull the files the team changed, push the ones changed here, keep both texts of a file changed on both sides. It never answers for a person: a file that still holds a phone number, an email address or a home-folder path is skipped and listed, with the command for the member to run in their own terminal (\`${SYNC_MEMORY_COMMAND}\`). Pass dryRun to see what it would do without writing or sending anything.`,
       inputSchema: {
-        project: z14.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "a project name: lower case letters, digits and -").optional().describe("The project's team memory, e.g. puglieseweb-ltd; needed when the workspace has more than one"),
-        dryRun: z14.boolean().optional().describe("Show what would be pulled, pushed, deleted, conflicted and skipped, and change nothing")
+        project: z16.string().regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "a project name: lower case letters, digits and -").optional().describe("The project's team memory, e.g. puglieseweb-ltd; needed when the workspace has more than one"),
+        dryRun: z16.boolean().optional().describe("Show what would be pulled, pushed, deleted, conflicted and skipped, and change nothing")
       },
       annotations: { readOnlyHint: false }
     },
@@ -4449,28 +5177,34 @@ var init_team_setup = __esm({
 
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-function createServer(apiClient2, { localFiles = false } = {}) {
-  const server2 = new McpServer({
-    name: "systemdox-mcp-server",
-    version: SERVER_VERSION
-  });
-  registerGetGuardrails(server2, apiClient2);
-  registerGetSpecs(server2, apiClient2);
-  registerGetDocs(server2, apiClient2);
-  registerGetTechStack(server2, apiClient2);
-  registerGetPlanningContext(server2, apiClient2);
-  registerGetPlanBoard(server2, apiClient2);
-  registerGetContext(server2, apiClient2);
-  registerGetProjectRules(server2, apiClient2);
-  registerGetPromptTemplates(server2, apiClient2);
-  registerCreateGuardrail(server2, apiClient2);
-  registerUpdateSpec(server2, apiClient2);
-  registerReportDecision(server2, apiClient2);
-  registerCreateProjectRule(server2, apiClient2);
-  registerCreatePromptTemplate(server2, apiClient2);
-  registerSkillTools(server2, apiClient2, { localFiles });
-  registerTeamSetupTools(server2, apiClient2, { localFiles });
-  return server2;
+function createServer(apiClient2, { localFiles = false, instructions, keyProblem: keyProblem2 } = {}) {
+  const server = new McpServer(
+    {
+      name: "systemdox-mcp-server",
+      version: SERVER_VERSION
+    },
+    instructions ? { instructions } : void 0
+  );
+  registerGetGuardrails(server, apiClient2);
+  registerGetSpecs(server, apiClient2);
+  registerGetDocs(server, apiClient2);
+  registerGetTechStack(server, apiClient2);
+  registerGetPlanningContext(server, apiClient2);
+  registerGetPlanBoard(server, apiClient2);
+  registerGetChange(server, apiClient2);
+  registerGetContext(server, apiClient2);
+  registerGetProjectRules(server, apiClient2);
+  registerGetPromptTemplates(server, apiClient2);
+  registerGetTeamSetup(server, apiClient2, { localFiles, keyProblem: keyProblem2 });
+  registerDocumentGraph(server, apiClient2);
+  registerCreateGuardrail(server, apiClient2);
+  registerUpdateSpec(server, apiClient2);
+  registerReportDecision(server, apiClient2);
+  registerCreateProjectRule(server, apiClient2);
+  registerCreatePromptTemplate(server, apiClient2);
+  registerSkillTools(server, apiClient2, { localFiles });
+  registerTeamSetupTools(server, apiClient2, { localFiles });
+  return server;
 }
 var SERVER_VERSION;
 var init_server = __esm({
@@ -4482,7 +5216,10 @@ var init_server = __esm({
     init_get_tech_stack();
     init_get_planning_context();
     init_get_plan_board();
+    init_get_change();
     init_get_context();
+    init_get_team_setup();
+    init_document_graph();
     init_create_guardrail();
     init_update_spec();
     init_report_decision();
@@ -4492,7 +5229,7 @@ var init_server = __esm({
     init_create_prompt_template();
     init_skills2();
     init_team_setup();
-    SERVER_VERSION = true ? "0.1.48" : "0.0.0-dev";
+    SERVER_VERSION = true ? "0.1.50" : "0.0.0-dev";
   }
 });
 
@@ -4505,21 +5242,34 @@ __export(index_exports, {
 });
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 async function main() {
-  await apiClient.validate();
+  const instructions = await sessionInstructions(apiClient, { localFiles: true, keyProblem });
+  const server = createServer(apiClient, { localFiles: true, instructions, keyProblem });
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
-var config, apiClient, server;
+var config, keyProblem, apiClient;
 var init_index = __esm({
-  "src/index.ts"() {
+  async "src/index.ts"() {
     "use strict";
-    init_config();
     init_api_client();
+    init_config();
+    init_session_brief();
+    init_team_setup_files();
     init_server();
     init_server();
-    config = loadConfig();
+    try {
+      config = await loadLocalConfig();
+    } catch (err) {
+      console.error(`SystemDox MCP server: ${err.message}`);
+      keyProblem = keyReason(err.message);
+      try {
+        config = loadConfig(NO_KEY);
+      } catch (urlErr) {
+        console.error(`SystemDox MCP server: ${urlErr.message}`);
+        process.exit(1);
+      }
+    }
     apiClient = new SystemDoxApiClient(config);
-    server = createServer(apiClient, { localFiles: true });
     main();
   }
 });
@@ -4527,10 +5277,6 @@ var init_index = __esm({
 // src/cli.ts
 init_config();
 init_team_setup_files();
-import { readFile as readFile5, writeFile as writeFile6, chmod as chmod2 } from "fs/promises";
-import { existsSync as existsSync6 } from "fs";
-import { homedir as homedir5 } from "os";
-import { join as join7 } from "path";
 import { createInterface } from "readline";
 function prompt(question) {
   const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -4541,158 +5287,10 @@ function prompt(question) {
     });
   });
 }
-async function validateApiKey(apiKey, apiUrl) {
-  try {
-    const res = await fetch(`${apiUrl.replace(/\/+$/, "")}/v1/health`, {
-      headers: {
-        Authorization: `Bearer ${apiKey}`,
-        "X-API-Key": apiKey,
-        Accept: "application/json"
-      }
-    });
-    return res.ok;
-  } catch {
-    return false;
-  }
-}
-function findConfigTargets() {
-  const targets = [];
-  const projectMcp = join7(process.cwd(), ".mcp.json");
-  targets.push({
-    name: "Claude Code (project)",
-    path: projectMcp,
-    detected: true
-    // Always available
-  });
-  const claudeUser = join7(homedir5(), ".claude.json");
-  targets.push({
-    name: "Claude Code (user \u2014 all projects)",
-    path: claudeUser,
-    detected: true
-    // Always available
-  });
-  const cursorProject = join7(process.cwd(), ".cursor", "mcp.json");
-  const cursorDir = join7(process.cwd(), ".cursor");
-  targets.push({
-    name: "Cursor (project)",
-    path: cursorProject,
-    detected: existsSync6(cursorDir)
-  });
-  const vscodeProject = join7(process.cwd(), ".vscode", "mcp.json");
-  const vscodeDir = join7(process.cwd(), ".vscode");
-  targets.push({
-    name: "VS Code (project)",
-    path: vscodeProject,
-    detected: existsSync6(vscodeDir)
-  });
-  const cursorGlobal = join7(homedir5(), ".cursor", "mcp.json");
-  targets.push({
-    name: "Cursor (global)",
-    path: cursorGlobal,
-    detected: existsSync6(join7(homedir5(), ".cursor"))
-  });
-  return targets;
-}
-async function readOrCreateConfig(path) {
-  try {
-    const content = await readFile5(path, "utf-8");
-    return JSON.parse(content);
-  } catch {
-    return { mcpServers: {} };
-  }
-}
-async function writeConfig(path, config2) {
-  const dir = path.substring(0, path.lastIndexOf("/"));
-  if (!existsSync6(dir)) {
-    const { mkdir: mkdir6 } = await import("fs/promises");
-    await mkdir6(dir, { recursive: true });
-  }
-  await writeFile6(path, JSON.stringify(config2, null, 2) + "\n", { mode: 384 });
-  try {
-    await chmod2(path, 384);
-  } catch {
-  }
-}
-function serverEntry(apiKey, apiUrl) {
-  const entry = {
-    command: "npx",
-    args: ["@systemdox/mcp-server"],
-    env: {
-      SYSTEMDOX_API_KEY: apiKey
-    }
-  };
-  if (apiUrl !== API_URL_DEFAULT) {
-    entry.env.SYSTEMDOX_API_URL = apiUrl;
-  }
-  return entry;
-}
-async function setup() {
-  console.log("\n  SystemDox MCP Server Setup\n");
-  const apiKey = await prompt("  Enter your SystemDox API key: ");
-  if (!apiKey) {
-    console.error(
-      "\n  Error: API key is required.\n  Generate one at your SystemDox settings page.\n"
-    );
-    process.exit(1);
-  }
-  const apiUrlInput = await prompt(
-    `  API URL [${API_URL_DEFAULT}]: `
-  );
-  const apiUrl = apiUrlInput || API_URL_DEFAULT;
-  try {
-    requireHttpsApiUrl(apiUrl);
-  } catch (err) {
-    console.error(`
-  Error: ${err.message}
-`);
-    process.exit(1);
-  }
-  console.log("\n  Validating API key...");
-  const valid = await validateApiKey(apiKey, apiUrl);
-  if (!valid) {
-    console.error(
-      "\n  Error: Invalid API key or cannot reach the SystemDox API.\n  Check your key and try again.\n"
-    );
-    process.exit(1);
-  }
-  console.log("  API key validated successfully.\n");
-  const targets = findConfigTargets();
-  const detected = targets.filter((t) => t.detected);
-  console.log("  Available targets:");
-  detected.forEach((t, i) => {
-    console.log(`    ${i + 1}. ${t.name} (${t.path})`);
-  });
-  const choiceInput = await prompt(
-    `
-  Which target? [1-${detected.length}, or 'all']: `
-  );
-  let selected;
-  if (choiceInput.toLowerCase() === "all") {
-    selected = detected;
-  } else {
-    const idx = parseInt(choiceInput, 10) - 1;
-    if (isNaN(idx) || idx < 0 || idx >= detected.length) {
-      console.error("\n  Invalid selection.\n");
-      process.exit(1);
-    }
-    selected = [detected[idx]];
-  }
-  const entry = serverEntry(apiKey, apiUrl);
-  for (const target of selected) {
-    const config2 = await readOrCreateConfig(target.path);
-    config2.mcpServers["systemdox"] = entry;
-    await writeConfig(target.path, config2);
-    console.log(`  Configured: ${target.name}`);
-  }
-  console.log(
-    "\n  Done! Restart your AI coding tool to activate the SystemDox MCP server.\n  The server provides 20 tools: get_context, get_checks,\n  get_project_rules, get_prompt_templates, get_specs, get_docs,\n  get_tech_stack, get_planning_context, get_plan_board, create_check,\n  create_project_rule, create_prompt_template, update_spec,\n  report_decision, publish_skill, list_skills, install_skill,\n  publish_setup_part, resolve_person, sync_memory.\n\n  get_guardrails and create_guardrail remain registered as deprecated\n  aliases of get_checks and create_check \u2014 existing configs keep working.\n"
-  );
-  return { apiKey, apiUrl };
-}
 var args = process.argv.slice(2);
 var command = args[0];
 if (command === "setup") {
-  Promise.resolve().then(() => (init_setup_team(), setup_team_exports)).then(async ({ parseSetupArgs: parseSetupArgs2, runTeamSetupCommand: runTeamSetupCommand2 }) => {
+  Promise.all([Promise.resolve().then(() => (init_setup_team(), setup_team_exports)), Promise.resolve().then(() => (init_setup_mcp(), setup_mcp_exports))]).then(async ([{ parseSetupArgs: parseSetupArgs2, runTeamSetupCommand: runTeamSetupCommand2 }, { setupMcpServer: setupMcpServer2 }]) => {
     let teamArgs;
     try {
       teamArgs = parseSetupArgs2(args.slice(1));
@@ -4702,8 +5300,13 @@ if (command === "setup") {
 `);
       process.exit(1);
     }
-    const key = await setup();
-    return runTeamSetupCommand2(teamArgs, key, {
+    const step = await setupMcpServer2({
+      out: console.log,
+      err: console.error,
+      ask: (question) => prompt(question)
+    });
+    if (step.code !== 0) return step.code;
+    return runTeamSetupCommand2(teamArgs, step, {
       out: console.log,
       ask: (question) => prompt(question),
       terminal: !!process.stdin.isTTY
@@ -4763,15 +5366,18 @@ if (command === "setup") {
     systemdox-mcp-server --help   Show this help message
 
   Environment variables:
-    SYSTEMDOX_API_KEY             Your SystemDox API key (required; plugin-path and
-                                  marketplace-auth also read
-                                  ~/.claude/systemdox/credentials.json)
+    SYSTEMDOX_API_KEY             Your SystemDox API key. When it is not set, every
+                                  command reads ~/.claude/systemdox/credentials.json,
+                                  where setup stores the key (and nowhere else: not
+                                  in your AI tool's MCP config)
+    SYSTEMDOX_WORKSPACE           The workspace whose key to use when
+                                  credentials.json holds several
     SYSTEMDOX_API_URL             API URL (default: ${API_URL_DEFAULT})
     SYSTEMDOX_CACHE_TTL           Cache TTL in seconds (default: 300)
     SYSTEMDOX_DEFAULT_ORG         Default GitHub org
 `);
 } else if (!command) {
-  Promise.resolve().then(() => init_index());
+  init_index();
 } else {
   console.error(`  Unknown command: ${command}
   Run 'systemdox-mcp-server --help' for usage.`);