@flowriki/agent 0.1.0-beta.6 → 0.1.0-beta.60

package/dist/cli.js

@@ -1,17 +1,2755 @@
 #!/usr/bin/env node
 import {
+  AGENT_LATEST_URL,
   AGENT_VERSION,
+  agentUpdateFor,
+  authenticationResolver,
+  checkAssertion,
+  closeRunSession,
   connect,
+  connectionFor,
+  dataDir,
   disconnect,
   doctor,
+  executeStep,
+  fieldNames,
+  flowrikiHome,
+  helperRunner,
+  openRunSession,
   prepareBrowsers,
+  replayCase,
+  replayFlow,
   resolveCheckouts,
+  resolveService,
+  runtimeValue,
   start,
   status
-} from "./chunk-ZUHML4TR.js";
+} from "./chunk-BYFYSV5H.js";
+import {
+  CLOUD_PROVIDERS,
+  CLOUD_PROVIDER_NAME,
+  CODEBASE_TAG_NAME,
+  MobileLane,
+  RecordedStepSchema,
+  checkMobileAssertion,
+  codebaseIndexOf,
+  exploreSummary,
+  isMobile,
+  listDevices,
+  locate,
+  mirrorCheckTargets,
+  mobileDoctor,
+  mobileOf,
+  mobileSetup,
+  nameKey,
+  openMobileSession,
+  parseGherkin,
+  performMobileStep,
+  platformsOf,
+  replayMobileCase,
+  runMobileSteps,
+  screenLines,
+  slugify,
+  stepRefusedOn,
+  targetFor
+} from "./chunk-WQ22OUIQ.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
+
+// src/mcp/protocol.ts
+import readline from "readline";
+var PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+async function handle(message, tools, info) {
+  const reply = (result) => ({ jsonrpc: "2.0", id: message.id ?? null, result });
+  const fail = (code, text2) => ({ jsonrpc: "2.0", id: message.id ?? null, error: { code, message: text2 } });
+  if (message.id === void 0 || message.id === null) return null;
+  switch (message.method) {
+    case "initialize": {
+      const asked = String(message.params?.["protocolVersion"] ?? "");
+      const version = PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0];
+      return reply({
+        protocolVersion: version,
+        capabilities: { tools: { listChanged: true } },
+        serverInfo: { name: info.name, version: info.version },
+        instructions: info.instructions
+      });
+    }
+    case "ping":
+      return reply({});
+    case "tools/list":
+      return reply({
+        tools: tools.map(({ name, title, description, inputSchema, annotations }) => ({
+          name,
+          ...title ? { title } : {},
+          description,
+          inputSchema,
+          ...annotations ? { annotations } : {}
+        }))
+      });
+    case "tools/call": {
+      const name = String(message.params?.["name"] ?? "");
+      const tool = tools.find((t) => t.name === name);
+      if (!tool) return fail(-32602, `no tool named ${name}`);
+      const args = message.params?.["arguments"] ?? {};
+      try {
+        return reply(await tool.run(args));
+      } catch (error) {
+        return reply({ content: [{ type: "text", text: error.message }], isError: true });
+      }
+    }
+    default:
+      return fail(-32601, `method not found: ${message.method}`);
+  }
+}
+function serve(tools, info, io = {}) {
+  const input = io.input ?? process.stdin;
+  const output = io.output ?? process.stdout;
+  if (!io.output) {
+    console.log = console.info = console.warn = console.debug = (...args) => {
+      process.stderr.write(`${args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ")}
+`);
+    };
+  }
+  const lines = readline.createInterface({ input, crlfDelay: Infinity });
+  const pending = /* @__PURE__ */ new Set();
+  lines.on("line", (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      output.write(`${JSON.stringify({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } })}
+`);
+      return;
+    }
+    const task = handle(message, tools, info).then((answer) => {
+      if (answer) output.write(`${JSON.stringify(answer)}
+`);
+      if (message.method === "notifications/initialized") {
+        output.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/tools/list_changed" })}
+`);
+      }
+    });
+    pending.add(task);
+    void task.finally(() => pending.delete(task));
+  });
+  return new Promise((resolve) => lines.on("close", () => void Promise.allSettled([...pending]).then(() => resolve())));
+}
+
+// src/mcp/service-client.ts
+var ASK_ID = (process.env["FLOWRIKI_ASK_ID"] ?? "").trim().slice(0, 200);
+var ServiceClient = class {
+  constructor(connection, fetcher = fetch) {
+    this.connection = connection;
+    this.fetcher = fetcher;
+  }
+  connection;
+  fetcher;
+  get origin() {
+    return this.connection.service;
+  }
+  /** One request to the service, retried when the service — or the proxy in
+   *  front of it — says it is too busy. A 429 or a 503 from the edge means
+   *  the request was never handled, so trying again is safe for any method;
+   *  a 502/504 is retried only when nothing could have happened (a GET).
+   *  Backing off here, inside the tool, is what keeps the model from asking
+   *  again every two seconds and making the limit worse. */
+  async call(path3, init = {}, attempt = 0) {
+    const res = await this.fetcher(`${this.connection.service}${path3}`, {
+      ...init,
+      headers: {
+        "x-flowriki-device": this.connection.deviceId,
+        "x-flowriki-device-secret": this.connection.secret,
+        "content-type": "application/json",
+        // The dashboard's question these tools are answering, when they are:
+        // what they build is filed on it, for the person to watch.
+        ...ASK_ID ? { "x-flowriki-ask": ASK_ID } : {}
+      }
+    });
+    const text2 = await res.text();
+    let body = {};
+    try {
+      body = text2 ? JSON.parse(text2) : {};
+    } catch {
+    }
+    if (!res.ok) {
+      const method = String(init.method ?? "GET").toUpperCase();
+      const busy = res.status === 429 || res.status === 503 || method === "GET" && (res.status === 502 || res.status === 504);
+      if (busy && attempt < 4) {
+        const asked = Number(res.headers.get("retry-after"));
+        const wait = Math.min(15e3, res.headers.get("retry-after") !== null && Number.isFinite(asked) && asked >= 0 ? asked * 1e3 : 1e3 * 2 ** attempt);
+        await new Promise((r) => setTimeout(r, wait));
+        return this.call(path3, init, attempt + 1);
+      }
+      if (res.status === 404 && !("error" in body)) {
+        throw new Error("the Flowriki service does not offer this yet \u2014 it may need updating");
+      }
+      if (busy) throw new Error(`the Flowriki service is too busy right now (${res.status}) and stayed so after several tries \u2014 wait a minute before asking again, and do not retry in a loop`);
+      throw new Error(String(body["error"] ?? `the service answered ${res.status}`));
+    }
+    return body;
+  }
+  projects() {
+    return this.call("/api/agent/projects");
+  }
+  createProject(name, repository, baseUrl) {
+    return this.call("/api/agent/projects", {
+      method: "POST",
+      body: JSON.stringify({ name, repository, ...baseUrl ? { baseUrl } : {} })
+    });
+  }
+  catalog(projectId) {
+    return this.call(`/api/agent/catalog?projectId=${encodeURIComponent(projectId)}`);
+  }
+  /** `cloud` asks for that device farm's access key too, for a flow written
+   *  on one of its phones. */
+  prepare(projectId, steps, signIn, extra = {}) {
+    return this.call(`/api/agent/prepare?projectId=${encodeURIComponent(projectId)}`, {
+      method: "POST",
+      body: JSON.stringify({ steps, ...signIn ? { signIn } : {}, ...extra.cloud ? { cloud: extra.cloud } : {} })
+    });
+  }
+  /** This person's open branches that Claude wrote on this project. */
+  agentChanges(projectId) {
+    return this.call(
+      `/api/agent/changes?projectId=${encodeURIComponent(projectId)}`
+    );
+  }
+  /** Delete one — refused by the service unless it is all Claude's own,
+   *  unedited, unpublished work. */
+  discardChange(projectId, changeId) {
+    return this.call(
+      `/api/agent/changes/${encodeURIComponent(changeId)}?projectId=${encodeURIComponent(projectId)}`,
+      { method: "DELETE" }
+    );
+  }
+  saveFlow(projectId, title, flow, where = {}, secretValues = {}) {
+    return this.call(
+      `/api/agent/flows?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify({ title, flow, ...where, secretValues }) }
+    );
+  }
+  /** A sign-in made from a recorded login flow. */
+  createSignIn(projectId, input) {
+    return this.call(
+      `/api/agent/sign-ins?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(input) }
+    );
+  }
+  /** An account for a sign-in; secret values are sealed by the service and
+   *  never come back. */
+  createAccount(projectId, input) {
+    return this.call(
+      `/api/agent/accounts?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(input) }
+    );
+  }
+  /** A helper, its secrets sealed by the service. */
+  createHelper(projectId, input) {
+    return this.call(
+      `/api/agent/helpers?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(input) }
+    );
+  }
+  /** What a new flow starts after: the flows, in run order, and their steps. */
+  flowsAfter(projectId, after) {
+    return this.call(
+      `/api/agent/flows/after?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify({ after }) }
+    );
+  }
+  /** Build a test case from flows — as a dry run, or saved. */
+  /** The flow being recorded, as it stands, for the dashboard's job. Only
+   *  when these tools answer a question asked in the dashboard. */
+  async reportDraft(projectId, draft) {
+    if (!ASK_ID) return;
+    await this.call(`/api/agent/jobs/draft?projectId=${encodeURIComponent(projectId)}`, { method: "POST", body: JSON.stringify({ draft }) });
+  }
+  /** The test case being built, as it stands, for the dashboard's job. */
+  async reportCase(projectId, live) {
+    if (!ASK_ID) return;
+    await this.call(`/api/agent/jobs/case?projectId=${encodeURIComponent(projectId)}`, { method: "POST", body: JSON.stringify({ case: live }) });
+  }
+  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. */
+  importPart(projectId, draftId, part) {
+    return this.call(
+      `/api/agent/import-drafts/${encodeURIComponent(draftId)}?projectId=${encodeURIComponent(projectId)}&part=${part}`
+    );
+  }
+  saveImportCases(projectId, draftId, body) {
+    return this.call(
+      `/api/agent/import-drafts/${encodeURIComponent(draftId)}/cases?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(body) }
+    );
+  }
+  updateRequest(projectId, id) {
+    return this.call(
+      `/api/agent/update-requests/${encodeURIComponent(id)}?projectId=${encodeURIComponent(projectId)}`
+    );
+  }
+  proposeUpdates(projectId, id, body) {
+    return this.call(
+      `/api/agent/update-requests/${encodeURIComponent(id)}/proposals?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(body) }
+    );
+  }
+  readCases(projectId, refs) {
+    const ids = refs.filter((r) => /^tc_/.test(r.trim()));
+    const names = refs.filter((r) => !/^tc_/.test(r.trim()));
+    const q = new URLSearchParams({ projectId, ...ids.length ? { ids: ids.join(",") } : {}, ...names.length ? { names: names.join("|") } : {} });
+    return this.call(`/api/agent/cases/read?${q}`);
+  }
+  /** Test cases written down — business steps, no flows yet — on Claude's
+   *  working branch. */
+  writeCases(projectId, groups, changeId) {
+    return this.call(
+      `/api/agent/cases/batch?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify({ groups, ...changeId ? { changeId } : {} }) }
+    );
+  }
+  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(path3, projectId, extra = {}) {
+    const query = new URLSearchParams({ projectId, ...extra });
+    return `/api/agent${path3}?${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 ──────────────────────
+  /** The project's brief for a job: its slice of the knowledge. */
+  brief(projectId, scope) {
+    return this.call(this.scoped("/brief", projectId, { ...scope.platform ? { platform: scope.platform } : {}, ...scope.features?.length ? { features: scope.features.join(",") } : {} }));
+  }
+  knowledgePages(projectId) {
+    return this.call(this.scoped("/knowledge", projectId));
+  }
+  knowledgePage(projectId, path3) {
+    return this.call(this.scoped("/knowledge/page", projectId, { path: path3 }));
+  }
+  writeKnowledge(projectId, body) {
+    return this.call(`/api/agent/knowledge?projectId=${encodeURIComponent(projectId)}`, { method: "POST", body: JSON.stringify(body) });
+  }
+  search(projectId, q) {
+    return this.call(this.scoped("/search", projectId, { q }));
+  }
+  sources(projectId) {
+    return this.call(this.scoped("/sources", projectId));
+  }
+  source(projectId, id) {
+    return this.call(this.scoped(`/sources/${encodeURIComponent(id)}`, projectId));
+  }
+  addSource(projectId, body, sourceId) {
+    return this.call(
+      this.scoped(sourceId ? `/sources/${encodeURIComponent(sourceId)}/versions` : "/sources", projectId),
+      { method: "POST", body: JSON.stringify(body) }
+    );
+  }
+  requirements(projectId, opts = {}) {
+    return this.call(
+      this.scoped("/requirements", projectId, { ...opts.sourceId ? { sourceId: opts.sourceId } : {}, ...opts.state ? { state: opts.state } : {} })
+    );
+  }
+  deleteSource(projectId, id) {
+    return this.call(this.scoped(`/sources/${encodeURIComponent(id)}`, projectId), { method: "DELETE" });
+  }
+  updateRequirement(projectId, id, body) {
+    return this.call(this.scoped(`/requirements/${encodeURIComponent(id)}`, projectId), { method: "PATCH", body: JSON.stringify(body) });
+  }
+  /** Gather Claude's open branches here into one. */
+  gatherChanges(projectId, opts = {}) {
+    return this.call(
+      `/api/agent/changes/gather?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify(opts) }
+    );
+  }
+};
+
+// src/mcp/session.ts
+import fs from "fs";
+import path from "path";
+var MAX_TREE = 14e3;
+var MAX_STEP_VIEW = 6e3;
+function topLevelBlocks(tree) {
+  const blocks = [];
+  for (const line of tree.split("\n")) {
+    if (line.startsWith("- ") || blocks.length === 0) blocks.push([line]);
+    else blocks[blocks.length - 1].push(line);
+  }
+  const named = (b, kinds) => kinds.some((k) => b[0].startsWith(`- ${k}`));
+  return {
+    dialogs: blocks.filter((b) => named(b, ["dialog", "alertdialog"])).map((b) => b.join("\n")),
+    navigation: blocks.find((b) => named(b, ["navigation", "banner"]))?.join("\n") ?? null
+  };
+}
+var STEP_TIMEOUT_MS = 1e4;
+var SECRET_WORDS = /password|passwd|pass[-_\s]?code|pwd|secret|otp|one[-_\s]?time[-_\s]?(code|pass)|security[-_\s]?(code|answer)|cvv|cvc|\bpin\b/i;
+var TYPED = "typed_";
+var withoutTyped = (steps) => steps.map((st) => st.secretRef?.startsWith(TYPED) ? (({ secretRef: _, ...rest }) => rest)(st) : st);
+var ACTIONS = [
+  "click",
+  "dblclick",
+  "rightclick",
+  "hover",
+  "fill",
+  "select",
+  "check",
+  "press",
+  "navigate",
+  "back",
+  "forward",
+  // On a phone: a tap is a click, and these have no web equivalent.
+  "tap",
+  "longPress",
+  "swipe",
+  "scroll",
+  "hideKeyboard",
+  "launchApp",
+  "terminateApp",
+  "resetApp",
+  "background",
+  "rotate",
+  "permission"
+];
+var isAction = (value) => ACTIONS.includes(String(value));
+var LANDMARKS = /* @__PURE__ */ new Set(["main", "navigation", "banner", "contentinfo", "complementary", "search", "form", "dialog", "alertdialog", "region", "group", "list", "table", "menu", "toolbar", "tablist"]);
+function scopeOf(within) {
+  const said = within?.trim() ?? "";
+  if (!said) return { scope: "" };
+  return LANDMARKS.has(said.toLowerCase()) ? { scope: "", scopeRole: said.toLowerCase() } : { scope: said };
+}
+function asLabelled(target, fields) {
+  const field = fields.find((f) => f.role === target.role && (f.label === target.name || f.hint === target.name));
+  if (!field) return target;
+  return {
+    ...target,
+    name: field.label,
+    nameFrom: "adjacent-label",
+    ...field.hintFrom === "name" ? {} : { candidates: [{ strategy: field.hintFrom, value: field.hint }] }
+  };
+}
+function labelTree(tree, fields) {
+  let out = tree;
+  for (const f of fields) out = out.split(`- ${f.role} ${JSON.stringify(f.hint)}`).join(`- ${f.role} ${JSON.stringify(f.label)}`);
+  return out;
+}
+function numberDuplicates(tree) {
+  const line = /^(\s*- )([\w-]+) "((?:[^"\\]|\\.)*)"(.*)$/;
+  const totals = /* @__PURE__ */ new Map();
+  const lines = tree.split("\n");
+  for (const l of lines) {
+    const m = line.exec(l);
+    if (m) totals.set(`${m[2]}|${m[3]}`, (totals.get(`${m[2]}|${m[3]}`) ?? 0) + 1);
+  }
+  const seen = /* @__PURE__ */ new Map();
+  return lines.map((l) => {
+    const m = line.exec(l);
+    if (!m) return l;
+    const key = `${m[2]}|${m[3]}`;
+    const total = totals.get(key) ?? 1;
+    if (total < 2) return l;
+    const at = seen.get(key) ?? 0;
+    seen.set(key, at + 1);
+    return `${l}  [nth ${at} of ${total} with this name]`;
+  }).join("\n");
+}
+function deviceFrom(said, platform, devices, mobile) {
+  const want = said?.trim();
+  if (!want) return mobile?.devices[platform];
+  const lower = want.toLowerCase();
+  const mine = devices.filter((d) => d.platform === platform);
+  const local = mine.find((d) => d.id.toLowerCase() === lower || d.name.toLowerCase() === lower) ?? mine.find((d) => d.name.toLowerCase().includes(lower));
+  if (local) return { kind: "local", id: local.id, name: local.name };
+  const farm = /^([^:]+):\s*(.+?)(?:\s+(\d+(?:\.\d+)*))?$/.exec(want);
+  const provider = farm && CLOUD_PROVIDERS.find((p) => p === farm[1].trim().toLowerCase().replace(/\s+/g, "") || CLOUD_PROVIDER_NAME[p].toLowerCase() === farm[1].trim().toLowerCase());
+  if (farm && provider) {
+    if (!mobile?.cloud.some((c) => c.provider === provider)) throw new Error(`${CLOUD_PROVIDER_NAME[provider]} is not connected to this project \u2014 add it in Settings \u2192 Mobile`);
+    return { kind: "cloud", provider, device: farm[2].trim(), ...farm[3] ? { osVersion: farm[3] } : {} };
+  }
+  throw new Error(`no ${platform === "ios" ? "iOS" : "Android"} device called "${want}" \u2014 connected: ${mine.map((d) => d.name).join(", ") || "none"}`);
+}
+async function devicesSummary() {
+  return listDevices().catch(() => []);
+}
+function describeRows(rows, testCase) {
+  return rows.map((r, i) => {
+    const steps = testCase?.occurrences[i]?.steps;
+    if (r.steps?.length && steps?.length === r.steps.length) {
+      const on = new Map(r.checks.map((c) => [c.n, c.on]));
+      return [
+        `Row ${r.row}: "${r.flow}" (${r.browser})`,
+        ...r.steps.map((st, j) => `  step ${st.n}. ${describe(steps[j])}${st.check !== void 0 ? `  \u2014 check ${st.check} ${on.get(st.check) ? "[on]" : "[off]"}` : ""}`)
+      ].join("\n");
+    }
+    return [
+      `Row ${r.row}: "${r.flow}" (${r.browser})`,
+      ...r.checks.length ? r.checks.map((c) => `  ${c.on ? "[on] " : "[off]"} ${c.n}. ${c.check}`) : ["  (no checks in this flow)"]
+    ].join("\n");
+  }).join("\n");
+}
+function describe(step) {
+  const target = (step.name ? `${step.role || "element"} "${step.name}"` : step.role || "") + (step.nth !== void 0 ? ` (nth ${step.nth})` : "");
+  const where = step.scope ? ` in "${step.scope}"` : step.scopeRole ? ` in the ${step.scopeRole}` : "";
+  switch (step.type) {
+    case "fill":
+      return step.secret ? `type a secret (\u2022\u2022\u2022\u2022\u2022\u2022) into ${target}${where}` : `type "${step.value}" into ${target}${where}`;
+    case "select":
+      return `choose "${step.value}" in ${target}${where}`;
+    case "check":
+      return `${step.value === "false" ? "untick" : "tick"} ${target}${where}`;
+    case "press":
+      return `press ${step.value}${target ? ` in ${target}` : ""}`;
+    case "navigate":
+      return `go to ${step.value}`;
+    case "back":
+    case "forward":
+      return `browser ${step.type}`;
+    case "assert":
+      return `check ${step.proposals.map((p) => `${p.kind}${p.op && p.op !== "equals" ? ` ${p.op}` : ""} "${String(p.value)}"${p.target?.name ? ` on ${p.target.role} "${p.target.name}"` : ""}`).join(", ")}`;
+    case "useHelper":
+      return `use helper ${step.name || step.helper?.helperId} \u2192 {{${step.helper?.saveAs}}}${step.helper?.then === "open" ? ", then open it" : ""}`;
+    case "swipe":
+      return `swipe ${step.value}${target ? ` on ${target}` : ""}`;
+    case "scroll":
+      return target ? `scroll to ${target}` : `scroll ${step.value}`;
+    case "longPress":
+      return `long-press ${target}${where}`;
+    case "hideKeyboard":
+      return "hide the keyboard";
+    case "launchApp":
+      return "open the app";
+    case "terminateApp":
+      return "close the app";
+    case "resetApp":
+      return "clear the app's data and open it";
+    case "background":
+      return `send the app to the background for ${step.value || 3}s`;
+    case "rotate":
+      return `rotate to ${step.value}`;
+    case "permission":
+      return `${step.value === "deny" ? "deny" : "allow"} the permission prompt`;
+    default:
+      return `${step.type} ${target}${where}`;
+  }
+}
+var AuthoringSession = class _AuthoringSession {
+  constructor(service, opts = {}) {
+    this.service = service;
+    this.opts = opts;
+  }
+  service;
+  opts;
+  run = null;
+  page = null;
+  /** The phone, when the flow being written runs on one. */
+  mobile = null;
+  values = /* @__PURE__ */ new Map();
+  resolvers = null;
+  lastTree = null;
+  /** Values typed into secret fields, by their `typed:` reference. */
+  typed = /* @__PURE__ */ new Map();
+  draft = null;
+  /** The steps as last replayed from the start and passed — a save of the
+   *  same steps needs no second replay. Cleared by any change to them. */
+  verified = 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 || this.mobile !== null;
+  }
+  requireMobile() {
+    if (!this.mobile || !this.draft) throw new Error("no flow is being written \u2014 call start_flow first");
+    return { mobile: this.mobile, draft: this.draft };
+  }
+  requireOpen() {
+    if (!this.run || !this.page || !this.draft) throw new Error("no flow is being written \u2014 call start_flow first");
+    return { page: this.page, draft: this.draft, run: this.run };
+  }
+  /** What the steps so far, plus any about to run, need from the service:
+   *  sign-ins, helpers, and their secret values. Asked again whenever a new
+   *  helper or sign-in appears, never kept beyond this process. */
+  async prepare(extra = []) {
+    const draft = this.draft;
+    const prepared = await this.service.prepare(
+      draft.projectId,
+      withoutTyped([...draft.preparation ?? [], ...draft.steps, ...extra]),
+      draft.signIn ?? null,
+      draft.device?.kind === "cloud" ? { cloud: draft.device.provider } : {}
+    );
+    const runHelper = helperRunner(prepared.helpers, prepared.secrets);
+    this.resolvers = {
+      resolveAuth: authenticationResolver(prepared.authentications),
+      resolveSecret: (ref) => this.typed.get(ref) ?? prepared.secrets[ref],
+      ...runHelper ? { runHelper } : {}
+    };
+    return this.resolvers;
+  }
+  baseUrl() {
+    const base = this.catalog?.baseUrl ?? "";
+    if (!base) throw new Error("this project has no base URL \u2014 set one in the project's settings first");
+    return base;
+  }
+  /** Open a browser for a new flow, signed in first if asked.
+   *
+   * A DRAFT LEFT BEHIND IS PICKED UP. Every kept step is written to disk as
+   * it is kept, so a flow interrupted — the program stopped, the limit hit,
+   * the agent restarted — is not lost: starting the same flow again replays
+   * what was kept and carries on from there, unless `fresh` says start over. */
+  async start(input, catalog, opts = {}) {
+    await this.close();
+    this.catalog = catalog;
+    this.draft = { ...input, steps: [] };
+    this.values = /* @__PURE__ */ new Map();
+    this.typed = /* @__PURE__ */ new Map();
+    this.lastTree = null;
+    this.verified = null;
+    const left = opts.fresh ? null : this.readDraft(input.projectId, input.name);
+    if (opts.fresh) this.dropDraft(input.projectId, input.name);
+    const opened = isMobile(input.platform) ? await this.startMobile(input.platform, catalog) : await this.startWeb(input, catalog);
+    this.report();
+    if (!left?.steps.length) return opened;
+    return this.resume(left.steps, opened);
+  }
+  /** The steps of an earlier attempt, performed again in the open session
+   *  and kept as they pass; the first that fails is where the person — or
+   *  the model — takes over. */
+  async resume(steps, opened) {
+    const draft = this.draft;
+    let failed = null;
+    for (const step of steps) {
+      try {
+        if (this.mobile) {
+          const done = await runMobileSteps(this.mobile, [step], this.mobileResolvers());
+          if (done.status !== "passed") throw new Error(done.results[0]?.detail ?? done.error ?? "it did not work");
+        } else {
+          const { page, run } = this.requireOpen();
+          this.page = await executeStep(page, step, {
+            pages: run.pages,
+            values: this.values,
+            baseUrl: this.baseUrl(),
+            ...this.resolvers ?? {},
+            resolveSecret: (ref) => this.typed.get(ref) ?? this.resolvers?.resolveSecret(ref),
+            timeoutMs: STEP_TIMEOUT_MS,
+            navigationTimeoutMs: 45e3
+          });
+          await this.settle();
+        }
+        draft.steps.push(step);
+        this.checkpoint();
+      } catch (error) {
+        failed = `${describe(step)} \u2014 ${error.message.split("\n")[0]}`;
+        break;
+      }
+    }
+    this.checkpoint();
+    const kept = draft.steps.length;
+    const head = failed ? `Resumed "${draft.name}": ${kept} of ${steps.length} earlier steps are back; the next one did not work this time and was dropped (${failed}). Carry on from here.` : `Resumed "${draft.name}": its ${kept} earlier step${kept === 1 ? "" : "s"} ${kept === 1 ? "is" : "are"} back. Carry on from here.`;
+    const view = this.mobile ? await this.snapshot() : opened.includes("\n") ? await this.snapshot() : opened;
+    return `${head}
+
+${view}`;
+  }
+  // ── Drafts on disk ──────────────────────────────────────────────────────
+  static draftFile(projectId, name) {
+    return path.join(flowrikiHome(), "drafts", projectId.replace(/[^A-Za-z0-9_-]/g, "_"), `${slugify(name) || "flow"}.json`);
+  }
+  /** Written after every kept step: the draft as it stands, never a typed
+   *  secret (those stay in memory until the vault has them). */
+  checkpoint() {
+    const draft = this.draft;
+    if (!draft) return;
+    this.verified = null;
+    this.report();
+    try {
+      const file = _AuthoringSession.draftFile(draft.projectId, draft.name);
+      fs.mkdirSync(path.dirname(file), { recursive: true, mode: 448 });
+      const { preparation: _p, ...rest } = draft;
+      fs.writeFileSync(file, JSON.stringify({ ...rest, steps: withoutTyped(draft.steps), savedAt: (/* @__PURE__ */ new Date()).toISOString() }), { mode: 384 });
+    } catch {
+    }
+  }
+  /** The draft as it stands, to the dashboard question this answers — at
+   *  most every half second, a recording keeps a step a second. */
+  reportTimer = null;
+  report() {
+    if (this.reportTimer) return;
+    this.reportTimer = setTimeout(() => void this.sendReport(), 500);
+    this.reportTimer.unref?.();
+  }
+  /** Whatever is waiting to be reported, now — before a save or a close, so
+   *  the dashboard ends on the flow as it was saved. */
+  async sendReport() {
+    if (this.reportTimer) {
+      clearTimeout(this.reportTimer);
+      this.reportTimer = null;
+    }
+    const draft = this.draft;
+    if (draft) {
+      const featureName = draft.featureName ?? this.catalog?.features?.find((f) => f.id === draft.featureId)?.name ?? "";
+      if (typeof this.service.reportDraft === "function") await this.service.reportDraft(draft.projectId, {
+        name: draft.name,
+        feature: featureName,
+        platform: draft.platform ?? "web",
+        after: (draft.after ?? []).map((a) => a.name),
+        signsIn: Boolean(draft.signIn),
+        steps: withoutTyped(draft.steps).map((st) => st.secret ? { ...st, value: "" } : st)
+      }).catch(() => void 0);
+    }
+    if (this.liveCase) await this.sendCaseReport();
+  }
+  // ── The test case a recording is for ────────────────────────────────
+  //
+  // A PERSON THINKS IN TEST CASES. The flows are how the assistant makes one
+  // runnable; what the person watches is the case filling in — every Given /
+  // When / Then with the steps that carry it out, as each step is kept, not
+  // after the flows are saved and the case is built. start_case names the
+  // case and its lines; each step recorded after it says which line it is
+  // for; save_case ties them on the saved case without being told again.
+  liveCase = null;
+  startCase(projectId, name, folder, lines) {
+    const same = this.liveCase && this.liveCase.projectId === projectId && nameKey(this.liveCase.name) === nameKey(name);
+    this.liveCase = same ? { ...this.liveCase, folder, lines } : { projectId, name, folder, lines, rows: [], lineOf: /* @__PURE__ */ new Map() };
+    void this.sendCaseReport();
+    return `Building the test case "${name}" in ${folder}:
+${lines.map((l, i) => `  ${i + 1}. ${l.keyword} ${l.text}`).join("\n")}
+Record the flows it needs; on every act, add_check and use_helper pass line: the number of the line that step carries out. save_case ties them on the case.`;
+  }
+  /** How many steps the flow being written has kept — before a tool runs, so
+   *  the steps it keeps can be told apart. */
+  keptCount() {
+    return this.draft?.steps.length ?? 0;
+  }
+  /** The steps kept since `before` carry out line `line` of the case. */
+  tagSince(before, line) {
+    const live = this.liveCase;
+    const draft = this.draft;
+    if (!live || !draft) return "";
+    if (!Number.isInteger(line) || line < 1 || line > live.lines.length) return ` (There is no line ${line} in "${live.name}" \u2014 it has ${live.lines.length}.)`;
+    for (const step of draft.steps.slice(before)) live.lineOf.set(step.id, line);
+    void this.sendCaseReport();
+    return "";
+  }
+  /** The case's lines, each with the flow steps that carry it out — what
+   *  save_case sends when it is not told. Null for another case. */
+  caseLinesFor(name) {
+    const live = this.liveCase;
+    if (!live || nameKey(live.name) !== nameKey(name)) return null;
+    const steps = this.caseRows().flatMap((r) => r.steps);
+    return live.lines.map((l, i) => ({
+      step: `${l.keyword} ${l.text}`,
+      flowSteps: steps.filter((st) => live.lineOf.get(st.id) === i + 1).map((st) => st.id)
+    }));
+  }
+  caseRows() {
+    const live = this.liveCase;
+    const draft = this.draft && this.draft.projectId === live.projectId ? this.draft : null;
+    const rows = live.rows.filter((r) => !draft || nameKey(r.name) !== nameKey(draft.name));
+    const current = draft ? { name: draft.name, platform: draft.platform ?? "web", steps: draft.steps } : null;
+    const at = draft ? live.rows.findIndex((r) => nameKey(r.name) === nameKey(draft.name)) : -1;
+    if (current && at >= 0) rows.splice(at, 0, current);
+    else if (current) rows.push(current);
+    return rows;
+  }
+  /** The case as it stands, to the dashboard question this answers. */
+  async sendCaseReport() {
+    const live = this.liveCase;
+    if (!live || typeof this.service.reportCase !== "function") return;
+    const rows = this.caseRows();
+    const refOf = /* @__PURE__ */ new Map();
+    const occurrences = rows.map((r) => {
+      const occurrenceId = `live_${slugify(r.name) || "flow"}`;
+      for (const st of r.steps) refOf.set(st.id, `${occurrenceId}/${st.id}`);
+      return {
+        occurrenceId,
+        name: r.name,
+        ...r.platform !== "web" ? { platform: r.platform } : {},
+        steps: withoutTyped(r.steps).map((st) => st.secret ? { ...st, value: "" } : st)
+      };
+    });
+    const businessSteps = live.lines.map((l, i) => {
+      const steps = rows.flatMap((r) => r.steps).filter((st) => live.lineOf.get(st.id) === i + 1).map((st) => refOf.get(st.id));
+      return { keyword: l.keyword, text: l.text, ...steps.length ? { steps } : {} };
+    });
+    await this.service.reportCase(live.projectId, { name: live.name, folder: live.folder, testCase: { name: live.name, occurrences, businessSteps } }).catch(() => void 0);
+  }
+  readDraft(projectId, name) {
+    try {
+      const raw = JSON.parse(fs.readFileSync(_AuthoringSession.draftFile(projectId, name), "utf8"));
+      const steps = (raw.steps ?? []).map((s) => RecordedStepSchema.parse(s));
+      return { steps };
+    } catch {
+      return null;
+    }
+  }
+  dropDraft(projectId, name) {
+    try {
+      fs.rmSync(_AuthoringSession.draftFile(projectId, name), { force: true });
+    } catch {
+    }
+  }
+  /** Close and forget the flow being written: close_browser means it. */
+  async closeAndDrop() {
+    const draft = this.draft;
+    await this.close();
+    if (draft) this.dropDraft(draft.projectId, draft.name);
+    this.draft = null;
+  }
+  async startWeb(input, catalog) {
+    void catalog;
+    const base = this.baseUrl();
+    this.run = await openRunSession({ steps: [], headless: this.opts.headless ?? false });
+    this.page = this.run.page;
+    if (input.signIn) {
+      const resolvers = await this.prepare();
+      const signIn = {
+        id: "sign-in",
+        type: "signIn",
+        auth: { ...input.signIn, from: "loginPage" },
+        role: "",
+        name: "Sign in",
+        scope: "",
+        value: "",
+        secret: false,
+        legacySelector: "",
+        proposals: []
+      };
+      this.page = await executeStep(this.page, signIn, {
+        pages: this.run.pages,
+        ...resolvers,
+        values: this.values,
+        baseUrl: base,
+        timeoutMs: 2e4,
+        navigationTimeoutMs: 45e3
+      });
+    } else {
+      await this.page.goto(new URL(input.startPath || "/", base).href, { waitUntil: "domcontentloaded", timeout: 45e3 });
+    }
+    if (input.preparation?.length) {
+      const resolvers = await this.prepare(input.preparation);
+      for (const step of input.preparation) {
+        try {
+          this.page = await executeStep(this.page, step, {
+            pages: this.run.pages,
+            ...resolvers,
+            values: this.values,
+            baseUrl: base,
+            timeoutMs: 2e4,
+            navigationTimeoutMs: 45e3
+          });
+        } catch (error) {
+          throw new Error(`The flows this one starts after did not finish, at "${step.name || step.type}": ${error.message.split("\n")[0]}`);
+        }
+      }
+      await this.settle();
+    }
+    return this.snapshot();
+  }
+  /** The page as Claude reads it: where it is, and what is on it by role and name. */
+  async snapshot() {
+    return this.view(true);
+  }
+  /** WHAT CHANGED, after a step — not the whole page again.
+   *
+   * Every step used to answer with the full tree, which on a long storefront
+   * is twenty thousand characters repeated forty times to say "the box now
+   * has text in it". So a step answers with what it is about: an open dialog
+   * (with the navigation, which says who is signed in), or the lines that
+   * appeared and disappeared — and only after a real navigation, when most of
+   * the page is new, the page itself, capped. read_page is always the whole
+   * thing. */
+  async view(full) {
+    const { tree, head } = this.mobile ? await this.mobileTree() : await this.webTree();
+    const before = this.lastTree;
+    this.lastTree = tree;
+    const cap = (t, max) => t.length > max ? `${t.slice(0, max)}
+\u2026 (cut \u2014 read_page shows the whole page)` : t;
+    if (full || before === null) return head + cap(tree, MAX_TREE);
+    const { dialogs, navigation } = topLevelBlocks(tree);
+    if (dialogs.length) {
+      return head + cap([...navigation ? [navigation] : [], ...dialogs].join("\n"), MAX_STEP_VIEW) + "\n(only the open dialog and the navigation \u2014 read_page shows the whole page)";
+    }
+    const was = new Set(before.split("\n"));
+    const now = new Set(tree.split("\n"));
+    const added = tree.split("\n").filter((l) => !was.has(l));
+    const removed = before.split("\n").filter((l) => !now.has(l));
+    if (added.length === 0 && removed.length === 0) return head + "(the page did not change \u2014 read_page shows it)";
+    if (added.length + removed.length > 120) return head + cap(tree, MAX_STEP_VIEW);
+    return head + [
+      ...navigation ? [navigation, ""] : [],
+      added.length ? `Appeared:
+${added.join("\n")}` : "",
+      removed.length ? `Gone:
+${removed.join("\n")}` : "",
+      "(changes since the last step \u2014 read_page shows the whole page)"
+    ].filter(Boolean).join("\n");
+  }
+  async webTree() {
+    const { page, draft } = this.requireOpen();
+    await page.waitForLoadState("domcontentloaded", { timeout: 1e4 }).catch(() => void 0);
+    const tree = numberDuplicates(labelTree(
+      await page.locator("body").ariaSnapshot({ timeout: 8e3 }).catch((e) => `(could not read the page: ${e.message})`),
+      await fieldNames(page)
+    ));
+    const title = await page.title().catch(() => "");
+    return { tree, head: `Page: ${page.url()}${title ? ` \u2014 "${title}"` : ""}
+Steps so far: ${draft.steps.length}
+
+` };
+  }
+  /** Do one thing on the page, and keep it as a step if it worked. */
+  async act(input) {
+    if (this.mobile) return this.mobileAct(input);
+    const refused = stepRefusedOn(input.action === "tap" ? "click" : input.action, "web");
+    if (refused) throw new Error(refused);
+    const { page, draft, run } = this.requireOpen();
+    const navigating = input.action === "navigate" || input.action === "back" || input.action === "forward";
+    if (!navigating && input.action !== "press" && !(input.role && input.name)) {
+      throw new Error(`${input.action} needs the element's role and name, exactly as read_page shows them`);
+    }
+    if ((input.action === "fill" || input.action === "select" || input.action === "press" || input.action === "navigate") && input.value === void 0) {
+      throw new Error(`${input.action} needs a value`);
+    }
+    const target = navigating ? { role: "", name: "" } : asLabelled({ role: input.role ?? "", name: input.name ?? "" }, await fieldNames(page));
+    const secret = input.action === "fill" && (input.secret ?? (SECRET_WORDS.test(input.name ?? "") || SECRET_WORDS.test(target.name)));
+    const id = `s${draft.steps.length + 1}_${Date.now().toString(36)}`;
+    if (secret) this.typed.set(`${TYPED}${id}`, input.value ?? "");
+    const step = RecordedStepSchema.parse({
+      id,
+      type: input.action,
+      ...target,
+      ...scopeOf(input.within),
+      ...input.nth !== void 0 ? { nth: input.nth } : {},
+      value: secret ? "" : input.action === "check" ? input.value === "false" ? "false" : "true" : input.value ?? "",
+      secret,
+      ...secret ? { secretRef: `${TYPED}${id}` } : {},
+      legacySelector: "",
+      proposals: [],
+      // A path is the application's own, so the step replays on whichever
+      // environment the run is pointed at rather than the one written on.
+      ...input.action === "navigate" && input.value?.startsWith("/") ? { navigationBase: "application" } : {}
+    });
+    try {
+      this.page = await executeStep(page, step, {
+        pages: run.pages,
+        values: this.values,
+        baseUrl: this.baseUrl(),
+        ...this.resolvers ?? {},
+        resolveSecret: (ref) => this.typed.get(ref) ?? this.resolvers?.resolveSecret(ref),
+        timeoutMs: STEP_TIMEOUT_MS,
+        navigationTimeoutMs: 45e3
+      });
+    } catch (error) {
+      if (secret) this.typed.delete(`${TYPED}${id}`);
+      const said = error.message.split("\n")[0] ?? "";
+      const several = /strict mode violation|resolved to \d+ elements|\d+ elements match/i.test(said) ? "\nSeveral elements share this role and name. Pass nth (0 = the first, in the order read_page lists them \u2014 each shared name is marked [nth N of M]) to say which one." : "";
+      throw new Error(`That did not work, and was not kept: ${said}${several}
+
+${await this.view(false)}`);
+    }
+    await this.settle();
+    draft.steps.push(step);
+    this.checkpoint();
+    return `Step ${draft.steps.length} kept: ${describe(step)}.
+
+${await this.view(false)}`;
+  }
+  /** Check something about the page now, and keep the check if it holds. */
+  async check(input) {
+    if (this.mobile) return this.mobileCheck(input);
+    const { page, draft } = this.requireOpen();
+    if ((input.kind === "heading" || input.kind === "message" || input.kind === "screen") && input.op && input.op !== "equals" && !input.role) {
+      throw new Error(`a ${input.kind} check without role and name matches the whole ${input.kind} \u2014 give its full text with op equals, or name the element (role + name) and use kind "text" with op ${input.op}`);
+    }
+    const assertion = RecordedStepSchema.shape.proposals.element.parse({
+      kind: input.kind,
+      value: input.value,
+      enabled: true,
+      ...input.op && input.op !== "equals" ? { op: input.op } : {},
+      ...input.role ? { target: { ...asLabelled({ role: input.role, name: input.name ?? "" }, await fieldNames(page)), ...scopeOf(input.within), ...input.nth !== void 0 ? { nth: input.nth } : {} } } : {}
+    });
+    const filled = (text2) => text2.replace(/\{\{([a-zA-Z][a-zA-Z0-9_]*)\}\}/g, (_, name) => runtimeValue(this.values, name));
+    const expected = Array.isArray(assertion.value) ? assertion.value.map(filled) : filled(assertion.value);
+    try {
+      await checkAssertion(page, assertion.kind, expected, 5e3, { ...assertion, value: expected });
+    } catch (error) {
+      throw new Error(`That is not true of the page right now, so it was not kept: ${error.message.split("\n")[0]}`);
+    }
+    const step = RecordedStepSchema.parse(mirrorCheckTargets([{
+      id: `c${draft.steps.length + 1}_${Date.now().toString(36)}`,
+      type: "assert",
+      role: "",
+      name: "",
+      scope: "",
+      value: "",
+      secret: false,
+      legacySelector: "",
+      proposals: [assertion]
+    }])[0]);
+    draft.steps.push(step);
+    this.checkpoint();
+    return `Step ${draft.steps.length} kept: ${describe(step)}.`;
+  }
+  /** Get a value from outside the page — an email code, a 2FA code, a text,
+   *  an API reply — and keep the step that gets it. */
+  async useHelper(input) {
+    if (this.mobile) return this.mobileHelper(input);
+    const { page, draft, run } = this.requireOpen();
+    const helper = this.catalog?.helpers.find((h) => h.id === input.helperId || h.name.toLowerCase() === input.helperId.toLowerCase());
+    if (!helper) throw new Error(`no helper "${input.helperId}" \u2014 project_catalog lists them; one can be made on the Helpers screen`);
+    const missing = helper.inputs.filter((name) => !(input.inputs ?? {})[name]);
+    if (missing.length) throw new Error(`${helper.name} needs ${missing.map((n) => `{{${n}}}`).join(", ")} in inputs`);
+    const step = RecordedStepSchema.parse({
+      id: `h${draft.steps.length + 1}_${Date.now().toString(36)}`,
+      type: "useHelper",
+      role: "",
+      name: helper.name,
+      scope: "",
+      value: "",
+      secret: false,
+      legacySelector: "",
+      proposals: [],
+      helper: { helperId: helper.id, inputs: input.inputs ?? {}, saveAs: input.saveAs || (helper.kind === "mailbox" ? "code" : "value"), then: input.then ?? "remember" }
+    });
+    const resolvers = await this.prepare([step]);
+    let got = { value: "", detail: "" };
+    try {
+      this.page = await executeStep(page, step, {
+        pages: run.pages,
+        values: this.values,
+        baseUrl: this.baseUrl(),
+        ...resolvers,
+        timeoutMs: STEP_TIMEOUT_MS,
+        navigationTimeoutMs: 45e3,
+        onHelper: (answer) => {
+          got = answer;
+        }
+      });
+    } catch (error) {
+      throw new Error(`The helper did not get a value, and the step was not kept: ${error.message}`);
+    }
+    await this.settle();
+    draft.steps.push(step);
+    this.checkpoint();
+    return `Step ${draft.steps.length} kept: ${describe(step)}. It got "${got.value}" (${got.detail}). Use {{${step.helper.saveAs}}} as the value of a later step.` + (step.helper.then === "open" ? `
+
+${await this.view(false)}` : "");
+  }
+  list() {
+    const draft = this.draft;
+    if (!draft) return "No flow is being written.";
+    const head = `"${draft.name}"${draft.signIn ? ", signed in first" : ""}, starting at ${draft.startPath}`;
+    if (draft.steps.length === 0) return `${head}. No steps yet.`;
+    return `${head}:
+${draft.steps.map((s, i) => `${i + 1}. ${describe(s)}`).join("\n")}`;
+  }
+  /** Drop a step from the draft. The browser is not wound back — replay to
+   *  see the flow as it now stands. */
+  remove(number) {
+    const draft = this.draft;
+    if (!draft || !this.open) throw new Error("no flow is being written \u2014 call start_flow first");
+    if (!Number.isInteger(number) || number < 1 || number > draft.steps.length) throw new Error(`there is no step ${number}`);
+    const [gone] = draft.steps.splice(number - 1, 1);
+    this.checkpoint();
+    return `Removed step ${number} (${describe(gone)}). The browser was not undone \u2014 replay_flow shows the flow as it now stands.
+
+${this.list()}`;
+  }
+  /** Run the whole draft from the start, in a browser of its own, the way a
+   *  run will — the proof the steps work together, not just one at a time. */
+  async replay() {
+    if (this.mobile) return this.mobileReplay();
+    const { draft } = this.requireOpen();
+    if (draft.steps.length === 0) throw new Error("there are no steps to replay yet");
+    const resolvers = await this.prepare();
+    const steps = [
+      ...draft.signIn ? [RecordedStepSchema.parse({ id: "sign-in", type: "signIn", auth: { ...draft.signIn, from: "loginPage" }, role: "", name: "Sign in", scope: "", value: "", secret: false, legacySelector: "", proposals: [] })] : [],
+      ...draft.preparation ?? [],
+      ...draft.steps
+    ];
+    const outcome = await replayFlow({ steps, baseUrl: this.baseUrl(), startPath: draft.startPath, headless: true, ...resolvers });
+    const lines = outcome.steps.map((s) => `${s.status === "passed" ? "\u2713" : s.status === "failed" ? "\u2717" : "\xB7"} ${s.name || s.type}${s.status === "failed" && s.detail ? ` \u2014 ${s.detail}` : ""}`);
+    if (outcome.status === "passed") this.verified = signatureOf(draft.steps);
+    return `${outcome.status === "passed" ? "The whole flow passed from the start." : `The flow ${outcome.status}${outcome.error ? `: ${outcome.error}` : ""}.`}
+${lines.join("\n")}`;
+  }
+  /** Save the draft as a flow on a new branch, for a person to review.
+   *
+   * REPLAYED FIRST. A flow that was only ever performed step by step, with
+   * pauses to look, has not been shown to run as a test runs it; so unless
+   * the same steps already passed a replay, they are replayed from the
+   * start now, and a flow that fails is not saved — the failing step is
+   * named instead. `force` saves anyway, for a person who knows. */
+  async save(title, where = {}, opts = {}) {
+    const draft = this.draft;
+    if (!draft || !this.open) throw new Error("no flow is being written \u2014 call start_flow first");
+    if (draft.steps.length === 0) throw new Error("there are no steps to save yet");
+    if (!draft.steps.some((s) => s.type === "assert" || s.proposals.length > 0)) {
+      throw new Error("the flow checks nothing \u2014 add at least one check (add_check) that proves it worked, then save");
+    }
+    let replayed = "";
+    if (!opts.force && this.verified !== signatureOf(draft.steps)) {
+      const report = await this.replay();
+      if (!/^The whole flow passed/.test(report)) {
+        throw new Error(`Not saved: replayed from the start, the flow did not pass.
+${report}
+Fix the step that failed (remove_step, then act again) and save again \u2014 or save_flow with force: true to keep it as it is.`);
+      }
+      replayed = " It was replayed from the start first and passed.";
+    }
+    const checksOff = draft.steps.map((step) => step.type === "assert" ? { ...step, proposals: step.proposals.map((p) => ({ ...p, enabled: false })) } : step);
+    if (this.reportTimer) await this.sendReport();
+    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,
+      ...isMobile(draft.platform) ? { platform: draft.platform } : {},
+      steps: withoutTyped(checksOff),
+      ...draft.signIn ? { signIn: draft.signIn } : {},
+      ...draft.after?.length ? { prerequisites: draft.after.map((a) => ({ flowId: a.flowId })) } : {}
+    }, where, secretValues);
+    const review = `${this.service.origin}/projects/${draft.projectId}/changes/${saved.changeId}`;
+    const what = saved.replaced ? `Replaced the earlier "${draft.name}"` : `Saved "${draft.name}"`;
+    const sealed = Object.keys(secretValues).length;
+    const vault = sealed ? ` ${sealed} secret value${sealed === 1 ? " was" : "s were"} put in the project's vault, not the flow.` : "";
+    const where_ = saved.newBranch ? `on a new branch, ${saved.branch}` : `on Claude's working branch, ${saved.branch}`;
+    const others = await this.service.agentChanges(draft.projectId).then((r) => r.changes.filter((c) => c.id !== saved.changeId)).catch(() => []);
+    const note = others.length ? `
+Claude has ${others.length} other open branch${others.length === 1 ? "" : "es"} on this project \u2014 gather_branches puts them into this one, for one review.` : "";
+    const after = draft.after?.length ? ` It starts after ${draft.after.map((a) => `"${a.name}"`).join(", ")}.` : "";
+    this.dropDraft(draft.projectId, draft.name);
+    const live = this.liveCase;
+    if (live && live.projectId === draft.projectId) {
+      const row = { name: draft.name, platform: draft.platform ?? "web", steps: [...draft.steps] };
+      const at = live.rows.findIndex((r) => nameKey(r.name) === nameKey(draft.name));
+      if (at >= 0) live.rows[at] = row;
+      else live.rows.push(row);
+    }
+    return `${what} ${where_}.${replayed}${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.
+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, built.testCase)}`;
+  }
+  /** 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;
+    const phoneRows = testCase.occurrences.filter((o) => isMobile(o.platform));
+    if (!base && phoneRows.length < testCase.occurrences.length) throw new Error("this project has no base URL \u2014 set one in the project's settings first");
+    const laneOptions = {
+      mobile: catalog.mobile ?? mobileOf(null),
+      resolveSecret: (ref) => prepared.secrets[ref],
+      resolveAuth: authenticationResolver(prepared.authentications),
+      ...runHelper ? { runHelper } : {}
+    };
+    const lane = phoneRows.length ? new MobileLane(laneOptions) : null;
+    const opened = /* @__PURE__ */ new Set();
+    const outcome = phoneRows.length === testCase.occurrences.length ? await replayMobileCase({ ...laneOptions, occurrences: testCase.occurrences, ...testCase.defaultActorId ? { defaultActorId: testCase.defaultActorId } : {} }) : await replayCase({
+      ...lane ? {
+        runElsewhere: (occurrence, ctx) => {
+          if (!isMobile(occurrence.platform)) return null;
+          const key = occurrence.actorId ?? testCase.defaultActorId ?? "default";
+          const first = !opened.has(key);
+          opened.add(key);
+          return lane.run(occurrence, { deviceKey: key, first, ...ctx });
+        }
+      } : {},
+      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 } : {}
+    }).finally(() => lane?.close());
+    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, testCase)}`;
+    }
+    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() {
+    if (this.reportTimer) await this.sendReport();
+    const run = this.run;
+    const mobile = this.mobile;
+    this.run = null;
+    this.page = null;
+    this.mobile = null;
+    this.resolvers = null;
+    if (mobile) await mobile.close().catch(() => void 0);
+    if (run) await closeRunSession(run, { passed: true }).catch(() => void 0);
+  }
+  // ── On a phone ────────────────────────────────────────────────────────
+  /** Open the project's app on the chosen phone, signed in and brought to
+   *  where the flow starts, as on the web. */
+  async startMobile(platform, catalog) {
+    const draft = this.draft;
+    const mobile = catalog.mobile;
+    if (!mobile) throw new Error("this project has no phone apps set up \u2014 turn on Android or iOS in Settings \u2192 Platforms");
+    const resolvers = draft.signIn || draft.device?.kind === "cloud" ? await this.prepare() : null;
+    this.mobile = await openMobileSession({
+      platform,
+      mobile,
+      ...catalog.runWhere ? { where: catalog.runWhere[platform] } : {},
+      ...draft.device ? { device: draft.device } : {},
+      ...resolvers ? { resolveSecret: resolvers.resolveSecret } : {}
+    });
+    const opening = [
+      ...draft.signIn ? [RecordedStepSchema.parse({ id: "sign-in", type: "signIn", auth: draft.signIn, role: "", name: "Sign in", scope: "", value: "", secret: false, legacySelector: "", proposals: [] })] : [],
+      ...draft.preparation ?? []
+    ];
+    if (/^[a-z][\w+.-]*:\/\//i.test(draft.startPath)) await this.mobile.openLink(draft.startPath);
+    if (opening.length) {
+      const ready = await this.prepare(draft.preparation ?? []);
+      const done = await runMobileSteps(this.mobile, opening, { values: this.values, ...ready });
+      if (done.status !== "passed") throw new Error(`The app could not be brought to where this flow starts: ${done.error}`);
+    }
+    return this.snapshot();
+  }
+  async mobileTree() {
+    const { mobile, draft } = this.requireMobile();
+    mobile.changed();
+    let screen = await mobile.screen();
+    if (screen.nodes.length === 0) screen = await mobile.settle(8e3);
+    const where = await mobile.currentScreenName();
+    const tree = numberDuplicates(screenLines(screen)) || "(nothing on the screen can be read \u2014 the app may still be loading, or draws without accessibility labels)";
+    return { tree, head: `Screen: ${screen.app || mobile.appId} on ${mobile.deviceName}${where ? ` \u2014 ${where}` : ""}
+Steps so far: ${draft.steps.length}
+
+` };
+  }
+  mobileResolvers() {
+    return {
+      values: this.values,
+      ...this.resolvers ?? {},
+      resolveSecret: (ref) => this.typed.get(ref) ?? this.resolvers?.resolveSecret(ref)
+    };
+  }
+  async mobileAct(input) {
+    const { mobile, draft } = this.requireMobile();
+    const type = input.action === "tap" ? "click" : input.action;
+    const refused = stepRefusedOn(type, mobile.platform);
+    if (refused) throw new Error(refused);
+    const needsElement = ["click", "longPress", "fill", "select", "check"].includes(type);
+    if (needsElement && !(input.role && (input.name || input.nth !== void 0))) {
+      throw new Error(`${input.action} needs the element's role and name, exactly as read_page shows them`);
+    }
+    if ((type === "fill" || type === "select" || type === "navigate") && input.value === void 0) throw new Error(`${input.action} needs a value`);
+    let target = { role: "", name: "" };
+    let password = false;
+    if (input.role) {
+      const asked = { role: input.role, name: input.name ?? "", ...scopeOf(input.within), ...input.nth !== void 0 ? { nth: input.nth } : {} };
+      try {
+        const found = await locate(mobile, asked, STEP_TIMEOUT_MS, { scroll: type !== "swipe" });
+        target = { ...targetFor(found.screen, found.node), ...asked };
+        password = found.node.password;
+      } catch (error) {
+        const said = error.message.split("\n")[0] ?? "";
+        const several = /elements match/.test(said) ? "\nSeveral elements share this role and name. Pass nth (0 = the first, in the order read_page lists them) to say which one." : "";
+        throw new Error(`That did not work, and was not kept: ${said}${several}
+
+${await this.view(false)}`);
+      }
+    }
+    const secret = type === "fill" && (input.secret ?? (password || SECRET_WORDS.test(input.name ?? "")));
+    const id = `s${draft.steps.length + 1}_${Date.now().toString(36)}`;
+    if (secret) this.typed.set(`${TYPED}${id}`, input.value ?? "");
+    const value = secret ? "" : type === "check" ? input.value === "false" ? "false" : "true" : type === "swipe" || type === "scroll" && !input.role ? (input.value || "up").toLowerCase() : input.value ?? "";
+    const step = RecordedStepSchema.parse({
+      id,
+      type,
+      ...target,
+      value,
+      secret,
+      ...secret ? { secretRef: `${TYPED}${id}` } : {},
+      legacySelector: "",
+      proposals: []
+    });
+    try {
+      await performMobileStep(mobile, step, this.mobileResolvers());
+    } 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]}
+
+${await this.view(false)}`);
+    }
+    await new Promise((r) => setTimeout(r, 600));
+    draft.steps.push(step);
+    this.checkpoint();
+    return `Step ${draft.steps.length} kept: ${describe(step)}.
+
+${await this.view(false)}`;
+  }
+  async mobileCheck(input) {
+    const { mobile, draft } = this.requireMobile();
+    if (input.kind === "url" || input.kind === "title") throw new Error(`a phone app has no ${input.kind === "url" ? "address" : "page title"} \u2014 check text on the screen (message), a heading's text, or an element`);
+    const assertion = RecordedStepSchema.shape.proposals.element.parse({
+      kind: input.kind,
+      value: input.value,
+      enabled: true,
+      ...input.op && input.op !== "equals" ? { op: input.op } : {},
+      ...input.role ? { target: { role: input.role, name: input.name ?? "", ...scopeOf(input.within), ...input.nth !== void 0 ? { nth: input.nth } : {} } } : {}
+    });
+    const filled = (text2) => text2.replace(/\{\{([a-zA-Z][a-zA-Z0-9_]*)\}\}/g, (_, name) => runtimeValue(this.values, name));
+    const expected = Array.isArray(assertion.value) ? assertion.value.map(filled) : filled(assertion.value);
+    try {
+      await checkMobileAssertion(mobile, { ...assertion, value: expected }, 5e3);
+    } catch (error) {
+      throw new Error(`That is not true of the screen right now, so it was not kept: ${error.message.split("\n")[0]}`);
+    }
+    const step = RecordedStepSchema.parse(mirrorCheckTargets([{
+      id: `c${draft.steps.length + 1}_${Date.now().toString(36)}`,
+      type: "assert",
+      role: "",
+      name: "",
+      scope: "",
+      value: "",
+      secret: false,
+      legacySelector: "",
+      proposals: [assertion]
+    }])[0]);
+    draft.steps.push(step);
+    this.checkpoint();
+    return `Step ${draft.steps.length} kept: ${describe(step)}.`;
+  }
+  async mobileHelper(input) {
+    const { mobile, draft } = this.requireMobile();
+    const helper = this.catalog?.helpers.find((h) => h.id === input.helperId || h.name.toLowerCase() === input.helperId.toLowerCase());
+    if (!helper) throw new Error(`no helper "${input.helperId}" \u2014 project_catalog lists them; one can be made on the Helpers screen`);
+    const missing = helper.inputs.filter((name) => !(input.inputs ?? {})[name]);
+    if (missing.length) throw new Error(`${helper.name} needs ${missing.map((n) => `{{${n}}}`).join(", ")} in inputs`);
+    const step = RecordedStepSchema.parse({
+      id: `h${draft.steps.length + 1}_${Date.now().toString(36)}`,
+      type: "useHelper",
+      role: "",
+      name: helper.name,
+      scope: "",
+      value: "",
+      secret: false,
+      legacySelector: "",
+      proposals: [],
+      helper: { helperId: helper.id, inputs: input.inputs ?? {}, saveAs: input.saveAs || (helper.kind === "mailbox" ? "code" : "value"), then: input.then ?? "remember" }
+    });
+    await this.prepare([step]);
+    let got;
+    try {
+      got = await performMobileStep(mobile, step, this.mobileResolvers());
+    } catch (error) {
+      throw new Error(`The helper did not get a value, and the step was not kept: ${error.message}`);
+    }
+    draft.steps.push(step);
+    this.checkpoint();
+    return `Step ${draft.steps.length} kept: ${describe(step)}. It got "${got?.value ?? ""}" (${got?.detail ?? ""}). Use {{${step.helper.saveAs}}} as the value of a later step.` + (step.helper.then === "open" ? `
+
+${await this.view(false)}` : "");
+  }
+  /** The whole flow again from the app's start, on the same phone — a phone
+   *  holds one session at a time, so the app is closed and opened rather than
+   *  a second device started. */
+  async mobileReplay() {
+    const { mobile, draft } = this.requireMobile();
+    if (draft.steps.length === 0) throw new Error("there are no steps to replay yet");
+    const resolvers = await this.prepare();
+    const steps = [
+      ...draft.signIn ? [RecordedStepSchema.parse({ id: "sign-in", type: "signIn", auth: draft.signIn, role: "", name: "Sign in", scope: "", value: "", secret: false, legacySelector: "", proposals: [] })] : [],
+      ...draft.preparation ?? [],
+      ...draft.steps
+    ];
+    await mobile.terminateApp().catch(() => void 0);
+    await mobile.launchApp();
+    await mobile.settle();
+    if (/^[a-z][\w+.-]*:\/\//i.test(draft.startPath)) await mobile.openLink(draft.startPath);
+    const outcome = await runMobileSteps(mobile, steps, { values: /* @__PURE__ */ new Map(), ...resolvers, resolveSecret: (ref) => this.typed.get(ref) ?? resolvers.resolveSecret(ref) });
+    this.lastTree = null;
+    if (outcome.status === "passed") this.verified = signatureOf(draft.steps);
+    const lines = outcome.results.map((s) => `${s.status === "passed" ? "\u2713" : s.status === "failed" ? "\u2717" : "\xB7"} ${s.name || s.type}${s.status === "failed" && s.detail ? ` \u2014 ${s.detail}` : ""}`);
+    return `${outcome.status === "passed" ? "The whole flow passed from the app's start." : `The flow ${outcome.status}${outcome.error ? `: ${outcome.error}` : ""}.`}
+${lines.join("\n")}`;
+  }
+  /** Let a click's consequences land before the page is read again. */
+  async settle() {
+    const page = this.page;
+    if (!page) return;
+    await page.waitForLoadState("domcontentloaded", { timeout: 1e4 }).catch(() => void 0);
+    await page.waitForTimeout(300);
+  }
+};
+function signatureOf(steps) {
+  return JSON.stringify(steps.map((s) => [s.id, s.type, s.role, s.name, s.value, s.nth ?? null, s.proposals.map((p) => [p.kind, p.value, p.enabled])]));
+}
+
+// src/mcp/tools.ts
+var INSTRUCTIONS = `Flowriki tools write UI tests by driving a real browser on this computer.
+Every step you take is performed first and kept only if it worked, so what you
+save already ran once. Everything goes to ONE working branch per project that a
+person reviews and publishes in the Flowriki dashboard \u2014 nothing you do is
+published.
+
+A new project \u2014 "set up Flowriki for this site, in this repository" \u2014 is made
+with create_project; it then becomes the project the other tools work on.
+
+THE MODEL \u2014 get this right before recording anything:
+- A FLOW is a reusable building block: one piece of a journey ("Open the account
+  dialog", "Fill the sign-up form", "Sign in with a wrong password"). A flow can
+  START AFTER other flows (start_flow's "after"), so it holds only its own new
+  steps and links to the ones before it. A path that behaves differently \u2014 a
+  wrong password, a duplicate email \u2014 is its own flow, because the page does
+  something different.
+- A flow records checks (add_check) that prove each thing happened, but they
+  are SAVED SWITCHED OFF: which ones matter depends on the test.
+- Every kept step is written down as it is kept: if you are stopped, start_flow
+  with the same name picks the flow up where it was (fresh: true starts over).
+  save_flow replays the flow from the start first and refuses one that fails.
+- A TEST CASE 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.
+- A test case can be WRITTEN BEFORE IT IS AUTOMATED: business steps (Given /
+  When / Then) and no flows \u2014 imported from a spreadsheet, or written with
+  write_test_cases. To automate one, record the flows its steps need, then
+  save_case with the SAME name in the SAME folder: that fills it, and its
+  business steps stay. Its Then lines are the checks to switch on.
+- 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.
+
+KNOWLEDGE: project_brief is the project's memory \u2014 read it first. Search the
+knowledge pages with knowledge_search; read one with knowledge_read.
+product.md is "About the product": the person's own description of
+the product, in their words, as long as they like \u2014 read it first. Beside it,
+product/web.md, product/android.md and product/ios.md hold what is particular
+to that platform's app, when the project tests more than one. They
+write them, often with you in a conversation beside it; propose text there and
+let them decide, rather than writing product pages unless they ask you to.
+A linked codebase folder is learned into
+codebase/<folder>.md, which must start "# <folder>", then "Commit: <full sha>"
+and "Learned: <yyyy-mm-dd>" lines: that is how the Knowledge screen shows it
+as learned. codebase.json says which platform's code each folder holds (Web,
+Android, iOS, Mobile, All combined, Other): read the web folder's page for a
+website test and the phone folder's for an app test. explore/<platform>.md is
+what the assistant saw WALKING that platform \u2014 screens, the words on them,
+journeys, rules it saw refused, vocabulary: read it before writing a test for
+that platform, because it says what a person sees; the code does not. Keep what you learn with write_knowledge (features/<name>.md,
+memory/decisions.md, a session summary), on Claude's branch for review \u2014
+never a password, key or token.
+
+UPDATING TEST CASES: when asked to update test cases (upd_\u2026), read the
+request with read_update_request, then propose_case_updates with each changed
+case's complete new steps \u2014 keep what the change does not touch word for
+word, so the person sees exactly what moved. Leave out cases that need no
+change. You never change a test case yourself; the person accepts.
+
+CONVERTING A SPREADSHEET: when asked to convert an import (imp_\u2026), read
+every part with read_import_file, then save_import_cases in batches. Group
+cases into features by product area (a sheet or section usually is one). Each
+case is one scenario: name it after what it proves. Steps: preconditions and
+setup as Given; ONE action per When / And \u2014 split steps that do several
+things; each expected result as Then / And, after the action it follows.
+Keep every case and every step's meaning, and its id from the file in row \u2014
+that id is how a later import of the same file knows the case is already
+there; never invent a step or drop one. A case found in several sheets is
+converted once. Use the project's existing feature names (project_catalog)
+when a case belongs in one, rather than a new look-alike. Rows that are not test cases (titles,
+notes, empty) are left out. Say in note what you could not convert.
+
+PHONE APPS (Android, iOS): a project can test its Android and iOS apps as well
+as, or instead of, a website \u2014 project_catalog says which, names the app, and
+lists the phones connected to this computer. start_flow with platform
+"android" or "ios" opens the app on a phone (device: a name from the catalog,
+"BrowserStack: Samsung Galaxy S23", or nothing for whatever is connected).
+read_page then reads the SCREEN as roles and names, just like a page, and act
+and add_check work the same way. On a phone: tap (= click) a button, fill a
+textbox, swipe up/down/left/right (value; on an element, or the screen), scroll
+to an element (role + name) or by direction, longPress, back (Android only),
+hideKeyboard, permission (value "allow" or "deny") for a system prompt, and
+launchApp / terminateApp / resetApp / background (value: seconds) / rotate
+(value: portrait or landscape). navigate opens a deep link. Never tap by
+position \u2014 use the role and name; [id=\u2026] on a line is the app's own id for it,
+and is used automatically. A phone app has no URL or page title: check a
+message (text on the screen), an element's text, or that something is visible.
+The app keeps its data between runs unless the project says otherwise, so a
+sign-in step is skipped when the app is already signed in. A test case can
+mix rows on a phone with rows in a browser (a customer orders in the app, an
+admin approves on the website).
+
+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
+   checks). Then record the blocks, earliest first.
+3. Record with start_flow (pass "after" for the flows it continues from), read
+   the page with read_page, and act using the role and name EXACTLY as the page
+   shows them. If a name appears more than once, pass "within" with the name of
+   the region, dialog or form \u2014 or "dialog" / "navigation".
+4. For things outside the page \u2014 an emailed code or link, an authenticator
+   code, a text message, an API call \u2014 use use_helper with a helper from the
+   catalog, then type {{its saveAs name}} into the field that needs it.
+5. Add checks for what each step proves (a heading, a message, a value, the
+   URL). replay_flow, then save_flow. A flow must record at least one check.
+6. THE PERSON THINKS IN TEST CASES; flows are how you make one runnable.
+   Before recording, start_case with the case's name, folder and Given /
+   When / Then lines (its own, from read_test_cases, when it has them). Then
+   on EVERY act, add_check and use_helper pass line: the number of the line
+   that step carries out \u2014 the person watches each line fill with its steps.
+   preview_case lists the case's rows and every step, numbered; save_case
+   with the checks to switch on runs the whole case, saves it only if it
+   passed, and ties each line to its steps. Give the person the review link.
+7. Saving the same name again replaces it on the working branch. ONE VERSION
+   of each scenario per platform: redo a flow or case under its existing name
+   (project_catalog lists them) rather than saving another beside it. A test's
+   PLATFORM IS ITS LABEL, not words in its name: name flows and cases for what
+   they do ("Sign up with valid credentials"), give start_flow its platform
+   and preview_case / save_case theirs \u2014 the same name on two platforms is
+   two tests, told apart by the label. 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 test case: 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
+      }
+    },
+    businessSteps: {
+      type: "array",
+      description: 'The case in Given / When / Then lines, in order, each with the step numbers from preview_case that carry it out \u2014 e.g. {"step": "Given the user is on the sign-in page", "steps": [1, 2]}. A case that already has business steps keeps its own words: give the same lines.',
+      items: {
+        type: "object",
+        properties: {
+          step: { type: "string", description: "One line, starting Given, When, Then, And or But." },
+          steps: { type: "array", items: { type: "number" }, description: "The step numbers (across the case) that carry it out." }
+        },
+        required: ["step"],
+        additionalProperties: false
+      }
+    },
+    platform: { type: "string", enum: ["web", "android", "ios"], description: "The platform this case is for, when the project tests several: its rows are that platform's flows. Its label \u2014 not words in its name." },
+    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"] : [],
+  ...Array.isArray(args["businessSteps"]) ? { businessSteps: args["businessSteps"] } : {},
+  ...args["branch"] ? { changeId: String(args["branch"]) } : {},
+  ...args["platform"] === "web" || args["platform"] === "android" || args["platform"] === "ios" ? { platform: args["platform"] } : {}
+});
+var text = (value, isError = false) => ({ content: [{ type: "text", text: value }], ...isError ? { isError } : {} });
+var str = (value) => typeof value === "string" ? value : value === void 0 || value === null ? void 0 : String(value);
+function authoringTools(service, session) {
+  let defaultProject = null;
+  const catalogs = /* @__PURE__ */ new Map();
+  const projectFor = async (asked) => {
+    const named = str(asked);
+    if (named) return defaultProject = named;
+    if (session.draft) return session.draft.projectId;
+    if (defaultProject) return defaultProject;
+    const { projects } = await service.projects();
+    if (projects.length === 1) return defaultProject = projects[0].id;
+    if (projects.length === 0) throw new Error("this account is not on any Flowriki project yet \u2014 create one in the dashboard");
+    throw new Error(`which project? Pass projectId \u2014 one of: ${projects.map((p) => `${p.name} (${p.id})`).join(", ")}`);
+  };
+  const catalogOf = async (projectId, fresh = false) => {
+    if (!fresh && catalogs.has(projectId)) return catalogs.get(projectId);
+    const catalog = await service.catalog(projectId);
+    catalogs.set(projectId, catalog);
+    return catalog;
+  };
+  const tagged = async (args, run) => {
+    const before = session.keptCount();
+    const out = await run();
+    const line = Number(args["line"]);
+    return text(Number.isInteger(line) && line > 0 ? out + session.tagSince(before, line) : out);
+  };
+  const withLines = (spec) => {
+    if (spec.businessSteps?.length) return spec;
+    const lines = session.caseLinesFor(spec.name);
+    return lines ? { ...spec, businessSteps: lines } : spec;
+  };
+  const tools = [
+    {
+      name: "list_projects",
+      title: "List Flowriki projects",
+      description: "The Flowriki projects you can write tests for, with your role on each. Only needed when you are on more than one.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async () => {
+        const { projects } = await service.projects();
+        return text(projects.length ? projects.map((p) => `${p.name} \u2014 id ${p.id}, you are ${p.role}`).join("\n") : "You are not on any project yet.");
+      }
+    },
+    {
+      name: "create_project",
+      title: "Create a Flowriki project",
+      description: "Create a new Flowriki project, connected to a git repository where its tests will be stored, and pointed at the app to test. The repository must already exist and must not hold another Flowriki project. You become its owner.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: `The project's name, e.g. "Pizza Romano".` },
+          repository: { type: "string", description: "owner/name, or the repository's address, e.g. https://github.com/acme/shop-tests.git" },
+          baseUrl: { type: "string", description: "The app's address, e.g. https://shop.example.com/" }
+        },
+        required: ["name", "repository"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const made = await service.createProject(str(args["name"]) ?? "", str(args["repository"]) ?? "", str(args["baseUrl"]));
+        defaultProject = made.id;
+        catalogs.delete(made.id);
+        return text(`Created "${made.name}" (id ${made.id}), stored in ${made.repository}${made.baseUrl ? `, testing ${made.baseUrl}` : " \u2014 no base URL yet; set one in its settings"}.${made.note ? `
+Note: ${made.note}` : ""}
+It is now the project these tools work on. Open it: ${service.origin}/projects/${made.id}`);
+      }
+    },
+    {
+      name: "project_catalog",
+      title: "What a test can be built from",
+      description: "The project's base URL, features (folders for flows), existing flows, sign-in profiles with their accounts, and helpers (email codes, 2FA, SMS, API calls). Read this before starting a flow.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string", description: "Optional when you are on one project." } }, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const c = await catalogOf(projectId, true);
+        const flowsBy = (featureId) => c.flows.filter((f) => f.featureId === featureId).map((f) => `    - ${f.name} (${f.steps} steps${isMobile(f.platform) ? `, ${f.platform}` : ""})`).join("\n");
+        const platforms = platformsOf(c);
+        const phones = platforms.android || platforms.ios ? await devicesSummary() : [];
+        const phoneLines = ["android", "ios"].filter((p) => platforms[p]).map((p) => {
+          const app = p === "android" ? c.mobile?.android?.appPackage : c.mobile?.ios?.bundleId;
+          const here = phones.filter((d) => d.platform === p);
+          const farms = (c.mobile?.cloud ?? []).map((f) => CLOUD_PROVIDER_NAME[f.provider]);
+          const chosen = c.mobile?.devices[p];
+          return `${p === "android" ? "Android" : "iOS"} app: ${app ?? "(not named \u2014 Settings \u2192 Environments)"}
+  Phones on this computer: ${here.length ? here.map((d) => `${d.name}${d.state === "ready" ? "" : ` (${d.state})`}`).join(", ") : "none"}` + (farms.length ? `
+  Cloud device farms: ${farms.join(", ")}` : "") + `
+  Runs: ${c.runWhere?.[p] === "cloud" ? "in the cloud" : "on this computer"}` + (chosen ? ` \u2014 ${chosen.kind === "local" ? chosen.name || chosen.id : `${CLOUD_PROVIDER_NAME[chosen.provider]}: ${chosen.device}`}` : "");
+        });
+        return text([
+          `Project ${projectId}. Tests: ${[platforms.web && "web", platforms.android && "Android app", platforms.ios && "iOS app"].filter(Boolean).join(", ")}.`,
+          platforms.web ? `Base URL: ${c.baseUrl || "(not set)"}${c.runWhere?.web === "cloud" ? " \u2014 test runs use a cloud browser; recording is on this computer" : ""}` : "",
+          ...phoneLines,
+          c.environments.length ? `Environments: ${c.environments.map((e) => `${e.name} ${e.baseUrl}`).join(", ")}` : "",
+          `
+Features:${c.features.length ? "" : " none yet"}`,
+          ...c.features.map((f) => `  - ${f.name} (id ${f.id})${f.description ? ` \u2014 ${f.description}` : ""}
+${flowsBy(f.id)}`),
+          ...c.draft ? [
+            `
+On Claude's working branch "${c.draft.title}" (${c.draft.changeId}), not yet published:`,
+            ...c.draft.features.length ? [`  New features: ${c.draft.features.map((f) => `${f.name} (id ${f.id})`).join(", ")}`] : [],
+            ...c.draft.flows.length ? c.draft.flows.map((f) => `    - flow: ${f.name} (${f.steps} steps, feature ${f.featureId}${f.after?.length ? `, after ${f.after.map((a) => `"${a}"`).join(", ")}` : ""})`) : ["  (no flows yet)"],
+            ...c.draft.caseFolders?.length ? [`  New case folders: ${c.draft.caseFolders.map((f) => f.name).join(", ")}`] : [],
+            ...(c.draft.cases ?? []).map((t) => `    - case: ${t.name} (folder ${t.folderId}) \u2014 rows: ${t.rows.join(" \u2192 ")}`)
+          ] : [],
+          `
+Test cases:${(c.cases ?? []).length ? "" : " none published"}`,
+          ...(c.caseFolders ?? []).map((f) => `  - ${f.name} (id ${f.id})
+${(c.cases ?? []).filter((t) => t.folderId === f.id).map((t) => `    - ${t.name} \u2014 rows: ${t.rows.join(" \u2192 ")}`).join("\n")}`),
+          `
+Sign-in profiles:${c.signIns.length ? "" : " none"}`,
+          ...c.signIns.map((s) => `  - ${s.name} (profileId ${s.profileId})${s.fields?.length ? ` \u2014 fields ${s.fields.map((f) => `"${f}"`).join(", ")}` : ""}: ${s.accounts.map((a) => `${a.name} (accountId ${a.accountId})`).join(", ") || "no accounts yet"}`),
+          `
+Helpers:${c.helpers.length ? "" : " none \u2014 create_helper makes one"}`,
+          ...c.helpers.map((h) => `  - ${h.name} (id ${h.id}) \u2014 ${h.what}${h.inputs.length ? `; needs ${h.inputs.map((n) => `{{${n}}}`).join(", ")}` : ""}${h.description ? ` \u2014 ${h.description}` : ""}`)
+        ].filter(Boolean).join("\n"));
+      }
+    },
+    {
+      name: "start_case",
+      title: "Start building a test case",
+      description: "Say which test case you are building, before recording what it needs: its name, its folder and its Given / When / Then lines (the case's own, from read_test_cases, when it already has them). The person watches it fill in: every step you then keep with act, add_check or use_helper \u2014 passing line, the number of the line it carries out \u2014 shows under that line at once. save_case then ties them on the saved case.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "The test case: the scenario it proves." },
+          folder: { type: "string", description: 'Its folder \u2014 area and topic, e.g. "Account \u2013 Sign up".' },
+          steps: { type: "array", items: { type: "string" }, description: "Its Given / When / Then lines, in order; And / But continue the line above." },
+          projectId: { type: "string" }
+        },
+        required: ["name", "folder", "steps"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const lines = parseGherkin((Array.isArray(args["steps"]) ? args["steps"].map(String) : []).join("\n"));
+        if (!lines?.length) throw new Error("the steps must each start with Given, When, Then, And or But");
+        return text(session.startCase(projectId, str(args["name"]) ?? "", str(args["folder"]) ?? "", lines));
+      }
+    },
+    {
+      name: "start_flow",
+      title: "Start writing a flow",
+      description: "Open a browser on this computer at the project's app \u2014 or, with platform android or ios, the project's phone app on a phone \u2014 and start a new flow. Returns the page or screen. Closes any flow that was being written.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: `The flow's name: the user journey, e.g. "Sign up and verify email".` },
+          feature: { type: "string", description: "The feature it belongs to: an existing feature's id or name, or a new name." },
+          startPath: { type: "string", description: `Where it starts, relative to the base URL. Default "/". On a phone: a deep link to open, or leave out for the app's first screen.` },
+          platform: { type: "string", enum: ["web", "android", "ios"], description: "Where the flow runs. Default: web, or the project's only platform." },
+          device: { type: "string", description: `Phones only: a phone from project_catalog by name, or a cloud farm's as "BrowserStack: Samsung Galaxy S23". Default: the project's choice, then whatever is connected.` },
+          after: {
+            type: "array",
+            items: { type: "string" },
+            description: "Flows this one starts after (names or ids from project_catalog). They are replayed first, so recording begins where they end; what THEY start after is added too. The saved flow links to them."
+          },
+          signIn: {
+            type: "object",
+            description: "Start signed in, with a profile (and optionally an account) from project_catalog.",
+            properties: { profileId: { type: "string" }, accountId: { type: "string" } },
+            required: ["profileId"],
+            additionalProperties: false
+          },
+          fresh: { type: "boolean", description: "Start over, ignoring a draft of this flow left by an earlier attempt. By default the earlier steps are replayed and kept, and recording carries on from there." },
+          projectId: { type: "string" }
+        },
+        required: ["name", "feature"],
+        additionalProperties: false
+      },
+      annotations: { openWorldHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const catalog = await catalogOf(projectId, true);
+        const featureAsked = str(args["feature"]) ?? "";
+        const feature = catalog.features.find((f) => f.id === featureAsked || f.name.toLowerCase() === featureAsked.toLowerCase());
+        const signIn = args["signIn"];
+        if (signIn && !catalog.signIns.some((s) => s.profileId === signIn.profileId)) {
+          throw new Error(`no sign-in profile ${signIn.profileId} \u2014 project_catalog lists them`);
+        }
+        const asked = Array.isArray(args["after"]) ? args["after"].map(String).filter(Boolean) : [];
+        const plan = asked.length ? await service.flowsAfter(projectId, asked) : null;
+        const platforms = platformsOf(catalog);
+        const enabled = ["web", "android", "ios"].filter((p) => platforms[p]);
+        const platform = str(args["platform"]) ?? (enabled.length === 1 ? enabled[0] : enabled.includes("web") ? "web" : void 0);
+        if (!platform) throw new Error(`this project tests ${enabled.join(" and ")} \u2014 say which with platform`);
+        if (!platforms[platform]) throw new Error(`this project does not test ${platform === "web" ? "a website" : `an ${platform === "ios" ? "iOS" : "Android"} app`} \u2014 turn it on in Settings first`);
+        const device = isMobile(platform) ? deviceFrom(str(args["device"]), platform, await devicesSummary(), catalog.mobile) : void 0;
+        const page = await session.start({
+          projectId,
+          ...isMobile(platform) ? { platform, ...device ? { device } : {} } : {},
+          ...plan ? { after: plan.prerequisites, preparation: plan.steps } : {},
+          name: str(args["name"]) ?? "Untitled flow",
+          ...feature ? { featureId: feature.id } : { featureName: featureAsked },
+          startPath: str(args["startPath"]) || (isMobile(platform) ? "" : "/"),
+          ...signIn?.profileId ? { signIn: { profileId: signIn.profileId, ...signIn.accountId ? { accountId: signIn.accountId } : {} } } : {}
+        }, catalog, { ...args["fresh"] === true ? { fresh: true } : {} });
+        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} ${isMobile(platform) ? "The app is open on the phone." : "The browser is open."}
+
+${page}`);
+      }
+    },
+    {
+      name: "read_page",
+      title: "Read the page",
+      description: "The current page \u2014 or phone screen \u2014 as its accessibility tree: each element's role and name, which is exactly what act and add_check refer to.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async () => text(await session.snapshot())
+    },
+    {
+      name: "act",
+      title: "Do one thing on the page",
+      description: `Perform one step and keep it in the flow if it worked. Returns the page afterwards. click/dblclick/rightclick/hover: role + name. fill: role + name + value (may use {{values}} from helpers). select: role + name + the option's label as value. check: role + name, value "true" or "false". press: a key such as "Enter" as value, optionally role + name of where. navigate: a path such as "/settings" or a full URL as value (on a phone, a deep link). back/forward: nothing. PHONE ONLY: tap (role + name), longPress (role + name), swipe (value up/down/left/right, optionally on role + name), scroll (to role + name, or value up/down), hideKeyboard, permission (value allow/deny), launchApp, terminateApp, resetApp, background (value: seconds), rotate (value portrait/landscape).`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          action: { type: "string", enum: ["click", "dblclick", "rightclick", "hover", "fill", "select", "check", "press", "navigate", "back", "forward", "tap", "longPress", "swipe", "scroll", "hideKeyboard", "permission", "launchApp", "terminateApp", "resetApp", "background", "rotate"] },
+          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." },
+          line: { type: "integer", minimum: 1, description: "The number of the test case's line (from start_case) this step carries out." }
+        },
+        required: ["action"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        if (!isAction(args["action"])) throw new Error("action must be one of click, dblclick, rightclick, hover, fill, select, check, press, navigate, back, forward \u2014 or on a phone tap, longPress, swipe, scroll, hideKeyboard, permission, launchApp, terminateApp, resetApp, background, rotate");
+        const action = args["action"];
+        return tagged(args, async () => session.act({
+          action,
+          ...str(args["role"]) ? { role: str(args["role"]) } : {},
+          ...str(args["name"]) !== void 0 ? { name: str(args["name"]) } : {},
+          ...str(args["within"]) ? { within: str(args["within"]) } : {},
+          ...Number.isInteger(args["nth"]) && args["nth"] >= 0 ? { nth: args["nth"] } : {},
+          ...str(args["value"]) !== void 0 ? { value: str(args["value"]) } : {},
+          ...typeof args["secret"] === "boolean" ? { secret: args["secret"] } : {}
+        }));
+      }
+    },
+    {
+      name: "add_check",
+      title: "Add a check",
+      description: "Assert something about the page (or phone screen) as it is now, and keep it in the flow if it holds. Page checks need only kind + value: heading, url (a path), title, message (text shown anywhere \u2014 on a phone, the way to check a screen). Element checks also need role + name: text, value, visible, hidden, checked, count. op: equals (default), contains or matches.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          kind: { type: "string", enum: ["heading", "url", "title", "message", "screen", "text", "value", "visible", "hidden", "checked", "enabled", "count"] },
+          value: { type: "string", description: `What it should be: the heading's words, the path, "true" for a state, a number for count.` },
+          op: { type: "string", enum: ["equals", "contains", "matches"] },
+          role: { type: "string" },
+          name: { type: "string" },
+          within: { type: "string" },
+          nth: { type: "integer", minimum: 0, description: "Which one, when several elements share this role and name: 0 is the first in the order read_page lists them (each shared name is marked [nth N of M])." },
+          line: { type: "integer", minimum: 1, description: "The number of the test case's line (from start_case) this step carries out." }
+        },
+        required: ["kind", "value"],
+        additionalProperties: false
+      },
+      run: async (args) => tagged(args, async () => session.check({
+        kind: str(args["kind"]),
+        value: str(args["value"]) ?? "",
+        ...str(args["op"]) ? { op: str(args["op"]) } : {},
+        ...str(args["role"]) ? { role: str(args["role"]), name: str(args["name"]) ?? "" } : {},
+        ...str(args["within"]) ? { within: str(args["within"]) } : {},
+        ...Number.isInteger(args["nth"]) && args["nth"] >= 0 ? { nth: args["nth"] } : {}
+      }))
+    },
+    {
+      name: "use_helper",
+      title: "Use a helper",
+      description: `Get a value from outside the page with one of the project's helpers \u2014 the code or link from a verification email, an authenticator code, an SMS code, a field of an API reply \u2014 and keep the step. Later steps use it as {{saveAs}}. then: "open" goes to the value as a link (for verification links).`,
+      inputSchema: {
+        type: "object",
+        properties: {
+          helperId: { type: "string", description: "The helper's id or name from project_catalog." },
+          inputs: { type: "object", additionalProperties: { type: "string" }, description: `Values for the helper's {{names}}, e.g. {"email": "qa+signup1@example.com"}.` },
+          saveAs: { type: "string", description: "What to call the value, e.g. code. Default: code for a mailbox, value otherwise." },
+          then: { type: "string", enum: ["remember", "open"] },
+          line: { type: "integer", minimum: 1, description: "The number of the test case's line (from start_case) this step carries out." }
+        },
+        required: ["helperId"],
+        additionalProperties: false
+      },
+      run: async (args) => tagged(args, async () => session.useHelper({
+        helperId: str(args["helperId"]),
+        ...args["inputs"] && typeof args["inputs"] === "object" ? { inputs: Object.fromEntries(Object.entries(args["inputs"]).map(([k, v]) => [k, String(v)])) } : {},
+        ...str(args["saveAs"]) ? { saveAs: str(args["saveAs"]) } : {},
+        ...args["then"] === "open" ? { then: "open" } : {}
+      }))
+    },
+    {
+      name: "list_steps",
+      title: "List the flow's steps",
+      description: "The flow being written, step by step.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async () => text(session.list())
+    },
+    {
+      name: "remove_step",
+      title: "Remove a step",
+      description: "Remove one step by its number in list_steps. The browser is not wound back; use replay_flow to see the flow as it now stands.",
+      inputSchema: { type: "object", properties: { number: { type: "integer", minimum: 1 } }, required: ["number"], additionalProperties: false },
+      annotations: { destructiveHint: true },
+      run: async (args) => text(session.remove(Number(args["number"])))
+    },
+    {
+      name: "replay_flow",
+      title: "Replay the flow from the start",
+      description: "Run the whole flow from the beginning in a fresh browser, exactly as a test run will, and report each step. Do this before saving.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+      run: async () => text(await session.replay())
+    },
+    {
+      name: "save_flow",
+      title: "Save the flow to a branch",
+      description: "Save the flow onto Claude's working branch for this project (made on the first save), for a person to review and publish. Saving the same name again replaces the earlier version there. The flow is replayed from the start first, as a test run will run it, unless the same steps already passed replay_flow; one that fails is not saved and the failing step is named. Returns the review link. Refused if the flow checks nothing.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          title: { type: "string", description: "The branch's title, used only when a new branch is started." },
+          branch: { type: "string", description: "Optional: a branch id (chg_\u2026) from list_my_branches to save onto instead." },
+          newBranch: { type: "boolean", description: "Start a separate branch instead of the working one. Only when the person asks for separate reviews." },
+          force: { type: "boolean", description: "Save even though the replay from the start failed \u2014 only when the person asked for it as it is." }
+        },
+        additionalProperties: false
+      },
+      run: async (args) => text(await session.save(str(args["title"]), {
+        ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {},
+        ...args["newBranch"] === true ? { newBranch: true } : {}
+      }, { ...args["force"] === true ? { force: true } : {} }))
+    },
+    {
+      name: "list_my_branches",
+      title: "List Claude's open branches",
+      description: "The project's open, unpublished branches that Claude wrote for this person, newest first, with review links. Use it to find a superseded branch to discard.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string", description: "Optional when you are on one project." } }, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const { changes } = await service.agentChanges(projectId);
+        if (!changes.length) return text("Claude has no open branches on this project.");
+        return text(changes.map((c) => `- ${c.id} \u2014 "${c.title}" (${new Date(c.createdAt).toISOString().slice(0, 16).replace("T", " ")}) ${service.origin}${c.path}`).join("\n"));
+      }
+    },
+    {
+      name: "gather_branches",
+      title: "Gather Claude's branches into one",
+      description: "Move the flows from Claude's open branches on this project into one branch, and delete the emptied ones \u2014 so the person reviews and publishes once. Only Claude's own, unedited branches; anything a person touched stops it.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          into: { type: "string", description: "The branch to gather into (chg_\u2026). Default: Claude's oldest open branch." },
+          title: { type: "string", description: 'A title for the gathered branch, e.g. "Sign in and sign up tests".' },
+          projectId: { type: "string" }
+        },
+        additionalProperties: false
+      },
+      annotations: { destructiveHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const done = await service.gatherChanges(projectId, {
+          ...str(args["into"]) ? { into: str(args["into"]) } : {},
+          ...str(args["title"]) ? { title: str(args["title"]) } : {}
+        });
+        catalogs.delete(projectId);
+        return text(`Gathered ${done.gathered.length} branch${done.gathered.length === 1 ? "" : "es"} into "${done.title}" (${done.changeId}). Review and publish it here: ${service.origin}${done.path}`);
+      }
+    },
+    {
+      name: "discard_branch",
+      title: "Delete one of Claude's branches",
+      description: "Delete an open branch Claude wrote, with the flows on it \u2014 e.g. one a redo replaced. Only after the person asked for it or agreed. Refused for a branch a person started, edited, or published; those are deleted in the dashboard.",
+      inputSchema: {
+        type: "object",
+        properties: { changeId: { type: "string", description: "The branch's id from list_my_branches (chg_\u2026)." }, projectId: { type: "string" } },
+        required: ["changeId"],
+        additionalProperties: false
+      },
+      annotations: { destructiveHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const changeId = str(args["changeId"]) ?? "";
+        const { deleted } = await service.discardChange(projectId, changeId);
+        return text(`Deleted ${changeId} and its branch ${deleted}.`);
+      }
+    },
+    {
+      name: "preview_case",
+      title: "Preview 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.",
+      inputSchema: CASE_INPUT,
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        return text(await session.previewCase(projectId, withLines(caseSpec(args))));
+      }
+    },
+    {
+      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.",
+      inputSchema: CASE_INPUT,
+      annotations: { openWorldHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const out = await session.saveCase(projectId, withLines(caseSpec(args)), await catalogOf(projectId, true));
+        catalogs.delete(projectId);
+        return text(out);
+      }
+    },
+    {
+      name: "read_import_file",
+      title: "Read a spreadsheet waiting to be converted",
+      description: "Read one part of a spreadsheet the person is importing (its id is imp_\u2026): every sheet's rows, each as a JSON array of its cells, numbered as the spreadsheet numbers them. Part 1 says how many parts there are; read every one.",
+      inputSchema: {
+        type: "object",
+        properties: { projectId: { type: "string" }, file: { type: "string", description: "The import's id, imp_\u2026" }, part: { type: "number", description: "Which part, from 1." } },
+        required: ["file", "part"],
+        additionalProperties: false
+      },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const got = await service.importPart(projectId, str(args["file"]) ?? "", Number(args["part"] ?? 1));
+        return text(`${got.file} \u2014 part ${got.part} of ${got.of}${got.part < got.of ? " (read the rest too)" : " (the last)"}
+
+${got.text}`);
+      }
+    },
+    {
+      name: "save_import_cases",
+      title: "Save the test cases a spreadsheet becomes",
+      description: "Save test cases converted from a spreadsheet being imported (its id is imp_\u2026), in batches as you go: features, each with cases \u2014 name (the scenario it proves), steps as Given / When / Then / And lines, row (its id or row in the file), description (optional). They are shown to the person to import; nothing is written to the project until they do. done: true with the last batch; note: anything you could not convert, and why. restart: true replaces what was saved before.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          file: { type: "string", description: "The import's id, imp_\u2026" },
+          features: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                feature: { type: "string" },
+                cases: {
+                  type: "array",
+                  items: {
+                    type: "object",
+                    properties: { name: { type: "string" }, description: { type: "string" }, steps: { type: "array", items: { type: "string" } }, row: { type: "string" } },
+                    required: ["name", "steps"],
+                    additionalProperties: false
+                  }
+                }
+              },
+              required: ["feature", "cases"],
+              additionalProperties: false
+            }
+          },
+          done: { type: "boolean" },
+          note: { type: "string" },
+          restart: { type: "boolean" }
+        },
+        required: ["file", "features"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const features = Array.isArray(args["features"]) ? args["features"] : [];
+        const saved = await service.saveImportCases(projectId, str(args["file"]) ?? "", {
+          features,
+          ...args["done"] === true ? { done: true } : {},
+          ...typeof args["note"] === "string" ? { note: args["note"] } : {},
+          ...args["restart"] === true ? { restart: true } : {}
+        });
+        return text(`Saved ${saved.added} more \u2014 ${saved.total} test cases so far.${saved.done ? " Done: the person can now look them over and import them." : " Keep going, and pass done: true with the last batch."}`);
+      }
+    },
+    {
+      name: "read_update_request",
+      title: "Read what should change in some test cases",
+      description: "Read a request to update test cases (its id is upd_\u2026): what the person wants changed, the change document they gave with it (a spec, release notes \u2014 read every part), and each test case as it is now \u2014 its id, feature, name and business steps.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" }, request: { type: "string", description: "upd_\u2026" }, part: { type: "number", description: "Which part of a long change document, from 1." } }, required: ["request"], additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const r = await service.updateRequest(projectId, str(args["request"]) ?? "");
+        const PART = 4e4;
+        const doc = r.document;
+        const parts = doc ? Math.max(1, Math.ceil(doc.text.length / PART)) : 0;
+        const part = Math.min(Math.max(1, Math.floor(Number(args["part"] ?? 1)) || 1), Math.max(parts, 1));
+        return text([
+          `What should change: ${r.instruction}`,
+          ...doc ? [`
+The change document "${doc.name}" \u2014 part ${part} of ${parts}${part < parts ? " (read the rest with part)" : ""}:
+${doc.text.slice((part - 1) * PART, part * PART)}
+\u2014 end of part ${part} \u2014`] : [],
+          ...r.cases.map((c) => [`
+${c.feature} \u203A ${c.name} (${c.id})`, ...c.businessSteps.length ? c.businessSteps.map((s) => `  ${s.keyword} ${s.text}`) : ["  (no steps written)"]].join("\n"))
+        ].join("\n"));
+      }
+    },
+    {
+      name: "propose_case_updates",
+      title: "Propose new steps for test cases",
+      description: "Propose the new business steps for test cases in an update request (upd_\u2026): for each case changed, its id and ALL its steps as Given / When / Then / And lines (the whole case, not only what changed). Cases that need no change are left out. The person sees each before and after and accepts the ones they want; nothing changes until they do. done: true with the last batch; note: anything you could not do.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          request: { type: "string", description: "upd_\u2026" },
+          updates: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: { case: { type: "string", description: "The test case's id, tc_\u2026" }, steps: { type: "array", items: { type: "string" } }, note: { type: "string", description: "Why, in a few words." } },
+              required: ["case", "steps"],
+              additionalProperties: false
+            }
+          },
+          done: { type: "boolean" },
+          note: { type: "string" }
+        },
+        required: ["request", "updates"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const updates = Array.isArray(args["updates"]) ? args["updates"] : [];
+        const r = await service.proposeUpdates(projectId, str(args["request"]) ?? "", { updates, ...args["done"] === true ? { done: true } : {}, ...typeof args["note"] === "string" ? { note: args["note"] } : {} });
+        return text(`Proposed new steps for ${r.proposed} of ${r.of} test cases.${r.done ? " Done: the person can now accept them." : " Pass done: true with the last batch."}`);
+      }
+    },
+    {
+      name: "read_test_cases",
+      title: "Read test cases",
+      description: "Read test cases by id (tc_\u2026) or exact name: their feature, business steps (Given / When / Then), whether they are automated, and the flows they run. Read a case's steps before automating it.",
+      inputSchema: {
+        type: "object",
+        properties: { projectId: { type: "string" }, cases: { type: "array", items: { type: "string" }, description: "Ids or names." } },
+        required: ["cases"],
+        additionalProperties: false
+      },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const refs = Array.isArray(args["cases"]) ? args["cases"].map(String) : [];
+        const { cases, missing } = await service.readCases(projectId, refs);
+        const parts = cases.map((c) => [
+          `${c.folder} \u203A ${c.name} (${c.id}) \u2014 ${c.automated ? `automated, rows: ${c.rows.join(" \u2192 ")}` : "not automated yet"}`,
+          ...c.description ? [`  ${c.description}`] : [],
+          ...c.businessSteps.length ? c.businessSteps.map((s) => `  ${s.keyword} ${s.text}`) : ["  (no business steps written)"]
+        ].join("\n"));
+        if (missing.length) parts.push(`Not found: ${missing.join(", ")} \u2014 project_catalog lists the test cases.`);
+        return text(parts.join("\n\n") || "No test cases found.");
+      }
+    },
+    {
+      name: "write_test_cases",
+      title: "Write test cases down, before automating them",
+      description: "Write test cases as business steps \u2014 Given / When / Then \u2014 with no flows yet, grouped by feature (the case folder), on Claude's working branch for review. They show as not automated until a test case with the same name is saved into the same folder with save_case, which keeps these steps. A case its folder already has is skipped. Use it when asked to write, plan or list test cases; record and save_case only when asked to automate.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          features: {
+            type: "array",
+            description: 'One entry per feature (case folder), e.g. "Account \u2013 Sign up".',
+            items: {
+              type: "object",
+              properties: {
+                feature: { type: "string" },
+                cases: {
+                  type: "array",
+                  items: {
+                    type: "object",
+                    properties: {
+                      name: { type: "string", description: 'The scenario it proves, e.g. "A taken email is refused".' },
+                      description: { type: "string" },
+                      steps: { type: "array", description: `Given / When / Then lines, e.g. "Given the sign-up form is open", "When I sign up with a taken email", "Then I see 'That email is taken'". And / But continue the line above.`, items: { type: "string" } }
+                    },
+                    required: ["name", "steps"],
+                    additionalProperties: false
+                  }
+                }
+              },
+              required: ["feature", "cases"],
+              additionalProperties: false
+            }
+          },
+          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: ["features"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const features = Array.isArray(args["features"]) ? args["features"] : [];
+        const groups = features.map((f) => ({
+          folder: String(f.feature ?? "").trim(),
+          cases: (Array.isArray(f.cases) ? f.cases : []).map((c) => {
+            const lines = Array.isArray(c.steps) ? c.steps.map(String) : [];
+            const steps = parseGherkin(lines.join("\n"));
+            if (!steps) throw new Error(`the steps of "${String(c.name ?? "")}" must each start with Given, When, Then, And or But`);
+            return { name: String(c.name ?? "").trim(), ...typeof c.description === "string" ? { description: c.description } : {}, businessSteps: steps };
+          })
+        }));
+        const done = await service.writeCases(projectId, groups, str(args["branch"]));
+        catalogs.delete(projectId);
+        const skipped = done.skipped.length ? ` Skipped ${done.skipped.length} the folder already had: ${done.skipped.map((s) => `"${s.name}"`).join(", ")}.` : "";
+        return text(`Wrote ${done.created.length} test case${done.created.length === 1 ? "" : "s"}, not automated yet, on Claude's working branch ${done.branch}.${skipped}`);
+      }
+    },
+    {
+      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.",
+      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 / test cases 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: "project_brief",
+      title: "Read the project's memory",
+      description: "The project's own knowledge, in one call: About the product (product.md, and product/<web|android|ios>.md where a platform differs), memory/decisions.md, what each linked codebase folder was learned as and which platform's code it holds, what each platform looked like when explored (explore/<platform>.md), and the list of feature pages and session summaries. Call it first in every conversation. With platform and/or features, the brief is the slice for that job: that platform's part and exploration, those features' notes, the code tagged for the platform, and who can sign in.",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" }, platform: { type: "string", enum: ["web", "android", "ios"], description: "The platform the job is about." }, features: { type: "array", items: { type: "string" }, description: "The features (or case folders) the job is about, by name." } }, additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const platform = str(args["platform"]);
+        const features = Array.isArray(args["features"]) ? args["features"].filter((f) => typeof f === "string") : [];
+        if (platform || features.length) {
+          try {
+            return text((await service.brief(projectId, { ...platform ? { platform } : {}, features })).brief);
+          } catch {
+          }
+        }
+        const { pages } = await service.knowledgePages(projectId);
+        const read = async (path3) => pages.some((p) => p.path === path3) ? (await service.knowledgePage(projectId, path3)).content : null;
+        const [product, glossary, decisions, web, android, ios, tagged2] = await Promise.all(["product.md", "glossary.md", "memory/decisions.md", "product/web.md", "product/android.md", "product/ios.md", "codebase.json"].map(read));
+        const codebases = pages.filter((p) => p.path.startsWith("codebase/"));
+        const tags = codebaseIndexOf(tagged2).folders;
+        const headers = await Promise.all(codebases.map(async (p) => {
+          const holds = tags[p.path.slice("codebase/".length, -".md".length)]?.tags ?? [];
+          return `- ${p.path}${holds.length ? ` (${holds.map((t) => CODEBASE_TAG_NAME[t]).join(", ")} code)` : ""}: ${(await read(p.path))?.split("\n").filter((l) => l.trim()).slice(0, 3).join(" \xB7 ") ?? ""}`;
+        }));
+        const explored = pages.filter((p) => p.path.startsWith("explore/"));
+        const walks = await Promise.all(explored.map(async (p) => {
+          const s = exploreSummary(await read(p.path) ?? "");
+          return `- ${p.path}: explored ${s.exploredAt ?? "?"}${s.environment ? ` in ${s.environment}` : ""}${s.screens !== null ? `, ${s.screens} screens` : ""} \u2014 read it with knowledge_read before testing that platform`;
+        }));
+        const shown = /* @__PURE__ */ new Set(["product.md", "glossary.md", "memory/decisions.md", "product/web.md", "product/android.md", "product/ios.md", "codebase.json", ...codebases.map((p) => p.path), ...explored.map((p) => p.path)]);
+        const parts = [
+          product ? `## About the product (product.md)
+${product}` : "No About the product yet \u2014 the person writes it on the Knowledge screen; offer to help draft it.",
+          web ? `## About the website (product/web.md)
+${web}` : "",
+          android ? `## About the Android app (product/android.md)
+${android}` : "",
+          ios ? `## About the iOS app (product/ios.md)
+${ios}` : "",
+          glossary ? `## glossary.md (older page; terms now belong in product.md)
+${glossary}` : "",
+          decisions ? `## memory/decisions.md
+${decisions}` : "",
+          codebases.length ? `## Codebase, as learned
+${headers.join("\n")}` : "No codebase learned yet.",
+          walks.length ? `## The product, as explored
+${walks.join("\n")}` : "",
+          `## Other pages
+${pages.filter((p) => !shown.has(p.path)).map((p) => `- ${p.path}`).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, product/<web|android|ios>.md, codebase/<folder>.md, features/<name>.md, memory/\u2026).",
+      inputSchema: { type: "object", properties: { projectId: { type: "string" }, path: { type: "string" } }, required: ["path"], additionalProperties: false },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const page = await service.knowledgePage(projectId, str(args["path"]) ?? "");
+        return text(page.content);
+      }
+    },
+    {
+      name: "write_knowledge",
+      title: "Write a knowledge page",
+      description: `Write what the project should remember, on Claude's working branch for review: product.md (About the product \u2014 the person's own description; write it only when they ask) and product/<web|android|ios>.md (what is particular to that platform's app), explore/<web|android|ios>.md (what you saw walking that platform: "# Explored: <Platform>", "Explored: <yyyy-mm-dd>", "Environment: <name>", "Screens: <n>" lines, then Screens, Journeys, Rules observed, Vocabulary, Suggested features), codebase/<folder>.md (what a linked folder holds \u2014 starting with "# <folder>", "Commit: <sha>" and "Learned: <yyyy-mm-dd>" lines, then routes, screens, forms and their validation, roles, APIs, flags; summarised, never copied code), features/<name>.md (screens, rules, quirks), memory/decisions.md (decisions and conventions), memory/sessions/<yyyy-mm-dd>-<topic>.md (what a job did). append: true adds to the end instead of replacing. Never a password, key or token \u2014 those are refused.`,
+      inputSchema: {
+        type: "object",
+        properties: { projectId: { type: "string" }, path: { type: "string" }, content: { type: "string" }, append: { type: "boolean" }, branch: { type: "string" } },
+        required: ["path", "content"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const saved = await service.writeKnowledge(projectId, {
+          path: str(args["path"]) ?? "",
+          content: String(args["content"] ?? ""),
+          ...args["append"] === true ? { append: true } : {},
+          ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {}
+        });
+        return text(`Wrote ${saved.path} (${saved.length} characters) on Claude's working branch ${saved.branch}.`);
+      }
+    },
+    {
+      name: "close_browser",
+      title: "Close the browser",
+      description: "Close the browser \u2014 or the app on the phone \u2014 and drop the flow being written, unsaved.",
+      inputSchema: { type: "object", properties: {}, additionalProperties: false },
+      annotations: { destructiveHint: true },
+      run: async () => {
+        await session.closeAndDrop();
+        return text("Closed.");
+      }
+    }
+  ];
+  return tools.map((tool) => ({
+    ...tool,
+    run: async (args) => {
+      let result;
+      try {
+        result = await tool.run(args);
+      } catch (error) {
+        throw new Error(session.redact(error.message));
+      }
+      return { ...result, content: result.content.map((c) => c.type === "text" && c.text !== void 0 ? { ...c, text: session.redact(c.text) } : c) };
+    }
+  }));
+}
+
+// src/mcp/upgrade.ts
+import { spawn } from "child_process";
+import readline2 from "readline";
+var PRIVATE = "flowriki-upgrade";
+var startWithNpx = (version) => spawn(process.platform === "win32" ? "npx.cmd" : "npx", ["-y", `@flowriki/agent@${version}`, "mcp"], {
+  env: { ...process.env, FLOWRIKI_MCP_CHILD: "1" },
+  stdio: ["pipe", "pipe", "inherit"]
+});
+var toolShape = (tools) => JSON.stringify(tools.map((t) => [t.name, t.description ?? "", t.inputSchema ?? null]).sort());
+function serveWithUpgrades(tools, info, opts) {
+  const input = opts.input ?? process.stdin;
+  const output = opts.output ?? process.stdout;
+  const log = opts.log ?? ((line) => process.stderr.write(`flowriki: ${line}
+`));
+  const send = (m) => output.write(`${JSON.stringify(m)}
+`);
+  if (!opts.output) {
+    console.log = console.info = console.warn = console.debug = (...args) => {
+      process.stderr.write(`${args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ")}
+`);
+    };
+  }
+  let initialize = null;
+  let localCalls = 0;
+  let ready = null;
+  let active = null;
+  let preparing = false;
+  let notice = null;
+  const forwarded = /* @__PURE__ */ new Set();
+  let timer = null;
+  const withNotice = (answer) => {
+    if (!notice || !answer.result || typeof answer.result !== "object") return answer;
+    const result = answer.result;
+    if (!Array.isArray(result.content)) return answer;
+    const text2 = notice;
+    notice = null;
+    return { ...answer, result: { ...result, content: [{ type: "text", text: text2 }, ...result.content] } };
+  };
+  const prepare = async (version) => {
+    if (preparing || ready || active || !initialize) return;
+    preparing = true;
+    let child = null;
+    try {
+      child = (opts.start ?? startWithNpx)(version);
+      const c = child;
+      const lines2 = readline2.createInterface({ input: c.stdout, crlfDelay: Infinity });
+      const waiting = /* @__PURE__ */ new Map();
+      const exited = new Promise((_, reject) => c.once("exit", (code) => reject(new Error(`it stopped while starting (exit ${code})`))));
+      exited.catch(() => void 0);
+      c.once("error", (e) => waiting.forEach((resolve) => resolve({ jsonrpc: "2.0", error: { message: e.message } })));
+      lines2.on("line", (line) => {
+        let m;
+        try {
+          m = JSON.parse(line);
+        } catch {
+          return;
+        }
+        if (typeof m.id === "string" && m.id.startsWith(PRIVATE)) {
+          waiting.get(m.id)?.(m);
+          waiting.delete(m.id);
+          return;
+        }
+        if (active?.child !== c) return;
+        if (m.id !== void 0 && m.id !== null) forwarded.delete(m.id);
+        send(m.id !== void 0 && m.id !== null && "result" in m ? withNotice(m) : m);
+      });
+      const ask = (method, params, id) => new Promise((resolve, reject) => {
+        waiting.set(id, resolve);
+        c.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, ...params ? { params } : {} })}
+`);
+        setTimeout(() => reject(new Error("it did not answer in time")), opts.readyWithinMs ?? 18e4).unref();
+      });
+      const hello = await Promise.race([ask("initialize", initialize.params, `${PRIVATE}-init`), exited]);
+      if (hello.error) throw new Error(JSON.stringify(hello.error));
+      c.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" })}
+`);
+      const listed = await Promise.race([ask("tools/list", void 0, `${PRIVATE}-tools`), exited]);
+      const theirs = listed.result?.tools ?? [];
+      ready = { child: c, version, lines: lines2, toolsChanged: toolShape(theirs) !== toolShape(tools) };
+      c.once("exit", () => {
+        if (ready?.child === c) ready = null;
+        if (active?.child === c) {
+          active = null;
+          for (const id of forwarded) send({ jsonrpc: "2.0", id, error: { code: -32603, message: "the updated Flowriki stopped \u2014 ask again" } });
+          forwarded.clear();
+          notice = `The updated Flowriki (${version}) stopped, so this connection carries on with ${opts.current}.`;
+          log(`updated server ${version} exited; back on ${opts.current}`);
+        }
+      });
+      log(`${version} is ready to take over from ${opts.current}`);
+    } catch (error) {
+      child?.kill();
+      log(`could not start ${version}: ${error.message}`);
+      notice ??= `Flowriki ${version} is out (this connection runs ${opts.current}) and could not switch over by itself: ${error.message}. A new Claude session starts the new version.`;
+    } finally {
+      preparing = false;
+    }
+  };
+  const maybeSwitch = async (incomingTool) => {
+    if (!ready || active || localCalls > 0) return false;
+    if (!opts.idle() && incomingTool !== "start_flow") return false;
+    const next = ready;
+    ready = null;
+    await opts.handOff().catch(() => void 0);
+    active = next;
+    if (timer) clearInterval(timer);
+    notice = `Flowriki updated itself from ${opts.current} to ${next.version} \u2014 the new version is answering now.` + (next.toolsChanged ? " It brings new or changed tools; if Claude does not offer them yet, start a new Claude session (in the terminal version of Claude Code, /mcp then Reconnect also works)." : "");
+    send({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
+    log(`switched to ${next.version}`);
+    return true;
+  };
+  const look = async () => {
+    if (active || ready || preparing) return;
+    const version = await opts.check().catch(() => null);
+    if (version) {
+      await prepare(version);
+      await maybeSwitch();
+    }
+  };
+  setTimeout(() => void look(), opts.firstCheckMs ?? 15e3).unref();
+  timer = setInterval(() => void look(), opts.everyMs ?? 30 * 6e4);
+  timer.unref();
+  const lines = readline2.createInterface({ input, crlfDelay: Infinity });
+  const pending = /* @__PURE__ */ new Set();
+  lines.on("line", (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "parse error" } });
+      return;
+    }
+    if (message.method === "initialize") initialize = message;
+    const task = (async () => {
+      const tool = message.method === "tools/call" ? String(message.params?.["name"] ?? "") : void 0;
+      if (!active && tool) await maybeSwitch(tool);
+      if (active) {
+        if (message.id !== void 0 && message.id !== null) forwarded.add(message.id);
+        active.child.stdin.write(`${line}
+`);
+        return;
+      }
+      if (tool) localCalls++;
+      try {
+        const answer = await handle(message, tools, info);
+        if (answer) send(tool ? withNotice(answer) : answer);
+        if (message.method === "notifications/initialized") send({ jsonrpc: "2.0", method: "notifications/tools/list_changed" });
+      } finally {
+        if (tool) localCalls--;
+      }
+      if (tool && ready) await maybeSwitch();
+    })();
+    pending.add(task);
+    void task.finally(() => pending.delete(task));
+  });
+  return new Promise((resolve) => lines.on("close", () => {
+    void Promise.allSettled([...pending]).then(() => {
+      if (timer) clearInterval(timer);
+      const child = active?.child ?? ready?.child;
+      if (!child) return resolve();
+      child.stdin?.end();
+      const done = () => resolve();
+      child.once("exit", done);
+      setTimeout(() => {
+        child.kill();
+        done();
+      }, 5e3).unref();
+    });
+  }));
+}
+
+// src/updates.ts
+import fs2 from "fs";
+import path2 from "path";
+var CACHE_MS = 30 * 60 * 1e3;
+async function latestPublished(opts = {}) {
+  const file = path2.join(dataDir(), "latest-agent.json");
+  if (!opts.fresh) {
+    try {
+      const kept = JSON.parse(fs2.readFileSync(file, "utf8"));
+      if (kept.version && kept.at && Date.now() - kept.at < CACHE_MS) return kept.version;
+    } catch {
+    }
+  }
+  try {
+    const res = await fetch(AGENT_LATEST_URL, { signal: AbortSignal.timeout(5e3), headers: { accept: "application/json" } });
+    if (!res.ok) return null;
+    const version = (await res.json()).version ?? null;
+    if (version) {
+      try {
+        fs2.mkdirSync(path2.dirname(file), { recursive: true });
+        fs2.writeFileSync(file, JSON.stringify({ version, at: Date.now() }));
+      } catch {
+      }
+    }
+    return version;
+  } catch {
+    return null;
+  }
+}
+async function updateFor(running) {
+  const latest = await latestPublished();
+  return agentUpdateFor(running, latest) ? latest : null;
+}
+
+// src/mcp/index.ts
+async function runMcp(opts) {
+  let service;
+  try {
+    service = resolveService(opts.service);
+  } catch (error) {
+    process.stderr.write(`${error.message}
+`);
+    return 2;
+  }
+  const connection = connectionFor(service);
+  const session = connection ? new AuthoringSession(new ServiceClient(connection), opts.headless ? { headless: true } : {}) : null;
+  let tools = connection && session ? authoringTools(new ServiceClient(connection), session) : authoringTools(null, null);
+  if (!connection) {
+    const why = `This computer is not connected to Flowriki at ${service}. Run \`flowriki-agent connect\` in a terminal, approve it in your browser, then restart Claude.`;
+    tools = tools.map((tool) => ({ ...tool, run: async () => ({ content: [{ type: "text", text: why }], isError: true }) }));
+  }
+  const closing = async () => {
+    await session?.close();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void closing());
+  process.on("SIGTERM", () => void closing());
+  const info = { name: "flowriki", version: opts.version, instructions: INSTRUCTIONS };
+  if (process.env["FLOWRIKI_MCP_CHILD"] === "1" || process.env["FLOWRIKI_NO_UPDATE"] === "1" || !/^\d+\.\d+\.\d+/.test(opts.version)) {
+    await serve(tools, info);
+  } else {
+    await serveWithUpgrades(tools, info, {
+      current: opts.version,
+      check: () => updateFor(opts.version),
+      idle: () => !session?.open,
+      handOff: async () => {
+        await session?.close();
+        if (session) session.draft = null;
+      }
+    });
+  }
+  await session?.close();
+  return 0;
+}
+
+// src/cli.ts
 var paint = (code) => (s) => `\x1B[${code}m${s}\x1B[0m`;
 var bold = paint("1");
 var dim = paint("2");
@@ -30,6 +2768,13 @@ ${bold("USAGE")}
   flowriki-agent doctor             diagnose setup problems
   flowriki-agent prepare            download the browser recording needs
   flowriki-agent disconnect         forget this computer's credential
+  flowriki-agent mobile setup       install what testing Android and iOS apps
+                                    needs (Appium and its drivers)
+  flowriki-agent mobile doctor      is this computer ready to test phones
+  flowriki-agent mobile devices     the phones, emulators and simulators here
+  flowriki-agent mcp                Flowriki as tools for Claude \u2014 started by
+                                    Claude Code or Claude Desktop, not by you:
+                                    claude mcp add flowriki -- flowriki-agent mcp
 
 ${bold("OPTIONS")}
   --project <dir>        a checkout to serve; repeat for several.
@@ -37,6 +2782,7 @@ ${bold("OPTIONS")}
   --name <label>         how this computer appears in your dashboard
   --service <url>        advanced: a self-hosted Flowriki. Defaults to the
                          hosted service, which is what you want.
+  --no-open              print the approval link without opening a browser
   --json                 machine-readable output for status and doctor
   -h, --help             this
   -v, --version          version
@@ -56,6 +2802,7 @@ async function main(argv) {
         name: { type: "string" },
         service: { type: "string" },
         json: { type: "boolean" },
+        "no-open": { type: "boolean" },
         help: { type: "boolean", short: "h" },
         version: { type: "boolean", short: "v" }
       }
@@ -79,8 +2826,13 @@ Run \`flowriki-agent --help\`.`);
   const service = values.service ? String(values.service) : void 0;
   const projects = (values.project ?? []).map(String);
   switch (command) {
+    // FIRST, and before anything writes to stdout: in this mode stdout is the
+    // protocol, and one stray line of output is a message Claude rejects.
+    case "mcp":
+      return runMcp({ ...service ? { service } : {}, version: AGENT_VERSION });
     case "connect": {
       const result = await connect({
+        open: !values["no-open"],
         ...service ? { service } : {},
         ...values.name ? { machineName: String(values.name) } : {},
         onProgress: (note) => {
@@ -91,7 +2843,7 @@ Run \`flowriki-agent --help\`.`);
           console.log(`  ${url}
 `);
           if (note.detail?.["canOpen"] === false) {
-            console.log(dim("  No graphical session here \u2014 open that link on a computer that has one.\n"));
+            console.log(dim("  Open the approval link in your browser.\n"));
           } else {
             console.log(dim("  Opening it for you. If nothing happens, use the link above.\n"));
           }
@@ -108,6 +2860,11 @@ Run \`flowriki-agent --help\`.`);
       return 0;
     }
     case "start": {
+      process.on("unhandledRejection", (reason) => {
+        const said = reason instanceof Error ? reason.stack ?? reason.message : String(reason);
+        console.error(red(`! a command failed without being handled \u2014 the agent is still running`));
+        console.error(dim(said.split("\n").slice(0, 4).join("\n")));
+      });
       const started = await start({
         ...service ? { service } : {},
         ...projects.length ? { projects } : {},
@@ -137,6 +2894,17 @@ Run \`flowriki-agent --help\`.`);
         console.log(dim(`  project  ${project.name}  (${project.root})`));
       }
       console.log(dim("\n  Running in the foreground. Ctrl-C to stop.\n"));
+      let told = null;
+      const tellIfBehind = async () => {
+        const newer = await updateFor(AGENT_VERSION).catch(() => null);
+        if (!newer || newer === told) return;
+        told = newer;
+        console.log(yellow(`  ! Flowriki agent ${newer} is out \u2014 this is ${AGENT_VERSION}.`));
+        console.log(dim(`    Update: npm install -g @flowriki/agent@latest   then stop (Ctrl-C) and start again
+`));
+      };
+      void tellIfBehind();
+      setInterval(() => void tellIfBehind(), 6 * 60 * 6e4).unref();
       let stopping = false;
       const shutdown = async (signal) => {
         if (stopping) return;
@@ -188,7 +2956,11 @@ Run \`flowriki-agent --help\`.`);
       console.log(`  node       ${found.node}  ${dim(`${found.platform}/${found.arch}`)}`);
       console.log(`  protocol   ${found.protocolVersion}`);
       console.log(`  data       ${found.dataDir}`);
-      console.log(`  service    ${found.service}  ${found.reachable ? green("reachable") : red("unreachable")}`);
+      console.log(
+        `  service    ${found.service}  ${found.reachable ? green("reachable") : red("unreachable")}` + // WHICH FLOWRIKI, from the service's own mouth. Not the site being
+        // tested — that is a project setting and changes nothing here.
+        (found.environment ? dim(`  [${found.environment}]`) : "")
+      );
       console.log(`  credential ${found.credentialFingerprint ?? dim("none stored")}`);
       console.log(
         `  browsers   ${found.playwright.chromiumInstalled ? green("chromium ready") : yellow("chromium not installed")}  ${dim(found.playwright.browsersPath ?? "")}`
@@ -206,6 +2978,42 @@ Run \`flowriki-agent --help\`.`);
       }
       return 0;
     }
+    case "mobile": {
+      const sub = positionals[1] ?? "doctor";
+      const report = (found) => {
+        for (const [title, lines] of [["Appium", found.appium], ["Android", found.android], ["iOS", found.ios]]) {
+          console.log(bold(title));
+          for (const line of lines) {
+            console.log(`  ${line.ok ? green("\u2713") : line.optional ? yellow("\u2013") : red("\u2717")} ${line.item.padEnd(15)} ${line.ok ? dim(line.detail) : line.detail}`);
+            if (!line.ok && line.fix) console.log(`    ${yellow("\u2192")} ${line.fix}`);
+          }
+        }
+        console.log(`
+  Android ${found.androidReady ? green("ready") : yellow("not ready")}   iOS ${found.iosReady ? green("ready") : yellow("not ready")}`);
+        return found.androidReady || found.iosReady ? 0 : 1;
+      };
+      if (sub === "setup") return report(await mobileSetup((line) => console.log(dim(`  ${line}`))));
+      if (sub === "doctor") {
+        const found = await mobileDoctor();
+        if (values.json) {
+          console.log(JSON.stringify(found, null, 2));
+          return found.androidReady || found.iosReady ? 0 : 1;
+        }
+        return report(found);
+      }
+      if (sub === "devices") {
+        const found = await listDevices();
+        if (values.json) {
+          console.log(JSON.stringify(found, null, 2));
+          return 0;
+        }
+        if (!found.length) console.log(yellow("  No phones, emulators or simulators found."));
+        for (const d of found) console.log(`  ${d.state === "ready" ? green("\u25CF") : dim("\u25CB")} ${d.name.padEnd(28)} ${dim(`${d.platform === "ios" ? "iOS" : "Android"} ${d.osVersion} \xB7 ${d.kind}${d.state === "ready" ? "" : ` \xB7 ${d.state}`}`)}`);
+        return 0;
+      }
+      console.error(`unknown: mobile ${sub} \u2014 use setup, doctor or devices`);
+      return 2;
+    }
     case "projects": {
       const { projects: found, skipped } = resolveCheckouts(projects.length ? projects : [process.cwd()]);
       for (const p of found) console.log(`  ${p.name}  ${dim(p.root)}`);