@flowriki/agent 0.1.0-beta.34 → 0.1.0-beta.39

package/dist/cli.js

@@ -15,13 +15,15 @@ import {
   mirrorCheckTargets,
   openRunSession,
   prepareBrowsers,
+  replayCase,
   replayFlow,
   resolveCheckouts,
   resolveService,
   runtimeValue,
+  similarity,
   start,
   status
-} from "./chunk-7OODSC7P.js";
+} from "./chunk-7CH5XDEE.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
@@ -172,12 +174,141 @@ var ServiceClient = class {
       { method: "DELETE" }
     );
   }
-  saveFlow(projectId, title, flow, where = {}) {
+  saveFlow(projectId, title, flow, where = {}, secretValues = {}) {
     return this.call(
       `/api/agent/flows?projectId=${encodeURIComponent(projectId)}`,
-      { method: "POST", body: JSON.stringify({ title, flow, ...where }) }
+      { 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, integrations ──────────────────────
+  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) });
+  }
+  refreshBug(projectId, id) {
+    return this.call(this.scoped(`/bugs/${encodeURIComponent(id)}/refresh`, projectId), { method: "POST" });
+  }
+  integrations(projectId) {
+    return this.call(this.scoped("/integrations", projectId));
+  }
+  syncIntegration(projectId, id) {
+    return this.call(this.scoped(`/integrations/${encodeURIComponent(id)}/sync`, projectId), { method: "POST" });
+  }
+  pushBug(projectId, bugId, integrationId) {
+    return this.call(this.scoped(`/bugs/${encodeURIComponent(bugId)}/push`, projectId), { method: "POST", body: JSON.stringify({ integrationId }) });
+  }
   /** Gather Claude's open branches here into one. */
   gatherChanges(projectId, opts = {}) {
     return this.call(
@@ -203,6 +334,9 @@ function topLevelBlocks(tree) {
   };
 }
 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"]);
@@ -226,12 +360,38 @@ function labelTree(tree, fields) {
   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 || "";
+  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 `type "${step.value}" into ${target}${where}`;
+      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":
@@ -263,8 +423,23 @@ var AuthoringSession = class {
   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;
   }
@@ -277,11 +452,11 @@ var AuthoringSession = class {
    *  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, [...draft.steps, ...extra], draft.signIn ?? null);
+    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) => prepared.secrets[ref],
+      resolveSecret: (ref) => this.typed.get(ref) ?? prepared.secrets[ref],
       ...runHelper ? { runHelper } : {}
     };
     return this.resolvers;
@@ -297,6 +472,7 @@ var AuthoringSession = class {
     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 });
@@ -326,6 +502,24 @@ var AuthoringSession = class {
     } 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. */
@@ -344,10 +538,10 @@ var AuthoringSession = class {
   async view(full) {
     const { page, draft } = this.requireOpen();
     await page.waitForLoadState("domcontentloaded", { timeout: 1e4 }).catch(() => void 0);
-    const tree = labelTree(
+    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}
@@ -388,13 +582,18 @@ ${removed.join("\n")}` : "",
       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: `s${draft.steps.length + 1}_${Date.now().toString(36)}`,
+      id,
       type: input.action,
       ...target,
       ...scopeOf(input.within),
-      value: input.action === "check" ? input.value === "false" ? "false" : "true" : input.value ?? "",
-      secret: false,
+      ...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
@@ -407,11 +606,15 @@ ${removed.join("\n")}` : "",
         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) {
-      throw new Error(`That did not work, and was not kept: ${error.message.split("\n")[0]}
+      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)}`);
     }
@@ -432,7 +635,7 @@ ${await this.view(false)}`;
       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.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);
@@ -524,6 +727,7 @@ ${this.list()}`;
     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 });
@@ -538,21 +742,77 @@ ${lines.join("\n")}`;
     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: draft.steps,
-      ...draft.signIn ? { signIn: draft.signIn } : {}
-    }, where);
+      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.` : "";
-    return `${what} ${where_}. Nothing is published yet.
+    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;
@@ -572,47 +832,152 @@ Review and publish it here: ${review}${note}`;
 
 // 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 the flow
-you save already ran once. Saved flows go to a NEW branch that a person reviews
-and publishes in the Flowriki dashboard \u2014 nothing you do is published.
+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.
 
-How to write a good Flowriki test:
-1. Call project_catalog first. Reuse an existing feature for the flow when one
-   fits; otherwise name a new one. Check the existing flows so you do not write
-   one that already exists.
-2. One flow is one user journey with one purpose ("Sign up and verify email",
-   "Pay by card"), named the way a tester would say it.
-3. If the journey needs somebody signed in, pass signIn with a profile and an
-   account from the catalog to start_flow. Never type real credentials.
-4. Read the page with read_page and act using the role and name EXACTLY as the
-   page shows them (e.g. button "Continue", textbox "Email"). If a name appears
-   more than once, pass "within" with the name of the region, dialog or form
-   that holds the one you mean.
-5. For things outside the page \u2014 an emailed code or link, an authenticator
+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, sources, requirements, test cases) with
+knowledge_search; read a page with knowledge_read; read source documents with
+sources. Keep what you learn: write_knowledge writes product.md, glossary.md,
+features/<name>.md, memory/decisions.md or a session summary, on Claude's
+branch for review \u2014 never a password, key or token.
+
+FROM DOCUMENTS TO TESTS: sources are PRDs, CRs, Jira stories, Figma frames.
+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.
+
+INTEGRATIONS: integrations lists Jira, Linear, GitHub, Figma and Confluence
+connections; sync_integration reads them as sources. push_bug raises a bug in
+a tracker \u2014 it reaches outside Flowriki, so only after the person says to.
+
+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.
-6. End with at least one check (add_check) that proves the journey worked:
-   a heading, a message, the URL. Saving is refused for a flow that checks nothing.
-7. Before saving, call replay_flow to run the whole flow from the start. If a
-   step fails there, fix it (remove_step, act again) and replay again.
-8. Save with save_flow and give the person the review link it returns. Saves go
-   to ONE working branch per project \u2014 everything you write here lands on it,
-   for one review. Saving a flow with the same name again replaces it there.
-   The catalog lists what is already on that branch: reuse its features, and
-   do not write a flow twice.
-9. Old branches of yours from before (one per flow)? gather_branches puts them
-   into one. discard_branch deletes one \u2014 only after the person asks for it or
-   agrees. Only Claude's own unedited branches can be gathered or deleted;
-   anything a person touched is theirs.
+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) {
@@ -634,7 +999,7 @@ function authoringTools(service, session) {
     catalogs.set(projectId, catalog);
     return catalog;
   };
-  return [
+  const tools = [
     {
       name: "list_projects",
       title: "List Flowriki projects",
@@ -690,13 +1055,19 @@ ${flowsBy(f.id)}`),
             `
 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) => `    - ${f.name} (${f.steps} steps, feature ${f.featureId})`) : ["  (no flows yet)"]
+            ...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.accounts.map((a) => `${a.name} (accountId ${a.accountId})`).join(", ") || "no accounts yet"}`),
+          ...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 they are made on the Helpers screen"}`,
+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"));
       }
@@ -711,6 +1082,11 @@ Helpers:${c.helpers.length ? "" : " none \u2014 they are made on the Helpers scr
           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.",
@@ -733,14 +1109,18 @@ Helpers:${c.helpers.length ? "" : " none \u2014 they are made on the Helpers scr
         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);
-        return text(`Started "${str(args["name"])}"${feature ? ` in ${feature.name}` : ` in a new feature, ${featureAsked}`}. The browser is open.
+        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}`);
       }
@@ -764,7 +1144,9 @@ ${page}`);
           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." },
-          value: { 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]). 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
@@ -776,7 +1158,9 @@ ${page}`);
           ...str(args["role"]) ? { role: str(args["role"]) } : {},
           ...str(args["name"]) !== void 0 ? { name: str(args["name"]) } : {},
           ...str(args["within"]) ? { within: str(args["within"]) } : {},
-          ...str(args["value"]) !== void 0 ? { value: str(args["value"]) } : {}
+          ...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"] } : {}
         }));
       }
     },
@@ -792,7 +1176,8 @@ ${page}`);
           op: { type: "string", enum: ["equals", "contains", "matches"] },
           role: { type: "string" },
           name: { type: "string" },
-          within: { 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
@@ -802,7 +1187,8 @@ ${page}`);
         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"]) } : {}
+        ...str(args["within"]) ? { within: str(args["within"]) } : {},
+        ...Number.isInteger(args["nth"]) && args["nth"] >= 0 ? { nth: args["nth"] } : {}
       }))
     },
     {
@@ -924,6 +1310,713 @@ ${page}`);
         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: product.md, glossary.md, memory/decisions.md, the list of feature pages and session summaries, the codebase summary's header, and the sources and integrations 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 }, { integrations }] = await Promise.all([
+          service.knowledgePages(projectId),
+          service.sources(projectId).catch(() => ({ sources: [] })),
+          service.integrations(projectId).catch(() => ({ integrations: [] }))
+        ]);
+        const read = async (path) => pages.some((p) => p.path === path) ? (await service.knowledgePage(projectId, path)).content : null;
+        const [product, glossary, decisions, codebase] = await Promise.all(["product.md", "glossary.md", "memory/decisions.md", "codebase.json"].map(read));
+        const parts = [
+          product ? `## product.md
+${product}` : "No product.md yet \u2014 write one with write_knowledge once you understand the product.",
+          glossary ? `## glossary.md
+${glossary}` : "",
+          decisions ? `## memory/decisions.md
+${decisions}` : "",
+          codebase ? `## codebase.json (first 1500 characters)
+${codebase.slice(0, 1500)}` : "No codebase summary yet.",
+          `## Other pages
+${pages.filter((p) => !["product.md", "glossary.md", "memory/decisions.md", "codebase.json"].includes(p.path)).map((p) => `- ${p.path}`).join("\n") || "none"}`,
+          `## Sources
+${sources.map((s) => `- ${s.title} (id ${s.id}, v${s.version}, ${s.kind}) \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"}`,
+          `## Integrations
+${integrations.map((i) => `- ${i.name} (${i.platform}, id ${i.id}, ${i.status}${i.lastSyncAt ? `, last read ${i.lastSyncAt}` : ""})`).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, glossary.md, features/<name>.md, memory/\u2026, codebase.json, index.json).",
+      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 (what the app is, roles, environments), glossary.md, features/<name>.md (screens, rules, quirks), memory/decisions.md (decisions and conventions), memory/sessions/<yyyy-mm-dd>-<topic>.md (what a job did), codebase.json (the codebase summary: routes, screens, forms, roles, APIs, and the commit read). 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: "integrations",
+      title: "Read integrations",
+      description: "The project's connections to Jira, Linear, GitHub, Figma and Confluence: what each is, whether it works, when it was last read, and which take bugs.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" } }, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const { integrations } = await service.integrations(projectId);
+        if (!integrations.length) return text("No integrations. An owner connects them on the Knowledge screen.");
+        return text(integrations.map((i) => `${i.name} (${i.platform}, id ${i.id}) \u2014 ${i.status}${i.lastSyncAt ? `, last read ${i.lastSyncAt}` : ", never read"}${["jira", "linear", "github"].includes(i.platform) ? ", takes bugs" : ""}`).join("\n"));
+      }
+    },
+    {
+      name: "sync_integration",
+      title: "Read an integration's items as sources",
+      description: "Read what an integration holds (Jira stories, Linear and GitHub issues, Confluence pages, Figma frames) as sources. Items unchanged since the last read stay as they are.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" }, integrationId: { type: "string" } }, required: ["integrationId"], additionalProperties: false },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const done = await service.syncIntegration(projectId, str(args["integrationId"]) ?? "");
+        return text(`Read ${done.items} item${done.items === 1 ? "" : "s"}: ${done.newSources} new, ${done.newVersions} changed, ${done.unchanged} unchanged. Requirements: ${done.requirements["added"] ?? 0} new, ${done.requirements["changed"] ?? 0} changed, ${done.requirements["removed"] ?? 0} removed.`);
+      }
+    },
+    {
+      name: "push_bug",
+      title: "Raise a bug in a tracker",
+      description: "Raise a Flowriki bug (BUG-n or its id) in Jira, Linear or GitHub through one of the project's integrations. This reaches outside Flowriki: only after the person has said to.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" }, bug: { type: "string" }, integrationId: { type: "string" } }, required: ["bug", "integrationId"], additionalProperties: false },
+      annotations: { destructiveHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const ref = str(args["bug"]) ?? "";
+        const { bugs } = await service.bugs(projectId);
+        const bug = bugs.find((b) => b.id === ref || b.key.toLowerCase() === ref.toLowerCase());
+        if (!bug) return text(`No bug ${ref}.`);
+        const pushed = await service.pushBug(projectId, bug.id, str(args["integrationId"]) ?? "");
+        return text(`${bug.key} is now ${pushed.externalKey} in ${pushed.tracker}: ${pushed.url}`);
+      }
+    },
+    {
+      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}. {bugId, refresh: true} reads a pushed bug's status back from its tracker.",
+      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" },
+          refresh: { type: "boolean" }
+        },
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const bugId = str(args["bugId"]);
+        if (bugId && args["refresh"] === true) {
+          const fresh = await service.refreshBug(projectId, bugId);
+          return text(`${fresh.key} is ${fresh.status} in its tracker.`);
+        }
+        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",
@@ -937,6 +2030,18 @@ ${page}`);
       }
     }
   ];
+  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