@remits/remits-cli 0.1.114 → 0.1.116

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -60,6 +60,19 @@ reference named after it.
 - **edit → stage → run, every time.** The platform executes whatever is in the staging cache at the
   moment a run starts. Edit a file, run a test without `remits-cli components stage`, and the test runs
   the OLD code. This is the single most common mistake. (`development-loop.md`)
+- **Stage your WORKSET, not the whole repo: `remits-cli components stage --workset`.** It uploads only
+  the components git reports changed and makes the lane hold exactly them. A plain `components stage` is
+  a FULL SNAPSHOT — it puts every component in the repo into the lane, so "115 staged" tells a human
+  nothing about what you are working on, and every one of those entries shadows committed source until
+  it expires. Keep the full stage for a deliberate complete snapshot or a "what is stale here?" reset.
+  (`development-loop.md`)
+- **Give each agent its own lane: `remits-cli workspace use --auto`.** Without a workspace you are in
+  the SHARED lane, where a full stage replaces what another agent is testing rather than merging with
+  it. (`component-resolution.md`)
+- **On a variant branch, sync with `remits-cli components sync --safe`.** It dry-runs first and refuses
+  a plan that would write components this checkout did not change — which is what a branch that is
+  behind trunk produces, because it still physically carries old copies of files nobody touched.
+  (`component-integrity.md`, `branch-variants.md`)
 - **`stage` is always safe. `components commit` on trunk is the most dangerous command in the CLI.**
   It is not a convenience wrapper: it `git add -A`, commits, pushes, and then reconciles the whole
   pushed repo into the live component database — creating, updating, renaming, and **hard-deleting**
@@ -76,11 +89,24 @@ reference named after it.
 - **Ask which world your checkout resolves before you run anything:** `remits-cli components status`.
   A trunk checkout and a variant-branch checkout differ on both ends of the loop — what a run resolves
   and what a sync writes. Do not infer it from the branch name. (`branch-variants.md`)
+- **Start from a steady git baseline before the first edit.** Run `git fetch origin`; confirm
+  `git log origin/<branch>..<branch>` and `git log <branch>..origin/<branch>` are both empty; then run
+  `remits-cli components status`. On a variant branch also run `remits-cli components promotion --branch
+  <branch>`. A workspace isolates staging, not the commit your files are based on. (`development-loop.md`,
+  `branch-variants.md`)
 - **Resolution order is staged → variant → trunk, and each layers over the one beneath.** A populated
   staging cache makes a committed variant look broken through any tokenized entry point; clear it before
   verifying variant resolution. (`component-resolution.md`)
+- **A lane's staged count is the OVERLAY, not your workset.** The overlay is every staged entry the lane
+  holds — what a run resolves. The workset is what git says you changed. A full stage makes them differ
+  by the size of the repo, and `--changed-only` merges, so it can never shrink an overlay it inherited.
+  `components status` prints all three numbers; so does the console. (`component-resolution.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`)
+- **`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`
+  when auditing a run. (`command-reference.md`)
 - **A tool's `dataMode` input never widens the lane.** It may narrow `prod` → `test`, never escalate
   `test` → `prod`. The response's `dataMode` is the truth, not your input. To reach prod data, pass
   `--data-mode prod` on the command line. (`account-targeting.md`)
@@ -95,6 +121,10 @@ 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`)
+- **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.
+  (`development-loop.md`)
 - **Read the account's `resolution` block before acting on it** — `role`, `type`,
   `resolvedDatabaseName`, `relationships`. More than one relationship means the account can legitimately
   resolve differently depending on the path a request travelled. Never infer an account's shape from its
@@ -111,6 +141,12 @@ reference named after it.
 - **Reading and investigating are parallel-safe; editing one account's repository is exclusive**, via a
   lease. A refusal is not an error — carry on read-only and hand off with `ticket progress --next-step`.
   Never wait or poll for a lease. (`support-tickets.md`)
+- **A brief's `## Rules you will be held to` section is ENFORCED, not requested.** The platform refuses
+  the verb and the message says what to do instead — act on that sentence rather than retrying or
+  looking for another door. A `[require]` rule needs a person; hand off. (`support-tickets.md`)
+- **`components commit` takes a short landing lease on `(account, branch)`.** Refused means somebody else
+  is landing right now — keep staging and iterating, which is lane-isolated, and retry in a minute.
+  Never loop on it. (`development-loop.md`)
 - **If something looks wrong, stop — do not paper over it.** Unexpected deletes, creates, renames,
   uniqueness errors, id drift, or a 500 from the platform: stop, preserve the session log and tool
   responses, and escalate. Never create replacement components to make ids line up, and never discover
@@ -120,7 +156,8 @@ reference named after it.
 
 ```bash
 remits-cli whoami                 # account, user, branch, data mode, host for the NEXT tool call
-remits-cli components status      # trunk or variant checkout, staging lane, what is staged
+remits-cli workspace use --auto   # your own staging lane, named after this checkout
+remits-cli components status      # trunk or variant checkout, staging lane, workset vs overlay, who else is staging
 remits-cli tools                  # which tools this account actually has (tools are per-account)
 ```
 
@@ -139,7 +176,11 @@ repo's `account-info.json`. `cli-state.md` maps every remaining question to its
 
 Keep support and development sessions lean:
 
-- Prefer local repo files over remote tools whenever the target account repo exists locally.
+- Prefer local repo files over remote component tools whenever the target account repo exists locally.
+  `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.
 - Do not read entire `.remits-cli/sessions/*.jsonl` 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

@@ -53,9 +53,18 @@ Two more, easily confused: top-level **`componentBranches`** lists the variant b
 
 ### Repo selection rules
 
-- **Inside the target implementation repo**: read `account-info.json` and inspect `components/` directly.
-- **Inside one repo but supporting a different account**: switch to that account's repo if it exists;
-  otherwise use `mcp_account_view` / `mcp_component_view` / `mcp_component_grep`.
+- **Inside the target implementation repo**: make sure you are on the relevant branch and the checkout is
+  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.
+- **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
+  implementation lives in an upstream `PLATFORM` / `PRODUCT` repo.
+- **Only use `mcp_component_view` / `mcp_component_grep` when the correct repo is not available locally,**
+  or when you are deliberately comparing local source to the live DB after reading the files. They are not
+  the normal way to learn source on a machine with the account repo.
 - **Outside any repo**: rely on the tools, and `mcp_get_guide` for the front-stage guides.
 - **Never create a new local repo/directory just because a ticket references an account name.** Resolve the
   account type and parent hierarchy first, and work only from an existing indexed repo unless the user

package/skills/remits-cli/references/agent-sessions.md

@@ -68,7 +68,7 @@ capacity. For each new ticket it launches a headless worker:
 
 | | headless invocation | edit mode | investigate mode |
 |---|---|---|---|
-| `codex` | `codex exec --cd <repo>` | `--sandbox workspace-write` | `--sandbox read-only` |
+| `codex` | `codex exec --cd <repo>` | `--sandbox workspace-write` | `workspace-write with investigation-only brief and no edit lease` |
 | `claude` | `claude -p --add-dir <repo>` | `--permission-mode acceptEdits` | `--permission-mode plan` |
 | `gemini` | `gemini -p` in `<repo>` | `--approval-mode auto_edit` | `--approval-mode plan` |
 
@@ -83,6 +83,9 @@ and the worker are one answer, not two.
 The brief always arrives on **stdin**, never in argv — it is a page of prose and argv has a hard
 length limit, so an argv brief would fail on exactly the detailed tickets that most need the detail.
 The brief itself is generated by the platform, so all three worker types are told the same thing.
+In `--mode investigate`, the supervisor still claims tickets and may update them with findings, but it
+does **not** acquire or renew the repository edit lease. The brief says the run was launched for
+investigation only and forbids file edits, component staging, commits, and manual lease escalation.
 
 **Following a run.** `remits-cli start`'s control center lists every worker; **Follow live** streams
 that run's transcript into the page, rendering commands with their exit codes, file edits, and the
@@ -162,6 +165,7 @@ and holds a PID lock (`~/.remits-cli/listener.pid`) so only one runs per machine
 
 The control center shows, in one browser view:
 - which agent sessions are registered, what each is doing right now, and its recent activity
+- live and recent worker runs, with historical transcript follow/stop controls keyed to the exact run
 - the open support-ticket queue, and which agent each ticket is routed to
 - a control to route a ticket at a specific available agent
 - websocket connection and topic health

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

@@ -81,6 +81,22 @@ checkout and 15/15 from trunk, with no code difference.) **Run branch-variant su
 - **Nothing is renamed.** A variant sync never renames files and never repoints the account's trunk
   branch. A `new_*` file stays `new_*`.
 
+**Start from a current branch, not just an isolated workspace.** Before the first edit in a variant
+checkout:
+
+```bash
+git fetch origin
+git status --porcelain
+git log origin/<branch>..<branch>              # must be empty: nothing local-only
+git log <branch>..origin/<branch>              # must be empty: not behind the remote
+remits-cli components promotion --branch <branch>
+```
+
+`components promotion` reads the remote and reports whether the branch is also current with trunk. If it
+says `diverged` or `STALE`, merge trunk in or sync first, as instructed, before writing new work. A
+workspace lane prevents another agent from overwriting your staged Redis snapshot; it does not say which
+commit your files are based on.
+
 **Branch-local `account-info.json` can describe a subscriber.** On a variant branch the repository is
 still the OWNER's component repo — files overlay that owner's trunk ids and sync writes overlays owned by
 that owner. But when the checkout was synced from a subscribing account reached through an
@@ -193,7 +209,10 @@ resolution on production/subscription semantics. Do **not** use this pattern wit
 ### The SDLC is identical on a variant branch
 
 ```bash
-git checkout feature_branch          # or: git checkout -b feature_branch
+git fetch origin
+git checkout feature_branch
+git pull --ff-only origin feature_branch
+remits-cli components promotion --branch feature_branch
 # edit components/actions/50_ExtractInvoice.groovy   (KEEP the trunk id)
 remits-cli components stage          # Redis, scoped to this branch — same as always
 remits-cli test run --test "Invoice Tests"                    # the feature_branch world

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

@@ -15,6 +15,7 @@
   - [Hierarchy-scoped tool reads](#hierarchy-scoped-tool-reads)
   - [Data Mode](#data-mode)
 - [Command Reference](#command-reference)
+  - [Staging modes: workset vs full snapshot](#staging-modes-workset-vs-full-snapshot)
   - [Prod banners and retryable failures](#prod-banners-and-retryable-failures)
 
 ## Getting Started
@@ -158,7 +159,7 @@ remits-cli data-mode set test         # Switch back to test for development
 remits-cli auth [--base-url URL] [--account-id ID] [--data-mode test|prod]
 remits-cli sessions [list|remove] [--account-id ID]
 remits-cli config [set] [--agent claude|codex|gemini]
-remits-cli agent serve [--worker-agent claude|codex|gemini] [--max-concurrent N] [--mode edit|investigate] [--label NAME] [--data-mode test|prod]
+remits-cli agent serve [--worker-agent claude|codex|gemini] [--max-concurrent N] [--mode edit|investigate] [--serves a,b] [--label NAME] [--data-mode test|prod]
 remits-cli agent workers [--json]
 remits-cli agent register [--label NAME] [--data-mode test|prod] [--account-id ID] [--max-concurrent N]
 remits-cli agent work [--wait SECONDS] [--json]
@@ -181,7 +182,7 @@ remits-cli ticket artifact --ticket ID --type TYPE --label "..." [--url U | --co
 remits-cli ticket participant --ticket ID --email E [--role watcher|requester|agent]
 remits-cli ticket field --ticket ID --key K --value V  # the ORGANIZATION's own field, outside the planning slots
 remits-cli ticket reclaim [--ticket ID | --account-id ID] [--stale-hours 24] [--apply]   # OPERATOR: take back an agent's abandoned ticket
-remits-cli ticket queue --account-id ID [--status ...] [--unrouted] [--unassigned] [--awaiting-response] [--workstream W] [--board-stage S] [--planned-in P] [--search "..."] [--sort-by ...] [--json]
+remits-cli ticket queue --account-id ID [--status ...] [--unrouted] [--unassigned] [--awaiting-response] [--min-runs N] [--workstream W] [--board-stage S] [--planned-in P] [--search "..."] [--sort-by ...] [--json]
 remits-cli ticket create --account-id ID --subject "..." --type defect|question|task|incident|enhancement [--priority P] [--description "..."] [--tags a,b] [--workstream W] [--affected-component C] [--implementation-account-id ID] [--reference-id KEY]
 remits-cli start [--foreground true] [--port 8787]
 remits-cli stop
@@ -189,12 +190,12 @@ remits-cli status [--base-url URL] [--account-id ID] [--data-mode test|prod] [--
 remits-cli whoami [--base-url URL] [--account-id ID] [--data-mode test|prod] [--json]
 remits-cli listen [stop|status] [--foreground true]   # compatibility alias
 remits-cli data-mode [set test|prod]
-remits-cli components stage [--branch <name>] [--workspace <name>] [--changed-only] [--data-mode test|prod] [--json|--verbose]
+remits-cli components stage [--workset | --changed-only] [--branch <name>] [--workspace <name>] [--empty-workset clear] [--data-mode test|prod] [--json|--verbose]   # default = FULL SNAPSHOT of the repo; --workset = only what git says changed, lane reconciled to it
 remits-cli workspace [show | use <name> | use --auto | clear]
 remits-cli components status [--branch <name>] [--component-type <type>] [--component-id <id>] [--json|--verbose]
 remits-cli components clear [--branch <name>] [--component-type <type>] [--component-id <id>] [--all] [--json|--verbose]   # id alone scopes to one component when unambiguous (ids are type-local; add --component-type if the same id is staged in multiple families); no filter clears the whole branch scope; --all forces the full wipe
-remits-cli components sync [--branch <name>] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary] [--changed-only [--changed-since <ref>]]   # gated; on trunk = full repo->DB reconcile, on a variant branch = ComponentVariant overlays only
-remits-cli components commit [--message "msg"] [--data-mode test|prod] [--force-tombstones]
+remits-cli components sync [--safe [--yes]] [--branch <name>] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary] [--changed-only [--changed-since <ref>]]   # gated; on trunk = full repo->DB reconcile, on a variant branch = ComponentVariant overlays only
+remits-cli components commit [--safe] [--message "msg"] [--data-mode test|prod] [--force-tombstones]   # --safe gates phase 2; it cannot un-push phase 1
 remits-cli components branches [--json]                                # branches carrying committed variants, with counts + drift
 remits-cli components branch <name> [--json]                           # one branch: overridden / added / removed, drift flags, subscribers
 remits-cli components branch <name> --diff <componentId> --component-type <kind> [--json]
@@ -211,7 +212,9 @@ remits-cli tool status --call-id <callId> [--data-mode test|prod]
 ```
 
 For tests specifically:
-- If `--data-mode` is omitted, `remits-cli test run` uses `test`.
+- If `--data-mode` is omitted, `remits-cli test run` uses `test` and sends `dataModeSource:"cliDefault"`.
+  An explicit `--data-mode prod` sends `dataModeSource:"explicitFlag"` so production test runs are
+  auditable from the server status payload even when the original terminal history is gone.
 - `--names` is `|`-delimited (a comma still splits a single value) and may be repeated; an unmatched
   selector fails the run instead of reporting zero cases as success.
 - `--as-account <ID>` runs AS a descendant subscriber so its edge selects the component branch
@@ -249,8 +252,50 @@ For tests specifically:
   - `--names-only` — dry-run and print only `BUCKET type:id name` lines for the planned writes, then stop
     without writing overlays.
 
+  - `--safe` — the NAME for that combination, and the recommended agent path on a variant branch. It
+    expands to `--summary --changed-only --fail-on-errors --fail-on-removed`, resolves `--changed-since`
+    from this branch's merge base with trunk when you did not name one (local refs only — it never runs
+    an implicit `git fetch`, and refuses with the fetch command when nothing local can answer), and
+    prints the planned writes before mutating unless `--yes` is passed. On TRUNK there is no plan to
+    gate, so it states what a trunk reconcile does (every row rewritten from the repo; any live component
+    missing from the repo DELETED) and requires `--yes`. It does not override a narrower
+    `--expected-removed`.
+
   A good default for an unattended promotion is:
-  `remits-cli components sync --summary --changed-only --fail-on-errors`
+  `remits-cli components sync --safe`
+
+  When `--changed-only` refuses a plan far larger than your changed set, the usual cause is a branch that
+  is BEHIND trunk: it still physically carries old copies of files nobody on it touched, and a variant
+  sync turns each of those into an unrelated override. The refusal says so. Merge trunk in, push, re-run.
+
+### Staging modes: workset vs full snapshot
+
+`components stage` reports three numbers, and they answer three different questions:
+
+| Number | Question |
+|---|---|
+| **workset** | how many components git reports this working tree changed |
+| **submitted** | how many this command uploaded |
+| **overlay** | how many staged entries the lane now holds — **what a run resolves** |
+
+| Mode | Uploads | Lane afterwards |
+|---|---|---|
+| `components stage` (default) | the whole repository manifest | reconciled to the whole repo — a FULL SNAPSHOT |
+| `components stage --workset` | only the git-changed components | reconciled to exactly those |
+| `components stage --changed-only` | only the git-changed components | merged; earlier entries are left in place |
+
+`--workset` is the iteration mode. `--changed-only` keeps its long-standing merge semantics, so it cannot
+shrink a lane inherited from an earlier full stage; the command warns when it retains entries that way.
+`--changed-only --replace-lane` is the explicit spelling of `--workset`.
+
+An empty workset never clears a lane: `--workset` on a clean tree stages nothing and leaves the lane as
+it is. `--empty-workset clear` opts into the clear; `components clear --all` is the direct way.
+
+A deleted component file cannot be represented in Redis staging — clearing a staged entry falls back to
+the committed row, so the component still resolves. The command reports those changes as NOT
+REPRESENTABLE. On a non-trunk variant branch, prove a deletion through
+`components sync --dry-run --summary --fail-on-errors`; on trunk there is no dry-run plan, so use the
+full pre-sync safety check before any mutating reconcile.
 
 ### Prod banners and retryable failures
 

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

@@ -135,9 +135,14 @@ file is catastrophic.
   variant branch the id/delete/renumber checks below apply to the **overlay set** instead: confirm every
   component absent from the branch is *meant* to be tombstoned for subscribers.
 - The user intends durable platform promotion now — not just local edits, staging, or verification.
+- `git fetch origin` has run, and this checkout matches the remote branch the platform will sync:
+  `git log origin/<branch>..<branch>` and `git log <branch>..origin/<branch>` are both empty. A local
+  commit that is not pushed is invisible to Remits; a local branch behind the remote is a stale baseline.
 - `git status --short` shows only intended changes; every rename/delete is explained. **No component file has
   been renumbered to a different id.**
-- Local branch is committed and pushed; sync will read the intended remote commit.
+- Local branch is committed and pushed; sync will read the intended remote commit. If a sync just
+  completed, `git pull --ff-only origin <branch>` has run before any next git operation, because sync may
+  push generated artifacts back to the branch.
 - Local filenames and live inventory (`mcp_account_view`) **agree on id and name for every component**: no live
   component appears locally under a different id, and no expected component is missing a repo file.
   > **Do not run this comparison against `account-info.json` alone — it will report false orphans.** That

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

@@ -15,6 +15,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)
+  - [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)
 
@@ -153,7 +154,11 @@ overwrite each other, and a `components commit` clears the lane out from under t
 If more than one agent is working on the same branch, give each its own workspace:
 
 ```bash
-git worktree add ../repo-agent-a forked      # one checkout per agent, same branch
+git fetch origin
+git switch forked
+git pull --ff-only origin forked
+git rev-list --left-right --count HEAD...origin/forked   # must print: 0  0
+git worktree add --force ../repo-agent-a forked           # one checkout per agent, same branch
 cd ../repo-agent-a
 remits-cli workspace use --auto              # names the lane after this directory
 remits-cli components stage                  # isolated: nobody else sees it, nobody overwrites it
@@ -161,6 +166,14 @@ remits-cli test run --test 42
 remits-cli token --path /page/whatever
 ```
 
+That first block matters. `git worktree add ... forked` uses the local `forked` ref; it does not fetch or
+prove that `forked` equals `origin/forked`. If the local ref is stale, every isolated staging lane starts
+from the same stale files and a later sync looks like a deliberate revert. Before the first edit in a new
+or reused worktree, `git status --porcelain`, `git log origin/<branch>..<branch>`, and
+`git log <branch>..origin/<branch>` should all be empty. For variant branches, run
+`remits-cli components promotion --branch <branch>` too; a branch can be current with its own remote and
+still stale relative to trunk.
+
 A workspace narrows STAGING and nothing else. A commit still targets the same branch and the same owner
 account, and the run still resolves whatever committed variant branch the account subscribes to — so it
 does **not** have the side effects of inventing a throwaway git branch per agent (which would make a
@@ -172,19 +185,60 @@ commit write `ComponentVariant` overlays for a branch nobody subscribes to).
 - Every stage / test run / token / clear prints its `Staging lane:` — if a change seems to have had no
   effect, check that line FIRST. A mismatched lane resolves committed source, which looks identical to
   "the stage did not work".
-- `remits-cli components status` lists every lane staged on the branch, so you can see whether another
-  agent is working alongside you.
+- `remits-cli components status` lists every lane staged on the branch AND every lane on the account, so
+  you can see whether another agent is working alongside you. Each row names its world (trunk or variant
+  branch), its overlay, its workset where known, and whether it is the SHARED lane.
 - `remits-cli components clear --all` is scoped to YOUR lane and never touches another agent's.
 
+### 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.
+
+- The **overlay** is every staged entry the lane currently holds. It is what a CLI-scoped run resolves,
+  and it is the number the console shows as "staged".
+- The **workset** is what git reports this working tree changed. It is the work in flight.
+
+A plain `components stage` is a FULL SNAPSHOT: it uploads the whole repository manifest and reconciles
+the lane to it, so on a 115-component repo the overlay is 115 whether you edited five components or all
+of them. That is safe — it is a complete, known state — but it is a poor signal. Everyone reading the
+console sees a lane that looks like 115 edits in flight, and all 115 entries shadow committed source for
+every run in that lane until they expire.
+
+`components stage --workset` uploads only the changed components and reconciles the lane to exactly
+them, so the overlay IS the workset. That is the mode to iterate in.
+
+`components stage --changed-only` uploads the same narrow set but MERGES: it deliberately leaves every
+other staged entry alone. So it can never shrink a lane inherited from an earlier full snapshot — the
+overlay stays at 115 while you work on seven. The command warns when entries are retained that way.
+
+Every count is `unknown` rather than `0` when it cannot be established. "git could not answer" and "git
+says nothing changed" are different facts and only one of them is a number.
+
+**Deletion is not expressible here.** There is no staged removal: clearing a staged entry falls back to
+the committed row, so the component still resolves. `stage --workset` reports a deleted component file as
+NOT REPRESENTABLE rather than quietly omitting it. On a non-trunk variant branch, prove a deletion
+through the durable variant plan — `remits-cli components sync --dry-run --summary --fail-on-errors` —
+and read the removed/tombstone bucket. On trunk there is no dry-run plan; a deletion is only proven by
+the full pre-sync safety check before a mutating reconcile.
+
+**An empty workset never clears the lane.** `--workset` on a clean tree stages nothing and leaves the
+lane as it is; reconciling to an empty manifest would delete the overlay the next run depends on.
+Clearing stays explicit (`components clear --all`), or `--empty-workset clear` if that really is what you
+meant.
+
 ### Stage / sync / clear with remits-cli
 
-- `remits-cli components stage` writes local file changes into the Redis staging cache for the current
-  branch/user/workspace scope. This is the normal edit/test loop.
-- `remits-cli components stage --changed-only` stages just the components this working tree edited. It
-  does NOT reconcile, so entries for components it did not mention are left alone rather than deleted.
-  Useful on a large repo; a full stage is still the default and the safest.
-- `remits-cli components status` shows which branch/variant world the checkout resolves, plus staged entries,
-  staged fields, aliases, hashes, and TTLs. Use `--json` or `--verbose` for the full staged-entry payload.
+- `remits-cli components stage --workset` stages exactly what git says this working tree changed and
+  reconciles the lane to it. **The normal iteration mode.**
+- `remits-cli components stage` stages the whole repository manifest (a full snapshot). Use it for a
+  deliberate complete snapshot, when a `.meta.yml` key you deleted must be reconciled against the whole
+  repo, or as a "what is stale in here?" reset — then clear when you are done.
+- `remits-cli components stage --changed-only` stages just the changed components and does NOT reconcile,
+  so entries it did not mention are left alone rather than deleted. Kept as-is for compatibility;
+  `--workset` is the same narrow upload with the lane reconciled.
+- `remits-cli components status` shows which branch/variant world the checkout resolves, whether the lane
+  is shared, the overlay/workset/retained split with the last stage's mode, plus staged entries, staged
+  fields, aliases, hashes, and TTLs. Use `--json` or `--verbose` for the full staged-entry payload.
 - **A full `stage` makes the `.meta.yml` AUTHORITATIVE.** Staging layers a payload over what is already
   staged, which is what lets `mcp_component_edit` write a single field without blanking the others. But a
   `remits-cli components stage` sends the whole sidecar, so a key you DELETE from a sidecar is removed from