specrails-desktop 2.64.1 → 2.65.0

package/docs/internals/api-reference.md

@@ -25,6 +25,29 @@ The CLI and the desktop client read the token automatically. The browser client
 
 There is no UI to set or clear the token, and it is not an app setting.
 
+## Versioning and deprecation policy
+
+Every response under `/api` — desktop routes, project-scoped routes, public routes, auth rejections and 404s — carries the header:
+
+```http
+X-Specrails-Api-Version: 1
+```
+
+The header is set by middleware mounted in `server/index.ts` before any `/api` router (and exposed to allowed CORS origins), so no route can bypass it. `GET /api/health` (public) also returns `apiVersion`, and `GET /api/meta` (authenticated) returns the full version set. The constant lives in `server/api-version.ts`.
+
+Rules:
+
+1. **Additive changes keep the version.** New routes, new optional request fields and new response fields are not breaking. Clients must ignore response fields they do not know.
+2. **`apiVersion` is bumped only on a breaking change**: removing or renaming a route or field, changing a field's type or meaning, tightening validation of an existing request, or changing a WebSocket event contract. A bump is a `feat!`/`fix!` commit with a `BREAKING CHANGE:` footer.
+3. **Deprecate before removing.** A route or field to be removed is first marked deprecated: it keeps working, the deprecation is recorded in the ledger below and announced in `CHANGELOG.md` under a **Deprecations** heading for the release that ships it (see [CONTRIBUTING](../../CONTRIBUTING.md#api-changes-and-deprecations)).
+4. **Keep deprecated surface for at least two minor releases.** Something deprecated in `2.65.0` can be removed no earlier than `2.67.0`, and the removal itself is a breaking change under rule 2.
+
+Deprecation ledger (newest first):
+
+| Route or field | Deprecated in | Earliest removal | Replacement |
+|---|---|---|---|
+| — | — | — | No deprecations yet |
+
 This page is hand-maintained against the route declarations in `server/*-router.ts`, the per-domain `server/project-router-{jobs,spending,settings,terminals,tickets,chat,setup}.ts` family, `server/modules/code/runtime/code-explorer-router.ts`, and `server/jira-router.ts`. If you spot a discrepancy, please file an issue.
 
 ---
@@ -33,7 +56,7 @@ This page is hand-maintained against the route declarations in `server/*-router.
 
 | Prefix | Router | Auth | Notes |
 |--------|--------|------|-------|
-| `/api/health` | direct | none | Liveness probe (`{ status, version, uptime, projects, mode }`) |
+| `/api/health` | direct | none | Liveness probe (`{ status, version, apiVersion, uptime, projects, mode }`) |
 | `/api/token` | direct | none | Returns the auth token for local bootstrapping (loopback-only) |
 | `/api/docs` | `docs-router` | loopback-only (mounted before token auth) | Bundled documentation portal |
 | `/api/mobile/*` | `mobile-admin-router` | Bearer / X-Desktop-Token + loopback | Mobile Gateway admin (enable/pair/devices) |
@@ -63,8 +86,9 @@ A non-localhost `Origin` header is rejected by the CORS middleware with `403 For
 | Method | Path | Notes |
 |--------|------|-------|
 | `GET` | `/projects` | List registered projects |
-| `POST` | `/projects` | Register a project. Body `{ path, name?, provider?, providers? }`. Each provider value is one of `claude`, `codex`, `gemini`, `kimi` (registry-validated). `providers: string[]` enables a multi-provider project (first entry = primary/default); legacy single `provider` still honoured; omit both to default to `["claude"]`. 409 if the path is already registered or Kimi fails its executable/version/Core-target checks. 400 if a provider is unknown, or if a disabled provider is selected: `codex` when `SPECRAILS_CODEX_BETA=0`, `gemini` when `SPECRAILS_GEMINI_BETA=0` (both default-enabled). Kimi has no beta flag: it requires a usable `kimi` CLI ≥ 0.27.0 and a Core build that advertises the Kimi target. Kimi 0.27 has no safe non-billing authentication probe, so login/model configuration is confirmed by the first real turn |
+| `POST` | `/projects` | Register a project. Body `{ path, name?, provider?, providers? }`. Each provider value is one of `claude`, `codex`, `gemini`, `kimi` (registry-validated). `providers: string[]` enables a multi-provider project (first entry = primary/default); legacy single `provider` still honoured; omit both to register with the auto-detected provider set (`["claude"]` when nothing is detected yet). After `201` the workspace is assembled in the background for the detected providers; progress arrives as `project.assemble_progress` WS events. 409 if the path is already registered or Kimi fails its executable/version/Core-target checks. 400 if a provider is unknown, or if a disabled provider is selected: `codex` when `SPECRAILS_CODEX_BETA=0`, `gemini` when `SPECRAILS_GEMINI_BETA=0` (both default-enabled). Kimi has no beta flag: it requires a usable `kimi` CLI ≥ 0.27.0 and a Core build that advertises the Kimi target. Kimi 0.27 has no safe non-billing authentication probe, so login/model configuration is confirmed by the first real turn |
 | `DELETE` | `/projects/:id` | Unregister (does not delete the project directory) |
+| `POST` | `/projects/:id/assemble-retry` | Re-run the background workspace assembly for the providers that failed (every detected provider when none is recorded as failed). `202 { retrying: [...] }`, or `202 { alreadyRunning: true }` while one is running; `409` when no provider is detected; progress via `project.assemble_progress` |
 | `GET` | `/resolve?path=…` | Find a project by **exact** canonical filesystem path. No parent-directory walking — a subdirectory returns 404 |
 
 Example — register a project that uses both Claude and Gemini:
@@ -85,18 +109,23 @@ Example — register a project that uses both Claude and Gemini:
 |--------|------|-------|
 | `GET` | `/state` | `{ projects, projectCount, …todayStats }` (today's cross-project cost/run aggregates spread into the response) |
 | `GET` | `/cli-status` | Detected AI CLI provider + version (`{ provider, version }`), e.g. `claude`, `codex`, `gemini`, or `kimi` — runs the registered adapter's version probe. Registry-driven |
-| `GET` | `/available-providers` | Provider catalogue used by the setup wizard. Registry-driven map (`{ claude, codex, gemini, kimi, tiers, providerIssues, launchDescriptors }`) reporting which CLIs are usable. Codex/Gemini are surfaced unless forced off by `SPECRAILS_CODEX_BETA=0` / `SPECRAILS_GEMINI_BETA=0` (both enabled by default). Kimi is reported unavailable, with a machine-readable `providerIssues.kimi`, when the CLI is missing/unusable, is older than 0.27.0, or the installed Core lacks the Kimi target. The bounded readiness probe is intentionally non-billing and cannot prove account authentication; a login/configuration problem is surfaced by the first model turn. `launchDescriptors` exposes each external CLI command; the app does not bundle a Kimi daemon/server |
+| `GET` | `/available-providers` | Provider catalogue used by the Add Project dialog (no-provider warning), mission and provider pickers. Registry-driven map (`{ claude, codex, gemini, kimi, tiers, providerIssues, launchDescriptors }`) reporting which CLIs are usable. Codex/Gemini are surfaced unless forced off by `SPECRAILS_CODEX_BETA=0` / `SPECRAILS_GEMINI_BETA=0` (both enabled by default). Kimi is reported unavailable, with a machine-readable `providerIssues.kimi`, when the CLI is missing/unusable, is older than 0.27.0, or the installed Core lacks the Kimi target. The bounded readiness probe is intentionally non-billing and cannot prove account authentication; a login/configuration problem is surfaced by the first model turn. `launchDescriptors` exposes each external CLI command; the app does not bundle a Kimi daemon/server |
+| `GET` | `/meta` | Versions a client negotiates with: `{ apiVersion, appVersion, coreVersion, contractSchemaVersion, channel, updateManifestUrl }`. `coreVersion` is the Core in use (active framework, else the located contract's Core, else the bundled one); `contractSchemaVersion` is the integration contract's `schemaVersion`; unknown values are `null`. `channel` is the update channel (`latest` or `stable`) and `updateManifestUrl` the Tauri updater manifest it reads |
 | `GET` | `/core-compat` | specrails-core version compatibility probe |
+| `GET` | `/core-update/status` | Core update status without network access. Includes `channel`, `resolvedDistTag` (`latest`/`stable`/`null`) and `channelFallback` (`true` when `stable` was requested but Core has no `stable` dist-tag, so `latest` was used). A version cached for another channel is never offered |
+| `POST` | `/core-update/check` | Resolve the channel's npm dist-tag (`stable` → `stable`, falling back to `latest` only on a 404 for the tag) and return the refreshed status |
+| `POST` | `/core-update/update` | Install the checked version (or `{ version }`). `202`; progress over the `core_update.progress` WebSocket event |
 | `GET` | `/setup-prerequisites` | Tool checks (`node`/`npm`/`npx`/`git`, optionally `uv`). Add `?diagnostic=1` to nest a `diagnostic` object: `{ pathSegments, pathSources, loginShellStatus, whichResults, nodeEnv, platform }` |
 
 ### Settings, budget, theme
 
 | Method | Path | Notes |
 |--------|------|-------|
-| `GET` | `/settings` | App-wide settings, including `allowSubagents` (default `false`) and `subagentRuntime` (default `null`) |
-| `PUT` | `/settings` | Update any subset of `{ port?, specrailsTechUrl?, costAlertThresholdUsd?, allowSubagents?, subagentRuntime? }`. `subagentRuntime` is `null` (same as the mission agent) or `{ provider, model, effort: string \| null }` for missions without a project; an invalid value returns `400`. `allowSubagents` is the app-wide "Allow sub-agents" setting for missions without a project. It must be a boolean (otherwise `400` and nothing is written), and a change refreshes the policy of open sessions |
+| `GET` | `/settings` | App-wide settings, including `allowSubagents` (default `true`), `subagentRuntime` (default `null`) and `updateChannel` (`latest` default, or `stable`) |
+| `PUT` | `/settings` | Update any subset of `{ port?, specrailsTechUrl?, costAlertThresholdUsd?, allowSubagents?, subagentRuntime?, updateChannel? }`. `updateChannel` must be `latest` or `stable` (otherwise `400` and nothing is written); it selects the Desktop updater manifest and the Core npm dist-tag. `subagentRuntime` is `null` (same as the mission agent) or `{ provider, model, effort: string \| null }` for missions without a project; an invalid value returns `400`. `allowSubagents` is the app-wide "Allow sub-agents" setting for missions without a project. It must be a boolean (otherwise `400` and nothing is written), and a change refreshes the policy of open sessions |
 | `GET` | `/budget` | App-wide budget config |
-| `PATCH` | `/budget` | Update the app-wide daily budget |
+| `PATCH` | `/budget` | Update the app-wide budgets: `{ desktopDailyBudgetUsd?, desktopWeeklyBudgetUsd?, desktopMonthlyBudgetUsd?, runCapUsd?, costAlertThresholdUsd? }` (`null` clears, a number > 0 sets; a bad weekly / monthly / run value is `400 { error: 'invalid_cap', field }`). `GET /budget` reports the same fields |
+| `GET` | `/budget/caps` | Budget panel read model, app-wide: `{ generatedAt, spend: { day, week, month }, projection, config, caps }`. `spend.<period>` is `{ startsAt, resetsAt, usd, estimatedUsd, byProvider: [{ provider, usd, estimatedUsd, invocations, turns }] }` over the LOCAL period (week starts Monday); `projection` is `{ estimate: true, trailingDays, avgDailyUsd, monthToDateUsd, remainingDays, projectedUsd }` or `null` without a completed day of history; `config` is `{ day, week, month, run }`; `caps` lists the configured app-wide caps `{ scope, period, budgetUsd, spentUsd, exhausted, resetsAt }` |
 | `GET` | `/theme` | Current UI theme (defaults to `specrails`) |
 | `PATCH` | `/theme` | Set UI theme. Body `{ theme }`; one of `dracula`, `aurora-light`, `obsidian-dark`, `matrix`, `specrails`. 400 on an unknown value |
 | `GET` | `/language` | Current UI language; `{ language: null }` when the user never chose one (the client then follows the OS language) |
@@ -113,6 +142,33 @@ Example — register a project that uses both Claude and Gemini:
 | `GET` | `/analytics?period=&from=&to=` | Cross-project aggregated spending (the Desktop Analytics page; supports a custom `from`/`to` range) |
 | `GET` | `/recent-jobs?limit=` | Recent jobs across all projects (1–50) |
 
+### Failure diagnosis
+
+A run that ended `failed`, `blocked` or `stalled` carries one typed record explaining why. It is persisted in `loop_runs.failure_diagnosis` when the run settles (migration 84) and served read-only by:
+
+- `GET /api/projects/:projectId/jobs/:id` as `job.failureDiagnosis`;
+- `GET /api/projects/:projectId/loop-runs/:id` as `loopRun.failureDiagnosis` (a delivery card reads its last run's);
+- `GET /api/inbox` as `diagnosis` on failed / blocked items.
+
+Shape: `{ kind, confidence, phase, rounds, resetAt, detail, resumablePhase, blocker, source, remedies }`.
+`kind` is `tests_failed`, `provider_limit`, `environment`, `blocked`, `timeout`, `tool_inactivity`, `crash` or `unknown`; `confidence` is `high` or `low` (a low-confidence record is always `unknown`); `source` is `core` (the classification of Core contract 5.8) or `desktop` (derived from the loop's stall reason, the provider-limit signal, Core's fixed blocker sentences or `completion.blocker`); `remedies` are ranked ids from `resume`, `retry`, `edit-spec`, `fix-environment`, `open-logs`. A run finished before the column existed reads as `unknown`/low, and a successful run has none. Module: [`server/modules/recovery`](../../server/modules/recovery/README.md).
+
+### Needs-you inbox (app-wide)
+
+| Method | Path | Notes |
+|--------|------|-------|
+| `GET` | `/inbox` | Read-only projection of what waits for the person, across every registered project: `{ items, projects, generatedAt }`. Each item: `id` (`<projectId>:<kind>:<sourceId>`), `projectId`, `projectName`, `kind` (`review` \| `question` \| `failed` \| `blocked` \| `budget` \| `jira`), `title`, `detail`, `at`, `version` (changes when the state changes), `action` (`open-review` \| `open-run` \| `resume-run` \| `retry-jira` \| `raise-cap`), `subjectId` (delivery id, loop-run id, Jira outbox id, or `<scope>:<period>` for a cap), `conversationId`, `diagnosis` (a failed / blocked run's [failure diagnosis](#failure-diagnosis), else `null`; a provider limit or environment problem is listed as `blocked`), and — only on a reached spend cap (`kind: 'budget'`, `action: 'raise-cap'`, id `<projectId>:budget:cap-<scope>-<period>`) — `cap: { scope, period, budgetUsd, spentUsd, resetsAt }`. A delivery or run item also carries `railIndex` (when known) and a delivery item its `decision` (the state a remote PR decision must echo back). An app-wide cap is listed once, under the first project. Newest first, at most 50 per project. Each project is read through its own database and a failing project is skipped; nothing is cached or stored. Snooze and Done are per viewer and never reach the server. Module: [`server/modules/inbox`](../../server/modules/inbox/README.md). |
+
+### Sample project (first run)
+
+| Method | Path | Notes |
+|--------|------|-------|
+| `GET` | `/onboarding/sample` | `{ catalog: [{ id, name, specCount }], sample, defaultParentDir, launch }`. `sample` is the created sample (`{ sampleId, projectId, path, specIds }`) or `null`; a record whose project was removed by hand is dropped. `launch` is the pre-validated first-run configuration: `{ ready: true, preset, localPreset, estimate: { minutes: [3, 5], usd: [0.3, 1] }, runCapUsd }` or `{ ready: false, reason: 'no_provider' \| 'not_signed_in', estimate, runCapUsd }`. `preset` is `{ provider, model, local, loopId: 'factory:sdd-quick-openspec', runCapUsd }`: the cheapest priced model of the cheapest ready cloud provider with the per-run soft cap, or a configured local engine (no cap). `localPreset` is the local alternative when both exist. The estimate is a static, labelled envelope, never a quote. `?refresh=1` re-probes the providers first; a failing probe is "not ready", never an error. |
+| `POST` | `/onboarding/sample` | Body `{ sampleId?, locale?, path?, parentDir? }`. Copies the bundled tic-tac-toe repository, runs `git init -b main` plus one commit, installs the three specs (title, summary and description in `locale`, English as fallback) and registers the project (broadcasting `desktop.project_added`, with the usual silent workspace assembly). `201 { reused: false, project, sample }`; a second call returns `200 { reused: true, ... }` and writes nothing. The folder must be strictly inside the home directory (`400 outside_home`); an explicit `path` must not exist (`409 path_exists`); without `path` the first free `<parentDir>/<name>[-N]` is used (default parent `~/Specrails Samples`). `404 unknown_sample`, `500 git_failed` / `write_failed` / `register_failed` (everything created is removed). |
+| `DELETE` | `/onboarding/sample` | `?deleteFolder=1` (or body `{ deleteFolder: true }`) also deletes the folder, only when it is the recorded path, strictly inside home and still a git repository (`409 unsafe_delete` otherwise; the project is not unregistered then). Returns `{ ok, removedProject, deletedFolder }`; `404 not_found` when there is no sample. Module: [`server/modules/onboarding`](../../server/modules/onboarding/README.md). |
+
+The first run itself is the ordinary rail launch: the client assigns the first sample spec to a free rail (`PUT /rails/:n/tickets`) and calls `POST /rails/:n/launch` with `{ loopId, aiEngine, model, runCapUsd }` from the preset.
+
 ### Mobile Gateway admin (`/api/mobile/*`)
 
 Loopback-only admin surface for the Mobile Gateway (the gateway itself is a separate HTTPS listener that tunnels the web companion's RPC over WebRTC). The wire contract the phone consumes intentionally keeps the legacy `hub.*` names — see the frozen mobile wire-compat note in `CLAUDE.md`.
@@ -127,32 +183,35 @@ Loopback-only admin surface for the Mobile Gateway (the gateway itself is a sepa
 | `GET` | `/devices` | List paired devices |
 | `DELETE` | `/devices/:id` | Revoke a paired device |
 | `POST` | `/cert/rotate` | Rotate the gateway TLS identity (unpairs every device) |
-| `GET` | `/previews` | Live Companion app previews (`{ previews: [{ projectId, projectName, sessionId, deviceId, deviceName, url, title, createdAt }] }`) |
-| `DELETE` | `/previews/:projectId/:sessionId` | End a device-owned preview from Desktop (`{ ok }`; Desktop sessions are never affected) |
-
-Revoking a device also ends its previews. The app-level WS event `mobile.previews_changed` (no `projectId`) tells Settings ▸ Mobile to refetch the list.
-
-#### Companion app preview (gateway `/v1`)
 
-A paired Companion views a project's locally served web app through a device-owned server-side browser session. The routes require the mission grant (all-projects device) and the `appPreview` capability (`GET /v1/capabilities` → `features.appPreview`, true when browser capture is enabled).
+### Companion inbox decisions (`/v1/inbox*`, paired devices only)
 
-| Method | Path | Notes |
-|--------|------|-------|
-| `GET` | `/v1/projects/:pid/missions/:cid/preview-targets` | `{ targets: [{ processId, urls }] }`: local URLs announced in the logs of the mission's running background processes |
-| `POST` | `/v1/projects/:pid/preview-sessions` | Body `{ missionId, processId, url, viewport? }`; `url` must be announced by that process. `201 { sessionId, channel, url }` |
-| `POST` | `/v1/projects/:pid/preview-sessions/:sid/attach` | Re-attach after a reconnect: `{ sessionId, channel }` (a new DataChannel replaces the old one) |
-| `POST` | `/v1/projects/:pid/preview-sessions/:sid/navigate` | Body `{ action: goto\|back\|forward\|reload, url? }`; `goto` accepts only paths on announced origins |
-| `DELETE` | `/v1/projects/:pid/preview-sessions/:sid` | End the device's own preview |
+The paired companion reads the [Needs-you inbox](#needs-you-inbox-app-wide) and runs a closed set of safe decisions through the Mobile Gateway (`/v1`, device bearer token, same project grant as every other `/v1` route). Each action is forwarded to the route the desktop UI itself uses, addressed to one project, and tier-checked with the MCP permission tiers (Settings ▸ MCP): a tier that is off answers `403 { error: "tier_disabled", tier, action }` and nothing is forwarded. See [companion inbox decisions](companion-inbox-decisions.md).
 
-Errors carry `{ error, code }`. Codes: `preview_unavailable` (404), `preview_target_gone` (404), `preview_session_closed` (404), `preview_url_not_announced` (400), `preview_limit` (429), `preview_requires_webrtc` (409), `preview_failed` (502). Sessions owned by Desktop or by another device are reported as `preview_session_closed`.
+| Method | Path | Tier | Forwards to |
+|--------|------|------|-------------|
+| `GET` | `/v1/inbox` | none (read) | `GET /api/inbox`, narrowed to the device's granted projects; each item gains `companion: { actions: [{ id, tier, enabled }], runId?, sourceId?, railIndex?, expectedDecision? }` |
+| `GET` | `/v1/projects/:pid/inbox/runs/:runId/question` | none (read) | `GET /agent-runtime/runs/:runId`; answers `{ pending, question?, requestedAt? }` |
+| `POST` | `/v1/projects/:pid/inbox/answer` | `write` | body `{ runId, answer }` (1-20000 chars) -> `POST /loop-runs/:runId/resume { answer, interruptId }` (workflow runs) or `POST /agent-runtime/runs/:runId/resume { answer }`; `409 no_pending_question` when nothing waits |
+| `POST` | `/v1/projects/:pid/inbox/resume` | `ai-spawn` | body `{ runId, runCap?: "ignore" \| runCapUsd?: number }` -> `POST /loop-runs/:runId/resume`; the budget `409` body is passed through so the phone can offer Continue / Raise |
+| `POST` | `/v1/projects/:pid/inbox/retry` | `ai-spawn` | body `{ sourceId, railIndex }` (`sourceId` is a delivery id or `run:<id>`) -> `POST /rails/:railIndex/relaunch { sourceId }` |
+| `POST` | `/v1/projects/:pid/inbox/create-pr` | `destructive` (pushes a branch) | body `{ prDeliveryId, expectedDecision: "on_review" }` -> `POST /rails/pr-decision { action: "create-pr" }`; the answer is narrowed to `{ ok, decision, prUrl, prState, detail }` |
+| any | `/v1/projects/:pid/inbox/<anything else>` | n/a | `403 action_not_allowed_for_companion` (merge, discard, publish, force-push, settings, delete stay on Desktop) |
 
-**Channel.** `channel` is the label of an ordered, reliable DataChannel (`preview:<sessionId>`) that Desktop opens on the device's existing WebRTC peer without renegotiation:
+WebSocket: a device subscribed to the `inbox` topic receives a bare `{ type: "inbox.changed", projectId, reason }` when `rail.pr_state`, `rail.job_completed`, `rail.job_stopped`, `job.stuck`, `jira.outbox_changed` or `loop.run_paused|resumed|stopped|completed` fires for a project it may see; the phone re-reads `GET /v1/inbox`.
 
-- **Desktop → Companion, text:** JSON control: `ready` (`{ id, url, title, viewport }`), `nav`, `popup`, `closed` (`{ reason }`) and `nav_rejected`.
-- **Desktop → Companion, binary:** JPEG screencast frames in fragments of at most 16 000 bytes. Each fragment starts with an 8-byte big-endian header `u32 frameSeq | u16 index | u16 count`. Render a frame only when all of its fragments have arrived. A newer `frameSeq` discards an incomplete older frame.
-- **Companion → Desktop:** JSON `{ type: 'input', event }` (mouse / wheel / key / resize, validated) and `{ type: 'navigate', action, url? }`, rate-limited to 6 000 messages per minute.
+### Mission app addresses
 
-**Origin policy.** A device session may load a loopback origin only while a running background process of the project announces it. Every other request passes the regular server-side SSRF guard. Device sessions have their own budget: one per device (opening a new one replaces it) and two per project. They never count against Desktop's four sessions.
+A running mission background process (`GET /api/projects/:id/background-processes`,
+its `/:pid/logs` snapshot, the Companion's `/v1/projects/:pid/missions/:cid/processes`
+proxy and every `background_process.*` WS event) carries
+`appUrls: { local: string[], network: string[] }` once its output announces an
+address. `local` opens on the Desktop computer; `network` holds private LAN/VPN
+addresses (RFC 1918, `100.64/10`, `*.local`, or this machine's addresses for a
+`0.0.0.0` bind) that a phone on the same Wi-Fi opens in its own browser. The
+field is derived from the retained logs on read, never persisted, and absent
+once the process stops. A new or changed address is announced as a
+`background_process.updated` event; log lines themselves are not broadcast.
 
 ### specrails-tech proxy
 
@@ -182,6 +241,9 @@ These routes are available when a mission ran in a Core agent session (`SPECRAIL
 | Method | Path | Notes |
 |--------|------|-------|
 | `GET` | `/agent/active-turns` | Reconnect snapshot. Besides `turns`, the response includes `sessions[]`: `{ conversationId, residentPhase, processAlive, liveSubagents, subagents }` for missions with background work. |
+| `DELETE` | `/agent/conversations/:id` | Soft delete: stops the live turn, closes the Core session and hides the mission (`deleted_at`); `{ ok, restorable: true }`. `?permanent=1` removes the row, history and attachments for good (`404` unknown id). Deleted missions are `404` on `GET /agent/conversations/:id` and `/send`, and absent from the list, search and mobile listings |
+| `GET` | `/agent/conversations/trash?projectId=` | Deleted missions pinned to the project (all when omitted), newest deletion first: `{ items: [{ conversation, deletedAt, purgeAt }], retentionDays: 30 }`. Purges missions deleted more than 30 days ago first |
+| `POST` | `/agent/conversations/:id/restore` | Undo a delete; idempotent. `{ ok, conversation }`, `404` when the mission no longer exists |
 | `GET` | `/agent/conversations/:id` | Includes `session`: `{ residentPhase, processAlive, liveSubagents, subagents }`, or `null` when the mission never ran in Core. |
 | `GET` | `/agent/conversations/:id/subagents` | `{ subagents, session }`. Each sub-agent has id, parent, kind, agent type, description, phase (`running`/`idle`/`failed`/`stopped`/`killed`/`interrupted`), reason, restarts, launching Core turn, timestamps, usage, tool uses, duration and result summary. Sub-agents Specrails launched on another provider carry `delegated: { driver, model }`; their usage is recorded as separate `subagent` invocations. |
 | `GET` | `/agent/conversations/:id/subagents/:subagentId/events?after=&limit=` | Paged sub-agent transcript `{ events: [{ seq, channel, delta?, tool?, createdAt }], hasMore }`. `limit` is 1–1000. |
@@ -204,6 +266,8 @@ Background turns also stream `agent_stream`, `agent_tool` and `agent_tool_result
 
 `agent_error` may carry `code` and `provider` for failures the client explains in the user's language. One example is `policy_unenforceable`, sent when a provider cannot honour "Allow sub-agents: off".
 
+Flow mode: `POST /agent/conversations/:id/send` also accepts `deliveryMode: 'interrupt'`, only while the conversation's Flow is active (`409 interrupt_requires_flow` otherwise). In a Flow every mid-turn input reaches Core as `session.send { delivery: 'interrupt' }`, which cuts the running turn and runs the input next; the reply continues the same user turn. A Flow turn on a host without `flowSessions` fails with `agent_error` code `flow_sessions_unavailable` (there is no legacy Flow transport). Flow turns are recorded in `agent_invocations` with `surface: 'flow'`.
+
 ### Webhooks
 
 | Method | Path | Notes |
@@ -249,8 +313,10 @@ Example — queue a command on a specific provider:
 | `GET` | `/issues` | GitHub issues linked to the project |
 | `GET` | `/jobs` | Job list (`?limit=&offset=&status=`) |
 | `GET` | `/jobs/export` | CSV/JSON export |
+| `GET` | `/jobs/:runId/audit` | Agent actions of one run (job id or loop run id) as an attachment. `?format=jsonl` (default) or `csv`. Pending batched rows are flushed first; at most 100 000 rows, oldest first; `X-Agent-Actions-Rows` carries the count. `400` invalid format. See [agent actions audit](agent-actions-audit.md) |
+| `GET` | `/agent-actions` | Project-wide agent actions export. `?format=jsonl\|csv&from=&to=` (ISO timestamps, inclusive). `400` for an invalid format, an unparsable timestamp or `from` after `to` |
 | `GET` | `/jobs/compare` | Compare metrics between two jobs |
-| `GET` | `/jobs/:id` | One job. Returns `{ job, events, phaseDefinitions }`; `job` is annotated with `hasTelemetry`, `tickets[]` (resolved from the command, powers the ticket header), `interactiveSettleMode` (`'finalize'` \| `'auto'` \| `null`) and `interactiveAcceptingTurns` (whether a resident session accepts turns right now — a between-steps loop run reports `'auto'`/`false` so the composer can phrase the waiting state) |
+| `GET` | `/jobs/:id` | One job. Returns `{ job, events, phaseDefinitions }`; `job` is annotated with `hasTelemetry`, `tickets[]` (resolved from the command, powers the ticket header), `interactiveSettleMode` (`'finalize'` \| `'auto'` \| `null`) and `interactiveAcceptingTurns` (whether a resident session accepts turns right now — a between-steps loop run reports `'auto'`/`false` so the composer can phrase the waiting state) and `failureDiagnosis` (`null`, or why a failed / stalled / blocked job stopped: see [failure diagnosis](#failure-diagnosis)) |
 | `DELETE` | `/jobs/:id` | Cancel a running or queued job |
 | `DELETE` | `/jobs` | Purge completed jobs (optional `{ from, to }` window) |
 | `PATCH` | `/jobs/:id/priority` | Re-rank a queued job |
@@ -307,6 +373,9 @@ Spending is tracked across six surfaces: `job`, `quick-spec`, `explore-spec`, `a
 | `GET` | `/invocations` | Paginated raw `ai_invocations` rows |
 | `GET` | `/tickets/:id/spending-summary` | Per-ticket cross-surface aggregate (powers `TicketSpendingLine`) |
 | `GET` | `/analytics/export?format=csv\|json&mode=summary\|raw&…` | Multi-section summary CSV/JSON, or raw rows (10 000 cap) |
+| `GET` | `/analytics/decision-times?period=7d\|30d\|90d\|all\|custom&from&to` | Time to decision / merge per delivery: `{ period, from, to, project, byLoop[] }`, each group `{ deliveries, toDecision, toMerge }` with `{ measured, pending, unknown, medianMs, p90Ms }`. Window = `on_review_at` (or `created_at` for legacy rows). `medianMs`/`p90Ms` are `null` when nothing is measurable; unknown is never zero. Repository children are excluded (counted via the group parent). 400 on an invalid period or a custom period without `from`/`to` |
+| `GET` | `/analytics/loop-economics?period=7d\|30d\|90d\|all\|custom&from&to` | Loop economics: `{ period, from, to, sources: { escapedDefects: tracked\|untracked, requirementsDemonstrated: measured\|unavailable, triageAccuracy: unavailable }, project, byLoop[] }`. Each group: `{ hasData, delivered, merged, discarded, superseded, onReview, discardRate, cost: { pricedDeliveries, unpricedDeliveries, incompleteDeliveries, totalUsd, authoritativeUsd, estimatedUsd, avgCostUsd, estimatedShare }, decisionTimes, rounds: { measuredDeliveries, reviewRounds, fixerRounds, reviewPerDelivery, fixerPerDelivery }, escapedDefects, requirementsDemonstrated, triageAccuracy }`; loops add `loopId`, `loopName`. Delivered = parent delivery that reached `on_review` or beyond. Unknown values are `null`, never 0; published saved loops without deliveries appear with `hasData: false`. `escapedDefects` counts tickets whose `metadata.regressionOf` names a delivery in the window (null while no ticket carries a link). `requirementsDemonstrated` is `{ demonstrated, total, deliveries }` summed over the spec traces (Core `specTrace`) in the settle evidence of delivered deliveries, `null` when none carries one. Same period validation as decision-times |
+| `GET` | `/analytics/loop-economics/deliveries?limit=50` | Recent delivered parent deliveries `{ deliveries: [{ id, loopId, loopName, decision, ticketIds, createdAt }] }` (max 200) — source of the ticket "Regression of" picker |
 
 Example — the Analytics dashboard payload (abridged):
 
@@ -328,8 +397,28 @@ provides no authoritative token/USD envelope, so those values remain null.
 
 | Method | Path | Notes |
 |--------|------|-------|
-| `GET` | `/budget` | Daily cap + per-job alert |
-| `PATCH` | `/budget` | Update |
+| `GET` | `/budget` | Daily / weekly / monthly caps, per-run soft cap and per-job alert: `{ dailyBudgetUsd, weeklyBudgetUsd, monthlyBudgetUsd, runCapUsd, jobCostThresholdUsd, costToday, … }` |
+| `PATCH` | `/budget` | Update `{ dailyBudgetUsd?, weeklyBudgetUsd?, monthlyBudgetUsd?, runCapUsd?, jobCostThresholdUsd? }`. `null` clears; a number > 0 sets; a bad weekly / monthly / run value is `400 { error: 'invalid_cap', field }`. All caps are enforced by the same gate (below) |
+| `GET` | `/budget/caps` | Budget panel read model: `{ generatedAt, spend, projection, config, appConfig, caps }` — see the app-wide `GET /api/budget/caps` for the shapes. `caps` holds every configured cap of this project AND the app-wide ones with the spend the gate counts; `spend.<period>.byProvider` carries `turns` so a subscription provider can show turns instead of dollars. The projection is an estimate (average of the last 14 completed local days × days left in the month + month to date, integer cents), never a billed figure |
+| `GET` | `/budget/what-if?from=<provider:model>&to=<provider:model>&days=30` | What-if pricing over recorded usage. Without `from`/`to`: `{ days, sources, targets, result: null }` (`sources` = models seen in the window with `{ invocations, recordedUsd, priced }`, `targets` = every model the local rate card prices). With both: `result` re-prices each invocation's recorded tokens on both models (`estimateCurrentUsd`, `estimateWhatIfUsd`, `deltaUsd = whatIf − current`, all estimates) and reports `repriced` / `skipped` invocations and `recordedUsd` apart. A model without a rate card yields `noPricing: { side, provider, model }` and null estimates, never a guess. `400 invalid_model_ref` on a malformed ref. Usage is recorded per model, not per profile role |
+| `GET` | `/run-duration-range?loopId=\|command=` | Measured p25/median/p75 of this project's settled runs of a loop or job-command shape (`{ range, minSamples }`); `range` is `null` below 5 samples. Feeds the job story's "Runs like this have taken…" |
+| `GET` | `/launch-forecast?loopId=\|command=&provider=` | Read-only launch forecast: `{ time, cost, minSamples, budget }`. Same samples as `run-duration-range`, narrowed to `provider`. `time` is `{ p25Ms, medianMs, p75Ms, sampleCount }`. `cost` is `{ lowUsd, highUsd, sampleCount }` (cents), built **only** from provider-reported costs (estimated costs and runs without a cost are excluded) and is an estimate, never a billed figure. Each is `null` below the 5-sample floor (render "Not enough history yet"). `factory:implement`/`factory:batch`/`factory:freestyle` read the `/specrails:implement`/`/specrails:freestyle` jobs; any other loop id reads `loop_runs`. `budget` is the tightest configured cap (daily, weekly or monthly; project or app-wide) `{ scope, period?, budgetUsd, spentUsd, exhausted, resetsAt }` (the same figures the launch gate enforces; `period` is absent for the daily budget) or `null`. `400` without `loopId`/`command` or on a malformed `provider` |
+
+### Scoped search (⌘K)
+
+The command palette's scopes. Missions (`@`) stay on `GET /api/agents/search`, files (`f:`) on `GET /code/find`
+and docs (`?`) on `GET /api/docs/search`; these two are project-scoped and read only that project's data.
+
+| Method | Path | Notes |
+|--------|------|-------|
+| `GET` | `/search/specs` | `?q=` (required, single line, at most 200 characters, `400` otherwise), `?limit=` (default 8, max 30). Folded (case- and diacritics-insensitive) substring scan of the ticket store: title, short summary, description, labels, non-goals, addenda and comments, so it is never behind the file Core also writes. `#12`/`12` also matches by id. Live Flow placeholders are skipped. Returns `{ results: [{ id, title, status, priority, field, snippet }] }`, best field first (`field`: `id` \| `title` \| `summary` \| `label` \| `description` \| `nonGoal` \| `addendum` \| `comment`), then newest. `snippet` is `{ text, ranges: [[start, end], ...] }` (plain text plus character ranges to mark; never HTML) or `null` |
+| `GET` | `/search/jobs` | Same `q`/`limit` rules. FTS5 trigram search (`bm25`, one row per job; queries under 3 characters use a bounded `LIKE` scan) over the job-log index of this project's database (migration 86, `server/db/job-search.ts`): job command, loop name, phase titles and the failure diagnosis kind/detail/host-blocker text. It never indexes events or token streams. Returns `{ results: [{ jobId, command, status, startedAt, field, snippet }] }` (`field`: `command` \| `loop` \| `phase` \| `failure` \| `detail`). `jobId` is also the loop-run id, so the client opens `/jobs/:jobId` |
+
+The job-log index (`job_search_docs` + external-content `job_search_fts`) is derived data kept current at job create,
+phase events and settle (`finishJob`, loop-run settle), cleaned on delete/purge, and bounded: 300 characters per
+document, 30 phase documents per job, 30,000 documents per project (the oldest tenth is dropped when over). Migration 86
+creates it and runs the same idempotent backfill (`rebuildJobSearchIndex`, newest 5,000 jobs). An indexing failure never
+fails the write that triggered it.
 
 ### Tickets
 
@@ -337,14 +426,18 @@ provides no authoritative token/USD envelope, so those values remain null.
 |--------|------|-------|
 | `GET` | `/tickets` | Filters: `?status=`, `?label=`, `?q=` |
 | `GET` | `/tickets/:id` | One ticket |
-| `POST` | `/tickets` | Create |
-| `PATCH` | `/tickets/:id` | Update any subset of fields |
-| `DELETE` | `/tickets/:id` | Delete (cascades the draft conversation if it is the last reference) |
+| `POST` | `/tickets` | Create. Optional `nonGoals: string[]` ("Out of scope"; `400 nonGoals must be an array of strings` otherwise) |
+| `PATCH` | `/tickets/:id` | Update any subset of fields. `metadata` merges keys; `metadata.regressionOf` (delivery id string ≤ 200 chars, escaped-defect link) is validated on create/update/commit-draft (400 otherwise) and `null` removes it. `nonGoals` (string array; `[]` or `null` removes the field) is cleaned (list markers, blanks, duplicates; at most 20 items of 300 characters) and never written back to Jira |
+| `DELETE` | `/tickets/:id` | Soft delete: the spec moves to the trash sidecar `<store>.trash.json` (hidden from every list, search and Core read; `{ ok, revision, restorable: true }`, `404` unknown id, repeat deletes are idempotent). A deleted epic orphans its children. Attachments, the Explore draft conversation and the Jira link are kept until the entry is purged or deleted permanently. Broadcasts `ticket_deleted` |
+| `GET` | `/tickets/trash` | Recently deleted specs, newest deletion first: `{ items: [{ ticket, deletedAt, purgeAt }], retentionDays: 30 }`. Purges entries older than 30 days first |
+| `POST` | `/tickets/:id/restore` | Undo a delete: the spec returns under the same id (and re-adopts the children it orphaned). Idempotent (`alreadyLive: true`), `404` when it is in neither the board nor the trash. Broadcasts `ticket_created` |
+| `DELETE` | `/tickets/trash/:id` | Delete permanently: removes the entry plus the cascade a hard delete used to run (attachments, the draft's orphan Explore conversation). `404` when not in the trash |
 | `POST` | `/tickets/generate-spec` | Quick-mode generation. Body `{ idea, model?, contractRefine?, aiEngine?, attachmentIds?, pendingSpecId?, contextScope? }` (the spec text is `idea`, not `title`). Streams progress over WS |
 | `POST` | `/tickets/save-as-draft` | Persist an Explore conversation as a draft (idempotent on `conversationId`) |
-| `POST` | `/tickets/from-draft` | Commit a draft (flip-in-place) or insert a new ticket |
+| `POST` | `/tickets/from-draft` | Commit a draft (flip-in-place) or insert a new ticket. An explicit `nonGoals` list wins; otherwise a `## Out of Scope` section of the description moves into `nonGoals` |
 | `POST` | `/tickets/from-prompt` | Create a ticket directly from a prompt |
 | `POST` | `/tickets/:id/contract-refine` | Retry Contract Refine for an existing ticket. `202` scheduled, `404` unknown ticket, `409` when the effective provider cannot enforce the required tool policy (`contract_refine_unsupported_for_<provider>`; this includes Kimi), the kill switch is active (`feature_disabled_by_env`), or the ticket has no origin conversation. Kimi is rejected before spawn or mutation |
+| `POST` | `/tickets/:id/triage` | Recalculate the [spec triage](spec-triage.md) (forced, even when the inputs hash is unchanged). `200 { triage }` with the stored `metadata.triage` record (`ready`, `unavailable` or `failed`), `400` invalid id, `404` unknown ticket, `409 { error: 'triage_not_applicable', reason }` for a cancelled spec, an epic or a Flow-held spec, `503 triage_unavailable` when the project has no triage service. The record is also broadcast as `ticket_updated` |
 | `POST` | `/tickets/:id/smash` | SMASH an epic into sub-specs |
 | `POST` | `/tickets/:id/smash/undo` | Undo a SMASH operation |
 | `DELETE` | `/tickets/:id/children` | Delete all children of an epic |
@@ -355,6 +448,8 @@ provides no authoritative token/USD envelope, so those values remain null.
 | `GET` | `/tickets/:ticketId/attachments/:attachmentId` | Download one |
 | `DELETE` | `/tickets/:ticketId/attachments/:attachmentId` | Delete one |
 | `DELETE` | `/tickets/:ticketId/attachments` | Delete all |
+| `GET` | `/tickets/:ticketId/timeline` | The spec's lifecycle, a read-model over existing stores (no store of its own). Query: `?kinds=spec_edit,addendum,mission_turn,job,phase,audit,pr_event,review` (comma list, `400` for an unknown kind), `?limit=` (1-200, default 50), `?cursor=` (opaque, from `nextCursor`; `400` when malformed). Returns `{ ticketId, entries, nextCursor, counts, total }`, newest first; `counts` are per kind over the whole timeline so filter chips keep counting. An entry is `{ id, at, kind, event, params, title, summary, actor, tone: neutral\|ok\|failure\|review, provider, costUsd?, costKind?: billed\|estimated, costEstimatedUsd?, turns?, link, url?, count?, items? }`: `event`/`params` are a stable code the client localizes, `title` is the source text (or an English fallback), `link` is `{ place: spec\|mission\|job\|review, id }` for the client to turn into a place URL, `count`/`items` describe a collapsed group (phases per job, agent actions per job, mission turns per conversation). `costKind: estimated` means part of `costUsd` came from the pricing table; a run the provider reported no cost for carries no `costUsd`. Free text is passed through `redactProse`. `400` invalid id, `404` unknown ticket |
+| `GET` | `/tickets/:ticketId/handoff` | The hand-off export: `?format=md\|html\|pr` (default `md`; `pr` is the concise Markdown PR description), `?locale=` (UI language, any of the 8; headings follow it, unknown falls back to `en`), `?planProviders=claude,codex` (providers billed through a plan: shown as turns, never dollars). Returns `{ format, filename, contentType, body, redactions, locale }`. Sections: summary, request, decisions (addenda, clarifications, reviewer verdicts), changes (delivery diff stats from the review packet's Changes read model), verification, cost (billed and estimated apart), open follow-ups (open addenda, unresolved findings). Every string and the finished document go through `redactProse`; `redactions` counts the changed strings. `400` invalid format or id, `404` unknown ticket |
 
 ### Chat / Explore
 
@@ -364,7 +459,7 @@ provides no authoritative token/USD envelope, so those values remain null.
 | `POST` | `/chat/conversations` | Create. Body `{ kind?, model?, aiEngine? (alias provider), contextScope? }`. `contextScope` is only allowed for `kind=explore` |
 | `GET` | `/chat/conversations/:id` | One conversation (with messages) |
 | `PATCH` | `/chat/conversations/:id` | Update metadata (title, contextScope, etc.) |
-| `DELETE` | `/chat/conversations/:id` | Delete (clears `origin_conversation_id` on linked draft tickets) |
+| `DELETE` | `/chat/conversations/:id` | Delete (clears `origin_conversation_id` on linked draft tickets). Sidebar/Explore chats keep their hard delete; the soft delete applies to specs and agent missions |
 | `GET` | `/chat/conversations/:id/messages` | List messages |
 | `POST` | `/chat/conversations/:id/messages` | Send a turn; streams over WS |
 | `DELETE` | `/chat/conversations/:id/messages/stream` | Cancel an in-progress turn |
@@ -372,20 +467,20 @@ provides no authoritative token/USD envelope, so those values remain null.
 | `POST` | `/chat/conversations/:id/minimize` | Park the session (arms the idle-kill timer) |
 | `POST` | `/chat/conversations/:id/restore` | Cancel the idle-kill timer |
 
-### Setup wizard
+### Setup (API / MCP only)
 
-The setup wizard is a three-step flow (Configure / Install / Done). The `enrich/*` and `setup/start`+`setup/message` endpoints back the legacy AI-enriched flow that the app UI does not expose; they remain mounted for forward compatibility.
+The app UI has no setup wizard: adding a project assembles its workspace in the background (see `POST /api/projects` and `POST /api/projects/:id/assemble-retry`). These per-project routes remain mounted for the MCP `specrails_setup` tool and other API callers. The `enrich/*` and `setup/start`+`setup/message` endpoints back the legacy AI-enriched flow.
 
 | Method | Path | Notes |
 |--------|------|-------|
 | `POST` | `/setup/install-config` | Write `.specrails/install-config.yaml` to the project |
-| `POST` | `/setup/install` | Run `npx specrails-core init --from-config <file>` (the pinned core release — currently `specrails-core@^4.12.0` — is resolved by SetupManager, overridable via `SPECRAILS_CORE_BIN`) |
+| `POST` | `/setup/install` | Run `npx specrails-core init --from-config <file>` (the pinned Core range `CORE_PACKAGE_SPEC` from `server/core-package.ts` — currently `specrails-core@^6.0.0` — is resolved by SetupManager, overridable via `SPECRAILS_CORE_BIN`) |
 | `POST` | `/setup/start` | Legacy setup-chat session start |
 | `POST` | `/setup/message` | Legacy setup-chat turn |
 | `POST` | `/enrich/start` | Legacy AI-enrich session start |
 | `POST` | `/enrich/message` | Legacy AI-enrich turn |
 | `GET` | `/setup/checkpoints` | Checkpoint state + last log lines |
-| `POST` | `/setup/abort` | Abort the wizard |
+| `POST` | `/setup/abort` | Abort the in-progress install |
 
 ### Proposals
 
@@ -460,8 +555,12 @@ Gated by `requireBrowserCaptureEnabled` — returns 404 when the feature is disa
 
 | Method | Path | Notes |
 |--------|------|-------|
-| `GET` | `/settings` | Project settings, including `allowSubagents` (default `false`) and `subagentRuntime` (default `null`) |
-| `PATCH` | `/settings` | Update. `allowSubagents` must be a boolean; `subagentRuntime` is `null` or `{ provider, model, effort: string \| null }` (strictly validated). A change to either refreshes the sub-agent policy of the project's open agent sessions. A change to `worktreeEnvPassthrough` (names only) re-warms the project's login-shell recovery |
+| `GET` | `/settings` | Project settings, including `allowSubagents` (default `true`), `subagentRuntime` (default `null`), `reviewerFamilySuggestionDismissed` (default `false`), `reviewWipLimit` (default `null` = no limit), `agentAuditRetentionDays` (default `30`), `jiraPostClarifications` (default `false`) and `baselineOnTouch` (default `false`) |
+| `PATCH` | `/settings` | Update. `reviewWipLimit` is an integer from 1 to 100 or `null` (otherwise `400` and nothing is written). `allowSubagents` must be a boolean; `subagentRuntime` is `null` or `{ provider, model, effort: string \| null }` (strictly validated); `reviewerFamilySuggestionDismissed` must be a boolean. A change to either refreshes the sub-agent policy of the project's open agent sessions. A change to `worktreeEnvPassthrough` (names only) re-warms the project's login-shell recovery. `agentAuditRetentionDays` must be an integer between 1 and 3650. `jiraPostClarifications` and `baselineOnTouch` must be booleans (see [existing-project anchoring](existing-project-anchoring.md)) |
+| `GET` | `/core/phase3-capabilities` | `{ architectClarifications, specTrace, baselineOnTouch, rulesInventory }` booleans from the active Core's `runtime api` (all `false` when Core is unavailable). The settings UI gates each switch on its flag |
+| `GET` | `/rules` | Project rules inventory (`.specrails/rules.json`, workspace first, then the repository): `{ supported, running, state: 'missing' }`, `{ ..., state: 'invalid', file, message }` or `{ ..., state: 'ok', file, modifiedAt, inventory: { generatedAt, gates, rules[{ id, index, text, source, status: enforcedBy\|automatable\|humanOnly\|unclassified, enforcedBy, proposedCheck }], counts, classification, dropped } }`. `supported` is Core `rulesInventory: 1`; `running` covers the automatic run after setup too; `lastRun: { trigger: setup\|manual, ok, exitCode, output, at }` (absent until a run in this app session) |
+| `POST` | `/rules/inventory` | Re-run Core's inventory (`specrails-core rules inventory --root <repo> [--artifact-root <dir>]`). `200 { ok: true, exitCode, output, ...read }`, `502` when the command failed (same body with `ok: false`), `409 rules_inventory_unsupported` without the capability, `409 rules_inventory_running` while one runs for the project |
+| `POST` | `/rules/specs` | Body `{ id }` (Core rule id) or `{ index }`: turn an `automatable` rule into a spec (source `rules`, labels `rules`, `automation`, with non-goals). `201 { ticket }`, `400` invalid index or `rule_not_automatable`, `404 rules_missing` / `rule_not_found`, `409 rules_inventory_unsupported` |
 | `GET` | `/env-passthrough/status` | Value-free resolution status of every configured `worktreeEnvPassthrough` name: `{ loginShellRecovery, timeoutMs, checking, names: [{ name, status, shell, checkedAt, exitCode }] }`. `status` is `inherited`, `recovered`, `not-defined`, `probe-timeout`, `probe-failed`, or `pending` for a name never checked. Probes first only when a missing name has no valid cached result. Never returns values |
 | `POST` | `/env-passthrough/recheck` | Probe the login shell now (asynchronously, `SPECRAILS_LOGIN_SHELL_TIMEOUT_MS`, default 10 s), then return the same payload as the status route |
 | `GET` | `/terminal-settings` | Per-project terminal overrides |
@@ -492,18 +591,59 @@ A non-developer-friendly file tree + Monaco viewer with plain-language AI summar
 
 ---
 
+## `/api/projects/:projectId/flow/*`
+
+Flow mode ([guide](flow-mode.md)): build with an agent in an isolated worktree,
+then hand the worktree to a rail. Thin routes over the
+[Flow module](../../server/modules/flow/README.md). Every response carries the
+Flow as `{ id, conversationId, ticketId, state, branch, worktreePath, baseSha,
+headSha, coreSessionId, railIndex, deliveryId, step, createdAt, updatedAt }`;
+`state` is `active` / `paused` / `handed_off` / `delivered` / `discarded` /
+`needs-review` and `step` names an unfinished saga step (`start:*`, `handoff:*`).
+
+| Method | Path | Notes |
+|--------|------|-------|
+| `GET` | `/flow/availability` | `{ available, reason, missing[] }`. Available only when Core sessions are usable and Core advertises `flowSessions` and `deriveChange`. |
+| `POST` | `/flow` | Start. Body `{ conversationId, idea, title?, flowId?, repositoryId?, ticketId? }`. With `ticketId` the Flow starts from that EXISTING spec (idea optional): no placeholder; the spec is labelled In Flow and seeds the first turn; `400 invalid_ticket_id` / `spec_not_found`, `409 spec_closed` / `spec_in_flow` / `spec_on_rail` / `spec_running` before anything is written. The mission must be pinned to this project and its provider must have a Core session driver on a host with `flowSessions`. Creates the placeholder spec, reserves the worktree and returns `201 { flow }`. Idempotent by `flowId`. `409 flow_already_open` (with `flowId`) when the conversation has an open Flow; `409 feature_unavailable` (with `missing`) without the capabilities; `409 repository_has_no_commits` when the repository has an unborn HEAD (nothing is created; the placeholder spec is removed; the client offers `POST /api/projects/:projectId/git/initial-commit`, which runs only `git commit --allow-empty -m "Initial commit"` in the primary repository against an empty scratch index (zero files, nothing staged) and answers `201 { sha, repositoryId }`, `409 repository_has_commits`, `409 git_identity_missing` or `409 repository_is_not_git`); `400 conversation_not_pinned` / `idea_required` (without `ticketId`). |
+| `GET` | `/flow/by-conversation/:conversationId` | `{ flow }`: the open Flow, else the latest one, else `null`. |
+| `GET` | `/flow/open` | `{ flows: [{ id, conversationId, state, branch }] }`: the project's conversations in Flow mode (active, paused, needing review) — the mission list's "In Flow" mark. No worktree paths. |
+| `GET` | `/flow/:flowId` | `{ flow }`; `404 flow_not_found`. |
+| `POST` | `/flow/:flowId/pause` | Closes the Flow's Core session (a running Flow turn is stopped); worktree and spec stay. Idempotent. |
+| `POST` | `/flow/:flowId/resume` | Reopens the session lazily on the next turn. `409 flow_worktree_missing` when the worktree disappeared. Idempotent. |
+| `POST` | `/flow/:flowId/discard` | Closes the session, removes the Flow worktree and branch and deletes the placeholder spec. `409 illegal_transition` after a hand-off and for a `needs-review` Flow. Idempotent. |
+| `POST` | `/flow/:flowId/close` | Ends a `needs-review` Flow WITHOUT deleting anything: branch, any surviving worktree and the spec stay; the Flow becomes `closed` (terminal; `discarded` means the worktree and branch were removed), the spec's `metadata.flow.state` becomes `closed` (no "In Flow" label) and the history gets a `left/closed` boundary. `409 illegal_transition` from any other open state. Idempotent. |
+| `POST` | `/flow/:flowId/hand-off` | Body `{ railIndex, loopId?, aiEngine?, model?, reasoning_effort? }`; `loopId` defaults to `factory:flow-spec` (never the rail's default loop). Commits the worktree (HEAD frozen), closes the session, assigns the Flow spec to a free rail and launches it with `flowId`. Returns `202 { flow, loopRunIds, deliveryId }`. A refused launch keeps its status and code (`409 rail_not_empty`, `409 flow_worktree_mismatch`, `409 pr_decision_pending`…) and the Flow returns to `paused`. |
+| `POST` | `/flow/by-delivery/:deliveryId/return` | Back to Flow: the Flow → Spec delivery stopped with requested changes (`implementation_failed` / `review_changes_requested`) gives its adopted worktree back. One delivery-owned transaction removes the `rail_worktrees` row, closes the delivery as `discarded` / `returned_to_flow` and sets the Flow `paused` with the review as its next-turn briefing; then the session reopens (`active`, or `paused` when it cannot open). Returns `{ flow }`. Idempotent by delivery. `404 flow_not_found`; `409 flow_return_not_allowed`, `flow_return_busy`, `flow_return_worktree_mismatch`, `flow_worktree_missing`. |
+| `POST` | `/flow/by-delivery/:deliveryId/relaunch` | The same return, then the ordinary hand-off on the stopped delivery's rail and engine choices: Flow → Spec runs again on the same worktree and re-derives the existing change. Returns `202 { flow, loopRunIds, deliveryId }`; refusals as for `return` and `hand-off`. |
+| `GET` | `/flow/:flowId/diff` | `{ branch, baseSha, headSha, files: [{ path, status, additions, deletions }], totals: { files, additions, deletions } }` — working tree against the Flow base, overlay and `node_modules` excluded. Empty once the Flow is no longer open. |
+| `GET` | `/flow/:flowId/cost` | `{ flowId, costUsd, turns, unpricedTurns, tokensIn, tokensOut }` — provider-billed cost of the Flow's turns only; turns without billed cost are counted in `unpricedTurns`, never estimated. |
+
+WebSocket: `flow.state` `{ projectId, conversationId, flowId, flow, timestamp }`
+on every committed state change (project-scoped).
+
+The launched `factory:flow-spec` loop exists only on a Core with `deriveChange: 1`
+(`409 engine_unsupported` otherwise; `400 flow_id_required` without `flowId`).
+When its delivery reaches review the Flow settles: spec rewrite, Jira create and
+review transition as durable effects ([settlement](flow-mode.md#settlement)). The
+delivery's review packet carries `derivation` and `flowSettlement`.
+
+---
+
 ## `/api/projects/:projectId/rails/*`
 
 | Method | Path | Notes |
 |--------|------|-------|
-| `GET` | `/` | List rails |
+| `GET` | `/` | List rails. Also returns `reviewWip { limit, pending: [{ deliveryId, railIndex, ticketIds, decision, since }], reached }` (the review WIP limit and the deliveries that count against it) |
 | `PUT` | `/:railIndex/tickets` | Assign tickets to a rail. Body `{ ticketIds: number[], mode?, profileName?, aiEngine? }`. An omitted `mode` keeps the rail's stored mode; `mode` must be `implement` / `freestyle` / `loop` (400 otherwise), with `batch-implement` / `batch` normalized to `implement`. |
 | `PUT` | `/:railIndex/profile` | Set the rail's default profile |
 | `PUT` | `/:railIndex/engine` | Set the rail's AI engine override. Body `{ aiEngine }` (string — one of the project's providers — or `null` to clear) |
 | `PUT` | `/:railIndex/name` | Set the rail's display name. Body `{ name }` (string or `null` to clear back to the default label); 400 if longer than 60 characters |
-| `POST` | `/:railIndex/launch` | Launch the rail. Body `{ mode?, loopId?, profileName?, aiEngine?, model?, reasoning_effort?, originConversationId?, originSurface?, interactive? }`. `mode` is `implement` / `freestyle` / `loop` (the removed Batch mode's `batch-implement` / `batch` are accepted as input aliases and normalized to `implement`); a factory `loopId` maps to its canonical rail mode (`factory:batch` resolves to `factory:implement`). `model` and `reasoning_effort` are validated against the effective adapter/model (Kimi effort is K3-only). Kimi + a loop containing a Decider returns a capability error before the first step. Claude alone advertises persistent in-job stdin; `interactive` remains wire-compatible. Returns `202 { jobId, railIndex, mode }`; a missing provider CLI fails before a job starts. |
+| `POST` | `/:railIndex/launch` | Launch the rail. Body `{ mode?, loopId?, profileName?, aiEngine?, model?, reasoning_effort?, originConversationId?, originSurface?, interactive?, flowId? }`. `flowId` (sent by the Flow hand-off, never by the dashboard) adopts that Flow's frozen worktree: the rail must carry exactly the Flow spec (`409 flow_rail_mismatch`), the Flow must be waiting for the launch (`409 flow_handoff_not_ready`), the launch must be isolated (`409 flow_requires_isolation`), relaunch/revision/target PR/follow-up/base options are refused (`400 flow_handoff_incompatible`) and a mount/branch/HEAD discrepancy returns `409 flow_worktree_mismatch`. `loopId: 'factory:flow-spec'` without `flowId` returns `400 flow_id_required`. `runCapUsd` (a number > 0 caps this run's provider-reported cost: it pauses and asks through the budget gate; `0` waives the default; absent keeps the project/app default) is accepted on a fresh launch and stored with the run. `mode` is `implement` / `freestyle` / `loop` (the removed Batch mode's `batch-implement` / `batch` are accepted as input aliases and normalized to `implement`); a factory `loopId` maps to its canonical rail mode (`factory:batch` resolves to `factory:implement`). `model` and `reasoning_effort` are validated against the effective adapter/model (Kimi effort is K3-only). Kimi + a loop containing a Decider returns a capability error before the first step. Claude alone advertises persistent in-job stdin; `interactive` remains wire-compatible. Returns `202 { jobId, railIndex, mode }`; a missing provider CLI fails before a job starts. While the project or app-wide daily budget is exhausted, this route and `/relaunch` return `409 { error: 'daily_budget_exceeded', scope, period?, budgetUsd, spentUsd, resetsAt, detail, action }` and spawn nothing (`period` is `week` / `month` for the longer caps and absent for the daily budget, so the body predating caps is unchanged). `POST /loop-runs` and `POST /loop-runs/:id/resume` return the same body. Resume also continues a `budget_paused` run in place; a run paused at its per-run soft cap answers `409` with `period: 'run'` (`resetsAt: null`) until the resume body carries the person's choice: `{ runCap: 'ignore' }` (continue without the cap) or `{ runCapUsd: n }` (raise it; it must end above what the run spent). `POST /loop-runs` also accepts `runCapUsd` (a number > 0 caps that run, `0` waives the default). When the project's `reviewWipLimit` is reached and the launch would open a new delivery, this route and `/relaunch` return `409 { error: 'review_wip_limit_reached', limit, pending: [{ deliveryId, railIndex, ticketIds, since }], detail, action }` and spawn nothing. Continuations of an existing delivery (`revisionOfDeliveryId`, Relaunch of a recorded delivery, `targetPrNumber`, `followUp`, or a rail that still owns an active delivery) are exempt.A repository that must be worktree-isolated (e.g. a multi-repository launch) but has no commits yet returns `409 { error: 'repository_has_no_commits', detail }` before any delivery row, branch or worktree exists; a single-repository launch without commits keeps the shared-checkout fallback (`isolationUnavailable: 'no-commits'`). |
 | `POST` | `/:railIndex/stop` | Stop the rail's running job (cancels every job the rail registered) |
 | `POST` | `/:railIndex/relaunch` | Relaunch a settled source. Body `{ sourceId: deliveryId or 'run:<runId>', originConversationId?, originSurface? }`. Uses its recorded specs and admitted options, restores empty assignments after preflight and atomically replaces an undelivered failed generation. Returns the same `202` launch response. Reused/removed rails, active/stale sources, missing specs/workflow and delivered work needing recovery return actionable errors. Request-side workflow overrides are ignored. |
+| `GET` | `/pr-deliveries/:id/packet[?repositoryId=]` | The plain-language [review packet](review-packet.md) with the pre-resolved Accept ladder. 404 when `SPECRAILS_REVIEW_PACKET=false`. |
+| `GET` | `/pr-deliveries/:id/changes[?repositoryId=&source=]` | Changes tab list (read-only). `{ prDeliveryId, repositoryId, changes }`; `changes` is `{ available: true, source, sources: [{ id: 'delivery' \| 'ticket:<id>', ticketId, branch }], base, head, baseSha, headSha, root, rootKind: 'worktree' \| 'repository', files: [{ path, oldPath, status: added\|modified\|deleted\|renamed\|copied\|typechange, additions, deletions, binary, hash }], truncated, totals, annotations }` or `{ available: false, reason: not_a_repository\|no_branch\|head_missing\|base_missing\|git_failed, sources, annotations }`. The comparison is the delivery head (settled sha, else the branch) against its merge-base with the base branch. `source` picks one unit's branch when there is no assembled branch (`400` on a malformed value). At most 2000 files (`truncated`). `hash` changes whenever the file's diff does (viewed-mark invalidation). `annotations` are reviewer findings (anchored when Core contract 5.9 named a location), review-brief risks and untested files, and follow-up comments; `location` is `null` when the source named no place. |
+| `GET` | `/pr-deliveries/:id/changes/file?path=&full=1[&repositoryId=&source=]` | One file's parsed diff: `{ prDeliveryId, diff: { path, oldPath, status, binary, hunks: [{ header, oldStart, oldLines, newStart, newLines, lines: [{ type: context\|add\|delete, oldNo, newNo, text, noNewline? }] }], truncated, totalLines } }`. Capped at 4000 lines unless `full=1` (60,000). `path` must be a path of the listing (`404 file_not_in_changes`, `400` without it); it is never passed to git as a free pathspec. `409` with the unavailable `reason` when the comparison cannot be made. |
 
 ---
 
@@ -624,8 +764,11 @@ The bundled documentation portal (served by `docs-router`, loopback-only — mou
 | Method | Path | Notes |
 |--------|------|-------|
 | `GET` | `/` | List categories. Top-level `.md` files → a synthetic `guides` category; each subdirectory becomes its own category |
+| `GET` | `/search?q=&lang=` | Search page titles and headings (levels 2–4) in one language, English fallback per page. `{ results: [{ category, categoryName, slug, title, heading, anchor }] }`, titles first, at most 8; `heading`/`anchor` are null on a title match, `anchor` is null for a heading without an explicit anchor. Empty `[]` for a query that is blank or longer than 80 chars |
 | `GET` | `/:category/:slug` | Fetch one document (`{ title, content, category, slug }`) |
 
+Headings may carry an explicit, locale-independent anchor, `## Title {#anchor}`. The server removes it from page titles; the client renders it as the heading id (`doc-<anchor>`) and never shows it. In-app "Learn more" hints address a section by `category/slug#anchor` (see [`client/src/features/README.md`](../../client/src/features/README.md#contextual-help-learn-more)).
+
 Source resolution: `~/.specrails/docs/` (user-editable) wins if present; otherwise the bundled `docs/` from the install.
 
 ---
@@ -670,8 +813,8 @@ Every project-scoped message includes a `projectId` field. App-level messages ha
 | Type | Scope | Notes |
 |------|-------|-------|
 | `cost_alert` | project | Job exceeded the per-job alert threshold |
-| `daily_budget_exceeded` | project | Project daily budget hit; queue paused |
-| `desktop_daily_budget_exceeded` | app | App-wide daily budget hit |
+| `daily_budget_exceeded` | project | Project budget hit; queue paused. Carries `period: 'week' \| 'month'` for the weekly / monthly cap (absent = daily) |
+| `desktop_daily_budget_exceeded` | app | App-wide budget hit (same optional `period`) |
 | `spending.invalidated` | project | Analytics cache should refetch (no payload) |
 
 ### Tickets, specs & drafts
@@ -745,7 +888,9 @@ Every project-scoped message includes a `projectId` field. App-level messages ha
 | `jira.outbox_changed` | project | The durable write-back outbox changed (op enqueued/drained/dead-lettered) |
 | `jira.degraded` | project | A write-back op was dead-lettered or a path is blocked; sync continues |
 
-### Setup wizard
+### Setup (API / MCP install flow)
+
+Emitted by the legacy per-project `/setup/*` install flow (MCP `specrails_setup`). Background workspace assembly after `POST /api/projects` reports through the app-level `project.assemble_progress` event instead.
 
 | Type | Scope | Notes |
 |------|-------|-------|