@remits/remits-cli 0.1.112 → 0.1.114

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

@@ -0,0 +1,251 @@
+# Investigation and Production Support
+
+> A `remits-cli` skill reference. **Load this when** you are investigating live behavior: which record trail to read, how to correlate a processing chain, and the production support flows.
+>
+> The table of contents below carries **real line numbers** (`- L84  Some Heading`), resolved when
+> this file is installed, so they are never stale. Read the head, pick your sections, and offset-read
+> only those. The entry text is the heading verbatim, so it also greps.
+
+## Table of Contents
+
+- [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)
+- [Production Support Workflow](#production-support-workflow)
+  - [Investigation Strategy](#investigation-strategy)
+  - [Presenting Findings](#presenting-findings)
+  - [Verifying a Production Issue Fix](#verifying-a-production-issue-fix)
+
+## 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.md` 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.
+
+## 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 `tool-reference.md`. 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.

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

@@ -0,0 +1,389 @@
+# Support Tickets
+
+> A `remits-cli` skill reference. **Load this when** a ticket is part of the request, you are registering to work tickets, or you are the worker inside an autonomous ticket run.
+>
+> The table of contents below carries **real line numbers** (`- L84  Some Heading`), resolved when
+> this file is installed, so they are never stale. Read the head, pick your sections, and offset-read
+> only those. The entry text is the heading verbatim, so it also greps.
+
+## Table of Contents
+
+- [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)
+  - [The manual loop](#the-manual-loop)
+  - [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)
+
+## 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 |
+|---|---|---|
+| 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`.