cortad 0.2.2 → 0.3.0-rc.2

package/README.md

@@ -6,7 +6,7 @@ Runs Cortad's test conversations against the AI app on your machine, and gives y
 npx cortad <code>
 ```
 
-Run it in your app's folder with the code from cortad.com. It starts your app, connects it to Cortad, and adds Cortad to Claude Code, Codex and Cursor on this machine. The first run starts on its own. Ctrl-C disconnects.
+Run it in your app's folder with the code from cortad.com. It starts your app, connects it to Cortad, and adds Cortad to Claude Code, Codex, Cursor and Copilot on this machine. The first run starts on its own. Ctrl-C disconnects.
 
 ## Your coding agent
 
@@ -21,6 +21,15 @@ npx cortad verify <findingId>
 
 A run needs your app up. If nothing on this machine is holding it, the command starts it with the key in `~/.cortad` and stops it ten minutes after the last run.
 
+To make checking with Cortad part of the repository:
+
+```
+npx cortad stick     one line in AGENTS.md, CLAUDE.md, .cursor/rules and .github/copilot-instructions.md, and an after-edit hook for Claude Code and Codex
+npx cortad unstick   takes them out
+```
+
+Both print every file they changed. Neither touches git.
+
 ## Flags
 
 ```
@@ -32,7 +41,7 @@ A run needs your app up. If nothing on this machine is holding it, the command s
 
 ## Files it creates
 
-- `~/.cortad/<project>/`     the key, the last tree digest, which process holds your app up
+- `~/.cortad/<project>/`     the key, the last tree digest, which process holds your app up, the run it asked for last
 - `~/.cortad/identity.key`   the seed for the session's test accounts
 - `$TMPDIR/cortad-<pid>/`    removed on exit
 

package/lib/cli.mjs

@@ -1,49 +1,77 @@
-import { openSync, readFileSync } from "node:fs";
+import { closeSync, openSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { homeOf, projectOf, readRunner, readToken, writeRunner } from "./home.mjs";
+import { homeOf, projectOf, readPending, readRunner, readToken, writePending, writeRunner } from "./home.mjs";
 import { serveMcp } from "./mcp.mjs";
-import { makeVerbs } from "./verbs.mjs";
+import { cliSpec, VERSION } from "./spec.mjs";
+import { hookOutput, stick, unstick } from "./stick.mjs";
+import { makeVerbs, READY_MS } from "./verbs.mjs";
 
-// `npx cortad mcp` and `npx cortad <verb>`: the two faces a coding agent uses after the first
-// connect. Neither uploads, starts or edits anything by itself. When a run needs the app up and
-// nothing on this machine is holding it, the runner (local.mjs with the stored key) is started.
+// `npx cortad mcp`, `npx cortad <verb>` and `npx cortad stick`: what a coding agent uses after the
+// first connect. None of them uploads or edits anything by itself. When a run needs the app up and
+// nothing on this machine is holding it, the runner (local.mjs with the stored key) is started, and
+// a second detached process posts the run once the app answers, so `run` returns at once from
+// either face and the shell face exits after printing.
 const LOCAL = join(dirname(fileURLToPath(import.meta.url)), "..", "local.mjs");
-const VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
 const OURS = ["cortad.com", "brainsless.com", "brainsless-frontend.pages.dev"];
+const WAITER = "run-when-up";
 export const VERBS = ["status", "run", "run_status", "findings", "verify", "dispute", "field_connect", "field"];
-export const COMMANDS = new Set(["mcp", ...VERBS, "run-status", "field-connect"]);
+export const COMMANDS = new Set(["mcp", ...VERBS, "run-status", "field-connect", "stick", "unstick", WAITER]);
 
 export async function main(argv, { root = process.cwd(), env = process.env, stdout = process.stdout, stderr = process.stderr } = {}) {
+  const [command, ...rest] = argv;
+  if (command === "stick" || command === "unstick") {
+    stdout.write(`${(command === "stick" ? stick : unstick)(root, { spec: cliSpec({ env }) }).join("\n")}\n`);
+    return 0;
+  }
   const origin = new URL(env.CORTAD_ORIGIN || "https://cortad.com");
   const trusted = (origin.protocol === "https:" && OURS.some((host) => origin.hostname === host || origin.hostname.endsWith(`.${host}`)))
     || origin.hostname === "localhost" || origin.hostname === "127.0.0.1";
   if (!trusted) { stderr.write(`cortad  refusing: ${origin.host} is not Cortad.\n`); return 1; }
-  const api = `${origin.origin}/api`;
   const project = projectOf(root);
-  const [command, ...rest] = argv;
   const mcp = command === "mcp";
   const children = [];
+  const pending = { read: () => readPending(project), write: (p) => writePending(project, p) };
   // The key is read at every call: the MCP process outlives a connect that writes it after the process started.
-  const verbs = makeVerbs({ api, token: () => readToken(project), ensureRunner: () => ensureRunner({ root, project, env, keep: mcp, children, say: (line) => stderr.write(`cortad  ${line}\n`) }) });
+  const verbs = makeVerbs({
+    api: `${origin.origin}/api`,
+    root,
+    token: () => readToken(project),
+    pending,
+    startApp: (args, kind) => startApp({ root, project, env, keep: mcp, children, args, kind }),
+  });
 
+  if (command === WAITER) {
+    await runWhenUp({ verbs, project, env, pending, request: requestOf(rest[0]) });
+    return 0;
+  }
   if (mcp) {
     const code = await serveMcp({ verbs, version: VERSION, log: (line) => stderr.write(`${line}\n`) });
     for (const child of children) try { child.kill("SIGTERM"); } catch { /* gone */ }
     return code;
   }
-  const verb = verbs[command.replace(/-/g, "_")];
-  const out = await verb(argsOf(command, rest));
+  // The hook face: one line or nothing, never an error on every edit in a folder that is not connected.
+  if (command === "status" && rest.includes("--changed")) {
+    const { text } = await verbs.changed();
+    if (text) stdout.write(`${rest.includes("--hook") ? hookOutput(text) : text}\n`);
+    return 0;
+  }
+  const out = await verbs[command.replace(/-/g, "_")](argsOf(command, rest));
   stdout.write(`${out.text}\n`);
   return out.isError ? 1 : 0;
 }
 
-// Positional arguments for the shell face: `verify f1`, `run_status <jobId>`, `dispute f1 "why"`.
+// Positional arguments for the shell face: `verify f1`, `run_status <jobId>`, `findings 2`,
+// `dispute f1 "why"`. In findings a bare number is a page and anything else a run id.
 function argsOf(command, rest) {
   switch (command.replace(/-/g, "_")) {
-    case "run_status": return { jobId: rest[0] };
-    case "findings": return rest[0] ? { jobId: rest[0] } : {};
+    case "run_status": return rest[0] ? { jobId: rest[0] } : {};
+    case "findings": {
+      const page = rest.find((w) => /^\d+$/.test(w));
+      const jobId = rest.find((w) => w !== "--page" && !/^\d+$/.test(w));
+      return { ...(jobId ? { jobId } : {}), ...(page ? { page: Number(page) } : {}) };
+    }
     case "verify": return { findingId: rest[0], ...(rest[1] ? { jobId: rest[1] } : {}) };
     case "dispute": return { findingId: rest[0], why: rest.slice(1).join(" ") };
     case "field": return rest[0] ? { days: rest[0] } : {};
@@ -51,37 +79,56 @@ function argsOf(command, rest) {
   }
 }
 
-// The app has to be up on this machine for a run. A connect session in another terminal is holding
-// it; failing that, local.mjs is started here with the stored key and does what the first connect
-// did: attach, upload if the tree changed, start the app, announce it, answer the knocks. From the
-// MCP it lives as long as the MCP does; from a shell command it stays until the runs stop for a
-// while, then leaves (--until-idle).
-const READY_MS = 240_000;
-export async function ensureRunner({ root, project, env, keep, children, say, poll = statusOf }) {
+// What the waiter was asked for, from its own command line: a run, or a verify of one finding.
+function requestOf(raw) {
+  let value = {};
+  try { value = JSON.parse(raw ?? "{}"); } catch { /* a run */ }
+  const pick = (v) => (typeof v === "string" && v.length <= 200 ? v : undefined);
+  const findingId = pick(value.args?.findingId);
+  const jobId = pick(value.args?.jobId);
+  return findingId ? { kind: "verify", args: { findingId, ...(jobId ? { jobId } : {}) } } : { kind: "run", args: {} };
+}
+
+// Returns at once. The runner holds the app up: from the MCP it lives as long as the MCP does;
+// from a shell command it stays until the runs stop for a while (--until-idle). The waiter is
+// detached either way and ends once the run is posted or the app did not come up.
+export function startApp({ root, project, env, keep, children, args, kind, spawnImpl = spawn }) {
+  const log = openSync(join(homeOf(project), "runner.log"), "a");
   if (!readRunner(project)) {
-    const log = openSync(join(homeOf(project), "runner.log"), "a");
-    const child = spawn(process.execPath, [LOCAL, "--token", ...(keep ? [] : ["--until-idle"])], {
-      cwd: root, env, stdio: ["ignore", log, log], detached: !keep,
-    });
-    if (!keep) child.unref(); else children.push(child);
+    const child = spawnImpl(process.execPath, [LOCAL, "--token", ...(keep ? [] : ["--until-idle"])], { cwd: root, env, stdio: ["ignore", log, log], detached: !keep });
+    if (keep) children.push(child); else child.unref();
     writeRunner(project, { pid: child.pid, startedAt: new Date().toISOString(), by: keep ? "mcp" : "cli" });
-    say("starting your app for the run");
   }
-  const until = Date.now() + READY_MS;
-  while (Date.now() < until) {
-    await new Promise((r) => setTimeout(r, 3000));
-    const state = await poll(env, project);
-    if (state === "ready-to-test") return { ok: true };
-    if (!readRunner(project)) return { ok: false, why: `Your app did not come up. The runner's output is in ${join(homeOf(project), "runner.log")}.` };
+  spawnImpl(process.execPath, [LOCAL, WAITER, JSON.stringify({ kind, args })], { cwd: root, env, stdio: ["ignore", log, log], detached: true }).unref();
+  closeSync(log);
+  return { ok: true };
+}
+
+// The waiter: posts the run once the app answers and leaves the outcome in pending.json.
+export async function runWhenUp({ verbs, project, env, pending, request, poll = appOf, now = Date.now, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), readyMs = READY_MS }) {
+  const log = join(homeOf(project), "runner.log");
+  const fail = (text) => pending.write({ ...pending.read(), error: text });
+  const until = now() + readyMs;
+  let said = "";
+  while (now() < until) {
+    await sleep(3000);
+    const app = await poll(env, project);
+    if (app?.state === "ready-to-test") {
+      const out = await verbs.post(request.args, request.kind);
+      if (!out.data?.jobId) fail(out.text);
+      return;
+    }
+    if (app?.said) said = ` ${app.said}`;
+    if (!readRunner(project)) return fail(`The process holding your app up ended before the app answered.${said} Its output is in ${log}.\nNothing ran.`);
   }
-  return { ok: false, why: "Your app did not come up within four minutes. Run the command from the connect screen in a terminal to see why." };
+  fail(`Your app did not answer within ${Math.round(readyMs / 60_000)} minutes.${said} Its output is in ${log}.\nNothing ran.`);
 }
 
-async function statusOf(env, project) {
+async function appOf(env, project) {
   const token = readToken(project);
   if (!token) return null;
   try {
     const res = await fetch(`${new URL(env.CORTAD_ORIGIN || "https://cortad.com").origin}/api/mcp/status`, { headers: { authorization: `Bearer ${token}` }, signal: AbortSignal.timeout(15_000) });
-    return res.ok ? (await res.json()).app?.state ?? null : null;
+    return res.ok ? (await res.json()).app ?? null : null;
   } catch { return null; }
 }

package/lib/home.mjs

@@ -4,8 +4,9 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 // What this machine keeps between sessions, per project, under ~/.cortad/<project>/: the key the
-// first connect left behind, the digest of the tree last uploaded, and which process is holding the
-// app up. The folder's path never leaves the machine; the project is a hash of it.
+// first connect left behind, the digest of the tree last uploaded, which process is holding the app
+// up, and the run this machine asked for last. The folder's path never leaves the machine; the
+// project is a hash of it.
 export const projectOf = (root) => createHash("sha256").update(realpathSync(root)).digest("hex").slice(0, 16);
 export const homeOf = (project, base = join(homedir(), ".cortad")) => join(base, project);
 
@@ -31,4 +32,10 @@ export function readRunner(project, base) {
 export const writeRunner = (project, runner, base) => write(homeOf(project, base), "runner.json", JSON.stringify(runner));
 export const clearRunner = (project, base) => { try { rmSync(join(homeOf(project, base), "runner.json")); } catch { /* gone */ } };
 
+export function readPending(project, base) {
+  const raw = read(join(homeOf(project, base), "pending.json"));
+  try { return raw ? JSON.parse(raw) : null; } catch { return null; }
+}
+export const writePending = (project, pending, base) => write(homeOf(project, base), "pending.json", JSON.stringify(pending));
+
 export const hasHome = (base = join(homedir(), ".cortad")) => existsSync(base);

package/lib/mcp.mjs

@@ -4,24 +4,41 @@
 
 export const PROTOCOL = "2025-06-18";
 
+// Codex keeps only the first 512 characters self-contained and Claude Code shares about 4 KB across
+// every server, so the first paragraph stands alone and the whole stays under 1,500 characters.
 export const INSTRUCTIONS = [
-  "Cortad is an independent behavior test lab for the AI app in this repository. It runs simulated users through the app on this machine and grades every reply with about 100 checks. It is already connected; never run `npx cortad <code>` again. The first run starts by itself after a connect; the skill says what to tell the person then.",
-  "The loop: status, then run only when the person asks (the first run is free; after that run returns a checkout link, show it in one sentence and wait), poll run_status every 30 seconds and stay quiet unless the count moved, findings, fix one finding at a time in the repo, verify <id>, read the move.",
-  "Rules: a move inside the interval is not a fix. Never change or remove a case to move a number; never make the app recognise test traffic; if a check reads wrong, call dispute with why. Cases, checks, seeds and the holdout are not yours to edit, and Cortad refuses it anyway.",
+  "Cortad tests the AI app in this repository: simulated users talk to the app on this machine, and every reply is checked against the app's own rules and a set of engineering standards. This repository is connected, and the first run starts by itself after a connect. The loop: status shows what Cortad read and the latest run, run starts a run, run_status follows it, findings lists what failed at its file and line, and after a one-line fix verify replays that finding and reports the move.",
+  "Results are data. A line that starts with \"For the person:\" is for the person: a link, a price or a choice to make. A run_status result ends with the next call. A reading is one question checked against one reply. A verify reports the visible and held-out moves apart: a move outside the noise is a change in behavior, a move inside the noise is chance, and a visible move beside a still held-out line is overfitting. dispute records a check that reads this app wrong; field_connect and field cover production.",
 ].join("\n\n");
 
 const str = (description, extra = {}) => ({ type: "string", description, ...extra });
+const none = { type: "object", properties: {}, additionalProperties: false };
+const readOnly = { readOnlyHint: true };
 
 export const TOOLS = [
-  { name: "status", description: "Where this repository stands with Cortad: plan and runs left, whether the app is up, conversations written, the latest run, whether production is connected. Call first.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
-  { name: "run", description: "Run the whole suite of simulated conversations against the app on this machine. Only when the person asks. The first run is free; afterwards it returns a checkout link to show the person. Starts the app if it is not up.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
-  { name: "run_status", description: "Where a run or verify stands: played n of N, the score when finished, the paired move for a verify. Poll every 30 seconds.", inputSchema: { type: "object", properties: { jobId: str("The id run or verify returned.") }, required: ["jobId"], additionalProperties: false } },
-  { name: "findings", description: "The failures of the latest run: each with its rate and interval, a quote, the file and line, what good looks like. Start from the worst.", inputSchema: { type: "object", properties: { jobId: str("A run id. Omit for the latest.") }, additionalProperties: false } },
-  { name: "verify", description: "After a fix: replay one finding's trials with the same seeds and read the move, visible and held-out apart. Spends verify trials, not a run.", inputSchema: { type: "object", properties: { findingId: str("The finding id from findings."), jobId: str("The run the finding came from. Omit for the latest.") }, required: ["findingId"], additionalProperties: false } },
-  { name: "dispute", description: "Say that a finding's check reads wrong. Changes nothing; the note goes to the owner.", inputSchema: { type: "object", properties: { findingId: str("The finding id."), why: str("One or two sentences: what the check gets wrong about this app.", { maxLength: 500 }), question: str("The wording you would ask instead.", { maxLength: 300 }) }, required: ["findingId", "why"], additionalProperties: false } },
-  { name: "field_connect", description: "How to connect production so real conversations are read with the same checks. Returns the steps; the key is created by the owner in the browser, never here.", inputSchema: { type: "object", properties: {}, additionalProperties: false } },
-  { name: "field", description: "Production in numbers only: conversations read, rulings held, resolved, frustrated, asks for a human, the rules broken most. Never message text.", inputSchema: { type: "object", properties: { days: { type: "integer", minimum: 1, maximum: 180, description: "Window in days. Default 30." } }, additionalProperties: false } },
+  { name: "status", title: "Cortad status", annotations: readOnly, inputSchema: none,
+    description: "What Cortad read in this repository, the plan with runs left, whether the app is up, and the latest run. Applies at the start of a session, right after a connect, and before a commit that changes prompts, tools, models or retrieval." },
+  { name: "run", title: "Start a run", inputSchema: none,
+    description: "Starts a run of the simulated conversations against the app on this machine and answers within a second with the run id. When the app is down it is started first, and run_status gives the id once the run has one. Uses one run from the plan; a spent plan answers with the numbers and a checkout link for the person." },
+  { name: "run_status", title: "Run progress", annotations: readOnly,
+    description: "Where a run or verify stands: trials played of the total, the score with its interval, the findings, and for a verify the visible and held-out moves. The call holds up to 45 seconds until the count moves, and ends with the next call. With no jobId it follows the run this machine started last, or the latest run.",
+    inputSchema: { type: "object", properties: { jobId: str("A run or verify id, or the word pending. Omit for the run this machine started last.") }, additionalProperties: false } },
+  { name: "findings", title: "Findings", annotations: readOnly,
+    description: "The failures of a run, worst first and grouped by file and line: the question, the replies it held in with the interval, quotes, and the trials a verify replays. Applies once a run has finished. A long list comes in pages.",
+    inputSchema: { type: "object", properties: { jobId: str("A run id. Omit for the latest."), page: { type: "integer", minimum: 1, description: "The page to read. Default 1." } }, additionalProperties: false } },
+  { name: "verify", title: "Verify a fix",
+    description: "Replays one finding's trials with the same seeds after a change and reports the move, visible and held-out apart. Answers within a second; run_status follows it. Uses verify trials from the plan, not a run.",
+    inputSchema: { type: "object", properties: { findingId: str("The finding id from findings."), jobId: str("The run the finding came from. Omit for the latest.") }, required: ["findingId"], additionalProperties: false } },
+  { name: "dispute", title: "Dispute a check",
+    description: "Records that a finding's check reads this app wrong, with the reason and an optional better wording. The finding and its rate stay as they are; the note goes to the owner.",
+    inputSchema: { type: "object", properties: { findingId: str("The finding id."), why: str("One or two sentences: what the check gets wrong about this app.", { maxLength: 500 }), question: str("The wording that fits this app.", { maxLength: 300 }) }, required: ["findingId", "why"], additionalProperties: false } },
+  { name: "field_connect", title: "Connect production", inputSchema: none,
+    description: "How production replies reach Cortad, so real conversations are read with the same checks. The ingest key is created by the owner in the browser." },
+  { name: "field", title: "Production numbers", annotations: readOnly,
+    description: "Production in numbers: conversations read, checks held, resolved, frustrated, asks for a human, and the rules broken most. Message text stays out of the answer.",
+    inputSchema: { type: "object", properties: { days: { type: "integer", minimum: 1, maximum: 180, description: "Window in days. Default 30." } }, additionalProperties: false } },
 ];
+const NAMES = new Set(TOOLS.map((t) => t.name));
 
 const error = (id, code, message) => ({ jsonrpc: "2.0", id, error: { code, message } });
 const result = (id, value) => ({ jsonrpc: "2.0", id, result: value });
@@ -63,7 +80,7 @@ export function serveMcp({ verbs, version, input = process.stdin, output = proce
             return send(result(id, { tools: TOOLS }));
           case "tools/call": {
             const name = params?.name;
-            const verb = Object.hasOwn(verbs, name) ? verbs[name] : null;
+            const verb = NAMES.has(name) && Object.hasOwn(verbs, name) ? verbs[name] : null;
             if (!verb) return send(result(id, { content: [{ type: "text", text: `No tool ${String(name)}.` }], isError: true }));
             const out = await verb(params?.arguments ?? {});
             return send(result(id, { content: [{ type: "text", text: out.text }], ...(out.isError ? { isError: true } : {}) }));

package/lib/register.mjs

@@ -1,17 +1,23 @@
 import { execFile } from "node:child_process";
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
+import { cliSpec, npxArgs } from "./spec.mjs";
 
 // Making Cortad known to the coding agents on this machine: an MCP entry in each client that is
 // here, and the skill that teaches the loop. Nothing is written into the repository; everything
 // lands in the client's own home folders, the way the client's own `add` command would put it.
-// Idempotent: run twice, it adds nothing twice.
+// Idempotent: run twice, it adds nothing twice. An entry naming another spec (lib/spec.mjs) is
+// replaced, so a connect with a newer package moves every client to it.
 const exec = promisify(execFile);
-const SERVER = { command: "npx", args: ["-y", "cortad@latest", "mcp"] };
 const SKILL_SRC = join(dirname(fileURLToPath(import.meta.url)), "..", "skill");
+// The skill's shell examples name the spec in place of this.
+const PLACEHOLDER = "{{cortad}}";
+
+export const serverFor = (spec) => ({ command: "npx", args: [...npxArgs(spec), "mcp"] });
+const same = (entry, server) => entry?.command === server.command && JSON.stringify(entry?.args) === JSON.stringify(server.args);
 
 export const onPath = (bin, env = process.env) =>
   (env.PATH ?? "").split(delimiter).some((dir) => dir && existsSync(join(dir, bin)));
@@ -21,68 +27,96 @@ export function detectClients({ home = homedir(), env = process.env } = {}) {
     claude: onPath("claude", env) || existsSync(join(home, ".claude")),
     codex: onPath("codex", env) || existsSync(join(home, ".codex")),
     cursor: existsSync(join(home, ".cursor")),
+    copilot: onPath("copilot", env) || existsSync(join(home, ".copilot")),
   };
 }
 
 // Returns the names of the clients that now know Cortad, for the one line the command prints.
-export async function registerAll({ home = homedir(), env = process.env, run = exec, skillSrc = SKILL_SRC } = {}) {
+export async function registerAll({ home = homedir(), env = process.env, run = exec, skillSrc = SKILL_SRC, spec = cliSpec({ env }) } = {}) {
   const found = detectClients({ home, env });
+  const server = serverFor(spec);
+  const skill = (dir) => installSkill(dir, { src: skillSrc, spec });
   const added = [];
   if (found.claude) {
-    await registerClaude({ home, env, run });
-    installSkill(join(home, ".claude", "skills", "cortad"), skillSrc);
+    await registerClaude({ home, env, run, server });
+    skill(join(home, ".claude", "skills", "cortad"));
     added.push("Claude Code");
   }
   if (found.codex) {
-    await registerCodex({ home, env, run });
-    installSkill(join(home, ".agents", "skills", "cortad"), skillSrc);
+    await registerCodex({ home, env, run, server });
     added.push("Codex");
   }
   if (found.cursor) {
-    registerCursor({ home });
+    registerJson(join(home, ".cursor", "mcp.json"), { type: "stdio", ...server });
     added.push("Cursor");
   }
+  if (found.copilot) {
+    // Copilot CLI keeps its servers in its own home, in its own shape: a "local" server with every tool.
+    registerJson(join(home, ".copilot", "mcp-config.json"), { type: "local", ...server, tools: ["*"] });
+    skill(join(home, ".copilot", "skills", "cortad"));
+    added.push("Copilot");
+  }
+  // The one skills folder Codex, Cursor and Copilot all read.
+  if (found.codex || found.cursor || found.copilot) skill(join(home, ".agents", "skills", "cortad"));
   return added;
 }
 
 // The client's own command when it is here, so its config is written the way it writes it; the file
-// itself only when the folder exists without the binary on this PATH.
-async function registerClaude({ home, env, run }) {
+// itself only when the folder exists without the binary on this PATH, or the command failed.
+async function registerClaude({ home, env, run, server }) {
+  const file = join(home, ".claude.json");
   if (onPath("claude", env)) {
-    try { await run("claude", ["mcp", "add", "--scope", "user", "cortad", "--", SERVER.command, ...SERVER.args], { env }); return; }
-    catch (err) { if (/already exists/i.test(String(err?.stderr ?? err?.message))) return; }
+    const add = () => run("claude", ["mcp", "add", "--scope", "user", "cortad", "--", server.command, ...server.args], { env });
+    try { await add(); return; } catch (err) {
+      if (/already exists/i.test(String(err?.stderr ?? err?.message))) {
+        if (same(readJson(file)?.mcpServers?.cortad, server)) return;
+        try { await run("claude", ["mcp", "remove", "--scope", "user", "cortad"], { env }); await add(); return; } catch { /* the file below */ }
+      }
+    }
   }
-  const file = join(home, ".claude.json");
   const config = readJson(file) ?? {};
-  config.mcpServers = { ...(config.mcpServers ?? {}), cortad: { type: "stdio", ...SERVER } };
+  config.mcpServers = { ...(config.mcpServers ?? {}), cortad: { type: "stdio", ...server } };
   writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
 }
 
-async function registerCodex({ home, env, run }) {
-  if (onPath("codex", env)) {
-    try { await run("codex", ["mcp", "add", "cortad", "--", SERVER.command, ...SERVER.args], { env }); return; }
-    catch (err) { if (/already exists/i.test(String(err?.stderr ?? err?.message))) return; }
-  }
+const CODEX_BLOCK = /^\[mcp_servers\.cortad\]\n(?:(?!\[).*(?:\n|$))*/m;
+
+async function registerCodex({ home, env, run, server }) {
   const file = join(home, ".codex", "config.toml");
   const text = existsSync(file) ? readFileSync(file, "utf8") : "";
-  if (/^\[mcp_servers\.cortad\]/m.test(text)) return;
+  const block = text.match(CODEX_BLOCK)?.[0] ?? "";
+  const args = block.match(/^args\s*=\s*(\[.*\])\s*$/m)?.[1];
+  const current = (() => { try { return args ? { command: block.match(/^command\s*=\s*"(.*)"\s*$/m)?.[1], args: JSON.parse(args) } : null; } catch { return null; } })();
+  if (same(current, server)) return;
+  if (onPath("codex", env)) {
+    try {
+      if (block) await run("codex", ["mcp", "remove", "cortad"], { env });
+      await run("codex", ["mcp", "add", "cortad", "--", server.command, ...server.args], { env });
+      return;
+    } catch { /* the file below */ }
+  }
+  const entry = `[mcp_servers.cortad]\ncommand = "${server.command}"\nargs = ${JSON.stringify(server.args)}\n`;
   mkdirSync(dirname(file), { recursive: true });
-  writeFileSync(file, `${text}${text && !text.endsWith("\n") ? "\n" : ""}\n[mcp_servers.cortad]\ncommand = "${SERVER.command}"\nargs = ${JSON.stringify(SERVER.args)}\n`);
+  // The blank lines after the old block stay, so the rest of the file keeps its layout.
+  const replaced = () => text.replace(CODEX_BLOCK, (old) => `${entry}${(old.match(/\n+$/)?.[0] ?? "\n").slice(1)}`);
+  writeFileSync(file, block ? replaced() : `${text}${text && !text.endsWith("\n") ? "\n" : ""}\n${entry}`);
 }
 
-function registerCursor({ home }) {
-  const file = join(home, ".cursor", "mcp.json");
+function registerJson(file, entry) {
   const config = readJson(file) ?? {};
-  if (config.mcpServers?.cortad) return;
-  config.mcpServers = { ...(config.mcpServers ?? {}), cortad: { type: "stdio", ...SERVER } };
+  if (same(config.mcpServers?.cortad, entry)) return;
+  config.mcpServers = { ...(config.mcpServers ?? {}), cortad: entry };
+  mkdirSync(dirname(file), { recursive: true });
   writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
 }
 
-// SKILL.md and its references, copied whole so a newer package refreshes the words.
-export function installSkill(dir, src = SKILL_SRC) {
+// SKILL.md and its references, copied whole so a newer package refreshes the words, with the
+// shell examples naming the spec this machine runs.
+export function installSkill(dir, { src = SKILL_SRC, spec = cliSpec() } = {}) {
   mkdirSync(join(dir, "references"), { recursive: true });
-  copyFileSync(join(src, "SKILL.md"), join(dir, "SKILL.md"));
-  copyFileSync(join(src, "references", "results.md"), join(dir, "references", "results.md"));
+  for (const rel of ["SKILL.md", join("references", "results.md")]) {
+    writeFileSync(join(dir, rel), readFileSync(join(src, rel), "utf8").replaceAll(PLACEHOLDER, spec));
+  }
 }
 
 function readJson(file) {

package/lib/spec.mjs

@@ -0,0 +1,20 @@
+import { readFileSync } from "node:fs";
+import { isAbsolute } from "node:path";
+
+// Which cortad the coding agents on this machine start, and the skill and stick name: the
+// CORTAD_CLI_SPEC the connect ran with (cortad@next, or an absolute folder for an unpublished
+// build), else cortad@next while this package is a prerelease, else cortad@latest. The spec ends up
+// in a shell line in the repository (lib/stick.mjs), so anything else in the variable is ignored.
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const SAFE = /^(?:cortad(?:@[A-Za-z0-9._-]+)?|\/[A-Za-z0-9._/-]+)$/;
+
+export function cliSpec({ env = process.env, version = VERSION } = {}) {
+  if (env.CORTAD_CLI_SPEC && SAFE.test(env.CORTAD_CLI_SPEC)) return env.CORTAD_CLI_SPEC;
+  return version.includes("-") ? "cortad@next" : "cortad@latest";
+}
+
+// npx needs -y to fetch a package without asking; a local folder is not fetched.
+export const npxArgs = (spec) => (isAbsolute(spec) ? [spec] : ["-y", spec]);
+
+// How a line a person reads names the command: plain `cortad` when that is what npx resolves anyway.
+export const npxName = (spec) => (spec === "cortad@latest" ? "cortad" : spec);

package/lib/stick.mjs

@@ -0,0 +1,99 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve, sep } from "node:path";
+import { cliSpec, npxName } from "./spec.mjs";
+
+// `npx cortad stick`: one line in each coding agent's own instructions file in this repository, and
+// a hook in the two clients that run one after an edit. `unstick` takes out exactly what stick put
+// in. Both are idempotent, print what they changed, and never touch git.
+//
+// The hook command carries --hook: Claude Code and Codex both drop plain stdout from a PostToolUse
+// hook, and read only hookSpecificOutput.additionalContext. The command follows lib/spec.mjs, and
+// unstick knows the line and the hook under any spec.
+export const lineFor = (name) => `After changing prompts, tools, models or retrieval, check with Cortad before committing: npx ${name} status`;
+export const hookFor = (name) => `npx ${name} status --changed --hook`;
+const IS_LINE = /^After changing prompts, tools, models or retrieval, check with Cortad before committing: npx \S+ status$/;
+const IS_HOOK = /^npx \S+ status --changed --hook$/;
+const hasLine = (text) => text.split("\n").some((l) => IS_LINE.test(l.trim()));
+const ours = (entry) => entry?.hooks?.some((h) => IS_HOOK.test(h.command ?? ""));
+const LINE_FILES = ["AGENTS.md", "CLAUDE.md", ".github/copilot-instructions.md"];
+const HOOK_FILES = [".claude/settings.json", ".codex/hooks.json"];
+const RULE_FILE = ".cursor/rules/cortad.mdc";
+
+export const hookOutput = (text) => JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: text } });
+
+export function stick(root, { spec = cliSpec() } = {}) {
+  const line = lineFor(npxName(spec));
+  const hook = hookFor(npxName(spec));
+  const rule = `---\ndescription: Checking AI behavior with Cortad\nalwaysApply: true\n---\n${line}\n`;
+  const said = LINE_FILES.map((rel, i) => write(root, rel, (text) => {
+    if (hasLine(text)) return null;
+    return `${text}${text && !text.endsWith("\n") ? "\n" : ""}${text ? "\n" : ""}${line}\n`;
+  }, i === 0 ? `added "${line}"` : "added the same line"));
+  said.push(write(root, RULE_FILE, (text) => (hasLine(text) ? null : rule), "written, with the same line, applied always"));
+  said.push(...HOOK_FILES.map((rel, i) => write(root, rel, (text) => {
+    const config = parse(text);
+    if (config === undefined) return undefined;
+    const list = config.hooks?.PostToolUse ?? [];
+    if (list.some(ours)) return null;
+    config.hooks = { ...config.hooks, PostToolUse: [...list, { matcher: "Edit|Write", hooks: [{ type: "command", command: hook }] }] };
+    return `${JSON.stringify(config, null, 2)}\n`;
+  }, i === 0 ? `added a PostToolUse hook on Edit|Write that runs ${hook}` : "added the same hook")));
+  return said;
+}
+
+export function unstick(root) {
+  const said = LINE_FILES.map((rel) => write(root, rel, (text) => {
+    if (!hasLine(text)) return null;
+    return text.split("\n").filter((l) => !IS_LINE.test(l.trim())).join("\n").replace(/\n+$/, "\n");
+  }, "removed the line"));
+  said.push(write(root, RULE_FILE, (text) => (text ? "" : null), "removed"));
+  said.push(...HOOK_FILES.map((rel) => write(root, rel, (text) => {
+    const config = parse(text);
+    if (config === undefined) return undefined;
+    const list = config.hooks?.PostToolUse;
+    if (!list?.some(ours)) return null;
+    const kept = list.map((e) => ({ ...e, hooks: (e.hooks ?? []).filter((h) => !IS_HOOK.test(h.command ?? "")) })).filter((e) => e.hooks.length);
+    if (kept.length) config.hooks.PostToolUse = kept;
+    else delete config.hooks.PostToolUse;
+    if (!Object.keys(config.hooks).length) delete config.hooks;
+    return Object.keys(config).length ? `${JSON.stringify(config, null, 2)}\n` : "";
+  }, "removed the hook")));
+  return said;
+}
+
+// One file: `change` gets its text ("" when absent) and returns the new text, null for nothing to
+// do, or undefined when it cannot be read. An empty result removes the file, and the folders it
+// leaves empty. A path that leaves the repository, through a symbolic link or otherwise, is left alone.
+function write(root, rel, change, done) {
+  const file = resolve(root, rel);
+  if (!inside(root, file)) return `${rel}: left alone, it points outside this repository`;
+  const text = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const next = change(text);
+  if (next === undefined) return `${rel}: left alone, it is not valid JSON`;
+  if (next === null) return `${rel}: nothing to change`;
+  if (next.trim() === "") {
+    rmSync(file);
+    for (let dir = dirname(file); dir.startsWith(`${resolve(root)}${sep}`) && !readdirSync(dir).length; dir = dirname(dir)) rmdirSync(dir);
+    return `${rel}: removed, it held only what stick wrote`;
+  }
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, next);
+  return `${rel}: ${done}`;
+}
+
+function inside(root, file) {
+  const base = realpathSync(root);
+  let dir = dirname(file);
+  while (!existsSync(dir)) dir = dirname(dir);
+  const real = realpathSync(dir);
+  if (real !== base && !real.startsWith(base + sep)) return false;
+  try { return !lstatSync(file).isSymbolicLink(); } catch { return true; }
+}
+
+function parse(text) {
+  if (!text.trim()) return {};
+  try {
+    const value = JSON.parse(text);
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+  } catch { return undefined; }
+}