@remits/remits-cli 0.1.124 → 0.1.126

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.124",
+  "version": "0.1.126",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,
@@ -12,6 +12,7 @@
   "files": [
     "index.js",
     "README.md",
+    "scripts/prepare-index-toc.js",
     "skills/remits-cli/SKILL.md",
     "skills/remits-cli/references"
   ],
@@ -29,8 +30,10 @@
     "automation"
   ],
   "scripts": {
+    "prepare:index-toc": "node scripts/prepare-index-toc.js",
+    "prepack": "node scripts/prepare-index-toc.js",
     "start": "node index.js",
-    "test": "node --test test/*.test.js"
+    "test": "node scripts/prepare-index-toc.js --check && node --test test/*.test.js"
   },
   "dependencies": {
     "@stomp/stompjs": "^7.2.0",

package/scripts/prepare-index-toc.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+
+const indexPath = path.join(__dirname, '..', 'index.js');
+const cliSource = fs.readFileSync(indexPath, 'utf8');
+
+function functionSource(name) {
+  const declaration = new RegExp('(?:async\\s+)?function\\s+' + name + '\\s*\\([^)]*\\)\\s*\\{');
+  const match = declaration.exec(cliSource);
+  assert.notEqual(match, null, name + ' should exist');
+
+  const start = match.index;
+  let depth = 0;
+  for (let i = start + match[0].length - 1; i < cliSource.length; i += 1) {
+    if (cliSource[i] === '{') depth += 1;
+    if (cliSource[i] === '}') {
+      depth -= 1;
+      if (depth === 0) return cliSource.slice(start, i + 1);
+    }
+  }
+  assert.fail(name + ' body should be parseable');
+}
+
+const sandbox = vm.createContext({});
+vm.runInContext(
+  ['headingSlug', 'formatTocEntry', 'resolveTocEntry', 'resolveTableOfContentsLineNumbers']
+    .map(functionSource)
+    .join('\n'),
+  sandbox
+);
+
+const resolveTableOfContentsLineNumbers = vm.runInContext('resolveTableOfContentsLineNumbers', sandbox);
+const prepared = resolveTableOfContentsLineNumbers(cliSource);
+const check = process.argv.includes('--check');
+
+if (check) {
+  if (prepared !== cliSource) {
+    console.error('cli/index.js Table of Contents is stale. Run: npm run prepare:index-toc');
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+if (prepared !== cliSource) {
+  fs.writeFileSync(indexPath, prepared);
+  console.log('Updated cli/index.js Table of Contents line numbers.');
+}

package/skills/remits-cli/SKILL.md

@@ -74,7 +74,14 @@ reference named after it.
   (`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`)
+  it. Each agent works in its own **clone**, never a same-branch worktree: worktrees share the branch
+  ref, so one agent's pull moves `HEAD` under the others, and `components commit` refuses there.
+  (`component-resolution.md`)
+- **Land only from trunk or a real variant branch.** A per-agent/feature branch (`components status` says
+  `FEATURE BRANCH … [subscription-fallback]`) is safe to stage and run from — it resolves the same world
+  as its target — but `components commit`/`sync` refuse it. Merge into the branch it resolves and land
+  there; `--create-variant-branch` is only for deliberately creating a new variant branch.
+  (`branch-variants.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.
@@ -82,8 +89,12 @@ reference named after it.
 - **`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**
-  rows. Prefer the observable `git commit → git push → components sync → git pull`.
-  (`component-integrity.md`)
+  rows. Prefer the observable `git commit → git push → components sync → git pull`. On trunk it refuses
+  before any git write unless you pass `--yes`. (`component-integrity.md`)
+- **After anyone lands, ask whether your lane is stale: `remits-cli components status`.** A landing clears
+  only the lander's lane; yours keeps shadowing their new rows with content staged from the old base.
+  `LANDED SINCE YOUR BASE` / `STALE OVERLAY` mean pull, re-stage, then verify — a pass against a stale
+  lane proves nothing. (`component-resolution.md`)
 - **A component filename's numeric id prefix is load-bearing.** Renumber it and the next trunk sync
   creates a duplicate at the new id and hard-deletes the original. A live component whose files are
   missing from the repo at trunk-sync time is hard-deleted. Never renumber, rename across ids, or

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

@@ -44,13 +44,21 @@ Three facts that everything else follows from:
 
 ### Which world does your working tree resolve? (read this before you run anything)
 
-You will work from **two different checkouts of the same repo**, and they behave differently on both ends
-of the loop. The rule turns entirely on **trunk vs non-trunk**:
+You will work from **different checkouts of the same repo**, and they behave differently on both ends of
+the loop. **You only ever stage the edits you intend to test** — the world beneath them comes from the
+account, not from what you named your git branch:
 
 | Working tree | Staging scope | A run resolves | `components sync`/`commit` writes |
 |---|---|---|---|
 | **trunk** (`main`, or whatever `account-info.json` says) | that branch | trunk + **each account's subscribed** variant branch (production semantics) | the **live component rows** — full reconcile, creates/updates/**deletes** |
-| **any other branch** (`feature_branch`) | that branch | trunk + **`feature_branch`** overlays | **`ComponentVariant` overlays on that branch only** — never touches trunk rows |
+| **a variant branch** (it has committed variants, or an account subscribes to it — e.g. `forked`) | that branch | trunk + **that branch's** overlays | **`ComponentVariant` overlays on that branch only** — never touches trunk rows |
+| **any other branch** (`codex/x`, `feature/y`) | that branch | the **same world as trunk**: trunk + the account's subscribed branch (`forked` for its subscriber) | **refused** (`feature_branch_landing`) — merge into the branch it resolves and land from there |
+
+A branch like that is a **feature branch**, and it is safe to *run* from: stage only the components you edited,
+and runs still resolve every `forked` overlay for the subscriber. Do **not** stage untouched components to
+"restore" something reported missing — check `components status` first. It is never a place to *land* from.
+For parallel agents the preferred shape is still the real branch name plus a workspace; see
+`features/multi-agent-development.md` ("Per-agent git branches: safe to run, never to land").
 
 Do not infer this from the branch name. Ask:
 
@@ -61,12 +69,17 @@ remits-cli components status
 ```
 Working tree: VARIANT BRANCH "feature_branch"  (trunk is "main")
   runs resolve:   trunk + the 'feature_branch' variant overlays
+  variant world:  feature_branch  [branch-has-variants]
   commit writes:  ComponentVariant overlays on 'feature_branch' (never touches trunk rows)
   variants stored on this branch: 3
   subscribing accounts: 101 (Acme Child)
 ```
 
-**The precedence trap that costs the most time:** `variantBranch` **outranks every account's
+From a branch that is not a variant branch the header reads `FEATURE BRANCH` and `runs resolve` names the
+subscribed branch, tagged `[subscription-fallback]`. `test run`, `token` and `tool` responses carry the
+same `variantBranch` / `variantBranchSource` fields, and a verification envelope records that world.
+
+**The precedence trap that costs the most time:** a variant branch's world **outranks every account's
 subscription**. So running a Test suite that asserts *production* semantics from a **variant checkout**
 pins every account in that suite — including fixture accounts subscribed to their own generated branches —
 to your branch, where they have no variants, and they all read trunk. The suite fails in a way that looks
@@ -274,7 +287,8 @@ remits-cli components branch <name> --retire [--force]
 ```
 
 Branch administration commands act **as the account you are running from**, which is treated as the branch
-**owner** — run them from the owner's trunk checkout. Authorization is downward-only.
+**owner** — run them from the owner's trunk checkout. Authorization is downward-only. (`--retire` checks
+this and refuses from a non-owner; the read commands below resolve the owner for you.)
 
 - **`--subscribe` sets the branch on an edge that must already exist — it cannot create one.** Failure
   reads *"Account N has no relationship edge to subscribe; add a membership edge first"*. Create it with
@@ -295,7 +309,22 @@ Branch administration commands act **as the account you are running from**, whic
   subscriptions.
 - **Retiring is explicit.** Deleting the *git* branch does **not** remove its overlays; subscribers would
   keep resolving a branch that no longer exists. `--retire` refuses while subscribers remain unless you
-  pass `--force`.
+  pass `--force`, and it refuses (naming the owner) when run from any account other than the branch owner.
+- **Reads work from any checkout.** `components branch <name>` (status, `--diff`, `--subscribers`) and
+  `components promotion` resolve the branch owner the account actually resolves the branch from —
+  including an inherited subscription held by an ancestor — and report it as `branchOwnerAccountId`.
+  `components branches` lists branches this account OWNS; from a subscriber it also names the branch it
+  resolves and from whom. If `components status` prints `INHERITED BRANCH`, this account gets the branch
+  through an ancestor's subscription: a sync from here varies THIS account's own components (for it and the
+  accounts beneath it). To change the owner's components, work in the owner's repository on that branch.
+- **A commit must push to the repository the platform syncs.** `components status` names it (`sync reads
+  repository`). `components commit` refuses before any git write, and `components sync --safe` refuses,
+  when this checkout's `origin` is a different repository; a plain sync warns.
+- **Every prompt varies on a branch, including the README and agent prompts.** Edit the repo-root
+  `README.md`, an agent's `.md` in `components/agents/`, or a prompt in `components/prompts/` exactly as
+  you would any other component file: stage, verify, sync, and subscribers resolve it; merging to trunk
+  lands it. The README becomes an overlay of the account's README prompt (a branch without `README.md`
+  reverts to trunk's); an agent's prompt travels inside that agent's overlay.
 
 **Every component kind can be varied** — `schema`, `reader`, `action`, `embeddable`, `i18n`, `htmltemplate`,
 `rule`, `test`, `utility` (agent), `tool`, `prompt` — including tombstones and branch-only additions. A
@@ -367,7 +396,9 @@ branch that overlays it.
 
 **`components branches` only lists branches that already have overlays.** A branch you just pushed is
 invisible here until its first sync — that is not an error. Preview it by name (`components sync --dry-run`
-from that checkout).
+from that checkout). Its first real sync (or commit) needs `--create-variant-branch`: until a branch has
+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.
 
 **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

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

@@ -193,20 +193,20 @@ remits-cli listen [stop|status] [--foreground true]   # compatibility alias
 remits-cli data-mode [set test|prod]
 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 status [--branch <name>] [--component-type <type>] [--component-id <id>] [--json|--verbose]   # also: has anyone landed since this lane was staged (freshness)
 remits-cli components lanes [--json]                         # every indexed staging lane on the account
 remits-cli components entries --lane-id <id> [--json|--verbose]  # authoritative staged files for one lane
 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 [--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]   # phase 1 merge-stages + compile-validates changed source (never reconciles the lane); --safe gates sync writes
+remits-cli components sync [--safe [--yes]] [--branch <name>] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--create-variant-branch] [--summary] [--changed-only [--changed-since <ref>]]   # gated; on trunk = full repo->DB reconcile, on a variant branch = ComponentVariant overlays only
+remits-cli components commit [--yes] [--safe] [--allow-shared-branch] [--create-variant-branch] [--message|-m "msg"] [--data-mode test|prod] [--force-tombstones] [--json [--summary]]   # phase 1 merge-stages + compile-validates changed source (never reconciles the lane); on TRUNK refuses before any git write unless --yes; --safe gates variant sync writes
 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> [--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> --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>]
+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 token [--path <embeddablePathOrId>] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]
 remits-cli token inspect --token <token|tokenKey|URL>                  # inspect token metadata, safety/dataMode evidence, and full context
 remits-cli tools [--branch <name>] [--data-mode test|prod] [--variant-branch <name|none>]
@@ -316,16 +316,45 @@ For tests specifically:
   `--variant-branch none` when an existing staged cache on the real git branch would shadow committed trunk
   or variant rows. On `components sync` / `commit`, `--branch` is different: it names the GitHub branch to
   reconcile.
+- `--json` on `test run` prints exactly one JSON document to stdout: the final status/result. Safety
+  banners, start/progress lines, and websocket case progress go to stderr so shell callers can parse
+  stdout directly. The exit code is non-zero when the run fails, does not complete, or a requested case
+  selector matches nothing.
 - `--force-tombstones` is only for non-trunk variant syncs, when missing trunk component files are known,
   intentional tombstone overrides. It is rejected on trunk.
 - `--dry-run` is only for `components sync` on non-trunk variant branches. It reports the variant write
   plan without writing rows, caching the sync SHA, or clearing staging.
-- `--summary` on `components sync --dry-run` prints compact counts, removals/tombstones, skipped items, errors,
-  and warnings instead of the full override/add/remove payload.
+- `--summary` on `components sync` prints compact counts plus named updated (with the fields that
+  changed), renamed, skipped, removal/tombstone, error, and gate details instead of the full payload. A
+  trunk sync reports an untouched component under `unchanged`, not `updated`.
+- `--json` on `components stage`, `components sync`, `components commit`, and `tool` prints one
+  parseable JSON document to stdout. Safety banners and prose go to stderr, and sync safety-gate failures
+  are reported inside `gateViolations` with a non-zero exit code instead of appending prose after the JSON.
+- `components commit --json` prints the COMMIT outcome, not the sync's: `phase` (`stage` → `git` → `sync`
+  → `pull` → `complete`), `gitCommitted`, `pushed`, `pushedSha`, `synced`, `postSyncSha`, `pulled`, the
+  nested `sync` (summary with `--summary`), and on failure `error` + `nextStep`. It stops at the first
+  failed phase. `phase: "sync"` with `pushed: true` means the remote holds work the platform has not
+  reconciled — follow `nextStep`; do not re-run `components commit`.
+- `components commit` on trunk refuses before staging, committing, or pushing unless `--yes` is present —
+  with or without `--safe`. Trunk has no dry-run plan, so nothing can preview the full repo-to-DB reconcile.
+- `components commit` refuses before any git write while its branch is checked out in another worktree
+  (`sharedBranchWorktrees` in `--json`). Worktrees of one branch share its ref, so a stale one would commit
+  over landed work. Use one clone per agent; `--allow-shared-branch` overrides after `git status` is clean
+  apart from your own changes.
+- `components commit` refuses before any git write, and `components sync` refuses, on a **feature branch** — one
+  `components status` reports as `[subscription-fallback]` (no committed variants, no subscribers). Runs from
+  it resolve the subscribed branch; landing it would write overlays nobody subscribes to and flip every sibling
+  lane on that branch to them (`refusal: "feature_branch_landing"` in `--json`). Merge it into the branch it
+  resolves and land from there. `--create-variant-branch` overrides, for deliberately creating a NEW variant
+  branch (its first sync looks identical). `--dry-run` previews are never refused.
+- `components commit` refuses before any git write, and `components sync --safe` refuses, when this checkout's
+  `origin` is not the repository the platform syncs for the resolved account (`branchContext.repository` in
+  `components status`). A plain sync warns and reports `repositoryCheck`, including under `--summary`.
 - **Fail-closed sync gates.** On non-trunk variant branches these flags now force a server dry-run first,
   evaluate that plan before any overlay row is written, and only then run the mutating sync when the plan
   passes. On trunk, there is no safe dry-run plan, so do not treat these as scoped commit controls:
-  - `--changed-only` — fail unless every planned write is a component **this checkout actually changed**.
+  - `--changed-only` — fail unless every planned write is a component **this checkout actually changed**
+    (matched by type + id, type + name, or the repo file it came from — so a root `README.md` edit counts).
     This is the strongest guard against a sync that quietly rewrites components you never touched. It
     also fails when the checkout is not a git working tree, because "git could not answer" must never
     be read as "nothing changed".
@@ -388,6 +417,11 @@ 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.
 
+The repo-root `README.md` is staged as the account's README-purpose Prompt. It is part of the git workset
+for `components stage --workset`, even though it does not live under `components/`. It behaves like any
+other component on trunk AND on a variant branch: a variant sync stores a README change as an overlay of
+the README prompt, and an agent's `.md` in `components/agents/` travels with that agent's overlay.
+
 ### Prod banners and retryable failures
 
 - Every command that can touch production (`tool`, `test run`, `components sync`) prints a `PROD DATA`

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

@@ -115,6 +115,18 @@ Key implications:
   immediately syncs. Never run it while the tree contains drift or unexplained changes. Prefer the explicit,
   observable `components stage → git commit → git push → components sync → git pull` sequence so each
   phase can be inspected.
+- **`components commit` on trunk refuses before any git write unless `--yes` is present** — with or
+  without `--safe`, and with `--skip-git`. Trunk has no dry-run sync plan, so an explicit acknowledgement
+  is the only honest gate; the CLI must not create or push a commit and only then discover it.
+- **A commit that fails after the push says so.** `phase`, `pushed`, `pushedSha` and `nextStep` (in
+  `--json`, one document on stdout) tell you whether the remote now holds work the platform has not
+  reconciled. If it does, fix the cause and run `components sync` — do not re-run `components commit`.
+- **A commit refuses when the push and the sync would hit different repositories** — this checkout's
+  `origin` versus the repository the platform syncs for the account the command resolved. Fix the account
+  (account-info.json, `--account-id`) or run from the right checkout; never force it.
+- **A commit refuses while its branch is checked out in another worktree.** Worktrees of one branch share
+  its ref: a pull in one moves `HEAD` under the others, and `git add -A` from a stale one reverts work that
+  has already landed. Give each agent its own clone.
 - **`components sync` acts on the pushed remote**, so local edits are invisible to it until committed **and
   pushed**, and a drifted **remote** is dangerous even when your local tree looks fine.
 - **Runtime-compiled component source is validated before durable writes.** When a trunk sync or variant
@@ -165,14 +177,14 @@ file is catastrophic.
   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
+  > **Do not run this comparison against `account-info.json` alone — it can still be incomplete.** That
   > file omits `auxiliary: true` components by design, so every auxiliary component looks like a repo file
   > with no DB row, i.e. exactly the "a trunk sync will CREATE a duplicate" signal this check exists to
-  > catch. It also omits README- and AGENT-purpose Prompts, which live at the repo root and as `.md`
-  > sidecars in `components/agents/` rather than in `components/prompts/`, so they look like DB rows with
-  > no repo file — the "will be DELETED" signal. Both are benign. Before treating a flagged component as
-  > drift, confirm against the live row: `mcp_component_view`, or
-  > `mcp_run_action controlAction:"describe"` for an Action. A component that answers is not an orphan.
+  > catch. README- and AGENT-purpose Prompts are also intentionally absent from the `Prompts` collection:
+  > they live at repo-root `README.md` and as `.md` sidecars in `components/agents/`, not in
+  > `components/prompts/`. Before treating a flagged component as drift, confirm against the live row:
+  > `mcp_component_view`, or `mcp_run_action controlAction:"describe"` for an Action. A component that
+  > answers is not an orphan.
 - You can state the expected create/update/delete set. **If any delete or renumber is unexpected, stop.**
 
 ### If something looks wrong — stop, don't paper over

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

@@ -174,22 +174,21 @@ 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 fetch origin
+git clone <repository-url> repo-agent-a                  # one CLONE per agent, same branch
+cd repo-agent-a
 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
 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
+**A clone, not `git worktree add --force`.** Worktrees of one branch share its ref: a pull or commit in one
+moves `HEAD` under the others, and a `components commit` from a stale one reverts work that already landed.
+`components commit` refuses while its branch is checked out in another worktree (`--allow-shared-branch`
+overrides, only once `git status` shows nothing but your own changes). A stale clone is still stale: before
+the first edit in a new or reused clone, `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.
@@ -199,7 +198,7 @@ account, and the run still resolves whatever committed variant branch the accoun
 does **not** have the side effects of inventing a throwaway git branch per agent (which would make a
 commit write `ComponentVariant` overlays for a branch nobody subscribes to).
 
-- `.remits-cli/workspace` is per-checkout and gitignored, so each worktree keeps its own lane.
+- `.remits-cli/workspace` is per-checkout and gitignored, so each clone keeps its own lane.
 - Precedence: `--workspace NAME` > `REMITS_WORKSPACE` > `.remits-cli/workspace` > shared default lane.
 - `--no-workspace` targets the shared lane for one command without clearing the file.
 - Every stage / test run / token / clear prints its `Staging lane:` — if a change seems to have had no
@@ -211,6 +210,18 @@ commit write `ComponentVariant` overlays for a branch nobody subscribes to).
 - `remits-cli components lanes` is the review view across users/branches/workspaces, and
   `remits-cli components entries --lane-id <id>` is the drill-down into actual staged files.
 - `remits-cli components clear --all` is scoped to YOUR lane and never touches another agent's.
+- In lane rows, `currentLane` (also `mine`) marks THIS command's lane; `ownedByCaller` marks every lane
+  staged by your CLI user — your other clones' agents included.
+- **A landing clears only the lander's lane.** Every stage records the commit it came from
+  (`stageBaseSha`), and `components status` compares that with the last commit the platform synced for the
+  branch (`branchContext.lastSyncedSha`) using your local git:
+  - `LANDED SINCE YOUR BASE` — the platform synced a commit this checkout does not contain. Somebody landed
+    after you pulled: `git fetch origin && git pull --ff-only`, then re-stage.
+  - `STALE OVERLAY` — entries staged from a commit older than the last sync. They shadow rows that landed
+    after they were staged; re-stage with `--workset` or clear them.
+  - `--json` carries the same answer as `freshness` (`landedSinceHead`, `entriesBehindLastSync`, `stale`).
+    `null` means unknown — a lane staged by an older CLI, or a branch whose last sync is not recorded —
+    never "fresh".
 
 ### A lane holds an OVERLAY; your workset is a different number
 

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

@@ -354,7 +354,7 @@ Inspect individual lifecycle records with line-range or grep.
 | `recordType` | yes | `object`, `object_log`, `event`, or `alert` |
 | `recordId` | yes | Record primary key |
 | `field` | no | `content` (default) or `body` (objects only) |
-| `revisionId` | no | Envers revision ID (not for object_log) |
+| `revisionId` | no | Envers revision ID (not for object_log). Revision history does not retain `content`/`body`; omit it to read the current payload |
 | `lineRange` | no | `{start, end}` (1-based inclusive) |
 | `grep` | no | `{pattern, caseSensitive, contextBefore, contextAfter}` |
 

package/skills/remits-cli/references/troubleshooting.md

@@ -39,7 +39,8 @@
 | A custom hostname resolves to an unexpected account | Compare `resolution.domainName` with `resolvedDomainName` and the edge `domainName`s. An **edge** host wins over the account's own host and additionally supplies the path travelled (which is what makes that edge's branch variants apply). |
 | Need users of an account, accounts of a user, or account-scoped user fields | Use `mcp_account_user_admin` (`action:'users'`, `action:'user'`, or `action:'user_update'`). Use `mcp_sql_query` on `user` / `user_account` only for raw join-table investigation. Remember user custom fields are stored **per bound account**, so the same person can differ per account. |
 | One account behaves differently from its siblings on the same component | It probably subscribes to a **branch variant**. Check `remits-cli components branches` and `remits-cli components branch <name> --subscribers`, and reproduce with `remits-cli test run --as-account <ID>`. Do NOT "fix" this by adding per-account logic to the origin component. |
-| Edits on a feature branch seem to run against trunk code | You are likely on the **trunk** branch, or passed `--variant-branch none`. Run `remits-cli components status` — it states which world the working tree resolves. |
+| Edits on a feature branch seem to run against trunk code | A branch with no committed variants and no subscribers resolves the account's **subscription** (trunk, if it subscribes to nothing) beneath what you staged — `components status` shows `FEATURE BRANCH … [subscription-fallback]` and names the world. To see a specific branch's overlays, run from that branch's checkout or pass `--variant-branch <name>`. |
+| `components commit`/`sync` refused with `feature_branch_landing` | The branch is a feature branch, not a variant branch. Merge it into the branch the message names and land from that checkout. Do **not** pass `--create-variant-branch` to get past it — that flag deliberately creates a new variant branch nobody subscribes to. |
 | A component vanished for one account after a variant-branch sync | Its file is missing from that branch, so the sync created a **tombstone** that hides it from subscribers. Restore the file on the branch and re-sync. Trunk is unaffected. |
 | A variant Test suite fails wholesale, asserting trunk where you expect a variant | You are almost certainly running it from a **variant checkout**: `variantBranch` outranks every subscription, so the suite's own fixture accounts resolve YOUR branch. Re-run from trunk or with `--variant-branch none` before treating it as a regression. |
 | `components sync` on a branch says "No changes detected" but trunk has moved | Re-run it; a trunk sync now invalidates the branch's cached verdict. If it still skips, the branch genuinely matches trunk - check `components branch <name>` for what is actually stored. |