@flowriki/agent 0.1.0-beta.4 → 0.1.0-beta.41

package/dist/cli.js

@@ -1,17 +1,2024 @@
 #!/usr/bin/env node
 import {
   AGENT_VERSION,
+  RecordedStepSchema,
+  authenticationResolver,
+  checkAssertion,
+  closeRunSession,
   connect,
+  connectionFor,
   disconnect,
   doctor,
+  executeStep,
+  fieldNames,
+  helperRunner,
+  mirrorCheckTargets,
+  openRunSession,
   prepareBrowsers,
+  replayCase,
+  replayFlow,
   resolveCheckouts,
+  resolveService,
+  runtimeValue,
+  similarity,
   start,
   status
-} from "./chunk-7JLRYAQ2.js";
+} from "./chunk-ALLCHKXG.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
+
+// src/mcp/protocol.ts
+import readline from "readline";
+var PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+async function handle(message, tools, info) {
+  const reply = (result) => ({ jsonrpc: "2.0", id: message.id ?? null, result });
+  const fail = (code, text2) => ({ jsonrpc: "2.0", id: message.id ?? null, error: { code, message: text2 } });
+  if (message.id === void 0 || message.id === null) return null;
+  switch (message.method) {
+    case "initialize": {
+      const asked = String(message.params?.["protocolVersion"] ?? "");
+      const version = PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0];
+      return reply({
+        protocolVersion: version,
+        capabilities: { tools: { listChanged: true } },
+        serverInfo: { name: info.name, version: info.version },
+        instructions: info.instructions
+      });
+    }
+    case "ping":
+      return reply({});
+    case "tools/list":
+      return reply({
+        tools: tools.map(({ name, title, description, inputSchema, annotations }) => ({
+          name,
+          ...title ? { title } : {},
+          description,
+          inputSchema,
+          ...annotations ? { annotations } : {}
+        }))
+      });
+    case "tools/call": {
+      const name = String(message.params?.["name"] ?? "");
+      const tool = tools.find((t) => t.name === name);
+      if (!tool) return fail(-32602, `no tool named ${name}`);
+      const args = message.params?.["arguments"] ?? {};
+      try {
+        return reply(await tool.run(args));
+      } catch (error) {
+        return reply({ content: [{ type: "text", text: error.message }], isError: true });
+      }
+    }
+    default:
+      return fail(-32601, `method not found: ${message.method}`);
+  }
+}
+function serve(tools, info, io = {}) {
+  const input = io.input ?? process.stdin;
+  const output = io.output ?? process.stdout;
+  if (!io.output) {
+    console.log = console.info = console.warn = console.debug = (...args) => {
+      process.stderr.write(`${args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ")}
+`);
+    };
+  }
+  const lines = readline.createInterface({ input, crlfDelay: Infinity });
+  const pending = /* @__PURE__ */ new Set();
+  lines.on("line", (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      output.write(`${JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } })}
+`);
+      return;
+    }
+    const task = handle(message, tools, info).then((answer) => {
+      if (answer) output.write(`${JSON.stringify(answer)}
+`);
+      if (message.method === "notifications/initialized") {
+        output.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/tools/list_changed" })}
+`);
+      }
+    });
+    pending.add(task);
+    void task.finally(() => pending.delete(task));
+  });
+  return new Promise((resolve) => lines.on("close", () => void Promise.allSettled([...pending]).then(() => resolve())));
+}
+
+// src/mcp/service-client.ts
+var ServiceClient = class {
+  constructor(connection, fetcher = fetch) {
+    this.connection = connection;
+    this.fetcher = fetcher;
+  }
+  connection;
+  fetcher;
+  get origin() {
+    return this.connection.service;
+  }
+  async call(path, init = {}) {
+    const res = await this.fetcher(`${this.connection.service}${path}`, {
+      ...init,
+      headers: {
+        "x-flowriki-device": this.connection.deviceId,
+        "x-flowriki-device-secret": this.connection.secret,
+        "content-type": "application/json"
+      }
+    });
+    const text2 = await res.text();
+    let body = {};
+    try {
+      body = text2 ? JSON.parse(text2) : {};
+    } catch {
+    }
+    if (!res.ok) {
+      if (res.status === 404 && !("error" in body)) {
+        throw new Error("the Flowriki service does not offer this yet \u2014 it may need updating");
+      }
+      throw new Error(String(body["error"] ?? `the service answered ${res.status}`));
+    }
+    return body;
+  }
+  projects() {
+    return this.call("/api/agent/projects");
+  }
+  createProject(name, repository, baseUrl) {
+    return this.call("/api/agent/projects", {
+      method: "POST",
+      body: JSON.stringify({ name, repository, ...baseUrl ? { baseUrl } : {} })
+    });
+  }
+  catalog(projectId) {
+    return this.call(`/api/agent/catalog?projectId=${encodeURIComponent(projectId)}`);
+  }
+  prepare(projectId, steps, signIn) {
+    return this.call(`/api/agent/prepare?projectId=${encodeURIComponent(projectId)}`, {
+      method: "POST",
+      body: JSON.stringify({ steps, ...signIn ? { signIn } : {} })
+    });
+  }
+  /** This person's open branches that Claude wrote on this project. */
+  agentChanges(projectId) {
+    return this.call(
+      `/api/agent/changes?projectId=${encodeURIComponent(projectId)}`
+    );
+  }
+  /** Delete one — refused by the service unless it is all Claude's own,
+   *  unedited, unpublished work. */
+  discardChange(projectId, changeId) {
+    return this.call(
+      `/api/agent/changes/${encodeURIComponent(changeId)}?projectId=${encodeURIComponent(projectId)}`,
+      { method: "DELETE" }
+    );
+  }
+  saveFlow(projectId, title, flow, where = {}, secretValues = {}) {
+    return this.call(
+      `/api/agent/flows?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify({ title, flow, ...where, secretValues }) }
+    );
+  }
+  /** A sign-in made from a recorded login flow. */
+  createSignIn(projectId, input) {
+    return this.call(
+      `/api/agent/sign-ins?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(input) }
+    );
+  }
+  /** An account for a sign-in; secret values are sealed by the service and
+   *  never come back. */
+  createAccount(projectId, input) {
+    return this.call(
+      `/api/agent/accounts?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(input) }
+    );
+  }
+  /** A helper, its secrets sealed by the service. */
+  createHelper(projectId, input) {
+    return this.call(
+      `/api/agent/helpers?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(input) }
+    );
+  }
+  /** What a new flow starts after: the flows, in run order, and their steps. */
+  flowsAfter(projectId, after) {
+    return this.call(
+      `/api/agent/flows/after?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify({ after }) }
+    );
+  }
+  /** Build a test case from flows — as a dry run, or saved. */
+  buildCase(projectId, spec, dryRun) {
+    return this.call(`/api/agent/cases?projectId=${encodeURIComponent(projectId)}`, { method: "POST", body: JSON.stringify({ ...spec, dryRun }) });
+  }
+  /** The test library, on Claude's working branch when it has one. */
+  library(projectId, opts = {}) {
+    const query = new URLSearchParams({ projectId, ...opts.q ? { q: opts.q } : {}, ...opts.featureId ? { featureId: opts.featureId } : {} });
+    return this.call(`/api/agent/library?${query}`);
+  }
+  /** Test cases written, edited or linked in one commit; duplicates skipped. */
+  saveLibrary(projectId, input) {
+    return this.call(`/api/agent/library?projectId=${encodeURIComponent(projectId)}`, { method: "POST", body: JSON.stringify(input) });
+  }
+  // ── Manual cycles and bugs: the dashboard's own routes, behind this
+  // machine's credential, so the assistant can do what a person can. ──────
+  scoped(path, projectId, extra = {}) {
+    const query = new URLSearchParams({ projectId, ...extra });
+    return `/api/agent${path}?${query}`;
+  }
+  cycles(projectId) {
+    return this.call(this.scoped("/cycles", projectId));
+  }
+  cycle(projectId, id) {
+    return this.call(this.scoped(`/cycles/${encodeURIComponent(id)}`, projectId));
+  }
+  createCycle(projectId, body, changeId) {
+    return this.call(this.scoped("/cycles", projectId, changeId ? { changeId } : {}), { method: "POST", body: JSON.stringify(body) });
+  }
+  updateCycle(projectId, id, body, changeId) {
+    return this.call(this.scoped(`/cycles/${encodeURIComponent(id)}`, projectId, changeId ? { changeId } : {}), { method: "PATCH", body: JSON.stringify(body) });
+  }
+  deleteCycle(projectId, id) {
+    return this.call(this.scoped(`/cycles/${encodeURIComponent(id)}`, projectId), { method: "DELETE" });
+  }
+  recordResult(projectId, id, caseId, body) {
+    return this.call(this.scoped(`/cycles/${encodeURIComponent(id)}/results/${encodeURIComponent(caseId)}`, projectId), { method: "PUT", body: JSON.stringify(body) });
+  }
+  addEvidenceLink(projectId, id, caseId, body) {
+    return this.call(this.scoped(`/cycles/${encodeURIComponent(id)}/results/${encodeURIComponent(caseId)}/evidence`, projectId), {
+      method: "POST",
+      body: JSON.stringify({ kind: "link", ...body })
+    });
+  }
+  bugs(projectId) {
+    return this.call(this.scoped("/bugs", projectId));
+  }
+  createBug(projectId, body) {
+    return this.call(this.scoped("/bugs", projectId), { method: "POST", body: JSON.stringify(body) });
+  }
+  updateBug(projectId, id, body) {
+    return this.call(this.scoped(`/bugs/${encodeURIComponent(id)}`, projectId), { method: "PATCH", body: JSON.stringify(body) });
+  }
+  // ── Knowledge, sources, requirements ──────────────────────
+  knowledgePages(projectId) {
+    return this.call(this.scoped("/knowledge", projectId));
+  }
+  knowledgePage(projectId, path) {
+    return this.call(this.scoped("/knowledge/page", projectId, { path }));
+  }
+  writeKnowledge(projectId, body) {
+    return this.call(`/api/agent/knowledge?projectId=${encodeURIComponent(projectId)}`, { method: "POST", body: JSON.stringify(body) });
+  }
+  search(projectId, q) {
+    return this.call(this.scoped("/search", projectId, { q }));
+  }
+  sources(projectId) {
+    return this.call(this.scoped("/sources", projectId));
+  }
+  source(projectId, id) {
+    return this.call(this.scoped(`/sources/${encodeURIComponent(id)}`, projectId));
+  }
+  addSource(projectId, body, sourceId) {
+    return this.call(
+      this.scoped(sourceId ? `/sources/${encodeURIComponent(sourceId)}/versions` : "/sources", projectId),
+      { method: "POST", body: JSON.stringify(body) }
+    );
+  }
+  requirements(projectId, opts = {}) {
+    return this.call(
+      this.scoped("/requirements", projectId, { ...opts.sourceId ? { sourceId: opts.sourceId } : {}, ...opts.state ? { state: opts.state } : {} })
+    );
+  }
+  deleteSource(projectId, id) {
+    return this.call(this.scoped(`/sources/${encodeURIComponent(id)}`, projectId), { method: "DELETE" });
+  }
+  updateRequirement(projectId, id, body) {
+    return this.call(this.scoped(`/requirements/${encodeURIComponent(id)}`, projectId), { method: "PATCH", body: JSON.stringify(body) });
+  }
+  /** Gather Claude's open branches here into one. */
+  gatherChanges(projectId, opts = {}) {
+    return this.call(
+      `/api/agent/changes/gather?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(opts) }
+    );
+  }
+};
+
+// src/mcp/session.ts
+var MAX_TREE = 14e3;
+var MAX_STEP_VIEW = 6e3;
+function topLevelBlocks(tree) {
+  const blocks = [];
+  for (const line of tree.split("\n")) {
+    if (line.startsWith("- ") || blocks.length === 0) blocks.push([line]);
+    else blocks[blocks.length - 1].push(line);
+  }
+  const named = (b, kinds) => kinds.some((k) => b[0].startsWith(`- ${k}`));
+  return {
+    dialogs: blocks.filter((b) => named(b, ["dialog", "alertdialog"])).map((b) => b.join("\n")),
+    navigation: blocks.find((b) => named(b, ["navigation", "banner"]))?.join("\n") ?? null
+  };
+}
+var STEP_TIMEOUT_MS = 1e4;
+var SECRET_WORDS = /password|passwd|pass[-_\s]?code|pwd|secret|otp|one[-_\s]?time[-_\s]?(code|pass)|security[-_\s]?(code|answer)|cvv|cvc|\bpin\b/i;
+var TYPED = "typed_";
+var withoutTyped = (steps) => steps.map((st) => st.secretRef?.startsWith(TYPED) ? (({ secretRef: _, ...rest }) => rest)(st) : st);
+var ACTIONS = ["click", "dblclick", "rightclick", "hover", "fill", "select", "check", "press", "navigate", "back", "forward"];
+var isAction = (value) => ACTIONS.includes(String(value));
+var LANDMARKS = /* @__PURE__ */ new Set(["main", "navigation", "banner", "contentinfo", "complementary", "search", "form", "dialog", "alertdialog", "region", "group", "list", "table", "menu", "toolbar", "tablist"]);
+function scopeOf(within) {
+  const said = within?.trim() ?? "";
+  if (!said) return { scope: "" };
+  return LANDMARKS.has(said.toLowerCase()) ? { scope: "", scopeRole: said.toLowerCase() } : { scope: said };
+}
+function asLabelled(target, fields) {
+  const field = fields.find((f) => f.role === target.role && (f.label === target.name || f.hint === target.name));
+  if (!field) return target;
+  return {
+    ...target,
+    name: field.label,
+    nameFrom: "adjacent-label",
+    ...field.hintFrom === "name" ? {} : { candidates: [{ strategy: field.hintFrom, value: field.hint }] }
+  };
+}
+function labelTree(tree, fields) {
+  let out = tree;
+  for (const f of fields) out = out.split(`- ${f.role} ${JSON.stringify(f.hint)}`).join(`- ${f.role} ${JSON.stringify(f.label)}`);
+  return out;
+}
+function numberDuplicates(tree) {
+  const line = /^(\s*- )([\w-]+) "((?:[^"\\]|\\.)*)"(.*)$/;
+  const totals = /* @__PURE__ */ new Map();
+  const lines = tree.split("\n");
+  for (const l of lines) {
+    const m = line.exec(l);
+    if (m) totals.set(`${m[2]}|${m[3]}`, (totals.get(`${m[2]}|${m[3]}`) ?? 0) + 1);
+  }
+  const seen = /* @__PURE__ */ new Map();
+  return lines.map((l) => {
+    const m = line.exec(l);
+    if (!m) return l;
+    const key = `${m[2]}|${m[3]}`;
+    const total = totals.get(key) ?? 1;
+    if (total < 2) return l;
+    const at = seen.get(key) ?? 0;
+    seen.set(key, at + 1);
+    return `${l}  [nth ${at} of ${total} with this name]`;
+  }).join("\n");
+}
+function describeRows(rows) {
+  return rows.map((r) => [
+    `Row ${r.row}: "${r.flow}" (${r.browser})`,
+    ...r.checks.length ? r.checks.map((c) => `  ${c.on ? "[on] " : "[off]"} ${c.n}. ${c.check}`) : ["  (no checks in this flow)"]
+  ].join("\n")).join("\n");
+}
+function describe(step) {
+  const target = (step.name ? `${step.role || "element"} "${step.name}"` : step.role || "") + (step.nth !== void 0 ? ` (nth ${step.nth})` : "");
+  const where = step.scope ? ` in "${step.scope}"` : step.scopeRole ? ` in the ${step.scopeRole}` : "";
+  switch (step.type) {
+    case "fill":
+      return step.secret ? `type a secret (\u2022\u2022\u2022\u2022\u2022\u2022) into ${target}${where}` : `type "${step.value}" into ${target}${where}`;
+    case "select":
+      return `choose "${step.value}" in ${target}${where}`;
+    case "check":
+      return `${step.value === "false" ? "untick" : "tick"} ${target}${where}`;
+    case "press":
+      return `press ${step.value}${target ? ` in ${target}` : ""}`;
+    case "navigate":
+      return `go to ${step.value}`;
+    case "back":
+    case "forward":
+      return `browser ${step.type}`;
+    case "assert":
+      return `check ${step.proposals.map((p) => `${p.kind}${p.op && p.op !== "equals" ? ` ${p.op}` : ""} "${String(p.value)}"${p.target?.name ? ` on ${p.target.role} "${p.target.name}"` : ""}`).join(", ")}`;
+    case "useHelper":
+      return `use helper ${step.name || step.helper?.helperId} \u2192 {{${step.helper?.saveAs}}}${step.helper?.then === "open" ? ", then open it" : ""}`;
+    default:
+      return `${step.type} ${target}${where}`;
+  }
+}
+var AuthoringSession = class {
+  constructor(service, opts = {}) {
+    this.service = service;
+    this.opts = opts;
+  }
+  service;
+  opts;
+  run = null;
+  page = null;
+  values = /* @__PURE__ */ new Map();
+  resolvers = null;
+  lastTree = null;
+  /** Values typed into secret fields, by their `typed:` reference. */
+  typed = /* @__PURE__ */ new Map();
+  draft = null;
+  catalog = null;
+  /** Text going back to Claude, with every secret typed here masked — a
+   *  password box's value is in the page's tree, and a careless form puts it
+   *  in the address. */
+  redact(text2) {
+    let out = text2;
+    for (const value of this.typed.values()) {
+      if (value.length < 3) continue;
+      out = out.split(value).join("\u2022\u2022\u2022\u2022\u2022\u2022");
+      const encoded = encodeURIComponent(value);
+      if (encoded !== value) out = out.split(encoded).join("\u2022\u2022\u2022\u2022\u2022\u2022");
+    }
+    return out;
+  }
+  get open() {
+    return this.run !== null;
+  }
+  requireOpen() {
+    if (!this.run || !this.page || !this.draft) throw new Error("no flow is being written \u2014 call start_flow first");
+    return { page: this.page, draft: this.draft, run: this.run };
+  }
+  /** What the steps so far, plus any about to run, need from the service:
+   *  sign-ins, helpers, and their secret values. Asked again whenever a new
+   *  helper or sign-in appears, never kept beyond this process. */
+  async prepare(extra = []) {
+    const draft = this.draft;
+    const prepared = await this.service.prepare(draft.projectId, withoutTyped([...draft.preparation ?? [], ...draft.steps, ...extra]), draft.signIn ?? null);
+    const runHelper = helperRunner(prepared.helpers, prepared.secrets);
+    this.resolvers = {
+      resolveAuth: authenticationResolver(prepared.authentications),
+      resolveSecret: (ref) => this.typed.get(ref) ?? prepared.secrets[ref],
+      ...runHelper ? { runHelper } : {}
+    };
+    return this.resolvers;
+  }
+  baseUrl() {
+    const base = this.catalog?.baseUrl ?? "";
+    if (!base) throw new Error("this project has no base URL \u2014 set one in the project's settings first");
+    return base;
+  }
+  /** Open a browser for a new flow, signed in first if asked. */
+  async start(input, catalog) {
+    await this.close();
+    this.catalog = catalog;
+    this.draft = { ...input, steps: [] };
+    this.values = /* @__PURE__ */ new Map();
+    this.typed = /* @__PURE__ */ new Map();
+    this.lastTree = null;
+    const base = this.baseUrl();
+    this.run = await openRunSession({ steps: [], headless: this.opts.headless ?? false });
+    this.page = this.run.page;
+    if (input.signIn) {
+      const resolvers = await this.prepare();
+      const signIn = {
+        id: "sign-in",
+        type: "signIn",
+        auth: { ...input.signIn, from: "loginPage" },
+        role: "",
+        name: "Sign in",
+        scope: "",
+        value: "",
+        secret: false,
+        legacySelector: "",
+        proposals: []
+      };
+      this.page = await executeStep(this.page, signIn, {
+        pages: this.run.pages,
+        ...resolvers,
+        values: this.values,
+        baseUrl: base,
+        timeoutMs: 2e4,
+        navigationTimeoutMs: 45e3
+      });
+    } else {
+      await this.page.goto(new URL(input.startPath || "/", base).href, { waitUntil: "domcontentloaded", timeout: 45e3 });
+    }
+    if (input.preparation?.length) {
+      const resolvers = await this.prepare(input.preparation);
+      for (const step of input.preparation) {
+        try {
+          this.page = await executeStep(this.page, step, {
+            pages: this.run.pages,
+            ...resolvers,
+            values: this.values,
+            baseUrl: base,
+            timeoutMs: 2e4,
+            navigationTimeoutMs: 45e3
+          });
+        } catch (error) {
+          throw new Error(`The flows this one starts after did not finish, at "${step.name || step.type}": ${error.message.split("\n")[0]}`);
+        }
+      }
+      await this.settle();
+    }
+    return this.snapshot();
+  }
+  /** The page as Claude reads it: where it is, and what is on it by role and name. */
+  async snapshot() {
+    return this.view(true);
+  }
+  /** WHAT CHANGED, after a step — not the whole page again.
+   *
+   * Every step used to answer with the full tree, which on a long storefront
+   * is twenty thousand characters repeated forty times to say "the box now
+   * has text in it". So a step answers with what it is about: an open dialog
+   * (with the navigation, which says who is signed in), or the lines that
+   * appeared and disappeared — and only after a real navigation, when most of
+   * the page is new, the page itself, capped. read_page is always the whole
+   * thing. */
+  async view(full) {
+    const { page, draft } = this.requireOpen();
+    await page.waitForLoadState("domcontentloaded", { timeout: 1e4 }).catch(() => void 0);
+    const tree = numberDuplicates(labelTree(
+      await page.locator("body").ariaSnapshot({ timeout: 8e3 }).catch((e) => `(could not read the page: ${e.message})`),
+      await fieldNames(page)
+    ));
+    const title = await page.title().catch(() => "");
+    const head = `Page: ${page.url()}${title ? ` \u2014 "${title}"` : ""}
+Steps so far: ${draft.steps.length}
+
+`;
+    const before = this.lastTree;
+    this.lastTree = tree;
+    const cap = (t, max) => t.length > max ? `${t.slice(0, max)}
+\u2026 (cut \u2014 read_page shows the whole page)` : t;
+    if (full || before === null) return head + cap(tree, MAX_TREE);
+    const { dialogs, navigation } = topLevelBlocks(tree);
+    if (dialogs.length) {
+      return head + cap([...navigation ? [navigation] : [], ...dialogs].join("\n"), MAX_STEP_VIEW) + "\n(only the open dialog and the navigation \u2014 read_page shows the whole page)";
+    }
+    const was = new Set(before.split("\n"));
+    const now = new Set(tree.split("\n"));
+    const added = tree.split("\n").filter((l) => !was.has(l));
+    const removed = before.split("\n").filter((l) => !now.has(l));
+    if (added.length === 0 && removed.length === 0) return head + "(the page did not change \u2014 read_page shows it)";
+    if (added.length + removed.length > 120) return head + cap(tree, MAX_STEP_VIEW);
+    return head + [
+      ...navigation ? [navigation, ""] : [],
+      added.length ? `Appeared:
+${added.join("\n")}` : "",
+      removed.length ? `Gone:
+${removed.join("\n")}` : "",
+      "(changes since the last step \u2014 read_page shows the whole page)"
+    ].filter(Boolean).join("\n");
+  }
+  /** Do one thing on the page, and keep it as a step if it worked. */
+  async act(input) {
+    const { page, draft, run } = this.requireOpen();
+    const navigating = input.action === "navigate" || input.action === "back" || input.action === "forward";
+    if (!navigating && input.action !== "press" && !(input.role && input.name)) {
+      throw new Error(`${input.action} needs the element's role and name, exactly as read_page shows them`);
+    }
+    if ((input.action === "fill" || input.action === "select" || input.action === "press" || input.action === "navigate") && input.value === void 0) {
+      throw new Error(`${input.action} needs a value`);
+    }
+    const target = navigating ? { role: "", name: "" } : asLabelled({ role: input.role ?? "", name: input.name ?? "" }, await fieldNames(page));
+    const secret = input.action === "fill" && (input.secret ?? (SECRET_WORDS.test(input.name ?? "") || SECRET_WORDS.test(target.name)));
+    const id = `s${draft.steps.length + 1}_${Date.now().toString(36)}`;
+    if (secret) this.typed.set(`${TYPED}${id}`, input.value ?? "");
+    const step = RecordedStepSchema.parse({
+      id,
+      type: input.action,
+      ...target,
+      ...scopeOf(input.within),
+      ...input.nth !== void 0 ? { nth: input.nth } : {},
+      value: secret ? "" : input.action === "check" ? input.value === "false" ? "false" : "true" : input.value ?? "",
+      secret,
+      ...secret ? { secretRef: `${TYPED}${id}` } : {},
+      legacySelector: "",
+      proposals: [],
+      // A path is the application's own, so the step replays on whichever
+      // environment the run is pointed at rather than the one written on.
+      ...input.action === "navigate" && input.value?.startsWith("/") ? { navigationBase: "application" } : {}
+    });
+    try {
+      this.page = await executeStep(page, step, {
+        pages: run.pages,
+        values: this.values,
+        baseUrl: this.baseUrl(),
+        ...this.resolvers ?? {},
+        resolveSecret: (ref) => this.typed.get(ref) ?? this.resolvers?.resolveSecret(ref),
+        timeoutMs: STEP_TIMEOUT_MS,
+        navigationTimeoutMs: 45e3
+      });
+    } catch (error) {
+      if (secret) this.typed.delete(`${TYPED}${id}`);
+      const said = error.message.split("\n")[0] ?? "";
+      const several = /strict mode violation|resolved to \d+ elements|\d+ elements match/i.test(said) ? "\nSeveral elements share this role and name. Pass nth (0 = the first, in the order read_page lists them \u2014 each shared name is marked [nth N of M]) to say which one." : "";
+      throw new Error(`That did not work, and was not kept: ${said}${several}
+
+${await this.view(false)}`);
+    }
+    await this.settle();
+    draft.steps.push(step);
+    return `Step ${draft.steps.length} kept: ${describe(step)}.
+
+${await this.view(false)}`;
+  }
+  /** Check something about the page now, and keep the check if it holds. */
+  async check(input) {
+    const { page, draft } = this.requireOpen();
+    if ((input.kind === "heading" || input.kind === "message" || input.kind === "screen") && input.op && input.op !== "equals" && !input.role) {
+      throw new Error(`a ${input.kind} check without role and name matches the whole ${input.kind} \u2014 give its full text with op equals, or name the element (role + name) and use kind "text" with op ${input.op}`);
+    }
+    const assertion = RecordedStepSchema.shape.proposals.element.parse({
+      kind: input.kind,
+      value: input.value,
+      enabled: true,
+      ...input.op && input.op !== "equals" ? { op: input.op } : {},
+      ...input.role ? { target: { ...asLabelled({ role: input.role, name: input.name ?? "" }, await fieldNames(page)), ...scopeOf(input.within), ...input.nth !== void 0 ? { nth: input.nth } : {} } } : {}
+    });
+    const filled = (text2) => text2.replace(/\{\{([a-zA-Z][a-zA-Z0-9_]*)\}\}/g, (_, name) => runtimeValue(this.values, name));
+    const expected = Array.isArray(assertion.value) ? assertion.value.map(filled) : filled(assertion.value);
+    try {
+      await checkAssertion(page, assertion.kind, expected, 5e3, { ...assertion, value: expected });
+    } catch (error) {
+      throw new Error(`That is not true of the page right now, so it was not kept: ${error.message.split("\n")[0]}`);
+    }
+    const step = RecordedStepSchema.parse(mirrorCheckTargets([{
+      id: `c${draft.steps.length + 1}_${Date.now().toString(36)}`,
+      type: "assert",
+      role: "",
+      name: "",
+      scope: "",
+      value: "",
+      secret: false,
+      legacySelector: "",
+      proposals: [assertion]
+    }])[0]);
+    draft.steps.push(step);
+    return `Step ${draft.steps.length} kept: ${describe(step)}.`;
+  }
+  /** Get a value from outside the page — an email code, a 2FA code, a text,
+   *  an API reply — and keep the step that gets it. */
+  async useHelper(input) {
+    const { page, draft, run } = this.requireOpen();
+    const helper = this.catalog?.helpers.find((h) => h.id === input.helperId || h.name.toLowerCase() === input.helperId.toLowerCase());
+    if (!helper) throw new Error(`no helper "${input.helperId}" \u2014 project_catalog lists them; one can be made on the Helpers screen`);
+    const missing = helper.inputs.filter((name) => !(input.inputs ?? {})[name]);
+    if (missing.length) throw new Error(`${helper.name} needs ${missing.map((n) => `{{${n}}}`).join(", ")} in inputs`);
+    const step = RecordedStepSchema.parse({
+      id: `h${draft.steps.length + 1}_${Date.now().toString(36)}`,
+      type: "useHelper",
+      role: "",
+      name: helper.name,
+      scope: "",
+      value: "",
+      secret: false,
+      legacySelector: "",
+      proposals: [],
+      helper: { helperId: helper.id, inputs: input.inputs ?? {}, saveAs: input.saveAs || (helper.kind === "mailbox" ? "code" : "value"), then: input.then ?? "remember" }
+    });
+    const resolvers = await this.prepare([step]);
+    let got = { value: "", detail: "" };
+    try {
+      this.page = await executeStep(page, step, {
+        pages: run.pages,
+        values: this.values,
+        baseUrl: this.baseUrl(),
+        ...resolvers,
+        timeoutMs: STEP_TIMEOUT_MS,
+        navigationTimeoutMs: 45e3,
+        onHelper: (answer) => {
+          got = answer;
+        }
+      });
+    } catch (error) {
+      throw new Error(`The helper did not get a value, and the step was not kept: ${error.message}`);
+    }
+    await this.settle();
+    draft.steps.push(step);
+    return `Step ${draft.steps.length} kept: ${describe(step)}. It got "${got.value}" (${got.detail}). Use {{${step.helper.saveAs}}} as the value of a later step.` + (step.helper.then === "open" ? `
+
+${await this.view(false)}` : "");
+  }
+  list() {
+    const draft = this.draft;
+    if (!draft) return "No flow is being written.";
+    const head = `"${draft.name}"${draft.signIn ? ", signed in first" : ""}, starting at ${draft.startPath}`;
+    if (draft.steps.length === 0) return `${head}. No steps yet.`;
+    return `${head}:
+${draft.steps.map((s, i) => `${i + 1}. ${describe(s)}`).join("\n")}`;
+  }
+  /** Drop a step from the draft. The browser is not wound back — replay to
+   *  see the flow as it now stands. */
+  remove(number) {
+    const { draft } = this.requireOpen();
+    if (!Number.isInteger(number) || number < 1 || number > draft.steps.length) throw new Error(`there is no step ${number}`);
+    const [gone] = draft.steps.splice(number - 1, 1);
+    return `Removed step ${number} (${describe(gone)}). The browser was not undone \u2014 replay_flow shows the flow as it now stands.
+
+${this.list()}`;
+  }
+  /** Run the whole draft from the start, in a browser of its own, the way a
+   *  run will — the proof the steps work together, not just one at a time. */
+  async replay() {
+    const { draft } = this.requireOpen();
+    if (draft.steps.length === 0) throw new Error("there are no steps to replay yet");
+    const resolvers = await this.prepare();
+    const steps = [
+      ...draft.signIn ? [RecordedStepSchema.parse({ id: "sign-in", type: "signIn", auth: { ...draft.signIn, from: "loginPage" }, role: "", name: "Sign in", scope: "", value: "", secret: false, legacySelector: "", proposals: [] })] : [],
+      ...draft.preparation ?? [],
+      ...draft.steps
+    ];
+    const outcome = await replayFlow({ steps, baseUrl: this.baseUrl(), startPath: draft.startPath, headless: true, ...resolvers });
+    const lines = outcome.steps.map((s) => `${s.status === "passed" ? "\u2713" : s.status === "failed" ? "\u2717" : "\xB7"} ${s.name || s.type}${s.status === "failed" && s.detail ? ` \u2014 ${s.detail}` : ""}`);
+    return `${outcome.status === "passed" ? "The whole flow passed from the start." : `The flow ${outcome.status}${outcome.error ? `: ${outcome.error}` : ""}.`}
+${lines.join("\n")}`;
+  }
+  /** Save the draft as a flow on a new branch, for a person to review. */
+  async save(title, where = {}) {
+    const { draft } = this.requireOpen();
+    if (draft.steps.length === 0) throw new Error("there are no steps to save yet");
+    if (!draft.steps.some((s) => s.type === "assert" || s.proposals.length > 0)) {
+      throw new Error("the flow checks nothing \u2014 add at least one check (add_check) that proves it worked, then save");
+    }
+    const checksOff = draft.steps.map((step) => step.type === "assert" ? { ...step, proposals: step.proposals.map((p) => ({ ...p, enabled: false })) } : step);
+    const checkCount = checksOff.filter((step) => step.type === "assert").length;
+    const secretValues = {};
+    for (const step of checksOff) {
+      const value = step.secretRef ? this.typed.get(step.secretRef) : void 0;
+      if (value !== void 0) secretValues[step.id] = value;
+    }
+    const saved = await this.service.saveFlow(draft.projectId, title || "Tests written with Claude", {
+      name: draft.name,
+      ...draft.featureId ? { featureId: draft.featureId } : { featureName: draft.featureName },
+      startPath: draft.startPath,
+      steps: withoutTyped(checksOff),
+      ...draft.signIn ? { signIn: draft.signIn } : {},
+      ...draft.after?.length ? { prerequisites: draft.after.map((a) => ({ flowId: a.flowId })) } : {}
+    }, where, secretValues);
+    const review = `${this.service.origin}/projects/${draft.projectId}/changes/${saved.changeId}`;
+    const what = saved.replaced ? `Replaced the earlier "${draft.name}"` : `Saved "${draft.name}"`;
+    const sealed = Object.keys(secretValues).length;
+    const vault = sealed ? ` ${sealed} secret value${sealed === 1 ? " was" : "s were"} put in the project's vault, not the flow.` : "";
+    const where_ = saved.newBranch ? `on a new branch, ${saved.branch}` : `on Claude's working branch, ${saved.branch}`;
+    const others = await this.service.agentChanges(draft.projectId).then((r) => r.changes.filter((c) => c.id !== saved.changeId)).catch(() => []);
+    const note = others.length ? `
+Claude has ${others.length} other open branch${others.length === 1 ? "" : "es"} on this project \u2014 gather_branches puts them into this one, for one review.` : "";
+    const after = draft.after?.length ? ` It starts after ${draft.after.map((a) => `"${a.name}"`).join(", ")}.` : "";
+    return `${what} ${where_}.${after}${vault} Its ${checkCount} check${checkCount === 1 ? " is" : "s are"} saved switched off \u2014 an automation switches on the ones it is about. Nothing is published yet.
+Review and publish it here: ${review}${note}`;
+  }
+  /** A test case built from flows, without saving: its rows and every check,
+   *  numbered, with which are on — what save_case's `checks` refer to. */
+  async previewCase(projectId, spec) {
+    const built = await this.service.buildCase(projectId, spec, true);
+    return `"${spec.name}" in ${spec.folder} would be:
+${describeRows(built.rows)}`;
+  }
+  /** RUN THE CASE, THEN SAVE IT. Built as a dry run, replayed in a fresh
+   *  browser exactly as a test run does it, and saved onto Claude's working
+   *  branch only when every row passed. */
+  async saveCase(projectId, spec, catalog) {
+    const built = await this.service.buildCase(projectId, spec, true);
+    const testCase = built.testCase;
+    const steps = testCase.occurrences.flatMap((o) => o.steps);
+    const prepared = await this.service.prepare(projectId, steps, null);
+    const runHelper = helperRunner(prepared.helpers, prepared.secrets);
+    const base = catalog.baseUrl;
+    if (!base) throw new Error("this project has no base URL \u2014 set one in the project's settings first");
+    const outcome = await replayCase({
+      occurrences: testCase.occurrences,
+      ...testCase.actors ? { actors: testCase.actors } : {},
+      ...testCase.defaultActorId ? { defaultActorId: testCase.defaultActorId } : {},
+      baseUrl: base,
+      headless: true,
+      resolveAuth: authenticationResolver(prepared.authentications),
+      resolveSecret: (ref) => prepared.secrets[ref],
+      ...runHelper ? { runHelper } : {}
+    });
+    const lines = outcome.occurrences.map((o, i) => {
+      const failed = o.steps.find((st) => st.status === "failed");
+      const why = o.status === "failed" ? `: ${failed ? `step "${failed.name || failed.type}" \u2014 ${(failed.detail ?? "").split("\n")[0]}` : (o.error ?? "").split("\n")[0]}` : "";
+      return `${o.status === "passed" ? "\u2713" : o.status === "failed" ? "\u2717" : "\xB7"} row ${i + 1} \u2014 ${o.name}${why}`;
+    });
+    if (outcome.status !== "passed") {
+      return `The case did not pass, so it was NOT saved.
+${lines.join("\n")}
+
+${describeRows(built.rows)}`;
+    }
+    const saved = await this.service.buildCase(projectId, spec, false);
+    const review = `${this.service.origin}${saved.path}`;
+    return `The case passed from the start${saved.replaced ? " and replaced the earlier version" : ""}, and is saved on ${saved.newBranch ? "a new branch" : "Claude's working branch"}. Nothing is published yet.
+${lines.join("\n")}
+Review and publish it here: ${review}`;
+  }
+  async close() {
+    const run = this.run;
+    this.run = null;
+    this.page = null;
+    this.resolvers = null;
+    if (run) await closeRunSession(run, { passed: true }).catch(() => void 0);
+  }
+  /** Let a click's consequences land before the page is read again. */
+  async settle() {
+    const page = this.page;
+    if (!page) return;
+    await page.waitForLoadState("domcontentloaded", { timeout: 1e4 }).catch(() => void 0);
+    await page.waitForTimeout(300);
+  }
+};
+
+// src/mcp/tools.ts
+var INSTRUCTIONS = `Flowriki tools write UI tests by driving a real browser on this computer.
+Every step you take is performed first and kept only if it worked, so what you
+save already ran once. Everything goes to ONE working branch per project that a
+person reviews and publishes in the Flowriki dashboard \u2014 nothing you do is
+published.
+
+A new project \u2014 "set up Flowriki for this site, in this repository" \u2014 is made
+with create_project; it then becomes the project the other tools work on.
+
+THE MODEL \u2014 get this right before recording anything:
+- A FLOW is a reusable building block: one piece of a journey ("Open the account
+  dialog", "Fill the sign-up form", "Sign in with a wrong password"). A flow can
+  START AFTER other flows (start_flow's "after"), so it holds only its own new
+  steps and links to the ones before it. A path that behaves differently \u2014 a
+  wrong password, a duplicate email \u2014 is its own flow, because the page does
+  something different.
+- A flow records checks (add_check) that prove each thing happened, but they
+  are SAVED SWITCHED OFF: which ones matter depends on the test.
+- An AUTOMATION is the test. It strings flows together as rows (in the same
+  browser, or a new one for a second person) and switches on the checks it is
+  about. Build it with preview_case, then save_case \u2014 which runs it first.
+- SIGN-IN is shared setup: a flow or case that needs somebody signed in uses a
+  sign-in profile from the catalog (start_flow's signIn), never typed login steps.
+  None yet? Make it: record the login as a flow that ends with a check proving
+  it worked (the account menu, a heading, the URL), then create_sign_in from it
+  and create_account for each person who signs in (a customer, an admin). The
+  login flow types into its fields; the account supplies the values.
+- HELPERS (an inbox for email codes, an authenticator, SMS, an API call) are made
+  with create_helper when the catalog has none that fits.
+- SEVERAL ELEMENTS WITH THE SAME NAME (two "Proceed to Checkout" buttons, twelve
+  "Select & Customize") are told apart by POSITION, like an XPath index: read_page
+  marks each one [nth N of M], and act / add_check take nth (0 = the first). Use it
+  as soon as a name is shared \u2014 there is no need to look for another way round.
+- PASSWORDS AND KEYS never go into a flow or a reply. Typed into a password
+  field, a value is kept as a secret and saved to the project's vault; given to
+  create_account or create_helper, it is sealed there too and never shown back.
+  Only use credentials the person gave you or that the app itself shows for
+  testing (a demo login) \u2014 never guess or reuse anyone's real password.
+- FOLDERS do not nest. Name each one after the product area and what is in it,
+  the way a tester would look for it \u2014 "Account \u2013 Sign up", "Account \u2013 Sign in",
+  "Ordering \u2013 Pizza builder", "Checkout \u2013 Payment". Flows (features) and the
+  cases built from them use the same names. Keep one area per folder.
+
+THE TEST LIBRARY is what the team checks, written down: test cases (TC-1,
+TC-2\u2026) with steps, expected results, priority and status. An automation is how
+a test case is checked by a machine, and each test case lists the automations
+that check it. Read it with library_cases before deciding what to automate \u2014
+the important cases nothing checks yet come first. Write cases with
+save_test_cases (a case the library already has is skipped, so writing the
+same thing twice is harmless), and after save_case, link the automation to the
+test cases it proves with link_test_case.
+
+KNOWLEDGE: project_brief is the project's memory \u2014 read it first. Search
+everything (knowledge pages, documents, requirements, test cases) with
+knowledge_search; read a page with knowledge_read; read documents with
+sources. product.md is "About the product": the person's own description of
+the product, in their words, as long as they like \u2014 read it first. They
+write it, often with you in a conversation beside it; propose text there and
+let them decide, rather than writing product.md unless they ask you to.
+A linked codebase folder is learned into
+codebase/<folder>.md, which must start "# <folder>", then "Commit: <full sha>"
+and "Learned: <yyyy-mm-dd>" lines: that is how the Knowledge screen shows it
+as learned. Keep what you learn with write_knowledge (features/<name>.md,
+memory/decisions.md, a session summary), on Claude's branch for review \u2014
+never a password, key or token.
+
+FROM DOCUMENTS TO TESTS: documents (sources) are PRDs, CRs, feature docs.
+requirements lists what was found in them and what the latest version changed
+(new / changed / removed). For a new requirement: write test cases that cover
+it (save_test_cases with covers: [requirement id]) \u2014 but first check
+find_similar_cases, and link an existing case instead of writing a duplicate.
+For a changed one: update the cases that cover it. For a removed one: mark
+cases that only covered it deprecated. Never invent requirements.
+
+AUTOMATING A TEST CASE: first write the plan with save_automation_plan \u2014 flows
+to reuse, flows to record, which checks prove each expected result, accounts
+and helpers it needs, and anything that cannot be automated and why. Show it
+and wait for the person to approve before recording. Then record, save_case,
+and link_test_case.
+
+MANUAL TESTING: a test cycle is a set of library cases a person runs by hand
+("Release 4.2 regression"); each case is marked passed, failed, blocked or
+skipped, step by step, with a bug raised from the step that broke. Read them
+with test_cycles and bugs; make and change cycles with manage_cycle; record
+what happened with record_result; raise or update bugs with save_bug. Never
+mark a case passed on a person's behalf without being told it passed.
+
+HOW TO WORK:
+1. Call project_catalog. Reuse what exists \u2014 published, and on Claude's working
+   branch \u2014 rather than writing it again.
+2. Before recording, say the plan to the person: the folders, the building-block
+   flows (and what each starts after), and the automations (rows + what each
+   checks). Then record the blocks, earliest first.
+3. Record with start_flow (pass "after" for the flows it continues from), read
+   the page with read_page, and act using the role and name EXACTLY as the page
+   shows them. If a name appears more than once, pass "within" with the name of
+   the region, dialog or form \u2014 or "dialog" / "navigation".
+4. For things outside the page \u2014 an emailed code or link, an authenticator
+   code, a text message, an API call \u2014 use use_helper with a helper from the
+   catalog, then type {{its saveAs name}} into the field that needs it.
+5. Add checks for what each step proves (a heading, a message, a value, the
+   URL). replay_flow, then save_flow. A flow must record at least one check.
+6. Build each automation: preview_case lists its rows and every check, numbered;
+   save_case with the numbers to switch on runs the whole case and saves it only
+   if it passed. Give the person the review link.
+7. Saving the same name again replaces it on the working branch. Old branches
+   of yours? gather_branches puts them into one; discard_branch deletes one \u2014
+   only after the person asks or agrees.
+Test data you invent (a new user's email or password for a sign-up) is fine to
+type. For anything that must be NEW on every run \u2014 a sign-up's email or
+username \u2014 use {{unique}}: it is different on every run and the same within
+one, e.g. qa+{{unique}}@ the domain of the project's mailbox helper, so the
+helper can read that address's verification email with {"email": "qa+{{unique}}@\u2026"}.
+A test that types a fixed new email passes once and fails every run after.`;
+var CASE_INPUT = {
+  type: "object",
+  properties: {
+    name: { type: "string", description: 'The automation: the scenario it proves, e.g. "Wrong password is refused".' },
+    folder: { type: "string", description: 'The case folder \u2014 area and topic, e.g. "Account \u2013 Sign in". Made if new.' },
+    description: { type: "string" },
+    rows: {
+      type: "array",
+      description: "The flows to run, in order. Each row runs in the same browser as the row above unless newBrowser is true (a second person).",
+      items: {
+        type: "object",
+        properties: {
+          flow: { type: "string", description: "A flow's name or id from project_catalog." },
+          newBrowser: { type: "boolean" },
+          checks: {
+            description: `Which of this row's checks to switch on: their numbers from preview_case, or "all". The rest stay off.`,
+            anyOf: [{ type: "array", items: { type: "number" } }, { type: "string", enum: ["all"] }]
+          }
+        },
+        required: ["flow"],
+        additionalProperties: false
+      }
+    },
+    branch: { type: "string", description: "Optional: save onto this branch (chg_\u2026) instead of the working one." },
+    projectId: { type: "string" }
+  },
+  required: ["name", "folder", "rows"],
+  additionalProperties: false
+};
+var caseSpec = (args) => ({
+  name: String(args["name"] ?? ""),
+  folder: String(args["folder"] ?? ""),
+  ...args["description"] ? { description: String(args["description"]) } : {},
+  rows: Array.isArray(args["rows"]) ? args["rows"] : [],
+  ...args["branch"] ? { changeId: String(args["branch"]) } : {}
+});
+var text = (value, isError = false) => ({ content: [{ type: "text", text: value }], ...isError ? { isError } : {} });
+var str = (value) => typeof value === "string" ? value : value === void 0 || value === null ? void 0 : String(value);
+function authoringTools(service, session) {
+  let defaultProject = null;
+  const catalogs = /* @__PURE__ */ new Map();
+  const projectFor = async (asked) => {
+    const named = str(asked);
+    if (named) return defaultProject = named;
+    if (session.draft) return session.draft.projectId;
+    if (defaultProject) return defaultProject;
+    const { projects } = await service.projects();
+    if (projects.length === 1) return defaultProject = projects[0].id;
+    if (projects.length === 0) throw new Error("this account is not on any Flowriki project yet \u2014 create one in the dashboard");
+    throw new Error(`which project? Pass projectId \u2014 one of: ${projects.map((p) => `${p.name} (${p.id})`).join(", ")}`);
+  };
+  const catalogOf = async (projectId, fresh = false) => {
+    if (!fresh && catalogs.has(projectId)) return catalogs.get(projectId);
+    const catalog = await service.catalog(projectId);
+    catalogs.set(projectId, catalog);
+    return catalog;
+  };
+  const tools = [
+    {
+      name: "list_projects",
+      title: "List Flowriki projects",
+      description: "The Flowriki projects you can write tests for, with your role on each. Only needed when you are on more than one.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async () => {
+        const { projects } = await service.projects();
+        return text(projects.length ? projects.map((p) => `${p.name} \u2014 id ${p.id}, you are ${p.role}`).join("\n") : "You are not on any project yet.");
+      }
+    },
+    {
+      name: "create_project",
+      title: "Create a Flowriki project",
+      description: "Create a new Flowriki project, connected to a git repository where its tests will be stored, and pointed at the app to test. The repository must already exist and must not hold another Flowriki project. You become its owner.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: `The project's name, e.g. "Pizza Romano".` },
+          repository: { type: "string", description: "owner/name, or the repository's address, e.g. https://github.com/acme/shop-tests.git" },
+          baseUrl: { type: "string", description: "The app's address, e.g. https://shop.example.com/" }
+        },
+        required: ["name", "repository"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const made = await service.createProject(str(args["name"]) ?? "", str(args["repository"]) ?? "", str(args["baseUrl"]));
+        defaultProject = made.id;
+        catalogs.delete(made.id);
+        return text(`Created "${made.name}" (id ${made.id}), stored in ${made.repository}${made.baseUrl ? `, testing ${made.baseUrl}` : " \u2014 no base URL yet; set one in its settings"}.${made.note ? `
+Note: ${made.note}` : ""}
+It is now the project these tools work on. Open it: ${service.origin}/projects/${made.id}`);
+      }
+    },
+    {
+      name: "project_catalog",
+      title: "What a test can be built from",
+      description: "The project's base URL, features (folders for flows), existing flows, sign-in profiles with their accounts, and helpers (email codes, 2FA, SMS, API calls). Read this before starting a flow.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string", description: "Optional when you are on one project." } }, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const c = await catalogOf(projectId, true);
+        const flowsBy = (featureId) => c.flows.filter((f) => f.featureId === featureId).map((f) => `    - ${f.name} (${f.steps} steps)`).join("\n");
+        return text([
+          `Project ${projectId}. Base URL: ${c.baseUrl || "(not set)"}`,
+          c.environments.length ? `Environments: ${c.environments.map((e) => `${e.name} ${e.baseUrl}`).join(", ")}` : "",
+          `
+Features:${c.features.length ? "" : " none yet"}`,
+          ...c.features.map((f) => `  - ${f.name} (id ${f.id})${f.description ? ` \u2014 ${f.description}` : ""}
+${flowsBy(f.id)}`),
+          ...c.draft ? [
+            `
+On Claude's working branch "${c.draft.title}" (${c.draft.changeId}), not yet published:`,
+            ...c.draft.features.length ? [`  New features: ${c.draft.features.map((f) => `${f.name} (id ${f.id})`).join(", ")}`] : [],
+            ...c.draft.flows.length ? c.draft.flows.map((f) => `    - flow: ${f.name} (${f.steps} steps, feature ${f.featureId}${f.after?.length ? `, after ${f.after.map((a) => `"${a}"`).join(", ")}` : ""})`) : ["  (no flows yet)"],
+            ...c.draft.caseFolders?.length ? [`  New case folders: ${c.draft.caseFolders.map((f) => f.name).join(", ")}`] : [],
+            ...(c.draft.cases ?? []).map((t) => `    - case: ${t.name} (folder ${t.folderId}) \u2014 rows: ${t.rows.join(" \u2192 ")}`)
+          ] : [],
+          `
+Test cases:${(c.cases ?? []).length ? "" : " none published"}`,
+          ...(c.caseFolders ?? []).map((f) => `  - ${f.name} (id ${f.id})
+${(c.cases ?? []).filter((t) => t.folderId === f.id).map((t) => `    - ${t.name} \u2014 rows: ${t.rows.join(" \u2192 ")}`).join("\n")}`),
+          `
+Sign-in profiles:${c.signIns.length ? "" : " none"}`,
+          ...c.signIns.map((s) => `  - ${s.name} (profileId ${s.profileId})${s.fields?.length ? ` \u2014 fields ${s.fields.map((f) => `"${f}"`).join(", ")}` : ""}: ${s.accounts.map((a) => `${a.name} (accountId ${a.accountId})`).join(", ") || "no accounts yet"}`),
+          `
+Helpers:${c.helpers.length ? "" : " none \u2014 create_helper makes one"}`,
+          ...c.helpers.map((h) => `  - ${h.name} (id ${h.id}) \u2014 ${h.what}${h.inputs.length ? `; needs ${h.inputs.map((n) => `{{${n}}}`).join(", ")}` : ""}${h.description ? ` \u2014 ${h.description}` : ""}`)
+        ].filter(Boolean).join("\n"));
+      }
+    },
+    {
+      name: "start_flow",
+      title: "Start writing a flow",
+      description: "Open a browser on this computer at the project's app and start a new flow. Returns the page. Closes any flow that was being written.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: `The flow's name: the user journey, e.g. "Sign up and verify email".` },
+          feature: { type: "string", description: "The feature it belongs to: an existing feature's id or name, or a new name." },
+          startPath: { type: "string", description: 'Where it starts, relative to the base URL. Default "/".' },
+          after: {
+            type: "array",
+            items: { type: "string" },
+            description: "Flows this one starts after (names or ids from project_catalog). They are replayed first, so recording begins where they end; what THEY start after is added too. The saved flow links to them."
+          },
+          signIn: {
+            type: "object",
+            description: "Start signed in, with a profile (and optionally an account) from project_catalog.",
+            properties: { profileId: { type: "string" }, accountId: { type: "string" } },
+            required: ["profileId"],
+            additionalProperties: false
+          },
+          projectId: { type: "string" }
+        },
+        required: ["name", "feature"],
+        additionalProperties: false
+      },
+      annotations: { openWorldHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const catalog = await catalogOf(projectId, true);
+        const featureAsked = str(args["feature"]) ?? "";
+        const feature = catalog.features.find((f) => f.id === featureAsked || f.name.toLowerCase() === featureAsked.toLowerCase());
+        const signIn = args["signIn"];
+        if (signIn && !catalog.signIns.some((s) => s.profileId === signIn.profileId)) {
+          throw new Error(`no sign-in profile ${signIn.profileId} \u2014 project_catalog lists them`);
+        }
+        const asked = Array.isArray(args["after"]) ? args["after"].map(String).filter(Boolean) : [];
+        const plan = asked.length ? await service.flowsAfter(projectId, asked) : null;
+        const page = await session.start({
+          projectId,
+          ...plan ? { after: plan.prerequisites, preparation: plan.steps } : {},
+          name: str(args["name"]) ?? "Untitled flow",
+          ...feature ? { featureId: feature.id } : { featureName: featureAsked },
+          startPath: str(args["startPath"]) || "/",
+          ...signIn?.profileId ? { signIn: { profileId: signIn.profileId, ...signIn.accountId ? { accountId: signIn.accountId } : {} } } : {}
+        }, catalog);
+        const after = plan?.prerequisites.length ? ` It starts after ${plan.prerequisites.map((p) => `"${p.name}"`).join(" \u2192 ")}, which ran first.` : "";
+        return text(`Started "${str(args["name"])}"${feature ? ` in ${feature.name}` : ` in a new feature, ${featureAsked}`}.${after} The browser is open.
+
+${page}`);
+      }
+    },
+    {
+      name: "read_page",
+      title: "Read the page",
+      description: "The current page as its accessibility tree: each element's role and name, which is exactly what act and add_check refer to.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async () => text(await session.snapshot())
+    },
+    {
+      name: "act",
+      title: "Do one thing on the page",
+      description: `Perform one step and keep it in the flow if it worked. Returns the page afterwards. click/dblclick/rightclick/hover: role + name. fill: role + name + value (may use {{values}} from helpers). select: role + name + the option's label as value. check: role + name, value "true" or "false". press: a key such as "Enter" as value, optionally role + name of where. navigate: a path such as "/settings" or a full URL as value. back/forward: nothing.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          action: { type: "string", enum: ["click", "dblclick", "rightclick", "hover", "fill", "select", "check", "press", "navigate", "back", "forward"] },
+          role: { type: "string", description: "The element's role as read_page shows it, e.g. button, link, textbox, checkbox, combobox." },
+          name: { type: "string", description: "The element's accessible name, exactly as read_page shows it." },
+          within: { type: "string", description: "When the name is not unique: the name of the region, dialog, form or navigation that holds it." },
+          nth: { type: "integer", minimum: 0, description: "Which one, when several elements share this role and name: 0 is the first in the order read_page lists them (each shared name is marked [nth N of M]). Leave it out when the name is unique." },
+          value: { type: "string" },
+          secret: { type: "boolean", description: "fill only: the value is a secret (a password, PIN, key) \u2014 kept out of the flow and saved to the vault. Fields named like a password are secret without this." }
+        },
+        required: ["action"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        if (!isAction(args["action"])) throw new Error("action must be one of click, dblclick, rightclick, hover, fill, select, check, press, navigate, back, forward");
+        return text(await session.act({
+          action: args["action"],
+          ...str(args["role"]) ? { role: str(args["role"]) } : {},
+          ...str(args["name"]) !== void 0 ? { name: str(args["name"]) } : {},
+          ...str(args["within"]) ? { within: str(args["within"]) } : {},
+          ...Number.isInteger(args["nth"]) && args["nth"] >= 0 ? { nth: args["nth"] } : {},
+          ...str(args["value"]) !== void 0 ? { value: str(args["value"]) } : {},
+          ...typeof args["secret"] === "boolean" ? { secret: args["secret"] } : {}
+        }));
+      }
+    },
+    {
+      name: "add_check",
+      title: "Add a check",
+      description: "Assert something about the page as it is now, and keep it in the flow if it holds. Page checks need only kind + value: heading, url (a path), title, message. Element checks also need role + name: text, value, visible, hidden, checked, count. op: equals (default), contains or matches.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          kind: { type: "string", enum: ["heading", "url", "title", "message", "screen", "text", "value", "visible", "hidden", "checked", "enabled", "count"] },
+          value: { type: "string", description: `What it should be: the heading's words, the path, "true" for a state, a number for count.` },
+          op: { type: "string", enum: ["equals", "contains", "matches"] },
+          role: { type: "string" },
+          name: { type: "string" },
+          within: { type: "string" },
+          nth: { type: "integer", minimum: 0, description: "Which one, when several elements share this role and name: 0 is the first in the order read_page lists them (each shared name is marked [nth N of M])." }
+        },
+        required: ["kind", "value"],
+        additionalProperties: false
+      },
+      run: async (args) => text(await session.check({
+        kind: str(args["kind"]),
+        value: str(args["value"]) ?? "",
+        ...str(args["op"]) ? { op: str(args["op"]) } : {},
+        ...str(args["role"]) ? { role: str(args["role"]), name: str(args["name"]) ?? "" } : {},
+        ...str(args["within"]) ? { within: str(args["within"]) } : {},
+        ...Number.isInteger(args["nth"]) && args["nth"] >= 0 ? { nth: args["nth"] } : {}
+      }))
+    },
+    {
+      name: "use_helper",
+      title: "Use a helper",
+      description: `Get a value from outside the page with one of the project's helpers \u2014 the code or link from a verification email, an authenticator code, an SMS code, a field of an API reply \u2014 and keep the step. Later steps use it as {{saveAs}}. then: "open" goes to the value as a link (for verification links).`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          helperId: { type: "string", description: "The helper's id or name from project_catalog." },
+          inputs: { type: "object", additionalProperties: { type: "string" }, description: `Values for the helper's {{names}}, e.g. {"email": "qa+signup1@example.com"}.` },
+          saveAs: { type: "string", description: "What to call the value, e.g. code. Default: code for a mailbox, value otherwise." },
+          then: { type: "string", enum: ["remember", "open"] }
+        },
+        required: ["helperId"],
+        additionalProperties: false
+      },
+      run: async (args) => text(await session.useHelper({
+        helperId: str(args["helperId"]),
+        ...args["inputs"] && typeof args["inputs"] === "object" ? { inputs: Object.fromEntries(Object.entries(args["inputs"]).map(([k, v]) => [k, String(v)])) } : {},
+        ...str(args["saveAs"]) ? { saveAs: str(args["saveAs"]) } : {},
+        ...args["then"] === "open" ? { then: "open" } : {}
+      }))
+    },
+    {
+      name: "list_steps",
+      title: "List the flow's steps",
+      description: "The flow being written, step by step.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async () => text(session.list())
+    },
+    {
+      name: "remove_step",
+      title: "Remove a step",
+      description: "Remove one step by its number in list_steps. The browser is not wound back; use replay_flow to see the flow as it now stands.",
+      inputSchema: { type: "object", properties: { number: { type: "integer", minimum: 1 } }, required: ["number"], additionalProperties: false },
+      annotations: { destructiveHint: true },
+      run: async (args) => text(session.remove(Number(args["number"])))
+    },
+    {
+      name: "replay_flow",
+      title: "Replay the flow from the start",
+      description: "Run the whole flow from the beginning in a fresh browser, exactly as a test run will, and report each step. Do this before saving.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+      run: async () => text(await session.replay())
+    },
+    {
+      name: "save_flow",
+      title: "Save the flow to a branch",
+      description: "Save the flow onto Claude's working branch for this project (made on the first save), for a person to review and publish. Saving the same name again replaces the earlier version there. Returns the review link. Refused if the flow checks nothing.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          title: { type: "string", description: "The branch's title, used only when a new branch is started." },
+          branch: { type: "string", description: "Optional: a branch id (chg_\u2026) from list_my_branches to save onto instead." },
+          newBranch: { type: "boolean", description: "Start a separate branch instead of the working one. Only when the person asks for separate reviews." }
+        },
+        additionalProperties: false
+      },
+      run: async (args) => text(await session.save(str(args["title"]), {
+        ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {},
+        ...args["newBranch"] === true ? { newBranch: true } : {}
+      }))
+    },
+    {
+      name: "list_my_branches",
+      title: "List Claude's open branches",
+      description: "The project's open, unpublished branches that Claude wrote for this person, newest first, with review links. Use it to find a superseded branch to discard.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string", description: "Optional when you are on one project." } }, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const { changes } = await service.agentChanges(projectId);
+        if (!changes.length) return text("Claude has no open branches on this project.");
+        return text(changes.map((c) => `- ${c.id} \u2014 "${c.title}" (${new Date(c.createdAt).toISOString().slice(0, 16).replace("T", " ")}) ${service.origin}${c.path}`).join("\n"));
+      }
+    },
+    {
+      name: "gather_branches",
+      title: "Gather Claude's branches into one",
+      description: "Move the flows from Claude's open branches on this project into one branch, and delete the emptied ones \u2014 so the person reviews and publishes once. Only Claude's own, unedited branches; anything a person touched stops it.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          into: { type: "string", description: "The branch to gather into (chg_\u2026). Default: Claude's oldest open branch." },
+          title: { type: "string", description: 'A title for the gathered branch, e.g. "Sign in and sign up tests".' },
+          projectId: { type: "string" }
+        },
+        additionalProperties: false
+      },
+      annotations: { destructiveHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const done = await service.gatherChanges(projectId, {
+          ...str(args["into"]) ? { into: str(args["into"]) } : {},
+          ...str(args["title"]) ? { title: str(args["title"]) } : {}
+        });
+        catalogs.delete(projectId);
+        return text(`Gathered ${done.gathered.length} branch${done.gathered.length === 1 ? "" : "es"} into "${done.title}" (${done.changeId}). Review and publish it here: ${service.origin}${done.path}`);
+      }
+    },
+    {
+      name: "discard_branch",
+      title: "Delete one of Claude's branches",
+      description: "Delete an open branch Claude wrote, with the flows on it \u2014 e.g. one a redo replaced. Only after the person asked for it or agreed. Refused for a branch a person started, edited, or published; those are deleted in the dashboard.",
+      inputSchema: {
+        type: "object",
+        properties: { changeId: { type: "string", description: "The branch's id from list_my_branches (chg_\u2026)." }, projectId: { type: "string" } },
+        required: ["changeId"],
+        additionalProperties: false
+      },
+      annotations: { destructiveHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const changeId = str(args["changeId"]) ?? "";
+        const { deleted } = await service.discardChange(projectId, changeId);
+        return text(`Deleted ${changeId} and its branch ${deleted}.`);
+      }
+    },
+    {
+      name: "preview_case",
+      title: "Preview an automation",
+      description: "Build an automation from flows without saving or running it: its rows (each flow with what it starts after folded in, and which browser it runs in) and every check, numbered, with which are on. Use the numbers in save_case.",
+      inputSchema: CASE_INPUT,
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        return text(await session.previewCase(projectId, caseSpec(args)));
+      }
+    },
+    {
+      name: "save_case",
+      title: "Run and save an automation",
+      description: "Build the automation, run it from the start in a fresh browser exactly as a test run will, and \u2014 only if every row passed \u2014 save it onto Claude's working branch. Saving the same name in the same folder again replaces it. Refused if it switches on no checks.",
+      inputSchema: CASE_INPUT,
+      annotations: { openWorldHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const out = await session.saveCase(projectId, caseSpec(args), await catalogOf(projectId, true));
+        catalogs.delete(projectId);
+        return text(out);
+      }
+    },
+    {
+      name: "create_sign_in",
+      title: "Make a sign-in profile",
+      description: "Turn a saved login flow into a sign-in profile that flows and automations can start signed in with. The flow must not itself sign in or start after other flows, and must end with a check proving the login worked \u2014 its last check is switched on here. Returns the fields an account fills in. Making the same name again replaces Claude's earlier one.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          flow: { type: "string", description: "The login flow's name or id (project_catalog)." },
+          name: { type: "string", description: `What a tester calls this way of signing in, e.g. "Customer sign-in". Default: the flow's name.` },
+          description: { type: "string" },
+          signOutFlow: { type: "string", description: "Optional: a flow that signs out, by name or id." },
+          branch: { type: "string", description: "Optional: the id of one of Claude's open branches to write to (list_my_branches). Default: the working branch." }
+        },
+        required: ["flow"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const made = await service.createSignIn(projectId, {
+          flow: str(args["flow"]) ?? "",
+          ...str(args["name"]) ? { name: str(args["name"]) } : {},
+          ...str(args["description"]) ? { description: str(args["description"]) } : {},
+          ...str(args["signOutFlow"]) ? { signOutFlow: str(args["signOutFlow"]) } : {},
+          ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {}
+        });
+        catalogs.delete(projectId);
+        return text(`${made.replaced ? "Replaced" : "Made"} the sign-in "${made.name}" (profileId ${made.profileId}) from "${made.flow}", on ${made.newBranch ? "a new branch" : "Claude's working branch"} ${made.branch}.
+An account fills in: ${made.fields.map((f) => `"${f.label}"${f.secret ? " (secret)" : ""}`).join(", ") || "nothing \u2014 the flow types no values"}.
+Next: create_account for each person who signs in this way.`);
+      }
+    },
+    {
+      name: "create_account",
+      title: "Make a sign-in account",
+      description: "An account for a sign-in profile: who signs in, and the values its login flow types, by field label (create_sign_in and project_catalog list them). Secret fields are sealed in the project's vault and never shown again. Then start_flow / automations can use signIn {profileId, accountId}. Making the same name again updates Claude's earlier one.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          signIn: { type: "string", description: "The sign-in profile's name or id." },
+          name: { type: "string", description: 'Who this is, e.g. "Demo customer", "Kitchen admin".' },
+          values: { type: "object", additionalProperties: { type: "string" }, description: 'Field label \u2192 value, e.g. {"Email": "demo@example.com", "Password": "\u2026"}.' },
+          environments: { type: "array", items: { type: "string" }, description: "Optional: the environments this account exists on. Default: all." },
+          branch: { type: "string", description: "Optional: the id of one of Claude's open branches to write to (list_my_branches). Default: the working branch." }
+        },
+        required: ["signIn", "name", "values"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const values = Object.fromEntries(Object.entries(args["values"] && typeof args["values"] === "object" ? args["values"] : {}).map(([k, v]) => [k, String(v)]));
+        const made = await service.createAccount(projectId, {
+          signIn: str(args["signIn"]) ?? "",
+          name: str(args["name"]) ?? "",
+          values,
+          ...Array.isArray(args["environments"]) ? { environments: args["environments"].map(String) } : {},
+          ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {}
+        });
+        catalogs.delete(projectId);
+        return text(`${made.replaced ? "Updated" : "Made"} the account "${made.name}" (accountId ${made.accountId}) for "${made.signIn}", on Claude's working branch ${made.branch}. Filled: ${made.filled.join(", ")} \u2014 secrets are in the vault, not the repository.
+Use it with start_flow signIn {"profileId": "\u2026", "accountId": "${made.accountId}"}.`);
+      }
+    },
+    {
+      name: "create_helper",
+      title: "Make a helper",
+      description: `A helper for things outside the page, as the Helpers screen makes one. config by kind \u2014 mailbox: {kind, host, port?, secure?, username, folder?, match?: {to, from, subject}, extract?: {take: code|link|subject|body, pattern}, waitSeconds?} with secretValues {passwordRef: the mailbox password}. totp: {kind, digits?, period?, algorithm?} with secretValues {secretRef: the base32 secret}. sms: {kind, accountSid, to, match?, extract?} with secretValues {authTokenRef: the Twilio token}. http: {kind, method, url, headers?, secretHeaders?: {name: ""}, body?, expectStatus?, extract?: {take: json|pattern|status|nothing, path, pattern}} with secretValues {"header:<name>": value}. Use {{name}} in fields for inputs a step supplies. Secrets are sealed in the vault and never shown again. Making the same name again updates Claude's earlier one.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          name: { type: "string", description: 'e.g. "QA inbox", "Admin authenticator".' },
+          description: { type: "string" },
+          config: { type: "object", description: "The helper's settings, by kind (see above). Never put a secret here." },
+          secretValues: { type: "object", additionalProperties: { type: "string" }, description: "The secret for the kind, keyed as above." },
+          branch: { type: "string", description: "Optional: the id of one of Claude's open branches to write to (list_my_branches). Default: the working branch." }
+        },
+        required: ["name", "config"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const made = await service.createHelper(projectId, {
+          name: str(args["name"]) ?? "",
+          ...str(args["description"]) ? { description: str(args["description"]) } : {},
+          config: args["config"] && typeof args["config"] === "object" ? args["config"] : {},
+          ...args["secretValues"] && typeof args["secretValues"] === "object" ? { secretValues: Object.fromEntries(Object.entries(args["secretValues"]).map(([k, v]) => [k, String(v)])) } : {},
+          ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {}
+        });
+        catalogs.delete(projectId);
+        return text(`${made.replaced ? "Updated" : "Made"} the ${made.kind} helper "${made.name}" (id ${made.helperId}) on Claude's working branch ${made.branch}.${made.inputs.length ? ` A step supplies ${made.inputs.map((n) => `{{${n}}}`).join(", ")}.` : ""} Use it with use_helper.`);
+      }
+    },
+    {
+      name: "library_cases",
+      title: "Read the test library",
+      description: "The project's test cases \u2014 what the team checks \u2014 with their key (TC-n), priority, status, steps and expected results, and which automations check each one. Optional q (title, key or tag) and featureId narrow it. Read before planning automations: cases with priority P0/P1 and no automation are the gaps.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          q: { type: "string", description: "Words in the title, a key like TC-12, or a tag." },
+          featureId: { type: "string", description: "Only this feature's cases, e.g. f_checkout." }
+        },
+        additionalProperties: false
+      },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const { cases, total } = await service.library(projectId, {
+          ...str(args["q"]) ? { q: str(args["q"]) } : {},
+          ...str(args["featureId"]) ? { featureId: str(args["featureId"]) } : {}
+        });
+        if (cases.length === 0) return text(total ? "No test case matches." : "The test library is empty. Write cases with save_test_cases.");
+        const lines = cases.map((c) => {
+          const automated = c.automation.links.length ? `automated by ${c.automation.links.map((l) => l.automationId).join(", ")}${c.automation.links.some((l) => l.caseRevision < c.revision) ? " (case changed since \u2014 check it still matches)" : ""}` : c.automation.state === "not-automatable" ? `manual only: ${c.automation.reason ?? ""}` : c.automation.state === "planned" ? "automation planned" : "NOT AUTOMATED";
+          const steps = c.steps.map((st, i) => `   ${i + 1}. ${st.action}${st.data ? ` [${st.data}]` : ""}${st.expected ? ` \u2192 ${st.expected}` : ""}`).join("\n");
+          return `${c.key} (id ${c.id}, revision ${c.revision}) ${c.title} \u2014 ${c.featureId}, ${c.priority}, ${c.status}, ${automated}${c.preconditions.length ? `
+   Preconditions: ${c.preconditions.join("; ")}` : ""}${steps ? `
+${steps}` : ""}`;
+        });
+        return text(`${cases.length} of ${total} test cases:
+${lines.join("\n")}`);
+      }
+    },
+    {
+      name: "save_test_cases",
+      title: "Write test cases",
+      description: `Add test cases to the library, or edit existing ones, in one commit on Claude's working branch. create: [{feature: "Checkout" (or featureId), title, priority?: P0|P1|P2|P3, type?: functional|negative|edge|regression|smoke|accessibility|other, status?: draft|ready|deprecated, preconditions?: [..], steps: [{action, data?, expected?}], tags?: [..], description?}]. update: [{id, revision (from library_cases), ...only the fields to change}]. A new case the library already has is skipped and named in the answer \u2014 never duplicated.`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          create: { type: "array", items: { type: "object" } },
+          update: { type: "array", items: { type: "object" } },
+          branch: { type: "string", description: "Optional: the id of one of Claude's open branches to write to (list_my_branches). Default: the working branch." }
+        },
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const featureOf = (item) => {
+          const id = str(item["featureId"]);
+          if (id) return id;
+          const name = str(item["feature"]) ?? "General";
+          return `f_${name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "general"}`;
+        };
+        const create = (Array.isArray(args["create"]) ? args["create"] : []).map((raw) => {
+          const { feature: _feature, ...item } = raw;
+          return { ...item, featureId: featureOf(raw) };
+        });
+        const update = (Array.isArray(args["update"]) ? args["update"] : []).map((raw) => {
+          const item = raw;
+          if (item["feature"] === void 0) return item;
+          const { feature: _feature, ...rest } = item;
+          return { ...rest, featureId: featureOf(item) };
+        });
+        const saved = await service.saveLibrary(projectId, {
+          create,
+          update,
+          message: "Test cases written with Claude",
+          ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {}
+        });
+        const made = saved.created.map((c) => `${c.key} ${c.title} (id ${c.id})`);
+        const edited = saved.updated.map((c) => `${c.key} ${c.title}`);
+        return text([
+          made.length ? `Added ${made.length}: ${made.join("; ")}.` : "",
+          edited.length ? `Updated ${edited.length}: ${edited.join("; ")}.` : "",
+          saved.duplicates.length ? `Skipped ${saved.duplicates.length} already in the library: ${saved.duplicates.map((d) => `"${d.title}" is ${d.matches}`).join("; ")}.` : "",
+          `On Claude's working branch ${saved.branch}.`
+        ].filter(Boolean).join(" "));
+      }
+    },
+    {
+      name: "link_test_case",
+      title: "Link an automation to a test case",
+      description: "Record that an automation (a case id from save_case or project_catalog) checks a library test case (its key like TC-12, or its id). unlink: true removes the link. Do this after save_case for every test case the automation proves.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          testCase: { type: "string", description: "TC-12, or the test case id." },
+          automationId: { type: "string" },
+          unlink: { type: "boolean" },
+          branch: { type: "string" }
+        },
+        required: ["testCase", "automationId"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const wanted = str(args["testCase"]) ?? "";
+        const automationId = str(args["automationId"]) ?? "";
+        const { cases } = await service.library(projectId);
+        const target = cases.find((c) => c.id === wanted || c.key.toLowerCase() === wanted.toLowerCase());
+        if (!target) return text(`No test case ${wanted} in the library \u2014 library_cases lists them.`);
+        const has = target.automation.links.some((l) => l.automationId === automationId);
+        const unlink = args["unlink"] === true;
+        if (has !== unlink) return text(`${target.key} is ${unlink ? "not" : "already"} linked to ${automationId}.`);
+        const links = unlink ? target.automation.links.filter((l) => l.automationId !== automationId) : [...target.automation.links, { automationId, caseRevision: target.revision + 1, at: (/* @__PURE__ */ new Date()).toISOString(), by: "Claude" }];
+        const state = links.length ? "automated" : target.automation.state === "automated" ? "none" : target.automation.state;
+        const saved = await service.saveLibrary(projectId, {
+          update: [{ id: target.id, revision: target.revision, automation: { ...target.automation, state, links } }],
+          message: `${unlink ? "Unlink" : "Link"} ${target.key} ${unlink ? "from" : "to"} ${automationId}`,
+          ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {}
+        });
+        return text(`${unlink ? "Unlinked" : "Linked"} ${target.key} "${target.title}" ${unlink ? "from" : "to"} automation ${automationId}, on Claude's working branch ${saved.branch}.`);
+      }
+    },
+    {
+      name: "project_brief",
+      title: "Read the project's memory",
+      description: "The project's own knowledge, in one call: About the product (product.md), memory/decisions.md, what each linked codebase folder was learned as, the list of feature pages and session summaries, and the documents it has. Call it first in every conversation.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" } }, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const [{ pages }, { sources }] = await Promise.all([
+          service.knowledgePages(projectId),
+          service.sources(projectId).catch(() => ({ sources: [] }))
+        ]);
+        const read = async (path) => pages.some((p) => p.path === path) ? (await service.knowledgePage(projectId, path)).content : null;
+        const [product, glossary, decisions] = await Promise.all(["product.md", "glossary.md", "memory/decisions.md"].map(read));
+        const codebases = pages.filter((p) => p.path.startsWith("codebase/"));
+        const headers = await Promise.all(codebases.map(async (p) => `- ${p.path}: ${(await read(p.path))?.split("\n").filter((l) => l.trim()).slice(0, 3).join(" \xB7 ") ?? ""}`));
+        const shown = /* @__PURE__ */ new Set(["product.md", "glossary.md", "memory/decisions.md", ...codebases.map((p) => p.path)]);
+        const parts = [
+          product ? `## About the product (product.md)
+${product}` : "No About the product yet \u2014 the person writes it on the Knowledge screen; offer to help draft it.",
+          glossary ? `## glossary.md (older page; terms now belong in product.md)
+${glossary}` : "",
+          decisions ? `## memory/decisions.md
+${decisions}` : "",
+          codebases.length ? `## Codebase, as learned
+${headers.join("\n")}` : "No codebase learned yet.",
+          `## Other pages
+${pages.filter((p) => !shown.has(p.path)).map((p) => `- ${p.path}`).join("\n") || "none"}`,
+          `## Documents
+${sources.map((s) => `- ${s.title} (id ${s.id}, v${s.version}) \u2014 requirements: ${s.requirements["new"] ?? 0} new, ${s.requirements["changed"] ?? 0} changed, ${s.requirements["active"] ?? 0} unchanged, ${s.requirements["removed"] ?? 0} removed`).join("\n") || "none"}`
+        ];
+        return text(parts.filter(Boolean).join("\n\n"));
+      }
+    },
+    {
+      name: "knowledge_search",
+      title: "Search everything the project knows",
+      description: "Search knowledge pages, source documents, requirements and test cases at once. Returns where each hit is, so it can be cited ([[knowledge:path]], [[source:id@vN]], [[requirement:id]], [[testCase:TC-n]]).",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" }, q: { type: "string" } }, required: ["q"], additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const { hits } = await service.search(projectId, str(args["q"]) ?? "");
+        if (!hits.length) return text("Nothing found.");
+        return text(hits.map((h) => `[[${h.kind}:${h.ref}]] ${h.title}
+   ${h.snippet}`).join("\n"));
+      }
+    },
+    {
+      name: "knowledge_read",
+      title: "Read a knowledge page",
+      description: "Read one knowledge page by path (product.md, codebase/<folder>.md, features/<name>.md, memory/\u2026).",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" }, path: { type: "string" } }, required: ["path"], additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const page = await service.knowledgePage(projectId, str(args["path"]) ?? "");
+        return text(page.content);
+      }
+    },
+    {
+      name: "write_knowledge",
+      title: "Write a knowledge page",
+      description: `Write what the project should remember, on Claude's working branch for review: product.md (About the product \u2014 the person's own description; write it only when they ask), codebase/<folder>.md (what a linked folder holds \u2014 starting with "# <folder>", "Commit: <sha>" and "Learned: <yyyy-mm-dd>" lines, then routes, screens, forms and their validation, roles, APIs, flags; summarised, never copied code), features/<name>.md (screens, rules, quirks), memory/decisions.md (decisions and conventions), memory/sessions/<yyyy-mm-dd>-<topic>.md (what a job did). append: true adds to the end instead of replacing. Never a password, key or token \u2014 those are refused.`,
+      inputSchema: {
+        type: "object",
+        properties: { projectId: { type: "string" }, path: { type: "string" }, content: { type: "string" }, append: { type: "boolean" }, branch: { type: "string" } },
+        required: ["path", "content"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const saved = await service.writeKnowledge(projectId, {
+          path: str(args["path"]) ?? "",
+          content: String(args["content"] ?? ""),
+          ...args["append"] === true ? { append: true } : {},
+          ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {}
+        });
+        return text(`Wrote ${saved.path} (${saved.length} characters) on Claude's working branch ${saved.branch}.`);
+      }
+    },
+    {
+      name: "sources",
+      title: "Read source documents",
+      description: "Without sourceId: every source (PRDs, CRs, feature docs, Jira stories, Figma files\u2026) with its version and how many requirements are new, changed, unchanged or removed. With sourceId: the latest version's text.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" }, sourceId: { type: "string" } }, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const id = str(args["sourceId"]);
+        if (id) {
+          const source = await service.source(projectId, id);
+          return text(`# ${source.title} (v${source.version})
+
+${source.text.slice(0, 6e4)}`);
+        }
+        const { sources } = await service.sources(projectId);
+        if (!sources.length) return text("No sources yet. add_source adds a document by text or link; the Knowledge screen takes files.");
+        return text(sources.map((s) => `${s.title} (id ${s.id}, v${s.version}, ${s.kind}${s.externalUrl ? `, ${s.externalUrl}` : ""}) \u2014 ${s.requirements["new"] ?? 0} new, ${s.requirements["changed"] ?? 0} changed, ${s.requirements["active"] ?? 0} unchanged, ${s.requirements["removed"] ?? 0} removed`).join("\n"));
+      }
+    },
+    {
+      name: "add_source",
+      title: "Add a source document",
+      description: "Add a document tests are written from \u2014 as text (Markdown is best: headings and lists are how requirements are found) or as a public link \u2014 or a new version of one (sourceId). The same text again is not a new version. Requirements are found and compared at once.",
+      inputSchema: {
+        type: "object",
+        properties: { projectId: { type: "string" }, title: { type: "string" }, text: { type: "string" }, url: { type: "string" }, sourceId: { type: "string" } },
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const made = await service.addSource(projectId, {
+          ...str(args["title"]) ? { title: str(args["title"]) } : {},
+          ...typeof args["text"] === "string" ? { text: args["text"] } : {},
+          ...str(args["url"]) ? { url: str(args["url"]) } : {}
+        }, str(args["sourceId"]));
+        const r = made.requirements;
+        return text(made.changed ? `${made.source.title} is now v${made.source.version} (id ${made.source.id}). Requirements: ${r["added"] ?? 0} new, ${r["changed"] ?? 0} changed, ${r["unchanged"] ?? 0} unchanged, ${r["removed"] ?? 0} removed.` : `${made.source.title} has not changed since v${made.source.version}; nothing new.`);
+      }
+    },
+    {
+      name: "delete_source",
+      title: "Delete a source document",
+      description: "Delete a source and everything found in it, for good. Only after the person has said to.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" }, sourceId: { type: "string" } }, required: ["sourceId"], additionalProperties: false },
+      annotations: { destructiveHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        await service.deleteSource(projectId, str(args["sourceId"]) ?? "");
+        return text(`Deleted the source ${str(args["sourceId"])} and its requirements.`);
+      }
+    },
+    {
+      name: "update_requirement",
+      title: "File or correct a requirement",
+      description: "Set which feature a requirement belongs to (featureId like f_checkout), or correct its wording where extraction got it wrong.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" }, requirementId: { type: "string" }, featureId: { type: "string" }, text: { type: "string" } }, required: ["requirementId"], additionalProperties: false },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const saved = await service.updateRequirement(projectId, str(args["requirementId"]) ?? "", {
+          ...typeof args["featureId"] === "string" ? { featureId: args["featureId"] } : {},
+          ...str(args["text"]) ? { text: str(args["text"]) } : {}
+        });
+        return text(`${saved.id}${saved.featureId ? ` is filed under ${saved.featureId}` : ""}: ${saved.text}`);
+      }
+    },
+    {
+      name: "requirements",
+      title: "Read requirements",
+      description: "Requirements found in sources, each with where it is (heading path), its state as of the source's latest version \u2014 new, changed (with what it said before), active (unchanged) or removed \u2014 and its id for covers. Optional sourceId and state narrow it.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" }, sourceId: { type: "string" }, state: { type: "string", enum: ["new", "changed", "active", "removed"] } }, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const [{ requirements }, { cases }] = await Promise.all([
+          service.requirements(projectId, { ...str(args["sourceId"]) ? { sourceId: str(args["sourceId"]) } : {}, ...str(args["state"]) ? { state: str(args["state"]) } : {} }),
+          service.library(projectId)
+        ]);
+        if (!requirements.length) return text("No requirements match.");
+        return text(requirements.map((r) => {
+          const covering = cases.filter((c) => c.covers.includes(r.id)).map((c) => c.key);
+          return `${r.id} [${r.state}] ${r.sourceTitle} \u203A ${r.anchor}: ${r.text}${r.state === "changed" && r.history.length ? `
+   was: ${r.history.at(-1).text}` : ""}
+   covered by: ${covering.join(", ") || "nothing yet"}`;
+        }).join("\n"));
+      }
+    },
+    {
+      name: "find_similar_cases",
+      title: "Find test cases like this one",
+      description: "Before writing a test case, find existing ones that may already check the same thing \u2014 by title and steps. You judge whether one is really the same; if it is, link the requirement to it (covers) instead of writing a duplicate.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" }, text: { type: "string", description: "The case you are about to write: its title and steps." } }, required: ["text"], additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const wanted = String(args["text"] ?? "");
+        const { cases } = await service.library(projectId);
+        const scored = cases.map((c) => ({ c, score: similarity(wanted, [c.title, ...c.steps.flatMap((st) => [st.action, st.expected ?? ""])].join(" ")) })).filter((x) => x.score >= 0.2).sort((a, b) => b.score - a.score).slice(0, 8);
+        if (!scored.length) return text("Nothing similar in the library.");
+        return text(scored.map(({ c, score }) => `${c.key} (id ${c.id}, revision ${c.revision}, ${Math.round(score * 100)}% alike) ${c.title}
+${c.steps.map((st, i) => `   ${i + 1}. ${st.action}${st.expected ? ` \u2192 ${st.expected}` : ""}`).join("\n")}`).join("\n"));
+      }
+    },
+    {
+      name: "save_automation_plan",
+      title: "Write the plan to automate a test case",
+      description: "Save the plan for automating a test case (TC key or id) before recording anything: flows to reuse, flows to record, which check proves each expected result, accounts and helpers it needs, and what cannot be automated and why. Marks it planned. approved: true only when the person has said the plan is right.",
+      inputSchema: {
+        type: "object",
+        properties: { projectId: { type: "string" }, testCase: { type: "string" }, plan: { type: "string" }, approved: { type: "boolean" }, branch: { type: "string" } },
+        required: ["testCase", "plan"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const ref = str(args["testCase"]) ?? "";
+        const { cases } = await service.library(projectId);
+        const target = cases.find((c) => c.id === ref || c.key.toLowerCase() === ref.toLowerCase());
+        if (!target) return text(`No test case ${ref} in the library.`);
+        const saved = await service.saveLibrary(projectId, {
+          update: [{
+            id: target.id,
+            revision: target.revision,
+            automation: {
+              ...target.automation,
+              plan: String(args["plan"] ?? ""),
+              planApproved: args["approved"] === true,
+              state: target.automation.links.length ? target.automation.state : "planned"
+            }
+          }],
+          message: `Automation plan for ${target.key}`,
+          ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {}
+        });
+        return text(`Saved the ${args["approved"] === true ? "approved " : ""}automation plan for ${target.key} "${target.title}" on Claude's working branch ${saved.branch}.`);
+      }
+    },
+    {
+      name: "test_cycles",
+      title: "Read manual test cycles",
+      description: "Manual test cycles and how they are going. Without cycleId: every cycle with its counts (passed, failed, blocked, untested). With cycleId: each case in it \u2014 key, title, steps, the outcome of each step, notes, evidence and bugs.",
+      inputSchema: {
+        type: "object",
+        properties: { projectId: { type: "string" }, cycleId: { type: "string" } },
+        additionalProperties: false
+      },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const counts = (s) => `${s.passed} passed, ${s.failed} failed, ${s.blocked} blocked, ${s.skipped} skipped, ${s.untested} untested of ${s.total}`;
+        const id = str(args["cycleId"]);
+        if (!id) {
+          const { cycles } = await service.cycles(projectId);
+          if (!cycles.length) return text("No test cycles yet. manage_cycle with action create makes one from library cases.");
+          return text(cycles.map((c) => `${c.name} (id ${c.id}, ${c.status}) \u2014 ${counts(c.summary)}`).join("\n"));
+        }
+        const cycle = await service.cycle(projectId, id);
+        const lines = cycle.entries.map((e) => {
+          const r = e.result;
+          const steps = e.steps.map((st, i) => {
+            const got = r?.steps.find((x) => x.stepId === st.id);
+            return `   ${i + 1}. ${st.action}${st.expected ? ` \u2192 ${st.expected}` : ""}: ${got?.outcome ?? "untested"}${got?.actual ? ` (actual: ${got.actual})` : ""}`;
+          }).join("\n");
+          return `${e.key} ${e.title} [${e.priority}] \u2014 ${r?.outcome ?? "untested"}${e.assignee ? `, assigned to ${e.assignee}` : ""}${r?.note ? `
+   Note: ${r.note}` : ""}${r?.bugIds.length ? `
+   Bugs: ${r.bugIds.join(", ")}` : ""}${r?.evidence.length ? `
+   Evidence: ${r.evidence.map((ev) => ev.url ? `${ev.name} <${ev.url}>` : ev.name).join(", ")}` : ""}${steps ? `
+${steps}` : ""}`;
+        });
+        return text(`${cycle.name} (${cycle.status}) \u2014 ${counts(cycle.summary)}
+${lines.join("\n")}`);
+      }
+    },
+    {
+      name: "manage_cycle",
+      title: "Make or change a test cycle",
+      description: "action create: {name, description?, testCases: [TC keys or ids]} \u2014 cases are taken from the library as they are now (on Claude's working branch when it has one). action update: {cycleId, name?, description?, addTestCases?, removeTestCases?, assign?: {testCase, assignee}}. action close / reopen: {cycleId}. action delete: {cycleId} \u2014 deletes the cycle and its results for good; only after the person has said to.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          action: { type: "string", enum: ["create", "update", "close", "reopen", "delete"] },
+          cycleId: { type: "string" },
+          name: { type: "string" },
+          description: { type: "string" },
+          testCases: { type: "array", items: { type: "string" } },
+          addTestCases: { type: "array", items: { type: "string" } },
+          removeTestCases: { type: "array", items: { type: "string" } },
+          assign: { type: "object", properties: { testCase: { type: "string" }, assignee: { type: "string" } }, additionalProperties: false }
+        },
+        required: ["action"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const action = str(args["action"]);
+        const cycleId = str(args["cycleId"]);
+        const resolve = async (refs) => {
+          const wanted = Array.isArray(refs) ? refs.map(String) : [];
+          if (!wanted.length) return { ids: [], changeId: void 0 };
+          const lib = await service.library(projectId);
+          const ids = wanted.map((ref) => lib.cases.find((c) => c.id === ref || c.key.toLowerCase() === ref.toLowerCase())?.id);
+          const missing = wanted.filter((_, i) => !ids[i]);
+          if (missing.length) throw new Error(`no test case ${missing.join(", ")} in the library \u2014 library_cases lists them`);
+          return { ids, changeId: lib.changeId };
+        };
+        if (action === "create") {
+          const name = str(args["name"]);
+          if (!name) return text("A cycle needs a name.");
+          const { ids, changeId } = await resolve(args["testCases"]);
+          const made = await service.createCycle(projectId, { name, ...str(args["description"]) ? { description: str(args["description"]) } : {}, testCaseIds: ids }, changeId);
+          return text(`Made the cycle "${made.name}" (id ${made.id}) with ${made.entries.length} case${made.entries.length === 1 ? "" : "s"}: ${made.entries.map((e) => e.key).join(", ")}.`);
+        }
+        if (!cycleId) return text("Say which cycle (cycleId \u2014 test_cycles lists them).");
+        if (action === "delete") {
+          await service.deleteCycle(projectId, cycleId);
+          return text(`Deleted the cycle ${cycleId} and its results.`);
+        }
+        if (action === "close" || action === "reopen") {
+          const saved2 = await service.updateCycle(projectId, cycleId, { status: action === "close" ? "closed" : "open" });
+          return text(`${saved2.name} is ${saved2.status}.`);
+        }
+        const current = await service.cycle(projectId, cycleId);
+        const inCycle = (ref) => current.entries.find((e) => e.testCaseId === ref || e.key.toLowerCase() === ref.toLowerCase())?.testCaseId;
+        const added = await resolve(args["addTestCases"]);
+        const body = {
+          ...str(args["name"]) ? { name: str(args["name"]) } : {},
+          ...typeof args["description"] === "string" ? { description: args["description"] } : {},
+          ...added.ids.length ? { addCaseIds: added.ids } : {},
+          ...Array.isArray(args["removeTestCases"]) ? { removeCaseIds: args["removeTestCases"].map(String).map((r) => inCycle(r) ?? r) } : {}
+        };
+        const assign = args["assign"];
+        if (assign?.testCase) body["assign"] = { testCaseId: inCycle(assign.testCase) ?? assign.testCase, assignee: assign.assignee ?? "" };
+        const saved = await service.updateCycle(projectId, cycleId, body, added.changeId);
+        return text(`Updated "${saved.name}": ${saved.entries.length} case${saved.entries.length === 1 ? "" : "s"} (${saved.entries.map((e) => e.key).join(", ")}).`);
+      }
+    },
+    {
+      name: "record_result",
+      title: "Record how a case went",
+      description: "Record a manual result for one case in a cycle: steps [{step: its number (1, 2\u2026), outcome: passed|failed|blocked|skipped|untested, actual?: what really happened}], or a whole outcome, a note, links as evidence ([{name, url}]). Any failed step fails the case. retest: true keeps the earlier attempt in the case's history. Only record what the person tells you happened.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          cycleId: { type: "string" },
+          testCase: { type: "string", description: "TC-12, or the test case id." },
+          steps: { type: "array", items: { type: "object" } },
+          outcome: { type: "string", enum: ["passed", "failed", "blocked", "skipped", "untested"] },
+          note: { type: "string" },
+          retest: { type: "boolean" },
+          evidenceLinks: { type: "array", items: { type: "object", properties: { name: { type: "string" }, url: { type: "string" } }, additionalProperties: false } }
+        },
+        required: ["cycleId", "testCase"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const cycleId = str(args["cycleId"]) ?? "";
+        const cycle = await service.cycle(projectId, cycleId);
+        const ref = str(args["testCase"]) ?? "";
+        const entry = cycle.entries.find((e) => e.testCaseId === ref || e.key.toLowerCase() === ref.toLowerCase());
+        if (!entry) return text(`${ref} is not in "${cycle.name}" \u2014 test_cycles lists its cases.`);
+        const steps = (Array.isArray(args["steps"]) ? args["steps"] : []).map((raw) => {
+          const item = raw;
+          const at = typeof item.step === "number" ? entry.steps[item.step - 1]?.id : void 0;
+          return { stepId: String(item.stepId ?? at ?? ""), outcome: String(item.outcome ?? ""), ...typeof item.actual === "string" ? { actual: item.actual } : {} };
+        });
+        const saved = await service.recordResult(projectId, cycleId, entry.testCaseId, {
+          steps,
+          ...str(args["outcome"]) ? { outcome: str(args["outcome"]) } : {},
+          ...typeof args["note"] === "string" ? { note: args["note"] } : {},
+          ...args["retest"] === true ? { retest: true } : {}
+        });
+        for (const link of Array.isArray(args["evidenceLinks"]) ? args["evidenceLinks"] : []) {
+          const { name, url } = link;
+          if (url) await service.addEvidenceLink(projectId, cycleId, entry.testCaseId, { name: name || "Evidence", url });
+        }
+        const now = saved.entries.find((e) => e.testCaseId === entry.testCaseId);
+        return text(`${entry.key} is ${now.result?.outcome ?? "untested"} in "${saved.name}". The cycle: ${saved.summary.passed} passed, ${saved.summary.failed} failed, ${saved.summary.blocked} blocked, ${saved.summary.untested} untested.`);
+      }
+    },
+    {
+      name: "bugs",
+      title: "Read bugs",
+      description: "The project's bugs: key (BUG-n), title, severity, status, and the test cases and cycle step they were found at. Optional status narrows it (open, in-progress, fixed, verified, closed, wont-fix).",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" }, status: { type: "string" } }, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const { bugs } = await service.bugs(projectId);
+        const shown = str(args["status"]) ? bugs.filter((b) => b.status === str(args["status"])) : bugs;
+        if (!shown.length) return text("No bugs.");
+        return text(shown.map((b) => `${b.key} (id ${b.id}) ${b.title} \u2014 ${b.severity}, ${b.status}${b.testCaseIds.length ? `, test cases ${b.testCaseIds.join(", ")}` : ""}${b.description ? `
+   ${b.description.slice(0, 300)}` : ""}`).join("\n"));
+      }
+    },
+    {
+      name: "save_bug",
+      title: "Raise or update a bug",
+      description: "New: {title, description?, severity?: critical|major|minor|trivial, cycleId?, testCase?, step? (its number)} \u2014 found in a cycle, it is attached to that case's result there. Update: {bugId, title?, description?, severity?, status?: open|in-progress|fixed|verified|closed|wont-fix}.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          bugId: { type: "string" },
+          title: { type: "string" },
+          description: { type: "string" },
+          severity: { type: "string" },
+          status: { type: "string" },
+          cycleId: { type: "string" },
+          testCase: { type: "string" },
+          step: { type: "number" }
+        },
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const bugId = str(args["bugId"]);
+        if (bugId) {
+          const body2 = Object.fromEntries(["title", "description", "severity", "status"].filter((k) => typeof args[k] === "string").map((k) => [k, args[k]]));
+          const saved = await service.updateBug(projectId, bugId, body2);
+          return text(`${saved.key} "${saved.title}" is ${saved.status} (${saved.severity}).`);
+        }
+        const title = str(args["title"]);
+        if (!title) return text("A bug needs a title.");
+        const body = {
+          title,
+          ...typeof args["description"] === "string" ? { description: args["description"] } : {},
+          ...str(args["severity"]) ? { severity: str(args["severity"]) } : {}
+        };
+        const cycleId = str(args["cycleId"]);
+        const ref = str(args["testCase"]);
+        if (cycleId && ref) {
+          const cycle = await service.cycle(projectId, cycleId);
+          const entry = cycle.entries.find((e) => e.testCaseId === ref || e.key.toLowerCase() === ref.toLowerCase());
+          if (!entry) return text(`${ref} is not in that cycle.`);
+          const step = typeof args["step"] === "number" ? entry.steps[args["step"] - 1]?.id : void 0;
+          body["foundAt"] = { cycleId, testCaseId: entry.testCaseId, ...step ? { stepId: step } : {} };
+        } else if (ref) {
+          const lib = await service.library(projectId);
+          const found = lib.cases.find((c) => c.id === ref || c.key.toLowerCase() === ref.toLowerCase());
+          if (found) body["testCaseIds"] = [found.id];
+        }
+        const made = await service.createBug(projectId, body);
+        return text(`Raised ${made.key} "${made.title}" (${made.severity}).`);
+      }
+    },
+    {
+      name: "close_browser",
+      title: "Close the browser",
+      description: "Close the browser and drop the flow being written, unsaved.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { destructiveHint: true },
+      run: async () => {
+        await session.close();
+        session.draft = null;
+        return text("Closed.");
+      }
+    }
+  ];
+  return tools.map((tool) => ({
+    ...tool,
+    run: async (args) => {
+      let result;
+      try {
+        result = await tool.run(args);
+      } catch (error) {
+        throw new Error(session.redact(error.message));
+      }
+      return { ...result, content: result.content.map((c) => c.type === "text" && c.text !== void 0 ? { ...c, text: session.redact(c.text) } : c) };
+    }
+  }));
+}
+
+// src/mcp/index.ts
+async function runMcp(opts) {
+  let service;
+  try {
+    service = resolveService(opts.service);
+  } catch (error) {
+    process.stderr.write(`${error.message}
+`);
+    return 2;
+  }
+  const connection = connectionFor(service);
+  const session = connection ? new AuthoringSession(new ServiceClient(connection), opts.headless ? { headless: true } : {}) : null;
+  let tools = connection && session ? authoringTools(new ServiceClient(connection), session) : authoringTools(null, null);
+  if (!connection) {
+    const why = `This computer is not connected to Flowriki at ${service}. Run \`flowriki-agent connect\` in a terminal, approve it in your browser, then restart Claude.`;
+    tools = tools.map((tool) => ({ ...tool, run: async () => ({ content: [{ type: "text", text: why }], isError: true }) }));
+  }
+  const closing = async () => {
+    await session?.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void closing());
+  process.on("SIGTERM", () => void closing());
+  await serve(tools, { name: "flowriki", version: opts.version, instructions: INSTRUCTIONS });
+  await session?.close();
+  return 0;
+}
+
+// src/cli.ts
 var paint = (code) => (s) => `\x1B[${code}m${s}\x1B[0m`;
 var bold = paint("1");
 var dim = paint("2");
@@ -30,6 +2037,9 @@ ${bold("USAGE")}
   flowriki-agent doctor             diagnose setup problems
   flowriki-agent prepare            download the browser recording needs
   flowriki-agent disconnect         forget this computer's credential
+  flowriki-agent mcp                Flowriki as tools for Claude \u2014 started by
+                                    Claude Code or Claude Desktop, not by you:
+                                    claude mcp add flowriki -- flowriki-agent mcp
 
 ${bold("OPTIONS")}
   --project <dir>        a checkout to serve; repeat for several.
@@ -37,6 +2047,7 @@ ${bold("OPTIONS")}
   --name <label>         how this computer appears in your dashboard
   --service <url>        advanced: a self-hosted Flowriki. Defaults to the
                          hosted service, which is what you want.
+  --no-open              print the approval link without opening a browser
   --json                 machine-readable output for status and doctor
   -h, --help             this
   -v, --version          version
@@ -56,6 +2067,7 @@ async function main(argv) {
         name: { type: "string" },
         service: { type: "string" },
         json: { type: "boolean" },
+        "no-open": { type: "boolean" },
         help: { type: "boolean", short: "h" },
         version: { type: "boolean", short: "v" }
       }
@@ -79,8 +2091,13 @@ Run \`flowriki-agent --help\`.`);
   const service = values.service ? String(values.service) : void 0;
   const projects = (values.project ?? []).map(String);
   switch (command) {
+    // FIRST, and before anything writes to stdout: in this mode stdout is the
+    // protocol, and one stray line of output is a message Claude rejects.
+    case "mcp":
+      return runMcp({ ...service ? { service } : {}, version: AGENT_VERSION });
     case "connect": {
       const result = await connect({
+        open: !values["no-open"],
         ...service ? { service } : {},
         ...values.name ? { machineName: String(values.name) } : {},
         onProgress: (note) => {
@@ -91,7 +2108,7 @@ Run \`flowriki-agent --help\`.`);
           console.log(`  ${url}
 `);
           if (note.detail?.["canOpen"] === false) {
-            console.log(dim("  No graphical session here \u2014 open that link on a computer that has one.\n"));
+            console.log(dim("  Open the approval link in your browser.\n"));
           } else {
             console.log(dim("  Opening it for you. If nothing happens, use the link above.\n"));
           }
@@ -108,6 +2125,11 @@ Run \`flowriki-agent --help\`.`);
       return 0;
     }
     case "start": {
+      process.on("unhandledRejection", (reason) => {
+        const said = reason instanceof Error ? reason.stack ?? reason.message : String(reason);
+        console.error(red(`! a command failed without being handled \u2014 the agent is still running`));
+        console.error(dim(said.split("\n").slice(0, 4).join("\n")));
+      });
       const started = await start({
         ...service ? { service } : {},
         ...projects.length ? { projects } : {},
@@ -188,7 +2210,11 @@ Run \`flowriki-agent --help\`.`);
       console.log(`  node       ${found.node}  ${dim(`${found.platform}/${found.arch}`)}`);
       console.log(`  protocol   ${found.protocolVersion}`);
       console.log(`  data       ${found.dataDir}`);
-      console.log(`  service    ${found.service}  ${found.reachable ? green("reachable") : red("unreachable")}`);
+      console.log(
+        `  service    ${found.service}  ${found.reachable ? green("reachable") : red("unreachable")}` + // WHICH FLOWRIKI, from the service's own mouth. Not the site being
+        // tested — that is a project setting and changes nothing here.
+        (found.environment ? dim(`  [${found.environment}]`) : "")
+      );
       console.log(`  credential ${found.credentialFingerprint ?? dim("none stored")}`);
       console.log(
         `  browsers   ${found.playwright.chromiumInstalled ? green("chromium ready") : yellow("chromium not installed")}  ${dim(found.playwright.browsersPath ?? "")}`