@remits/remits-cli 0.1.112 → 0.1.114

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

@@ -0,0 +1,962 @@
+# remits-cli Tool Reference
+
+> A `remits-cli` skill reference. **Load this when** you are about to call any `mcp_*` tool. Read the entry for that tool before you build its input.
+>
+> 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
+
+- [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)
+
+## 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 `command-reference.md` → *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 `investigation.md` → *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 in `component-resolution.md` → *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 |