@remits/remits-cli 0.1.113 → 0.1.114

package/skills/remits-cli/SKILL.md

@@ -5,3566 +5,157 @@ description: Use remits-cli for fast branch-scoped component staging, test execu
 
 # remits-cli
 
-## Table of Contents
+`remits-cli` is how a local agent talks to the Remits platform: it stages component source for
+server-side execution, runs Test components, mints embeddable browser tokens, reconciles a repo into
+the live component database, calls the server-side investigation tools, and carries the support-ticket
+lifecycle.
 
-- [Account Targeting Model](#account-targeting-model)
-  - [Read the shape first](#read-the-shape-first)
-  - [Which repo does the work belong in](#which-repo-does-the-work-belong-in)
-  - [Repo selection rules](#repo-selection-rules)
-- [Component Integrity Rules: Repo ↔ Database Reconciliation (read before any sync/commit)](#component-integrity-rules-repo--database-reconciliation-read-before-any-synccommit)
-  - [How the platform reconciles the repo into the database (the mechanism you must understand)](#how-the-platform-reconciles-the-repo-into-the-database-the-mechanism-you-must-understand)
-  - [The surfaces and their intended behavior](#the-surfaces-and-their-intended-behavior)
-  - [Intended workflows](#intended-workflows)
-  - [Pre-sync safety check (confirm ALL before `components sync` or `components commit`)](#pre-sync-safety-check-confirm-all-before-components-sync-or-components-commit)
-  - [If something looks wrong — stop, don't paper over](#if-something-looks-wrong--stop-dont-paper-over)
-- [Required Local Index Reads](#required-local-index-reads)
-- [Big Picture: How remits-cli State Is Organized](#big-picture-how-remits-cli-state-is-organized)
-- [Support Ticket Mental Model](#support-ticket-mental-model)
-  - [You are an agent, and you register yourself](#you-are-an-agent-and-you-register-yourself)
-  - [Autonomous: one ticket, one process](#autonomous-one-ticket-one-process)
-  - [If you are the worker](#if-you-are-the-worker)
-  - [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)
-  - [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)
-  - [When a worker needs a decision from a human](#when-a-worker-needs-a-decision-from-a-human)
-  - [The manual loop](#the-manual-loop)
-- [Efficiency Rules](#efficiency-rules)
-- [Account Repository Index](#account-repository-index)
-- [Two Workflows](#two-workflows)
-  - [Test Mode vs Prod Mode](#test-mode-vs-prod-mode)
-- [The Investigation Model](#the-investigation-model)
-  - [Which tool reads which record](#which-tool-reads-which-record)
-  - [Correlation keys](#correlation-keys)
-  - [Reading a record's `content` — persisted context, not a memory dump](#reading-a-records-content--persisted-context-not-a-memory-dump)
-  - [HTTP audits](#http-audits)
-  - [AI activity](#ai-activity)
-  - [Node Reference Table](#node-reference-table)
-  - [Runtime node and `localMode`](#runtime-node-and-localmode)
-- [Getting Started](#getting-started)
-  - [Authentication](#authentication)
-  - [Host vs Data Mode](#host-vs-data-mode)
-  - [Tool Execution Lifecycle](#tool-execution-lifecycle)
-  - [Data Mode](#data-mode)
-- [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)
-    - [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)
-    - [Step 8: Close the Ticket](#step-8-close-the-ticket)
-  - [User Confirmation Preferences](#user-confirmation-preferences)
-- [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)
-  - [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)
-  - [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)
-- [Account Resolution: how a request travels the account graph](#account-resolution-how-a-request-travels-the-account-graph)
-  - [Seeing an account's edges](#seeing-an-accounts-edges)
-  - [When a subscription "doesn't work"](#when-a-subscription-doesnt-work)
-  - [The same block answers the non-branch questions](#the-same-block-answers-the-non-branch-questions)
-- [Branched Component Variants (per-account component overrides)](#branched-component-variants-per-account-component-overrides)
-  - [Which world does your working tree resolve? (read this before you run anything)](#which-world-does-your-working-tree-resolve-read-this-before-you-run-anything)
-  - [Two levers, two different questions](#two-levers-two-different-questions)
-  - [The SDLC is identical on a variant branch](#the-sdlc-is-identical-on-a-variant-branch)
-  - [Subscribing, unsubscribing, retiring](#subscribing-unsubscribing-retiring)
-  - [Danger profile on a variant branch (different, not absent)](#danger-profile-on-a-variant-branch-different-not-absent)
-  - [Inspecting branches and drift](#inspecting-branches-and-drift)
-  - [Diagnosing a variant](#diagnosing-a-variant)
-- [Production Support Workflow](#production-support-workflow)
-  - [Investigation Strategy](#investigation-strategy)
-  - [Presenting Findings](#presenting-findings)
-  - [Verifying a Production Issue Fix](#verifying-a-production-issue-fix)
-- [Tool Reference](#tool-reference)
-  - [Execute a Tool](#execute-a-tool)
-  - [`mcp_account_view`](#mcp_account_view)
-  - [`mcp_account_user_admin`](#mcp_account_user_admin)
-  - [`mcp_firestore_search`](#mcp_firestore_search)
-  - [`mcp_firestore_patch`](#mcp_firestore_patch)
-  - [`mcp_object_activity`](#mcp_object_activity)
-  - [`mcp_record_listing`](#mcp_record_listing)
-  - [`mcp_record_view`](#mcp_record_view)
-  - [`mcp_ai_session_search`](#mcp_ai_session_search)
-  - [`mcp_run_action`](#mcp_run_action)
-    - [Stopping a run — `controlAction:'interrupt'`](#stopping-a-run--controlactioninterrupt)
-  - [`mcp_run_agent`](#mcp_run_agent)
-    - [Controlling a live agent — `pause` / `unpause` / `interrupt`](#controlling-a-live-agent--pause--unpause--interrupt)
-  - [`mcp_system_logs`](#mcp_system_logs)
-  - [`mcp_user_activity`](#mcp_user_activity)
-  - [`mcp_performance_trace`](#mcp_performance_trace)
-  - [`mcp_event_diagnostics`](#mcp_event_diagnostics)
-  - [`mcp_component_view`](#mcp_component_view)
-  - [`mcp_component_grep`](#mcp_component_grep)
-  - [`mcp_support_ticket`](#mcp_support_ticket)
-  - [Component branches](#component-branches)
-  - [`mcp_cache`](#mcp_cache)
-  - [`mcp_sql_query`](#mcp_sql_query)
-  - [`mcp_index_search`](#mcp_index_search)
-  - [`mcp_get_guide`](#mcp_get_guide)
-  - [`mcp_test_fixture`](#mcp_test_fixture)
-  - [`mcp_playwright_replay`](#mcp_playwright_replay)
-  - [`mcp_jvm_spike_triage`](#mcp_jvm_spike_triage)
-  - [`mcp_support_ticket_queue`](#mcp_support_ticket_queue)
-- [Multi-Session Support](#multi-session-support)
-- [Registering This Session As An Agent](#registering-this-session-as-an-agent)
-  - [What registration actually does](#what-registration-actually-does)
-  - [What `serve` adds](#what-serve-adds)
-  - [Resolving which agent a command means](#resolving-which-agent-a-command-means)
-  - [Which agent gets a ticket](#which-agent-gets-a-ticket)
-  - [Why a routed ticket might not have started](#why-a-routed-ticket-might-not-have-started)
-- [Background Service and Control Center](#background-service-and-control-center)
-  - [Control Center](#control-center)
-  - [Configuring the Preferred Agent](#configuring-the-preferred-agent)
-- [Local State Files](#local-state-files)
-- [Command Reference](#command-reference)
-  - [Prod banners and retryable failures](#prod-banners-and-retryable-failures)
-- [Troubleshooting](#troubleshooting)
-  - [When Something Doesn't Work as Expected](#when-something-doesnt-work-as-expected)
-    - [Escalation Bundle (tooling/operational issue)](#escalation-bundle-toolingoperational-issue)
+This file is the **index and the rules**. It is deliberately short so it can be loaded in full every
+session. Everything else — the mechanics, the failure modes, and the exact command and tool surface —
+lives in the reference files listed below, which ship with the CLI and are read on demand.
 
-## Account Targeting Model
+## How to read this skill
 
-**Establish the account's shape before you touch anything.** Which repo you work in, which account you run
-against, and where a fix belongs are answered by the account's structure — never by its name.
+**The reference files are here:**
 
-The account model itself — types, component inheritance, primary vs membership edges, the three independent
-edge properties, the user model — is in the always-loaded `platform-overview.md` and in depth in
-`features/account-management.md` (`mcp_get_guide`). What follows is only what changes **what you type**.
+`{{SKILL_REFERENCES_DIR}}`
 
-### Read the shape first
+Every reference named below is a file in that directory. Two mechanics make loading one cheap, and you
+are expected to use both:
 
-`account-info.json` (in a repo) and `mcp_account_view` (remotely) both carry a `resolution` block — the one
-place these facts appear. Field-by-field detail is under **`mcp_account_view`** in the Tool Reference. The
-four that decide a CLI action:
+1. **Each reference opens with a table of contents carrying real line numbers** — `- L412  Diagnosing a
+   variant`. The numbers are resolved when the CLI installs the file, so they are never stale, and each
+   entry is the heading verbatim, so it also greps.
+2. **Therefore: read the head of the reference, choose your sections, then offset-read only those.**
+   `tool-reference.md` alone is around a thousand lines. Loading a whole file because you needed forty
+   lines of it is the most common way an agent runs out of room to do the actual work.
 
-| Read | To decide |
-|---|---|
-| `role` + `summary` | `OWNER` (the files here **are** its components) vs `SUBSCRIBER` (it resolves another account's components under a variant branch). Read this before you touch anything. |
-| `type` | whether this repo is where the change belongs — see below |
-| `resolvedDatabaseName` | where its data actually lands. **Check this first when documents are "missing".** |
-| `relationships` | every link upward, primary first, each with its own `branchName` / `databaseName` / `domainName`. **More than one entry means the account can legitimately resolve differently depending on the path a request travelled** — establish which one a failing request used before comparing behavior. |
+**Naming a reference is not reading it.** These files exist because the behavior they describe is not
+guessable from the command names. An agent that skips one does not fail loudly — it proceeds on a
+plausible assumption and produces work that looks finished and is not. When a task is governed by a
+reference below, load it before you act, not after something surprises you.
 
-Two more, easily confused: top-level **`componentBranches`** lists the variant branches this account
-**owns**, with drift and subscriber counts — check it before editing a shared component. And
-`resolution.branchName` is the **repo's trunk sync branch**, *not* a component-variant branch.
+## Which reference, and when
 
-### Which repo does the work belong in
-
-| Situation | Target |
-|---|---|
-| Feature, enhancement, shared behavior fix | usually the owning `PLATFORM` / `PRODUCT` account — **not** the `CLIENT` that reported it |
-| Production investigation, client-specific data issue | the affected `CLIENT` account's data and runtime history |
-| Both | confirm the symptom on the `CLIENT`, then move to the owning repo to change code |
-
-### 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`.
-- **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
-  explicitly asks you to clone one.
-
-For access questions — "who can see this client account?", "why does this user see the wrong data?" — use
-`mcp_account_user_admin` first (`action:'users'`, `action:'user'`, or `action:'user_update'`). Use
-`mcp_sql_query` only when you need raw join-table investigation. Remember a user's custom fields are stored
-**per bound account**, so the same person can differ per account.
-
-**Test-data flags are first-class safety evidence.** `Account.testAccount` and `User.testUser` are set by
-the `account(...)` / `user(...)` factories when the execution data lane is `test` (which is how
-`mcp_account_user_admin` creates); direct inserts such as `new Account(...).save()` are also flagged by the
-domain `beforeInsert` hook in the test lane. Prod-data creates leave them false. Updating an existing real
-account/user in test mode does not convert it into test data, though its Firestore extension-field writes
-still go to the test lane. `Object.testMode` /
-`Event.testMode` / `Alert.testMode` (and `testMode` inside test-lane Audit documents) identify lifecycle
-rows in the test data lane. Agent-facing surfaces expose these fields:
-
-- `account-info.json`, `account-hierarchy.json`, and `mcp_account_view`: `resolution.testAccount` for the
-  described account, and `testAccount` on returned hierarchy nodes.
-- `mcp_account_user_admin`: `testAccount` on `hierarchy`, `account`, and `account_create` results;
-  `testUser` on `users` / `user` results.
-- `mcp_record_listing`: top-level `dataMode` (the lane it searched — listings are **filtered** by lane,
-  so `totalItems:0` in the wrong lane reads exactly like "no such record"), plus `testMode` per record.
-- `mcp_record_view`: `record.dataMode` (the lane read in) next to `record.testMode` (the lane the row
-  belongs to). This one loads **by id and does not filter**, so those two can legitimately disagree —
-  and when they do, that is the finding.
-- `mcp_object_activity`: top-level `dataMode`, `object.testMode`, and `testMode` on Event/Alert
-  timeline entries.
-- `mcp_event_diagnostics`: top-level `dataMode` and `result.event.testMode`.
-- `remits-cli token inspect`: owner `account.testAccount` and `user.testUser`, plus a `safety` block
-  carrying `dataMode`, `dataModeDeclared`, and an explicit warning when the token does not declare one.
-- `remits-cli whoami`: the resolved account / user / branch / lane / host tuple for the **next tool
-  call**. It does not describe `remits-cli test run`, which ignores the stored session lane — see below.
-
-Two surfaces deliberately have **no** lane flags, and both mislead if you forget it:
-
-- **`mcp_sql_query` reads MySQL directly and is lane-blind.** `object` / `event` / `alert` come back with
-  **both lanes mixed**, and `user` / `account` with test fixtures mixed into real records. Filter
-  explicitly — `test_mode = 0`, `test_user = 0`, `test_account = 0` — or use the purpose-built tool.
-- **Persisted AI session rows** store no durable per-grouping `testMode` / `dataMode`. Use
-  `mcp_ai_session_search.dataMode` as the current execution lane only, never as proof of the historical
-  grouping's lane.
-
-If any of those fields contradict the lane you intended, stop and rerun the command with an explicit
-`--data-mode test` or `--data-mode prod`. Never infer prod/test from an account name, URL, branch name, or
-the mere existence of a created account.
-
-**A tool's `dataMode` input never widens the lane.** Tools that accept a `dataMode` argument clamp it
-against the lane the *command* was launched with: it may narrow `prod` -> `test`, never escalate
-`test` -> `prod`. So `--data-mode test --input '{"dataMode":"prod"}'` stays in **test**, and the response's
-`dataMode` — not your input — is the truth. To reach prod data, pass `--data-mode prod` on the command
-line. (Under MCP, the launch lane is the caller's own `dataMode` argument, which defaults to `prod`.)
-
-Use `remits-cli` for everything else: staging changes, running tests, generating embeddable tokens,
-committing work, and diagnosing production issues.
-
-## Component Integrity Rules: Repo ↔ Database Reconciliation (read before any sync/commit)
-
-Component source-of-truth mistakes are the highest-impact failure in remits-cli. A repo/DB mismatch can
-hard-delete live components, spawn duplicates, renumber files, or leave the database and repo describing
-different implementations. These rules override the normal fast loop whenever they conflict.
-
-### How the platform reconciles the repo into the database (the mechanism you must understand)
-
-> **First, check which branch you are on.** Everything in this section describes a **TRUNK** sync. Syncing
-> from a **non-trunk branch** is a different, much safer operation — it writes `ComponentVariant` overlays
-> only and can never create, delete, rename, or overwrite a live component row. Run
-> `remits-cli components status` to see which mode your working tree is in, and read
-> "Branched Component Variants" for the variant-branch rules (which have their own hazard: tombstones).
-
-`remits-cli components sync` (and the sync phase of `components commit`) calls
-`GitHubClient.syncFromRepository`. On the account's **trunk branch** it is a **full two-way reconcile in
-which the GitHub remote is authoritative over the database.** It reads the **remote repo ZIP — not your
-local working tree** — and:
-
-- **Match / update:** each component is matched to a DB row by the **numeric id prefix of its files**
-  (`58_x.groovy` → component 58), not by name. Matching files overwrite that component's DB fields
-  (source/schema/html/etc.).
-- **Rename:** changing the component's `name:` in `.meta.yml` is supported as a normal update **as long as
-  the numeric id prefix stays the same**. On staging, the CLI updates the id/name cache aliases and prunes
-  stale old-name aliases for that id. On trunk sync, the platform canonicalizes the repo filenames to the
-  current component name (`58_OldName.groovy` with `name: New Name` becomes `58_NewName.groovy`, plus
-  sidecars) and reports those moves in `syncResults.renamed`.
-- **Create:** a file whose id prefix is **not** a live component on the account — including any `new_*` file —
-  is created as a **brand-new DB row with a fresh server-assigned id**, and the platform renames the repo files
-  to that id (the `Rename X→Y after component creation` / `Delete old file` commits).
-- **Delete:** after the create/update pass, **any live DB component whose id has no matching repo file is
-  hard-deleted** (`deleteMissingComponentsFor`), in reverse-dependency order. This runs only when the ZIP
-  "looks healthy" (contains `account-info.json` or `README.md`). Exempt from deletion: `auxiliary` components,
-  README-purpose prompts, and AGENT-purpose prompts.
-
-> ### `auxiliary: true` opts a component OUT of the repo entirely — in BOTH directions
->
-> This is a silent trap, so know it before you author a sidecar. `auxiliary: true` does not merely
-> "de-emphasize" a component:
->
-> - **Repo → platform:** the sync **skips the file outright**. A `new_*` component whose `.meta.yml` says
->   `auxiliary: true` is never created, so it **never gets a real id** and the file is never renamed. It
->   looks like the sync silently ignored your work — because it did.
-> - **Platform → repo:** the component's save hooks skip pushing source to GitHub, and repo initialization
->   omits it.
-> - It is also excluded from `getInformation()` (so AI agents do not discover it) and exempt from the
->   deletion pass above.
->
-> **Use `auxiliary: true` only for genuinely throwaway components** — ad-hoc reports, experiments, and the
-> ephemeral fixtures a Test creates and deletes at runtime (those are created in Groovy with
-> `auxiliary: true` and must never touch the repo).
->
-> **Use `auxiliary: false` for anything durable** — above all a Test suite that is a regression guard. If you
-> want it versioned in git, addressable by a stable id, or discoverable by another agent, it is not
-> auxiliary. Symptom to recognize: *"I added `new_Foo.groovy`, synced, and it neither appeared on the account
-> nor got renamed."* Check the sidecar's `auxiliary` flag first.
-
-**The single most important consequence:** the id in a component's **filename is load-bearing**. If a file's id
-no longer matches its DB row (a renumber or move across ids), the next sync will **create a duplicate at the
-new id and hard-delete the original at the old id**. If a component's files are missing from the repo at sync
-time, that component is **hard-deleted from the DB**. This is exactly how a prior session deleted live schemas
-and an embeddable.
-
-**Therefore: never renumber, rename-across-ids, or remove component files as a side effect.** Name-only
-renames are fine when every file keeps the same numeric id; either rename the local filename stem yourself or
-let trunk sync canonicalize it from `.meta.yml`. Before any sync, the repo must already mirror the live DB:
-every live component present at its real id, and nothing extra.
-
-### The surfaces and their intended behavior
-
-| Command | What it touches | Danger |
-|---|---|---|
-| `remits-cli components stage` (alias: deprecated `push`) | **Redis staging cache only.** Never mutates the DB or git. The safe iteration surface. | none |
-| `remits-cli components status` | Reads this lane's staging scope (account/user/branch/workspace) and branch resolution, and lists every other lane on the branch. | none |
-| `remits-cli components clear` | Clears THIS lane's staging cache without changing DB or git. Never touches another workspace lane. | none |
-| `remits-cli components sync` **on trunk** | **Server-side git→DB reconcile of the whole account** (create/update/**delete**/rename). Reads the pushed remote; ignores local files. | **high** |
-| `remits-cli components sync` **on a variant branch** | Writes `ComponentVariant` overlays for that branch only. Never touches trunk rows or the account's trunk branch. When the checkout identifies a subscribing account, the branch-local `account-info.json` is refreshed for that subscriber; `--dry-run` reports the plan without writes. | medium (a missing file becomes a **tombstone** that hides the component from subscribers) |
-| `remits-cli components commit` | **One shot:** `git add -A` + commit + `git push` + **`components sync`** + `git pull --ff-only`. Blindly stages the *entire* working tree (including any drift) and reconciles it into prod. Inherits the danger of whichever sync mode the branch selects. | **highest on trunk** |
-
-Key implications:
-- **`stage` is always safe** — stage and test as much as you want; it never reconciles or deletes.
-- **`components commit` is the most dangerous command**, not a mere convenience wrapper: it `git add -A`
-  commits and pushes whatever is in the working tree, then immediately syncs. Never run it while the tree
-  contains drift or unexplained changes. Prefer the explicit, observable
-  `git commit → git push → components sync → git pull` sequence so each phase can be inspected.
-- **`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.
-- After a successful non-dry-run `components sync` / `components commit`, the server clears the full
-  staging scope for that lane (account/user/branch/workspace). This is the expected clean state: old Redis aliases should not keep shadowing
-  the newly synced DB rows. `components sync --dry-run` intentionally leaves staging untouched.
-
-### Intended workflows
-
-**Change existing components (normal path):**
-1. Edit files under `components/` **keeping each component's existing numeric id** (use `new_*` only for
-   genuinely new components). To rename a component, update `name:` in its `.meta.yml`; keep the id prefix
-   fixed. Renaming the file stem is optional before trunk sync because the platform will canonicalize it, but
-   doing it locally keeps the working tree easier to read.
-2. `remits-cli components stage` → verify in test mode. Iterate (edit → stage → run).
-3. When ready to promote: pass the pre-sync safety check below, then
-   `git add -A && git commit && git push`, `remits-cli components sync`, `git pull --ff-only`.
-
-**Create a new component:** add `new_Name.groovy` (+ `.json` / `.meta.yml` as applicable). Sync assigns the
-durable id and renames the files. Standalone Prompts live in `components/prompts/new_Name.md`, and their
-sidecar must include `name`, `summary`, `description`, and `purpose` (usually `CUSTOM`). AGENT prompts do
-not live there; they are the `.md` sidecar beside the Utility in `components/agents/`. Do not create a
-direct database row to work around an id/name mismatch, and never create a replacement for a component
-that was unexpectedly deleted or renumbered.
-
-**Delete a component (deliberate only):** remove **all** of that component's files from the repo, confirm via
-`git status` that only those files are gone, then sync — the delete phase removes exactly that DB row. Deletion
-is a real, supported outcome of a missing file, which is precisely why an *accidentally* missing or renamed
-file is catastrophic.
-
-### Pre-sync safety check (confirm ALL before `components sync` or `components commit`)
-
-- **You know which sync mode this branch selects.** `remits-cli components status` states it outright. On a
-  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 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 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
-  > 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.
-- 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
-
-If sync reports unexpected `deleted` / `created` / `renamed`, uniqueness errors, or missing components — or you
-discover id drift — **stop. Do not re-run sync, do not `components commit`, and do not create replacement
-components to "make ids line up" or replace a deleted component.** Those actions compound the corruption.
-Preserve the repo-local session log and tool responses, and reconcile source-of-truth first.
-
-**Safe recovery pattern (repo ↔ DB drift):**
-1. Establish DB truth: `mcp_account_view` for the full live inventory; `mcp_component_view` to confirm and read
-   exact sources.
-2. Fix the **local tree to mirror the live DB** — rename component files back to their real DB ids, reassemble
-   any split components, remove orphan/duplicate files, and **refresh any local source that differs from the
-   live DB** (the DB is the running truth; a stale local file would overwrite good DB source on sync).
-3. Keep files for any components that were wrongly deleted so sync **re-creates** them (new ids are fine —
-   schemas are keyed by title, agents link tools by name).
-4. Make the remote authoritative **non-destructively**: commit the corrected tree, then
-   `git merge -s ours origin/<branch>` (keeps your tree, supersedes drifted remote history) and a fast-forward
-   `git push` — no force-push.
-5. Run **one** `components sync`: it updates everything to identical, creates the missing components, and
-   deletes nothing. Verify with `mcp_account_view`.
-
-If the mismatch is a genuine platform/tooling defect (not agent drift), follow the Back-Stage Escalation
-Workflow instead of improvising.
-
-## Required Local Index Reads
-
-These files are decision inputs. Read them when the related decision depends on them.
-
-- `~/.remits-cli/account-repos.json`
-  - The inventory of every local Remits repo. Account repos are keyed by numeric account id.
-  - It also contains the reserved **`platform`** entry: the local clone of the core Remits platform repo (`type:'PLATFORM_REPO'`, with its `directory` path). `remits-cli` clones it on first authenticated run if it is missing (default `~/remits`, override with `REMITS_PLATFORM_DIR`). Read this entry when you need to analyze a back-stage seam or open a platform-fix PR.
-  - Read before choosing a repo outside the current working directory.
-  - Read when a support ticket references an account and you need to locate the correct local repo.
-  - Read before concluding that a repo does not exist locally.
-- `~/.remits-cli/config.json`
-  - Read when service lifecycle, dashboard, or preferred-agent behavior matters.
-- `~/.remits-cli/service-state.json`
-  - Read when the local control center URL, current dashboard port, repo-scan summary, or websocket status matters.
-  - Read when the user asks whether the remits-cli service is running or where to open the browser view.
-- `~/.remits-cli/agents.json`
-  - The agent sessions registered from THIS machine, each with the process it is anchored to.
-  - Read when `remits-cli agent work` says no agent is registered, or when several agents are
-    registered and a command needs `--agent-id`.
-- `~/.remits-cli/activity.log`
-  - Read when diagnosing service lifecycle, websocket, agent registration, or ticket-routing failures.
-- `~/.remits-cli/sessions.json`
-  - Read when authentication state, active accounts, base URLs, websocket topics, or per-account data mode matters.
-- `./.remits-cli/current-session.txt`
-  - Read before opening repo-local session logs so you know which session file is current.
-- `./.remits-cli/sessions/<current-session>.jsonl`
-  - Read when the question is about what HTTP calls the repo recently made through remits-cli, which payload was sent, or what response/error came back.
-- `./.remits-cli/tool-responses/<callId>.json`
-  - Read when `remits-cli tool` says the full payload was stored externally.
-- `./.remits-cli/tools/tools.json`
-  - Read when the question is about available tool names, cached schemas, or why a tool invocation shape may be invalid.
-- `account-info.json`
-  - Read in the target repo before making component changes or assuming account ownership.
-- `account-configurations.json`
-  - Read only when account configuration values matter. It is generated separately because configuration maps can be large and `account-info.json` deliberately omits them.
-
-Do not rely on memory for these indexes. Read the file that governs the decision you are making.
-
-## Big Picture: How remits-cli State Is Organized
-
-Think about remits-cli as two cooperating layers:
-
-1. **Global machine state** in `~/.remits-cli/`
-   - This is the cross-repo control plane.
-   - It answers questions like:
-     - which accounts are authenticated
-     - which repos exist locally
-     - whether the background service is running
-     - where the control center lives
-     - which agent sessions are registered from this machine
-
-2. **Per-repo state** in `./.remits-cli/`
-   - This is the request/response and cache layer for one specific working tree.
-   - It answers questions like:
-     - which repo-local session log is current
-     - which `/cli/*` calls were made from this repo
-     - where a large tool response was written
-     - which tool schemas were most recently cached here
-
-When a user asks an indirect question, map it to the right layer first:
-
-- "Why did this ticket open in the wrong repo?" → start in global state.
-- "What exact payload did this tool call send?" → start in per-repo state.
-- "Why is the dashboard showing stale repos?" → start in `service-state.json` and `account-repos.json`.
-- "Why is the browser page not showing websocket activity?" → start in `service-state.json` and `activity.log`.
-- "Why is my agent not getting tickets?" → start in `agents.json`, then `remits-cli agent list`.
-
-Agents should use this mental model before guessing.
-
-## Support Ticket Mental Model
-
-Support tickets are a **first-class platform capability**, not an account convention. Every Remits
-account reads and writes the `support_tickets` collection without owning a Schema, tickets are anchor
-`Object`s on the account the work belongs to, and the lifecycle vocabulary is defined once in the
-platform.
-
-**The platform is deliberately not the standard for ticket workflow.** Different Remits
-platforms and products integrate with different systems — Zendesk, Jira, a customer's own portal —
-and each end client has its own rules for how tickets move. Remits owns the *record* and the *verbs*;
-each front-stage platform builds its own workflow on top through its own Embeddables, Rules, and
-Actions. So what you see through `remits-cli` is the shared record underneath every one of those
-workflows, and never one product's view of it.
-
-### You are an agent, and you register yourself
-
-**If the user says anything like "register to become a support agent", or "work support tickets",
-run exactly this and nothing else first:**
-
-```bash
-remits-cli agent serve
-```
-
-No flags, no setup, **no need to be in an account repo** — run it from wherever the session started.
-It registers this terminal for every account repo indexed on this machine that your user can reach,
-against the production platform and the production lane, and then **starts working tickets on its
-own**. It returns immediately; a background supervisor does the rest.
-
-Use `remits-cli agent register` instead **only** when the user wants presence without autonomy — a
-human, or you in this very tab, will work the tickets by hand. Registering alone starts nothing: it
-makes the session routable and then waits to be asked.
-
-Three tabs running an agent are three agents. Each is independently routable, each reports its own
-activity, and each stops receiving work when its tab closes — a heartbeat anchored to the session dies
-with it, so a crashed agent and a quit agent look identical to the platform.
-
-**Nothing is pushed at you.** A terminal mid-task cannot receive a push, so delivery is you asking.
-That is why the routing decision is a durable field on the ticket rather than a message: you can
-restart this terminal, register again, and the work is still there.
-
-Two facts about a ticket are separate and must stay separate:
-
-| Fact | Field | Means |
-|---|---|---|
-| **Routed** | `routedAgentId` | which agent session should pick this up — delivery |
-| **Claimed** | `claimedAgentId` | a worker process is running on it *right now* |
-| **Owned** | `assignedTo` | who has claimed it — accountability |
-| **Status** | `status` | where it is in the workflow |
-
-A ticket routed to you is not yet yours. Claim it with `accept`, and the queue then shows it owned.
-
-The **claim** is the supervisor's, not yours — it exists so two workers never start on one ticket,
-and it expires on its own so a killed worker cannot park a ticket forever. You do not manage it.
-
-### Autonomous: one ticket, one process
-
-```bash
-remits-cli agent serve                          # workers are whichever agent THIS session is
-remits-cli agent serve --worker-agent codex --max-concurrent 2
-remits-cli agent serve --mode investigate       # read-only workers: no file edits
-remits-cli agent workers                        # what is running right now
-remits-cli agent release                        # stop serving, go offline
-```
-
-**Run it in a plain terminal tab.** That tab becomes the agent host: `serve` returns immediately, a
-detached supervisor is anchored to the tab's shell, and closing the tab stops the agent. Nothing in
-that tab is an AI session — the AI only ever appears as the worker processes the supervisor spawns.
-
-Starting it from inside an AI session works too and self-detects the worker kind, but it is the
-lesser setup: it parks an interactive session as a heartbeat holder while its workers do the work.
-
-When a ticket is routed to this session, the supervisor launches **a fresh headless agent process
-for that ticket**, in that account's repo, with a brief the platform generates. That process exits
-when the ticket is done.
-
-**One ticket = one process is the point, and it is why nothing here ever needs `/clear`.** Context
-grooming cannot be a discipline: `/clear` and `/new` are commands a *human types into a TUI*, and no
-model can invoke them — so a long-lived session working ticket after ticket has no way to reset
-itself. A process that exits has nothing to reset. Do not try to solve context growth by being tidy
-inside one session; let the session end.
-
-**`serve` returns immediately, and that is correct.** Do not follow it with a wait, a poll, or a
-loop. The supervisor is detached precisely so this tab is free. Report that you are serving and
-stop; you have not left the job half done.
-
-What the supervisor handles for you, so you do not have to think about any of it: collecting routed
-work, claiming each ticket so no second worker starts on it, renewing that claim while the worker
-runs, reporting the worker's activity to the dashboard, dropping the claim when it exits, retrying a
-failed ticket once, and releasing a ticket back to the queue when it has failed too often. Closing
-the terminal stops everything and hands any in-flight work back.
-
-### The manual loop
-
-Only when the session registered with `agent register` rather than `agent serve`.
-
-```bash
-remits-cli agent work --wait 600                    # returns as soon as work arrives
-remits-cli agent status --state working --ticket 22454 --activity "reproducing the upload failure"
-# ... investigate, fix, verify — keep `status` current as what you are doing changes ...
-# ... close the ticket lifecycle through remits-cli ticket (accept -> status -> complete, ask, or release) ...
-remits-cli agent status --state idle                # then ask for work again
-```
-
-**Nothing wakes this tab.** A routed ticket sits there until someone in this session asks for it, so
-if you are working the manual loop you have to keep asking. If you find yourself wishing you could
-be woken up, that is what `agent serve` is.
-
-**Report what you are doing.** `agent status` is how an operator watching the dashboard, or another
-agent, knows this session is alive and what it is on. It costs one command and it is the difference
-between a visible queue and a silent one. Update it when you change what you are doing, not on a
-timer.
-
-**Work the ticket in the right repo.** A ticket names its `accountId`, and often an
-`implementationAccountId` — the platform/product account whose repo holds the code. Resolve that to a
-local directory through `~/.remits-cli/account-repos.json` and `cd` there before making changes. You
-registered from anywhere; you do not fix anything from anywhere.
-
-**Capacity is real, not advisory.** A serving session tells the platform how many workers it can run
-(`--max-concurrent`, default 1), and the router will not send it more than that. So a session at
-capacity is skipped in favour of one that is free, rather than accumulating tickets it will never
-start.
-
-**Lane note:** `register` and `serve` default to the production lane because a support agent works real tickets.
-`--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.
-
-### If you are the worker
-
-You know you are one when `REMITS_SUPPORT_TICKET_ID` is set in your environment. Your whole job is
-that one ticket, and your brief is your prompt — follow it. Two things it says that are worth
-repeating: **report progress** with `remits-cli agent status --ticket <id> --activity "..."` (a
-headless run is invisible otherwise), and **end in a terminal state** — `complete` with a real
-resolution, or `update_status` with what you established and what the next agent should try. Exiting
-quietly leaves a ticket that looks in-flight forever.
-
-### Before you edit anything: where you are, and whether you may
-
-Presence answers *who*. Two more facts answer *whether you may edit*, and with git worktrees and
-workspace lanes an account id no longer identifies a working tree — so an agent that does not ask these
-is assuming, and the assumption it makes when it guesses wrong is "this is my repository to edit".
-
-```bash
-remits-cli ticket where --ticket 22454     # repo account, checkout, branch, staging lane, lease, claim, YOUR phase
-remits-cli agent map                       # every repository, who holds each lease, and where each agent is working
-```
-
-**Reading, reproducing and investigating are parallel-safe and unrestricted. Editing one account's
-repository is exclusive**, enforced by a lease held per repository account per data lane:
-
-```bash
-remits-cli ticket lease   --ticket 22454   # take it when you started read-only and reached an actual edit
-remits-cli ticket unlease --ticket 22454   # complete / ask / release already do this for you
-```
-
-Four things are worth knowing and are not obvious:
-
-- **A refusal is not an error.** The run continues read-only, and the message names who holds the lease
-  **and where they are working**, so you can tell a real conflict from a holder in a different worktree.
-  **Do not wait for a lease and do not poll for one** — investigation is most of the work on most
-  tickets, and a ticket that turns out to need an edit hands off with `ticket progress --next-step`
-  saying exactly what change is needed. A lock people queue on turns one stuck worker into a stalled
-  fleet.
-- **A staging workspace does not replace the lease.** Separate lanes stop two runs *resolving* each
-  other's staged code; they do nothing about two processes writing the same files or pushing the same
-  branch, which is what actually destroys work.
-- **One editing worker per repository account per lane — worktrees do not change this.** Two worktrees
-  of one repo push to the same branch on the same remote, so per-directory leases would trade file
-  conflicts for non-fast-forward push conflicts, which surface later and are worse.
-- **A spawned ticket worker already has its own staging lane** (`REMITS_WORKSPACE=ticket-<id>`). You do
-  not set it, and your brief states it. Say which lane you staged into when you report what you verified
-  — somebody looking at the shared lane will not see your changes.
-
-`unlease` returns **your own** lease and deliberately cannot touch anybody else's. Breaking a stale one
-is a separate, human verb: `remits-cli ticket force-unlease --ticket ID --reason "..."`.
-
-### Your account's process is binding, and it is already in your brief
-
-An account declares how its work is done as Prompts with purpose `OPERATIONS`, selected per the ticket's
-`workstream` (`support`, `sdlc`, `incident`, `release`, or whatever that organization calls its
-processes) via `Prompt.category`, with an uncategorised one as the catch-all. The matching text is
-**inlined verbatim into the brief** of every agent that works one of that account's tickets and is
-binding on it — follow it even where it differs from how you would normally proceed, and if it conflicts
-with the brief, follow the process and say so on the ticket.
-
-You do not fetch it: if the brief has a "The process that governs this ticket" section, that is it. If
-it says the account documents no process, the likely cause is that the prompt is **staged but not
-committed** — an autonomous worker resolves the committed one, so it is never bound by a procedure
-nobody has reviewed. The repo root also carries a generated `OPERATIONS.md`; that file is generated
-from the prompt, so **edit the prompt, not the file**.
-
-`workstream` is not `type`: a type classifies the request, a workstream names the procedure, and they
-cross — a `defect` handled by incident response out of hours goes through the SDLC in the morning.
-
-### Seeing the queue as a human does
-
-`remits-cli start` opens a browser control center showing the same facts you are acting on: which
-agents are registered and what each is doing, which tickets are open, and which agent each is routed
-to. An operator can route a ticket to a specific agent from there. It is a view, not a second system —
-what it shows and what `remits-cli agent work` returns come from the same records.
-
-### Agent components are workers too
-
-An Agent component that works support tickets must register itself in the same presence registry as
-CLI sessions. That makes it visible in `cliAgents()` and `remits-cli agent map`, and lets
-`dispatch(...)` / `ticket route` target it by the same `agentId` field:
-
-```groovy
-def me = workerId()                         // component:Agent:34
-registerWorker([agentId: me, label: 'Support Triage Agent'])
-def work = workerWork([agentId: me, runId: threadGroupingId()])
-workerStatus([agentId: me, ticketId: work.tickets[0]?.id, activity: 'investigating'])
-```
-
-`workerWork(...)` is the component-side analogue of `remits-cli agent work` — the same code runs behind
-both, so a component and a terminal session get the same answer to the same question. It reads tickets
-routed to that worker, claims what it may start, sweeps eligible unrouted work when it is idle (reported
-separately as `sweptTicketIds`), takes the repository edit lease when available, and returns `phase`,
-`brief`, `briefFacts`, and `editLease`. `phase:'editing'` means the component may edit and stage;
-`phase:'investigating'` means another worker holds the repo lease and the component must stay read-only.
-When a component reaches a resting point, pass `agentId` to `complete(...)`, `ask(...)`, or
-`release(...)` so the ticket verb frees the edit lease and drops its claim.
-
-Route to a component by its **id** (`component:Agent:34`) — that is what `workerId()` returns and what
-the component polls on. `ticket route --agent component:Agent:MyAgent` also works: the name is resolved
-and the id form is what gets stored.
-
-### Moving a ticket through its lifecycle
-
-**`remits-cli ticket` is the platform surface, and it is what you should reach for.** It reads and
-writes the platform's own ticket record, so the same commands work on every Remits platform.
-
-```bash
-remits-cli ticket read     --ticket 22454        # the full record
-remits-cli ticket accept   --ticket 22454        # claim it before changing anything
-remits-cli ticket progress --ticket 22454 --summary "Traced it to the posting Action" --category investigation
-remits-cli ticket status   --ticket 22454 --status in_progress
-remits-cli ticket complete --ticket 22454 --resolution "What you found and did"
-remits-cli ticket ask      --ticket 22454 --question "Re-issue or skip?" --context "412 affected"
-remits-cli ticket answer   --ticket 22454 --message "Skip them."   # alias: reply
-remits-cli ticket message  --ticket 22454 --message "We reproduced it; a fix is staged."
-remits-cli ticket planning --ticket 22454 --board-stage ready_for_qa --blocked-by CAB-112
-remits-cli ticket release  --ticket 22454        # hand it back to the queue
-```
-
-**See the whole queue before deciding your ticket is unique.** Alert-raised tickets arrive in
-clusters, and the same root cause routinely appears under several different account names — so the
-first useful question is usually "how many of these are one fix?", and you cannot ask it from a single
-ticket.
-
-```bash
-remits-cli ticket queue --account-id 49                       # triage order, most urgent first
-remits-cli ticket queue --account-id 49 --unrouted --status open
-remits-cli ticket queue --account-id 49 --search "firestore index"
-```
-
-The `repo` column is the account the **edit lease** excludes on, so it also tells you which of these
-could be worked at the same time and which will serialize behind one another.
-
-Found a second, unrelated problem while working yours? **File it rather than widening the ticket you
-were given** — a ticket that describes two things cannot be closed by either fix.
-
-```bash
-remits-cli ticket create --account-id 49 --subject "Vendor name lost on re-normalization" \
-    --type defect --priority medium --reference-id vendor-name-lost
-```
-
-`--reference-id` makes it get-or-create, so a re-run — or another worker reaching the same conclusion
-— reconciles onto the same ticket instead of filing a duplicate.
-
-Marking and evidence, so the next reader does not repeat your work:
-
-```bash
-remits-cli ticket tag      --ticket 22454 --tags firestore-index,cluster-aug
-remits-cli ticket artifact --ticket 22454 --type log --label "Failing query" --content "..."
-remits-cli ticket note     --ticket 22454 --message "Internal: same cause as 23465"
-remits-cli ticket field    --ticket 22454 --key customerReference --value CR-9182
-```
-
-`note` is internal — the next worker and a reviewer see it, the requester does not. Use `message` for
-anything the requester should read. `field` writes your **organization's own** field, outside the
-platform's bounded planning slots.
-
-**`message`, `answer` and `note` are separated by who reads the result, not by tone.** They are easy to
-confuse and they do different things to the ticket:
-
-| Command | Who reads it | What it does to the ticket |
-|---|---|---|
-| `ticket message --message "..."` | the requester | appends a public entry. **Does not send anything** |
-| `ticket note --message "..."` | the next worker, a reviewer | appends an internal entry |
-| `ticket answer --message "..."` | whoever asked | answers the open question and **re-routes**, so a fresh worker resumes |
-
-`ticket reply` is an **alias of `answer`** — kept because every existing brief says it. Do not read it as
-"reply to the customer"; that is `message`. (Some account tools spell the conversational verb `reply`,
-which is exactly why this surface teaches `answer`.)
-
-**Appending a message is not emailing anyone.** The record is deliberately vendor-agnostic; the account
-owns the transport. To ask for something to actually go out:
-
-```bash
-remits-cli ticket deliver --ticket 22454 --channel email --to ops@acme.test \
-    --subject "Waiting on you" --idempotency-key waiting-22454
-remits-cli ticket deliveries --ticket 22454          # what is queued, and what already went
-```
-
-That records an outbox request. An account-owned Rule or scheduled Action sends it and marks the result
-(`ticket delivered --delivery-id ...` / `ticket delivery-failed --delivery-id ... --reason "..."`). Use
-this when a ticket is waiting on somebody who is not watching the queue.
-
-### When a worker needs a decision from a human
-
-There are **three** ways a run can end, not two, and the third is what stops an agent guessing:
-
-| Outcome | Verb | Means |
+| Load it before you | Reference | It owns |
 |---|---|---|
-| Done | `ticket complete --resolution` | finished, here is what I did |
-| **Blocked on a choice** | `ticket ask --question` | I understand the work; the DECISION is not mine |
-
-| Could not finish | `ticket status --status pending_review` + `ticket progress` | stuck, here is the hand-off |
-
-`ask` puts the question on the ticket as an outbound message and parks it. The queue then shows it as
-**awaiting a response** — distinct from "done, review me", which `pending_review` alone cannot express.
-
-Someone answers with `remits-cli ticket answer --message "..."` (`reply` is an alias), or through an
-operator Embeddable.
-That **re-routes the ticket by default**, so the supervisor's next poll starts a **fresh worker whose
-brief already contains the exchange**. Resumption costs nothing because a worker is one process per
-ticket — there is no session to restore.
-
-Ask when the choice is genuinely not yours: which of two behaviours is wanted, whether to touch live
-data, an ambiguity in the request. Do not ask for reassurance about something you can determine
-yourself, and ask **once**, with the options laid out.
-
-Inside an autonomous worker `--ticket` defaults to the ticket that worker was launched for.
-
-A refusal is an **answer**: "accept it first", "already assigned to someone else", "reopen it
-first". Act on the sentence — do not go looking for another tool that lets you skip the step.
-
-**`mcp_support_ticket` is an account convention, not a platform guarantee.** It belongs to one
-particular System Account: it may not exist on the platform you are on, it scopes to its own
-account, and it will refuse a ticket owned by a different one. Use it only when you are working in
-that account and want its product-specific workflow on top of the record. It offers:
-- `read` — always start here to load current state
-- `accept` — claim the ticket so other agents do not work it concurrently
-- `update_status` — move to `in_progress` or `pending_review`
-- `complete` — resolve the ticket with a summary of what was done
-- `release` — unassign if you cannot continue
-- **Pulling a ticket by number is enough — you do NOT need to know its account first.** The `ticketId` IS the ticket's globally-unique anchor id, and `mcp_support_ticket` resolves the owning account from it for every action that operates on an existing ticket (`read`, `accept`, `update_status`, `complete`, `release`, `record_progress`, `add_artifact`, `get_attachment`). So when a user says "pull ticket 19463", just call `read` with `{ "action": "read", "ticketId": "19463" }` from any authenticated **prod** session (the ticket lives in prod data) — omit `accountId` entirely. The response returns the resolved `accountId`/`accountName` (and `implementationAccountId` when set); use those for any follow-up work. **Only `create` requires an explicit `accountId`** (a brand-new ticket has no anchor to resolve from). If a bare `ticketId` returns "Support ticket not found", double-check you are in `--data-mode prod`, then fall back to passing an explicit `accountId`.
-- `read` can return `documentState:'missing_or_empty'` with `ticket.mirrorOnly:true` and `ticket.canMutate:false`. That means the support-ticket anchor exists and the queue row is real, but the backing Firestore `support_tickets/{ticketId}` document is missing or metadata-only. Treat this as a degraded ticket, not as "ticket not found"; run or request the System Account action `Restore Support Ticket Documents From Anchor Mirrors` for the owning account before lifecycle mutations. The restore recovers mirrored scalar fields, but document-only arrays such as alert snapshots, email threads, attachments, worklog entries, and artifacts may be lost.
-- If a ticket is part of the request, manage the lifecycle proactively. Do not wait for the human user to remind you to read, accept, update, complete, or release it.
-
-Ticket-routing context:
-- `accountId` / `accountName` identify the account that owns the ticket.
-- If present, `implementationAccountId` / `implementationAccountName` identify the owning `PLATFORM` or `PRODUCT` implementation context.
-- Prefer `implementationAccountId` when choosing the working directory for a ticket, falling back to `accountId` when the platform/product repo is not available locally. Routing already uses that same ladder, so the repo you were routed through is usually the right one.
-- For enhancement work, prefer the platform/product implementation context when deciding where code changes belong.
-- For defect investigations, start from the owning ticket account, then move to the platform/product context if the root cause is in shared components.
-
-Sandbox note:
-- Every `remits-cli` command that reaches the Remits service (`auth`, `tools`, `tool`, `components`, `test`, `token`, and all of `ticket` / `agent`) needs outbound network access.
-- **Inside an autonomous ticket worker this is already arranged** — the supervisor launches the worker with network enabled, in both the editing and the investigating phase. An investigating worker is restricted from *writing the repository*, never from *talking to the platform*: reading its ticket, running a diagnostic and recording a finding are the whole of what investigating means.
-- Elsewhere, `ENOTFOUND`, `EAI_AGAIN`, `ECONNREFUSED`, `EPERM` or a bare exit 6 / `HTTP:000` from a sandboxed session means the command needs escalated permissions or must run outside the sandbox. Do not read it as "the platform is down" — check a second command before concluding anything about the service.
-
-Use the same repo/context rules as other tools:
-- If the ticket targets a `CLIENT` account, do not assume that client's repo is the implementation repo. Confirm the parent `PLATFORM` / `PRODUCT` relationship first.
-- Read `~/.remits-cli/account-repos.json` before choosing which local repo to open.
-- If the correct repo for the relevant account type exists locally, switch there and inspect `account-info.json` and `/components`.
-- If the repo is not available locally, use `mcp_account_view`, `mcp_component_view`, and `mcp_component_grep`.
-
-## Efficiency Rules
+| decide which account or repo work belongs in, or explain why a request resolved the way it did | `account-targeting.md` | the `resolution` block, repo selection, multi-parent edges, storage namespaces, test-data flags, the data-lane clamp |
+| run `components sync` or `components commit` — **mandatory** | `component-integrity.md` | how a trunk sync reconciles repo→DB, why a filename's id prefix is load-bearing, the `auxiliary` trap, the pre-sync safety check, the repair procedure |
+| build or change any component | `development-loop.md` | test vs prod mode, the golden rule of verification, the eight-step fast loop, `new_` components and sidecars, the temporary-experiment pattern |
+| conclude "my change isn't working" | `component-resolution.md` | the staged → variant → trunk order, the staging key format, the compile signature that proves what ran, staging workspaces for parallel agents, the stale-compile-cache caveat |
+| work from a non-trunk checkout, or promote a branch | `branch-variants.md` | what a variant is, which world your checkout resolves, `--as-account` vs `--variant-branch`, tombstones, the promotion loop and its phases, subscribe/retire |
+| touch a support ticket | `support-tickets.md` | the ticket record and its verbs, routed vs claimed vs owned, autonomous workers, the repository edit lease, ask/answer/resume, delivery |
+| register this session as an agent, or ask why a routed ticket never started | `agent-sessions.md` | `serve` vs `register`, what registration does, worker spawning per agent kind, routing order, the control center, multi-session auth |
+| investigate live behavior | `investigation.md` | which tool reads which record, correlation keys, reading a record's `content`, HTTP audits, AI activity, node/`localMode`, the production support flows |
+| call any `mcp_*` tool | `tool-reference.md` | every tool's parameters, semantics, and traps — read the tool's entry before building its input |
+| reason about repo discovery, auth state, or what a command actually sent | `cli-state.md` | the global `~/.remits-cli/` control plane vs per-repo `./.remits-cli/`, and which file answers which question |
+| need an exact flag, or the auth / host / async surface | `command-reference.md` | authentication, host vs data mode, the two async mechanisms, hierarchy-scoped reads, the full command list, prod banners |
+| give up on something that misbehaved | `troubleshooting.md` | the symptom→fix table, the two kinds of escalation, and the escalation bundle |
+
+## The rules that are cheaper to state than to look up
+
+These are the ones that cost a session more to rediscover than to carry. Each is expanded in the
+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` 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`)
+- **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
+  remove component files as a side effect. (`component-integrity.md`)
+- **`auxiliary: true` opts a component out of the repo in BOTH directions.** A `new_*` file marked
+  auxiliary is never created, never gets an id, and never gets renamed — it looks exactly like the sync
+  silently ignored your work. Use it only for genuinely throwaway components.
+  (`component-integrity.md`)
+- **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`)
+- **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`)
+- **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`)
+- **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`)
+- **Never infer prod vs test from an account name, URL, or branch.** Read the explicit flags —
+  `testAccount`, `testUser`, `testMode`, and the echoed `dataMode`. `mcp_sql_query` is lane-blind and
+  returns both lanes mixed; filter it yourself. (`account-targeting.md`)
+- **"Tool call succeeded" means DISPATCHED, not that the tool did what you asked.** A tool that runs and
+  refuses returns HTTP 200 with its own `success: false`. For any mutating call, read `result.success`
+  from `./.remits-cli/tool-responses/<callId>.json` before reporting the work as done.
+  (`tool-reference.md`)
+- **Writing the code is not finishing the job.** A change is complete when it is verified — a Test
+  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 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
+  name. (`account-targeting.md`)
+- **Investigate in prod mode; verify in test mode.** "It looks right in prod data inspection" is not
+  proof that a code change works. And never copy live customer data into another account's test
+  collection to get realistic verification. (`development-loop.md`)
+- **`remits-cli agent serve` is the whole answer to "work support tickets".** No flags, no setup, no need
+  to be in an account repo. `agent register` makes the session routable and starts nothing.
+  (`support-tickets.md`)
+- **`remits-cli ticket` is the platform's own ticket surface** and works on every Remits platform.
+  `mcp_support_ticket` is one System Account's convention and refuses tickets it does not own.
+  (`support-tickets.md`)
+- **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`)
+- **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
+  behavior by running unsupported mutating command variants. (`troubleshooting.md`)
+
+## Orientation: the first four things to establish
+
+```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 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.
+
+If any command returns 401, run `remits-cli auth` (with the same `--base-url` if you were targeting a
+non-default host).
+
+**Files that are decision inputs — read the one that governs the decision, do not rely on memory:**
+`~/.remits-cli/account-repos.json` (every local repo, plus the reserved `platform` entry for the core
+platform clone), `~/.remits-cli/sessions.json` (auth state and lanes), `~/.remits-cli/agents.json`
+(agents registered here), `./.remits-cli/tool-responses/<callId>.json` (the full tool payload), and the
+repo's `account-info.json`. `cli-state.md` maps every remaining question to its file.
+
+## Efficiency rules
 
 Keep support and development sessions lean:
 
 - Prefer local repo files over remote tools whenever the target account repo exists locally.
-- 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` values instead of broad collection scans.
+- 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`
+  values instead of broad collection scans.
 - Do not call `mcp_account_view` repeatedly once you already have the needed account/component context.
-- For investigations, follow the shortest path: identify the exact document/ticket/object first, then drill in. Avoid exploratory “maybe this” queries across large collections.
-- For ticket replies, read the current ticket state and the new reply, then continue from existing context instead of re-loading broad account state from scratch.
-- Verification should be decisive. Avoid repeated identical test/status/tool calls when no new information is likely.
-
-## Account Repository Index
-
-The account repository index file is located at: `{{ACCOUNT_REPO_INDEX_PATH}}`
-
-This JSON file is automatically maintained by `remits-cli` and tracks all known Remits account repositories on this machine. It is updated whenever any `remits-cli` command runs from an account repo directory. The file maps account IDs to their metadata:
-
-```json
-{
-  "37": {
-    "accountId": 37,
-    "name": "Acme Corp",
-    "directory": "/Users/you/Projects/remits-acme-corp",
-    "updatedAt": "2026-03-23T12:00:00.000Z"
-  }
-}
-```
-
-**Use this index to:**
-- Discover which account repos exist on this machine when working from a different directory
-- Navigate to another account's repo to read its `account-info.json` and component source
-- Resolve account names and IDs without making remote API calls
-- Support cross-account workflows where an agent in one repo needs context from another
-
-If the index file doesn't exist yet, run any `remits-cli` command from an account repo to bootstrap it.
-
-## Two Workflows
-
-1. **Development** (test mode) — Build, modify, and verify components using isolated test data.
-2. **Production Support** (prod mode) — Investigate live data, debug issues, trace execution.
-
-Every CLI response includes `dataMode` so you always know which context you're in.
-
-### Test Mode vs Prod Mode
-
-Treat these as two different jobs:
-
-- **Prod mode** is for investigation.
-  - Read live Firestore documents.
-  - Inspect live object activity, events, alerts, and logs.
-  - Confirm what actually happened to a customer.
-  - Do not use prod mode as your final verification environment for a code fix.
-
-- **Test mode** is for verification.
-  - Stage local component changes.
-  - Run Test components.
-  - Generate token URLs and verify behavior in isolated browser flows.
-  - Confirm the fix without mutating or depending on live customer processing.
-
-The correct support loop is usually:
-1. Investigate in **prod mode**
-2. Identify the responsible implementation repo and make the code change locally
-3. Move back to **test mode** for verification
-4. Verify with a Test component, Playwright/browser confirmation, or both
-
-If a production issue needs realistic verification, do **not** copy live customer data from a production account into another account's test collection.
-
-The right model is:
-- investigate the source document in **prod mode**
-- model the relevant conditions in a **Test** component
-- or reproduce the scenario through a controlled **test-mode** embeddable/browser flow
-- verify the fix there
-
-Never treat "it looks right in prod data inspection" as sufficient proof that a code change is verified.
-
-## The Investigation Model
-
-Front stage — Schemas, Readers, Actions, Embeddables, Rules, HtmlTemplates, Agents, Tests, and the Firestore
-**documents** that hold business data — is described in `platform-overview.md`. This section is only about
-the **back-stage lifecycle records** an investigation actually reads, and how to read them.
-
-### Which tool reads which record
-
-The model — Documents (Firestore business data) vs Objects and their record trail (MySQL), linked by
-`object_id` — is in `platform-overview.md` → *Objects, Documents, and the Record Trail*. What matters
-here is the tool and the filterable fields:
-
-| Record | Query it with | Fields worth filtering on |
-|---|---|---|
-| document | `mcp_firestore_search` | any schema field, plus `account_id`, `object_id`, `_lastModifiedAt` |
-| `object` | `mcp_record_listing` / `mcp_record_view` | `status`, `type`, `name`, `referenceId` |
-| `object_log` | `mcp_record_listing` / `mcp_record_view` | `type`, `description`, `content`, `threadGroupingId` |
-| `event` | `mcp_record_listing` / `mcp_record_view` | `action`, `status`, `eventDate`, `threadGroupingId` |
-| `alert` | `mcp_record_listing` / `mcp_record_view` | `status`, `type`, `active`, `threadGroupingId` |
-| user activity session | `mcp_user_activity` | `userId`, `accountId`, `sessionKey`, `focusedOnly`, `traceId` pivots |
-
-`mcp_record_listing` finds candidates when you do not know the id; `mcp_record_view` opens an exact one;
-`mcp_object_activity` returns one Object's whole timeline in order.
-
-**Check the data lane before concluding a record does not exist** — `--data-mode test` and `prod` read
-different lanes (see `platform-overview.md` → *Test and Production Data Lanes*).
-
-### Correlation keys
-
-- **`object_id`** — links documents to records. Pivot `mcp_firestore_search` → `mcp_object_activity`.
-- **`threadGroupingId`** — groups every record and log line from one processing chain, and is also the
-  request's trace id. Pivot into `mcp_system_logs` and `mcp_performance_trace`.
-- **`node`** — resolves to `serviceName` + `region` for log queries (table below).
-- **`sessionKey`** — salted user-activity session key. Pivot `mcp_user_activity` `sessions` → `story`;
-  each beat then carries a `traceId` / `threadGroupingId` for trace and log investigation.
-- **`sessionId`** — pivots into persisted AI activity via `mcp_ai_session_search`.
-
-### Reading a record's `content` — persisted context, not a memory dump
-
-`content` on an `object`, `object_log`, `event`, or `alert` is the **sanitized snapshot** the platform
-deliberately kept of what the producing component knew at that workflow step. It is not everything that was
-in memory.
-
-- `Object.content` — ingestion/request/file context when the Object was created or updated.
-- `ObjectLog.content` — the logging component's point-in-time view.
-- `Event.content` — the scheduling component's view, plus the explicit event options.
-- `Alert.content` — the raising component's view, plus the explicit alert body.
-
-**Missing or `[REDACTED]` does not mean the component never had it.** Before persisting, the platform drops
-non-serializable objects, strips `requestBody` / `params` / `token` recursively, summarizes very large
-strings, prunes oversized maps and collections, and redacts secret-looking keys (`password`, `secret`,
-`authorization`, `cookie`, `clientSecret`, …) plus any Account/User schema field marked `sensitive: true`.
-When explaining a record, distinguish what the workflow *had* at runtime from what the platform *kept*.
-
-**Provenance travels in the context itself:**
-
-- **`source_bcd`** — the immediate component that produced this record, e.g. `[Action:18] DataPlus Invoice Posting`
-- **`upstream_source_bcd`** — the prior workflow hop, when the context was inherited from one
-
-**Never interpret `content` in isolation.** Pair it with the record type, `source_bcd`, any
-`upstream_source_bcd`, the `object_id` timeline, the `threadGroupingId` chain, and the producing
-component's source. The goal is not to find a suspicious record — it is to explain **why the context looks
-exactly the way it does relative to the workflow step that produced it**.
-
-### HTTP audits
-
-Raw inbound (Reader) and outbound (`rest(...)`) HTTP is persisted to Firestore — but **only for accounts
-with `Account.enableHttpAudits`**. When it is off, the absence of audit documents proves nothing.
-
-Audits live in **monthly** collections, not one global collection:
-
-```
-http-audits/http-audits-YYYY-MM/entries
-```
-
-Start with the month the request ran in, and check the adjacent month if the run may have crossed a
-boundary. Query them with `mcp_firestore_search` like any other collection; the filters worth reaching for
-are `direction` (`INBOUND` / `OUTBOUND`), `success`, `request.method`, `request.path`, `component.name`, and
-`response.statusCode`. Some paths are deliberately excluded from persistence, so a missing audit is not
-proof a call was never made.
-
-Reach for audits when the question is *what exact request went out, what came back, and did this component
-actually make the call* — then use the component source plus the payload to place the fault in request
-formation, the partner's response, or downstream processing. Full captured shape, websocket behavior, and
-embeddable patterns: `features/http-audits.md` (`mcp_get_guide`).
-
-### AI activity
-
-Every `ai()` call and Agent turn is persisted. Two ways in:
-
-- **`mcp_ai_session_search`** — search groupings and open their detail. A grouping spans every session
-  sharing one grouping id: the agent turns plus its guardrail and internal `ai()` calls. Use the
-  **map → open** flow described under its Tool Reference entry, never a whole-detail dump.
-- **`ai_request_response([sessionId: id])`** — from inside component code, loads the stored
-  request/response history for a session (`first: true` / `last: true` for one record). This is also how
-  you replay a stored provider response in a test.
-
-If a document or agent state already carries a session id, that is a direct pivot into persisted AI
-activity.
-
-**Before tuning any prompt, read the session.** `features/ai-session-investigation.md` owns the method —
-per-turn forensics, what each layer proves, and the rule that what a tool **PRODUCED** is not necessarily
-what the model **CONSUMED**. `features/ai-strategy.md` owns what to change once you know. Changing a prompt
-before reading the persisted request/response is guessing.
-
-### Node Reference Table
-
-| Node Name | Service Name | Region |
-|---|---|---|
-| remitsAdmin-east5 | remits | us-east5 |
-| remitsActions | remits-actions | us-east1 |
-| remitsAdmin | remits | us-east1 |
-
-`mcp_system_logs` accepts `node` directly and resolves it automatically.
-
-### Runtime node and `localMode`
-
-The deployed `remits` service in `us-east5` (`remitsAdmin-east5`) runs with the platform setting
-`localMode=true`. If someone says "localModel" in this context, confirm they mean this `localMode`
-setting. Operationally, immediate async follow-on work stays on the same Cloud Run service/node instead of
-being sharded to `remits-actions`:
-
-- Pub/Sub-style follow-on messages are handled locally after commit.
-- Near-immediate tasks are handled locally when `localMode` is enabled. Future scheduled tasks still use
-  Cloud Tasks.
-- Local worker hops preserve the run context, including staged-source resolution, data mode,
-  `threadGroupingId`, and trace correlation.
-- Durable boundaries such as async HTTP ingress and Events carry that same run context across the queue.
-
-For investigations on the default deployed host (`https://remits-529558023549.us-east5.run.app`), do not
-assume "async" means `remitsActions` / `us-east1`. Start with `node:"remitsAdmin-east5"` and the
-`threadGroupingId`; pivot to `remitsActions` only when the Event delivery envelope, log line, or returned
-node says the work actually ran there.
-
-This does not change the data-lane rule: a non-null `TestMode` can exist only to carry branch/staged-source
-resolution. Data isolation is decided by CLI `--data-mode`: a branch-scoped `--data-mode prod` run is still
-prod data, while `--data-mode test` remains isolated test data.
-
-## Getting Started
-
-### Authentication
-
-Authenticate once per session. Opens the user's browser for OAuth login:
-
-```bash
-remits-cli auth --account-id <ACCOUNT_ID>
-remits-cli auth --account-id <ACCOUNT_ID> --base-url http://localhost:8080
-```
-
-- `--account-id` is auto-resolved from `account-info.json` when you're inside an account repo, so you can usually just run `remits-cli auth`. Pass `--account-id <ID>` explicitly to target a different account (e.g., authenticating into a child account from a parent-account repo) — the explicit flag always wins over the repo's `account-info.json` and any prior session.
-- `--base-url` targets a specific platform instance (e.g., localhost for development). Sessions are stored per account + base URL + data mode, so authenticating against localhost does not overwrite a production session for the same account.
-- If any command returns a 401 error, re-run `remits-cli auth` (with the same `--base-url` if you were targeting a non-default instance).
-
-### Host vs Data Mode
-
-Treat host selection and data mode as two separate decisions:
-
-- `--base-url` chooses the Remits host: localhost vs a deployed environment.
-- `--data-mode` chooses the data segment on that host: `test` vs `prod`.
-
-Examples:
-
-```bash
-# Deployed prod host, but test data segment
-remits-cli tools --base-url https://your-prod-host --data-mode test
-
-# Localhost host, but prod data segment on that localhost instance
-remits-cli tool --base-url http://localhost:8080 --name mcp_account_view --data-mode prod
-```
-
-Do not assume `--data-mode prod` implies the deployed prod host, or that `--data-mode test` implies localhost. If host matters, read `~/.remits-cli/sessions.json` first and pass `--base-url` explicitly.
-
-### Tool Execution Lifecycle
-
-`remits-cli tool` supports both synchronous and asynchronous execution. Use normal synchronous execution
-for quick investigation tools:
-
-```bash
-remits-cli tool --name "mcp_account_view" --input '{"accountId": 37}' --data-mode prod
-```
-
-**There are two independent async mechanisms — do not confuse or stack them:**
-
-1. **The tool's own async mode** (`mcp_run_action` / `mcp_run_agent`, via `executionMode:"async"` in the
-   tool input). The tool spawns the long work server-side and **returns immediately in the same HTTP
-   response** with its own run identifiers — `actionRunId` (or `agentRunId`) and, for agents, a stable
-   `sessionId`. You poll it with the tool's **own** status protocol (`controlAction:"status"`). This is the
-   preferred path for long Actions/Agents, because the run ids come back on the very first call.
-
-2. **The CLI transport async** (`--async true`). This wraps *any* tool call in a background server task and
-   returns a CLI-level `callId` immediately, which you poll with `remits-cli tool status --call-id`. Use it
-   for long tools that do **not** have their own async mode. Its start response carries `callId`,
-   `status:"running"`, `threadGroupingId`, `accountId`, `branchName`, and `dataMode` — but **not** any
-   tool-specific ids, because the tool has not run yet; those arrive inside the `result` of the polled
-   completed status.
-
-For `mcp_run_action` / `mcp_run_agent`, prefer mechanism (1) alone — it already makes the call non-blocking
-**and** returns the run ids up front. Pass your own `actionRunId`/`agentRunId` so you can poll it
-deterministically:
-
-```bash
-remits-cli tool --name "mcp_run_action" --input '{"accountId":49,"actionId":200,"executionMode":"async","actionRunId":"my-stable-run-id","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
-```
-
-Every tool response is saved to `./.remits-cli/tool-responses/<callId>.json`.
-
-### Hierarchy-scoped tool reads
-
-For read/discovery tools, the account resolved from the checkout/session is the **scope root**, not proof
-that the business record is owned by that account. This closes the common support loop where you know a
-precise document, object, event, or indexed source id but do not yet know which child account owns it.
-
-Use the tool flags rather than editing JSON by hand:
-
-```bash
-remits-cli tool --name mcp_firestore_search \
-  --input '{"collection":"statements","documentId":"1234"}' \
-  --scope children --data-mode prod
-```
-
-Available flags:
-
-| Flag | Meaning |
-|---|---|
-| `--scope self|children|hierarchy` | Expand from the repo/session account for read/discovery. Exact-id lookups usually default to `children`; broad searches default to `self` unless widened. |
-| `--target-account-id ID` | Exact owner/execution account when already known. Required by mutating tools. |
-| `--account-ids 1,2,3` | Explicit bounded owner list. The platform verifies every id against the scope root. |
-| `--anchor-account-id ID` | Path-disambiguation anchor for multi-parent account relationships. |
-
-The CLI merges these into `--input`; a value already present in `--input` wins. Tool responses echo
-`scopeRootAccountId`, `scope`, `accountIds`, and, when an exact owner is discovered,
-`resolvedTargetAccountId`. Feed that returned owner to `mcp_firestore_patch`, action/test runs, and browser
-tokens. Mutating tools do not infer or fan out writes.
-
-The implicit account ceiling is intentionally different by shape: broad searches stay capped at 100 accounts
-unless the tool says otherwise, while exact-id discovery may span up to 1000 accounts by default. If a broad
-tool returns `scopeTooBroad`, narrow with `--target-account-id`, `--account-ids`, or a smaller `--scope`.
-
-`mcp_firestore_search` handles exact Firestore document ids. `mcp_index_search` handles fuzzy/semantic
-lookup through Vertex. `mcp_bigquery_query` handles warehouse lookup/query with server-resolved
-`{table_current}`/`{table}` placeholders and the scoped `{account_filter}` predicate. BigQuery is a prod
-analytics surface, so use `--data-mode prod` when you intend to query it.
-
-Poll a CLI-transport async call (mechanism 2) by call id:
-
-```bash
-remits-cli tool status --call-id <callId> --data-mode prod
-```
-
-Pass `--wait true` to have the CLI process poll locally until the transport call completes (short polling
-requests instead of one long HTTP connection):
-
-```bash
-remits-cli tool --name "some_long_tool_without_its_own_async" --async true --wait true --input '{...}' --data-mode prod
-```
-
-Stacking both (`--async true` **and** `executionMode:"async"`) works but is redundant: the tool's
-`actionRunId`/`agentRunId`/`sessionId` then appear only in the polled completed `result`, not in the CLI
-start response — which is why the start response looks "incomplete." Pick one mechanism.
-
-`--timeout-ms <ms>` controls the per-request HTTP timeout. Prefer async execution over a large timeout for
-multi-minute work so the server task is not tied to one HTTP connection.
-
-### Data Mode
-
-Controls whether you work with test data or production data. **Default is `test`.**
-
-```bash
-remits-cli data-mode                  # Show current mode
-remits-cli data-mode set prod         # Switch to prod for investigations
-remits-cli data-mode set test         # Switch back to test for development
-```
-
-## Development Workflow
-
-### The Golden Rule: Writing Code Is Not Finishing the Job
-
-**A change is not complete until it is verified.** Writing the component is the first step, not the last.
-Two ways to prove it:
-
-1. **A Test component** (preferred) — it exercises the change *and* becomes permanent regression
-   protection. Run it with `remits-cli test run`.
-2. **Visual verification** — `remits-cli token` for a browser URL, then drive it with `playwright-cli`.
-   This is how most users think about verification: "let me see it working."
-
-Use a Test when the behavior can be asserted programmatically, a browser when the change is visual.
-Often both.
-
-**Never skip verification.** "Just do it" and "that's fine, commit it" are not evidence. If you genuinely
-cannot verify — no Test component, no relevant embeddable — say what you would need and ask how the user
-wants to proceed rather than reporting the work as done.
-
-> The *design* rule that pairs with this — never solve interpretive problems with regex cascades, keyword
-> lists, or layout-specific branching when the platform's AI surface is the right tool — is in the account
-> repo's `CLAUDE.md` and, in depth, in `features/ai-strategy.md`.
-
-### The Development Fast Loop
-
-This is how every development task should flow:
-
-#### Step 1: Understand the Request
-Read the user's request. If you may need a repo other than the current one, read `~/.remits-cli/account-repos.json` first. Then review `account-info.json` and `README.md` to understand what components exist and how they relate. Read the source of any component you'll modify before changing it.
-
-**Establish the account's shape too, not just its components.** Read the `resolution` block in
-`account-info.json` (or `mcp_account_view`): the account `type` decides whether this repo is even the right
-place to change code, `resolution.relationships` shows whether the account has more than one parent (and
-which link carries a branch/namespace/host), and `resolvedDatabaseName` tells you where its data actually
-lands. See "Account Targeting Model" and `features/account-management.md` (`mcp_get_guide`).
-
-**Also establish which world you are working in.** `remits-cli components status` reports whether the
-working tree is a **trunk** checkout or a **variant branch** checkout — which decides both what your test
-runs resolve and what a sync writes. If `account-info.json` carries a `componentBranches` section, branch
-variants of these components exist: editing an origin component will drift them, so check
-`remits-cli components branches` before changing shared code. See "Branched Component Variants".
-
-#### Step 2: Make the Change
-Edit component files under `components/`. This is local file editing — the platform doesn't know about your changes yet.
-
-**Creating a component that does not exist yet.** Files are named `<id>_<Name>.<ext>`, where the numeric
-prefix is the platform's component id. A new component has no id, so name its files with the **`new_`
-prefix** and let the sync assign one (it then renames the files to that id):
-
-```
-components/embeddables/new_MerchantPortal.groovy     # source
-components/embeddables/new_MerchantPortal.html       # markup
-components/embeddables/new_MerchantPortal.js         # client script
-components/embeddables/new_MerchantPortal.meta.yml   # metadata sidecar
-components/prompts/new_PricingReviewPrompt.md        # standalone Prompt body
-components/prompts/new_PricingReviewPrompt.meta.yml  # standalone Prompt metadata
-```
-
-**Do NOT put an `id:` in a new component's sidecar.** `id` is what links a sidecar to an *existing*
-component and is parsed as a number, so a placeholder (`id: new`, `id: TBD`) fails the **entire**
-stage/sync request with a `NumberFormatException` — not just that one file, and the error does not name
-the file. Omit the key; the platform fills it in on sync:
-
-```yaml
-# components/embeddables/new_MerchantPortal.meta.yml   — no `id:` yet
-name: Merchant Portal
-summary: One-line statement of what this component is for. This is the compact text account-info.json uses first.
-description: |
-  Longer technical description with line-number references to the key logic.
-path: /page/merchant-portal        # Readers and Embeddables only
-injectionType: DIRECT              # Embeddables only: DIRECT or IFRAME
-category: default
-auxiliary: false                   # `true` means the sync SKIPS the file entirely — see Auxiliary
-mermaid: |
-  graph TD
-    A[Request] --> B[Load documents]
-```
-
-For `components/prompts/new_*.meta.yml`, include `description` and `purpose: CUSTOM`; missing
-`description` fails trunk validation, and missing/mismatched `purpose` leaves a post-promotion Prompt
-overlay instead of pruning cleanly.
-
-> **Staging creates nothing in the database, so a `new_` component has no id yet — address it BY NAME.**
-> `remits-cli test run --test "My Suite"`, not `--test <id>`. Component-to-component resolution and
-> request-level addressing are name-based too; the component guides cover those. After a trunk sync the
-> component has a real id and either form works.
-
-#### Step 3: Stage to Platform
-
-```bash
-remits-cli components stage
-```
-
-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.
-
-**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**.
-
-This applies to:
-- Creating new components (the platform won't find them until staged)
-- Editing existing components (the platform runs the previously staged version until you re-stage)
-- Every iteration of the fix loop — every edit requires a fresh stage before the next test run
-
-#### Step 4: Verify the Change
-
-**Option A — Run Tests** (if Test components exist for this area):
-
-```bash
-remits-cli test run --test <TEST_ID_OR_NAME>
-remits-cli test run --test "Invoice Tests" --names "specific test case"
-```
-
-Tests run on the platform against your staged snapshot. They stream results in real-time. If they fail, fix the code, re-stage, and re-run.
-
-Important test-runner constraints:
-- `remits-cli test run` now defaults to `test` dataMode unless you explicitly pass `--data-mode prod`.
-- **`--names` is delimited by `|`, and may be repeated.** A comma still splits a single `--names` value
-  (legacy behaviour), which is why a case name containing a comma used to be cut in half and match
-  nothing. Prefer `|` or repetition whenever a name might contain punctuation:
-  ```bash
-  remits-cli test run --test 13 --names "a case, with a comma|another case"
-  remits-cli test run --test 13 --names "a case, with a comma" --names "another case"
-  ```
-- **A selector that matches no case FAILS the run.** It used to report `0 passed, 0 failed`,
-  `completed`, and exit 0 — indistinguishable from a suite where everything passed. The run now names
-  the unmatched selectors and lists the cases the suite actually declared, and exits non-zero.
-
-If no relevant Test component exists yet, consider creating one. Test components live in `components/tests/` and follow the same component structure. They provide permanent regression protection — every test you write today saves debugging time tomorrow.
-
-New test files use the `new_` prefix (e.g., `new_MyTest.groovy`) and no `id:` in the sidecar — see "Creating a component that does not exist yet" in Step 2. Run them **by name** (`remits-cli test run --test "My Test"`) until a sync assigns an id and renames the file.
-
-**How to write the Test itself is not a CLI concern** — what a suite can assert, how mocks behave across HTTP/relay boundaries, driving an embeddable in-process, and the front-stage-only rule all live in `guides/components/test-components.md`. Read that before authoring a suite.
-
-**Option B — Visual verification with Playwright** (for UI changes or when the user wants to "see it"):
-
-```bash
-# Generate a browser-accessible URL for an embeddable
-remits-cli token --path embeddable/index/<EMBEDDABLE_ID>
-```
-
-This returns an `embeddableUrl`. Use Playwright to open and interact with it:
-
-```bash
-# Open the embeddable in a headed browser
-playwright-cli open --headed "<embeddableUrl>"
-
-# Take a snapshot to see the current state
-playwright-cli snapshot
-
-# Interact with elements
-playwright-cli click "text=Submit"
-playwright-cli fill "#amount" "500.00"
-
-# Verify specific content
-playwright-cli eval "() => document.querySelector('.total-amount').textContent"
-```
-
-The `testMode` metadata confirms you're testing against staged changes, not production.
-
-**Two different token keys come back, for two different jobs.** When `--path` resolves to an
-Embeddable, the response carries an `embedTokenKey` and a paste-ready `embedSnippet` alongside the usual
-`tokenKey` / `embeddableUrl`:
-
-| Field | Use it for |
-|---|---|
-| `tokenKey` / `embeddableUrl` | Opening the page in a browser (Playwright, or clicking the link) |
-| `embedTokenKey` / `embedSnippet` | The `<script>` embed loader — verifying the page as a HOST SITE embeds it |
-
-They are not interchangeable. The loader's request carries **no path**, so it resolves the component
-purely from the embeddable-scoped token key's persisted context. The browser `tokenKey` names the account
-preview URL; `embedTokenKey` names the host-loader credential. The response also echoes `injectionType` /
-`renderMode` / `headMode`, which decide what a host actually receives
-(`guides/components/embeddable-components.md`).
-
-**This works for a `new_` component that has never been synced.** The embed token key carries the
-component NAME as well as its id, so a staged, id-less Embeddable is loader-addressable — you do not
-have to sync it, or borrow another component's id, just to verify a host embed.
-
-**Option C — Use investigation tools** (for backend/data changes):
-
-For changes to Readers, Actions, or Rules that process data rather than display UI, verify by examining the data they produce:
-
-```bash
-# After triggering the component (via test or manual action), check the result
-remits-cli tool --name "mcp_firestore_search" --input '{"accountId": <ID>, "collection": "<collection>", "limit": 5, "sort": [{"field": "_lastModifiedAt", "direction": "DESC"}]}'
-```
-
-For long-running backend verification, use the Action runner's own async mode (`executionMode:"async"`) and
-poll by `actionRunId` rather than holding a single request open (see "Tool Execution Lifecycle" for why not
-to also stack the CLI `--async` flag):
-
-```bash
-remits-cli tool --name "mcp_run_action" --input '{"accountId": <ID>, "actionId": <ACTION_ID>, "executionMode": "async", "actionInput": {...}}' --data-mode test
-# then poll:  {"controlAction":"status","accountId": <ID>, "actionRunId":"<actionRunId>"}
-```
-
-#### Step 5: Iterate If Needed
-
-If verification reveals issues, repeat the loop: **edit → stage → run**. Every iteration must include a fresh `remits-cli components stage` after your edits and before the next test run. Never run a test immediately after editing without staging first — the platform will execute the previous version, not your latest changes.
-
-Don't ask the user for permission to re-iterate — just do it. Only stop to ask if you're stuck or unsure about the intended behavior.
-
-If the work is tied to a support ticket:
-- Use `remits-cli ticket status --status in_progress` once you have started substantive work.
-- If a new reply arrives, re-read the ticket and incorporate the reply into your current plan.
-
-#### Step 6: Update Documentation
-
-Before committing, update metadata so the next session understands what changed:
-
-1. **`.meta.yml` sidecars** — Update `summary`, `description`, and `mermaid` for each modified component. `summary` is what drives the compact component description in generated `account-info.json`; `description` is the fallback when no summary is set and is capped in that file.
-2. **`README.md`** — If the change affects account-level capabilities or workflows.
-3. **New components** — Always fill in `.meta.yml` immediately.
-
-`account-info.json` is read-only — never edit it. It regenerates automatically after sync. Component
-entries prefer `summary`, fall back to capped `description`, and cap `mermaid`; relationships remain as
-generated. On a trunk sync it describes the owning repo account. On a subscriber-initiated variant sync it
-describes the subscribing account reached through the branch edge, even though the component files still
-belong to the owner's repo.
-
-#### Temporary Experiment Workflow
-
-Use this when you need to prove a guard or assertion by temporarily making a local component fail. The staged
-Redis cache can affect later test/tool runs, so always clear it after restoring the file:
-
-```bash
-# make temporary local edit
-remits-cli components stage
-remits-cli test run --test <id-or-name> --names "<case name>"
-git restore <file>
-remits-cli components clear --all
-remits-cli components status
-```
-
-For narrower cleanup when only one staged component should be cleared:
-
-```bash
-remits-cli components clear --component-type Action --component-id 25
-```
-
-#### Step 7: Commit and Durable Sync
-
-Once verified and documented, create a normal git commit first:
-
-```bash
-git add -A
-git commit -m "description of what changed and why"
-git push origin <branch>
-```
-
-This separates the local failure boundaries cleanly:
-1. Local git commit
-2. Remote push
-
-After the push, run the **Component Integrity Rules** safety checks before any durable platform sync. Do not run
-`remits-cli components sync` when local files, `account-info.json`, and live inventory disagree about component
-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
-remits-cli components sync
-git pull --ff-only origin <branch>
-```
-
-`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.
-
-The CLI now returns the post-sync branch SHA from the platform and verifies that your `git fetch` and final `git pull --ff-only` land on that exact commit. If that SHA does not match `origin/<branch>` or local `HEAD`, stop immediately and investigate the race or branch drift instead of guessing.
-
-`remits-cli components commit` still exists as a convenience wrapper, but agents should not call unsupported
-subcommand help variants such as `remits-cli components commit --help` to discover behavior. Consult this skill,
-the CLI source, or `remits-cli components` documentation instead. If an exploratory or commit command behaves
-unexpectedly, stop and inspect the repo-local session log before running any mutating follow-up command.
-
-**Git is required for durable sync.** The platform syncs by pulling from the git remote (`GitHubClient.syncFromRepository`). If `git push` fails, the server has nothing new to sync. You can still **stage** and **test** without git — only durable sync requires it.
-
-#### Step 8: Close the Ticket
-
-If the request came from a support ticket, the task is not complete until you update the ticket lifecycle yourself:
-
-1. Re-read the ticket if needed to confirm the latest state and replies.
-2. If the work is done and verified, call `remits-cli ticket complete` and include a concise resolution summary.
-3. If you cannot finish, use `remits-cli ticket status` or `remits-cli ticket release` with clear notes so the next agent can continue.
-4. Do this automatically. The human user should not need to instruct you to update the ticket.
-
-Options:
-```bash
---message "commit msg"         # Commit message (default: auto-generated timestamp)
---allow-empty true             # Allow empty git commits
-```
-
-### User Confirmation Preferences
-
-Some users want to review every change before staging. Others want you to move fast and only stop if something breaks. **Pay attention to how the user communicates:**
-
-- If they say "just fix it" or "go ahead" — move through the loop without asking for confirmation at each step. Stage, verify, commit.
-- If they say "show me first" or "wait before committing" — pause at the appropriate step.
-- If they say "you don't need to ask me" or "stop asking" — remember this preference and work autonomously through the full loop.
-
-The default should be: make the change, stage it, verify it, and present the results. Only block on the user when you're genuinely unsure about intent.
-
-## Component Resolution: Staging Cache vs DB (which "version" actually runs)
-
-When the platform executes a component it resolves the source from one of two places, then compiles it
-behind an in-memory cache. Understanding this is the difference between "my change isn't working" guesses
-and a precise diagnosis.
-
-### The three source layers + the compile cache
-
-1. **CLI staging cache (Redis, 240-min TTL).** Branch + user + account scoped overrides written by
-   `remits-cli components stage`. These shadow the layers below **only during CLI/test-mode execution**
-   (see "When staged overrides apply" below).
-2. **Committed branch variants (`ComponentVariant`, MySQL).** Durable, branch-scoped overlays of a
-   component. Unlike staging these are **not** user-scoped, do **not** expire, and **do** apply to normal
-   production traffic — for the accounts that subscribe to that branch. See
-   "Branched Component Variants" below. Most accounts have none, in which case this layer is inert.
-3. **Database trunk row (the committed live component).** What `mcp_component_view` reads, what an
-   unsubscribed prod run uses, and what a trunk `commit` writes to.
-
-Resolution order is **staged → variant → trunk**, and each layer *layers over* the one beneath it rather
-than replacing it: a payload that only carries `source` inherits `path`, `objectType`, `inputSchema` etc.
-from the layer below. A staged edit made on a variant branch therefore layers over **that variant**, not
-over trunk.
-
-Plus the compile cache:
-
-- **Compiled-closure cache (`BaseClosureDomain.CLOSURE_CACHE`).** An in-memory, **per-JVM-instance** Guava
-  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.
-
-### Staging cache key format
-
-```
-# default lane (no workspace)
-account:<accountId>:cli:<cliUserId>:components:<branch>:<family>:id:<componentId>
-account:<accountId>:cli:<cliUserId>:components:<branch>:<family>:name:<normalizedName>
-
-# workspace lane
-account:<accountId>:cli:<cliUserId>:components:<branch>:ws:<workspace>:<family>:id:<componentId>
-```
-
-The staging scope is therefore **account + cli user + branch + workspace**. `workspace` is optional and
-absent by default; see "Working alongside other agents: the staging WORKSPACE" above.
-
-`<family>` is the lowercased component family (`reader`, `action`, `test`, `embeddable`, ...). Both an
-`id:` and a `name:` key are written per stage. The entry value carries: `kind` (the family), `type` (the
-component's OWN type enum such as `ObjectType`/`RuleType`, or absent — **never** the family), `hash`,
-`updatedAt`, the staged content field(s) (`source`/`prompt`/`html`/`javascript`/`schema`/
-`inputSchema`/`previewData`), and `.meta.yml` metadata fields such as `description`, `summary`, `mermaid`,
-`path`, Embeddable `injectionType`, `category`, and Schema flags (`enableTrigger`, `enableFullText`, `enableRAG`, `enableRevisions`,
-`enableBigQuerySync`, `enableRules`, `anchor`, `auxiliary`).
-
-### How the platform picks staged vs DB (the compile signature)
-
-At compile time the platform computes a **signature** that tells you which layer won:
-
-- Staged override present → `compileSignature = "cli:<hash>"` (the staged content hash).
-- Committed branch variant → `compileSignature = "variant:<variantId>:<hash12>"`.
-- Neither → `compileSignature = "version:<N>:<sourceHash12>"` (the DB row version plus a source hash
-  prefix, so source changes cannot reuse a stale compile entry on the same instance).
-
-The three namespaces are distinct on purpose: a component's staged, variant, and trunk closures coexist in
-the compile cache without colliding.
-
-That signature is logged. Querying for it is the single most reliable way to know what ran:
-
-```bash
-remits-cli tool --name mcp_system_logs --input '{"node":"remitsAdmin-east5","timeRange":"1h","filter":"Using Cached BCD"}' --data-mode prod
-```
-
-> **Pass the bare phrase — never hand-write a `textPayload:` filter.** In production the platform's
-> logback encoder writes every `log.*` line to **`jsonPayload.message`**; only `println`/stdout lands in
-> `textPayload`. A `textPayload:"..."` filter therefore matches **zero** rows for nearly every platform
-> log line, and zero rows is indistinguishable from "it never happened" — which has already caused a real
-> misdiagnosis. `mcp_system_logs` now widens a bare phrase (and any `textPayload:"..."` clause) to cover
-> both shapes, and echoes the executed filter back as `filterApplied`. A filter that names `jsonPayload`
-> explicitly is passed through untouched.
-
-`Using Cached BCD [ID: 230, Type: Action, Signature: cli:08cc...]` → ran a **staged** override.
-`...Signature: variant:14:9f2c1a...]` → ran a **committed branch variant**.
-`...Signature: version:37:abc123def456]` → ran the **committed trunk** version.
-
-### When staged overrides apply
-
-Staged overrides resolve whenever the execution carries a **CLI-scoped TestMode** — i.e.
-`TestMode.branchName` and `TestMode.cliUserId` are set. That includes:
-
-- `remits-cli test run`
-- `remits-cli tool`
-- `remits-cli tools`
-- tokenized runs minted with a branch-aware CLI token
-
-For `remits-cli tool`, the CLI TestMode now stays active for the **entire tool execution**, not just the
-top-level tool lookup. That means nested `reader()`, `action()`, `utility()`, `account.getTool()`, and
-similar component resolution inside the tool also see the staged branch context.
-
-`dataMode` is separate from staged resolution:
-
-- `branchName` + `cliUserId` decide whether staged components can resolve.
-- `dataMode:test|prod` decides which data surface the tool/test/token runs against.
-
-So a `remits-cli tool --data-mode prod` call can intentionally execute **staged code against prod data**
-for investigation or recall testing, while a normal live webhook / non-CLI runtime path with no CLI
-TestMode still uses the committed DB source. Staging remains a dev/verification surface, not a deploy.
-
-### Diagnosing which version is in play
-
-- **See staging metadata for a component:** `mcp_component_view` (omit `fieldName`) returns `staging` /
-  `stagedFields`, telling you whether a staged entry exists and which fields are staged.
-- **Inspect the raw staged entry + TTL in Redis:** use `mcp_cache`.
-  ```bash
-  # find staged entries for one component
-  remits-cli tool --name mcp_cache --input '{"action":"scan","pattern":"account:52:cli:*:components:*:reader:id:181","includeValuePreview":true}' --data-mode prod
-  # dump one exact key
-  remits-cli tool --name mcp_cache --input '{"action":"inspect","key":"account:52:cli:23:components:main:reader:id:181"}' --data-mode prod
-  ```
-  The preview shows `kind`/`type`/`hash`/`updatedAt` + a source snippet — confirm it's your content and
-  that `type` is NOT the family (a family value in `type` is a tool bug that crashes hydration, e.g.
-  `No enum constant ObjectType.reader`).
-- **Confirm the DB version:** `mcp_component_view` reads the live DB source directly (no staging, no compile
-  cache), so it is the source of truth for "what was committed."
-- **Ask the CLI what is staged:** `remits-cli components status` lists this lane's staged entries,
-  including staged fields, aliases, hashes, and TTLs. The default terminal output is concise; pass `--json` or
-  `--verbose` when you need the full staged-entry payload. `remits-cli components clear` removes those entries
-  when you intentionally want to fall back to DB source.
-
-### Working alongside other agents: the staging WORKSPACE
-
-Staging is scoped by `(account, cli user, branch, workspace)`. Account and user are fixed for a repo, so
-**without a workspace the git branch is the only isolation axis** — and `components stage` uploads the
-ENTIRE repo and REPLACES the lane rather than merging into it. Two agents on one branch therefore
-overwrite each other, and a `components commit` clears the lane out from under the other one.
-
-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
-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
-```
-
-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
-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.
-- 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
-  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 clear --all` is scoped to YOUR lane and never touches another agent's.
-
-### 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.
-- **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
-  the staged entry rather than lingering — "restore the file and re-stage" restores the staged state, which
-  is the only mental model that is safe to have. Content fields still layer (they come from separate files),
-  so a partial stage is unaffected.
-- `remits-cli components clear` drops staged entries when you intentionally want to fall back to committed DB
-  source. An empty staging scope is clean state, not a failure.
-- `remits-cli components sync` syncs the DB from the pushed git remote and then clears staged entries for the
-  synced components, so a clean promotion leaves a clean staging cache. Because sync reconciles the remote repo
-  into the live component database, it must pass the Component Integrity Rules first. Never use sync only to
-  clear staging, to recover from a mismatched ID, or to retry after an unexpected create/delete/rename response.
-
-### Stale after sync / commit (the in-memory compile cache)
-
-After a `git sync` or a `commit` updates the DB source, a **running instance can keep executing the
-previously-compiled closure** until the version-keyed signature changes and that instance's
-`CLOSURE_CACHE` misses (or the instance recycles). Symptoms: `mcp_component_view` shows the new source, but
-behaviour (or a freshly-staged entry produced by an edited *tool*) still reflects the old code. This is the
-standard Grails no-hot-reload caveat — it is environmental, not a code defect. Verify the live entry/source
-with `mcp_cache` / `mcp_component_view`, and if a platform/tool source change must take effect immediately,
-the platform owner recycles the instance.
-
-## Account Resolution: how a request travels the account graph
-
-Component inheritance, branch variants, and where data physically lives are all decided by **how the
-current request reached the executing account**. Read this before debugging *"my subscriber isn't picking
-up the branch"* or *"why is this account reading the wrong collection"* — those are almost always
-resolution questions, not component bugs.
-
-> The model behind it — the linear inheritance walk, the ambiguity rule, the three orthogonal edge
-> properties, and path-scoped storage namespaces — is in **`platform-overview.md` → *Account Structure***,
-> which is already loaded. What follows is how to *observe* it from the CLI.
-
-**The anchor is the branch of the graph you travelled.** At runtime it is `scope_account_id`, stamped onto
-the `Object` / `Event` / `Alert` / `ObjectLog` records a run creates, so async workers re-resolve on the
-same branch. A **null** anchor means "walk the structural chain". Entry points that already know the
-branch supply an anchor; from the CLI you supply it explicitly with `--as-account`, `--variant-branch`, or
-by using the edge's own host.
-
-### Seeing an account's edges
-
-```bash
-remits-cli tool --name mcp_account_view --input '{"accountId": 101}' --data-mode prod
-# then read: resolution.relationships, resolution.resolvedDatabaseName, resolution.componentBranch
-```
-
-`resolution.relationships` returns one entry per structural link, primary first, each carrying its own
-`branchName` / `databaseName` / `domainName`. The hierarchy tree flattens every link into one shape, so
-this block is the **only** place that answers "how many parents does this account really have, and which
-link carries what?"
-
-### When a subscription "doesn't work"
-
-1. Does the account have a primary parent, or is it membership-only? Count `resolution.relationships` and
-   see which is `primary: true`. (Membership-only **and** several edges ⇒ ambiguous ⇒ trunk, by design.)
-2. Which **edge** carries the `branchName`? `remits-cli components branch <name> --subscribers` prints
-   `via primary|membership edge -> parent N`.
-3. Was the run anchored through *that* edge's parent? Re-run with `--as-account <subscriberId>` so the
-   account's own edge selects the branch, exactly as production would.
-4. Check the resolved layer, not the source text: `testComponentSource`, or the `variant:<id>:<hash>`
-   compile signature (see "Diagnosing a variant").
-
-### The same block answers the non-branch questions
-
-- *"Why are this account's documents not where I expect?"* → compare `databaseName` vs
-  `resolvedDatabaseName`, and check for a `databaseName` on one of the `relationships` edges — it applies
-  to everything below that edge.
-- *"Why does this hostname land on the wrong account?"* → compare `domainName` vs `resolvedDomainName` and
-  the edge `domainName`. An **edge** host wins over the account's own, and additionally supplies the path
-  travelled — which is what makes that edge's branch variants apply.
-
-**Users are not part of this graph** (see `platform-overview.md`). Use `mcp_account_user_admin`
-(`action:'users'`, `action:'user'`, or `action:'user_update'`) for user membership and account-scoped user
-fields. Drop to `mcp_sql_query` against `user` / `user_account` only for raw join-table evidence.
-
-## Branched Component Variants (per-account component overrides)
-
-When one account — often a customer nested several levels down — needs *slightly* different behavior from
-a component owned by its platform or product account, the answer is a **branch variant**: a durable,
-branch-scoped overlay of that component, resolved only by accounts subscribed to that branch. The wrong
-answer is per-account `if/then` logic inside the origin component.
-
-> **`features/subscriber-branch-promotions.md` (`mcp_get_guide`) is the guide for this.** It owns the
-> mental model, the five scenarios you will actually meet, the full promotion procedure, what happens to a
-> `new_` component across a promotion, merge-conflict resolution file by file, removals, and the approval
-> gates for running a promotion as a coding agent. **Load it before promoting anything.** This section
-> covers only the CLI surface and the traps that bite at the command line.
-
-Three facts that everything else follows from:
-
-- **A branch is not an account.** Subscription is many-to-many, it applies to the subscribing account
-  *and its descendants*, and a subscribing account still has its own trunk components which merge on top.
-- **A variant keeps the origin's component id** — it is an overlay, not a copy. That is what makes drift
-  computable.
-- **Sparseness is computed at sync time, not declared.** A git branch physically contains every file; only
-  the ones whose content *differs from trunk* become variants. A file that is absent becomes a
-  **tombstone**; a file whose id prefix is not a live trunk id (`new_Foo.groovy`) becomes a **branch-only**
-  component keyed by name.
-
-### 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**:
-
-| 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 |
-
-Do not infer this from the branch name. Ask:
-
-```bash
-remits-cli components status
-```
-
-```
-Working tree: VARIANT BRANCH "feature_branch"  (trunk is "main")
-  runs resolve:   trunk + the 'feature_branch' variant overlays
-  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
-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
-exactly like a resolution regression. (Live example: a branch-variant suite scored 4/15 from a variant
-checkout and 15/15 from trunk, with no code difference.) **Run branch-variant suites from trunk, or pass
-`--variant-branch none`.** Before concluding "variant resolution is broken", re-run from trunk.
-
-**Two other things differ from trunk while you work on a branch:**
-
-- **Keep the origin id in the filename.** `50_ExtractInvoice.groovy` on the branch overlays Action 50.
-  That is what preserves component identity and lets drift be computed against the origin.
-- **Nothing is renamed.** A variant sync never renames files and never repoints the account's trunk
-  branch. A `new_*` file stays `new_*`.
-
-**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
-`AccountRelationship` edge, and the branch has **exactly one** subscriber, the branch's
-`account-info.json` is intentionally rooted at that subscriber. With **more than one** subscriber the
-refresh is skipped (the sync result says so under `accountInfo.skipped`/`reason`) and the file keeps
-describing the owner, which is at least true for all of them. Overlay ownership is unaffected either way.
-
-Read `resolution` before acting from any checkout — in particular `resolution.accountId` (the account this
-checkout should be treated as; **read this, not the top-level `id`**), `resolution.role`,
-`resolution.componentOwnerAccountId` (whose trunk ids the files overlay and whose overlays a sync writes),
-and `resolution.componentBranch` / `resolution.scopeAccountId` (the branch and the path anchor that made
-this subscriber resolution possible). If a variant checkout's `account-info.json` is stale
-and still names the owner, run the first repair sync with an explicit subscriber target
-(`remits-cli components sync --account-id 101`), then `git pull --ff-only`.
-
-### Two levers, two different questions
-
-- **`--as-account <id>`** changes **who** the run executes as, so that account's own edge picks the branch.
-  Answers *"what does customer X actually get?"* Only narrows downward (the target must be reachable from
-  an account you already have access to). It works for a `parentId`-less, membership-only subscriber too:
-  the anchor is derived from the branch you name, or from the account's single branch subscription. It
-  **refuses to guess** when an account has several edges each carrying a different branch — the run then
-  resolves trunk, and you must name the branch.
-- **`--variant-branch <name>`** changes **which branch**, from any checkout. Answers *"what does branch Y
-  look like?"* — most useful for verifying a freshly committed branch **before** any edge subscribes to
-  it. `--variant-branch none` (or `trunk`) forces production/subscription semantics without leaving the
-  branch.
-
-Both work on `remits-cli test run` and `remits-cli token`; `--variant-branch` also works on
-`remits-cli tools` and `remits-cli tool`, so tests, browser URLs, tool discovery, and tool execution can
-all inspect the same committed variant world.
-
-The strongest end-to-end proof for a UI-visible variant is a token, not a log line:
-
-```bash
-remits-cli token --path embeddable/index/50 --as-account 101   # subscriber -> variant
-remits-cli token --path embeddable/index/50                    # owner      -> trunk
-```
-
-Each answer carries a **`resolution`** block for the account the token executes as — `role`,
-`componentBranch` and its owner, `resolvedDatabaseName`, `resolvedDomainName`, `scopeAccountId`, and a
-one-sentence `summary`. Read it before opening the URL: `accountId` alone does not say whether a branch
-overlay applies or which storage namespace the page will read, and those are exactly what
-`--as-account` is being used to change.
-
-Separate branch fields, because these questions answer differently and can disagree:
-
-| Field | Answers |
-|---|---|
-| `componentBranch` | what **this token** will resolve |
-| `componentBranchSource` | `probe` (an explicit `--variant-branch`), `subscription` (the account's edge), or `trunk` |
-| `subscribedComponentBranch` | what the **account graph** says, independent of this token |
-| `componentBranchAnchored` | whether **this resolution actually reached** that subscription |
-
-A single `componentBranch` field would have reported `trunk` under `--variant-branch X`, for a token that
-resolves `X`.
-
-**Subscribing to a branch and resolving through it are different facts.** An account subscribes on an
-edge; a *request* resolves through that edge only when something named the path (`--as-account`, the
-edge's own host, an explicit `--variant-branch`). An account with no `parentId` and several upward links
-resolves trunk by design — the resolver refuses to guess a path. So this is a normal, explainable state:
-
-```
-"componentBranch": null,              // this token resolves TRUNK
-"componentBranchSource": "trunk",
-"subscribedComponentBranch": "forked", // ...but the account does subscribe
-"componentBranchAnchored": false       // ...and nothing anchored this request to it
-```
-
-Reading `componentBranch` alone there tells you the account is on trunk, which is true — and leads you to
-conclude it has no branch, which is false. If several edges carry branches, none is picked for you:
-`subscribedComponentBranch` is `null` and `subscribedComponentBranches` lists them.
-
-Under a probe, `componentOwnerAccountId` is the **nearest account on the token's resolution path that owns
-variant rows for X** — not an edge lookup, which answers `null` for the ordinary case of a variant
-committed before anything subscribes to it. `null` means no account on that path owns rows for X, and what
-that implies depends on the account, so read `summary`:
-
-- **on trunk** — the page resolves what it would without the probe; the branch is not committed yet.
-- **resolving through a subscription** — the probe **suppresses** it. `variantBranch` outranks the
-  subscription before it is consulted, so the page resolves **trunk**, not the overlays that account
-  normally gets. Drop `--variant-branch` to see the subscription.
-- **subscribed but not anchored** — it was already resolving trunk before you probed. Dropping
-  `--variant-branch` will *not* by itself show you the branch; name the path as well.
-
-The page itself then states the same facts. Its hidden `remits-session-info` line — which appears in an
-accessibility snapshot with no script — carries `Account` (what it runs as), `Addressed Account` (what
-the URL/token named), `Data Lane`, `Component Branch`, `Variant Applied`, and `Scope Account`.
-
-**`Component Branch` is the branch SELECTED; `Variant Applied` is what actually overlaid.** They are two
-fields because a branch can be selected and overlay nothing: `--variant-branch missing_branch` reports
-`Component Branch: missing_branch` while the page renders trunk components. So read `Variant Applied` —
-the `ComponentVariant` row id this page's component resolved through, or `none` — when the question is
-"did my variant apply?". That is a far sharper signal than inspecting the rendered markup for a style you
-expected.
-
-If `components status` shows staged entries that you cannot safely clear, isolate verification in an
-unused staging namespace instead of deleting someone else's cache:
-
-```bash
-remits-cli test run --test "Invoice Tests" --branch promotion-check-empty --variant-branch none --as-account 101
-remits-cli token --path embeddable/index/50 --branch promotion-check-empty --variant-branch none --as-account 101
-```
-
-Here `--branch` is only the CLI staging-cache namespace, and `--variant-branch none` keeps runtime
-resolution on production/subscription semantics. Do **not** use this pattern with `components sync` or
-`components commit`: for those commands `--branch` is the GitHub branch to reconcile.
-
-### The SDLC is identical on a variant branch
-
-```bash
-git checkout feature_branch          # or: git checkout -b 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
-remits-cli test run --test "Invoice Tests" --as-account 101   # ...as the real subscriber
-git add -A && git commit -m "..." && git push origin feature_branch
-remits-cli components sync --dry-run # inspect overrides/additions/tombstones without writes
-remits-cli components sync           # writes ComponentVariant overlays ONLY
-```
-
-Promotion back to trunk is a **git** operation followed by a **trunk** sync — the platform merges nothing
-for you, and merging a branch promotes its **deletions** as hard deletes. Do not improvise it: follow
-`features/subscriber-branch-promotions.md`. For a real trunk promotion with many `new_` files, use
-`remits-cli components sync --summary --timeout-ms 300000`; the platform may need longer than the default
-60 seconds to create rows, push rename/meta commits, and regenerate account metadata.
-
-### Where am I in the promotion loop?
-
-```bash
-remits-cli components promotion            # the branch you are standing on
-remits-cli components promotion --branch forked --json
-```
-
-**Run this before every promotion step and after every one.** It reports only — no git, no writes — and it
-reads the remote (which is what the platform syncs from, not your working tree). It works from either
-checkout, because it resolves the branch's owner itself. It exits non-zero while blockers remain, so treat
-that as "do not proceed".
-
-| Phase | Meaning | Next |
-|---|---|---|
-| `converged` | branch == trunk | nothing to do; this is also what a **finished** promotion looks like |
-| `ready` | ahead of trunk, current with it | promote |
-| `diverged` | behind trunk | `git merge <trunk>` into the branch, re-sync, re-read the plan |
-| `awaiting-merge-back` | fully contained in trunk, trunk has moved on | **steps 4–5 are owed** — merge trunk back and re-sync |
-
-Two things it tells you that nothing else does:
-
-- **Which commit the stored counts describe, on BOTH axes.** An overlay is stored only while a file
-  differs from trunk, so the stored set is a statement about a (branch, trunk) pair and either side moving
-  makes it stale: `[STALE — does not match the branch HEAD]` (the branch was pushed since) or
-  `[STALE — matches the branch HEAD, but trunk has moved since]`. The second is the easy one to miss —
-  measured live, a branch at its own synced HEAD reported 2 stored overlays against a real plan of 21.
-- **That a promotion is unfinished.** `awaiting-merge-back` is what a promotion that *looked* successful
-  leaves behind: trunk is correct and its tests pass, while the subscriber silently keeps resolving its
-  pre-promotion overlays — including for any fix made afterwards. **A trunk sync succeeding is step 2 of 5,
-  not completion.**
-
-### Subscribing, unsubscribing, retiring
-
-```bash
-remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]
-remits-cli components branch <name> --unsubscribe <accountId>
-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.
-
-- **`--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
-  `mcp_account_user_admin` `action:'edge_add'` (`targetAccountId` = the child, `parentAccountId` = the
-  owner), which also accepts `branchName` so you can create and subscribe in one call.
-  - **Many older accounts have no relationship row at all** — the edge table was added after the fact and
-    never backfilled, so an account whose parent link is only `Account.parentId` resolves fine but has
-    nothing to attach to. `mcp_account_user_admin` `action:'reparent'` with the account's *current* parent
-    is the one-call repair: it creates the missing primary edge and changes nothing else.
-- **When the account has several parents, say which edge you mean** with `--parent-account <ownerId>`.
-  Without it the CLI picks the edge to the owner whose branch you are managing, then falls back to the
-  account's primary edge — which may not be the one you intended. `--subscribers` prints
-  `via primary|membership edge -> parent N` so you can confirm.
-- **Primary-edge subscriptions are structural.** If the selected edge is the account's `parentId` edge,
-  subscribing it makes that account and descendants resolve the branch by default even though `parentId`
-  still points at the same parent. The server refuses this write unless you pass
-  `--confirm-primary-edge`; run `--dry-run` first and prefer a membership edge for fork/pilot
-  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`.
-
-**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
-**schema** variant deserves the same care as a trunk schema change: it can change the JSON schema *and*
-`collectionName`, so it changes validation and where the subscriber's documents physically land. A
-branch-only agent (a `new_*` file under `components/agents/`) defaults to `type: AI` so agent lookups
-find it.
-
-A variant speaks the same `.meta.yml` vocabulary trunk does; keys outside that set are ignored on purpose,
-because trunk cannot express them either — allowing them would mean a branch behaves one way and silently
-loses that behavior the moment it is promoted. **One documented exception: an agent's `tools:` list cannot
-be overridden by a variant.** It maps to a GORM association that `agent()` populates from the trunk row, so
-a `tools:` list on a branch is ignored. Change trunk, or have the agent select tools at runtime.
-
-### Danger profile on a variant branch (different, not absent)
-
-The Component Integrity Rules' worst case — *"a missing file hard-deletes a live component"* — **does not
-apply on a variant branch.** Variant sync writes overlay rows only; it cannot create, delete, rename, or
-overwrite a trunk component. That makes a variant branch a genuinely safer place to iterate.
-
-The analogous hazard is different, and you must still respect it:
-
-- **A trunk component with no file on the branch becomes a TOMBSTONE**, which *hides* that component from
-  every subscriber. It is reversible (restore the file, re-sync) and never touches trunk — but to a
-  subscribing account it looks exactly like the component was deleted. Confirm every omission is
-  deliberate before syncing.
-- **Deleting a file means "remove the component", not "stop overriding it."** To withdraw an override,
-  make the file identical to trunk again — the sync then removes the variant row.
-- **Keep the branch rebased.** A branch physically carries every file, so anything trunk added *after* the
-  branch was cut is absent from it. The sync now asks git which of those absences are real deletions
-  (comparing against the merge base) and refuses to tombstone the rest, reporting them as
-  `skipped: absent from the branch but never deleted on it`. Treat any such entry as "merge trunk in" —
-  if an older sync already stored one of those absences as a tombstone, a non-dry-run sync prunes it and a
-  dry run reports `wouldPrune: true`. The classification falls back to a conservative ratio guard when
-  GitHub's compare is unavailable or its file list comes back truncated, which the sync output says
-  explicitly.
-- **Use `components sync --dry-run` before risky variant syncs.** It reports `overridden`, `added`,
-  `removed`, `unchanged`, `skipped`, and `errors` without writing rows, caching the sync SHA, or clearing
-  staging. Existing overlay ids appear as `variantId`; an `unchanged` row with `pruned:true` means the
-  branch has converged back to trunk and the overlay would be removed. It is rejected on trunk, and
-  `components commit --dry-run` is unsupported because `commit` performs local git writes before syncing.
-- **The sync refuses a wholesale removal.** Above roughly a third of a kind — or **100% of a kind at any
-  size** — it aborts that kind, reports why, and points at a rebase. Rebasing is almost always the real
-  fix. Only when the removals are genuinely deliberate, re-run with `--force-tombstones`.
-- **Deleting a trunk component cascades**: its overlays on every branch are removed with it.
-- **A removal you did not author usually means TRUNK is drifted**, not that the branch deleted something.
-  A component that exists in the DB with **no file on trunk** is missing from every branch too, so it
-  shows up as a phantom `removed` in *every* branch preview — while the trunk sync separately tries to
-  hard-delete it on every run. Check whether the file exists on trunk before "fixing" it on the branch;
-  the repair is to mirror the live DB source back into the trunk repo (Component Integrity Rules).
-
-### Inspecting branches and drift
-
-```bash
-remits-cli components branches                                  # branches with variants, counts, drift
-remits-cli components branch feature_branch                     # overridden / added / removed + subscribers
-remits-cli components branch feature_branch --diff 50 --component-type action
-remits-cli components branch feature_branch --subscribers
-remits-cli components branch feature_branch --json              # the stored overlay content
-```
-
-**Drift is the number to watch.** Each variant records the trunk content hash at the moment it was cut
-(`originHash`). When the origin component later changes, the variant is reported **DRIFTED** — the branch
-is now based on a stale version and someone should reconcile it. Before editing an origin component, check
-whether variants of it exist: the owner account's `account-info.json` carries a `componentBranches`
-summary, and `components branches` gives the live view. A change to the origin silently drifts every
-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).
-
-**Trunk moving also invalidates a branch.** Variant sparseness compares branch content against *current*
-trunk, so a trunk change can make an overlay obsolete without the branch changing at all. A trunk sync
-drops the affected branches' cached sync verdicts, so the next `components sync` on the branch really
-re-evaluates instead of answering *"No changes detected"*. After promoting anything, re-sync each live
-branch.
-
-**The admin UI has the same surface**, which is what to point a non-CLI user at: the *owner* account page's
-**Component branches** box (per-branch counts, drift, subscribers, and Preview / Sync / Retire), and the
-*subscriber* account page's **Branch variants** box plus **GitHub → Fetch `<branch>` variants**. Both open
-the same result panel — grouped plan, subscribers, a Monaco diff of trunk vs branch per changed field, and
-a confirm-gated override when the removal guard refuses. Preview there is the same `--dry-run`.
-
-### Diagnosing a variant
-
-- `remits-cli components branch <name> --json` — the stored overlay content and what it overrides.
-- The compile signature `variant:<id>:<hash>` in `Using Cached BCD` logs — proves a variant actually ran.
-- A test/tool response reports `testComponentSource` as `staged` | `variant` | `db`, so you can see which
-  layer the run resolved without reading logs.
-
-> **A populated staging cache makes a variant look broken.** Anything carrying a CLI `TestMode` — a
-> `remits-cli token` URL, `/s/<tokenKey>/...`, an `X-Auth-Token` request, a script-loader embed — resolves
-> the STAGED layer, which outranks the variant. So with components staged under the same branch/user, a
-> tokenized page reports `Component Branch: <branch>` but `Variant Applied: none` and renders trunk, while
-> an anonymous `?account_id=` request to the same page reports the variant. That is the documented
-> precedence (staged -> variant -> trunk) working correctly, and it reads exactly like "tokens break
-> variant resolution". **Run `remits-cli components clear --all` before verifying variant resolution
-> through any tokenized entry point**, or check `remits-cli components status` first.
-
-## Production Support Workflow
-
-Switch to prod mode for investigations:
-
-```bash
-remits-cli data-mode set prod
-```
-
-### Investigation Strategy
-
-Before starting an investigation outside the confirmed current repo:
-1. Read `~/.remits-cli/account-repos.json`
-2. Switch to the best local repo candidate
-3. Read that repo's `account-info.json`
-4. Confirm whether you are in `CLIENT`, `PLATFORM`, or `PRODUCT` context
-5. Then continue with the investigation flow below
-
-**Document-First** (most common — user reports a data issue):
-1. `mcp_account_view` — understand the account's schemas and components.
-2. `mcp_firestore_search` — find the document, capture its `object_id`.
-3. If the issue involves inbound or outbound HTTP behavior and the account has `enableHttpAudits`, query `http-audits/http-audits-YYYY-MM/entries` with `mcp_firestore_search`.
-4. `mcp_object_activity` — scan the timeline for warnings, errors, unexpected events.
-5. `mcp_record_listing` — search or filter alerts, events, object logs, or objects when you need to find the suspicious record first.
-6. `mcp_record_view` — drill into suspicious entries for full content.
-7. `mcp_ai_session_search` — if the workflow involves AI, inspect session groupings, prompts, tool definitions, and responses in human-readable form.
-8. `mcp_user_activity` — for "user X is slow right now" reports, list sessions by `userId`/`accountId`, open the session story, and use the returned beat pivots.
-9. `mcp_performance_trace` — for slow/sluggish reports, open the beat `traceId` with `action:"trace"`; use `action:"slowest"` when you only have a broad time window.
-10. `mcp_system_logs` — correlate via `threadGroupingId` for raw log context when the trace needs supporting log lines.
-11. `mcp_component_view`/`mcp_component_grep` — explain how the responsible component works.
-
-**Slow / sluggish user report:**
-
-1. Resolve the reporting user/account with `mcp_account_user_admin` if you only have an email/name.
-2. Call `mcp_user_activity` with `action:"sessions"` and `userId` or `accountId`.
-3. Open the likely row with `action:"story"` and inspect beat labels, status, `ms`, `node`, and `traceId`.
-4. Open slow or failed beat pivots with `mcp_performance_trace` before querying raw logs.
-5. Use the returned `mcp_system_logs` pivot only when the trace needs surrounding log lines.
-6. If there is no live session, call `mcp_user_activity` `action:"watch"` for the user/account, ask for reproduction, then read `sessions`/`story` again. Focused sessions retain sanitized request detail and emit archived `REMITS_ACTIVITY` log lines.
-
-**Error or Alert Investigation:**
-1. `mcp_record_listing` — search by alert type, content, error text, action, status, `threadGroupingId`, or other exact-match record properties when you do not yet know the record ID.
-2. `mcp_record_view` — inspect the chosen record/event/alert/object in full once you have its ID.
-3. Use `object_id` + `threadGroupingId` to pull full timeline and logs.
-4. Cross-check Firestore document state.
-5. Identify `source_bcd` and any `upstream_source_bcd`.
-6. Explain the record in terms of the workflow step that produced it, not as a generic JSON blob.
-7. If the context looks missing, redacted, or truncated, consider sanitization rules before concluding data was never present.
-8. If AI behavior is part of the symptom, use `mcp_ai_session_search` and compare the persisted session content against the Agent component implementation and `features/ai-support.md`.
-
-**Stuck / failed / recovered Event:**
-
-Do **not** open the Action source first. The platform records each attempt's delivery envelope — which
-queue delivered it, which delivery attempt this was, and how long it was ever allowed to run — and
-classifies the failure for you.
-
-```bash
-remits-cli tool --name mcp_event_diagnostics --input '{"accountId":49,"eventId":18838}' --data-mode prod
-```
-
-The same classifier is available from a Test or any component as `eventDiagnostics(18838)`.
-
-**Read `classification` before anything else** — only `APPLICATION_FAILURE` means the bug is in the
-component. The full classification table, what each `abandonmentCause` implies, and the returned `pivots`
-are under **`mcp_event_diagnostics`** in the Tool Reference. One thing to check every time:
-`delivery.deliveryAttempt` above `1` means Cloud Tasks had **already** retried this event, so any
-non-idempotent side effect may have run more than once — look for duplicate records before concluding the
-component "ran twice for no reason".
-
-Full detail: `features/observability.md` and `features/events-builder-guide.md` (`mcp_get_guide`).
-
-### Presenting Findings
-
-Users are not engineers. When reporting investigation results:
-- Lead with what happened in plain language.
-- Show the evidence (document values, timeline events, log excerpts).
-- Explain why it happened if you can determine the cause.
-- Recommend what to do next — in terms the user can act on.
-
-### Verifying a Production Issue Fix
-
-When a bug is reported from production, use this pattern:
-
-1. Investigate the live issue in **prod mode** and identify the exact affected document IDs, collection names, account IDs, and component path.
-2. Make the code change in the owning `PLATFORM` or `PRODUCT` repo when the defect is in shared implementation.
-3. Verify in **test mode**, not prod.
-4. Prefer a **Test component** when the behavior can be asserted programmatically, because that creates a durable regression suite and lets you explicitly construct the necessary data, operations, and assertions.
-5. Use `remits-cli token` plus `playwright-cli` when the proof is visual or interaction-driven.
-6. If useful, create or update a dedicated embeddable "playground" in test mode to reproduce the scenario in a controlled way.
-
-Do not move production customer data into another account's test collection as a routine verification strategy. If you cannot verify with a Test component, Playwright flow, or controlled test-mode embeddable, explain the gap clearly instead of improvising with live production validation.
-
-## Tool Reference
-
-### Execute a Tool
-
-```bash
-remits-cli tool --name "mcp_firestore_search" --input '{"accountId": 37, "collection": "invoices"}' --data-mode prod
-```
-
-Response saved to `./.remits-cli/tool-responses/<callId>.json`. Read the file to see results.
-
-**"Tool call succeeded" means DISPATCHED, not that the tool did what you asked.** A tool that runs
-and refuses — an unmet precondition, a rejected enum value, a failed validation — returns HTTP 200
-with its own `success: false` inside `result`. The CLI now prints `Tool call FAILED — the tool ran
-and returned an error.` plus a `Tool error:` line and exits non-zero, and the response envelope
-carries `toolSuccess` / `toolMessage`. **For any MUTATING call, confirm the tool's own verdict before
-reporting the work as done** — do not grep the terminal output for "succeeded":
-
-```bash
-F=$(remits-cli tool --name mcp_support_ticket --input "$(cat payload.json)" --data-mode prod 2>&1 \
-    | grep -o '[^ ]*tool-responses/[a-f0-9-]*\.json' | tail -1)
-python3 -c "import json;r=json.load(open('$F'))['result'];print(r.get('success'), r.get('message'))"
-```
-
-Build non-trivial JSON into a file (e.g. with `python3 -c 'json.dumps(...)'`) and pass it as
-`--input "$(cat payload.json)"`. Long inline single-quoted JSON intermittently produces no response
-file at all.
-
-For long-running Action/Agent runners, use the tool's own async mode (`executionMode:"async"`), which returns
-the `actionRunId`/`agentRunId` (and, for agents, `sessionId`) immediately:
-
-```bash
-remits-cli tool --name "mcp_run_action" --input '{"accountId":37,"actionName":"Rebuild Invoice","executionMode":"async","actionInput":{"invoiceId":"abc"}}' --data-mode prod
-# poll by run id:  {"controlAction":"status","accountId":37,"actionRunId":"<actionRunId>"}
-```
-
-For long tools that lack their own async mode, use the CLI transport async (`--async true`), optionally with
-`--wait true` to poll locally, and `remits-cli tool status --call-id <callId>`. Do not stack both mechanisms
-(see "Tool Execution Lifecycle"). Use `--timeout-ms <ms>` only to adjust the per-request client timeout; it is
-not a replacement for async mode on multi-minute workflows.
-
-**Account-id precedence for tool calls.** When the CLI and the tool input both carry an account id, the server resolves them in this order:
-
-1. Explicit `--account-id <ID>` flag — always wins. Use this when you want to be certain the tool runs against a specific account (and the user's session covers it).
-2. `input.accountId` (or `input.account_id`) — the tool's per-call execution target.
-3. The current repo's `account-info.json` / active session — the default fallback.
-
-So from inside a parent account's repo you can target a child account just by setting `input.accountId`, or force it with `--account-id` if you need it to override whatever the tool input says. Verify with the `accountId` field in the response envelope.
-
-### `mcp_account_view`
-Returns complete account structure — schemas, components, relationships.
-
-Also returns two blocks that explain how the account RESOLVES, which is what you need before comparing
-its behavior against component source:
-
-- `resolution` — `role` (`OWNER` = resolves its own component trunk, `SUBSCRIBER` = resolves another
-  account's components through a branch edge) and a one-sentence `summary`; `accountId` (the account
-  described — the top level of this shape is the hierarchy ROOT, so do not read identity from there);
-  `databaseName` (the account's own override, often null) vs `resolvedDatabaseName` (the storage namespace
-  actually in effect); `branchName` (the repo sync branch) and `lastRepoSync`; `domainName` vs
-  `resolvedDomainName` (the custom host in effect, which differs when reached through an edge host);
-  `authPath` / `targetPath` (login and post-login landing routes); `editMode`; and — when a component
-  branch is in effect — `componentBranch` plus `componentOwnerAccountId` / `componentOwnerAccountName`.
-- `resolution.relationships` — **every structural link upward**, primary first: `parentAccountId` /
-  `parentAccountName` / `parentAccountCode` / `parentAccountType`, `primary` (true for the one link that
-  mirrors the account's primary parent), `active`, and the three independent link-scoped properties
-  `branchName` (which component-variant code runs), `databaseName` (where data lives), `domainName` (which
-  host reaches the account through this link). The hierarchy tree flattens all links into one shape, so this
-  is the **only** place that answers "does this account have more than one parent, and which link carries the
-  branch/namespace/host?" More than one entry ⇒ this account can resolve differently depending on the path a
-  request travelled — establish which one a failing request used before comparing behavior.
-- `componentBranches` — the variant branches this account OWNS, with override/add/remove, subscriber, and
-  drift counts. Same summary the owner's `account-info.json` carries.
-
-Note: this tool does **not** return users, and it returns EVERYTHING about one account. For users, for the
-deep account tree, or for small account/user updates, use `mcp_account_user_admin`.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `accountId` | yes | Account ID |
-
-### `mcp_account_user_admin`
-The account-graph and user surface: the middle ground between `account-info.json` (which states structure
-compactly, because it is read into your context every session) and `mcp_account_view` (everything about one
-account).
-
-- `action: 'hierarchy'` (default) — the descendant tree trimmed to `depth` (1-10, default 2; nodes cut off
-  are marked `truncated` and still report their child count) and/or the anchored ancestor chain plus every
-  edge (`direction: 'down'|'up'|'both'`). Nodes include `testAccount`. **This is how you get the deep tree
-  account-info.json omits.**
-- `action: 'account'` — one account's `resolution` block, including `testAccount`, plus masked
-  configuration fields, without paying for the component inventory.
-- `action: 'users'` — an account's users at a hierarchy `scope` (`self`/`children`/`parents`/`hierarchy`),
-  optional `email` substring filter. Rows include `testUser`. Extension fields are omitted here on purpose:
-  they are stored **per account** and these users are bound to their own.
-- `action: 'user'` — one user (`userId` or `email`) with roles, account memberships, and extension fields
-  **correctly scoped to the requested account**, plus `testUser`. It never grants membership as a side
-  effect of a read, and tells you when the fields shown belong to a different account.
-- `action: 'account_update'` — write Account-schema configuration `fields`, and/or `name`/`status`
-  (`ACTIVE`/`ON_HOLD`/`PENDING`).
-- `action: 'user_update'` — write User-schema `fields` under the named account, plus `name`/`enabled` and
-  membership add/remove. Refused unless the user is a member or you pass `addAccount: true`, because the
-  write would otherwise land on another account. If an email does not exist globally, `addAccount: true`
-  intentionally creates that user first, then binds them to the named account before writing fields.
-
-**Building an account hierarchy** (the structural writes — this is how a coding agent provisions accounts
-without a browser):
-
-**Data-lane rule for provisioning:** `remits-cli tool` defaults to `--data-mode test`. That is correct for
-fixtures and rehearsals, but it means `mcp_account_user_admin` `action:'account_create'` creates test-lane
-accounts unless the command explicitly passes `--data-mode prod`. For real platform/product/customer
-provisioning, always dry-run in prod first, check the response's `dataMode`, then run the write in prod:
-
-```bash
-remits-cli tool --name mcp_account_user_admin --data-mode prod --input '{"action":"account_create","parentAccountId":4,"name":"Freto","type":"PRODUCT","dryRun":true}'
-```
-
-After the real write, verify the response (or re-read `action:'account'`) shows the command `dataMode` you
-intended and `testAccount:false` for real provisioning. `testAccount:true` means you created a test-data
-account, even if the name and structure look correct.
-
-For a test rehearsal, make the opposite assertion explicit: the response should show `dataMode:'test'` and
-`testAccount:true` for **newly created** accounts (or `testUser:true` for created users).
-
-Read `reusedExisting` before reading anything into the flag. `account_create` is find-or-create, and a
-**test**-lane create can legitimately match a **real** account: real accounts are visible in both lanes,
-so a rehearsal for a name that already exists in prod returns `reusedExisting:true` /
-`testAccount:false` and changes nothing. That is correct reuse, not a lane error. Only
-`reusedExisting:false` with `testAccount:false` in a test rehearsal means the lane was not the one you
-intended. (The prod direction is not symmetrical: a prod-lane create never resolves onto a test
-CLIENT/PROVIDER account, so the same name can exist once per lane.)
-
-**A test-lane account does not get the `code` the prod one will.** `code` is derived from `name` and is
-globally unique, so a test-lane create with no explicit `code` is assigned `test_<code>_<parentId>`.
-A namespace resolves as `databaseName ?: platform.code ?: code`, so a rehearsal **does not prove the
-storage namespace** the real create will land in unless you set `databaseName` explicitly. Conversely,
-passing an explicit `code` in a test rehearsal opts out of the prefix, and the later prod create then
-fails on `code unique:true` — as it also will against a test account created before this rule existed.
-Check the existing account's `code` before assuming a name is free.
-
-Account/User schema `fields` are Firestore-backed extension fields. Their physical storage follows the
-same data lane as the tool call: `--data-mode test` writes under `testing/<resolvedDatabaseName>/...`, while
-`--data-mode prod` writes under `accounts/<resolvedDatabaseName>/...` (for modern segmented accounts). If a
-test-lane rehearsal should become real provisioning, rerun the create/update in prod mode; do not assume the
-test-lane Firestore fields moved.
-
-- `action: 'account_create'` — create a child under `parentAccountId`, with its **primary relationship edge**,
-  applying `type` / `databaseName` / `domainName` / `authPath` / `targetPath` / `code` /
-  `repositoryNameOverride` / `branchName` / `editMode` / … **at birth**. That ordering matters: the storage
-  namespace is resolved from those properties, and the parent's cascaded schema fields are written into it
-  during creation. Idempotent — an existing same-name account under that parent comes back with
-  `reusedExisting: true`, unchanged. The response includes `testAccount`.
-- `action: 'account_structure'` — change those properties on an existing account, including account-level
-  custom host, login path, and landing path.
-- `action: 'edge_add'` / `'edge_update'` / `'edge_remove'` — manage a membership `AccountRelationship` edge to
-  `parentAccountId`, including the three independent edge properties `branchName` (which component code runs),
-  `databaseName` (a path-scoped storage-namespace override — **live**, and inherited by everything below
-  that edge) and `domainName` (which host reaches the account through that edge). Cycles, self-edges, and
-  removing the primary edge are all refused.
-- `action: 'reparent'` — move the account's **primary** edge (and `Account.parentId`) to `parentAccountId`.
-
-> **The namespace guard.** An account's storage namespace resolves as
-> `databaseName ?: platform.code ?: code`, and `Account.setName` **regenerates `code`** — so renaming an
-> account whose namespace falls through to its own code silently repoints its storage. Any write that would
-> move the resolved namespace is **refused** unless you pass `confirmSegmentChange: true`, and the refusal
-> names both namespaces. To rename without moving storage, pin `code` to the old value in the same call.
->
-> Because the namespace follows the **path** (see *Account Structure* in `platform-overview.md`), an
-> `edge_update` that sets `databaseName` repoints storage for **everything below that edge**, and the
-> answer is path-specific — the same account reached through a different parent can resolve a different
-> namespace. Dry-run these.
-
-Every write supports `dryRun: true`, which reports each `from -> to` without writing. Not here by design:
-component-branch subscription reporting and drift (use `remits-cli components branches` /
-`remits-cli components branch <name>`), and account/user **deletion** (admin only, so the
-destructive-teardown contract applies).
-
-**Provisioning recipe** — a new product account under a platform, running its own component branch, with
-client accounts beneath it:
-
-```
-1. mcp_account_user_admin  action:'account_create'   parentAccountId:<platform>  name:'Adyen'
-                           type:'PLATFORM'|'PRODUCT'  [databaseName:'...']
-2. git branch + push in the OWNER's repo, then `remits-cli components sync` from that checkout
-   (non-trunk => writes ComponentVariant overlays only)
-3. mcp_account_user_admin  action:'edge_update'  targetAccountId:<new>  parentAccountId:<platform>
-                           branchName:'<branch>'
-4. mcp_account_user_admin  action:'account_create'  parentAccountId:<new>  name:'<business unit>'
-                           type:'CLIENT'                  # inherits the branch automatically
-```
-
-> **Put the branch on the edge that is UNAMBIGUOUSLY on the account's path up — primary or membership.**
-> Inheritance walks `parentId` and, at an account that has no `parentId`, continues through its *single*
-> active membership edge. So a subscriber shell with **no `parentId` and one membership edge** to its owner
-> is a fully supported shape: it resolves the branch, **and so do all of its descendants**. You do not need
-> to make the subscriber a structural child of its owner.
->
-> What is NOT resolved by default is genuine **ambiguity** — an account with *several* upward links, where
-> the platform refuses to guess which product it was reached through. That account (and its descendants)
-> resolve trunk until a request names the path: `--as-account`, `--variant-branch`, or the edge's own host.
-> An account that has a `parentId` **and** a separate membership edge carrying the branch is this case: the
-> `parentId` wins, so put the branch on the link the account actually inherits through.
->
-> Either way, descendants inherit the branch down the chain automatically, which is what makes step 4 free.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `action` | no | `hierarchy` (default), `account`, `users`, `user`, `account_update`, `user_update` |
-| `accountId` / `targetAccountId` | no | Account to act on; `targetAccountId` targets another account without moving tool resolution |
-| `depth` / `direction` | no | `hierarchy` only |
-| `scope` | no | `users` only |
-| `userId` / `email` | no | Identify the user (`user`, `user_update`); `email` is a filter for `users` |
-| `fields` / `name` / `status` / `enabled` | no | The update payload |
-| `addAccount` / `removeAccount` | no | Membership changes for `user_update` |
-| `dryRun` | no | Report the change without writing |
-
-### `mcp_firestore_search`
-Query Firestore documents.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `accountId` | yes | Account ID |
-| `collection` | yes | Collection name (snake_case plural, e.g., `invoices`) |
-| `documentId` | no | Fetch single document by ID |
-| `filters` | no | `[{field, operation, value}]`. Operations: `EQUALS` (or `==`), `NOT_EQUALS` (or `!=`), `GREATER_THAN` (or `>`), `GREATER_THAN_EQUALS` (or `>=`), `LESS_THAN` (or `<`), `LESS_THAN_EQUALS` (or `<=`), `IN`, `NOT_IN`, `ARRAY_CONTAINS`, `ARRAY_CONTAINS_ANY`, `IS_NULL`, `IS_NOT_NULL`. `op` is accepted as alias for `operation`. |
-| `sort` | no | `[{field, direction}]` — `ASC`/`DESC`. Also accepts top-level `orderBy` + `orderDirection`. |
-| `pagination` | no | `{limit, offset}`. Default limit=25, max=200. Also accepts top-level `limit`/`offset`. |
-| `fields` | no | Field names to return. If omitted, auto-selects up to 20 fields. |
-| `aggregation` | no | `{sum: [...], avg: [...], min: [...], max: [...], count: true}` |
-| `dateRanges` | no | `[{field, startDate, endDate}]` (yyyy-MM-dd) |
-| `textSearch` | no | `[{field, prefix}]` for prefix matching |
-| `fallbackOnMissingIndex` | no | When `true`, a sorted read that fails on a missing composite index retries without sort and returns `warning`, `missingIndexUrl`, and `sortApplied:false`. Use when an unsorted first page is still useful. |
-
-**HTTP audits use this same tool** — they are Firestore documents in monthly collections
-(`http-audits/http-audits-YYYY-MM/entries`). Which filters to reach for, and when audits are the right
-evidence at all, is in *The Investigation Model → HTTP audits*.
-
-```bash
-remits-cli tool --name "mcp_firestore_search" --input '{"accountId": 37, "collection": "http-audits/http-audits-2026-05/entries", "filters": [{"field": "direction", "operation": "EQUALS", "value": "OUTBOUND"}, {"field": "request.path", "operation": "EQUALS", "value": "/api/orders"}, {"field": "success", "operation": "EQUALS", "value": false}], "sort": [{"field": "timestamp", "direction": "DESC"}], "pagination": {"limit": 10}}' --data-mode prod
-```
-
-### `mcp_firestore_patch`
-Guarded exact-document Firestore patch tool for bounded repairs. It defaults to `dryRun:true` and refuses broad
-updates, wildcard collections, delete/remove operations, protected identity fields, and `_lastModified*` audit
-fields.
-
-Use it when the desired repair is mechanical and smaller than rerunning an expensive Action, for example copying
-canonical fields into stale UI mirror fields. Always dry-run first and include preconditions:
-
-```bash
-remits-cli tool --name mcp_firestore_patch --data-mode prod --input '{
-  "accountId":743,
-  "collection":"statements",
-  "documentId":"20958",
-  "dryRun":true,
-  "preconditions":[
-    {"field":"interchangeOptimization.status","equals":"Calculated"},
-    {"field":"interchangeOptimizationChecked","equals":false}
-  ],
-  "patch":{
-    "interchangeOptimizationChecked":true,
-    "feeBreakdown.interchangeOptimization":{"$copyFrom":"interchangeOptimization"},
-    "feeBreakdown.interchange.optimization":{"$copyFrom":"interchangeOptimization"}
-  }
-}'
-```
-
-Response fields include `dataMode`, `accountId`, `collection`, `documentId`, `dryRun`, `patchedFields`, and
-`diff`. Switch to `"dryRun":false` only after the diff and preconditions are exactly what you intended.
-
-### `mcp_object_activity`
-Object lifecycle timeline — metadata + recent activity.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `accountId` | yes | Account ID |
-| `objectId` | yes | Object ID (from `object_id` in documents) |
-| `dataMode` | no | Explicit lane: `prod` or `test`. Response echoes `dataMode`. |
-| `activityOptions` | no | `{limit, offset, types, start, end, order}`. Default: limit=5, order=desc. Types: `OBJECT_LOG`, `EVENT`, `ALERT`. |
-
-Response fields include `dataMode`, `object.testMode`, and `testMode` on Event/Alert timeline entries.
-
-### `mcp_record_listing`
-List and search lifecycle records when you do not already know the record ID.
-
-Typical use:
-- find active error alerts by `type` or `status`
-- search alert/event/object_log content for an error phrase from an inbound support email
-- narrow candidate records before switching to `mcp_record_view`
-
-Tool ID: `88`
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `accountId` | yes | Account ID used for tenant scoping |
-| `recordType` | yes | `object`, `object_log`, `event`, or `alert` |
-| `filters` | no | Exact-match domain-property filters following the admin `listData` model, for example `status`, `type`, `active`, `threadGroupingId`, `action`, or enum fields using `_enum` |
-| `ids` | no | Exact ID filter. Accepts a comma-separated string or array of numeric IDs |
-| `query` | no | Lightweight text query over key searchable fields such as alert type/content/error text or object_log description/content |
-| `page` | no | 1-based page number. Default: `1` |
-| `pageSize` | no | Records per page. Default: `10`, max: `100` |
-| `sort` | no | Domain property to sort by. Default: `id` |
-| `order` | no | Sort direction: `asc` or `desc`. Default: `desc` |
-| `includeChildren` | no | When `true`, include the specified account and child accounts |
-| `scanLimit` | no | When using `query`, number of filtered candidate records to scan before text matching. Default: `200`, max: `500` |
-| `maxPreviewChars` | no | Override preview length for returned content/body snippets. Max: `2048` |
-
-### `mcp_record_view`
-Inspect individual lifecycle records with line-range or grep.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `accountId` | yes | Account ID |
-| `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) |
-| `lineRange` | no | `{start, end}` (1-based inclusive) |
-| `grep` | no | `{pattern, caseSensitive, contextBefore, contextAfter}` |
-
-### `mcp_ai_session_search`
-Search AI session groupings and export grouping detail in human-readable form.
-
-Typical use:
-- find AI sessions by agent, user, account, session ID, or grouping ID
-- inspect the exact prompts, system messages, tools, and responses used in a prior run
-- identify tuning opportunities in Agent behavior by comparing session output with the front-stage guides and component source
-
-Front-stage references:
-- `components/agent-components.md`
-- `features/ai-support.md`
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `action` | no | `search` (default), `detail`, or session control `pause`/`unpause`/`interrupt` |
-| `dataMode` | no | Explicit execution lane: `prod` or `test`. Response echoes `dataMode`, but persisted groupings do not have durable per-row lane flags. |
-| `search` | no | Broad text match against session IDs and grouping IDs |
-| `sessionId` | no | Session ID filter in search mode, or grouping/session key in detail mode |
-| `groupingId` | no | Grouping ID filter in search mode, or grouping key in detail mode |
-| `groupingKey` | no | Preferred explicit grouping key for detail mode |
-| `user` | no | User filter |
-| `account` | no | Account filter |
-| `agent` | no | Agent filter |
-| `scope` | no | `all`, `agents`, or `internal` |
-| `status` | no | Search mode: filter by live runtime status, comma-separated (e.g. `paused,interrupted`) |
-| `scanLimit` | no | Search mode: window scanned when `status` is set. Default `100`, max `500` |
-| `page` | no | 1-based page number. Default: `1` |
-| `pageSize` | no | Results per page. Default: `25`, max: `100` |
-| `summaryOnly` | no | Detail mode: return the MAP (record index + stats + timeline) with no payloads. Same as `parts:["index"]` |
-| `parts` | no | Detail parts: `index`, `stats`, `transcript`, `tool_calls`, and record sections `full`, `conversation_messages`, `system`, `response`, `tools` |
-| `sections` | no | Alias for `parts` |
-| `recordIds` | no | Detail mode: open only these request/response record IDs |
-| `toolCallIds` | no | Detail mode: return the FULL exact input/result from `ai_tool_call` for these tool-call ids (what the tool PRODUCED — see the lens caveat) |
-| `consolidateContext` | no | When `true`, collapses repeated XML-like prompt context into a consolidated section |
-
-Audit flow: `action:"search"` to find the grouping → `action:"detail"` + `summaryOnly:true` for the MAP → re-call detail with `recordIds`/`toolCallIds` + `parts` to open exactly what you need. Prefer the map → open flow over a full-detail dump. Remember the two-lens rule: `tool_calls`/`toolCallIds` is what the tool PRODUCED; `conversation_messages`/`transcript` is what the AI CONSUMED (after any `_offload`/`_hideResult`/`_message`/supersede/evict transform).
-
-### `mcp_run_action`
-Run an Action on a target account, with explicit prod/test data mode, optional staged branch resolution, and
-staged-vs-DB provenance in the result.
-
-Describe the Action first when the input shape is not obvious. This does not execute the Action:
-
-```bash
-remits-cli tool --name mcp_run_action --input '{"controlAction":"describe","accountId":743,"actionId":25,"includeInputSchema":true}' --data-mode prod
-```
-
-The describe response reports `hasInputSchema`, optional `inputSchema`, `inferredInputKeys`, and component
-provenance. If `hasInputSchema:false`, treat `inferredInputKeys` as a best-effort static scan, not a contract.
-
-Use direct mode only for quick Actions:
-
-```bash
-remits-cli tool --name mcp_run_action --input '{"accountId":49,"actionId":200,"executionMode":"direct","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
-```
-
-Use the tool's own async mode for long-running Action execution — it returns immediately with an
-`actionRunId`. Pass your **own** `actionRunId` so you can poll deterministically without first parsing it out
-of the start response. Do **not** also pass the CLI `--async` flag; that only buries these ids behind the
-transport layer:
-
-```bash
-remits-cli tool --name mcp_run_action --input '{"accountId":49,"actionId":200,"executionMode":"async","actionRunId":"my-stable-run-id","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
-```
-
-Then poll that run with another **regular tool call** carrying `controlAction:"status"` and the same
-`accountId` + `actionRunId`:
-
-```bash
-remits-cli tool --name mcp_run_action --input '{"controlAction":"status","accountId":49,"actionRunId":"my-stable-run-id"}' --data-mode prod
-```
-
-> This poll is a normal `remits-cli tool --name mcp_run_action` call — **not** `remits-cli tool status`,
-> which polls the CLI-transport `--async` `callId` (a different mechanism). Use `controlAction:"status"`
-> (rather than `command:"status"`) inside the input so it is never conflated with the transport-level status.
-> If you started the run with a different `userId`, include that same `userId` in the poll (the run's status
-> is keyed by account + user + `actionRunId`; it otherwise defaults to the current user).
-
-For job-style Actions only (`Action.job == true`), prefer `executionMode:"event"` when you want the durable
-Event lifecycle, Event status, and platform recovery behavior. Event mode is inherently async; poll it the
-same way (`controlAction:"status"` + `actionRunId`) — the status resolves the backing Event's terminal state:
-
-```bash
-remits-cli tool --name mcp_run_action --input '{"accountId":49,"actionId":200,"executionMode":"event","actionRunId":"my-stable-run-id","actionInput":{}}' --data-mode prod
-```
-
-Returned fields on the async/event start: `actionRunId`, `status:"running"`, `executionMode`,
-`threadGroupingId`, `componentSource`, `componentSignature`, and (event mode) `eventId`/`eventStatus`. The
-`status` poll adds `result` on completion, or `message`/`error` on failure.
-
-> **In event mode the EVENT is the source of truth, not the promise.** `status` is driven by the Event's
-> own state; the value the dispatch call returned is reported separately as `dispatchResult` and is **not**
-> the Action's result. Read `eventStatus` for the outcome.
-
-#### Stopping a run — `controlAction:'interrupt'`
-
-The tool counterpart of the **Interrupt** button on the admin Events page. Use it when an investigation
-turns up a run that is consuming resources and should not finish — the case this exists for is finding a
-`PROCESSING` event that has been running far too long.
-
-```bash
-# the usual path: you found the event in mcp_record_listing / mcp_object_activity
-remits-cli tool --name mcp_run_action --data-mode prod --input '{"controlAction":"interrupt","accountId":49,"eventId":19102,"reason":"runaway extraction, 45min"}'
-
-# or stop a run you started yourself (executionMode:'event' only)
-remits-cli tool --name mcp_run_action --data-mode prod --input '{"controlAction":"interrupt","accountId":4,"actionRunId":"my-run-id"}'
-```
-
-Aliases `cancel` / `stop` / `kill` all work. What you need to know before using it:
-
-- **It is COOPERATIVE cancellation, not a thread kill.** It sets a flag the running work observes at its
-  next checkpoint, then throws. Checkpoints are dense across everything that matters — every Firestore
-  read/write, outbound HTTP call, AI turn, and front-stage DSL call — so a normal run stops promptly. A
-  run blocked inside a *single* long call (one slow AI turn) stops when that call returns, not instantly.
-- **Work already committed is NOT rolled back.** This stops further work; it does not undo what has run.
-- **Only `PENDING`/`QUEUED`/`PROCESSING` can be interrupted.** A terminal event is reported back with its
-  status rather than being silently reported as "interrupted".
-- **Event-scoped.** A `direct` or `async` run has no Event and cannot be stopped this way.
-- Tenant-scoped: you cannot interrupt another account's event.
-- The response returns `previousStatus`, `eventStatus`, and `threadGroupingId`, so you can pivot straight
-  into `mcp_performance_trace` / `mcp_system_logs` to see what it was doing when you stopped it.
-
-**AI sessions are stopped separately** with `mcp_ai_session_search` (`action:'interrupt'`, plus
-`pause`/`unpause`) — that controls an agent's conversation loop, whereas this controls an Action's Event.
-
-### `mcp_run_agent`
-Run one real Agent turn on a target account. The Agent hooks and tools execute for real against the requested
-`dataMode`; pass `dataMode:"test"` for safer tuning.
-
-Use direct mode only for short turns:
-
-```bash
-remits-cli tool --name mcp_run_agent --input '{"accountId":49,"agentName":"InvoiceAuditor","message":"Summarize this invoice context","executionMode":"direct"}' --data-mode prod
-```
-
-Use the tool's own async mode for autonomous or long Agent turns. It returns immediately with both an
-`agentRunId` and a single, stable `sessionId` — the **same** id the running session uses, so you can inspect
-it right away. Pass your own `agentRunId` for deterministic polling. Do **not** also pass the CLI `--async`
-flag (that only delays these ids into a polled result):
-
-```bash
-remits-cli tool --name mcp_run_agent --input '{"accountId":49,"agentName":"InvoiceAuditor","message":"Audit this invoice","executionMode":"async","agentRunId":"my-stable-run-id","context":{"invoiceId":"..."}}' --data-mode prod
-```
-
-Then poll that run with another **regular tool call** carrying `controlAction:"status"` and the same
-`accountId` + `agentRunId` (this is a normal `mcp_run_agent` call, **not** `remits-cli tool status`):
-
-```bash
-remits-cli tool --name mcp_run_agent --input '{"controlAction":"status","accountId":49,"agentRunId":"my-stable-run-id"}' --data-mode prod
-```
-
-Inspect the live/persisted AI session at any time using the `sessionId` returned by the start call (it is the
-run's real, canonical session id):
-
-```bash
-remits-cli tool --name mcp_ai_session_search --input '{"action":"detail","sessionId":"<sessionId>","summaryOnly":true}' --data-mode prod
-```
-
-Key returned fields: `agentRunId`, `sessionId`, `status`, `threadGroupingId`, runtime pause/interruption
-hints, `lastAssistantMessage`, `toolCallCount`, `result`, `message`, and `error`.
-
-#### Controlling a live agent — `pause` / `unpause` / `interrupt`
-
-```bash
-remits-cli tool --name mcp_run_agent --data-mode prod --input '{"controlAction":"pause","accountId":49,"agentRunId":"my-run-id"}'
-remits-cli tool --name mcp_run_agent --data-mode prod --input '{"controlAction":"interrupt","accountId":49,"sessionId":"<sessionId>"}'
-```
-
-Target the session with the `agentRunId` an async start returned, or the `sessionId` directly.
-
-- **`interrupt` is TERMINAL** (aliases `stop`/`cancel`/`kill`). It clears any pending resume and pending
-  guardrails and persists a terminal lifecycle status. An interrupted session **cannot be unpaused** —
-  attempting it is refused with that reason rather than silently doing nothing. Use `pause` if you intend
-  to resume.
-- If the session is not resident on the serving node, it is rehydrated by agent name — so pass `agentName`
-  (or an `agentRunId`, which carries it) when controlling a session you did not just start.
-- The same controls remain available on `mcp_ai_session_search`, which is the right tool when you are
-  *searching* for the session; this is the right one when you *started* the run.
-
-### `mcp_system_logs`
-Query Cloud Run service logs.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `node` | * | Node name (e.g., `remitsAdmin-east5`). Auto-resolves to serviceName+region. |
-| `serviceName` | * | Cloud Run service. Not needed if `node` provided. |
-| `region` | * | Cloud Run region. Not needed if `node` provided. |
-| `timeRange` | * | Relative time: `1h`, `4h`, `30m`, `7d`. Auto-calculates startTime. |
-| `startTime` | * | ISO 8601 timestamp. Not needed if `timeRange` provided. |
-| `endTime` | no | ISO 8601 upper bound (defaults to now) |
-| `severity` | no | Minimum: `INFO`, `WARNING`, `ERROR`, etc. |
-| `threadGroupingId` | no | Filter by processing chain ID |
-| `filter` | no | Additional Cloud Logging filter (LQL). **To search message text, pass the bare phrase** — it is widened automatically to match both `jsonPayload.message` (all `log.*` output) and `textPayload` (`println`/stdout). See the warning under "Diagnosing which version is in play". |
-| `maxPreviewChars` | no | Per-entry truncation width. Default 512, max 8000. Raise it when an entry carries a structured payload (a serialized `RemitsTrace`, a long stack frame) that the default cuts mid-JSON. |
-| `pageSize` | no | Default 25, max 100. Also accepts `limit`. |
-
-*Provide either `node` or `serviceName`+`region`. Provide either `timeRange` or `startTime`.
-
-**Example:**
-```json
-{"node": "remitsAdmin-east5", "timeRange": "4h", "severity": "ERROR"}
-```
-
-### `mcp_user_activity`
-Read live user activity sessions and control focused capture. Use this before trace/log spelunking when
-the report is user-centric, for example "User abc is reporting slow responses." It wraps the same
-Redis-backed store as System → Activity and returns ready pivots to traces, logs, and component source.
-
-Common flows:
-
-```bash
-# Find what one user is doing right now
-remits-cli tool --name mcp_user_activity --input '{"action":"sessions","userId":3,"limit":10}' --data-mode prod
-
-# Open a returned sessionKey and inspect its beats
-remits-cli tool --name mcp_user_activity --input '{"action":"story","sessionKey":"c_46ee68bba67003a6","limit":50}' --data-mode prod
-
-# Arm focused capture, ask the user to reproduce, then read the story again
-remits-cli tool --name mcp_user_activity --input '{"action":"watch","userId":3,"minutes":30}' --data-mode prod
-```
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `action` | no | `sessions`, `story`, `watch`, `unwatch`, `forget`, `status`, or `archive`. Default: `sessions`. |
-| `userId` / `accountId` | no | Filter sessions/archive or choose the focus subject for `watch`/`unwatch`. One is required for `watch`/`unwatch`. |
-| `sessionKey` | for `story`/`forget` | Salted activity session key returned by `sessions`; not a raw browser/session credential. |
-| `focusedOnly` | no | For `sessions`, return only focused/watched sessions. |
-| `sinceMs` | no | For `sessions`, lower bound on last-seen epoch milliseconds. Defaults to the activity TTL window. |
-| `limit` | no | Session/story/archive row cap. Defaults: sessions=100, story=200, archive=50. |
-| `minutes` | no | Watch TTL for `watch`; defaults to `activity.focus.ttl.minutes`. |
-| `traceId` / `threadGroupingId` | no | For `archive`, narrow focused activity log pivot to one trace. |
-| `lookbackHours` | no | For `archive`, Cloud Logging window in the returned `mcp_system_logs` pivot. Default 24, max 168. |
-| `node` / `serviceName` / `region` | no | For `archive`, target for the returned `mcp_system_logs` pivot. `node` defaults to `remitsAdmin-east5`. |
-
-Reading rule: use `sessions` → `story` to build the behavioral timeline, then open a slow or failed beat's
-`mcp_performance_trace` pivot. Use `watch` when the user can reproduce and no live story exists. Use
-`archive` only for watched/focused sessions; ordinary activity lives in Redis and expires with the activity
-TTL.
-
-### `mcp_performance_trace`
-Read Remits request traces through the same `traces(...)` DSL that powers the admin Diagnostics "Request
-traces" panel. Use this before raw log spelunking for slow or sluggish requests because it returns profiled
-span rollups, component annotations, and retained slow-request summaries directly.
-
-Common flows:
-
-```bash
-# User only knows it was slow this afternoon
-remits-cli tool --name mcp_performance_trace --input '{"action":"slowest","lookbackHours":4,"accountId":52,"minMs":2000,"limit":10}' --data-mode prod
-
-# You have the Diagnostics/request/Object/Event/Alert threadGroupingId
-remits-cli tool --name mcp_performance_trace --input '{"action":"trace","traceId":"msf1y65n-001","lookbackHours":6,"format":"markdown"}' --data-mode prod
-
-# Same local-node data as the Diagnostics table
-remits-cli tool --name mcp_performance_trace --input '{"action":"snapshot","limit":100}' --data-mode prod
-```
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `action` | no | `snapshot`, `slowest`, or `trace`. Default: `snapshot`. |
-| `traceId` / `threadGroupingId` | for `trace` | Request/grouping id to open across local ring and Cloud Logging. |
-| `lookbackHours` | no | Cloud Logging window for `trace`/`slowest`. Defaults are 6 and 4 hours. |
-| `accountId` | no | Account filter for `slowest`. |
-| `kind` | no | Operation kind filter for `slowest`. **Rarely what you want** — see the note below. |
-| `componentType` | no | Filter `slowest` by the component that did the work: `Action`, `Reader`, `Rule`, `Embeddable`, `Tool`, `Test`. **This is the right axis for "which Actions/Rules are slow".** |
-| `componentId` / `componentName` | no | Narrow `slowest` to one component. |
-
-> **Filter by `componentType`, not `kind`.** `kind` is set by whoever OPENS the trace. An Action delivered
-> by Cloud Tasks arrives over HTTP, so the trace is `kind:'web'` and the Action is a `component.Action`
-> *span inside it*; a Rule fired during a request and a Tool invoked by an agent are the same. So
-> `kind:'action'` matches almost nothing in production. Every component execution annotates
-> `componentType`/`componentId`/`componentName` — filter on those.
-| `minMs` | no | Minimum duration for `slowest`. Default: 1500. |
-| `limit` | no | Result limit. |
-| `format` / `markdown` | no | Set `format:"markdown"` or `markdown:true` for a rendered trace report. |
-
-> **Tools are components, so availability is per ACCOUNT.** `Tool not found: mcp_performance_trace` does
-> not mean the tool is broken or that tracing is off — it means that tool has not been synced to the
-> account you are resolving against. This bites most often on **localhost** (a Test Account that has not
-> pulled the System Account's tool set) and on **client accounts**. Run `remits-cli tools` for the account
-> in question, or re-run against an account that owns the tool (`--account-id 4` for the System Account).
-> The same is true of every `mcp_*` tool, including the component tools noted below.
-
-Reading rule: first use `slowest` to get candidate trace ids, then call `trace` on the suspicious id, then use
-`mcp_system_logs` only if you need surrounding log lines. A trace dominated by `firestore.*`, `http.*`,
-`gorm.save.*`, or component spans points you at the relevant platform seam or front-stage component. Large
-unaccounted wall time is itself a finding: check cold compile, queueing, blocking I/O, or missing
-`measure(...)` instrumentation.
-
-### `mcp_event_diagnostics`
-Diagnose one Event's infrastructure outcome through the same `eventDiagnostics(eventId)` DSL described in
-`features/observability.md`. Use this before opening Action source when an Event is stuck,
-recovered, timed out, retried, or appears to have been killed.
-
-```bash
-remits-cli tool --name mcp_event_diagnostics --input '{"accountId":49,"eventId":18838}' --data-mode prod
-```
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `accountId` | yes | Tenant scope. The Event must belong to this account unless `includeChildren:true`. |
-| `eventId` / `id` | yes | Event primary key to diagnose. |
-| `includeChildren` | no | Allow the Event to belong to the requested account or one of its child accounts. Default: `false`. |
-
-Read `classification` first:
-
-- `APPLICATION_FAILURE` — the Action failed in application code; read `event.errorMessage`, correlated
-  alerts, and the producing component.
-- `ORPHANED_*` / `RECOVERED_*` — the attempt was abandoned; read `abandonmentCause`.
-- `REQUEST_TIMEOUT_LIKELY` — it used its whole deadline (`timing.deadlineUsed` near `1.0`). The unit of
-  work is too big for one event; the fix is resumable batches, not component logic.
-- `PROCESS_TERMINATED_LIKELY` — it stopped well inside its deadline (`timing.deadlineUsed` near `0`), so
-  the worker was killed (memory pressure, restart). Not a logic bug; inspect JVM/node health and
-  container lifecycle logs.
-- `UNKNOWN_NO_DEADLINE_EVIDENCE` — no deadline was recorded, so the cause is genuinely unknown. Use the
-  returned `logQuery` filters; do not assume. Events predating delivery-envelope capture always look
-  like this.
-- `AWAITING_DELIVERY` — the Event was never claimed; check queue delivery and action-node health.
-- `IN_FLIGHT_HEALTHY` — the Event is still heartbeating. A long Action is not a stuck one; wait, and
-  inspect trace/logs before interrupting.
-
-`delivery.deliveryAttempt` above `1` means Cloud Tasks had **already** retried this event, so any
-non-idempotent side effect may have run more than once.
-
-The response returns `delivery.threadGroupingId` — the same id everything else uses — plus the full
-`result` map, `diagnosisHints`, and `pivots` carrying ready-to-run inputs for `mcp_performance_trace`,
-`mcp_system_logs`, `mcp_record_listing`, and `mcp_object_activity` when those handles are present.
-`logQuery` carries ready-made Cloud Logging filters, including the container-lifecycle and 504 queries.
-For a performance question, open the `mcp_performance_trace` pivot next; for raw failure context, open
-logs and records by `threadGroupingId`.
-
-### `mcp_component_view`
-Read component field content with line numbers.
-
-In a normal `remits-cli` coding workflow, prefer local repo files for source reads. Use this tool when the
-local repo is unavailable, when confirming live DB source, or when you need staging / variant metadata that
-is not present in the working tree.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `accountId` | yes | Account ID |
-| `componentType` | yes | `Schema`, `Reader`, `Action`, `Embeddable`, `HtmlTemplate`, `Rule`, `Agent`, `Test`, `Tool`, `Prompt` |
-| `componentId` | yes | Component ID |
-| `fieldName` | no | `source`, `html`, `javascript`, `css`, `schema`, `description`, `mermaid`. Also accepts `field`. Omit for metadata. |
-| `offset` | no | Start line (1-indexed). Also accepts `startLine`. |
-| `limit` | no | Number of lines to return |
-
-Returns `componentVariants` when the component has committed branch variants — the branches, their state
-(`current` / `drifted` / `removed`), and a warning. Non-null means some accounts run a different version
-than the source you are reading, and trunk promotions can drift those variants.
-`mcp_component_grep` searches trunk, so it will not match text that exists only in a variant.
-
-### `mcp_component_grep`
-Search component source code with regex.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `accountId` | yes | Account ID |
-| `componentType` | yes | Component type |
-| `pattern` | yes | Regex to search. Also accepts `searchTerm`, `query`, `search`. |
-| `fieldName` | no | Field to search (default: `source`). Also accepts `field`. |
-| `componentId` | no | Specific component. If omitted, searches ALL of the type. |
-| `context` | no | Lines before AND after each match. Also accepts `contextLines`. |
-| `caseSensitive` | no | Default: true |
-
-### `mcp_support_ticket`
-Create and manage the full lifecycle of account-relative `support_tickets`.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `accountId` | conditional | The account that owns the support ticket. **Required only for `create`.** For every other action it is optional — the tool resolves the owning account from `ticketId` (the ticket's anchor id) and returns it. Pass it only to override/disambiguate. |
-| `action` | yes | `create`, `read`, `accept`, `update_status`, `complete`, `release`, `record_progress`, `add_artifact`, or `get_attachment` |
-| `ticketId` | conditional | Required for every action **except** `create` (which returns the new ticket ID). Alone it is sufficient to resolve the ticket and its owning account. |
-| `subject` | conditional | Short title. Required for `create`. |
-| `type` | conditional | Required for `create`: `enhancement`, `defect`, `question`, `task`, or `incident` |
-| `priority` | no | `low`/`medium`/`high`/`critical` for `create` (default `medium`) |
-| `description` | no | Longer description of the request/issue for `create` |
-| `affectedComponent` | no | Component or platform area affected (`create`) |
-| `implementationAccountId` / `implementationAccountName` | no | Owning `PLATFORM`/`PRODUCT` account when the ticket concerns shared implementation (e.g. a back-stage platform fix) |
-| `stepsToReproduce` / `acceptanceCriteria` / `tags` | no | Extra `create` fields for defect/enhancement tickets |
-| `assignee` | no | Required for `accept`. The agent's own name by convention — `claude`, `codex`, `gemini` |
-| `status` | no | Required for `update_status`. Valid values: `in_progress`, `pending_review`. **The ticket must be `accept`ed first** — otherwise the call is rejected with *"Ticket must be accepted before updating status"* |
-| `resolution` | no | Required for `complete` |
-| `category` / `summary` / `details` / `findings` / `nextStep` | no | Worklog fields for `record_progress` (`category` + `summary` required). `category` is a **fixed enum** — `triage`, `investigation`, `reproduction`, `fix`, `verification`, `handoff`, `other` — and any other value fails the whole call. `findings` is a **list of strings**, not a paragraph |
-| `artifactType` / `artifactLabel` / `contentBase64` / `gcsPath` / `url` | no | Evidence fields for `add_artifact` (screenshot/trace/log/test_result/link) |
-| `notes` | no | Optional lifecycle note stored with the ticket activity |
-| `attachmentIndex` | no | Zero-based index of the attachment to download. Used with `get_attachment`. |
-
-**Opening a ticket for your own work (`create`).** When you are asked to do work — or you discover a Remits **back-stage** defect while building front stage — and you were **not** handed an existing ticket, open one with `action:'create'` so the work is tracked end-to-end. For a platform fix, use `type:'defect'` (or `'enhancement'` for a gap), describe the seam and evidence, reference the fix PR, and set `implementationAccountId`/`implementationAccountName` to the owning `PLATFORM`/`PRODUCT` account.
-
-**Attachments:** Support emails may include file attachments (screenshots, logs, documents). These are automatically extracted and stored in GCS when the email is ingested. The `read` action returns an `attachments` array on the ticket with metadata for each file (`index`, `filename`, `contentType`, `size`, `messageId`, `uploadedAt`). To retrieve the actual file content:
-
-1. Use `read` to see the attachments list and their indices
-2. Use `get_attachment` with the desired `attachmentIndex` to download the file content (returned base64-encoded)
-3. If called without `attachmentIndex`, `get_attachment` lists all attachments with their indices
-
-This keeps file retrieval self-contained — no separate download endpoint is needed.
-
-**Recommended flow** — `accountId` is optional throughout; `ticketId` resolves the owning account:
-1. `read` — check ticket state and any attachments
-   - If `read` returns `ticket.mirrorOnly:true`, use the mirrored fields for triage context, restore the backing document first, then claim/update/complete it.
-2. **`accept`** (with `assignee`) — this is a **hard precondition for `update_status`**, not just etiquette
-3. `get_attachment` if attachments are present and relevant to the investigation
-4. `update_status` — `in_progress` while working, `pending_review` when the fix is done but not yet deployed
-5. `record_progress` as you go — one `investigation` entry for the root cause, one `verification` entry for the proof
-6. investigate/fix/verify on the owning ticket account or its implementation account as appropriate
-7. `complete` (with `resolution`) or `release` if handing off
-
-**Check each mutation actually landed.** Every action above is a write that can be refused while the
-CLI still reports the *call* as fine — see "Execute a Tool" for why, and read `result.success` from
-the response file. A silent no-op here means telling the user a ticket moved when it did not.
-
-**Duplicates are common.** The same defect is often filed twice — once against the `CLIENT`/subscriber
-account where it was observed and once against the owning `PLATFORM`/`PRODUCT` account. Before
-starting, check `mcp_support_ticket_queue` for the same subject or affected component. Close the
-duplicate with a `resolution` naming the ticket that carries the real work, rather than investigating
-it twice.
-
-**Automation rule:** If a ticket is involved, you should usually:
-- `read` at the start
-- `accept` before substantive work
-- `get_attachment` if there are attachments relevant to the issue (screenshots, error logs, etc.)
-- `update_status` when actively working or blocked
-- `complete` after verification
-- `release` if you are handing it off or cannot continue
-
-### Component branches
-Use `remits-cli components branches` / `remits-cli components branch <name>` to inspect committed branch
-variants, subscribers, and drift from a local checkout.
-
-Common uses:
-- `remits-cli components branches` — list branches this owner has variants on.
-- `remits-cli components branch <name>` — show overridden / added / removed components on that branch.
-- `remits-cli components branch <name> --diff <id> --component-type <kind>` — compare one variant against
-  current trunk.
-- `remits-cli components branch <name> --subscribers` — list accounts resolving that branch.
-
-### `mcp_cache`
-Bounded read-only investigation of the platform Redis keyspace — the way to see exactly what a staged
-entry holds (and its TTL) or any other cache key. Read-only: no delete (use `remits-cli components clear`
-to remove staged component entries).
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `action` | yes | `summary` (overview of matching keys), `scan` (paginated key list; add `includeValuePreview:true`), or `inspect` (one exact `key`) |
-| `pattern` | no | Redis glob for summary/scan (e.g. `account:52:cli:*:components:*:reader:id:181`). Alias: `keyPattern`/`query` |
-| `key` | no | Exact key for `action:'inspect'` |
-| `pageSize`/`sampleSize`/`previewChars` | no | Bounding controls |
-
-### `mcp_sql_query`
-Read-only, bounded SQL against the platform database. This is the **catch-all investigation surface** for
-questions the purpose-built tools do not model — above all **users and account membership**, for which there
-is no dedicated tool.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `query` | yes* | One read-only statement. Alias: `sql`. Must start with `SELECT`, `WITH`, `SHOW`, `DESCRIBE`/`DESC`, or `EXPLAIN`; mutation, DDL, locking, and filesystem constructs are rejected. |
-| `queries` | yes* | Batch of up to 10 read-only queries (strings, or `{query, params}` objects) |
-| `params` / `parameters` | no | Positional parameters — **use these instead of interpolating values** |
-| `maxRows` / `limit` | no | Rows per query. Default 100, max 500. |
-| `maxValueChars` | no | Truncation width per string value. Default 2000, max 20000. |
-| `redact` | no | Redact secret-like columns (`password`, `token`, `secret`, `authorization`, …). **Default true — leave it on.** |
-
-*Provide `query`/`sql` or `queries`.
-
-Useful shapes:
-
-```sql
--- who has access to a client account (and through which membership rows)
-SELECT u.id, u.username, u.enabled FROM user u
-  JOIN user_account ua ON ua.user_id = u.id WHERE ua.account_id = ?;
-
--- every account a user can reach directly
-SELECT a.id, a.name, a.type FROM account a
-  JOIN user_account ua ON ua.account_id = a.id WHERE ua.user_id = ?;
-
--- the account's structural links, including membership edges (`primary` is column `is_primary`)
-SELECT parent_id, is_primary, branch_name, database_name, domain_name, active
-  FROM account_relationship WHERE account_id = ?;
-```
-
-**This tool is lane-blind — filter the data lane yourself.** Every other record surface segments test from
-prod data for you; raw SQL does not. `object`, `event`, and `alert` carry a `test_mode` column, `user`
-carries `test_user`, and `account` carries `test_account`, and an unfiltered query returns **both lanes
-mixed** — so "who has access to this account" silently includes throwaway test users, and a row count
-silently includes test fixtures. Add the predicate explicitly:
-
-```sql
--- prod lane only (legacy rows predate the column, so NULL counts as prod)
-SELECT id, name, status FROM object
-  WHERE account_id = ? AND (test_mode IS NULL OR test_mode = 0);
-
--- real users of an account, excluding test fixtures
-SELECT u.id, u.username, u.enabled FROM user u
-  JOIN user_account ua ON ua.user_id = u.id
-  WHERE ua.account_id = ? AND (u.test_user IS NULL OR u.test_user = 0);
-```
-
-Prefer the purpose-built tools when one fits — they apply account scoping, data-mode segmentation, and
-resolution awareness that raw SQL does not. Reach for SQL when nothing else models the question.
-
-### `mcp_index_search`
-Query and **diagnose** the Vertex AI Search index through the platform's Vertex DSL. Use it to check what a
-RAG/search-backed component actually retrieves before blaming the component.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `accountId` | yes | Tenant scoping |
-| `action` | no | `search` (default, `index_search()`), `facets` (`index_facets()` — taxonomy/distinct values), `diagnose` (explain why strict filtering dropped matches), `inspect` (what is actually indexed for given `sourceDocumentIds`) |
-| `query` | conditional | Required for `search`/`diagnose` |
-| `schema` / `projectionType(s)` / `projectionSource` | no | Scope to a schema's Vertex projections |
-| `filters` | no | Vertex-style structured filters on indexed metadata |
-| `pageSize` / `maxResults` / `pageToken` | no | Paging and local trimming |
-| `searchProfile` | no | `ai`/`agent`/`strict` (precision) vs `admin`/`default` (recall) |
-| `includeMatchDiagnostics` | no | Return the applied filter/query plus the pre-strict-filter candidate set |
-| `accountIds` | no | Explicit multi-account search |
-| `dataMode` | no | `test` (default) or `prod` |
-
-When a component "can't find" an obviously-present document, run `action:'inspect'` on its source document id
-first — that shows what was indexed, which is usually the answer.
-
-### `mcp_get_guide`
-Load the packaged front-stage guides — the same `docs/guides/` set `remits-cli` syncs into a repo. Use it when
-you are working **outside a repo** (or the repo's `guides/` is stale) and need the authoritative guidance
-before writing a component.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `guide` | conditional | Short name (`agent-components`), relative path (`features/account-management`), or full path |
-| `list` | no | List available guides instead of loading one |
-| `directory` | no | Scope a list to `components` or `features` |
-| `contains` | no | Substring filter when listing |
-
-Every guide is delivered with a table of contents whose entries carry **real line numbers**
-(`- L412  Querying Alerts`), resolved at delivery so they are never stale. Several of these guides are
-over a thousand lines: read the head, pick the sections you need, and offset-read those rather than
-loading the whole file. The entry text is the heading verbatim, so it also greps.
-
-### `mcp_test_fixture`
-Seed and remove schema-backed fixture documents in the **forced test** data segment. This is how you construct
-realistic conditions for verification without copying live customer data.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `accountId` | yes | Account owning the target schema/collection |
-| `action` | no | `create` (fails on existing id), `upsert`, or `delete` |
-| `schemaName` / `collection` | conditional | Schema display name or collection name |
-| `documentId` / `documentIds` | no | Explicit Firestore ids for single/batch operations |
-| `data` / `documents` | conditional | Single payload, or a batch array |
-| `dataMode` | no | Must be `test` — **prod-mode writes are rejected** |
-
-### `mcp_playwright_replay`
-Hosted browser automation (the `playwright-relay` service) for visual verification when local `playwright-cli`
-is unavailable — e.g. an agent running remotely. Returns an accessibility snapshot and interactive refs on
-every command, so you navigate iteratively.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `command` | yes | `open`, `goto`, `snapshot`, `click`, `dblclick`, `hover`, `fill`, `select`, `check`, `uncheck`, `eval`, `run-code`, `screenshot`, `pdf`, `console`, `network`, `go-back`, `go-forward`, `reload`, `tab-*`, `close`, `close-all` |
-| `sessionId` | conditional | Reuse an existing session. `open`/`goto` without one starts a session. |
-| `url` / `target` / `value` / `expression` / `code` | conditional | Per-command inputs (`target` is an element ref or selector) |
-| `compact` | no | Default true — omits bulky raw relay payloads |
-| `includeSnapshot` / `includeAccessibility` / `includeRefs` / `includePage` / `includeResult` / `includeRaw` | no | Response shaping |
-| `pattern` / `level` / `limit` | no | Filters for `console` / `network` |
-| `ticketId` / `artifactType` / `artifactLabel` / `artifactNotes` | no | Attach a screenshot/pdf/trace/video to a support ticket |
-
-### `mcp_jvm_spike_triage`
-Production-aware triage bundle for a Cloud Run service showing a latency/memory spike. Safe by construction:
-optional class-histogram sampling, **no heap dump and no JFR**.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `serviceName` | yes | e.g. `remits`, `remits-actions` |
-| `region` | yes | e.g. `us-east5`, `us-east1` |
-| `sampleHeap` | no | Default true — one class histogram + heap composition sample (brief stop-the-world) |
-| `top` | no | Top classes to return. Default 20, max 100. |
-| `includeThreadDump` / `threadLimit` | no | Fuller thread dump beyond the built-in top-thread preview |
-| `includeLogs` / `logLookbackMinutes` / `logLimit` | no | Recent WARNING+ log signals for the same service |
-
-### `mcp_support_ticket_queue`
-List and filter tickets **across an account and its descendants** so you can choose what to work on. Lifecycle
-actions stay on `mcp_support_ticket`.
-
-Queue rows are built from support-ticket anchor mirrors by default. A row in this list means a
-support-ticket anchor exists; it does not guarantee the full Firestore document is healthy. Open the
-ticket with `mcp_support_ticket read` before lifecycle work and honor `mirrorOnly` / `documentState` if present.
-
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `action` | no | `list` (default) |
-| `accountId` / `accountIds` / `includeChildren` / `includeRoot` | no | Queue scope. Defaults to the current account **and its descendants**. |
-| `statuses` / `status` | no | Defaults to `open`, `accepted`, `in_progress`, `pending_review`. `['all']` disables filtering. |
-| `priorities` / `types` / `sources` / `tags` | no | Additional filters |
-| `assignedTo` / `unassigned` | no | Assignment filters |
-| `implementationAccountId` | no | Filter by owning `PLATFORM`/`PRODUCT` account |
-| `workstream` / `plannedIn` / `boardStage` / `size` / `blockedBy` | no | SDLC-agnostic planning filters; exact matches on compact queue fields |
-| `rank` / `minRank` / `maxRank` | no | Exact or inclusive range filters for numeric planning rank |
-| `search` | no | Case-insensitive across subject, description, account, affected component, sender, tags, workstream, and planning fields |
-| `sortBy` | no | `triage` (default-style: critical/high unassigned first), `updated`, `priority`, `status`, `account`, `plannedIn`, `boardStage`, `rank`, `size` |
-| `sortDirection` | no | `asc` / `desc`, and it means the same thing on every axis. Natural order is `desc` for `triage`/`updated`/`priority` and `asc` for `status`/`account`/`rank`/`plannedIn`/`boardStage`/`size`, so pass it only to invert one |
-| `limit` / `offset` / `scanLimitPerAccount` | no | Paging and scan bounds |
-| `dataMode` | no | Normal agent work uses the **prod** ticket queue |
-
-## Multi-Session Support
-
-The CLI supports multiple authenticated sessions simultaneously. Sessions are stored in `~/.remits-cli/sessions.json` as a map keyed by `accountId + dataMode + baseUrl`, so the same account can stay authenticated against both localhost and production without one session overwriting the other. When you run any command from an account repo, the CLI automatically resolves the best matching session based on the `account-info.json` in that directory and any `--base-url` or `--data-mode` flags provided. If the same account is authenticated against multiple hosts and you omit `--base-url`, the CLI may legitimately choose either localhost or a deployed host depending on the best session match, so agents should treat `--base-url` as mandatory whenever host matters.
-
-```bash
-# Authenticate for an account (run from its repo, or pass --account-id)
-remits-cli auth
-remits-cli auth --account-id 42
-remits-cli auth --account-id 42 --base-url http://localhost:8080
-
-# List all active sessions
-remits-cli sessions list
-
-# Remove a session (removes all sessions for the account, or narrow with --base-url / --data-mode)
-remits-cli sessions remove --account-id 42
-remits-cli sessions remove --account-id 42 --base-url http://localhost:8080
-```
-
-You can work in multiple account repos simultaneously across different terminal windows — each uses its own session. You can also be authenticated against different base URLs (e.g., localhost for development and production) for the same account at the same time.
-
-Use `remits-cli whoami` when you need a compact proof of the active target before a sensitive operation.
-It prints the resolved Account ID, User ID, current git branch, data mode, and base URL. `remits-cli status`
-prints the same session tuple after the service/dashboard status. Pass `--base-url`, `--account-id`, and
-`--data-mode` when host or lane matters; do not infer those values from the repo directory or account name.
-
-**The reported data mode describes the next `tool` / `tools` / `token` call, not `test run`.** It falls back
-to the stored session lane, whereas `remits-cli test run` deliberately ignores that and defaults to `test`
-unless you pass `--data-mode prod` explicitly. So `whoami` can read `prod` while a test run goes to the test
-lane — which is the safe direction, but not the one you would predict from the output alone. `whoami` says
-so in its own output; when a test run genuinely needs prod data, pass the flag.
-
-## Registering This Session As An Agent
-
-`remits-cli agent` is how a terminal session makes itself available to work support tickets. It is
-independent of everything else — no background service is required, and every tab is its own agent.
-
-```bash
-remits-cli agent serve               # routable AND autonomously working tickets — the usual choice
-remits-cli agent workers             # what this session is running right now
-remits-cli agent list                # who else is available across the accounts you cover
-remits-cli agent release             # stop serving and stop receiving tickets right now
-
-remits-cli agent register            # presence ONLY — nothing starts on its own
-remits-cli agent work --wait 300     # ask for tickets routed here (manual loop)
-remits-cli agent status --state working --ticket 22454 --activity "reproducing"
-```
-
-`serve` is `register` plus a supervisor. Everything below about registration applies to both.
-
-**Defaults exist so the user does not have to type them.** With no flags, `register` targets the
-production platform (`REMITS_BASE_URL` when set) and the **prod** lane, and claims every account repo
-indexed on this machine. That is a deliberate exception to the CLI's test-first default: registering
-presence mutates no business data, and a test-lane agent is silently useless for support — it appears
-online and can never be routed a production ticket. Every command after `register` reuses the
-platform, lane and identity it registered with.
-
-### What registration actually does
-
-- Mints an `agentId` for this session and tells the platform which account repos this machine has
-  checked out — read from the machine-wide index (`~/.remits-cli/account-repos.json`), which is why
-  the working directory does not matter. The platform **verifies** those claims against what your user
-  can access and returns the ones it refused, so "I registered but never get tickets for account 52"
-  is answerable from the registration output alone.
-- Starts a small detached heartbeat process **anchored to the agent process that owns this terminal**
-  (it walks up the process tree to find `claude`/`codex`/`gemini`, then an interactive shell). When
-  that process ends, the heartbeat ends and the session stops being routable within a couple of
-  minutes. Closing the tab is a valid way to go offline; `agent release` just makes it immediate.
-- Registers in the session's **data lane**. A `test`-lane run only ever reaches a `test`-lane agent,
-  which is what keeps fixture traffic away from a production terminal.
-- Declares **capacity** — how many tickets this session can genuinely run at once (`--max-concurrent`,
-  default 1). The router will not exceed it.
-
-### What `serve` adds
-
-The same detached process that maintains presence also polls for work. On each poll it publishes the
-tickets it currently has running, renews their claims, and takes at most enough new ones to fill its
-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` |
-| `claude` | `claude -p --add-dir <repo>` | `--permission-mode acceptEdits` | `--permission-mode plan` |
-| `gemini` | `gemini -p` in `<repo>` | `--approval-mode auto_edit` | `--approval-mode plan` |
-
-**Which of the three it launches:** `--worker-agent` if you pass it, otherwise **whatever agent this
-session is** (detected from the process the agent anchored to — which finds nothing in a plain tab),
-otherwise `~/.remits-cli/config.json`'s `agent` (set it with `remits-cli config set --agent NAME`),
-otherwise `claude`. **It prints which it chose and why on startup**, because in the intended
-plain-tab setup the choice comes from a config file you may have set months ago. So running `agent serve` inside a Codex tab gives you Codex workers
-without a flag, and the label the operator sees (`codex@repo`) is resolved the same way — the label
-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.
-
-**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
-agent's own messages as distinct things. It keeps working after the worker exits — a finished run is
-usually the one worth reading. For a terminal instead, each worker prints a `tail -f` for its log in
-`~/.remits-cli/workers/`.
-
-**There is no terminal to attach to, by design.** A worker is spawned with pipes and runs
-non-interactively (`codex exec`, `claude -p`), so there is no tty and no prompt to type at — the
-whole point is that it needs no supervision. Following the transcript is the way to watch, and it is
-strictly better than a terminal would be: the output is structured, so it can be read as events
-rather than scraped back out of ANSI text.
-
-**No worker ever commits.** The brief forbids `git commit`/`git push` and nothing in the supervisor
-runs git — a worker leaves its changes in the working tree and says so on the ticket, for a human to
-review.
-
-### Resolving which agent a command means
-
-Order: `--agent-id`, then `REMITS_AGENT_ID`, then the single agent registered for this working
-directory. With several registered and no way to tell them apart, the command **fails and lists the
-candidates** rather than guessing — routing work to the wrong tab is silent, and a message is not.
-
-### Which agent gets a ticket
-
-The platform walks a ladder — the ticket's implementation account first (a defect seen on a client is
-usually fixed in the platform repo above it), then the ticket's own account, then its
-`PLATFORM`/`PRODUCT` ancestors — and takes the first account with an available agent. Among those it
-prefers an **idle** agent, then the one that has waited longest, so work spreads across your tabs
-instead of piling onto whichever one most recently ran a command. A `paused` agent stays visible and
-is never routed to, and so is one **at capacity** — those are different facts and stay separate:
-`paused` means a human stopped this session, at-capacity means its workers are all busy.
-
-### Why a routed ticket might not have started
-
-In order of likelihood:
-
-1. **The session registered but never served.** `agent register` starts nothing. `agent workers`
-   showing none while a ticket is routed here is this.
-2. **At capacity.** Check `agent workers`; the ticket starts when one finishes.
-3. **Another session is running it.** A claim held by a different agent blocks it until that claim is
-   dropped or expires.
-4. **No local checkout.** The worker still starts, and its brief tells it to locate the repo rather
-   than guess — but if the account genuinely is not on this machine it will say so and stop.
-5. **It failed twice already** and was released back to the queue. The transcripts in
-   `~/.remits-cli/workers/` say why.
-
-## Background Service and Control Center
-
-`remits-cli start` runs an optional background service for the **human** watching:
-
-- Maintains persistent WebSocket connections to the Remits platform
-- Hosts a localhost browser **control center** (typically `http://127.0.0.1:8787/`)
-
-```bash
-remits-cli start
-remits-cli start --foreground true
-remits-cli status
-remits-cli whoami
-remits-cli stop
-```
-
-Compatibility aliases still exist:
-
-```bash
-remits-cli listen
-remits-cli listen status
-remits-cli listen stop
-```
-
-**The service is not part of ticket delivery.** Agents register and collect work on their own, so the
-dashboard being down never stops a ticket reaching an agent. What the service adds is visibility: it
-scans for `account-info.json` files to rebuild the repo index, keeps one WebSocket per platform URL,
-and holds a PID lock (`~/.remits-cli/listener.pid`) so only one runs per machine.
-
-### Control Center
-
-The control center shows, in one browser view:
-- which agent sessions are registered, what each is doing right now, and its recent activity
-- 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
-- the discovered account repo index and the important global/per-repo files
-
-**What it shows is what the agents see.** The ticket queue comes from the platform's own generic
-endpoint, not from any product's tool, so the control center reads the same on every Remits platform
-and never implies a workflow that a particular product does not have. Product-specific views belong
-in that product's Embeddables.
-
-When a user asks a broad or vague question about remits-cli behavior, prefer reasoning from the
-control center state before spelunking individual files.
-
-### Configuring the Preferred Agent
-
-```bash
-remits-cli config                    # Show current config
-remits-cli config set --agent claude # Use Claude Code (default)
-remits-cli config set --agent codex  # Use OpenAI Codex CLI
-remits-cli config set --agent gemini # Use Gemini CLI
-```
-
-The agent preference is stored in `~/.remits-cli/config.json` and applies globally.
-
-## Local State Files
-
-**Global** (`~/.remits-cli/`):
-- `sessions.json`
-  - Source of truth for authenticated account sessions, keyed by `accountId + dataMode + baseUrl` so the same account can hold separate sessions for different environments (e.g., localhost vs production).
-  - Each entry contains auth token, user info, websocket topic, data mode, base URL, and timestamp.
-  - Read this when a question involves auth, account selection, websocket topic coverage, or which session a command should resolve.
-- `config.json`
-  - Global CLI preferences.
-  - Currently most important for preferred agent selection, but treat it as the general machine-level config file.
-- `service-state.json`
-  - Runtime snapshot for the currently running remits-cli service.
-  - Includes dashboard URL, chosen port, repo-discovery summary, and websocket connection state.
-  - This is the first file to read when the user asks "is remits-cli running?", "what port is the dashboard on?", or "why isn't the browser page showing my connections?"
-- `account-repos.json`
-  - Index of all known account repositories on this machine.
-  - Built from `account-info.json` discovery plus best-effort updates when commands run inside an account repo.
-  - This is the repo-resolution file. Read it before deciding that a repo is unavailable locally.
-- `listener.pid`
-  - PID of the background remits-cli service process.
-  - Use it only to confirm process presence; use `service-state.json` for richer service details.
-- `agents.json`
-  - The agent sessions registered from this machine, each with the process it is anchored to.
-  - Read this when a command asks for `--agent-id`, or when an agent appears registered locally but
-    is missing from `remits-cli agent list` (that gap IS the "why am I not getting tickets" answer).
-- `activity.log`
-  - Human-readable chronological event log for service lifecycle, websocket events, agent
-    registration/heartbeat, and ticket routing.
-  - This is usually the best forensic file for "what happened?" questions.
-
-**Per-repo** (`./.remits-cli/`):
-- `tools/tools.json`
-  - Cached tool definitions for this repo context.
-  - Read this when tool availability or input shape is unclear.
-- `sessions/<name>.jsonl`
-  - Repo-local HTTP request/response log for `/cli/*` calls.
-  - Tokens are redacted and large content fields are summarized.
-  - This is the first file to inspect when the question is "what exactly did remits-cli send or receive from this repo?"
-- `tool-responses/<callId>.json`
-  - Full payload for `remits-cli tool` responses that were too large for the session log.
-  - Prefer this over terminal summaries when investigating tool behavior.
-- `current-session.txt`
-  - Pointer to the active repo-local session log name.
-  - Always read this before opening `sessions/<name>.jsonl`.
-
-Reading rules:
-- Read `current-session.txt` before opening a session log by name.
-- When a tool call says the response was stored externally, open `tool-responses/<callId>.json` instead of inferring from the terminal summary.
-- If a question spans both global and repo-local behavior, inspect both layers and explain which facts came from which layer.
-
-## Command Reference
-
-```
-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 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]
-remits-cli agent status [--state idle|working|paused] [--ticket ID] [--activity "..."] [--step "..."]
-remits-cli agent list [--account-id ID] [--json]
-remits-cli agent map [--account-ids 1,4] [--json]       # who is EDITING which repository, from which checkout/branch/staging lane
-remits-cli agent release
-remits-cli ticket read|accept|status|progress|complete|release|reopen|assign|planning --ticket ID [--status S] [--resolution "..."] [--summary "..."] [--category C] [--assignee EMAIL] [--workstream VALUE] [--planned-in VALUE] [--board-stage VALUE] [--rank N] [--size VALUE] [--blocked-by VALUE] [--notes "..."]
-remits-cli ticket lease|unlease|force-unlease --ticket ID [--reason "..."]   # force-unlease breaks SOMEBODY ELSE'S lease; operator only
-remits-cli ticket where --ticket ID                    # WHERE this work is: repo account, checkout, branch, staging lane, live lease + holder's location, claim, your phase
-remits-cli ticket ask --ticket ID --question "..." [--context "..."] [--to WHO]   # park on a human decision
-remits-cli ticket answer --ticket ID --message "..." [--route false]             # answer it (alias: reply); re-routes by default
-remits-cli ticket message --ticket ID --message "..." [--to a@x,b@y] [--subject "..."] [--channel email]  # PUBLIC — the requester reads it
-remits-cli ticket note --ticket ID --message "..."     # INTERNAL — the next worker and a reviewer read it
-remits-cli ticket deliver --ticket ID --channel email --to a@x [--template T] [--subject "..."] [--idempotency-key K]   # ask for it to be SENT
-remits-cli ticket deliveries --ticket ID [--channel email]   # what is queued to go out, and what already went
-remits-cli ticket delivered --ticket ID --delivery-id ID | ticket delivery-failed --ticket ID --delivery-id ID --reason "..."
-remits-cli ticket tag --ticket ID --tags a,b           # make a cluster of near-identical tickets visible as one
-remits-cli ticket artifact --ticket ID --type TYPE --label "..." [--url U | --content "..."]
-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 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
-remits-cli status [--base-url URL] [--account-id ID] [--data-mode test|prod] [--json]
-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 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 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]
-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 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>]
-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]
-```
-
-For tests specifically:
-- If `--data-mode` is omitted, `remits-cli test run` uses `test`.
-- `--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
-  (*"what does customer X get?"*); `--variant-branch <name>` probes a branch from any checkout
-  (*"what does branch Y look like?"*), and `--variant-branch none` forces production/subscription semantics.
-  Omit both and the working tree decides — see "Branched Component Variants".
-- `--branch <stagingScope>` on `test run` selects the Redis staging namespace only. It is useful with
-  `--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.
-- `--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.
-- **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**.
-    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".
-    > **Pair it with `--changed-since <ref>` after you have committed.** On its own `--changed-only`
-    > reads UNCOMMITTED edits, and the documented flow commits and pushes *before* syncing (sync reads
-    > the pushed remote, so it cannot see uncommitted work at all) — so the changed set is empty at
-    > exactly the moment the gate runs, and it refuses the whole plan. `--changed-since origin/main`
-    > (or the commit you branched from) makes the changed set the components your commits touched.
-    > The refusal message says this when it detects the empty-set case.
-  - `--fail-on-removed` — fail if the plan removes or tombstones anything.
-  - `--expected-removed <type:id>` — whitelist the removals you intend (repeatable, or comma-delimited,
-    e.g. `--expected-removed action:5,reader:9`). It **implies** `--fail-on-removed`, so any removal you
-    did not name fails the sync.
-  - `--fail-on-errors` — fail if the server reported any per-component sync error.
-  - `--names-only` — dry-run and print only `BUCKET type:id name` lines for the planned writes, then stop
-    without writing overlays.
-
-  A good default for an unattended promotion is:
-  `remits-cli components sync --summary --changed-only --fail-on-errors`
-
-### Prod banners and retryable failures
-
-- Every command that can touch production (`tool`, `test run`, `components sync`) prints a `PROD DATA`
-  banner naming the operation, the resolved account, and the host — and distinguishes a live **WRITE**
-  from a live **READ** and from a **DRY RUN**. `remits-cli tool` also prints an explicit **TEST DATA WRITE**
-  banner for mutating tool calls in the test lane, including multi-action tools such as
-  `mcp_account_user_admin` where the write is signaled by `input.action` (`account_create`, `user_update`,
-  `edge_update`, etc.). If you see a WRITE banner you did not intend, stop.
-- A tool call that fails **in the platform runtime** rather than in the tool (Groovy reflective dispatch
-  of a runtime-compiled component, an empty connection pool, a Redis reconnect, a lock-wait timeout)
-  now comes back as HTTP `503` with `failureClass: "transient_infrastructure"` and `retryable: true`,
-  and the CLI prints `TRANSIENT INFRASTRUCTURE FAILURE (retryable)`. Retry that **once**; prefer an
-  idempotent input if the tool has side effects. A genuine tool error stays HTTP `500` with
-  `failureClass: "tool_error"` — do **not** retry it, fix the input or the component.
-
-## Troubleshooting
-
-| Symptom | Fix |
-|---|---|
-| 401 or `Not authenticated` | Run `remits-cli auth` |
-| `account-info.json not found` | Run from the account repo root |
-| Test not found (404) | New component not staged yet. Run `remits-cli components stage` first. For new tests (no ID), run by name not ID. |
-| Stage shows 0 updated | No changes since last stage (hash dedup) |
-| Test runs old code after edit | You forgot to stage, or you are looking at DB while a staged entry is still active. Run `remits-cli components status`; then `remits-cli components stage` to update staged code or `remits-cli components clear` to fall back to DB. |
-| "Git credentials" or `git push` error | Git auth is required for commit (server pulls from git remote). Fix git authentication (SSH keys or HTTPS credentials) before retrying. Staging and testing still work without git. |
-| Need to learn command behavior | Read this skill, repo docs, or CLI source. Do not run unsupported mutating subcommand variants such as `remits-cli components commit --help`; if a command unexpectedly mutates or commits, stop and inspect the repo-local session log before doing anything else. |
-| Sync response reports unexpected deletes, creates, renames, uniqueness errors, or component ID drift | Stop immediately. Do not rerun sync, do not create replacement components to paper over the mismatch, and do not promote more changes. Preserve session logs/tool responses, compare `account-info.json`, local filenames, live inventory, and git history, then prepare a repair/escalation summary. |
-| 500 / `Internal Server Error` from Remits | Stop normal task work. Capture the exact command, error, and response artifact, then escalate to a Remits system admin. Do not invent a workaround. |
-| Tool parameters rejected | Tool schemas may be cached. Run `remits-cli tools` to refresh `.remits-cli/tools/tools.json` with latest schemas. |
-| Tool response missing | Check `./.remits-cli/tool-responses/` |
-| Long-running tool times out | For `mcp_run_action`/`mcp_run_agent`, use the tool's own `executionMode:"async"` and poll with a `controlAction:"status"` call (see "Tool Execution Lifecycle"). For other long tools without their own async, use `remits-cli tool --async true` and poll `remits-cli tool status --call-id <callId>`. `--timeout-ms` only adjusts the per-request HTTP timeout; it is not a substitute for async. |
-| Need to continue tracking a long Action or Agent after terminal disconnect | Read `./.remits-cli/tool-responses/<callId>.json` for the returned `actionRunId`/`agentRunId`/`sessionId`/`threadGroupingId`. Re-poll the run with a `controlAction:"status"` call carrying that `actionRunId`/`agentRunId`, or inspect the agent session via `mcp_ai_session_search` with the `sessionId`. |
-| Staged change has no effect in a live (non-CLI) run | Staged overrides resolve only under a CLI TestMode (`branchName`+`cliUserId`). Live webhooks and other non-CLI runtime paths still use the DB (trunk, or the account's subscribed variant). `commit` to make it durable. See "Component Resolution". |
-| Need to know an account's shape (role, type, parents, namespace, branch, host/login routes) | Read `resolution` — from the repo's `account-info.json`, or `mcp_account_user_admin` `action:'account'` (cheap), or `mcp_account_view` (full inventory): `role`/`summary`, `type`, `resolvedDatabaseName`, `domainName`/`resolvedDomainName`, `authPath`/`targetPath`, `relationships`, `componentBranch`, plus top-level `componentBranches`. Never infer structure from the account's name. |
-| Need the account tree below an account, or its users | In a local repo, read `account-hierarchy.json` for the generated tree. For live data, use `mcp_account_user_admin` (`action:'hierarchy'` with a `depth`, or `action:'users'`). `account-info.json` deliberately omits the tree. |
-| Need to prove whether an account/user/record is test data | Check explicit flags: `resolution.testAccount` / hierarchy `testAccount`, `mcp_account_user_admin` `testAccount` / `testUser`, token inspect owner flags, and `mcp_record_listing` / `mcp_record_view` `testMode` for object/event/alert rows. Do not infer from names or branch labels. |
-| Need account configuration values | In a local repo, read `account-configurations.json`. For live data, use `mcp_account_user_admin` (`action:'account'`) or `mcp_account_view`. `account-info.json` deliberately omits configurations. |
-| An account has two parents and you don't know which one a run used | `resolution.relationships` lists every link with its own `branchName`/`databaseName`/`domainName`. A membership-only account with SEVERAL edges resolves **trunk and inherits nothing** until a path is named (`--as-account`, `--variant-branch`, or an edge host) — that is by design, not a bug. With exactly ONE membership edge it inherits normally, descendants included. |
-| Documents missing / written to the wrong place | Compare `resolution.databaseName` (the account's own override) with `resolution.resolvedDatabaseName` (what is actually in effect), and check for a `databaseName` on one of the `relationships` edges. Data does not inherit; components do. |
-| 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. |
-| 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. |
-| A sync summary reports `skipped: true` with `NO COMPONENTS WERE SYNCED` | The branch head matches the cached sync SHA, so the branch was never re-read — this is NOT an empty plan. It matters when something else changed the overlays at that same SHA: an ordinary re-sync then answers "nothing to do" forever. `--dry-run` always re-reads the branch and shows the real plan; `--force-tombstones` re-reads and applies it. |
-| A branch sync stores overlays for components you never edited on the branch | **Trunk moved.** Sparseness compares the branch against CURRENT trunk, so editing a component on trunk without merging trunk into the branch turns it into a branch overlay on the next branch sync. The branch did not change. Merge trunk in, push, re-sync — the overlays prune. Check `components promotion` for the phase. |
-| After promoting a `new_*` component to trunk, the branch still shows it as `added` | You have not re-synced the branch since the trunk sync. Merge trunk into the branch and `components sync`: the file adopts the promoted id and, if unchanged, removes its own overlay. If the branch carries BOTH `new_Foo.*` and `<id>_Foo.*`, the id file wins and the `new_` one is reported `skipped: superseded` - delete it. |
-| After promoting a standalone Prompt, the branch still shows `OVERRIDDEN prompt:<id>` with only `purpose` changed | The trunk Prompt row does not match repo metadata. Ensure the Prompt sidecar has `description` and `purpose: CUSTOM`, run a platform build that imports Prompt `purpose`, re-sync trunk, merge back, and re-sync the branch. |
-| A branch preview reports a `removed` component nobody deleted | Check whether that component has a file on **trunk**. A DB row with no trunk file is missing from every branch, so it reads as a removal everywhere (and the trunk sync tries to hard-delete it each run). Repair trunk, not the branch. |
-| `--as-account <id>` resolves trunk, or 404s | The account probably has several edges each carrying a branch, so the anchor is ambiguous and the platform refuses to guess. Name the branch with `--variant-branch <name>`, and confirm the edge with `components branch <name> --subscribers`. |
-| A branch variant is reported DRIFTED | The origin component changed after the variant was cut, so the branch is based on a stale version. `remits-cli components branch <name> --diff <id> --component-type <kind>` to compare, then reconcile the branch. |
-| New source shown by `mcp_component_view` but old behavior persists after sync/commit | The compile cache (`CLOSURE_CACHE`) is keyed by `version:<N>:<sourceHash12>`, so a source change on the same version now invalidates it automatically — a run right after sync/commit picks up the new source. If old behavior still persists, confirm the run actually hit the synced instance and that no staged override is still shadowing DB (`remits-cli components status`). |
-| Staged Reader test run throws `No enum constant ObjectType.<family>` | The staged entry has the component family in `type` (should be `kind`). Clear + re-stage; if it persists, inspect the staged payload with `mcp_cache` and escalate as a CLI/platform staging bug. |
-| Unsure whether a run used staged vs DB source | Query `mcp_system_logs` for `Using Cached BCD` — `Signature: cli:<hash>` = staged, `version:<N>:<sourceHash12>` = DB. CLI/MCP tool results also report `componentSource` and `componentSignature` when available. |
-| Service already running | Run `remits-cli status` to get the dashboard URL, or `remits-cli stop` before restarting. |
-| Control center URL unknown | Read `~/.remits-cli/service-state.json` or run `remits-cli status` |
-| Dashboard missing repos | Rebuild `~/.remits-cli/account-repos.json` with `remits-cli start` or the control center rescan action |
-| Agent dispatch to wrong directory | Check `~/.remits-cli/account-repos.json` has the correct directory and that you resolved the account type correctly. A `CLIENT` ticket may still belong to a parent `PLATFORM` or `PRODUCT` repo for code changes. |
-
-### When Something Doesn't Work as Expected
-
-All `remits-cli` capabilities — staging, test execution, committing, tool calls — are known to work. The
-most common cause is an operational mistake, above all forgetting to stage before running a test.
-
-If you have followed the loop (**edit → stage → run**) and something still misbehaves after 2-3 attempts,
-**stop trying workarounds** and decide which kind of problem it is:
-
-- **A `remits-cli` / tooling operational issue** — staging, sync, dispatch, the listener, or the CLI itself
-  misbehaving → use the **Escalation Bundle** below and ask the user to escalate to a Remits system admin.
-- **A Remits back-stage platform defect or limitation** — the component *runtime* behaves wrong:
-  Hibernate/session/optimistic-locking errors, detached-entity surprises, brittle lifecycle or tool
-  behavior, a DSL method diverging from its guide → follow the **Back-Stage Escalation Workflow** in
-  `features/front-stage-debugging-strategy.md` (`mcp_get_guide`), which owns it end to end: analyze the
-  platform seam locally, open a PR on a feature branch (never merge it yourself), raise a
-  `mcp_support_ticket`, and tell the user. **Do not normalize it into a front-stage workaround.**
-
-The local clone of the core platform repo that workflow needs is tracked in
-`~/.remits-cli/account-repos.json` under the reserved **`platform`** entry (default `~/remits`, override
-with `REMITS_PLATFORM_DIR`); `remits-cli` clones it on first authenticated run if it is missing.
-
-Apply the boy-scout rule to the guides themselves: **whenever you only solved the problem by reading the
-core back stage because a front-stage guide was unclear or missing — even when there was no platform
-defect at all — open a guide-only PR** updating the relevant guide in the platform repo's `docs/guides/`,
-which is the source served to every account repo. Better guides over time are an explicit goal.
-
-#### Escalation Bundle (tooling/operational issue)
-
-1. **Create a single escalation bundle under `~/.remits-cli/issues/`.**
-   Use a directory name like:
-   - `~/.remits-cli/issues/<timestamp>-account-<accountId>-<short-slug>/`
-
-   Populate that directory with enough information that the user or a Remits system admin can continue without re-running your work. Include at minimum:
-   - `summary.md`
-     - What you were trying to do
-     - Why you were trying to do it
-     - The expected behavior
-     - The actual behavior
-     - The exact commands you ran, in order
-     - The key error messages or unexpected outputs
-     - Whether the failure blocks staging, testing, sync, ticket routing, listener dispatch, or production investigation
-   - `context.json`
-     - `cwd`
-     - target repo directory
-     - `accountId`
-     - account name
-     - account `type`
-     - branch name
-     - current data mode
-     - ticket ID if applicable
-     - component names / IDs involved
-   - Copies or references for the relevant supporting artifacts:
-     - `./.remits-cli/current-session.txt`
-     - the active repo session log from `./.remits-cli/sessions/`
-     - any `./.remits-cli/tool-responses/<callId>.json` files involved
-     - `~/.remits-cli/account-repos.json` if repo resolution may be relevant
-     - `~/.remits-cli/activity.log` if service / websocket / agent-routing behavior may be relevant
-
-2. **Use the global Remits CLI state to make the bundle self-contained.**
-   - Read `./.remits-cli/current-session.txt` to identify the active repo session log.
-   - Record the exact repo directory and account context from `account-info.json`.
-   - If repo selection or account targeting may be part of the issue, include the relevant entry from `~/.remits-cli/account-repos.json`.
-   - If the problem involves support-ticket routing, agent registration, or websocket events, include the relevant lines from `~/.remits-cli/activity.log`.
-   - If a tool call stored its full response externally, include that file path and summarize the important fields in `summary.md`.
-
-3. **Stop and document the issue clearly for the user.**
-   Tell the user where the escalation bundle lives and summarize:
-   - what was attempted
-   - what should have happened
-   - what actually happened
-   - why this appears to require a Remits system admin
-
-4. **Ask the user to escalate to a Remits system admin.** The system admin has access to the Remits platform codebase and the `remits-cli` source code, and can diagnose and fix platform-level issues directly.
-
-5. **Do not attempt creative workarounds** (renaming components, duplicating files, bypassing the CLI with raw API calls, etc.). If the platform has a real bug, workarounds mask the problem and make it harder to diagnose. It is better to have the issue fixed at the source than to build fragile workarounds around it.
+- For investigations, follow the shortest path: identify the exact document/ticket/object first, then
+  drill in. Avoid exploratory "maybe this" queries across large collections.
+- For ticket replies, read the current ticket state and the new reply, then continue from existing
+  context instead of re-loading broad account state from scratch.
+- Verification should be decisive. Avoid repeated identical test/status/tool calls when no new
+  information is likely.
+
+## When something doesn't work
+
+All `remits-cli` capabilities are known to work. The most common cause is an operational mistake, above
+all forgetting to stage before running a test. If you have followed **edit → stage → run** and something
+still misbehaves after two or three attempts, stop trying workarounds and open `troubleshooting.md`: it
+carries the symptom table, separates a CLI/tooling issue from a back-stage platform defect, and owns the
+escalation bundle for each.