@remits/remits-cli 0.1.135 → 0.1.137

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.135",
+  "version": "0.1.137",
   "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 |
@@ -162,11 +163,18 @@ reference named after it.
   component (preferred, because it becomes regression protection) or a browser flow through
   `remits-cli token`. "Just do it" and "that's fine, commit it" are not evidence. If you genuinely
   cannot verify, say what you would need and ask. (`development-loop.md`)
-- **For concrete user workflows, start a verification envelope before you edit.** `remits-cli verify
-  start --summary "..."` records the account/source/lane tuple and a manifest when you have one.
-  Stage, test, token, tool, and sync commands attach evidence automatically while the envelope is
-  active; finish from `remits-cli verify report`, which separates verified claims from missing or stale
-  evidence. (`development-loop.md`, `component-resolution.md`)
+- **`remits-cli evidence` answers "what have I actually run, and in which world?"** Every stage, test,
+  token, tool and sync appends one world-stamped line automatically, per actor. Nothing to start,
+  nothing to satisfy. Read it before you re-run something, and quote it when you report what you
+  proved. (`development-loop.md`)
+- **Verification envelopes are OPTIONAL and exist for one job: a verdict someone else will rely on.**
+  Start one when a ticket, a human, or a handoff needs a checkable "these specific things are true" —
+  not as a routine step before editing. `remits-cli verify start --summary "..."` then
+  `remits-cli verify claim <id> --text "..." [--test "<suite>"]` names what must be true; add
+  `--claim <id>` to the command that proves it; `remits-cli verify report` gives the verdict. An
+  envelope with no claims is simply an evidence log, which is a complete state — not something to
+  chase. If you find yourself opening an envelope to answer a question about your own work, use
+  `remits-cli evidence` instead. (`development-loop.md`, `component-resolution.md`)
 - **Read the component's `.meta.yml` before changing behavior.** Sidecar descriptions can be dated
   decision records. Before changing a displayed value, helper, calculation, schema field, or prompt
   contract, check the sidecar and either preserve its decision or explicitly supersede it.
@@ -209,8 +217,9 @@ remits-cli tools                  # which tools this account actually has (tools
 ```
 
 plus the repo's `account-info.json` → `resolution` block for the account's shape.
-For a workflow-shaped request, also run `remits-cli verify start --summary "..."` once the target tuple
-is understood, then keep that envelope active through stage/test/token/sync.
+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.
 
 If any command returns 401, run `remits-cli auth` (with the same `--base-url` if you were targeting a
 non-default host).

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)
@@ -236,12 +238,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 +255,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.
@@ -344,10 +395,24 @@ shown is the latest run's, with the distinct worlds listed beneath it.
 
 ### Verification envelopes
 
-Use a verification envelope for workflow-shaped work: concrete user journeys, browser-facing changes,
-branch variants, subscriber/forked accounts, production-vs-test lane questions, support tickets, and
-multi-agent work. Start it after you know the target account/branch/workspace/data-mode tuple and before
-the first edit:
+**First, the thing you probably want instead.** `remits-cli evidence` prints what you have actually run
+and in which world, grouped by world, with no envelope and nothing to start:
+
+```bash
+remits-cli evidence            # this actor's trail
+remits-cli evidence --json     # structured, for your final report
+```
+
+Every stage, test, token, tool and sync appends to it automatically. Use it for "what have I already
+run?", "did that execute in the prod lane?" and "what do I put in my final message?".
+
+**Verification envelopes are optional, and exist for a verdict someone ELSE will rely on** — a support
+ticket, a human who asked you to prove specific things, a handoff another agent will act on. They are not
+a routine step before editing. An envelope you started for your own benefit is nearly always
+`remits-cli evidence` in disguise, and it costs you turns that prove nothing.
+
+When a verdict is genuinely wanted, start it after you know the target
+account/branch/workspace/data-mode tuple:
 
 ```bash
 remits-cli workspace use --auto
@@ -355,6 +420,35 @@ remits-cli components status
 remits-cli verify start --summary "Hosted upload updates an existing profile" --manifest acceptance.json
 ```
 
+**Name what must be true, or there is no verdict to reach.** An envelope with no `claims` and no
+`requiredEvidence` reports `evidence_only` — a world-stamped log. That is a complete, final state, not a
+partial one, and nothing about it is outstanding. When you DO want a verdict, a manifest file is one way to
+declare the contract; `verify claim` is the one-command way, and it works on a live envelope:
+
+```bash
+remits-cli verify claim market-filter --text "US market scoring excludes AU and GB statements"
+remits-cli verify claim pilot-green --text "the pilot suite passes" --test "Acquirer Pilot"
+```
+
+Prove a claim by naming it on the command that already proves it. `--claim <id>` is stamped onto the
+evidence packet every command sends, so it works on `verify test`, `token`, `tool`, `stage`, `sync` and
+`attach` alike, and takes a comma-separated list:
+
+```bash
+remits-cli verify test --test "Acquirer Pilot" --claim pilot-green
+remits-cli verify tool --name mcp_run_action --as-account 36 --claim market-filter
+remits-cli verify attach --claim market-filter --note "AU statements excluded and counted"
+```
+
+A claim with no shape is satisfied by any successful packet tagged with its id. A claim that names a
+`--test` suite (or `--packet-type`) must be proven by that shape. Re-declaring an id replaces it, so
+tightening a claim is also one command.
+
+**When an envelope with a contract will not close, read the report — do not start another one.** Several
+open envelopes for the same goal, or workspaces named `...-r7`/`-r8`/`-r9`, is the loop signature, and
+`activity inspect` reports both as smells. Close what you are not finishing: `verify supersede --envelope
+<old> --superseded-by <new>` or `verify abandon --envelope <old> --reason "false start"`.
+
 An active envelope is stored per command world (`baseUrl + accountId + git branch + workspace`)
 inside the active local actor's mirror; **data mode is deliberately not part of the active pointer key**:
 `./.remits-cli/actors/<local-agent>/verification/active-contexts.json`. The legacy flat
@@ -367,7 +461,7 @@ history:
 
 ```bash
 remits-cli verify stage --workset
-remits-cli verify test --test "Adyen Import Recovery" --names "browser upload recovery"
+remits-cli verify test --test "Adyen Import Recovery" --names "browser upload recovery" --claim recovery
 remits-cli verify token --path /page/pricing-config --as-account 21 --data-mode test
 remits-cli verify sync --safe
 remits-cli verify report
@@ -435,10 +529,10 @@ proof noun: `passed` for a Test case, `measured` for corpus comparisons, `synced
 
 Final claims should come from `remits-cli verify report`. Treat `Verified` as the acceptance boundary.
 `Additional evidence` is useful handoff context, but it does not satisfy a missing required packet unless
-the report lists it under `Verified`. If the report says `partially_verified`, stale, or missing evidence,
-say that plainly instead of widening the claim. In particular, staged proof is not committed variant/trunk
-proof, a token is not browser proof, and a direct DOM or Alpine state mutation is not the same as a user
-action.
+the report lists it under `Verified`. If the report says `evidence_only`, no verdict was requested; if it
+says `partially_verified`, stale, or missing evidence, say that plainly instead of widening the claim. In
+particular, staged proof is not committed variant/trunk proof, a token is not browser proof, and a direct
+DOM or Alpine state mutation is not the same as a user action.
 
 Evidence from the wrong world is excluded before it can satisfy a requirement. When the manifest declares
 fields such as `repoAccountId`, `gitBranch`, `componentBranch`, `workspace`, or `dataMode`, the report names

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)
@@ -201,9 +202,39 @@ runs resolve and what a sync writes. If `account-info.json` carries a `component
 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`.
 
-If the request names a journey or acceptance behavior, start the envelope here, after the target tuple is
-understood and before editing. A manifest can be lightweight JSON; the point is that the required
-evidence is durable before the proof is collected.
+**You do not need to start anything to have a record.** Every stage, test, token, tool and sync appends a
+world-stamped line to your actor's evidence trail automatically. Read it with:
+
+```bash
+remits-cli evidence
+```
+
+That is the right tool for "what have I already run?", "did that test actually execute in the prod lane?",
+and "what should I put in my final message?". It is per-actor, so agents sharing a checkout never read each
+other's trail.
+
+**Start a verification envelope only when someone else needs a verdict** — a support ticket, a human who
+asked you to prove specific things, or a handoff another agent will act on. It is not a routine step before
+editing, and an envelope you open for your own benefit is almost always `remits-cli evidence` in disguise.
+
+When you do want a verdict, name what must be true. One command, no manifest file:
+
+```bash
+remits-cli verify start --summary "Hosted upload updates an existing profile"
+remits-cli verify claim fees-balance --text "statement fee totals reconcile to source within five cents"
+remits-cli verify claim pilot-green --text "the pilot suite passes" --test "Acquirer Pilot"
+```
+
+Prove a claim by naming it on the command that already proves it — `--claim <id>` works on `verify
+test`, `token`, `tool`, `stage`, `sync` and `attach` alike:
+
+```bash
+remits-cli verify test --test "Acquirer Pilot" --claim pilot-green
+remits-cli verify attach --claim fees-balance --note "34025 reconciles at 0.02 variance"
+```
+
+An envelope with no claims reports `evidence_only`. That is a complete, final state — a log, not a
+half-finished exam. Nothing about it is outstanding.
 
 #### Step 2: Make the Change
 Edit component files under `components/`. This is local file editing — the platform doesn't know about your changes yet.
@@ -381,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*.

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