@remits/remits-cli 0.1.115 → 0.1.117

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.115",
+  "version": "0.1.117",
   "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**
@@ -84,6 +97,10 @@ reference named after it.
 - **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
@@ -104,6 +121,11 @@ 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`)
 - **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.
@@ -139,11 +161,14 @@ 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)
 ```
 
 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.
 
 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/command-reference.md

@@ -15,6 +15,8 @@
   - [Hierarchy-scoped tool reads](#hierarchy-scoped-tool-reads)
   - [Data Mode](#data-mode)
 - [Command Reference](#command-reference)
+  - [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)
 
 ## Getting Started
@@ -189,12 +191,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]
@@ -208,8 +210,86 @@ remits-cli token inspect --token <token|tokenKey|URL>                  # inspect
 remits-cli tools [--branch <name>] [--data-mode test|prod] [--variant-branch <name|none>]
 remits-cli tool --name <toolName> [--branch <name>] [--input "{...}"] [--data-mode test|prod] [--variant-branch <name|none>] [--timeout-ms 60000] [--async true --wait true]
 remits-cli tool status --call-id <callId> [--data-mode test|prod]
+remits-cli verify start --summary "..." [--manifest file.json] [--ticket ID]
+remits-cli verify use <envelopeId>
+remits-cli verify current
+remits-cli verify clear
+remits-cli verify show [--envelope ID] [--json]
+remits-cli verify manifest --file file.json [--envelope ID]
+remits-cli verify manifest --print [--envelope ID]
+remits-cli verify attach --artifact path --label "..." [--envelope ID]
+remits-cli verify attach --screenshot path --label "..." [--envelope ID]
+remits-cli verify attach --note "..." [--envelope ID]
+remits-cli verify browser-start --url URL [--label "..."]
+remits-cli verify browser-step [--action click|fill|upload|reload|observe|...] [--target "..."] [--value "..."] [--url URL] [--label "..."]
+remits-cli verify browser-snapshot [--url URL] [--label "..."]
+remits-cli verify stage --workset
+remits-cli verify test --test <id|name> [--names "case"]
+remits-cli verify token --path <embeddablePathOrId>
+remits-cli verify sync --safe
+remits-cli verify tool --name <toolName> [--input "{...}"]
+remits-cli verify status [--envelope ID]
+remits-cli verify report [--envelope ID]
 ```
 
+### 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:
+
+```bash
+remits-cli workspace use --auto
+remits-cli components status
+remits-cli verify start --summary "Hosted upload updates an existing profile" --manifest acceptance.json
+```
+
+An active envelope is stored in `./.remits-cli/verification/active`. Stage/test/token/tool/sync commands
+attach evidence automatically while an envelope is active. The explicit wrappers do the same thing and
+make the intent visible in terminal history:
+
+```bash
+remits-cli verify stage --workset
+remits-cli verify test --test "Adyen Import Recovery" --names "browser upload recovery"
+remits-cli verify token --path /page/pricing-config --as-account 21 --data-mode test
+remits-cli verify sync --safe
+remits-cli verify report
+```
+
+Existing commands also accept `--verify-envelope <id>` to attach to a specific envelope and
+`--no-verify-envelope` to suppress automatic attachment for one command.
+
+The manifest is the proof contract. It should name the world being exercised: repo account, host,
+git/component branch, workspace, data mode, source layer, user journeys, artifacts and hashes, and the
+evidence categories required before the final response may claim the work is done. If the manifest
+cannot be written because the workflow is ambiguous, ask before implementation. For machine-gated report
+requirements, prefer structured entries like `{"id":"actual_upload","packetType":"browser_step",
+"category":"browser_session.actual_upload"}`. Plain strings work when they match a packet type or an
+evidence category, but structured entries are clearer when several agents collect packets for one
+envelope.
+
+Common packet meanings:
+
+| Packet | It proves | It does not prove by itself |
+|---|---|---|
+| `stage` | Which components were uploaded to the staging lane, including workset vs overlay | The requested behavior works |
+| `component_status` | Which source world and lane are currently staged or clean | Any behavior was exercised |
+| `test_run` | A Test component passed in the recorded account/branch/workspace/data lane | A hosted browser journey unless that Test actually drove it |
+| `token_inspect` | A token was minted/inspected for a specific account, source layer, and lane | A user clicked through the page |
+| `browser_session` / `browser_step` / `browser_snapshot` | The browser journey was opened or observed with named actions | Server-side persistence unless paired with assertions or follow-up state checks |
+| `tool_call` | A platform tool ran in the recorded world and returned the recorded result | User-visible behavior unless the tool is the requested entry point |
+| `sync_dry_run` | The planned durable writes and safety gates | Anything was written |
+| `sync_mutation` | Durable source moved to trunk or variant and returned a sync SHA | The committed source behaves after staging is cleared |
+| `artifact` | A file/screenshot/note exists with path, size, and sha256 | The workflow consumed it |
+
+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
+click/upload/reload flow.
+
 For tests specifically:
 - 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
@@ -251,8 +331,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-resolution.md

@@ -10,11 +10,13 @@
 
 - [Component Resolution: Staging Cache vs DB (which "version" actually runs)](#component-resolution-staging-cache-vs-db-which-version-actually-runs)
   - [The three source layers + the compile cache](#the-three-source-layers--the-compile-cache)
+  - [Verification envelopes record the source layer](#verification-envelopes-record-the-source-layer)
   - [Staging cache key format](#staging-cache-key-format)
   - [How the platform picks staged vs DB (the compile signature)](#how-the-platform-picks-staged-vs-db-the-compile-signature)
   - [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)
 
@@ -47,6 +49,18 @@ Plus the compile cache:
   cache of the parsed closure, keyed by `(componentId, type, compileSignature)`. This is why a change that
   is correctly in the DB can still execute stale on a running instance — see "Stale after sync" below.
 
+### Verification envelopes record the source layer
+
+When a verification envelope is active, `components stage`, `components status`, `test run`, `token`,
+`tool`, and `components sync` attach evidence packets with the branch/workspace/staging lane and the best
+source-layer facts the command observed. A staged test packet is proof of the staged layer; a sync packet
+is proof of a source transition; a token packet is proof of the browser token's resolution tuple. Those
+are not interchangeable.
+
+Use `remits-cli verify report` before summarizing the work. It will naturally say when the evidence only
+covered staged source, when committed variant/trunk proof is missing, or when evidence became stale after
+the git head, overlay, or platform sync moved.
+
 ### Staging cache key format
 
 ```
@@ -184,19 +198,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

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

@@ -10,17 +10,21 @@
 
 - [Two Workflows](#two-workflows)
   - [Test Mode vs Prod Mode](#test-mode-vs-prod-mode)
+- [Verification Envelopes](#verification-envelopes)
 - [Development Workflow](#development-workflow)
   - [The Golden Rule: Writing Code Is Not Finishing the Job](#the-golden-rule-writing-code-is-not-finishing-the-job)
   - [The Development Fast Loop](#the-development-fast-loop)
     - [Step 1: Understand the Request](#step-1-understand-the-request)
     - [Step 2: Make the Change](#step-2-make-the-change)
     - [Step 3: Stage to Platform](#step-3-stage-to-platform)
+      - [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)
     - [Step 5: Iterate If Needed](#step-5-iterate-if-needed)
     - [Step 6: Update Documentation](#step-6-update-documentation)
     - [Temporary Experiment Workflow](#temporary-experiment-workflow)
     - [Step 7: Commit and Durable Sync](#step-7-commit-and-durable-sync)
+      - [Verifying the COMMITTED variant, not your staging](#verifying-the-committed-variant-not-your-staging)
     - [Step 8: Close the Ticket](#step-8-close-the-ticket)
   - [User Confirmation Preferences](#user-confirmation-preferences)
 
@@ -63,6 +67,36 @@ The right model is:
 
 Never treat "it looks right in prod data inspection" as sufficient proof that a code change is verified.
 
+## Verification Envelopes
+
+For a concrete user workflow, browser-facing change, branch-variant release, support ticket, or any loop
+where earlier manual testing found a gap, start a verification envelope before editing:
+
+```bash
+remits-cli verify start --summary "Hosted upload updates an existing profile" --manifest acceptance.json
+```
+
+The envelope records the account, host, data lane, branch, workspace, git heads, staging lane, and the
+acceptance manifest. It is mirrored locally under `.remits-cli/verification/<envelopeId>/` and becomes
+active for this checkout. While active, `components stage`, `components status`, `test run`, `token`,
+`token inspect`, `tool`, and `components sync` attach evidence packets automatically; pass
+`--verify-envelope <id>` to name one explicitly or `--no-verify-envelope` when a command should not be
+attached.
+
+Use the wrappers when you want the intent to be unmistakable:
+
+```bash
+remits-cli verify stage --workset
+remits-cli verify test --test "Suite" --names "case name"
+remits-cli verify token --path /page/example
+remits-cli verify sync --safe
+remits-cli verify attach --artifact sample.zip --label "user supplied ZIP"
+remits-cli verify report
+```
+
+The report is the final-response source. It separates verified claims, missing evidence, stale packets,
+and the source/account/lane tuple, so do not replace it with a generic "verified" sentence.
+
 ## Development Workflow
 
 ### The Golden Rule: Writing Code Is Not Finishing the Job
@@ -121,6 +155,10 @@ 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.
+
 #### Step 2: Make the Change
 Edit component files under `components/`. This is local file editing — the platform doesn't know about your changes yet.
 
@@ -174,10 +212,63 @@ overlay instead of pruning cleanly.
 #### Step 3: Stage to Platform
 
 ```bash
-remits-cli components stage
+remits-cli workspace use --auto          # once per checkout: your own lane
+remits-cli components stage --workset    # every edit: stage what you changed
 ```
 
-This uploads your local file changes to the platform's staging cache (Redis, 240-minute TTL). It does NOT commit anything. The platform cannot see your local edits until you stage them.
+This uploads your local component changes to the platform's staging cache (Redis, 240-minute TTL). It does NOT commit anything. The platform cannot see your local edits until you stage them.
+
+##### Stage your workset, not the whole repo
+
+There are three stage modes, and the difference decides what a run in your lane resolves and what a
+human watching the console sees:
+
+| Command | What it uploads | What the lane holds afterwards |
+|---|---|---|
+| `components stage --workset` | only the components git reports changed | **exactly those** — the lane is reconciled to your workset |
+| `components stage` | the whole repository manifest | **every component in the repo** (a full snapshot) |
+| `components stage --changed-only` | only the changed components | the changed ones **merged into whatever was already there** |
+
+**Use `--workset` for normal iteration.** A full stage is correct and safe, but on a real repository it
+puts a hundred-plus components into your lane, and every one of them then shadows committed source for
+any run in that lane until it expires. A human looking at `/admin/platforms` sees "115 staged" and cannot
+tell whether you edited 115 components or five.
+
+`--changed-only` MERGES. It cannot shrink a lane it inherited from an earlier full stage, so a lane can
+sit at 115 overlay entries while you are working on seven. The command warns when that happens; the fix
+is `--workset` (or `components clear --all` once, then keep using `--workset`).
+
+**When a full stage is the right answer:**
+
+- you deliberately want a complete snapshot of the repo in the lane;
+- you changed a `.meta.yml` sidecar and want removed keys reconciled against the whole repo;
+- you cannot tell what is stale in the lane and want a clean, known state (then `components clear --all`
+  when you are done).
+
+**An empty workset never clears your lane.** `--workset` on a clean working tree stages nothing and
+leaves the lane alone — reconciling to an empty manifest would delete the overlay your next test run
+depends on. Clearing stays explicit: `components clear --all`.
+
+**Deleting a component file cannot be verified by staging.** There is no staged "removal": clearing a
+staged entry falls back to the committed row, so the component still resolves. `stage --workset` reports
+those changes as NOT REPRESENTABLE.
+
+On a non-trunk variant branch, prove the removal 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; treat deletion as a high-risk durable reconcile and pass the full
+pre-sync safety check before running any mutating sync.
+
+##### Three numbers, three questions
+
+`components stage` and `components status` report all three, and so does the admin console. They are not
+interchangeable:
+
+- **workset** — components git reports this working tree changed. The work in flight.
+- **submitted** — what this command uploaded.
+- **overlay** — every staged entry the lane now holds. **This is what a run resolves.**
+
+A missing answer is printed as `unknown`, never as `0`: "git could not answer" and "git says nothing
+changed" are different facts and only one of them is a number.
 
 **THE STAGE-BEFORE-RUN RULE:** You MUST run `remits-cli components stage` after EVERY file edit and BEFORE any test run or verification. The platform executes whatever version is in the staging cache at the moment the test starts. If you edit a file and run a test without staging first, the test runs the OLD code — not your changes. This is the single most common mistake. Never skip staging. The sequence is always: **edit → stage → run**.
 
@@ -310,13 +401,16 @@ Redis cache can affect later test/tool runs, so always clear it after restoring
 
 ```bash
 # make temporary local edit
-remits-cli components stage
+remits-cli components stage --workset
 remits-cli test run --test <id-or-name> --names "<case name>"
 git restore <file>
 remits-cli components clear --all
 remits-cli components status
 ```
 
+With `--workset` the restore-and-clear is belt and braces rather than the only thing standing between
+the experiment and a later run: the lane only ever held the component you were experimenting on.
+
 For narrower cleanup when only one staged component should be cleared:
 
 ```bash
@@ -352,10 +446,41 @@ IDs or when unexpected deletes/renumbers are present.
 Only after those checks pass, and only when the user intends to promote the repo to the platform database:
 
 ```bash
+# On a VARIANT branch — the recommended path. Dry-runs first and refuses a surprising plan.
+remits-cli components sync --safe
+git pull --ff-only origin <branch>
+
+# On TRUNK — there is no plan to gate, so --safe explains what a trunk reconcile does and needs --yes.
 remits-cli components sync
 git pull --ff-only origin <branch>
 ```
 
+`--safe` expands to `--summary --changed-only --fail-on-errors --fail-on-removed`, resolves the
+comparison base from this branch's merge base with trunk when you did not pass `--changed-since`, and
+prints the planned writes before mutating unless you pass `--yes`. It refuses when the plan would write
+components this checkout did not change — which is exactly what a branch that is BEHIND trunk produces,
+because it still physically carries old copies of files nobody on it touched, and a variant sync turns
+each of those into an unrelated override. When it refuses that way, merge trunk into your branch, push,
+and re-run the same command.
+
+When a removal is intended, name it rather than disabling the gate:
+
+```bash
+remits-cli components sync --safe --expected-removed action:50
+```
+
+`--force-tombstones` stays explicit and human-owned. Never pass it to get past a refusal.
+
+##### Verifying the COMMITTED variant, not your staging
+
+After a sync, staged entries still win for CLI-scoped runs, so a test that passes may be testing your
+staging rather than what you just committed. Clear the lane first:
+
+```bash
+remits-cli components clear --all
+remits-cli test run --test <id-or-name> --as-account <subscriber-id>
+```
+
 `remits-cli components sync` is the authoritative platform-sync step. It does not perform local git operations,
 and it is capable of reconciling creates/deletes/renames from the remote repository into the database. Treat it
 as a gated promote/reconciliation command, not as an exploratory command or fallback.

package/skills/remits-cli/references/support-tickets.md

@@ -17,6 +17,7 @@
   - [Before you edit anything: where you are, and whether you may](#before-you-edit-anything-where-you-are-and-whether-you-may)
   - [Your account's process is binding, and it is already in your brief](#your-accounts-process-is-binding-and-it-is-already-in-your-brief)
   - [Some of that process is enforced, not requested](#some-of-that-process-is-enforced-not-requested)
+  - [Verification envelopes on tickets](#verification-envelopes-on-tickets)
   - [Seeing the queue as a human does](#seeing-the-queue-as-a-human-does)
   - [Agent components are workers too](#agent-components-are-workers-too)
   - [Moving a ticket through its lifecycle](#moving-a-ticket-through-its-lifecycle)
@@ -191,6 +192,26 @@ start.
 `--data-mode test` registers a fixture agent instead, which will never be routed a production ticket —
 use it only when you are deliberately testing the routing itself.
 
+### Verification envelopes on tickets
+
+For ticket work that changes component behavior, especially browser workflows, branch variants, release
+gates, or a previously failed manual loop, start an envelope tied to the ticket:
+
+```bash
+remits-cli verify start --ticket 22454 --summary "Fix hosted upload recovery"
+```
+
+Keep it active while you stage, run Tests, mint browser tokens, call tools, and sync. Those commands
+attach evidence packets to the platform envelope and mirror them locally under `.remits-cli/verification/`.
+Before completing or handing off the ticket, run:
+
+```bash
+remits-cli verify report
+```
+
+Use that output in the ticket update. It names what was verified, what is still missing, and whether the
+proof covered staged source or committed source.
+
 ### If you are the worker
 
 You know you are one when `REMITS_SUPPORT_TICKET_ID` is set in your environment. Your whole job is