specrails-desktop 2.64.2 → 2.65.1

package/docs/internals/spec-addenda.md

@@ -195,6 +195,16 @@ continue the existing generation.
   user wants it kept, an explicit addendum).
 - Jira mirroring of addenda (a comment per addendum) — deliberately not done;
   addenda are local guidance for the run, not tracker content.
+- Importing Jira comment threads in general. **One case is implemented**
+  (feedback-2026-10 task 3.2): with the project setting
+  `jiraPostClarifications`, Desktop posts the architect's clarifications
+  (questions a run paused on, or the assumptions it proceeded with) as a
+  comment on the linked issue, and a human reply posted **after that comment**
+  is imported once as an addendum of kind `clarification` (`created_by:
+  'jira'`, title `Answer from Jira <KEY> (<author>)` or `Correction from …`).
+  Specrails' own comments and every other thread are ignored; replies are read
+  for 14 days after the comment. See
+  [existing-project anchoring](existing-project-anchoring.md#architect-clarifications-on-jira).
 
 ## Quick SDD scope and efficiency
 

package/docs/internals/spec-triage.md

@@ -0,0 +1,140 @@
+# Spec triage
+
+Every spec gets a cheap triage that estimates its size and recommends the loop
+to run it on. The rail header preselects that loop, and each launch records the
+recommended and the chosen loop so loop economics can measure how often the
+triage was right. OpenSpec change: `launch-triage`.
+
+Code: the pure rules are in
+[`server/modules/specs/domain/triage.ts`](../../server/modules/specs/domain/triage.ts).
+The effects are in
+[`runtime/triage.ts`](../../server/modules/specs/runtime/triage.ts), and the
+provider call is in
+[`runtime/triage-runner.ts`](../../server/modules/specs/runtime/triage-runner.ts).
+
+## Record
+
+The record lives in `ticket.metadata.triage`. It uses ticket store schema 1.5,
+the same version Flow uses. Core ignores it.
+
+```json
+{
+  "status": "ready",
+  "size": "S",
+  "filesLikely": ["server/modules/delivery/runtime/rails-router.ts"],
+  "publicInterfaces": false,
+  "dataModel": false,
+  "securitySurface": false,
+  "recommendedLoop": "factory:sdd-quick-openspec",
+  "recommendedLoopName": "SDD Quick (OpenSpec)",
+  "rationale": "Single file, no schema or API change",
+  "confidence": "high",
+  "inputsHash": "sha256:…",
+  "model": "claude-haiku-5-5",
+  "costUsd": 0.0031,
+  "computedAt": "2026-10-22T10:12:00.000Z"
+}
+```
+
+- `recommendedLoop` is always one of the loops offered to the triage. These are
+  the rail built-ins the primary engine can run (Implement, Freestyle when the
+  provider supports it, and SDD Quick when Loops are enabled), plus published
+  spec-driven custom loops.
+- Flow is not a loop, and Flow and Implement never compete: the triage
+  recommends a loop and a size for Implement only and never ranks Flow against
+  Implement. Since prompt version 2 the model is not asked for a mode, a stray
+  `recommendedMode` in its answer is ignored, and Flow availability is not an
+  input. Records written by version 1 may still carry `recommendedMode`; it
+  stays readable for compatibility, and no surface shows it.
+- `costUsd` is the cost the provider reported, or the priced cost. It is `null`
+  when the cost is unknown.
+- When no usable model exists, the record is
+  `{ status: 'unavailable', reason, inputsHash, computedAt }`. Nothing is
+  spawned and no values are invented.
+- An answer that cannot be repaired is stored as
+  `{ status: 'failed', error, model, costUsd, … }`, with its real cost.
+
+## Inputs and hash
+
+The deterministic inputs come first:
+
+- The bounded spec text: title, description, labels, priority and repository
+  scope.
+- The repository map: packages, ecosystems, size buckets and the README excerpt.
+- Up to 30 files touched by the 5 most similar specs, taken from
+  `file_provenance`. Similarity is Jaccard over title tokens and labels.
+- The offered loops.
+- The resolved `provider:model` and the prompt version.
+
+The inputs are serialised as sorted-key JSON and hashed with sha256. Status,
+timestamps and the stored triage are not inputs, so a status change or the
+triage write itself never invalidates the hash. An automatic trigger skips a
+spec whose stored `inputsHash` matches. Recalculate always runs.
+
+## Engine and cost
+
+The `triage` role engine in `loop-role-engines.json` wins when it names a
+detected provider. People choose it in project settings ▸ Agent runtime ▸
+**Spec triage engine** (`TriageEngineSection`: provider tabs with "Primary
+provider", and a model whose default is the cheapest one; saved on change,
+reverted with a toast when the server refuses, other stored roles kept). Otherwise the triage uses the project's primary provider
+and its cheapest priced catalog model, weighted by input price. See
+[configuration](configuration.md#spec-triage-and-role-engines). Each run is one
+pure-output turn with no tools and a 90-second timeout. It is recorded in
+`ai_invocations` with surface `triage` and the spec's id, and the analytics
+surfaces label it "Triage".
+
+## Output parsing
+
+The model must answer with one JSON object. The parser repairs what it can:
+
+- It strips code fences and takes the first balanced object.
+- It normalises the size and confidence spelling.
+- It reads `"yes"` and `"no"` as booleans.
+- It drops absolute paths and paths that climb out with `..`.
+- It bounds the rationale.
+
+An unknown loop falls back to a size rule, XS or S ⇒ SDD Quick when offered,
+else Implement, and the confidence drops to `low`. With no JSON object or an
+invalid size, the triage is stored as `failed`.
+
+## Triggers
+
+`SpecTriageService` (one per project) taps the project broadcast. Every
+`ticket_created` or `ticket_updated` message schedules one scan after a 2-second
+debounce. The scan compares a content signature per spec with the one it saw
+before, and queues the `draft` and `todo` specs that are new or changed. The
+signatures are seeded when the project opens, so the existing backlog is not
+triaged in bulk. Those specs show a hover-only **Triage** action on their card
+instead. Triages run one at a time per project.
+
+Cancelled specs, epics and Flow-held specs are never triaged. The kill switch
+`SPECRAILS_SPEC_TRIAGE=false` stops the automatic triggers.
+
+## UI
+
+- **Spec card chip:** shows size · recommended loop · confidence. The tooltip
+  shows the rationale, the impact flags, the likely files, the model and cost,
+  and **Recalculate** (`POST /tickets/:id/triage`). It never shows a mode: no
+  "Flow suggested" hint, because Flow and Implement never compete.
+- **Rail header:** when the rail has no explicit loop and is on its default mode,
+  it preselects the recommended loop of its first triaged spec. This happens
+  only if the picker offers that loop, and the option is marked "recommended".
+  Any explicit choice wins. The launch uses the same rule.
+- **Mission rail-launch card:** shows the structured triage per spec instead of
+  the agent's prose rationale whenever the specs carry one.
+
+## Delivery recording and accuracy
+
+The launch route reads the ticket store on the server, so the measurement does
+not trust the client. It records two columns on the isolated delivery row
+(migration 76):
+
+- `recommended_loop`: the recommendation of the first triaged spec in rail
+  order.
+- `chosen_loop`: the launched canonical loop id.
+
+`getTriageAccuracy(db, { since? })` in
+[`rail-pr-store.ts`](../../server/modules/delivery/runtime/rail-pr-store.ts)
+returns `{ total, matched, rate }`. It counts root deliveries that carried a
+recommendation. Launches without an isolated delivery are not counted.

package/docs/internals/visual-design-audit.md

@@ -77,7 +77,7 @@ Prereq (fix #1): `npm i tw-animate-css` + `@import "tw-animate-css";` in `global
 | Job success | `CheckCircle2` | accent-success |
 | Job failed | `XCircle` | destructive |
 | Job canceled | `Ban` | muted-foreground |
-| App agent (chat/mode) | `Bot` | accent-primary |
+| App agent (chat/mode) | `RailMark` (brand glyph, `components/brand`) | accent-primary |
 | Pipeline agents/profiles | `BrainCircuit` | accent-primary |
 | MCP | `Plug` | accent-info |
 | AI generate/magic | `Sparkles` | accent-primary (one tint) |
@@ -91,7 +91,7 @@ Prereq (fix #1): `npm i tw-animate-css` + `@import "tw-animate-css";` in `global
 | Send | `Send w-3.5` | — |
 | Provider | `Cpu` (kill the `🤖⚡✨` emoji) | neutral |
 
-**Regression guards (CI grep-deny, extends the existing `dracula-*` guard):** `aurora-light:` outside globals.css · `#50fa7b|#ff5555|#f1fa8c|#6272a4|#44475a|rgba\(139,233|rgba\(189,147` · `text-white` on `bg-accent`/`bg-emerald`/`bg-green` lines · `hsl\(var\(--` · `border-border/(10|20|25|70)` · `shadow-black/` · `text-\[9px\]` · bare `rounded[" ]` (post-codemod).
+**Regression guards (CI grep-deny, extends the existing `dracula-*` guard):** `aurora-light:` outside globals.css · `#50fa7b|#ff5555|#f1fa8c|#6272a4|#44475a|rgba\(139,233|rgba\(189,147` · `text-white` on `bg-accent`/`bg-emerald`/`bg-green` lines · `hsl\(var\(--` · `border-border/(10|20|25|70)` · `shadow-black/` · `text-\[9px\]` · `text-\[(11|12)px\]` (use `text-caption` / `text-label`) · bare `rounded[" ]` (post-codemod).
 
 ---
 
@@ -144,6 +144,19 @@ Deferred to a dedicated bulk change (mechanical but broad): the remaining ~40-fi
 
 # PART 3 — RAILS REDESIGN PROPOSAL
 
+## 1.7 Premium tokens (Signal box at night)
+Defined once in `client/src/globals.css` `@theme`; every theme block may override the ones marked per-theme. Components adopt them in later batches; nothing here changes a component by itself.
+| Role | Tokens / utilities | Notes |
+|---|---|---|
+| Type scale | `text-micro` 10.5 · `text-caption` 11 · `text-label` 12 · `text-body` 13 · `text-strong` 14 · `text-title` 16 · `text-headline` 20 (page H1) · `text-display` 28 · `text-display-xl` 40 | Each carries line-height, weight and tracking sub-keys. `font-display` inherits; code-rain sets mono. |
+| Numerals | `num` utility | `tabular-nums slashed-zero`; use for every cost, token, duration and count. |
+| Radius roles | `rounded-control` 6 · `rounded-card` 10 · `rounded-panel` 14 · `rounded-pill` | Per-theme: code-rain sharp (2/3/4), aurora-light panel 12. |
+| Elevation | `shadow-1` card · `shadow-2` raised (menus, composer) · `shadow-3` overlay | Built from `--shadow-color`, `--shadow-color-strong`, `--edge-highlight` (per theme; aurora-light has no edge light). |
+| Motion | `--ease-out/in/rail`, `--duration-instant/fast/base/slow/peak` (100/150/200/300/640 ms) | Rail travel is the one authored motion: `animate-rail-travel`, `animate-rail-arrive` (static under reduced motion). |
+| Rail gradient end | `--color-rail-end` | Defaults to `accent-secondary`; galaxy uses its gold highlight. |
+| Native surfaces | `color-scheme` | Set per theme (`light` only for aurora-light) so date inputs, selects and scrollbars follow the theme. |
+Obsidian Dark is retuned as graphite: neutral hue 220, saturation at most 8%, one desaturated violet primary. `themes.ts` `OBSIDIAN_PALETTE` mirrors it for terminal and charts.
+
 ## 3.1 Diagnosis (one sentence)
 A single idle rail exposes **13 controls, six of them 10px native `<select>`s explained only by icon+`title`**, the primary action is the smallest target on the card (20px), a running rail is a **black box** (all config unmounts → layout jump; no loop/engine/model/phase shown), failure is **invisible after a 4s toast** (`RailStatus 'failed'` is dead code), and rail identity is three disagreeing coordinate systems (id-number vs array-index vs server-index) sitting on a localStorage/server split-brain.
 

package/docs/local-providers.md

@@ -119,6 +119,8 @@ You do not have to run everything on one model. Each role can have its own engin
 | Verifier (verify / fix and any custom loop ai-step) | the loop | Settings ▸ Specrails Agents ▸ **Loop roles** |
 | Decider (the Loop Decider) | the loop | same |
 
+When more than one provider is usable and the reviewer would run on the developer's provider, the loop editor suggests moving the reviewer to another model family (Claude ↔ Codex first). Apply it or dismiss it; nothing changes on its own.
+
 A sensible split for a local setup: **architect on a cloud model** (judgement and planning), **developer on the local coder** (volume), **fixer on a stronger model** (repairs are few and precise — this is where a cloud model pays off most), **reviewer on a cloud model**, **verifier local**, **decider on the cheapest fast model you have**.
 
 The correction loop is verification ⇄ fixer: the host runs your test command, a failure goes to the fixer with the exact output and the offending lines already read, and only a green verification reaches the reviewer. A rejected review also goes to the fixer.
@@ -159,6 +161,7 @@ rail to a new model.
 | Resume by session id | ✅ |
 | Read-only / no-tools boundaries (Explore, deciders) | ✅ native runner policies |
 | MCP servers in missions | ✅ (`--mcp-config`, tools as `mcp__<server>__<tool>`) |
+| Read-only missions | ✅ runner read-only tools, MCP tools kept |
 | Agent profiles / custom roles / Agent Studio AI | ❌ |
 | SMASH, Contract Layer, Project Builder generation | ❌ (need structured-action guarantees) |
 | Native cost | ❌ — unknown unless you set rates |

package/docs/mcp.md

@@ -49,9 +49,9 @@ reading one description. The tools are:
 | `specrails_code` | File discovery, literal content search, bounded line reads, summaries and provenance; AI summary regeneration is capability-gated |
 | `specrails_git` | Repository/branch/worktree information, status, diffs and PR lookup |
 | `specrails_env` | Project environment readiness and environment-file management; `get`/`status`/`recheck` report each configured name's value-free resolution status |
-| `specrails_support` | Support triage, local diagnostics and specrails-core update workflows |
-| `specrails_setup` | Add-project setup wizard surface |
-| `specrails_analytics` | Per-project spending analytics + budget |
+| `specrails_support` | Support triage, local diagnostics, specrails-core update workflows (following the app update channel) and `api_meta` (API, app, Core and contract versions) |
+| `specrails_setup` | Add-project and per-project install surface (prerequisites, add, install-config, install, checkpoints, abort) |
+| `specrails_analytics` | Per-project spending analytics + budget, decision times, loop economics (`loop_economics`) |
 | `specrails_settings` | App-level settings |
 | `specrails_watch` | Await the real result of an async (cost-incurring) action |
 | `specrails_guide` | Returns the platform guide — read this first |
@@ -117,6 +117,17 @@ failure and act only on the user's confirmation:
 | `runtime_dismiss` | write | Dismiss a runtime continuation card |
 | `runtime_cancel` | destructive | Cancel an active runtime continuation |
 
+## Agent actions audit
+
+`specrails_jobs(audit)` (read tier) returns what the agents of a run read,
+wrote, executed, called over MCP or fetched: pass `jobId` for one run, or omit
+it and pass `from`/`to` for a project-wide window. `format` is `jsonl`
+(default) or `csv`; the result carries `rows` and the export text in `data`.
+Reads are only as complete as each provider's stream. Every tool call made by
+an in-app mission agent in a pinned project is itself recorded as an `mcp` row
+(`tool:action`, never its arguments). See
+[agent actions audit](internals/agent-actions-audit.md).
+
 `specrails_rails(list)` rails carry `availability` — `free`, `busy` (active job
 or loop run), `pending_decision` (an undecided PR delivery) or `on_review` (a
 spec parked on review). Inside the app's own agent chat, a launch proposal is a
@@ -238,6 +249,13 @@ one.)
   short-lived capability bound server-side to that conversation, pinned project,
   and permission level, transports it through an app-owned `0600` file, and
   revokes it when the turn ends.
+- **Mission agents are read-only.** In the app's own agent chat, the AI CLI
+  starts with its native read-only boundary. Claude gets no file-writing or
+  shell tools, Codex runs in its read-only sandbox, Gemini runs in plan mode, and
+  local engines use the runner's read-only tools. Changes reach your projects
+  only through these MCP tools and the rails they launch. Kimi has no native
+  read-only mode, so Kimi missions keep their previous permissions. MCP servers
+  you add yourself keep their own behaviour.
 - **The app must be running.** The MCP server is embedded in the desktop app's
   process — there is no standalone daemon. The Tauri shell keeps it alive even
   when you close the main window: closing the window **minimizes to the system

package/docs/platforms/macos.md

@@ -40,7 +40,7 @@ You only need this once per build. It does not apply to the notarized installers
 
 ## Prerequisites
 
-When you add a project, the app checks for the tools it needs and surfaces them in a **prerequisites panel** (in the `Add Project` dialog and the setup wizard). It checks:
+When you add a project, the app checks for the tools it needs and surfaces them in a **prerequisites panel** in the `Add Project` dialog. It checks:
 
 - **Bundled tools** — `node`, `npm`, `npx`, `git`.
 

package/docs/platforms/windows.md

@@ -63,11 +63,11 @@ Updates use the signed NSIS `-setup.exe` for the same architecture. Installation
 
 Normal quit and updates request an authenticated graceful shutdown of the owned sidecar first, giving processes and persistent logs time to close before a bounded force-stop fallback.
 
-## Setup wizard
+## Project setup
 
 Adding a project assembles the framework from the bundled or newer compatible activated core. The installed app includes the Node-native core and OpenSpec resources, so normal project setup does not require a separate core installation. Core updates preserve the previous active framework if switching the Windows junction fails.
 
-Online fallback uses the range in `server/core-package.ts` (currently `specrails-core@^5.0.0`). Runtime selection and the activated version are shared with the Settings view so a restart cannot silently downgrade a newer working core. `SPECRAILS_CORE_BIN` remains available for a deliberately selected local core executable. Legacy pre-4.1 bash/Python installers are not used for Windows setup.
+Online fallback uses the range in `server/core-package.ts` (currently `specrails-core@^6.0.0`). Runtime selection and the activated version are shared with the Settings view so a restart cannot silently downgrade a newer working core. `SPECRAILS_CORE_BIN` remains available for a deliberately selected local core executable. Legacy pre-4.1 bash/Python installers are not used for Windows setup.
 
 Reserved paths (`.specrails/profiles/**`, `.claude/agents/custom-*.md`) are preserved across re-runs per the contract documented in [specrails-core's README](https://github.com/fjpulidop/specrails-core#reserved-paths).
 

package/docs/running-pipelines.md

@@ -16,12 +16,12 @@ SpecsBoard (left)            Rails (right)
                                      ▶ Play
 
                      Each rail runs Architect → Developer → Reviewer → Ship
-                     in your project directory.
+                     in its own git worktree, in parallel.
 ```
 
 A **rail** is an execution lane. Drag a spec card from the SpecsBoard onto a rail and press **▶ Play** to launch the pipeline. Rails let you organise and queue work into named lanes.
 
-> **One job at a time per project.** Each project has a single queue, so within a project only one rail job runs at a time; the rest queue behind it. Real parallelism is **across projects** — open two projects and their rails run independently. See [Running multiple rails](#running-multiple-rails).
+> **Rails run in parallel.** With Loops enabled (the default), every rail launch is its own loop run, and repo-mutating runs each get an isolated git worktree, so several rails in the same project run at the same time without touching your checkout. Only the legacy job queue (used when Loops are disabled) runs one job at a time per project. See [Running multiple rails](#running-multiple-rails).
 
 ## Rails
 
@@ -104,16 +104,32 @@ autonomously with native tools.
 
 - **One job per spec.** If the rail has three specs, `Freestyle` launches three independent jobs.
 - **Variable cost.** Because the run is open-ended, pressing Play opens a confirmation dialog before anything spawns.
-- **Capability-gated.** Claude advertise Freestyle. Codex
-  do not. Agent profiles do not apply to Freestyle rails.
+- **Every CLI provider.** Claude, Codex, Gemini, Kimi and local engines
+  advertise Freestyle (each verified by a real end-to-end run). Only Claude
+  adds the interactive in-job chat with **Finalize**; on the others each run is
+  non-interactive and settles through verification and the Loop Decider.
+  Agent profiles do not apply to Freestyle rails.
 
 You can customise the Freestyle pre-prompt per project on the [Settings page](customizing.md#freestyle-pre-prompt).
 
 ### Running multiple rails
 
-Within a single project, jobs are **serialised** — the project runs one rail job at a time and queues the rest. Adding more rails organises your work into lanes, but it doesn't make them run concurrently inside that project.
+Rails in the same project run **concurrently**. Each launch with Loops enabled (the default) becomes an independent loop run, and a run that can modify the repository works in its own git worktree under `~/.specrails/`, then delivers its branch as a draft PR (or merges back locally when PR delivery is off). Two guards keep parallel rails safe:
 
-True parallelism is **across projects**: each project has its own queue, so rails in different projects run at the same time without contending. There is no global concurrency limit to configure — the only automatic throttle is budget-based (see [Stopping everything](#stopping-everything)).
+- **No double-booked specs.** A launch whose spec is already being worked by an active run on another rail is refused (`tickets_in_flight`), so two rails never write to the same spec's branch.
+- **Shared-checkout fallback.** If isolation is unavailable for fresh work (a non-git folder, a repository with no commits yet), the run uses your checkout directly. Setting `SPECRAILS_RAIL_WORKTREES=0` forces that legacy shared-checkout behaviour.
+
+The legacy **job queue** is still serial: when Loops are disabled (`SPECRAILS_LOOPS_SECTION=false`), each project runs one queued job at a time and the rest wait behind it. Projects never contend with each other either way. There is no global concurrency limit to configure; the only automatic throttle is budget-based (see [Stopping everything](#stopping-everything)).
+
+### Review limit
+
+Parallel rails can finish work faster than you can review it. To cap that, set **Project settings ▸ Review limit** (we suggest 5; empty means no limit). Every delivery that is running, waiting for your decision, or open as a PR created by the app counts toward it.
+
+- The rails header shows **In review 3/5**. Click it to see which rails and specs are waiting and since when.
+- At the limit, **▶ Play** is disabled on rails that would start a new delivery. Hover it to see why. Decide a delivery (Create PR, merge or discard) and the next launch goes through.
+- **Launch all** starts only as many rails as there are free slots, in board order, and its dialog tells you how many wait. With no free slot it launches nothing.
+- Asking for a change to a delivery you already have, relaunching a failed attempt, or continuing an open PR is always allowed: it does not add review work.
+- Launches from the mission agent, MCP clients and the Companion app get the same answer, and the agent explains it.
 
 ## Jobs
 

package/docs/tracking-cost.md

@@ -2,16 +2,26 @@
 
 ## What gets tracked
 
-Six surfaces, all per-project:
+Every AI CLI call a project makes writes one `ai_invocations` row tagged with a **surface** (the closed list lives in `server/modules/accounting/runtime/ai-invocations.ts`). There are twelve:
 
 | Surface | What it captures |
 |---------|------------------|
-| **`job`** | Every rail run (the Architect → Developer → Reviewer → Ship pipeline, plus Freestyle runs) |
+| **`job`** | Every queued job: rail runs on the CLI pipeline (Implement, Freestyle), plus the AI steps of a local merge-back (verify / resolve-merge / fix) |
+| **`loop`** | Every AI step of a Loop run (the built-in Implement / SDD Quick loops and your custom loops) |
 | **`quick-spec`** | One-shot Quick spec generation (including a Quick-mode Contract Refine run) |
 | **`explore-spec`** | Every Explore conversation turn (including the Explore Contract Refine run) |
 | **`ai-edit`** | The **AI Edit / Refine** overlay (refining an agent or a ticket) |
 | **`smash`** | SMASH runs that break an epic spec into sub-specs |
-| **`file-summary`** | Code-explorer AI summaries of individual files |
+| **`file-summary`** | Code-explorer AI summaries and file stories |
+| **`chat-sidebar`** | Turns in the project chat sidebar |
+| **`spec-launcher`** | The OpenSpec fast-forward launcher that turns a spec into an OpenSpec change |
+| **`proposal`** | Spec proposals (explore an idea, refine it with feedback) |
+| **`agent-studio`** | Custom-agent generation and test runs in the Agents studio |
+| **`setup`** | AI turns of the legacy setup/enrich chat (`/setup/start`, `/enrich/start`; used by API/MCP callers, not by the app UI) |
+
+**Missions are tracked too, in a separate ledger.** Mission (agent chat) turns and their sub-agents record to the app-level `agent_invocations` table. A mission pinned to a project is folded into that project's Analytics next to the surfaces above; unpinned (Home) missions appear only in Desktop Analytics.
+
+Adding a project does not spend tokens: the background workspace assembly runs specrails-core `init` offline and makes no model call.
 
 > Cost averages exclude `failed`/`aborted` rows, but those rows still count toward the total run count and the failure rate.
 
@@ -26,10 +36,6 @@ On multi-provider projects, a **Provider breakdown** card splits spend across th
 
 > **Fail-soft on unknown models.** The rate card lists specific models (the current Codex catalogs). If an invocation uses a model that isn't in the table, the app **does not fabricate a number** — it stores no cost (`total_cost_usd` is left empty), so that row simply shows a blank cost rather than a misleading estimate.
 
-## What's NOT tracked (intentionally)
-
-- **Setup wizard** — the install/enrich flow when you add a project. It *does* spawn an AI CLI (a genuine model invocation), but it's an interactive one-time wizard rather than a repeatable pipeline job, so it's deliberately left uninstrumented.
-
 ## The Analytics page
 
 Open **Analytics** from the project right sidebar.
@@ -37,7 +43,7 @@ Open **Analytics** from the project right sidebar.
 ### Sticky filter header
 
 - **Period** — `7d`, `30d`, `90d`, or `All`. (There's no 24-hour or custom-range option here — the custom calendar range lives on Desktop Analytics, below.)
-- **Surface** — chips for `All` plus each of the six surfaces (Jobs, Explore, Quick, Refine, SMASH, File summaries). All are included by default; toggle chips to narrow the view.
+- **Surface** — chips for `All` plus Jobs, Explore, Quick, Refine, SMASH, File summaries and Loops. All surfaces (including the ones without a chip) are included by default; toggle chips to narrow the view.
 - **Engine** — one chip per installed provider plus `All`. These appear **only on multi-provider projects** and let you filter activity by engine.
 
 The period and surface filters are URL-synced, so you can share or bookmark a view.
@@ -55,7 +61,7 @@ When the project has zero invocations in the period (e.g. you just started), the
 
 ### Daily stacked timeline
 
-A daily bar chart for the period, stacked by surface. It plots five series — **Jobs, Explore, Quick, Refine, and File summaries**. SMASH spend is still tracked and shows up elsewhere (the Hero per-surface bar, Top models, and the raw table), but it is not currently a separate bar in this chart. Days with zero activity are zero-filled so the x-axis stays regular.
+A daily bar chart for the period, stacked by surface. It plots seven series — **Jobs, Explore, Quick, Refine, File summaries, SMASH and Loops**. The smaller surfaces (chat sidebar, spec launcher, proposals, Agent Studio, setup) still count in the Hero total, the per-surface breakdown bar, Top models and the raw table. Days with zero activity are zero-filled so the x-axis stays regular.
 
 Surface colours are consistent wherever a surface appears across the page:
 
@@ -65,6 +71,29 @@ Surface colours are consistent wherever a surface appears across the page:
 - `ai-edit` → green (`accent-success`)
 - `smash` → highlight (`accent-highlight`)
 - `file-summary` → yellow (`accent-warning`)
+- `loop` → primary (`accent-primary`)
+
+### Time to decision
+
+How long deliveries wait for you. From the moment a delivery becomes reviewable (`on_review`), the card shows the **median** and **p90** time to the first human decision (Create PR, Discard, Merge locally — including a Create PR that failed) and to the merge (in-app local merge or the merge observed on GitHub), for the project and per loop, in the selected period.
+
+Every instant is recorded once and never moved by a retry, a second click or a restart (first write wins). A delivery still waiting counts as **pending**; one without recorded instants — for example created before this metric existed — counts as **unknown**. Neither is ever counted as zero. Discarded deliveries count toward time to decision but never toward time to merge. The same data is available through `specrails_analytics` (`decision_times`).
+
+### Loop economics
+
+Compares your loops over the selected period. One row per loop (saved published loops with nothing delivered show **No data**):
+
+| Column | Meaning |
+| --- | --- |
+| Delivered | Deliveries that reached review or beyond (on review, PR draft/ready/closed, merged, superseded, or discarded after review). Failed or still-building runs do not count. A multi-repository delivery counts once. |
+| Merged / Discarded | Delivered changes that were merged / discarded; the discard rate is discarded ÷ delivered. |
+| Cost / delivery | Average AI cost of delivered changes, attributed exactly like the delivery cost footer (the delivery's runs and their merge-resolver calls). Provider-reported cost is used as is; the share that comes from the pricing table is shown as *estimated*. Deliveries without any recorded cost are listed as *unpriced* and left out of the average — never counted as $0. |
+| Decision / Merge | Median · p90, as in [Time to decision](#time-to-decision). |
+| Reviews / Fixer rounds per delivery | Reviewer and fixer steps of the delivery's loop runs (automatic stall retries are not new rounds). Deliveries whose runs have no step log are unknown and do not lower the average. |
+| Escaped defects | Bug tickets linked to the delivery that introduced them. Label a ticket `bug` and pick the delivery under **Regression of** when you create or edit it. Until any ticket in the project carries a link the column shows **No data**. |
+| Requirements demonstrated / Triage accuracy | Reserved: they show **No data** until spec traceability and loop triage ship. |
+
+**—** always means unknown. Revert commits on delivered branches are not detected automatically; link the regression ticket instead. The same data is available through `specrails_analytics` (`loop_economics`).
 
 ### Quick vs Explore card
 
@@ -129,13 +158,28 @@ Exports use the standard `fetch → Blob → URL.createObjectURL → anchor.clic
 
 Open **Settings** from the project right sidebar → the **Budget** card:
 
-- **Daily budget (USD)** — the app auto-pauses the queue when the day's spend (the sum of completed-job cost since midnight) exceeds this. New rail launches queue rather than start; in-flight jobs aren't killed.
+- **Daily budget (USD)** — the app auto-pauses the queue when the day's spend reaches this. While it is exhausted, rail launches are refused (nothing starts) and running loops pause at the next step boundary; in-flight steps aren't killed.
 - **Per-job cost alert (USD)** — emits an alert when a single job exceeds this amount.
 
 Leave either field blank to disable that limit.
 
 When the daily budget is hit, a dismissible banner appears across the project pages ("Daily budget exceeded — … Queue is paused.") and the queue stays paused server-side. Resume by raising the budget, clearing it, or waiting for the counter to reset at midnight (it counts completed-job cost since the start of the current calendar day, not a rolling 24-hour window).
 
+### Rails and loops over budget
+
+Rail launches and loop runs check the same project and app-wide budgets the queue enforces:
+
+- **Launches are refused.** Play, Launch all, mission launch cards, Relaunch, the Loops page **Run**, MCP `launch`/`launch_all`, the mobile companion and milestone chains all receive `409 daily_budget_exceeded` with `scope` (`project` or `desktop`), `budgetUsd`, `spentUsd` and `resetsAt`. Nothing is spawned. The UI shows the amounts and where to raise the budget. Launch all counts these rails as "over the daily budget", not as failures. A milestone chain pauses with `launch_rejected:daily_budget_exceeded` and can be resumed.
+- **Running loops pause at the next step.** When the budget runs out mid-run, Desktop asks Core to pause the workflow (Core with the `pauseRuns` capability; older Core checks only before the next step): the current step finishes and the run parks as `paused` with `restart_reason = budget_paused`. The run card and log show *Paused on the daily budget*. Raise or clear the budget, then press **Resume** (or `POST /api/projects/:id/loop-runs/:runId/resume`, or send any message to the run). If the budget is still exhausted, the resume returns the same 409 and the run stays paused. **Stop** settles the run as stopped. The pause does not use up the loop's wall-clock timeout.
+- **Core workflows** schedule their steps inside one Core process, so Desktop gates them at the points it controls: at launch, at resume, and before it re-invokes Core after a question or approval. Core has no pause control yet, so a Core workflow that is already running finishes its current invocation.
+- If the budget state can't be read, the launch is allowed (fail-open, same as the queue). The app-wide spend is the queue's figure: completed jobs since UTC midnight. The project spend counts every billed invocation since local midnight.
+
+### Weekly, monthly and per-run caps
+
+Besides the daily budget, **Analytics ▸ Budget** sets a **weekly** and a **monthly** cap, per project and app-wide, and a **per-run soft cap** ("pause and ask at $X"). Weeks start on Monday and months on the 1st, in your local time. Weekly and monthly caps are enforced by the very same gate as the daily budget: launches are refused with `409 daily_budget_exceeded` (the body names the `period`), queues pause and running loops park as `budget_paused`. The per-run cap pauses one run when its own reported cost reaches it; **Resume** then asks you to continue without the cap or raise it. Reaching a cap also puts a **Raise cap** item in the inbox.
+
+The panel shows today, this week and this month against each cap, a month-end **projection** (an estimate: the average of the last 14 completed days times the days left, plus what is spent so far; it is never added to billed spend) and a **What-if** pricer that re-prices the last 30 days of recorded token usage on another model with the app's price list (a model without a price says so). On a subscription plan there is no per-use dollar cost, so the panel shows turns and plan limits instead of dollars.
+
 See [Customising the app](customizing.md#budget) for the full setup.
 
 ## App-wide analytics