@kurrent/kcap 1.3.0-beta.6 → 1.3.0-beta.8

package/bin/refresh.js

@@ -1,6 +1,6 @@
-// Refreshes kcap's user-scope coding-agent installs so users pick up new or updated
-// skills, Codex/Cursor/Copilot hook commands, the Pi live-ingest extension, and
-// Claude plugin registration.
+// Refreshes kcap's user-scope coding-agent installs after an install or upgrade, by running
+// `kcap refresh` — the native binary owns the refresh list and the Claude plugin's .mcp.json patch,
+// so every installer (npm, the install scripts, a script install's `kcap update`) runs the same one.
 //
 // Shared by:
 // - postinstall.js — runs after `npm install -g @kurrent/kcap` (incl. upgrades),
@@ -10,152 +10,34 @@
 //
 // This file must never require kcap.js: during `kcap update`, runUpdate executes
 // before kcap.js's final module.exports assignment, so it would observe partial
-// exports. Shared platform/binary resolution lives in resolve.js instead.
+// exports.
 
 const { spawnSync } = require("child_process");
-const path = require("path");
-const fs = require("fs");
 
-// One entry per agent. Order is independent — each refresh is gated by its own
-// marker via `--if-installed`, which no-ops unless the user has previously
-// opted in (marker file present OR pre-marker install detected). A vendor entry
-// also refreshes the shared ~/.agents/skills tree, but only tops up one that is
-// already there: `plugin remove --skills` must survive an upgrade. The daemon
-// entry needs no marker: it acts only on service units that are already installed.
-const REFRESHES = [
-  ["plugin", "install", "--skills",  "--if-installed"],
-  ["plugin", "install", "--codex",   "--if-installed"],
-  ["plugin", "install", "--cursor",  "--if-installed"],
-  ["plugin", "install", "--copilot", "--if-installed"],
-  ["plugin", "install", "--pi",      "--if-installed"], // Pi extension (~/.pi/agent/extensions/kcap.ts)
-  ["plugin", "install", "--opencode", "--if-installed"], // OpenCode plugin (~/.config/opencode/plugins/kcap.ts)
-  ["plugin", "install", "--gemini",  "--if-installed"], // Gemini hooks/MCP/instructions (~/.gemini)
-  ["plugin", "install", "--kiro",    "--if-installed"], // Kiro agent hooks (~/.kiro/agents/kcap.json)
-  ["plugin", "install", "--antigravity", "--if-installed"], // Antigravity hooks (~/.gemini/config/plugins/kcap)
-  ["plugin", "install",              "--if-installed"], // Claude
-  ["daemon", "service", "refresh"],
-];
+// Above the binary's own worst case: eleven steps, each bounded at 60s.
+const REFRESH_TIMEOUT_MS = 15 * 60_000;
 
-// Runs each refresh via the given launcher (an absolute path to kcap.js).
-// Each refresh runs independently: a failure, timeout, or unexpected exit code
-// from one never prevents the others and never throws to the caller — a failed
-// refresh must never break `npm install` or report `kcap update` as failed.
-function runRefreshes(launcherPath) {
-  // Point the shipped Claude plugin's MCP entries at the native binary. Runs
-  // here because runRefreshes fires at exactly the two moments the plugin dir
-  // has just been (re)written by npm: postinstall and `kcap update`.
-  patchPluginMcpConfig(launcherPath);
-
-  for (const argv of REFRESHES) {
-    try {
-      spawnSync(process.execPath, [launcherPath, ...argv], {
-        stdio: "ignore",
-        env: process.env,
-        // Hard ceiling so a stalled child can never hang the caller.
-        timeout: 60_000,
-        killSignal: "SIGKILL",
-        windowsHide: true,
-      });
-    } catch {
-      // Never fail the caller.
-    }
-  }
-}
-
-// ── Claude plugin .mcp.json patch ───────────────────────────────────────────
-//
-// The plugin ships `"command": "kcap"`, which resolves to the node wrapper —
-// one resident Node runtime per MCP server per open Claude session (~25 MB
-// idle each). Rewriting the command to the resolved native binary makes Claude
-// spawn the binary directly. Best-effort: on any failure the shipped value
-// stays in place, which still works via the wrapper.
-
-// The servers shipped in the plugin's .mcp.json, keyed by canonical
-// `["mcp", <suffix>]` args. Only these exact name/args pairs are patched —
-// anything else in the file is preserved verbatim.
-const PLUGIN_MCP_SERVERS = {
-  "kcap-review":    "review",
-  "kcap-sessions":  "sessions",
-  "kcap-flows":     "flows",
-  "kcap-memory":    "memory",
-  "kcap-workitems": "workitems",
-  "kcap-plans":     "plans",
-  "kcap-artefacts": "artefacts",
-  "kcap-analytics": "analytics",
-  "kcap-knowledge": "knowledge",
-  "kcap-handoff":   "handoff",
-};
-
-// A command this patcher may rewrite: the shipped literal "kcap", or an
-// absolute path whose basename is the kcap binary (a previous patch that has
-// gone stale after an npm re-layout). Handles both path flavors so a stale
-// Windows path is still recognized. Anything else is a customization → keep.
-function isPatchableKcapCommand(command) {
-  if (command === "kcap") return true;
-  if (typeof command !== "string") return false;
-  if (!path.posix.isAbsolute(command) && !path.win32.isAbsolute(command)) return false;
-  const base = command.split(/[\\/]/).pop().toLowerCase();
-  return base === "kcap" || base === "kcap.exe";
-}
-
-// Pure: rewrites in place the canonical plugin entries of `cfg` whose command
-// is patchable, returning whether anything changed. Throws on a shape that
-// isn't the plugin config (caller turns that into the single warning).
-function patchPluginMcpServers(cfg, binaryPath) {
-  if (!cfg || typeof cfg !== "object" || Array.isArray(cfg)) {
-    throw new Error("config is not an object");
-  }
-  const servers = cfg.mcpServers;
-  if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
-    throw new Error("mcpServers is not an object");
-  }
-
-  let changed = false;
-  for (const [name, suffix] of Object.entries(PLUGIN_MCP_SERVERS)) {
-    const entry = servers[name];
-    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
-    if (!Array.isArray(entry.args) || entry.args.length !== 2 ||
-        entry.args[0] !== "mcp" || entry.args[1] !== suffix) continue; // customized args → keep
-    if (!isPatchableKcapCommand(entry.command)) continue;              // customized command → keep
-    if (entry.command === binaryPath) continue;                        // already current
-    entry.command = binaryPath;
-    changed = true;
-  }
-  return changed;
-}
-
-// Rewrites the plugin's shipped .mcp.json (a sibling `kcap/` dir of the
-// launcher's `bin/`) so Claude spawns the native binary directly. Validates
-// before writing, writes a sibling temp file, then renames atomically — the
-// original survives any pre-rename failure. Never throws; on failure it emits
-// ONE concise warning and leaves the shipped `"command": "kcap"` in place.
-// `binaryPath` is a test seam; real callers let it resolve.
-function patchPluginMcpConfig(launcherPath, binaryPath) {
-  let mcpJsonPath;
+// Runs `kcap refresh` through the given launcher (an absolute path to kcap.js), so the NEW
+// launcher and the NEW binary run it after an upgrade. Never throws and never fails the caller:
+// a failed refresh must never break `npm install` or report `kcap update` as failed. Its stderr
+// (which steps failed, a plugin patch that could not be written) is passed on through `warn`.
+function runRefreshes(launcherPath, warn = console.warn) {
   try {
-    binaryPath = binaryPath || require("./resolve").resolveNativeBinary();
-    if (!binaryPath) return; // unsupported platform / package missing — wrapper keeps working
-
-    mcpJsonPath = path.join(path.dirname(launcherPath), "..", "kcap", ".mcp.json");
-    if (!fs.existsSync(mcpJsonPath)) return; // dev checkout / plugin not shipped
-
-    const cfg = JSON.parse(fs.readFileSync(mcpJsonPath, "utf8"));
-    if (!patchPluginMcpServers(cfg, binaryPath)) return; // already patched / nothing canonical
-
-    const tmp = `${mcpJsonPath}.tmp-${process.pid}-${Date.now()}`;
-    try {
-      fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + "\n");
-      fs.renameSync(tmp, mcpJsonPath);
-    } catch (e) {
-      try { fs.unlinkSync(tmp); } catch {}
-      throw e;
-    }
-  } catch (e) {
-    console.warn(
-      `kcap: could not point the Claude plugin MCP entries at the native binary` +
-      ` (${e && e.message ? e.message : e}); they will keep launching via the node wrapper.`,
-    );
+    const result = spawnSync(process.execPath, [launcherPath, "refresh"], {
+      stdio: ["ignore", "ignore", "pipe"],
+      encoding: "utf8",
+      env: process.env,
+      timeout: REFRESH_TIMEOUT_MS,
+      killSignal: "SIGKILL",
+      windowsHide: true,
+    });
+    const stderr = (result.stderr || "").trim();
+    if (stderr) warn(stderr);
+    if (result.status !== 0)
+      warn("kcap: some agent integrations were not refreshed; run `kcap refresh` to retry.");
+  } catch {
+    // Never fail the caller.
   }
 }
 
-module.exports = { runRefreshes, patchPluginMcpConfig, patchPluginMcpServers, isPatchableKcapCommand };
+module.exports = { runRefreshes };

package/bin/resolve.js

@@ -1,10 +1,5 @@
-// Side-effect-free platform/native-binary resolution, shared by kcap.js (the
-// launcher) and refresh.js (postinstall / `kcap update` refresh).
-//
-// This lives in its OWN module — refresh.js must never require kcap.js: during
-// `kcap update`, runUpdate executes BEFORE kcap.js's final module.exports
-// assignment, so a refresh.js → kcap.js require would observe partial exports
-// exactly on that path. Requiring this module has no side effects.
+// Side-effect-free platform/native-binary resolution for kcap.js (the launcher).
+// Requiring this module has no side effects.
 
 const path = require("path");
 const fs = require("fs");

package/kcap/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "kcap",
-  "version": "1.3.0-beta.6",
+  "version": "1.3.0-beta.8",
   "description": "Records and visualizes Claude Code sessions via kcap CLI hooks"
 }

package/kcap/.codex-mcp.json

@@ -33,9 +33,9 @@
       "command": "kcap",
       "args": ["mcp", "handoff"]
     },
-    "kcap-artefacts": {
+    "kcap-pages": {
       "command": "kcap",
-      "args": ["mcp", "artefacts"]
+      "args": ["mcp", "pages"]
     },
     "kcap-knowledge": {
       "command": "kcap",

package/kcap/.mcp.json

@@ -40,9 +40,9 @@
       "args": ["mcp", "handoff"],
       "description": "Continue a session whose agent is gone — continue_session attaches this session to that session's work items and unfinished plans, refusing while it may still be running."
     },
-    "kcap-artefacts": {
+    "kcap-pages": {
       "command": "kcap",
-      "args": ["mcp", "artefacts"],
+      "args": ["mcp", "pages"],
       "cwd": "${CLAUDE_PROJECT_DIR}",
       "description": "Publish a self-contained HTML page — a plan, a report, a comparison — and get back a link to share. The page is sandboxed with no network access, so inline everything as data URIs. Private until you set visibility."
     },

package/kcap/README.md

@@ -20,6 +20,8 @@ Search and recall past Kurrent Capacitor sessions from inside the agent.
 | `get_session_transcript` | Speaker-tagged transcript window, with `around_event` drill-in for search hits |
 | `list_repo_plans` | List a repository's declared plans you can see, most recently touched first |
 | `get_declared_plans` | A plan's documents and full task list, by `plan_id` or `session_id` |
+| `get_session_evals` | Eval state and scores for up to 25 sessions by id; works on every plan |
+| `get_connection` | The server URL and profile this MCP server resolved at start; no network call |
 
 Repo-aware: it resolves the cwd to a repo hash at startup, so `search_sessions` defaults to *this* repo.
 
@@ -68,20 +70,20 @@ Governed read-only SQL over the org's curated coding-agent analytics views (sess
 
 Repo-aware: defaults to the cwd's repo; pass `scope: "global"` for org-wide questions. Requires `kcap login` and a kcap-server new enough to expose the `/api/analytics` endpoints.
 
-### `kcap-artefacts`
+### `kcap-pages`
 
 Publish a self-contained HTML page — a plan, a report, a comparison — and get back a link to share. The page is served under a sandbox with no network access, so every style, script and image has to be inlined as a data URI; an external URL renders as nothing.
 
 | Tool | Description |
 |------|-------------|
-| `publish_artefact` | Publish a page (`title`, and either `html` or a local `path`); optional `description`, `visibility`, `grants`, `session_ids`, `response_schema` to make it answerable, and `update_id` to revise an existing artefact without changing its URL |
-| `await_artefact_responses` | Block until people have answered — the human checkpoint. Returns on a respondent count, on a close, or on a timeout (which is not an error) |
-| `get_artefact_results` | Tallies and each person's current answer, without waiting |
-| `close_artefact_responses` | Freeze a version's answers; `closed: false` reopens and clears any deadline |
-| `list_my_artefacts` | The artefacts you can see — id, title, audience, latest version, URL |
-| `set_artefact_visibility` | Replace an artefact's audience (`none` / `org` / `scoped` + grants) |
+| `publish_page` | Publish a page (`title`, and either `html` or a local `path`); optional `description`, `visibility`, `grants`, `session_ids`, `response_schema` to make it answerable, and `update_id` to revise an existing page without changing its URL |
+| `await_page_responses` | Block until people have answered — the human checkpoint. Returns on a respondent count, on a close, or on a timeout (which is not an error) |
+| `get_page_results` | Tallies and each person's current answer, without waiting |
+| `close_page_responses` | Freeze a version's answers; `closed: false` reopens and clears any deadline |
+| `list_my_pages` | The pages you can see — id, title, audience, latest version, URL |
+| `set_page_visibility` | Replace a page's audience (`none` / `org` / `scoped` + grants) |
 
-An artefact is private to its owner until visibility says otherwise. The current session is cited automatically from `KCAP_SESSION_ID`, so a publish is attributed to the work that produced it.
+A page is private to its owner until visibility says otherwise. The current session is cited automatically from `KCAP_SESSION_ID`, so a publish is attributed to the work that produced it.
 
 Declaring a `response_schema` turns the page into a form the server validates and tallies: fields of type `choice`, `multi`, `score` or `text`, plus a `results_mode` deciding what other viewers see — `owner` (default, only you), `aggregate` (tallies, no names or free text) or `named` (who said what). Who answered is always the authenticated viewer; there is no field for it to forge. Reading, version history and takedown stay in the web UI.
 
@@ -110,7 +112,7 @@ Each hook pipes its JSON payload through the `kcap` CLI, which enriches it with
 - `review-flows` / `kcap-review-flows` — Run structured, iterative spec/code review loops; the reviewer vendor is chosen independently of the driver (pass a lowercase token like `claude`/`codex`/`cursor`)
 - `agent-flows` / `kcap-agent-flows` — Run structured multi-participant agent flows (catalog `definition_id` or an inline `definition_yaml`), each participant declaring its own vendor/model
 - `work-items` / `kcap-work-items` — Declare a work item's breakdown (parent and parts) and its blocks / blocked-by dependencies, so Home renders its topology, and record the loose ends a session leaves unfinished
-- `guided-tour` / `kcap-guided-tour` — Onboarding tour: what Capacitor has recorded for your team, then per-use-case tutorials (evals, session recall, PR review, analytics)
+- `guided-tour` / `kcap-guided-tour` — Onboarding tour: seven cards, one per reply (welcome, capture, investigate, collaborate, review, use, reuse), each a few questions to ask your agent
 
 In Claude they're invoked as `/kcap:recap`, `/kcap:errors`, `/kcap:guided-tour`, etc.
 

package/kcap/hooks/hooks.json

@@ -10,15 +10,6 @@
             "timeout": 5
           }
         ]
-      },
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/persist-session-id.sh",
-            "timeout": 3
-          }
-        ]
       }
     ],
     "SessionEnd": [
@@ -79,6 +70,16 @@
             "async": true
           }
         ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "kcap hook --claude --plan-read --no-update-check",
+            "timeout": 3
+          }
+        ]
       }
     ],
     "PostToolUseFailure": [
@@ -132,7 +133,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/set-title-prompt.sh",
+            "command": "kcap hook --claude --title-prompt --no-update-check",
             "timeout": 2
           }
         ]

package/kcap/skills/agent-flows/SKILL.md

@@ -1,25 +1,23 @@
 ---
 name: agent-flows
 description: >-
-  This skill should be used ONLY when the user explicitly asks to run a
-  structured agent *flow* by name or definition id — e.g. "start a flow",
-  "run the code-review flow", "run the X flow", "use flow definition X",
-  "kick off an agent flow", or wants an iterative loop run by a separate
-  hosted participant agent that continues until sign-off. It covers the same
-  underlying tools as the `review-flows` skill (`start_review_flow` etc. are
-  aliases of the generic tools documented here) — use `review-flows` for the
-  two built-in review kinds (`spec-review`, `code-review`) and this skill for
-  any other flow definition, or when the user names a `definition_id`
-  explicitly. Do NOT use this skill (and do NOT call the flows MCP tools) for
-  an ordinary request such as "review my PR", "do X for me", or "check this
-  over" where the user just wants you to do the work yourself — perform that
-  work directly instead. To start a hosted agent that works on its own, use
-  `start-agents`.
+  Use this skill to drive a structured agent *flow*: a separate hosted
+  participant agent runs a definition from the server's flow catalogue and
+  iterates with you until sign-off. Use it when the user names a flow or
+  definition id ("run the code-review flow", "start a flow", "use flow
+  definition X"), when the user accepts a flow you offered, or when you are
+  about to offer one listed under "Flows you may offer" in your session
+  context because its when-to-use applies. Before starting a flow, call
+  get_flow_definition and follow its guide. Do NOT use this skill (and do NOT
+  call the flows MCP tools) for an ordinary request such as "review my PR",
+  "do X for me", or "check this over" where the user wants you to do the work
+  yourself — do it directly instead. To start a hosted agent that works on its
+  own, use `start-agents`.
 ---
 
 # Agent Flows
 
-Use the `kcap mcp flows` MCP tools (`list_flow_definitions`, `start_flow`, `send_to_participant`, `get_flow_status`, `close_flow`) to run a structured agent **flow**: your work is handed to a **separate, hosted participant agent** driven by a flow definition from the server's catalog, which returns a result (kind `findings` with the participant's result text, or `clean`); you address a `findings` result and keep iterating until the clean signal. This is a deliberate, heavier workflow — use it only when the user explicitly opts into it.
+Use the `kcap mcp flows` MCP tools (`list_flow_definitions`, `get_flow_definition`, `start_flow`, `send_to_participant`, `get_flow_status`, `close_flow`) to run a structured agent **flow**: your work is handed to a **separate, hosted participant agent** driven by a flow definition from the server's catalog, which returns a result (kind `findings` with the participant's result text, or `clean`); you address a `findings` result and keep iterating until the clean signal. This is a deliberate, heavier workflow — use it when the user asks for a flow or accepts one you offered, never on your own initiative.
 
 ## Long rounds are normal
 
@@ -39,15 +37,14 @@ and end the reviewer turn. The hosted-reviewer contract wins over driver-looking
 
 These tools do **not** perform the work themselves — they hand it off to a separate hosted participant agent running a named flow definition. If the user simply asked *you* to do something in a normal session — e.g. "review my PR", "review this diff", "check this spec", "do X" — just do it yourself and report the result directly. Do **NOT** call `start_flow` / `send_to_participant` for an ordinary request; that would spin up a hosted agent the user did not ask for.
 
-Only start a flow when the user explicitly asks for a flow — e.g. "start a flow", "run the code-review flow", "use flow definition X", or "re-review after I address the findings" via a flow.
+Only start a flow when the user explicitly asks for one — e.g. "start a flow", "run the code-review flow", "use flow definition X", or "re-review after I address the findings" via a flow — or accepts a flow you offered. Offer a flow only when your session context lists it under **Flows you may offer** and its when-to-use applies to what just happened; ask, and never start it before the user says yes. Skip the offer when the user asked you to do the work yourself, or while you are mid-task.
 
 ## Choosing the flow definition
 
-Once the user has explicitly opted into a flow (see above), pick the `definition_id`:
+Once the user has asked for a flow or accepted one you offered (see above), pick the `definition_id`:
 
-- Spec or design document → `definition_id: "spec-review"` (built-in; same as `review-flows`' `spec-review` kind)
-- Code changes or a pull request → `definition_id: "code-review"` (built-in; same as `review-flows`' `code-review` kind)
-- Anything else → the definition id the user named, or one from `list_flow_definitions` (read-only), which lists every definition this server can start — operator-published ones included — with its version, description, participant roles and their authored vendor and model, and whether it is single- or multi-participant. Call it whenever the user has not named a definition, or named one you have not seen listed: a definition it does not list is disabled, deleted or unknown, and `start_flow` will refuse it. If several fit, ask the user rather than guessing. A server that answers that it cannot list definitions only predates the tool — the two built-ins and any id the user names still work.
+- The flow the user named, or the one you offered and they accepted.
+- If the user has not named one → choose from `list_flow_definitions` (read-only), which lists every definition this server can start — operator-published ones included — with its version, description, participant roles and their authored vendor and model, and whether it is single- or multi-participant. Call it whenever the user has not named a definition, or named one you have not seen listed: a definition it does not list is disabled, deleted or unknown, and `start_flow` will refuse it. If several fit, ask the user rather than guessing. A server that answers that it cannot list definitions only predates the tool — the two built-ins and any id the user names still work.
 
 For the reserved `spec-review` and `code-review` aliases, reviewer-vendor language is role-bound:
 pass the one vendor explicitly named as the reviewer, ignore driver-harness mentions, honor
@@ -88,6 +85,10 @@ vendor supports this: the daemon must advertise a runtime model resolver for the
 (Claude and Codex today; other vendors keep vendor-only overrides with no model choice) or the
 server rejects the override outright.
 
+## Read the flow's guide first
+
+Before a catalogue start (`definition_id`), call `get_flow_definition(definition_id)`. The guide is written by whoever published the flow: what to put in `context`, which target to name, how to iterate on its results and when to close. Where it differs from the generic rules below, follow the guide. A server that does not publish guides says so; then work from the definition's description and the rules below. A flow started with an inline `definition_yaml` has no catalogue id and no guide: drive it by the generic rules and its own YAML.
+
 ## Composing a dynamic flow
 
 If nothing `list_flow_definitions` shows fits — no `definition_id` covers the roles or workflow you need — compose one inline instead: pass `definition_yaml` to `start_flow` in place of `definition_id`. Provide exactly one of the two, never both. (`start_review_flow` / `submit_review_round` stay catalog-only — this only applies to the generic `start_flow`.)
@@ -147,7 +148,7 @@ After applying the role-surface safety gate, if `start_flow` / `send_to_particip
 5. **If participant output is unclear or requires user input**, pause and ask the user before proceeding.
 6. **Never start a nested flow.** If you are the hosted participant (see above), do not call these tools yourself.
 7. **Address each role independently.** A flow definition declares one or more participant roles in its `participants` map (single-participant definitions use `reviewer`). A multi-participant `start_flow` returns no round — nothing has launched yet. Call `send_to_participant(flow_run_id, participant=<role>, message=…)` naming the role you want to address; its first message launches that role's agent lazily. Only one round is in flight per role at a time — sending to a role that's still working on a round gets a `409` naming the busy round — but every OTHER role stays addressable in the meantime. Sending an unknown role is rejected by the server, which names the valid roles in its error.
-8. **For a code review flow (`definition_id: "code-review"`), do NOT ask the participant to run tests.** CI covers test execution; participant feedback is on correctness, design, and adherence to conventions.
+8. **Ask the participant only for what the flow's guide allows.** If the guide says CI covers tests, do not ask the participant to run them; participant feedback is on what the flow exists to judge.
 9. **State where your changes live.** The participant's worktree is mirrored from **this session's project directory**, not from the directory you are working in, and no tool parameter can redirect it. So if you changed directory, are a subagent in another checkout, or the changeset lives in another worktree/repo/machine, the participant will NOT see it: say so in `context`/`message`, give it an explicit commit range (never `git diff origin/main...HEAD`), and inline the diffs — or pass `mode: "context-only"` to make your context the sole source of truth. The participant flags referenced changes it cannot find; incomplete context wastes a full round.
 
 ## Pending messages
@@ -170,10 +171,17 @@ The server enforces per-run budgets; watch for these in tool error responses:
 
 ## Workflow
 
+A catalogue flow (`definition_id`) starts with its guide; an inline `definition_yaml` flow skips this step:
+
+```
+get_flow_definition(definition_id)
+  → read the driver guide; prepare the context it asks for
+```
+
 Single-participant definitions start eagerly — round 1 runs as part of `start_flow`:
 
 ```
-start_flow(definition_id, target_kind, target_ref, target_title, context)
+start_flow(definition_id, target_kind, target_ref, target_title, session_title, context)
   → participant returns a result: kind findings (with the result text) | kind clean
 
 if clean:
@@ -192,7 +200,7 @@ if findings:
 Multi-participant definitions start round-less — you address each role yourself, and the run is clean only in aggregate:
 
 ```
-start_flow(definition_id, target_kind, target_ref, target_title, context)
+start_flow(definition_id, target_kind, target_ref, target_title, session_title, context)
   → no round yet — roles have not launched
 
 send_to_participant(flow_run_id, participant="reviewer", message=…)
@@ -218,7 +226,8 @@ report completion to user
 | Tool | Required args | Optional args | When to call |
 |---|---|---|---|
 | `list_flow_definitions` | — | — | Before `start_flow`, whenever the user has not named a definition or named one you have not seen listed. Read-only: returns each runnable definition's id, version, description, whether it is single- or multi-participant, and its participants' role, authored vendor and model. A `server_catching_up` error is retryable — do not read it as an empty catalog. |
-| `start_flow` | Exactly one of `definition_id` (catalog id, e.g. `spec-review`, `code-review`, or a custom catalog id) or `definition_yaml` (inline dynamic definition — see "Composing a dynamic flow"); plus `target_kind` (what is being worked on: `spec`, `code`, `pr`, `branch`, `file`, etc.), `target_ref` (a path, branch name, or PR URL/number that identifies the target), `target_title` (short human-readable title), `context` (background context: what to focus on, constraints, definition of done) | `vendor` (reserved aliases only — explicit reviewer vendor; omit to use the definition's authored vendor, or your saved `flows.reviewer_vendor` preference if it declares none), `model` (reserved aliases only — explicit reviewer model override; REQUIRES `vendor`, rejected on dynamic/multi-participant starts), `instructions`, `mode` (`context-only` — optional; by default the participant's worktree is mirrored from THIS SESSION's project directory, not from the directory you are working in. Pass `context-only` to opt out and treat the submitted context as authoritative) | Once, at the start of a flow task. |
+| `get_flow_definition` | `definition_id` | — | Before every catalogue (`definition_id`) `start_flow`. Read-only: returns the definition's participants and when to use it, then its authored driver guide (what to submit, how to iterate, when to close). An unknown, disabled or deleted id is an error; an older server reports that it publishes no guides. |
+| `start_flow` | Exactly one of `definition_id` (catalog id, e.g. `spec-review`, `code-review`, or a custom catalog id) or `definition_yaml` (inline dynamic definition — see "Composing a dynamic flow"); plus `target_kind` (what is being worked on: `spec`, `code`, `pr`, `branch`, `file`, etc.), `target_ref` (a path, branch name, or PR URL/number that identifies the target), `target_title` (short human-readable title), `session_title` (the participant session's title: a short phrase naming this piece of work, specific enough to tell it apart from other sessions — it replaces the definition's generic opening instruction as the name), `context` (background context: what to focus on, constraints, definition of done) | `vendor` (reserved aliases only — explicit reviewer vendor; omit to use the definition's authored vendor, or your saved `flows.reviewer_vendor` preference if it declares none), `model` (reserved aliases only — explicit reviewer model override; REQUIRES `vendor`, rejected on dynamic/multi-participant starts), `instructions`, `mode` (`context-only` — optional; by default the participant's worktree is mirrored from THIS SESSION's project directory, not from the directory you are working in. Pass `context-only` to opt out and treat the submitted context as authoritative) | Once, at the start of a flow task. |
 | `send_to_participant` | `flow_run_id`, `participant` (role name declared in the flow definition's `participants` map; single-participant definitions use `reviewer` — an unknown role is rejected, naming the valid ones), `message` | `instructions`, `async` (defaults to `true`) | After addressing a non-clean result for that role, or to launch a role for the first time. Pass the same `flow_run_id`, the role's name, and the updated message. |
 | `get_flow_status` | — | `flow_run_id` (omit to read the newest open flow this session started, or on a harness without a session identity the newest one started from this workspace; several open flows are listed instead), `session_id` (look up another session's flows; defaults to this session), `wait` (`true`/`false`, defaults to `false`) — when `true`, blocks until the round is terminal or roughly 3.5 minutes pass, instead of returning the current snapshot immediately | Poll or check the current status of a flow run (running, waiting, completed, failed). Use `wait: true` to ride out a long round instead of polling repeatedly yourself, and omit `flow_run_id` to recover a flow whose id you never received or lost. |
 | `close_flow` | `flow_run_id` | — | Only after the definition's clean signal — or when abandoning the task early; the run otherwise stays open until closed. |
@@ -226,13 +235,14 @@ report completion to user
 ## Example (custom definition)
 
 ```
-# Step 1 — start (all five required args required; the participant sees a mirror of THIS SESSION's
+# Step 1 — start (all six args required; the participant sees a mirror of THIS SESSION's
 # project directory, not of the directory you are working in — pass mode="context-only" to opt out)
 start_flow(
   definition_id="code-review",
   target_kind="branch",
   target_ref="feature/add-null-check",
   target_title="Add null check on user input",
+  session_title="Review the null check on user input",
   context="Review the diff on this branch for correctness and adherence to project conventions."
 )
 # → returns flow_run_id, e.g. "flow_abc123"
@@ -261,6 +271,7 @@ start_flow(
   target_kind="branch",
   target_ref="feature/add-null-check",
   target_title="Add null check on user input",
+  session_title="Review and test the null check on user input",
   context="Review the diff on this branch and write/run tests for the new code path."
 )
 # → returns flow_run_id, e.g. "flow_xyz789"; no round in the response