@remits/remits-cli 0.1.136 → 0.1.138

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.136",
+  "version": "0.1.138",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,

package/skills/remits-cli/SKILL.md

@@ -48,6 +48,7 @@ reference below, load it before you act, not after something surprises you.
 | register this session as an agent, or ask why a routed ticket never started | `agent-sessions.md` | `serve` vs `register`, what registration does, worker spawning per agent kind, routing order, the control center, multi-session auth |
 | investigate live behavior | `investigation.md` | which tool reads which record, correlation keys, reading a record's `content`, HTTP audits, AI activity, node/`localMode`, the production support flows |
 | call any `mcp_*` tool | `tool-reference.md` | every tool's parameters, semantics, and traps — read the tool's entry before building its input |
+| run, describe, poll, or interrupt an Action from the CLI | `tool-reference.md` → `mcp_run_action` | Action execution through `remits-cli tool --name mcp_run_action`; there is no separate top-level `remits-cli action` / `run action` wrapper |
 | reason about repo discovery, auth state, or what a command actually sent | `cli-state.md` | the global `~/.remits-cli/` control plane vs per-repo `./.remits-cli/`, and which file answers which question |
 | need an exact flag, or the auth / host / async surface | `command-reference.md` | authentication, host vs data mode, the two async mechanisms, hierarchy-scoped reads, the full command list, prod banners |
 | give up on something that misbehaved | `troubleshooting.md` | the symptom→fix table, the two kinds of escalation, and the escalation bundle |
@@ -139,6 +140,12 @@ reference named after it.
   (`component-resolution.md`, `command-reference.md`)
 - **Host and data mode are two independent decisions.** `--base-url` picks the Remits host,
   `--data-mode` picks the data segment on it. Neither implies the other. (`command-reference.md`)
+- **Localhost being down is not a verification blocker.** `remits-cli` can talk to any reachable Remits
+  host, including the deployed production host, by passing `--base-url`. If `http://localhost:8080`
+  refuses a connection, retry the same stage/test/tool/status command against the intended deployed host
+  with the same account, branch, workspace and data-mode facts; do not stop unless no reachable host or
+  valid session exists. A deployed host can still run test-lane verification: `--base-url` selects the
+  server, while `test run` still defaults to `--data-mode test`. (`command-reference.md`)
 - **`test run` ignores the stored session data lane.** It defaults to `test` even when `whoami` shows
   the session parked on prod; production Test runs require explicit prod provenance (`--data-mode prod`)
   or Test source declaring `dataMode 'prod'` / `[dataMode:'prod']`. Check returned `dataModeSource`
@@ -215,7 +222,8 @@ remits-cli components status      # trunk or variant checkout, staging lane, wor
 remits-cli tools                  # which tools this account actually has (tools are per-account)
 ```
 
-plus the repo's `account-info.json` → `resolution` block for the account's shape.
+plus the repo's `account-boot.json` → `resolution` block for the account's shape (`account-info.json`
+only when you need full inventory detail).
 For a workflow-shaped request, rely on the automatic `remits-cli evidence` trail unless someone else needs
 a checkable verdict. Only then start `remits-cli verify start --summary "..."`, declare claims, and keep
 that envelope active through stage/test/token/sync.
@@ -227,7 +235,8 @@ non-default host).
 `~/.remits-cli/account-repos.json` (every local repo, plus the reserved `platform` entry for the core
 platform clone), `~/.remits-cli/sessions.json` (auth state and lanes), `~/.remits-cli/agents.json`
 (agents registered here), `./.remits-cli/actors/<local-agent>/tool-responses/<callId>.json` (the full
-tool payload), and the repo's `account-info.json`. `cli-state.md` maps every remaining question to its
+tool payload), the repo's `account-boot.json`, and `account-info.json` when compact context is not enough.
+`cli-state.md` maps every remaining question to its
 file, including legacy flat `.remits-cli/` fallbacks.
 Repo-local session JSONL is intentionally a bounded audit log: request payloads and ordinary response
 bodies are summarized with keys, sizes, hashes, and redaction markers. Open actor-scoped tool response
@@ -241,7 +250,7 @@ Keep support and development sessions lean:
   `mcp_component_view` / `mcp_component_grep` are fallback surfaces for agents without that checkout,
   or for confirming what the live DB has stored after you already understand the files. For a ticket
   with `implementationAccountId`, resolve that account's indexed repo first, pull the appropriate
-  branch when the checkout is clean, and inspect `account-info.json` + `components/` there.
+  branch when the checkout is clean, and inspect `account-boot.json` + relevant `components/` there.
 - Do not read entire `.remits-cli/actors/<local-agent>/sessions/*.jsonl` (or legacy flat session logs) or
   large tool response files unless you first narrow to the relevant request, endpoint, tool, or ticket.
 - Prefer targeted Firestore queries: use `documentId`, tight `filters`, narrow `fields`, and low `limit`

package/skills/remits-cli/references/account-targeting.md

@@ -23,13 +23,14 @@
 against, and where a fix belongs are answered by the account's structure — never by its name.
 
 The account model itself — types, component inheritance, primary vs membership edges, the three independent
-edge properties, the user model — is in the always-loaded `platform-overview.md` and in depth in
+edge properties, the user model — is summarized in `platform-core.md` and in depth in
 `features/account-management.md` (`mcp_get_guide`). What follows is only what changes **what you type**.
 
 ### Read the shape first
 
-`account-info.json` (in a repo) and `mcp_account_view` (remotely) both carry a `resolution` block — the one
-place these facts appear. Field-by-field detail is under **`mcp_account_view`** in `tool-reference.md`. The
+`account-boot.json` (in a repo), `account-info.json` (full local inventory), and `mcp_account_view`
+(remotely) all carry a `resolution` block — the one place these facts appear. Field-by-field detail is
+under **`mcp_account_view`** in `tool-reference.md`. The
 four that decide a CLI action:
 
 | Read | To decide |
@@ -57,7 +58,8 @@ Two more, easily confused: top-level **`componentBranches`** lists the variant b
   current before reading source or editing. Run `git fetch origin`; when the tree is clean,
   `git pull --ff-only origin <branch>`; then confirm `git log origin/<branch>..<branch>` and
   `git log <branch>..origin/<branch>` are both empty. A worktree can have an isolated staging workspace
-  and still be based on a stale commit. Then read `account-info.json` and inspect `components/` directly.
+  and still be based on a stale commit. Then read `account-boot.json` and inspect relevant `components/`
+  directly; use `account-info.json` only for full inventory detail.
 - **Inside one repo but supporting a different account**: switch to that account's indexed repo if it
   exists. For tickets, prefer `implementationAccountId` / `implementationAccountName` over the reporting
   `accountId` when choosing that repo; a subscriber or client often reports the symptom while the
@@ -84,7 +86,7 @@ still go to the test lane. `Object.testMode` /
 `Event.testMode` / `Alert.testMode` (and `testMode` inside test-lane Audit documents) identify lifecycle
 rows in the test data lane. Agent-facing surfaces expose these fields:
 
-- `account-info.json`, `account-hierarchy.json`, and `mcp_account_view`: `resolution.testAccount` for the
+- `account-boot.json`, `account-info.json`, `account-hierarchy.json`, and `mcp_account_view`: `resolution.testAccount` for the
   described account, and `testAccount` on returned hierarchy nodes.
 - `mcp_account_user_admin`: `testAccount` on `hierarchy`, `account`, and `account_create` results;
   `testUser` on `users` / `user` results.

package/skills/remits-cli/references/branch-variants.md

@@ -408,6 +408,31 @@ from that checkout). Its first real sync (or commit) needs `--create-variant-bra
 variants or a subscriber the platform treats it as a feature branch and refuses to land it, so creating a
 new variant branch is always a stated decision, never a side effect of a feature branch's name.
 
+For a nested branch cut from an existing variant branch, seed the platform overlays explicitly after the git
+branch is created and pushed:
+
+```bash
+remits-cli components branch forked --copy-to sandbox --dry-run
+remits-cli components branch forked --copy-to sandbox
+remits-cli components sync --safe --branch sandbox
+```
+
+The copy is a DB overlay bootstrap, not a git write. It makes inherited overlays from `forked` already
+`storedCurrent` on the first `sandbox` sync, so the safe diff gate only has to account for the new branch's
+real file changes.
+
+**Copy before you subscribe, or the copy needs `--force`.** The copy refuses a target that already has
+stored overlays *or* live subscribers, and that second guard fires even when the target has no overlays at
+all — a branch somebody is already resolving is code those accounts are running right now, and replacing it
+has to be a stated decision. Seeding first and subscribing after keeps the plain form working. The copy is
+also all-or-nothing: the delete of any replaced overlays and every inserted row share one transaction, so a
+failure leaves the target exactly as it was rather than half-populated.
+
+Run it as `--dry-run` first. The plan reports `plannedCopies` — the number the real run will write — which
+is not always the source branch's row count: a source overlay that has become identical to trunk in both
+content and metadata is sparse, is not stored, and is listed as skipped instead of being silently dropped
+from the total.
+
 **Trunk moving also invalidates a branch.** Variant sparseness compares branch content against *current*
 trunk, so a trunk change can make an overlay obsolete without the branch changing at all. A trunk sync
 drops the affected branches' cached sync verdicts, so the next `components sync` on the branch really

package/skills/remits-cli/references/command-reference.md

@@ -15,6 +15,8 @@
   - [Hierarchy-scoped tool reads](#hierarchy-scoped-tool-reads)
   - [Data Mode](#data-mode)
 - [Command Reference](#command-reference)
+  - [Reading a failing run](#reading-a-failing-run)
+  - [A pass count only means something within one data lane](#a-pass-count-only-means-something-within-one-data-lane)
   - [Verification envelopes](#verification-envelopes)
   - [Staging modes: workset vs full snapshot](#staging-modes-workset-vs-full-snapshot)
   - [Prod banners and retryable failures](#prod-banners-and-retryable-failures)
@@ -40,6 +42,10 @@ Treat host selection and data mode as two separate decisions:
 
 - `--base-url` chooses the Remits host: localhost vs a deployed environment.
 - `--data-mode` chooses the data segment on that host: `test` vs `prod`.
+- A connection failure to `http://localhost:8080` only says the local back-stage app is not reachable.
+  It does **not** mean staging, testing, tokens, or investigation are blocked. If a deployed Remits host
+  is the right target, pass it explicitly with `--base-url` and keep the same account/branch/workspace
+  and `--data-mode` facts.
 
 Examples:
 
@@ -47,11 +53,20 @@ Examples:
 # Deployed prod host, but test data segment
 remits-cli tools --base-url https://your-prod-host --data-mode test
 
+# Deployed prod host, test data, staged component verification
+remits-cli components stage --workset --base-url https://your-prod-host
+remits-cli test run --test "Statement Reader Calculations" --base-url https://your-prod-host
+
 # Localhost host, but prod data segment on that localhost instance
 remits-cli tool --base-url http://localhost:8080 --name mcp_account_view --data-mode prod
 ```
 
-Do not assume `--data-mode prod` implies the deployed prod host, or that `--data-mode test` implies localhost. If host matters, read `~/.remits-cli/sessions.json` first and pass `--base-url` explicitly.
+Do not assume `--data-mode prod` implies the deployed prod host, or that `--data-mode test` implies
+localhost. Likewise, do not assume localhost is required because the current checkout is a back-stage
+repo or because a previous command used localhost. If host matters, read `~/.remits-cli/sessions.json`,
+`remits-cli whoami`, or the recent `remits-cli evidence` world blocks, then pass `--base-url` explicitly.
+Only call verification blocked after trying the intended reachable host and finding that no authenticated
+session or usable network path exists.
 
 ### Tool Execution Lifecycle
 
@@ -236,12 +251,13 @@ remits-cli components branches [--json]                                # branche
 remits-cli components branch <name> [--json]                           # one branch: owner account, overridden / added / removed, drift flags, subscribers
 remits-cli components branch <name> --diff <componentId> --component-type <kind> [--json]
 remits-cli components branch <name> --subscribers [--json]
+remits-cli components branch <name> --copy-to <newBranch> [--dry-run] [--force] [--json] # seed a new variant branch with this branch's stored overlays; force if target has overlays/subscribers
 remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]   # make an account resolve this branch
 remits-cli components branch <name> --unsubscribe <accountId>                          # return that account to trunk
 remits-cli components branch <name> --retire [--force]                                 # delete the branch's overlays
-remits-cli test run --test <id|name> [--branch <stagingScope>] [--names "a|b"] [--watch true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>] [--json]
+remits-cli test run --test <id|name> [--branch <stagingScope>] [--names "a|b"] [--watch true|false] [--wait true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>] [--json]
 remits-cli test status --task-id <taskId> [--branch <stagingScope>] [--data-mode test|prod] [--json]   # falls back to the DURABLE run record once the live status expires
-remits-cli test runs [--test <id|name>] [--limit 20] [--compare] [--as-account <ID>] [--json]              # durable run history: pass counts, live AI cost, lane, content hash
+remits-cli test runs [--test <id|name>] [--limit 20] [--compare] [--all-lanes] [--as-account <ID>] [--json]  # durable run history: pass counts, live AI cost, lane, content hash
 remits-cli test compare --base <taskId> --head <taskId> [--json]                                            # per-case improved / regressed / changed, cost and world deltas
 remits-cli corpus import --manifest corpus-manifest.json [--corpus <name>] [--as-account <ID>] [--data-mode test|prod --confirm-prod] [--json]   # seed an evaluation corpus: cases + immutable artifacts; idempotent by caseKey
 remits-cli corpus cases --corpus <name> [--split S] [--tag T|--tags T,U] [--key K|--keys K,L] [--include-values] [--include-retired] [--limit N] [--json]
@@ -252,6 +268,54 @@ remits-cli corpus consistency --corpus <name> --case <caseKey> [--json]
 remits-cli corpus retire --corpus <name> --case <caseKey> [--case ...] [--restore] [--json]    # drop a case from future runs; past measurements stay readable
 ```
 
+`test run` starts a server-side task immediately. By default the CLI process polls until the task is
+terminal; `--watch false` disables websocket progress streaming but still waits. Pass `--wait false` to
+return after launch with the task id. A single run with `--names "a|b|c"` selects cases into one suite task,
+and those cases execute sequentially in declaration order. To overlap independent slow cases, launch
+separate `remits-cli test run --names "<case>" --wait false` commands from the same staged lane and keep the
+printed task ids; complete each proof with `test status --task-id <id>`. Avoid parallel runs for cases that
+share mutable fixtures, suite-level side effects, or undeclared live AI/provider calls.
+
+### Reading a failing run
+
+`test run` and `test status` print a **verdict**, not the run. The whole run object used to be dumped as
+pretty JSON in human mode - 220 KB for one 92-case suite, most of it identifiers repeated once per case - so
+the command an agent runs most often was the one that spent its remaining room to think. Every byte is still
+there behind `--json`, and behind `test status --task-id <id> --json` once the live status expires.
+
+What you get instead, and what to do with it:
+
+```text
+Cases: 59 passed, 33 failed, 92 total
+
+Failure roots (33 failed case(s), 21 distinct root(s)):
+  10x  assert statement.data.processingStatus == 'Analyzed'
+        e.g. bundled UK statements  (+9 more)
+   2x  assert statement.data.feeBreakdownChecked == true
+        e.g. 7851 Flat Rate  (+1 more)
+Largest root first: remits-cli test run --test "Statement Reader Calculations" --names "bundled UK statements"
+```
+
+**Thirty-three failures are not thirty-three problems.** Cases are grouped by their assertion root - the
+failure with the particulars (ids, numbers, Groovy's `Expression:`/`Values:` decoration) removed - largest
+group first, and one pivot block is printed per root rather than per case. Fix the largest root against one
+named case, then re-run the whole suite. Re-running the suite before you have a root is how a session spends
+an afternoon at the same pass count.
+
+### A pass count only means something within one data lane
+
+`test runs` is scoped to the data lane of the command by default, and says so:
+
+```text
+Data lane: test   (6 more run(s) in the other lane; --all-lanes to include)
+```
+
+A run's `dataMode` **is** the lane it was written in, so `64/92` in the prod lane and `59/92` in the test lane
+are two different facts, not a regression. `--compare` (and `test runs --compare`) picks the newest two runs
+of the same **shape** - same data lane, branch, workspace and case count - and says how many newer runs it
+skipped; it refuses rather than comparing across worlds. `test status --data-mode prod` on a run recorded in
+the test lane returns the run's real lane and now says that is what happened.
+
 A run labelled **`AI MOCKED`** replayed every AI turn from `aiMock`: it produces the same outcomes, scores and
 metrics a measured run would, so read that label before treating green as evidence. `compare` warns when base and
 head used different AI modes; `consistency` warns before calling a case unstable when its runs mixed modes.

package/skills/remits-cli/references/component-resolution.md

@@ -16,6 +16,7 @@
   - [When staged overrides apply](#when-staged-overrides-apply)
   - [Diagnosing which version is in play](#diagnosing-which-version-is-in-play)
   - [Working alongside other agents: the staging WORKSPACE](#working-alongside-other-agents-the-staging-workspace)
+  - [Keeping your remits-cli current](#keeping-your-remits-cli-current)
   - [A lane holds an OVERLAY; your workset is a different number](#a-lane-holds-an-overlay-your-workset-is-a-different-number)
   - [Stage / sync / clear with remits-cli](#stage--sync--clear-with-remits-cli)
   - [Stale after sync / commit (the in-memory compile cache)](#stale-after-sync--commit-the-in-memory-compile-cache)
@@ -250,6 +251,18 @@ index with `remits-cli workstream status`.
     `null` means unknown — a lane staged by an older CLI, or a branch whose last sync is not recorded —
     never "fresh".
 
+### Keeping your remits-cli current
+
+The diagnostics in these references only exist in the CLI that prints them. An older install does not print a
+worse version of them — it prints nothing, with no error, so nothing tells you what you are not being shown.
+`components stage` and `test run` warn when yours is behind:
+
+```text
+[remits-cli 0.1.120 -> 0.1.136] ... npm install -g @remits/remits-cli@latest
+```
+
+Upgrade when you see it. Auto-update handles it for you on most commands, including `--json` ones.
+
 ### A lane holds an OVERLAY; your workset is a different number
 
 This is the distinction that decides whether a lane is legible to anyone but you.

package/skills/remits-cli/references/development-loop.md

@@ -20,6 +20,7 @@
       - [Stage your workset, not the whole repo](#stage-your-workset-not-the-whole-repo)
       - [Three numbers, three questions](#three-numbers-three-questions)
     - [Step 4: Verify the Change](#step-4-verify-the-change)
+      - [Many failures are usually few causes](#many-failures-are-usually-few-causes)
     - [Step 5: Iterate If Needed](#step-5-iterate-if-needed)
     - [Step 6: Update Documentation](#step-6-update-documentation)
     - [Temporary Experiment Workflow](#temporary-experiment-workflow)
@@ -171,7 +172,7 @@ wants to proceed rather than reporting the work as done.
 This is how every development task should flow:
 
 #### Step 1: Understand the Request
-Read the user's request. If you may need a repo other than the current one, read `~/.remits-cli/account-repos.json` first. Then review `account-info.json` and `README.md` to understand what components exist and how they relate. Read the source of any component you'll modify before changing it.
+Read the user's request. If you may need a repo other than the current one, read `~/.remits-cli/account-repos.json` first. Then review `account-boot.json` and `README.md` to understand the account shape and component routing inventory. Read `account-info.json` only when the compact file lacks detail you need. Read the source of any component you'll modify before changing it.
 
 **Establish a steady git baseline before the first edit.** The platform syncs from the GitHub remote, not
 from your local files, and a worktree can be stale even when its staging lane is isolated. In the checkout
@@ -190,14 +191,14 @@ that the branch is behind trunk or that overlays were computed from an old SHA,
 code. A workspace prevents staged-cache collisions; it does not make a stale branch current.
 
 **Establish the account's shape too, not just its components.** Read the `resolution` block in
-`account-info.json` (or `mcp_account_view`): the account `type` decides whether this repo is even the right
+`account-boot.json` (or `mcp_account_view`): the account `type` decides whether this repo is even the right
 place to change code, `resolution.relationships` shows whether the account has more than one parent (and
 which link carries a branch/namespace/host), and `resolvedDatabaseName` tells you where its data actually
 lands. See `account-targeting.md` and `features/account-management.md` (`mcp_get_guide`).
 
 **Also establish which world you are working in.** `remits-cli components status` reports whether the
 working tree is a **trunk** checkout or a **variant branch** checkout — which decides both what your test
-runs resolve and what a sync writes. If `account-info.json` carries a `componentBranches` section, branch
+runs resolve and what a sync writes. If `account-boot.json` carries a `componentBranches` section, branch
 variants of these components exist: editing an origin component will drift them, so check
 `remits-cli components branches` before changing shared code. See `branch-variants.md`.
 
@@ -264,7 +265,7 @@ the file. Omit the key; the platform fills it in on sync:
 ```yaml
 # components/embeddables/new_MerchantPortal.meta.yml   — no `id:` yet
 name: Merchant Portal
-summary: One-line statement of what this component is for. This is the compact text account-info.json uses first.
+summary: One-line statement of what this component is for. This is the compact text account-boot.json uses first.
 description: |
   Longer technical description with line-number references to the key logic.
 path: /page/merchant-portal        # Readers and Embeddables only
@@ -411,14 +412,54 @@ Tests run on the platform against your staged snapshot. They stream results in r
 id + content hash, platform sync vs local HEAD. If it is not the world you meant, stop: the result will be
 about a different world.
 
+The platform launch is asynchronous. By default `remits-cli test run` waits for its task to finish, and any
+cases selected by `--names "a|b"` execute sequentially inside that suite task. If several slow cases are
+independent, stage once, then start separate `test run --names "<case>" --wait false` commands from the same
+lane and keep the task ids they print. Complete each proof with
+`remits-cli test status --task-id <id>`; that terminal status read records and attaches the final `test_run`
+evidence. Do not parallelize cases that mutate the same fixture, rely on shared suite setup state, or make
+undeclared live AI/provider calls.
+
 If cases fail, read the printed summary and pivots first: each case has an `outcome`
 (`failed`, `error`, `budget_exceeded`, `provider_unavailable`, …) with its reason, timing, trace id, AI usage
 (live vs mocked, cost), bounded `report(...)` diagnostics, live HTTP signals, and resolved component
 provenance. Fix the code, re-stage, and re-run only after those pivots explain the failure.
 
+##### Many failures are usually few causes
+
+When several cases fail, the run leads with **failure roots** — the failures grouped by their assertion with
+the particulars (ids, numbers, Groovy's `Expression:`/`Values:` decoration) stripped out, largest group first,
+one pivot block per root rather than per case:
+
+```text
+Failure roots (33 failed case(s), 21 distinct root(s)):
+  10x  assert statement.data.processingStatus == 'Analyzed'
+        e.g. bundled UK statements  (+9 more)
+Largest root first: remits-cli test run --test "Statement Reader Calculations" --names "bundled UK statements"
+```
+
+**Work the largest root against ONE named case, then re-run the suite.** A full re-run after every edit is the
+most expensive way to learn nothing: a real account spent two days and twenty-five runs holding a suite at
+56–59 of 92 while ten of its thirty-three failures were one cause. The narrow run is seconds, tells you
+whether the cause moved, and leaves your context for the actual reasoning.
+
+Two failure roots mean "stop and look elsewhere", not "iterate harder":
+
+- **`aiMock ctx.replay(...) found no usable stored provider response`** — the message says which of three
+  things happened. *No rows at all* for that sessionId means the stored session this fixture borrows is not
+  on this platform and will not come back; the case cannot pass until the mock builds its own response with
+  `ctx.toolCall(...)` / `ctx.content(...)`. Do not re-run it. (Replaying a session that IS there renews it,
+  so a suite that runs regularly keeps its fixtures.)
+- **`Method too large` / `Class too large` / a synthetic `_closureNN`** — a JVM limit on one method body, not
+  a bug in the line it names. Staging now warns *before* the refusal and names the closure's source line span.
+  Split that body; see `development-guide.md` → *Keep Component Bodies Split*.
+
 Every finished run is recorded durably: `remits-cli test status --task-id <id>` answers after the live status
-expires, `remits-cli test runs --test <name> --compare` compares the latest run with the previous one, and
-`remits-cli test compare --base <id> --head <id>` compares any two. For evaluation suites (a `corpus(name)` of
+expires, `remits-cli test runs --test <name> --compare` compares the latest run with the newest **comparable**
+one, and `remits-cli test compare --base <id> --head <id>` compares any two. Comparable means the same data
+lane, branch, workspace and case count: a run's `dataMode` is the lane it was written in, so `64/92` in prod
+and `59/92` in test are two facts and not a trend. `test runs` lists one lane at a time and names it
+(`--all-lanes` to see both). For evaluation suites (a `corpus(name)` of
 cases seeded with `remits-cli corpus import`, one case per corpus case, intentional live AI inside
 `withAiBudget(...)`, measurements compared with `remits-cli corpus compare` / `corpus consistency`), read
 `guides/test-components.md` → *Evaluation Suites And Corpora*.
@@ -527,7 +568,7 @@ If the work is tied to a support ticket:
 
 Before committing, update metadata so the next session understands what changed:
 
-1. **`.meta.yml` sidecars** — Update `summary`, `description`, and `mermaid` for each modified component. `summary` is what drives the compact component description in generated `account-info.json`; `description` is the fallback when no summary is set and is capped in that file. Preserve or explicitly revise dated decision notes; do not delete the evidence the next agent needs.
+1. **`.meta.yml` sidecars** — Update `summary`, `description`, and `mermaid` for each modified component. `summary` is what drives the compact component description in generated `account-boot.json`; `description` is the fallback when no summary is set and is capped there. Preserve or explicitly revise dated decision notes; do not delete the evidence the next agent needs.
 2. **`README.md`** — If the change affects account-level capabilities or workflows.
 3. **New components** — Always fill in `.meta.yml` immediately.
 

package/skills/remits-cli/references/tool-reference.md

@@ -76,6 +76,9 @@ remits-cli tool --account-id 21 --as-account 37 --target-account 37 --name mcp_r
 # poll by run id:  --account-id 21 --as-account 37 --target-account 37 --input '{"controlAction":"status","actionRunId":"my-stable-run-id"}'
 ```
 
+That is the CLI Action-run surface. The command is still `remits-cli tool`; this CLI does not have a
+separate top-level `remits-cli action`, `remits-cli actions`, or `remits-cli run action` wrapper.
+
 For long tools that lack their own async mode, use the CLI transport async (`--async true`), optionally with
 `--wait true` to poll locally, and `remits-cli tool status --call-id <callId>`. Do not stack both mechanisms
 (see `command-reference.md` → *Tool Execution Lifecycle*). Use `--timeout-ms <ms>` only to adjust the per-request client timeout; it is
@@ -403,12 +406,18 @@ Front-stage references:
 | `page` | no | 1-based page number. Default: `1` |
 | `pageSize` | no | Results per page. Default: `25`, max: `100` |
 | `summaryOnly` | no | Detail mode: return the MAP (record index + stats + timeline) with no payloads. Same as `parts:["index"]` |
-| `parts` | no | Detail parts: `index`, `stats`, `transcript`, `tool_calls`, and record sections `full`, `conversation_messages`, `system`, `response`, `tools` |
+| `compact` | no | Detail mode: after reading the MAP, open selected records without repeating the `records` index and `timeline`; keeps `groupingSummary`, `representativeSession`, `stats`, selected ids, and requested payload sections |
+| `payloadOnly` | no | Alias for `compact` |
+| `parts` | no | Detail parts: `index`, `map`, `records`, `stats`, `transcript`, `tool_calls`, and record sections `full`, `conversation_messages`, `system`, `response`, `tools` |
 | `sections` | no | Alias for `parts` |
 | `recordIds` | no | Detail mode: open only these request/response record IDs |
 | `toolCallIds` | no | Detail mode: return the FULL exact input/result from `ai_tool_call` for these tool-call ids (what the tool PRODUCED — see the lens caveat) |
 | `consolidateContext` | no | When `true`, collapses repeated XML-like prompt context into a consolidated section |
 
+Detail responses expose both lenses: `groupingSummary` is the authoritative grouping-wide summary
+(counts, lanes, cost, status), while `representativeSession` names the concrete session used for
+owner/runtime metadata. `session` remains only as a compatibility alias for older callers.
+
 Spend: each search row carries `liveRequestCount`, `mockedRequestCount`, `lanes`, `testTaskId` and
 `estimatedCost`/`estimatedCostUsd` = **live spend only** (a mocked turn is never priced, even when it replays a
 recording with a cost). `pageTotals` sums the page. Turns recorded before the platform stored the mock flag are
@@ -416,12 +425,16 @@ recording with a cost). `pageTotals` sums the page. Turns recorded before the pl
 is refused rather than silently widened; the applied bounds are echoed as `filters.rangeStart`/`rangeEnd`.
 To audit one Test run: `{"action":"search","testTaskId":"<taskId>","pageSize":100}`.
 
-Audit flow: `action:"search"` to find the grouping → `action:"detail"` + `summaryOnly:true` for the MAP → re-call detail with `recordIds`/`toolCallIds` + `parts` to open exactly what you need. Prefer the map → open flow over a full-detail dump. Remember the two-lens rule: `tool_calls`/`toolCallIds` is what the tool PRODUCED; `conversation_messages`/`transcript` is what the AI CONSUMED (after any `_offload`/`_hideResult`/`_message`/supersede/evict transform).
+Audit flow: `action:"search"` to find the grouping → `action:"detail"` + `summaryOnly:true` for the MAP → re-call detail with `recordIds`/`toolCallIds` + `parts` to open exactly what you need, usually with `compact:true` once the map has chosen the row. Prefer the map → open flow over a full-detail dump. Remember the two-lens rule: `tool_calls`/`toolCallIds` is what the tool PRODUCED; `conversation_messages`/`transcript` is what the AI CONSUMED (after any `_offload`/`_hideResult`/`_message`/supersede/evict transform).
 
 ### `mcp_run_action`
 Run an Action on a target account, with explicit prod/test data mode, optional staged branch resolution, and
 staged-vs-DB provenance in the result.
 
+Invoke it with `remits-cli tool --name mcp_run_action`. Despite the natural shorthand "run an Action", there
+is no separate top-level `remits-cli action` / `actions` command and no `remits-cli run action` wrapper in
+this CLI build.
+
 Describe the Action first when the input shape is not obvious. This does not execute the Action:
 
 ```bash
@@ -832,6 +845,10 @@ Common uses:
 - `remits-cli components branch <name> --diff <id> --component-type <kind>` — compare one variant against
   current trunk.
 - `remits-cli components branch <name> --subscribers` — list accounts resolving that branch.
+- `remits-cli components branch <name> --copy-to <newBranch> [--dry-run] [--force]` — seed a new variant
+  branch with the source branch's stored overlays before the first safe sync of the new branch. Dry-run
+  reports the copy plan without writes; force is required when the target already has overlays or live
+  subscribers.
 
 ### `mcp_cache`
 Bounded read-only investigation of the platform Redis keyspace — the way to see exactly what a staged