@systemdox/mcp-server 0.1.49 → 0.1.51

package/dist/install-skill.js

@@ -63,14 +63,6 @@ var SystemDoxApiClient = class {
     this.config = config;
     this.cache = new ResponseCache(config.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();
@@ -84,8 +76,8 @@ var SystemDoxApiClient = class {
   }
   /** 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();
   }
@@ -115,8 +107,8 @@ var SystemDoxApiClient = class {
   // 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)}`);
@@ -220,14 +212,15 @@ var SystemDoxApiClient = class {
     }
     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
     });
   }
 };
@@ -274,6 +267,7 @@ import { existsSync } from "fs";
 import { homedir } from "os";
 import { dirname, join, relative, resolve, sep } from "path";
 var MANIFEST_FILE = ".systemdox-skill.json";
+var PLUGIN_MANIFEST_FOLDER = ".claude-plugin";
 var MAX_FILE_BYTES = 256 * 1024;
 var MAX_TOTAL_BYTES = 1024 * 1024;
 var NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -297,7 +291,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 defaultSkillDir(name) {
   return join(homedir(), ".claude", "skills", name);
@@ -391,6 +385,9 @@ async function installSkill(version, dest, { overwrite = false } = {}) {
     keptEdited
   };
 }
+function afterInstall(skillMd) {
+  return `No restart is needed: a running Claude Code session picks it up. If one does not list it yet, read ${skillMd} and follow it, or run /reload-skills.`;
+}
 function describeInstall(name, r) {
   const lines = [
     `Installed ${name} version ${r.version} into ${r.dest} (${r.written.length} file(s)).`
@@ -400,7 +397,7 @@ function describeInstall(name, r) {
     lines.push(`Kept, edited here and no longer in the skill: ${r.keptEdited.join(", ")}`);
   }
   if (r.keptUntracked.length) lines.push(`Kept, added here: ${r.keptUntracked.join(", ")}`);
-  lines.push("Start a new Claude Code session to load it.");
+  lines.push(afterInstall(join(r.dest, "SKILL.md")));
   return lines.join("\n");
 }
 

package/dist/lib/api-client.d.ts

@@ -17,16 +17,15 @@ export declare class SystemDoxApiClient {
     private config;
     private cache;
     constructor(config: ServerConfig);
-    validate(): Promise<void>;
     get<T>(path: string, params?: Record<string, string>): Promise<T>;
     /** A read that skips the cache: an install must take the version that is
      * latest now, not the one cached before someone published another. */
-    getFresh<T>(path: string): Promise<T>;
+    getFresh<T>(path: string, signal?: AbortSignal): Promise<T>;
     post<T>(path: string, body: unknown): Promise<T>;
     put<T>(path: string, body: unknown): Promise<T>;
     private mutate;
     /** getOwnTeamSetup: the key's own workspace, named in `workspace`. */
-    getOwnTeamSetup(): Promise<TeamSetup>;
+    getOwnTeamSetup(signal?: AbortSignal): Promise<TeamSetup>;
     getTeamSetup(workspace: string): Promise<TeamSetup>;
     getMarketplace(workspace: string): Promise<Marketplace>;
     getPart(workspace: string, part: PartName): Promise<PartDetail>;

package/dist/lib/api-client.js

@@ -60,14 +60,6 @@ var SystemDoxApiClient = class {
     this.config = config;
     this.cache = new ResponseCache(config.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();
@@ -81,8 +73,8 @@ var SystemDoxApiClient = class {
   }
   /** 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();
   }
@@ -112,8 +104,8 @@ var SystemDoxApiClient = class {
   // 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)}`);
@@ -217,14 +209,15 @@ var SystemDoxApiClient = class {
     }
     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
     });
   }
 };

package/dist/lib/context-builder.js

@@ -403,16 +403,22 @@ async function hydrate(api, item, 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;
@@ -619,12 +625,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 text = 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, 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 };
 }
 export {

package/dist/lib/session-brief.d.ts

@@ -0,0 +1,59 @@
+import type { SystemDoxApiClient } from "./api-client.js";
+import type { TeamSetup } from "./team-setup-types.js";
+/** Claude Code cuts a server's instructions at 2,048 characters in older versions and 4,096 now: this fits both. */
+export declare const INSTRUCTIONS_MAX = 2000;
+/**
+ * The read that a session's start waits for, at most. Sessions start rarely, so
+ * the read is usually a cold one: in prod on 2026-11-04 the team setup function's
+ * cold start alone took 2 to 2.9 s, before the authoriser and the network, while a
+ * warm read took 0.65 s. A bound that fits only a warm read would fail the common
+ * case.
+ */
+export declare const BRIEF_TIMEOUT_MS = 8000;
+/** What the local server sends when this computer has no key: the API refuses it. */
+export declare const NO_KEY = "no-key-on-this-computer";
+declare const SETUP_COMMAND = "npx -y @systemdox/mcp-server setup";
+declare const CANNOT_SEE: string;
+/**
+ * The reason a key could not be loaded, as words of our own. The error's message
+ * goes to the server's log: it can hold a path on this computer, a long list of
+ * workspaces or a value from the environment, and none of that belongs in a system
+ * prompt.
+ */
+export declare function keyReason(message: string): string;
+export interface ComputerState {
+    missing: string[];
+    behind: {
+        name: string;
+        here: number;
+        latest: number;
+    }[];
+    notFromSystemDox: string[];
+    pluginInstalled: boolean;
+    pluginVersion?: string;
+}
+/** The team skills against this computer's folders. Reads only. */
+export declare function computerState(setup: TeamSetup): Promise<ComputerState>;
+/** Whether `setup` would add anything: a skill outside the default space is in no plugin. */
+export declare function hasPersonParts(setup: TeamSetup): boolean;
+/**
+ * What the local server adds, within `room`: nothing when this computer lacks
+ * nothing. The sentences are fixed and the lists take what is left, so a sentence
+ * is never cut. If the fixed sentences do not fit, the least urgent line goes whole.
+ */
+export declare function localSection(setup: TeamSetup, state: ComputerState, room: number): string;
+export interface BriefOptions {
+    localFiles?: boolean;
+    /** Why the local server has no key, when it has none. */
+    keyProblem?: string;
+    timeoutMs?: number;
+}
+/** The team setup, or what to tell a session about why it could not be read. */
+export declare function readTeamSetup(apiClient: Pick<SystemDoxApiClient, "getOwnTeamSetup">, { keyProblem, timeoutMs }?: BriefOptions): Promise<{
+    setup: TeamSetup;
+} | {
+    problem: string;
+}>;
+/** The `instructions` of an `initialize` answer. Never throws. */
+export declare function sessionInstructions(apiClient: Pick<SystemDoxApiClient, "getOwnTeamSetup">, options?: BriefOptions): Promise<string>;
+export { CANNOT_SEE, SETUP_COMMAND };

package/dist/lib/session-brief.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+// src/lib/session-brief.ts
+import { existsSync as existsSync2 } from "fs";
+import { readFile as readFile3 } from "fs/promises";
+import { join as join3 } from "path";
+
+// src/lib/skills.ts
+import { createHash } from "crypto";
+import { lstat, mkdir, readdir, readFile, rm, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { homedir } from "os";
+import { dirname, join, relative, resolve, sep } from "path";
+var MANIFEST_FILE = ".systemdox-skill.json";
+var MAX_FILE_BYTES = 256 * 1024;
+var MAX_TOTAL_BYTES = 1024 * 1024;
+function defaultSkillDir(name) {
+  return join(homedir(), ".claude", "skills", name);
+}
+
+// src/lib/team-setup-files.ts
+import { execFile } from "child_process";
+import { chmod, mkdir as mkdir2, readFile as readFile2, rename, rm as rm2, writeFile as writeFile2 } from "fs/promises";
+import { homedir as homedir2, userInfo } from "os";
+import { dirname as dirname2, join as join2 } from "path";
+import { promisify } from "util";
+function homeDir() {
+  return homedir2();
+}
+var run = promisify(execFile);
+
+// src/lib/session-brief.ts
+var INSTRUCTIONS_MAX = 2e3;
+var BRIEF_TIMEOUT_MS = 8e3;
+var NO_KEY = "no-key-on-this-computer";
+var SETUP_COMMAND = "npx -y @systemdox/mcp-server setup";
+var 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.`;
+var 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.";
+var 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.";
+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 readJsonQuietly(path) {
+  try {
+    return JSON.parse(await readFile3(path, "utf8"));
+  } catch {
+    return void 0;
+  }
+}
+async function computerState(setup) {
+  const id = `${setup.workspace}-setup@systemdox-${setup.workspace}`;
+  const installed = await readJsonQuietly(join3(homeDir(), ".claude", "plugins", "installed_plugins.json"));
+  const entries = installed?.plugins?.[id];
+  const entry = Array.isArray(entries) ? entries.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 (!existsSync2(dir)) {
+      if (!(pluginCurrent && setup.plugin?.skills?.[skill.name] !== void 0)) state.missing.push(skill.name);
+      continue;
+    }
+    const manifest = await readJsonQuietly(join3(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");
+}
+var MORE = (n) => `${n} more (get_team_setup lists them)`;
+var LIST_MIN = `all ${MORE(100)}`.length;
+function listWithin(items, room) {
+  const whole = items.join(", ");
+  if (whole.length <= room) return whole;
+  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(text, section) {
+  const whole = section ? `${text}
+
+${section}` : text;
+  if (whole.length <= INSTRUCTIONS_MAX) return whole;
+  return text.length <= INSTRUCTIONS_MAX ? text : `${text.slice(0, INSTRUCTIONS_MAX - 1)}\u2026`;
+}
+async function readTeamSetup(apiClient, { keyProblem, timeoutMs = BRIEF_TIMEOUT_MS } = {}) {
+  if (keyProblem) return { problem: noKey(keyProblem) };
+  try {
+    const setup = await apiClient.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(apiClient, options = {}) {
+  const read = await readTeamSetup(apiClient, options);
+  if ("problem" in read) return read.problem;
+  const text = read.setup.sessionBrief?.text ?? olderApi(read.setup);
+  try {
+    if (!options.localFiles) return fit(text, read.setup.sessionBrief?.skills?.length ? CANNOT_SEE : "");
+    const room = INSTRUCTIONS_MAX - text.length - 2;
+    return fit(text, localSection(read.setup, await computerState(read.setup), room));
+  } catch {
+    return fit(text, "");
+  }
+}
+export {
+  BRIEF_TIMEOUT_MS,
+  CANNOT_SEE,
+  INSTRUCTIONS_MAX,
+  NO_KEY,
+  SETUP_COMMAND,
+  computerState,
+  hasPersonParts,
+  keyReason,
+  localSection,
+  readTeamSetup,
+  sessionInstructions
+};

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

@@ -8,6 +8,7 @@ import { homedir } from "os";
 import { dirname, join, relative, resolve, sep } from "path";
 var MANIFEST_FILE = ".systemdox-skill.json";
 var ENTRY_FILE = "SKILL.md";
+var PLUGIN_MANIFEST_FOLDER = ".claude-plugin";
 var MAX_FILES = 100;
 var MAX_FILE_BYTES = 256 * 1024;
 var MAX_TOTAL_BYTES = 1024 * 1024;
@@ -32,7 +33,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);
@@ -181,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)).`
@@ -190,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 {
@@ -200,6 +204,7 @@ export {
   MAX_FILE_BYTES,
   MAX_TOTAL_BYTES,
   SkillInstallRefused,
+  afterInstall,
   defaultSkillDir,
   describeInstall,
   fenceFor,

package/dist/lib/team-setup-types.d.ts

@@ -90,6 +90,24 @@ export interface TeamSetup {
     parts: Record<string, number>;
     skills: string[];
     memory: MemoryProjectSummary[];
+    /** Absent on an API older than ADR-223. */
+    sessionBrief?: SessionBrief;
+}
+/** What every session is told (ADR-223, specs/changes/session-brief/contract.md). */
+export interface SessionBrief {
+    text: string;
+    /** What a session may install by itself: in the default space, and unable to run anything by itself. */
+    skills: {
+        name: string;
+        description: string;
+        latestVersion: number;
+    }[];
+    /** The rest: they reach a computer only through the person. Only the name is repeated. */
+    heldSkills: {
+        name: string;
+        reason: string;
+    }[];
+    omittedSkills: number;
 }
 /** `{path: sha256}`. */
 export type Manifest = Record<string, string>;

package/dist/plugin-path.js

@@ -67,14 +67,6 @@ var SystemDoxApiClient = class {
     this.config = config;
     this.cache = new ResponseCache(config.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();
@@ -88,8 +80,8 @@ var SystemDoxApiClient = class {
   }
   /** 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();
   }
@@ -119,8 +111,8 @@ var SystemDoxApiClient = class {
   // 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)}`);
@@ -224,14 +216,15 @@ var SystemDoxApiClient = class {
     }
     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
     });
   }
 };

package/dist/server.d.ts

@@ -5,10 +5,14 @@ export interface ServerOptions {
      * and write the skill folder there. The hosted server never touches a disk
      * (ADR-216 §2.2). */
     localFiles?: boolean;
+    /** What the server tells every session in its `initialize` answer (ADR-223). */
+    instructions?: string;
+    /** Why the local server has no key, when it has none. */
+    keyProblem?: string;
 }
 /**
  * Build a SystemDox MCP server with all tools registered against the given
  * API client. Shared by the stdio entry point (index.ts) and the hosted
  * Streamable HTTP entry point (http.ts).
  */
-export declare function createServer(apiClient: SystemDoxApiClient, { localFiles }?: ServerOptions): McpServer;
+export declare function createServer(apiClient: SystemDoxApiClient, { localFiles, instructions, keyProblem }?: ServerOptions): McpServer;