@remits/remits-cli 0.1.69

package/skills/remits-cli/SKILL.md

@@ -0,0 +1,1278 @@
+---
+name: remits-cli
+description: Use remits-cli for fast branch-scoped component staging, test execution, embeddable token flows, and tool-based investigation.
+---
+
+# remits-cli
+
+`remits-cli` is the brainstem for both **development** and **production support**. You might run it inside an account repository (where `account-info.json` and `/components` already exist) or from outside any repo when a user needs help on another account. Your users are business professionals — they think in terms of what they can see in a browser.
+
+## Account Targeting Model
+
+Before deciding which repo or account context to use, read the target account's `type` from `account-info.json` or `Account.getInformation` / `mcp_account_view`.
+
+- **`PLATFORM`** = a use-case/platform implementation account. This is often where the shared Remits components live.
+- **`PRODUCT`** = a product/use-case account under a platform. This can also hold shared implementation components.
+- **`CLIENT`** = an actual customer account. This is usually where production data lives and where an issue is observed, but not necessarily where the shared implementation is authored.
+
+Do not guess from the account name alone.
+
+- If the work is a **feature, enhancement, component change, or shared behavior fix**, the implementation target is usually the relevant `PLATFORM` or `PRODUCT` account, not the `CLIENT` account that reported the issue.
+- If the work is a **production investigation or client-specific data issue**, start with the affected `CLIENT` account's data and runtime history.
+- If the request spans both, investigate in the `CLIENT` account first to confirm symptoms, then move to the owning `PLATFORM` or `PRODUCT` repo before making code changes.
+
+Apply these rules before making remote tool calls:
+
+- **Inside the target implementation repo**: read `account-info.json` (the same data that `mcp_account_view` returns) and inspect `/components` directly.
+- **Inside one repo but supporting a different account**: switch to the correct repo for that account type if available; otherwise use `mcp_account_view` / `mcp_component_view` / `mcp_component_grep`.
+- **Outside any repo**: rely on the tools for account structure and component source.
+- **Never create a new local repo/directory just because a ticket references an account name.** First resolve the account type and parent hierarchy. Only work from an existing indexed repo unless the user explicitly asks you to create or clone one.
+
+Use `remits-cli` for everything else: staging changes, running tests, generating embeddable tokens, committing work, and diagnosing production issues.
+
+## Required Local Index Reads
+
+These files are decision inputs. Read them when the related decision depends on them.
+
+- `~/.remits-cli/account-repos.json`
+  - The inventory of every local Remits repo. Account repos are keyed by numeric account id.
+  - It also contains the reserved **`platform`** entry: the local clone of the core Remits platform repo (`type:'PLATFORM_REPO'`, with its `directory` path). `remits-cli` clones it on first authenticated run if it is missing (default `~/remits`, override with `REMITS_PLATFORM_DIR`). Read this entry when you need to analyze a back-stage seam or open a platform-fix PR.
+  - Read before choosing a repo outside the current working directory.
+  - Read when a support ticket references an account and you need to locate the correct local repo.
+  - Read before concluding that a repo does not exist locally.
+- `~/.remits-cli/config.json`
+  - Read when service lifecycle, dashboard, listener, or agent-dispatch behavior matters.
+- `~/.remits-cli/service-state.json`
+  - Read when the local control center URL, current dashboard port, repo-scan summary, or websocket status matters.
+  - Read when the user asks whether the remits-cli service is running or where to open the browser view.
+- `~/.remits-cli/dispatch-panes.json`
+  - Read when support-ticket follow-up routing, pane reuse, or pane replacement behavior matters.
+- `~/.remits-cli/tmux-activity.log`
+  - Read when diagnosing service lifecycle, websocket, tmux, ticket-routing, or dispatch failures.
+- `~/.remits-cli/sessions.json`
+  - Read when authentication state, active accounts, base URLs, websocket topics, or per-account data mode matters.
+- `./.remits-cli/current-session.txt`
+  - Read before opening repo-local session logs so you know which session file is current.
+- `./.remits-cli/sessions/<current-session>.jsonl`
+  - Read when the question is about what HTTP calls the repo recently made through remits-cli, which payload was sent, or what response/error came back.
+- `./.remits-cli/tool-responses/<callId>.json`
+  - Read when `remits-cli tool` says the full payload was stored externally.
+- `./.remits-cli/tools/tools.json`
+  - Read when the question is about available tool names, cached schemas, or why a tool invocation shape may be invalid.
+- `account-info.json`
+  - Read in the target repo before making component changes or assuming account ownership.
+
+Do not rely on memory for these indexes. Read the file that governs the decision you are making.
+
+## Big Picture: How remits-cli State Is Organized
+
+Think about remits-cli as two cooperating layers:
+
+1. **Global machine state** in `~/.remits-cli/`
+   - This is the cross-repo control plane.
+   - It answers questions like:
+     - which accounts are authenticated
+     - which repos exist locally
+     - whether the background service is running
+     - where the control center lives
+     - whether websocket/tmux dispatch is healthy
+
+2. **Per-repo state** in `./.remits-cli/`
+   - This is the request/response and cache layer for one specific working tree.
+   - It answers questions like:
+     - which repo-local session log is current
+     - which `/cli/*` calls were made from this repo
+     - where a large tool response was written
+     - which tool schemas were most recently cached here
+
+When a user asks an indirect question, map it to the right layer first:
+
+- "Why did this ticket open in the wrong repo?" → start in global state.
+- "What exact payload did this tool call send?" → start in per-repo state.
+- "Why is the dashboard showing stale repos?" → start in `service-state.json` and `account-repos.json`.
+- "Why is the browser page not showing websocket activity?" → start in `service-state.json` and `tmux-activity.log`.
+
+Agents should use this mental model before guessing.
+
+## Support Ticket Mental Model
+
+The local agent workflow includes a lightweight support-ticket system:
+
+- Support tickets are Firestore documents in `support_tickets`.
+- Support tickets belong to the actual Remits account the work relates to.
+- Tickets are created centrally from support intake and pushed to local agents over the `remits-cli` WebSocket channel.
+- Each incoming ticket becomes a tmux workstream in the shared `remits-listener` session, so you can think of it as a localized Jira-style queue for active agent work.
+- Review centralized listener/tmux activity in `~/.remits-cli/tmux-activity.log`.
+
+Use `mcp_support_ticket` to manage lifecycle:
+- `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
+- Always call `mcp_support_ticket` with the ticket's owning `accountId`.
+- 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.
+- The local listener should prefer `implementationAccountId` when choosing the initial working directory for a ticket, with fallback to `accountId` if the platform/product repo is not available locally.
+- 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:
+- `remits-cli` commands that call the Remits service (`auth`, `tools`, `tool`, `components`, `test`, `token`) require outbound network access.
+- In Codex or similar sandboxed agent environments, `ENOTFOUND`, `EAI_AGAIN`, `ECONNREFUSED`, `EPERM`, or similar network errors usually mean the command must be retried with escalated permissions or outside the sandbox.
+
+Use the same repo/context rules as other tools:
+- If the ticket targets a `CLIENT` account, do not assume that client's repo is the implementation repo. Confirm the parent `PLATFORM` / `PRODUCT` relationship first.
+- Read `~/.remits-cli/account-repos.json` before choosing which local repo to open.
+- If the correct repo for the relevant account type exists locally, switch there and inspect `account-info.json` and `/components`.
+- If the repo is not available locally, use `mcp_account_view`, `mcp_component_view`, and `mcp_component_grep`.
+
+## Efficiency Rules
+
+Keep support and development sessions lean:
+
+- Prefer local repo files over remote tools whenever the target account repo exists locally.
+- Do not read entire `.remits-cli/sessions/*.jsonl` or large tool response files unless you first narrow to the relevant request, endpoint, tool, or ticket.
+- Prefer targeted Firestore queries: use `documentId`, tight `filters`, narrow `fields`, and low `limit` values instead of broad collection scans.
+- Do not call `mcp_account_view` repeatedly once you already have the needed account/component context.
+- For investigations, follow the shortest path: identify the exact document/ticket/object first, then drill in. Avoid exploratory “maybe this” queries across large collections.
+- For ticket replies, read the current ticket state and the new reply, then continue from existing context instead of re-loading broad account state from scratch.
+- Verification should be decisive. Avoid repeated identical test/status/tool calls when no new information is likely.
+
+## Account Repository Index
+
+The account repository index file is located at: `{{ACCOUNT_REPO_INDEX_PATH}}`
+
+This JSON file is automatically maintained by `remits-cli` and tracks all known Remits account repositories on this machine. It is updated whenever any `remits-cli` command runs from an account repo directory. The file maps account IDs to their metadata:
+
+```json
+{
+  "37": {
+    "accountId": 37,
+    "name": "Acme Corp",
+    "directory": "/Users/you/Projects/remits-acme-corp",
+    "updatedAt": "2026-03-23T12:00:00.000Z"
+  }
+}
+```
+
+**Use this index to:**
+- Discover which account repos exist on this machine when working from a different directory
+- Navigate to another account's repo to read its `account-info.json` and component source
+- Resolve account names and IDs without making remote API calls
+- Support cross-account workflows where an agent in one repo needs context from another
+
+If the index file doesn't exist yet, run any `remits-cli` command from an account repo to bootstrap it.
+
+## Two Workflows
+
+1. **Development** (test mode) — Build, modify, and verify components using isolated test data.
+2. **Production Support** (prod mode) — Investigate live data, debug issues, trace execution.
+
+Every CLI response includes `dataMode` so you always know which context you're in.
+
+### Test Mode vs Prod Mode
+
+Treat these as two different jobs:
+
+- **Prod mode** is for investigation.
+  - Read live Firestore documents.
+  - Inspect live object activity, events, alerts, and logs.
+  - Confirm what actually happened to a customer.
+  - Do not use prod mode as your final verification environment for a code fix.
+
+- **Test mode** is for verification.
+  - Stage local component changes.
+  - Run Test components.
+  - Generate token URLs and verify behavior in isolated browser flows.
+  - Confirm the fix without mutating or depending on live customer processing.
+
+The correct support loop is usually:
+1. Investigate in **prod mode**
+2. Identify the responsible implementation repo and make the code change locally
+3. Move back to **test mode** for verification
+4. Verify with a Test component, Playwright/browser confirmation, or both
+
+If a production issue needs realistic verification, do **not** copy live customer data from a production account into another account's test collection.
+
+The right model is:
+- investigate the source document in **prod mode**
+- model the relevant conditions in a **Test** component
+- or reproduce the scenario through a controlled **test-mode** embeddable/browser flow
+- verify the fix there
+
+Never treat "it looks right in prod data inspection" as sufficient proof that a code change is verified.
+
+## Platform Mental Model: Front Stage vs Back Stage
+
+| Layer | What It Contains | Purpose |
+|-------|------------------|---------|
+| **Front Stage** | Schemas, Readers, Actions, Embeddables, Rules, HtmlTemplates, Agents, Tests. Firestore **documents** are the business data (invoices, payments, vendors). | What the user sees and interacts with. Components are the building blocks; documents are the data. |
+| **Back Stage** | Lifecycle **records**: Objects, ObjectLogs, Events, Alerts. Cloud Logging traces. | Audit trail of everything the platform executed. Used for debugging and investigation. |
+
+### Documents vs Records
+
+- **Documents** (Firestore) = business data. Always have `account_id`, `object_id`, `_lastModifiedAt`, `_lastModifiedBy`, `_lastModifiedOn`. Query with `mcp_firestore_search`.
+- **Records** (MySQL) = execution audit trail, tied to `object_id`:
+  - **Object** — ingestion anchor (file, HTTP request). Has name, status, body/content.
+  - **ObjectLog** — log entries from Readers/Actions. Has `type`, `description`, `content`, `threadGroupingId`.
+  - **Event** — scheduled or executed actions. Has `action`, `status`, `eventDate`, `threadGroupingId`.
+  - **Alert** — notices (info/warning/error). Has `status`, `type`, `active`, `threadGroupingId`.
+- Use `mcp_record_listing` when you need to find candidate records first, and `mcp_record_view` when you already have the exact record ID.
+
+### HTTP Audits
+
+HTTP Audits are a first-class Firestore investigation surface for raw HTTP traffic, but they are **opt-in** per account.
+
+- The feature is controlled by `Account.enableHttpAudits`.
+- If `enableHttpAudits` is `false`, do not expect Firestore HTTP audit documents to exist for that account.
+- If `enableHttpAudits` is `true`, the platform writes normalized inbound and outbound HTTP audit documents to Firestore and also emits websocket `"http"` payloads using the same normalized shape.
+
+What gets captured when enabled:
+
+- **Inbound** HTTP handled by Readers
+- **Outbound** HTTP made from front-stage code through the `rest(...)` DSL
+
+Storage contract:
+
+- HTTP audits live in monthly Firestore collections, not in one global collection.
+- Collection path format is:
+  - `http-audits/http-audits-YYYY-MM/entries`
+- Always start with the month that matches when the request likely ran.
+- If the run may have crossed a month boundary, check the adjacent month collection too.
+
+Normalized audit shape:
+
+- top-level `timestamp`, `month`, `direction`, `transport`, `success`, `component`, `request`, `response`
+- optional `error`, `durationMs`, `referenceId`, `category`
+- `direction` is `INBOUND` or `OUTBOUND`
+- `request` commonly contains `method`, `url`, `uri`, `path`, `queryString`, `headers`, `params`, `body`, `contentType`
+- `response` commonly contains `statusCode`, `contentType`, `headers`, `body`
+
+Investigation rules:
+
+- Use `mcp_firestore_search` to query HTTP audits directly from Firestore when the account has `enableHttpAudits`.
+- Prefer tight filters and low limits. Good filters include:
+  - `direction`
+  - `success`
+  - `request.method`
+  - `request.path`
+  - `component.name`
+  - `response.statusCode`
+- Treat HTTP audits as the best source when the question is:
+  - what exact HTTP request came in
+  - what exact outbound request was sent
+  - what status code or response body came back
+  - whether a Reader or Action actually made the expected HTTP call
+- Do not confuse HTTP audits with business documents. They are audit records stored in Firestore for investigation, not customer data collections like `invoices` or `freight_contracts`.
+- Do not assume every HTTP call will appear. The platform intentionally excludes some paths from HTTP audit persistence, such as configured audit-exclusion endpoints.
+
+How to combine them with the rest of the investigation stack:
+
+- Use `mcp_firestore_search` on business collections to find the affected document.
+- Use `object_id` to pivot into `mcp_object_activity` and lifecycle records.
+- Use `mcp_firestore_search` on the monthly HTTP audit collection to inspect the raw HTTP request/response evidence around the same time.
+- Use component source plus the HTTP audit payload to explain whether the problem is in request formation, partner response, or downstream document processing.
+
+### Record `content` / Context Mental Model
+
+When investigating lifecycle records, treat `content` as the **persisted workflow context**, not as a raw dump of everything that was in memory during execution.
+
+- Runtime component context is the live data a component has available while it is executing.
+- Persisted record context is the sanitized subset written to `Alert.content`, `Event.content`, `Object.content`, and `ObjectLog.content`.
+- Persisted `content` should be assumed to be the platform's intentional investigation-friendly snapshot of that workflow step.
+
+Understand record context this way:
+
+- **Object.content** captures ingestion/request/file context at the time the `Object` was created or updated.
+- **ObjectLog.content** captures `contextForSaving()` from the component that logged the object, so it reflects that component's point-in-time view of the workflow.
+- **Event.content** captures `contextForSaving()` from the component that scheduled the event, plus explicit event options.
+- **Alert.content** captures `contextForSaving()` from the component that raised the alert, plus explicit alert body data.
+
+This is the key investigation question:
+
+- not just "what keys are present?"
+- but "what did the producing component know at that exact workflow step, and what did the platform intentionally keep for persistence?"
+
+### Provenance Fields
+
+Persisted record context should be read with provenance in mind:
+
+- **`source_bcd`** = the immediate component that produced the persisted record context. Example: `[Action:18] DataPlus Invoice Posting`
+- **`upstream_source_bcd`** = the prior workflow hop, when the current component inherited context that already had a `source_bcd`
+- **`object_id`** = execution anchor linking documents and records
+- **`threadGroupingId`** = processing-chain correlation key across records and system logs
+
+Use these fields to reconstruct the path:
+
+1. Identify the record you are inspecting.
+2. Read `source_bcd` to determine the immediate producing component.
+3. If present, read `upstream_source_bcd` to understand the prior workflow hop.
+4. Use `object_id` to open the full object timeline.
+5. Use `threadGroupingId` to correlate related events, alerts, object logs, and system logs.
+6. Open the relevant component source to explain why that component saved that particular context.
+
+### Why Persisted Context Looks Different From Runtime Context
+
+Do not assume missing fields mean the component never had them in memory. Persisted context is deliberately sanitized before save:
+
+- non-serializable runtime objects are removed
+- configured removal keys such as `requestBody`, `params`, and `token` are removed recursively
+- large strings may be summarized instead of stored in full
+- oversized maps/collections may be pruned by serialization limits
+- sensitive-looking keys such as `password`, `secret`, `authorization`, `cookie`, `clientSecret`, and similar values may be redacted
+- Account/User schema fields marked `sensitive: true` may also be redacted before persistence
+
+So if a user asks "why isn't the full payload here?" or "why is this value `[REDACTED]`?", the right answer is usually:
+
+- the workflow may have had the full value at runtime
+- the persisted record intentionally stores only the safe, investigation-friendly subset
+
+When explaining a record, always distinguish between:
+
+- what the workflow likely had at runtime
+- what the platform intentionally kept in persistent `content`
+
+### Investigation Rule for Record Context
+
+Never interpret record `content` in isolation.
+
+Always pair it with:
+
+- the record type (`object`, `object_log`, `event`, `alert`)
+- the immediate producer (`source_bcd`)
+- the upstream producer when present (`upstream_source_bcd`)
+- the object timeline (`object_id`)
+- the execution chain (`threadGroupingId`)
+- the producing component source (`mcp_component_view`, `mcp_component_grep`, or local `/components`)
+
+The goal of an investigation is not only 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**.
+
+### AI Request Response Records
+  - AI activity is also persisted as `AI Request Response` records keyed by `sessionId`.
+  - In component code, use `ai_request_response([sessionId: id])` to load the stored request/response history for a session.
+  - Pass `first: true` or `last: true` when you need a single record.
+  - These records are especially useful during investigations, prompt tuning, and any workflow where you need to review a prior AI exchange or replay a stored provider response in tests.
+  - If a document or agent state already stores a session ID, treat that as a direct pivot into persisted AI session activity.
+
+### AI Session Groupings
+
+- For front-stage investigation and tuning work, use `mcp_ai_session_search` to search persisted AI session groupings and export grouping detail in human-readable form.
+- This tool mirrors the admin AI Groupings UI:
+  - search filters: `search`, `sessionId`, `groupingId`, `user`, `account`, `agent`, `scope`
+  - detail/export sections: `full`, `conversation_messages`, `system`, `response`, `tools`
+- Use it when you need to understand:
+  - what prompts, system instructions, tools, and responses were actually sent for a session
+  - how an Agent behaved across one grouping, including prompt-tuning and tool-usage opportunities
+  - whether a suspicious answer was caused by prompt design, tool definitions, missing context, or model behavior
+- This is a front-stage builder tool, so interpret it alongside the front-stage guides:
+  - `docs/guides/components/agent-components.md` for how Agents are authored and structured
+  - `docs/guides/features/ai-support.md` for the platform AI surface (`ai()`, agent tooling, model behavior, and related patterns)
+- Investigation rule: do not read raw AI session output in isolation. Pair it with the owning Agent component source and the AI support guide so you can explain why the session looked the way it did and where tuning should happen.
+
+### Correlation Keys
+
+- **`object_id`** — links documents to records. Pivot from `mcp_firestore_search` → `mcp_object_activity`.
+- **`threadGroupingId`** — groups all records from the same processing chain. Use with `mcp_system_logs`.
+- **`node`** → resolves to `serviceName` + `region` for log queries.
+
+### 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.
+
+### Repository vs External Context
+| Scenario | Preferred data source | When to call account/component tools |
+|----------|----------------------|--------------------------------------|
+| In the target account repo | Local `account-info.json` and `/components` | Only if files are missing or you need live prod insight not present locally |
+| In Account A repo but question is for Account B | Switch to Account B repo if available; otherwise read its files from disk | If Account B repo isn't available, use `mcp_account_view`, `mcp_component_view`, `mcp_component_grep` for that account |
+| Outside any repo | N/A | Always use the tools to load structure and source |
+
+## Getting Started
+
+### Authentication
+
+Authenticate once per session. Opens the user's browser for OAuth login:
+
+```bash
+remits-cli auth --account-id <ACCOUNT_ID>
+remits-cli auth --account-id <ACCOUNT_ID> --base-url http://localhost:8080
+```
+
+- `--account-id` is auto-resolved from `account-info.json` when you're inside an account repo, so you can usually just run `remits-cli auth`. Pass `--account-id <ID>` explicitly to target a different account (e.g., authenticating into a child account from a parent-account repo) — the explicit flag always wins over the repo's `account-info.json` and any prior session.
+- `--base-url` targets a specific platform instance (e.g., localhost for development). Sessions are stored per account + base URL + data mode, so authenticating against localhost does not overwrite a production session for the same account.
+- If any command returns a 401 error, re-run `remits-cli auth` (with the same `--base-url` if you were targeting a non-default instance).
+
+### Data Mode
+
+Controls whether you work with test data or production data. **Default is `test`.**
+
+```bash
+remits-cli data-mode                  # Show current mode
+remits-cli data-mode set prod         # Switch to prod for investigations
+remits-cli data-mode set test         # Switch back to test for development
+```
+
+## Development Workflow
+
+### The Golden Rule: Writing Code Is Not Finishing the Job
+
+**A change is not complete until it is verified.** Writing or modifying a component is only the first step. You must always confirm the change actually works before telling the user it's done. There are two ways to verify:
+
+1. **Test components** (preferred) — Write or update a Remits Test component that exercises the change. This creates a permanent regression check that protects against future breakage. Run it with `remits-cli test run`.
+
+2. **Visual verification with Playwright** — Generate a browser URL with `remits-cli token`, then use `playwright-cli` to open the embeddable and verify the behavior visually. This is how most users think about verification — "let me see it working."
+
+Both are valid. Use Test components when the behavior can be asserted programmatically. Use Playwright when the change is visual or when the user wants to see it. Often you'll do both.
+
+**Never skip verification.** If the user says "just do it" or "that's fine, commit it" — verify anyway. Silent bugs erode trust. If you can't verify because there's no Test component and no relevant embeddable, tell the user what you'd need to verify and ask how they'd like to proceed.
+
+### The Development Fast Loop
+
+This is how every development task should flow:
+
+#### Step 1: Understand the Request
+Read the user's request. If you may need a repo other than the current one, read `~/.remits-cli/account-repos.json` first. Then review `account-info.json` and `README.md` to understand what components exist and how they relate. Read the source of any component you'll modify before changing it.
+
+#### Step 2: Make the Change
+Edit component files under `components/`. This is local file editing — the platform doesn't know about your changes yet.
+
+#### Step 3: Stage to Platform
+
+```bash
+remits-cli components stage
+```
+
+This uploads your local file changes to the platform's staging cache (Redis, 240-minute TTL). It does NOT commit anything. The platform cannot see your local edits until you stage them.
+
+**THE STAGE-BEFORE-RUN RULE:** You MUST run `remits-cli components stage` after EVERY file edit and BEFORE any test run or verification. The platform executes whatever version is in the staging cache at the moment the test starts. If you edit a file and run a test without staging first, the test runs the OLD code — not your changes. This is the single most common mistake. Never skip staging. The sequence is always: **edit → stage → run**.
+
+This applies to:
+- Creating new components (the platform won't find them until staged)
+- Editing existing components (the platform runs the previously staged version until you re-stage)
+- Every iteration of the fix loop — every edit requires a fresh stage before the next test run
+
+#### Step 4: Verify the Change
+
+**Option A — Run Tests** (if Test components exist for this area):
+
+```bash
+remits-cli test run --test <TEST_ID_OR_NAME>
+remits-cli test run --test "Invoice Tests" --names "specific test case"
+```
+
+Tests run on the platform against your staged snapshot. They stream results in real-time. If they fail, fix the code, re-stage, and re-run.
+
+If no relevant Test component exists yet, consider creating one. Test components live in `components/tests/` and follow the same component structure. They provide permanent regression protection — every test you write today saves debugging time tomorrow.
+
+New test files use the `new_` prefix (e.g., `new_MyTest.groovy`). New tests have no database ID, so you must run them **by name**: `remits-cli test run --test "My Test"`. After committing, the platform assigns an ID and renames the file (e.g., `4_MyTest.groovy`) — then you can run by either ID or name.
+
+**Option B — Visual verification with Playwright** (for UI changes or when the user wants to "see it"):
+
+```bash
+# Generate a browser-accessible URL for an embeddable
+remits-cli token --path embeddable/index/<EMBEDDABLE_ID>
+```
+
+This returns an `embeddableUrl`. Use Playwright to open and interact with it:
+
+```bash
+# Open the embeddable in a headed browser
+playwright-cli open --headed "<embeddableUrl>"
+
+# Take a snapshot to see the current state
+playwright-cli snapshot
+
+# Interact with elements
+playwright-cli click "text=Submit"
+playwright-cli fill "#amount" "500.00"
+
+# Verify specific content
+playwright-cli eval "() => document.querySelector('.total-amount').textContent"
+```
+
+The `testMode` metadata confirms you're testing against staged changes, not production.
+
+**Option C — Use investigation tools** (for backend/data changes):
+
+For changes to Readers, Actions, or Rules that process data rather than display UI, verify by examining the data they produce:
+
+```bash
+# After triggering the component (via test or manual action), check the result
+remits-cli tool --name "mcp_firestore_search" --input '{"accountId": <ID>, "collection": "<collection>", "limit": 5, "sort": [{"field": "_lastModifiedAt", "direction": "DESC"}]}'
+```
+
+#### Step 5: Iterate If Needed
+
+If verification reveals issues, repeat the loop: **edit → stage → run**. Every iteration must include a fresh `remits-cli components stage` after your edits and before the next test run. Never run a test immediately after editing without staging first — the platform will execute the previous version, not your latest changes.
+
+Don't ask the user for permission to re-iterate — just do it. Only stop to ask if you're stuck or unsure about the intended behavior.
+
+If the work is tied to a support ticket:
+- Use `mcp_support_ticket` to mark the ticket `in_progress` once you have started substantive work.
+- If a new reply arrives, re-read the ticket and incorporate the reply into your current plan.
+
+#### Step 6: Update Documentation
+
+Before committing, update metadata so the next session understands what changed:
+
+1. **`.meta.yml` sidecars** — Update `description` and `mermaid` for each modified component.
+2. **`README.md`** — If the change affects account-level capabilities or workflows.
+3. **New components** — Always fill in `.meta.yml` immediately.
+
+`account-info.json` is read-only — never edit it. It regenerates automatically after sync.
+
+#### Step 7: Commit and Sync
+
+Once verified and documented:
+
+```bash
+git add -A
+git commit -m "description of what changed and why"
+git push origin <branch>
+remits-cli components sync
+git pull --ff-only origin <branch>
+```
+
+This separates the failure boundaries cleanly:
+1. Local git commit
+2. Remote push
+3. Server sync from the git remote
+4. Local fast-forward pull of the exact platform-generated commit, including updates such as `account-info.json`
+
+`remits-cli components sync` is the authoritative platform-sync step. It does not perform local git operations.
+
+The CLI now returns the post-sync branch SHA from the platform and verifies that your `git fetch` and final `git pull --ff-only` land on that exact commit. If that SHA does not match `origin/<branch>` or local `HEAD`, stop immediately and investigate the race or branch drift instead of guessing.
+
+`remits-cli components commit` still exists as a convenience wrapper, but agents should prefer the explicit `git -> remits-cli components sync -> git pull` sequence so each phase is observable and retryable on its own.
+
+**Git is required for durable sync.** The platform syncs by pulling from the git remote (`GitHubClient.syncFromRepository`). If `git push` fails, the server has nothing new to sync. You can still **stage** and **test** without git — only durable sync requires it.
+
+#### Step 8: Close the Ticket
+
+If the request came from a support ticket, the task is not complete until you update the ticket lifecycle yourself:
+
+1. Re-read the ticket if needed to confirm the latest state and replies.
+2. If the work is done and verified, call `mcp_support_ticket` with `complete` and include a concise resolution summary.
+3. If you cannot finish, use `update_status` or `release` with clear notes so the next agent can continue.
+4. Do this automatically. The human user should not need to instruct you to update the ticket.
+
+Options:
+```bash
+--message "commit msg"         # Commit message (default: auto-generated timestamp)
+--allow-empty true             # Allow empty git commits
+```
+
+### User Confirmation Preferences
+
+Some users want to review every change before staging. Others want you to move fast and only stop if something breaks. **Pay attention to how the user communicates:**
+
+- If they say "just fix it" or "go ahead" — move through the loop without asking for confirmation at each step. Stage, verify, commit.
+- If they say "show me first" or "wait before committing" — pause at the appropriate step.
+- If they say "you don't need to ask me" or "stop asking" — remember this preference and work autonomously through the full loop.
+
+The default should be: make the change, stage it, verify it, and present the results. Only block on the user when you're genuinely unsure about intent.
+
+## Component Resolution: Staging Cache vs DB (which "version" actually runs)
+
+When the platform executes a component it resolves the source from one of two places, then compiles it
+behind an in-memory cache. Understanding this is the difference between "my change isn't working" guesses
+and a precise diagnosis.
+
+### The two source layers + the compile cache
+
+1. **CLI staging cache (Redis, 240-min TTL).** Branch + user + account scoped overrides written by
+   `remits-cli components stage` and by the `mcp_component_edit` tool (`mode:'stage'`). These shadow the DB
+   source **only during CLI/test-mode execution** (see "When staged overrides apply" below).
+2. **Database (the committed live component).** What `mcp_component_view` reads, what a pure prod run uses,
+   and what `commit` writes to.
+3. **Compiled-closure cache (`BaseClosureDomain.CLOSURE_CACHE`).** An in-memory, **per-JVM-instance** Guava
+   cache of the parsed closure, keyed by `(componentId, type, compileSignature)`. This is why a change that
+   is correctly in the DB can still execute stale on a running instance — see "Stale after sync" below.
+
+### Staging cache key format
+
+```
+account:<accountId>:cli:<cliUserId>:components:<branch>:<family>:id:<componentId>
+account:<accountId>:cli:<cliUserId>:components:<branch>:<family>:name:<normalizedName>
+```
+
+`<family>` is the lowercased component family (`reader`, `action`, `test`, `embeddable`, ...). Both an
+`id:` and a `name:` key are written per stage. The entry value carries: `kind` (the family), `type` (the
+component's OWN type enum such as `ObjectType`/`RuleType`, or absent — **never** the family), `hash`,
+`updatedAt`, and the staged content field(s) (`source`/`prompt`/`html`/`javascript`/`schema`/
+`inputSchema`/`previewData`/`path`).
+
+### How the platform picks staged vs DB (the compile signature)
+
+At compile time the platform computes a **signature** that tells you which layer won:
+
+- Staged override present → `compileSignature = "cli:<hash>"` (the staged content hash).
+- No staged override → `compileSignature = "version:<N>"` (the DB row version).
+
+That signature is logged. Querying for it is the single most reliable way to know what ran:
+
+```bash
+remits-cli tool --name mcp_system_logs --input '{"node":"remitsAdmin-east5","timeRange":"1h","filter":"textPayload:\"Using Cached BCD\""}' --data-mode prod
+```
+
+`Using Cached BCD [ID: 230, Type: Action, Signature: cli:08cc...]` → ran a **staged** override.
+`...Signature: version:37]` → ran the **committed DB** version.
+
+### When staged overrides apply
+
+Staged overrides resolve **only when the execution carries a CLI TestMode** — i.e. `TestMode.branchName`
+and `TestMode.cliUserId` are set (a `remits-cli test run`, a `mcp_run_test`, or a tokenized run minted with
+those). A **pure production run with no TestMode always uses the DB source**, ignoring staging entirely. So
+"I staged it but the live webhook still runs the old code" is expected — staging is a dev/verification
+surface, not a deploy.
+
+### Diagnosing which version is in play
+
+- **See staging metadata for a component:** `mcp_component_view` (omit `fieldName`) returns `staging` /
+  `stagedFields`, telling you whether a staged entry exists and which fields are staged.
+- **Inspect the raw staged entry + TTL in Redis:** use `mcp_cache`.
+  ```bash
+  # find staged entries for one component
+  remits-cli tool --name mcp_cache --input '{"action":"scan","pattern":"account:52:cli:*:components:*:reader:id:181","includeValuePreview":true}' --data-mode prod
+  # dump one exact key
+  remits-cli tool --name mcp_cache --input '{"action":"inspect","key":"account:52:cli:23:components:main:reader:id:181"}' --data-mode prod
+  ```
+  The preview shows `kind`/`type`/`hash`/`updatedAt` + a source snippet — confirm it's your content and
+  that `type` is NOT the family (a family value in `type` is a tool bug that crashes hydration, e.g.
+  `No enum constant ObjectType.reader`).
+- **Confirm the DB version:** `mcp_component_view` reads the live DB source directly (no staging, no compile
+  cache), so it is the source of truth for "what was committed."
+
+### Stage / commit / clear with the MCP tools
+
+- `mcp_component_edit` `mode:'stage'` → writes the staging cache (Redis). `mode:'commit'` → writes the field
+  to the **live DB** and **clears** that component's staging entries. `editMode:'replace'` swaps the whole
+  field; `editMode:'targeted'` does anchor-verified line edits.
+- `mcp_component_commit` (`read`/`commit`/`clear`) enumerates staged entries and can flush or clear them.
+- **Commit bypasses the staged-override path entirely** (it writes the DB and clears staging), so committing
+  is the way to make a change durable and to stop a stale staged entry from shadowing the live component in
+  later test runs.
+
+### Stale after sync / commit (the in-memory compile cache)
+
+After a `git sync` or a `commit` updates the DB source, a **running instance can keep executing the
+previously-compiled closure** until the version-keyed signature changes and that instance's
+`CLOSURE_CACHE` misses (or the instance recycles). Symptoms: `mcp_component_view` shows the new source, but
+behaviour (or a freshly-staged entry produced by an edited *tool*) still reflects the old code. This is the
+standard Grails no-hot-reload caveat — it is environmental, not a code defect. Verify the live entry/source
+with `mcp_cache` / `mcp_component_view`, and if a platform/tool source change must take effect immediately,
+the platform owner recycles the instance.
+
+## 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_system_logs` — correlate via `threadGroupingId` for execution traces.
+9. `mcp_component_view`/`mcp_component_grep` — explain how the responsible component works.
+
+**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 `docs/guides/features/ai-support.md`.
+
+### Presenting Findings
+
+Users are not engineers. When reporting investigation results:
+- Lead with what happened in plain language.
+- Show the evidence (document values, timeline events, log excerpts).
+- Explain why it happened if you can determine the cause.
+- Recommend what to do next — in terms the user can act on.
+
+### Verifying a Production Issue Fix
+
+When a bug is reported from production, use this pattern:
+
+1. Investigate the live issue in **prod mode** and identify the exact affected document IDs, collection names, account IDs, and component path.
+2. Make the code change in the owning `PLATFORM` or `PRODUCT` repo when the defect is in shared implementation.
+3. Verify in **test mode**, not prod.
+4. Prefer a **Test component** when the behavior can be asserted programmatically, because that creates a durable regression suite and lets you explicitly construct the necessary data, operations, and assertions.
+5. Use `remits-cli token` plus `playwright-cli` when the proof is visual or interaction-driven.
+6. If useful, create or update a dedicated embeddable "playground" in test mode to reproduce the scenario in a controlled way.
+
+Do not move production customer data into another account's test collection as a routine verification strategy. If you cannot verify with a Test component, Playwright flow, or controlled test-mode embeddable, explain the gap clearly instead of improvising with live production validation.
+
+## Tool Reference
+
+### Execute a Tool
+
+```bash
+remits-cli tool --name "mcp_firestore_search" --input '{"accountId": 37, "collection": "invoices"}' --data-mode prod
+```
+
+Response saved to `./.remits-cli/tool-responses/<callId>.json`. Read the file to see results.
+
+**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.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `accountId` | yes | Account ID |
+
+### `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 |
+
+HTTP audit usage notes:
+
+- Use this same tool for monthly HTTP audit collections:
+  - `http-audits/http-audits-YYYY-MM/entries`
+- Example investigation query:
+
+```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
+```
+
+- For Reader webhook investigations, commonly filter on:
+  - `direction = INBOUND`
+  - `request.method`
+  - `request.path`
+  - `response.statusCode`
+- For outbound integration investigations, commonly filter on:
+  - `direction = OUTBOUND`
+  - `component.name`
+  - `request.path` or `request.url`
+  - `response.statusCode`
+  - `success`
+
+### `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) |
+| `activityOptions` | no | `{limit, offset, types, start, end, order}`. Default: limit=5, order=desc. Types: `OBJECT_LOG`, `EVENT`, `ALERT`. |
+
+### `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:
+- `docs/guides/components/agent-components.md`
+- `docs/guides/features/ai-support.md`
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `action` | no | `search` (default) or `detail` |
+| `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` |
+| `page` | no | 1-based page number. Default: `1` |
+| `pageSize` | no | Results per page. Default: `25`, max: `100` |
+| `recordIds` | no | Optional request/response record IDs to export from the selected grouping |
+| `parts` | no | Export sections: `full`, `conversation_messages`, `system`, `response`, `tools` |
+| `sections` | no | Alias for `parts` |
+| `consolidateContext` | no | When `true`, collapses repeated XML-like prompt context into a consolidated section |
+
+Use `action: "search"` first, then `action: "detail"` with the returned `groupingKey` when you want the human-readable export for investigation or tuning.
+
+### `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) |
+| `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_component_view`
+Read component field content with line numbers.
+
+| 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 |
+
+### `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` | yes | The account that owns the support ticket |
+| `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) |
+| `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` |
+| `status` | no | Required for `update_status`. Valid values: `in_progress`, `pending_review` |
+| `resolution` | no | Required for `complete` |
+| `category` / `summary` / `details` / `findings` / `nextStep` | no | Worklog fields for `record_progress` (`category` + `summary` required) |
+| `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:**
+1. `read` with the ticket's `accountId` — check ticket state and any attachments
+2. `accept` with the ticket's `accountId`
+3. `get_attachment` if attachments are present and relevant to the investigation
+4. `update_status` with the ticket's `accountId`
+5. investigate/fix/verify on the owning ticket account or its implementation account as appropriate
+6. `complete` or `release` with the ticket's `accountId`
+
+**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
+
+### `mcp_run_test`
+Execute a Test component.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `accountId` | yes | Account ID |
+| `testId` | yes | Test component ID |
+| `testNames` | no | Array of specific test case names |
+
+### `mcp_component_edit`
+Edit a component field, server-side, with stage or commit semantics. The agent counterpart to local file
+edit → `remits-cli components stage`. Useful for components that don't live in the local repo (e.g.
+auxiliary components). See "Component Resolution" for stage-vs-DB behavior.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `accountId` | yes | Account ID of the component |
+| `componentType` | yes | `Schema`/`Reader`/`Action`/`Embeddable`/`HtmlTemplate`/`Rule`/`Agent`/`Test`/`Tool`/`Prompt` |
+| `componentId` | yes | Component ID |
+| `fieldName` | yes | Field to edit (`source`, `html`, `javascript`, `schema`, `inputSchema`, `previewData`, `path`; metadata fields like `description`/`mermaid` require `mode:'commit'`) |
+| `mode` | no | `stage` (default, Redis 240-min TTL) or `commit` (write live DB + clear staging) |
+| `editMode` | no | `targeted` (default, anchor-verified line edit via `lineStart`/`lineEnd`/`anchorContent`/`newContent`) or `replace` (full-field `newContent`) |
+| `auxiliary`/`category`/`partnerSlug` | no | Companion metadata applied alongside the edit |
+
+### `mcp_component_commit`
+Inspect, flush, or clear the CLI staging cache for components.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `accountId` | yes | Account ID |
+| `action` | yes | `read` (list staged entries), `commit` (flush staged → DB), or `clear` (drop staged entries without touching the DB) |
+
+### `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 `mcp_component_commit clear`
+to remove staged 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 |
+
+## Multi-Session Support
+
+The CLI supports multiple authenticated sessions simultaneously. Sessions are stored in `~/.remits-cli/sessions.json` as a map keyed by `accountId + dataMode + baseUrl`, so the same account can stay authenticated against both localhost and production without one session overwriting the other. When you run any command from an account repo, the CLI automatically resolves the best matching session based on the `account-info.json` in that directory and any `--base-url` or `--data-mode` flags provided.
+
+```bash
+# Authenticate for an account (run from its repo, or pass --account-id)
+remits-cli auth
+remits-cli auth --account-id 42
+remits-cli auth --account-id 42 --base-url http://localhost:8080
+
+# List all active sessions
+remits-cli sessions list
+
+# Remove a session (removes all sessions for the account, or narrow with --base-url / --data-mode)
+remits-cli sessions remove --account-id 42
+remits-cli sessions remove --account-id 42 --base-url http://localhost:8080
+```
+
+You can work in multiple account repos simultaneously across different terminal windows — each uses its own session. You can also be authenticated against different base URLs (e.g., localhost for development and production) for the same account at the same time.
+
+## Persistent Service, Control Center, and Agent Dispatch
+
+The current mental model is a **background remits-cli service**, not just a listener.
+
+That service does three jobs:
+- Maintains persistent WebSocket connections to the Remits platform
+- Manages tmux-based agent dispatch for inbound `remits-cli` support messages
+- Hosts a localhost browser **control center** that shows the full local integration state
+
+### Starting the Service
+
+```bash
+remits-cli start
+remits-cli start --foreground true
+remits-cli status
+remits-cli stop
+```
+
+Compatibility aliases still exist:
+
+```bash
+remits-cli listen
+remits-cli listen status
+remits-cli listen stop
+```
+
+The service:
+- Scans the machine for `account-info.json` files and rebuilds `~/.remits-cli/account-repos.json`
+- Maintains one WebSocket connection per unique platform URL across all sessions
+- Subscribes to topics for every authenticated account
+- Handles `TestSuite` messages (test results) and `remits-cli` messages (agent dispatch)
+- Reconnects automatically if the connection drops
+- Uses a PID lock file (`~/.remits-cli/listener.pid`) to ensure only one service per machine
+- Writes `~/.remits-cli/service-state.json` so agents can discover the dashboard URL and current runtime status
+
+### Control Center
+
+`remits-cli start` should provide a localhost URL such as `http://127.0.0.1:8787/`.
+
+The control center is the fastest way to understand the whole integration surface in one browser view. It shows:
+- whether the remits-cli service is running
+- the current dashboard URL and port
+- websocket connection and topic health
+- tmux availability, session state, and tracked panes
+- the discovered account repo index
+- the important global JSON/log files
+- the important per-repo remits-cli files for every indexed account repo
+
+When a user asks a broad or vague question about remits-cli behavior, prefer opening or reasoning from the control center state before spelunking random files individually.
+
+### Agent Dispatch
+
+All dispatched agents run as **panes** within a single tmux session named `remits-listener`. This gives the user a single window where they can see and interact with all active agent workstreams side by side.
+
+When a `remits-cli` WebSocket message arrives from the platform:
+
+1. The message's `accountId` is used to look up the account's local directory from the account repo index
+2. If the message has a `ticketId` that already has an active pane, the new message is **delivered to the existing pane** (the agent receives the follow-up in-context)
+3. If no pane exists for the `ticketId`, a new pane is **split into the `remits-listener` tmux session**, running the preferred AI coding agent with the message prompt at the account's directory
+4. Panes are automatically tiled for a clean layout
+
+**Ticket tracking:** Each support-ticket message should include a `ticketId`. The listener maps ticket workstreams to tmux pane IDs so follow-up messages for the same ticket are routed to the same agent session. Legacy payloads that only include `taskId` are still supported as a fallback. If the pane has been closed, a fresh pane is created.
+
+**Inspecting activity:** Use `tail -f ~/.remits-cli/tmux-activity.log` to watch service start/stop, WebSocket subscriptions, ticket dispatch receipt, pane creation, follow-up delivery, and failures.
+
+**Interacting with agents:** Attach to the tmux session to see all active agents:
+```bash
+tmux attach -t remits-listener
+```
+Use standard tmux navigation (`Ctrl-b` + arrow keys) to switch between panes.
+
+### Configuring the Preferred Agent
+
+```bash
+remits-cli config                    # Show current config
+remits-cli config set --agent claude # Use Claude Code (default)
+remits-cli config set --agent codex  # Use OpenAI Codex CLI
+remits-cli config set --agent gemini # Use Gemini CLI
+```
+
+The agent preference is stored in `~/.remits-cli/config.json` and applies globally.
+
+## Local State Files
+
+**Global** (`~/.remits-cli/`):
+- `sessions.json`
+  - Source of truth for authenticated account sessions, keyed by `accountId + dataMode + baseUrl` so the same account can hold separate sessions for different environments (e.g., localhost vs production).
+  - Each entry contains auth token, user info, websocket topic, data mode, base URL, and timestamp.
+  - Read this when a question involves auth, account selection, websocket topic coverage, or which session a command should resolve.
+- `config.json`
+  - Global CLI preferences.
+  - Currently most important for preferred agent selection, but treat it as the general machine-level config file.
+- `service-state.json`
+  - Runtime snapshot for the currently running remits-cli service.
+  - Includes dashboard URL, chosen port, repo-discovery summary, and websocket connection state.
+  - This is the first file to read when the user asks "is remits-cli running?", "what port is the dashboard on?", or "why isn't the browser page showing my connections?"
+- `account-repos.json`
+  - Index of all known account repositories on this machine.
+  - Built from `account-info.json` discovery plus best-effort updates when commands run inside an account repo.
+  - This is the repo-resolution file. Read it before deciding that a repo is unavailable locally.
+- `listener.pid`
+  - PID of the background remits-cli service process.
+  - Use it only to confirm process presence; use `service-state.json` for richer service details.
+- `dispatch-panes.json`
+  - Maps active ticket routing keys (`ticket:<id>` or legacy `task:<id>`) to tmux pane IDs.
+  - Read this when follow-up messages appear to route to the wrong pane or when panes are being recreated.
+- `tmux-activity.log`
+  - Human-readable chronological event log for service lifecycle, websocket events, tmux actions, and dispatch behavior.
+  - This is usually the best forensic file for "what happened?" questions.
+
+**Per-repo** (`./.remits-cli/`):
+- `tools/tools.json`
+  - Cached tool definitions for this repo context.
+  - Read this when tool availability or input shape is unclear.
+- `sessions/<name>.jsonl`
+  - Repo-local HTTP request/response log for `/cli/*` calls.
+  - Tokens are redacted and large content fields are summarized.
+  - This is the first file to inspect when the question is "what exactly did remits-cli send or receive from this repo?"
+- `tool-responses/<callId>.json`
+  - Full payload for `remits-cli tool` responses that were too large for the session log.
+  - Prefer this over terminal summaries when investigating tool behavior.
+- `current-session.txt`
+  - Pointer to the active repo-local session log name.
+  - Always read this before opening `sessions/<name>.jsonl`.
+
+Reading rules:
+- Read `current-session.txt` before opening a session log by name.
+- When a tool call says the response was stored externally, open `tool-responses/<callId>.json` instead of inferring from the terminal summary.
+- If a question spans both global and repo-local behavior, inspect both layers and explain which facts came from which layer.
+
+## Command Reference
+
+```
+remits-cli auth [--base-url URL] [--account-id ID] [--data-mode test|prod]
+remits-cli sessions [list|remove] [--account-id ID]
+remits-cli config [set] [--agent claude|codex|gemini]
+remits-cli start [--foreground true] [--port 8787]
+remits-cli stop
+remits-cli status
+remits-cli listen [stop|status] [--foreground true]   # compatibility alias
+remits-cli data-mode [set test|prod]
+remits-cli components stage [--branch <name>] [--data-mode test|prod]
+remits-cli components sync [--branch <name>] [--data-mode test|prod]
+remits-cli components commit [--message "msg"] [--data-mode test|prod]
+remits-cli test run --test <id|name> [--names "a,b"] [--watch true|false] [--data-mode test|prod]
+remits-cli token [--path <embeddablePathOrId>] [--data-mode test|prod]
+remits-cli tools [--data-mode test|prod]
+remits-cli tool --name <toolName> [--input "{...}"] [--data-mode test|prod]
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| 401 or `Not authenticated` | Run `remits-cli auth` |
+| `account-info.json not found` | Run from the account repo root |
+| Test not found (404) | New component not staged yet. Run `remits-cli components stage` first. For new tests (no ID), run by name not ID. |
+| Stage shows 0 updated | No changes since last stage (hash dedup) |
+| Test runs old code after edit | You forgot to stage. Run `remits-cli components stage` THEN re-run the test. The platform runs whatever was last staged, not your local files. |
+| "Git credentials" or `git push` error | Git auth is required for commit (server pulls from git remote). Fix git authentication (SSH keys or HTTPS credentials) before retrying. Staging and testing still work without git. |
+| 500 / `Internal Server Error` from Remits | Stop normal task work. Capture the exact command, error, and response artifact, then escalate to a Remits system admin. Do not invent a workaround. |
+| Tool parameters rejected | Tool schemas may be cached. Run `remits-cli tools` to refresh `.remits-cli/tools/tools.json` with latest schemas. |
+| Tool response missing | Check `./.remits-cli/tool-responses/` |
+| Staged change has no effect in a live (non-test) run | Staged overrides resolve only under a CLI TestMode (`branchName`+`cliUserId`). A pure prod run always uses the DB. `commit` to make it durable. See "Component Resolution". |
+| New source shown by `mcp_component_view` but old behavior persists after sync/commit | In-memory compile cache (`CLOSURE_CACHE`, version-keyed, per instance) still holds the prior closure. Environmental; the platform owner recycles the instance. |
+| Staged Reader test run throws `No enum constant ObjectType.<family>` | The staged entry has the component family in `type` (should be `kind`). Clear + re-stage; if it persists, the `mcp_component_edit` tool on that instance is on an old/cached version. Inspect with `mcp_cache`. |
+| Unsure whether a run used staged vs DB source | Query `mcp_system_logs` for `Using Cached BCD` — `Signature: cli:<hash>` = staged, `version:<N>` = DB. |
+| Service already running | Run `remits-cli status` to get the dashboard URL, or `remits-cli stop` before restarting. |
+| tmux not installed | Install tmux (`brew install tmux` on macOS). Required for agent dispatch. |
+| Control center URL unknown | Read `~/.remits-cli/service-state.json` or run `remits-cli status` |
+| Dashboard missing repos | Rebuild `~/.remits-cli/account-repos.json` with `remits-cli start` or the control center rescan action |
+| Agent dispatch to wrong directory | Check `~/.remits-cli/account-repos.json` has the correct directory and that you resolved the account type correctly. A `CLIENT` ticket may still belong to a parent `PLATFORM` or `PRODUCT` repo for code changes. |
+
+### When Something Doesn't Work as Expected
+
+All `remits-cli` capabilities (staging, test execution, committing, tool calls) have been tested and confirmed to work correctly. The most common issues are operational mistakes like forgetting to stage before running tests.
+
+However, the Remits **platform itself** may have bugs or gaps that prevent certain behavior from working. If you've followed the correct workflow (edit → stage → run) and something still doesn't behave as expected after 2-3 attempts, **do not keep trying workarounds.** First decide which kind of problem it is:
+
+- **A `remits-cli` / tooling operational issue** (staging, sync, dispatch, listener, the CLI itself misbehaving) → use the escalation-bundle path below and ask the user to escalate to a Remits system admin.
+- **A Remits back-stage platform defect or limitation** (the component runtime behaves wrong: Hibernate/session/optimistic-locking errors, detached-entity surprises, brittle lifecycle/tool behavior, a DSL method diverging from its guide) → run the **Back-Stage Escalation Workflow** below. Do **not** normalize it into a front-stage workaround.
+
+Also apply the boy-scout rule to the guides themselves: **whenever you only solved the problem by reading the core back stage because a front-stage guide was unclear or missing — even if there was no platform defect at all — open a guide-only PR** updating the relevant `docs/guides/` guide so the next agent can succeed from the front stage. Better guides over time are an explicit goal.
+
+#### Back-Stage Escalation Workflow (platform defect/limitation)
+
+The core Remits platform repo is cloned on this machine and tracked in `~/.remits-cli/account-repos.json` under the reserved **`platform`** entry (default `~/remits`, or `REMITS_PLATFORM_DIR`). Use it:
+
+1. **Analyze the back stage locally.** Open the platform repo and read every seam on the failing path — `src/main/groovy/remits/domain/BaseClosureDomain.groovy`, `src/main/groovy/remits/GormUtils.groovy`, the relevant controller/service/client, and `docs/back-stage-session-resilience.md` / `CLAUDE.md`. Map the runtime-compiled class name in any stack trace (`{componentType}_{componentId}_...`) back to the failing line, then trace it into the platform code to find the true root cause.
+2. **Propose the fix as a PR — and improve the guides (boy-scout rule).** Create a **feature branch** in the platform repo and open a **pull request** with the recommended back-stage fix that honors the resiliency contract (front stage stays clean; add/extend a reproducing spec or Test Account suite where it applies). The front-stage guides live in `docs/guides/` in that same repo and are the source of truth served to every account repo via `/cli/guides`, so the PR should **also** update the relevant component/feature guide whenever you had to read the back stage because the guides didn't make the answer obvious — document the new behavior for a real limitation, or fix the unclear/missing guidance even when no platform code changed (a guide bug is still a bug). **Do not merge it yourself.**
+3. **Raise a support ticket** with `mcp_support_ticket` `action:'create'` (`type:'defect'` for brittleness or `'enhancement'` for a gap). Include the subject, the seam, the evidence, and the PR; set `affectedComponent`, `priority`, and `implementationAccountId`/`implementationAccountName` for the owning `PLATFORM`/`PRODUCT` account. Use `record_progress`/`add_artifact` to attach the diagnosis and supporting evidence.
+4. **Tell the user about the PR** and the ticket so a Remits engineer can review and decide whether to approve and merge.
+
+#### Escalation Bundle (tooling/operational issue)
+
+1. **Create a single escalation bundle under `~/.remits-cli/issues/`.**
+   Use a directory name like:
+   - `~/.remits-cli/issues/<timestamp>-account-<accountId>-<short-slug>/`
+
+   Populate that directory with enough information that the user or a Remits system admin can continue without re-running your work. Include at minimum:
+   - `summary.md`
+     - What you were trying to do
+     - Why you were trying to do it
+     - The expected behavior
+     - The actual behavior
+     - The exact commands you ran, in order
+     - The key error messages or unexpected outputs
+     - Whether the failure blocks staging, testing, sync, ticket routing, listener dispatch, or production investigation
+   - `context.json`
+     - `cwd`
+     - target repo directory
+     - `accountId`
+     - account name
+     - account `type`
+     - branch name
+     - current data mode
+     - ticket ID if applicable
+     - component names / IDs involved
+   - Copies or references for the relevant supporting artifacts:
+     - `./.remits-cli/current-session.txt`
+     - the active repo session log from `./.remits-cli/sessions/`
+     - any `./.remits-cli/tool-responses/<callId>.json` files involved
+     - `~/.remits-cli/account-repos.json` if repo resolution may be relevant
+     - `~/.remits-cli/tmux-activity.log` if listener / websocket / dispatch behavior may be relevant
+
+2. **Use the global Remits CLI state to make the bundle self-contained.**
+   - Read `./.remits-cli/current-session.txt` to identify the active repo session log.
+   - Record the exact repo directory and account context from `account-info.json`.
+   - If repo selection or account targeting may be part of the issue, include the relevant entry from `~/.remits-cli/account-repos.json`.
+   - If the problem involves support-ticket delivery, tmux panes, or websocket events, include the relevant lines from `~/.remits-cli/tmux-activity.log`.
+   - If a tool call stored its full response externally, include that file path and summarize the important fields in `summary.md`.
+
+3. **Stop and document the issue clearly for the user.**
+   Tell the user where the escalation bundle lives and summarize:
+   - what was attempted
+   - what should have happened
+   - what actually happened
+   - why this appears to require a Remits system admin
+
+4. **Ask the user to escalate to a Remits system admin.** The system admin has access to the Remits platform codebase and the `remits-cli` source code, and can diagnose and fix platform-level issues directly.
+
+5. **Do not attempt creative workarounds** (renaming components, duplicating files, bypassing the CLI with raw API calls, etc.). If the platform has a real bug, workarounds mask the problem and make it harder to diagnose. It is better to have the issue fixed at the source than to build fragile workarounds around it.