@remits/remits-cli 0.1.110 → 0.1.113

package/skills/remits-cli/SKILL.md

@@ -21,7 +21,15 @@ description: Use remits-cli for fast branch-scoped component staging, test execu
 - [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)
-  - [The loop](#the-loop)
+  - [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)
@@ -109,8 +117,10 @@ description: Use remits-cli for fast branch-scoped component staging, test execu
 - [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)
@@ -291,8 +301,8 @@ every live component present at its real id, and nothing extra.
 | 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 the local branch/user staging scope and branch resolution. | none |
-| `remits-cli components clear` | Clears the local branch/user staging cache without changing DB or git. | 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** |
@@ -306,7 +316,7 @@ Key implications:
 - **`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
-  branch/user staging scope. This is the expected clean state: old Redis aliases should not keep shadowing
+  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
@@ -462,17 +472,21 @@ 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", run exactly this and nothing
-else first:**
+**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 register
+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 prints the accounts it was accepted for.
-It also prints the support loop; follow it.
+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
@@ -487,27 +501,67 @@ 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 loop
+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
 
-After `register`, **no agent command needs a flag** — they reuse the platform, lane and identity this
-session registered with.
+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 mcp_support_ticket (accept -> update_status -> complete) ...
+# ... 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
 ```
 
-**Stay on duty.** When `agent work` returns nothing, ask again — do not stop and wait to be
-re-prompted. Registration persists for the life of the session (the heartbeat keeps you visible and
-routable even while you are not polling), but collecting work is something you have to do.
+**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
@@ -519,10 +573,82 @@ timer.
 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.
 
-**Lane note:** `register` defaults to the production lane because a support agent works real tickets.
+**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
@@ -530,7 +656,147 @@ agents are registered and what each is doing, which tickets are open, and which
 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.
 
-Use `mcp_support_ticket` to manage lifecycle:Use `mcp_support_ticket` to manage lifecycle:
+### 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 |
+|---|---|---|
+| 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`
@@ -548,8 +814,9 @@ Ticket-routing context:
 - 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:
-- `remits-cli` commands that call the Remits service (`auth`, `tools`, `tool`, `components`, `test`, `token`) require outbound network access.
-- In Codex or similar sandboxed agent environments, `ENOTFOUND`, `EAI_AGAIN`, `ECONNREFUSED`, `EPERM`, or similar network errors usually mean the command must be retried with escalated permissions or outside the sandbox.
+- 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.
@@ -839,6 +1106,43 @@ remits-cli tool --name "mcp_run_action" --input '{"accountId":49,"actionId":200,
 
 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
@@ -1071,7 +1375,7 @@ If verification reveals issues, repeat the loop: **edit → stage → run**. Eve
 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 `mcp_support_ticket` to mark the ticket `in_progress` once you have started substantive work.
+- 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
@@ -1151,8 +1455,8 @@ unexpectedly, stop and inspect the repo-local session log before running any mut
 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 `mcp_support_ticket` with `complete` and include a concise resolution summary.
-3. If you cannot finish, use `update_status` or `release` with clear notes so the next agent can continue.
+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:
@@ -1203,10 +1507,17 @@ Plus the compile cache:
 ### 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`,
@@ -1284,15 +1595,51 @@ TestMode still uses the committed DB source. Staging remains a dev/verification
   `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 the current branch/user staged entries,
+- **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 scope. This is the normal edit/test loop.
+  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
@@ -2729,8 +3076,11 @@ ticket with `mcp_support_ticket read` before lifecycle work and honor `mirrorOnl
 | `priorities` / `types` / `sources` / `tags` | no | Additional filters |
 | `assignedTo` / `unassigned` | no | Assignment filters |
 | `implementationAccountId` | no | Filter by owning `PLATFORM`/`PRODUCT` account |
-| `search` | no | Case-insensitive across subject, description, account, affected component, sender, tags |
-| `sortBy` / `sortDirection` | no | `triage` (default-style: critical/high unassigned first), `updated`, `priority`, `status`, `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 |
 
@@ -2771,13 +3121,18 @@ so in its own output; when a test run genuinely needs prod data, pass the flag.
 independent of everything else — no background service is required, and every tab is its own agent.
 
 ```bash
-remits-cli agent register            # this session is now routable — no flags, any directory
-remits-cli agent work --wait 300     # ask for tickets routed here
-remits-cli agent status --state working --ticket 22454 --activity "reproducing"
+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 receiving tickets right now
+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
@@ -2798,6 +3153,48 @@ platform, lane and identity it registered with.
   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
 
@@ -2812,7 +3209,22 @@ usually fixed in the platform repo above it), then the ticket's own account, the
 `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.
+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
 
@@ -2926,18 +3338,39 @@ Reading rules:
 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 register [--label NAME] [--data-mode test|prod] [--account-id ID]
+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>] [--data-mode test|prod] [--json|--verbose]
+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