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

package/dist/cli.js

@@ -20,9 +20,10 @@ import {
   resolveCheckouts,
   resolveService,
   runtimeValue,
+  similarity,
   start,
   status
-} from "./chunk-N3P4O3OH.js";
+} from "./chunk-7CH5XDEE.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
@@ -212,6 +213,102 @@ var ServiceClient = class {
   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(
@@ -263,6 +360,26 @@ 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})`,
@@ -270,7 +387,7 @@ function describeRows(rows) {
   ].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":
@@ -421,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}
@@ -473,6 +590,7 @@ ${removed.join("\n")}` : "",
       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}` } : {},
@@ -494,7 +612,9 @@ ${removed.join("\n")}` : "",
       });
     } catch (error) {
       if (secret) this.typed.delete(`${TYPED}${id}`);
-      throw new Error(`That did not work, and was not kept: ${error.message.split("\n")[0]}
+      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)}`);
     }
@@ -515,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);
@@ -646,7 +766,7 @@ ${lines.join("\n")}`;
     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 a test case switches on the ones it is about. Nothing is published yet.
+    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,
@@ -729,7 +849,7 @@ THE MODEL \u2014 get this right before recording anything:
   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.
-- A TEST CASE is the test. It strings flows together as rows (in the same
+- 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
@@ -740,6 +860,10 @@ THE MODEL \u2014 get this right before recording anything:
   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.
@@ -750,11 +874,52 @@ THE MODEL \u2014 get this right before recording anything:
   "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 test cases (rows + what each
+   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
@@ -765,7 +930,7 @@ HOW TO WORK:
    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 test case: preview_case lists its rows and every check, numbered;
+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
@@ -780,7 +945,7 @@ 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 test case: the scenario it proves, e.g. "Wrong password is refused".' },
+    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: {
@@ -979,6 +1144,7 @@ ${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." },
+          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." }
         },
@@ -992,6 +1158,7 @@ ${page}`);
           ...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"] } : {}
         }));
@@ -1009,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
@@ -1019,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"] } : {}
       }))
     },
     {
@@ -1143,8 +1312,8 @@ ${page}`);
     },
     {
       name: "preview_case",
-      title: "Preview a test case",
-      description: "Build a test case 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.",
+      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) => {
@@ -1154,8 +1323,8 @@ ${page}`);
     },
     {
       name: "save_case",
-      title: "Run and save a test case",
-      description: "Build the test case, 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.",
+      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) => {
@@ -1168,7 +1337,7 @@ ${page}`);
     {
       name: "create_sign_in",
       title: "Make a sign-in profile",
-      description: "Turn a saved login flow into a sign-in profile that flows and test cases 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.",
+      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: {
@@ -1200,7 +1369,7 @@ 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 / test cases can use signIn {profileId, accountId}. Making the same name again updates Claude's earlier one.",
+      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: {
@@ -1259,6 +1428,595 @@ Use it with start_flow signIn {"profileId": "\u2026", "accountId": "${made.accou
         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",