@remits/remits-cli 0.1.113 → 0.1.115

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

@@ -0,0 +1,483 @@
+# Support Tickets
+
+> A `remits-cli` skill reference. **Load this when** a ticket is part of the request, you are registering to work tickets, or you are the worker inside an autonomous ticket run.
+>
+> The table of contents below carries **real line numbers** (`- L84  Some Heading`), resolved when
+> this file is installed, so they are never stale. Read the head, pick your sections, and offset-read
+> only those. The entry text is the heading verbatim, so it also greps.
+
+## Table of Contents
+
+- [Support Ticket Mental Model](#support-ticket-mental-model)
+  - [You are an agent, and you register yourself](#you-are-an-agent-and-you-register-yourself)
+  - [Autonomous: one ticket, one process](#autonomous-one-ticket-one-process)
+  - [Serving only some workstreams](#serving-only-some-workstreams)
+  - [The manual loop](#the-manual-loop)
+  - [If you are the worker](#if-you-are-the-worker)
+  - [Before you edit anything: where you are, and whether you may](#before-you-edit-anything-where-you-are-and-whether-you-may)
+  - [Your account's process is binding, and it is already in your brief](#your-accounts-process-is-binding-and-it-is-already-in-your-brief)
+  - [Some of that process is enforced, not requested](#some-of-that-process-is-enforced-not-requested)
+  - [Seeing the queue as a human does](#seeing-the-queue-as-a-human-does)
+  - [Agent components are workers too](#agent-components-are-workers-too)
+  - [Moving a ticket through its lifecycle](#moving-a-ticket-through-its-lifecycle)
+  - [When a worker needs a decision from a human](#when-a-worker-needs-a-decision-from-a-human)
+
+## Support Ticket Mental Model
+
+Support tickets are a **first-class platform capability**, not an account convention. Every Remits
+account reads and writes the `support_tickets` collection without owning a Schema, tickets are anchor
+`Object`s on the account the work belongs to, and the lifecycle vocabulary is defined once in the
+platform.
+
+**The platform is deliberately not the standard for ticket workflow.** Different Remits
+platforms and products integrate with different systems — Zendesk, Jira, a customer's own portal —
+and each end client has its own rules for how tickets move. Remits owns the *record* and the *verbs*;
+each front-stage platform builds its own workflow on top through its own Embeddables, Rules, and
+Actions. So what you see through `remits-cli` is the shared record underneath every one of those
+workflows, and never one product's view of it.
+
+### You are an agent, and you register yourself
+
+**If the user says anything like "register to become a support agent", or "work support tickets",
+run exactly this and nothing else first:**
+
+```bash
+remits-cli agent serve
+```
+
+No flags, no setup, **no need to be in an account repo** — run it from wherever the session started.
+It registers this terminal for every account repo indexed on this machine that your user can reach,
+against the production platform and the production lane, and then **starts working tickets on its
+own**. It returns immediately; a background supervisor does the rest.
+
+Use `remits-cli agent register` instead **only** when the user wants presence without autonomy — a
+human, or you in this very tab, will work the tickets by hand. Registering alone starts nothing: it
+makes the session routable and then waits to be asked.
+
+Three tabs running an agent are three agents. Each is independently routable, each reports its own
+activity, and each stops receiving work when its tab closes — a heartbeat anchored to the session dies
+with it, so a crashed agent and a quit agent look identical to the platform.
+
+**Nothing is pushed at you.** A terminal mid-task cannot receive a push, so delivery is you asking.
+That is why the routing decision is a durable field on the ticket rather than a message: you can
+restart this terminal, register again, and the work is still there.
+
+Two facts about a ticket are separate and must stay separate:
+
+| Fact | Field | Means |
+|---|---|---|
+| **Routed** | `routedAgentId` | which agent session should pick this up — delivery |
+| **Claimed** | `claimedAgentId` | a worker process is running on it *right now* |
+| **Owned** | `assignedTo` | who has claimed it — accountability |
+| **Status** | `status` | where it is in the workflow |
+
+A ticket routed to you is not yet yours. Claim it with `accept`, and the queue then shows it owned.
+
+The **claim** is the supervisor's, not yours — it exists so two workers never start on one ticket,
+and it expires on its own so a killed worker cannot park a ticket forever. You do not manage it.
+
+### Autonomous: one ticket, one process
+
+```bash
+remits-cli agent serve                          # workers are whichever agent THIS session is
+remits-cli agent serve --worker-agent codex --max-concurrent 2
+remits-cli agent serve --mode investigate       # read-only workers: no file edits
+remits-cli agent serve --serves support,sdlc    # only these workstreams are routed here
+remits-cli agent workers                        # what is running right now
+remits-cli agent release                        # stop serving, go offline
+```
+
+`--mode investigate` is still autonomous ticket work. The supervisor claims a ticket, launches a
+worker, and the worker should read/reproduce/localize the issue and update the ticket with useful
+findings or a handoff. What it must **not** do is become the repository editor: investigation-mode
+polls do not acquire or renew the repo edit lease, and the brief explicitly forbids file edits,
+component staging, commits, and `remits-cli ticket lease`.
+
+**Run it in a plain terminal tab.** That tab becomes the agent host: `serve` returns immediately, a
+detached supervisor is anchored to the tab's shell, and closing the tab stops the agent. Nothing in
+that tab is an AI session — the AI only ever appears as the worker processes the supervisor spawns.
+
+Starting it from inside an AI session works too and self-detects the worker kind, but it is the
+lesser setup: it parks an interactive session as a heartbeat holder while its workers do the work.
+
+When a ticket is routed to this session, the supervisor launches **a fresh headless agent process
+for that ticket**, in that account's repo, with a brief the platform generates. That process exits
+when the ticket is done.
+
+**One ticket = one process is the point, and it is why nothing here ever needs `/clear`.** Context
+grooming cannot be a discipline: `/clear` and `/new` are commands a *human types into a TUI*, and no
+model can invoke them — so a long-lived session working ticket after ticket has no way to reset
+itself. A process that exits has nothing to reset. Do not try to solve context growth by being tidy
+inside one session; let the session end.
+
+**`serve` returns immediately, and that is correct.** Do not follow it with a wait, a poll, or a
+loop. The supervisor is detached precisely so this tab is free. Report that you are serving and
+stop; you have not left the job half done.
+
+What the supervisor handles for you, so you do not have to think about any of it: collecting routed
+work, claiming each ticket so no second worker starts on it, renewing that claim while the worker
+runs, reporting the worker's activity to the dashboard, dropping the claim when it exits, retrying a
+failed ticket once, and releasing a ticket back to the queue when it has failed too often. Closing
+the terminal stops everything and hands any in-flight work back.
+
+### Serving only some workstreams
+
+`--serves` declares which of the account's **workstreams** this machine covers, so a fleet can be a
+set of queues rather than a pool of interchangeable machines:
+
+```bash
+remits-cli agent serve --serves support,incident --mode investigate   # the support desk box
+remits-cli agent serve --serves sdlc --max-concurrent 2               # the engineering box
+```
+
+The names are the account's own — the platform compares them and learns nothing about any of them.
+Read `remits-cli ticket queue --workstream ...` or the account's `OPERATIONS` prompts to find out
+what this account calls its processes; do not invent names.
+
+**Omit it unless the user asked for it.** A session that declares nothing is a generalist and takes
+everything, which is the right default and what every existing fleet does. Specialising has a real
+cost: a specialist is only routed tickets in its workstreams *and its unrouted sweep takes only
+those*, so a workstream no live session covers is routed to nobody. The platform reports that rather
+than quietly overriding the declaration —
+
+- `dispatch` answers `reason: 'no_agent_serves_workstream'` and names what the live sessions do cover;
+- `agent map` prints each session's declared queues;
+- the supervisor logs `serve.out_of_scope` when it passes over unrouted work it does not serve.
+
+**So after specialising a fleet, run `remits-cli agent map`** and confirm every workstream the
+account ingests is covered by something.
+
+### The manual loop
+
+Only when the session registered with `agent register` rather than `agent serve`.
+
+```bash
+remits-cli agent work --wait 600                    # returns as soon as work arrives
+remits-cli agent status --state working --ticket 22454 --activity "reproducing the upload failure"
+# ... investigate, fix, verify — keep `status` current as what you are doing changes ...
+# ... close the ticket lifecycle through remits-cli ticket (accept -> status -> complete, ask, or release) ...
+remits-cli agent status --state idle                # then ask for work again
+```
+
+**Nothing wakes this tab.** A routed ticket sits there until someone in this session asks for it, so
+if you are working the manual loop you have to keep asking. If you find yourself wishing you could
+be woken up, that is what `agent serve` is.
+
+**Report what you are doing.** `agent status` is how an operator watching the dashboard, or another
+agent, knows this session is alive and what it is on. It costs one command and it is the difference
+between a visible queue and a silent one. Update it when you change what you are doing, not on a
+timer.
+
+**Work the ticket in the right repo.** A ticket names its `accountId`, and often an
+`implementationAccountId` — the platform/product account whose repo holds the code. Resolve that to a
+local directory through `~/.remits-cli/account-repos.json` and `cd` there before making changes. You
+registered from anywhere; you do not fix anything from anywhere.
+
+For subscriber/fork tickets, this is also the investigation starting point. The reporting account may be
+the fork or client that observed the issue, while `implementationAccountId` names the repo whose branch
+contains the front-stage source. Read the ticket, run/inspect the run context (`ticket where` when useful),
+open the indexed implementation repo, then establish the relevant branch's steady starting state before
+the first edit: fetch origin, fast-forward the branch, and confirm local and remote have no commits missing
+from either side. Then read `account-info.json` and the component files. Use `mcp_component_view` /
+`mcp_component_grep` only when that repo is unavailable locally or when explicitly comparing live DB source
+to the files.
+
+**Capacity is real, not advisory.** A serving session tells the platform how many workers it can run
+(`--max-concurrent`, default 1), and the router will not send it more than that. So a session at
+capacity is skipped in favour of one that is free, rather than accumulating tickets it will never
+start.
+
+**Lane note:** `register` and `serve` default to the production lane because a support agent works real tickets.
+`--data-mode test` registers a fixture agent instead, which will never be routed a production ticket —
+use it only when you are deliberately testing the routing itself.
+
+### If you are the worker
+
+You know you are one when `REMITS_SUPPORT_TICKET_ID` is set in your environment. Your whole job is
+that one ticket, and your brief is your prompt — follow it. Two things it says that are worth
+repeating: **report progress** with `remits-cli agent status --ticket <id> --activity "..."` (a
+headless run is invisible otherwise), and **end in a terminal state** — `complete` with a real
+resolution, or `update_status` with what you established and what the next agent should try. Exiting
+quietly leaves a ticket that looks in-flight forever.
+
+**If your brief says this is not the first autonomous run on this ticket, believe it.** Earlier runs
+picked it up and handed it back unfinished; whatever they tried did not work, so repeating it will not
+work either. Read what they recorded, then either take a genuinely different approach or **stop and
+ask** (`remits-cli ticket ask`). Asking is a complete, successful outcome, and it is the right one when
+the obstacle is not something a run can remove. Accounts cap how many times a ticket may be picked up
+and handed back — past that the ticket stops being offered to workers at all and waits for a person, so
+a run that exits quietly at the limit has cost every earlier run as well as its own.
+
+### Before you edit anything: where you are, and whether you may
+
+Presence answers *who*. Two more facts answer *whether you may edit*, and with git worktrees and
+workspace lanes an account id no longer identifies a working tree — so an agent that does not ask these
+is assuming, and the assumption it makes when it guesses wrong is "this is my repository to edit".
+
+```bash
+remits-cli ticket where --ticket 22454     # repo account, checkout, branch, staging lane, lease, claim, YOUR phase
+remits-cli agent map                       # every repository, who holds each lease, and where each agent is working
+```
+
+**Reading, reproducing and investigating are parallel-safe and unrestricted. Editing one account's
+repository is exclusive**, enforced by a lease held per repository account per data lane:
+
+```bash
+remits-cli ticket lease   --ticket 22454   # take it when you started read-only and reached an actual edit
+remits-cli ticket unlease --ticket 22454   # complete / ask / release already do this for you
+```
+
+Four things are worth knowing and are not obvious:
+
+- **A refusal is not an error.** The run continues read-only, and the message names who holds the lease
+  **and where they are working**, so you can tell a real conflict from a holder in a different worktree.
+  **Do not wait for a lease and do not poll for one** — investigation is most of the work on most
+  tickets, and a ticket that turns out to need an edit hands off with `ticket progress --next-step`
+  saying exactly what change is needed. A lock people queue on turns one stuck worker into a stalled
+  fleet.
+- **A staging workspace does not replace the lease.** Separate lanes stop two runs *resolving* each
+  other's staged code; they do nothing about two processes writing the same files or pushing the same
+  branch, which is what actually destroys work.
+- **You are not restricted to trunk, and you do not choose the branch.** You work on whatever branch your
+  checkout is on — `ticket where` prints it — and nothing switches it underneath you. Separately, if this
+  account subscribes to a **component variant branch**, its variant components (including its
+  `OPERATIONS` process) resolve for you automatically, server-side, without you doing anything. Those are
+  two different facts and only the first is about your files. Load `branch-variants.md` before working in
+  a non-trunk checkout.
+- **The edit lease excludes per repository account and lane, NOT per branch.** So an agent editing a
+  different branch of this same repository still blocks you, even though your files and your pushes would
+  not collide. That is deliberate over-exclusion, not a bug — investigate read-only and hand off, exactly
+  as for any other refusal.
+- **A spawned local ticket worker owns its checkout grounding and already has its staging lane.** For
+  repository work, `remits-cli agent serve` appends the local repository checkout, target branch and a
+  suggested per-ticket worktree path. Before editing, create or choose an isolated worktree appropriate to
+  the ticket. For a ticket with no component branch subscription, the target branch is the repository
+  default before it is the launch checkout's current branch. The supervisor sets
+  `REMITS_WORKSPACE=ticket-<id>` for you; if you choose a detached worktree, export
+  `REMITS_GIT_BRANCH=<branch>` before running `remits-cli`. A worktree is a checkout-isolation tool, not
+  a freshness proof: fetch, fast-forward and prove `HEAD...origin/<branch>` is `0  0` before the first
+  edit, following `multi-agent-development.md`.
+- **GCP Agent components do not get a local checkout.** The same ticket brief can name a component branch
+  subscription, but for a GCP Agent component that is component-resolution context, not a filesystem
+  instruction.
+- **One editing worker per repository account per lane is still the server lease rule.** The worker-owned
+  worktree protects a human's checkout from the spawned worker; it does not make the edit lease
+  per-directory. A branch-aware edit lease with same-branch exclusion is a separate design.
+
+`unlease` returns **your own** lease and deliberately cannot touch anybody else's. Breaking a stale one
+is a separate, human verb: `remits-cli ticket force-unlease --ticket ID --reason "..."`.
+
+### Your account's process is binding, and it is already in your brief
+
+An account declares how its work is done as Prompts with purpose `OPERATIONS`, selected per the ticket's
+`workstream` (`support`, `sdlc`, `incident`, `release`, or whatever that organization calls its
+processes) via `Prompt.category`, with an uncategorised one as the catch-all. The matching text is
+**inlined verbatim into the brief** of every agent that works one of that account's tickets and is
+binding on it — follow it even where it differs from how you would normally proceed, and if it conflicts
+with the brief, follow the process and say so on the ticket.
+
+You do not fetch it: if the brief has a "The process that governs this ticket" section, that is it. If
+it says the account documents no process, the likely cause is that the prompt is **staged but not
+committed** — an autonomous worker resolves the committed one, so it is never bound by a procedure
+nobody has reviewed. The repo root also carries a generated `OPERATIONS.md`; that file is generated
+from the prompt, so **edit the prompt, not the file**.
+
+`workstream` is not `type`: a type classifies the request, a workstream names the procedure, and they
+cross — a `defect` handled by incident response out of hours goes through the SDLC in the morning.
+
+### Some of that process is enforced, not requested
+
+Part of an account's process can be **deterministic**. If your brief has a `## Rules you will be held to`
+section, those rules are enforced by the platform at the write door — the verb is refused, not
+discouraged.
+
+- **Read that section before you act.** A refusal you were warned about costs one command; a refusal you
+  were not costs the run.
+- **A refusal is an ANSWER.** The message names the rule and says what to do instead. Act on that
+  sentence. Do not retry the identical call, and do not go looking for another door — the rules govern the
+  DSL, the MCP tools and this CLI identically.
+- **`[require]` rules mean a human.** You cannot acknowledge one: the platform decides "human" from the
+  absence of an agent run identity, which your commands always carry. Record what you found with
+  `ticket progress` and hand off.
+- **`[warn]` rules let the call through and write a `policy` worklog entry.** Mention it in your handoff.
+- **If you see "POLICY NOT ENFORCED"**, the account's rules could not be parsed. Do not read the absence
+  of a refusal as permission — say so on the ticket. It is a defect in the account's `OPERATIONS` prompt.
+
+The same rules govern `components stage` and `components commit`. A `no-commit` rule is why
+`remits-cli components commit` refuses rather than asks.
+
+### Seeing the queue as a human does
+
+`remits-cli start` opens a browser control center showing the same facts you are acting on: which
+agents are registered and what each is doing, which tickets are open, and which agent each is routed
+to. An operator can route a ticket to a specific agent from there. It is a view, not a second system —
+what it shows and what `remits-cli agent work` returns come from the same records.
+
+### Agent components are workers too
+
+An Agent component that works support tickets must register itself in the same presence registry as
+CLI sessions. That makes it visible in `cliAgents()` and `remits-cli agent map`, and lets
+`dispatch(...)` / `ticket route` target it by the same `agentId` field:
+
+```groovy
+def me = workerId()                         // component:Agent:34
+registerWorker([agentId: me, label: 'Support Triage Agent'])
+def work = workerWork([agentId: me, runId: threadGroupingId()])
+workerStatus([agentId: me, ticketId: work.tickets[0]?.id, activity: 'investigating'])
+```
+
+`workerWork(...)` is the component-side analogue of `remits-cli agent work` — the same code runs behind
+both, so a component and a terminal session get the same answer to the same question. It reads tickets
+routed to that worker, claims what it may start, sweeps eligible unrouted work when it is idle (reported
+separately as `sweptTicketIds`), takes the repository edit lease when available, and returns `phase`,
+`brief`, `briefFacts`, and `editLease`. `phase:'editing'` means the component may edit and stage;
+`phase:'investigating'` means another worker holds the repo lease and the component must stay read-only.
+When a component reaches a resting point, pass `agentId` to `complete(...)`, `ask(...)`, or
+`release(...)` so the ticket verb frees the edit lease and drops its claim.
+
+Route to a component by its **id** (`component:Agent:34`) — that is what `workerId()` returns and what
+the component polls on. `ticket route --agent component:Agent:MyAgent` also works: the name is resolved
+and the id form is what gets stored.
+
+### Moving a ticket through its lifecycle
+
+**`remits-cli ticket` is the platform surface, and it is what you should reach for.** It reads and
+writes the platform's own ticket record, so the same commands work on every Remits platform.
+
+```bash
+remits-cli ticket read     --ticket 22454        # the full record
+remits-cli ticket accept   --ticket 22454        # claim it before changing anything
+remits-cli ticket progress --ticket 22454 --summary "Traced it to the posting Action" --category investigation
+remits-cli ticket status   --ticket 22454 --status in_progress
+remits-cli ticket complete --ticket 22454 --resolution "What you found and did"
+remits-cli ticket ask      --ticket 22454 --question "Re-issue or skip?" --context "412 affected"
+remits-cli ticket answer   --ticket 22454 --message "Skip them."   # alias: reply
+remits-cli ticket message  --ticket 22454 --message "We reproduced it; a fix is staged."
+remits-cli ticket planning --ticket 22454 --board-stage ready_for_qa --blocked-by CAB-112
+remits-cli ticket release  --ticket 22454        # hand it back to the queue
+```
+
+**See the whole queue before deciding your ticket is unique.** Alert-raised tickets arrive in
+clusters, and the same root cause routinely appears under several different account names — so the
+first useful question is usually "how many of these are one fix?", and you cannot ask it from a single
+ticket.
+
+```bash
+remits-cli ticket queue --account-id 49                       # triage order, most urgent first
+remits-cli ticket queue --account-id 49 --unrouted --status open
+remits-cli ticket queue --account-id 49 --search "firestore index"
+```
+
+The `repo` column is the account the **edit lease** excludes on, so it also tells you which of these
+could be worked at the same time and which will serialize behind one another.
+
+Found a second, unrelated problem while working yours? **File it rather than widening the ticket you
+were given** — a ticket that describes two things cannot be closed by either fix.
+
+```bash
+remits-cli ticket create --account-id 49 --subject "Vendor name lost on re-normalization" \
+    --type defect --priority medium --reference-id vendor-name-lost
+```
+
+`--reference-id` makes it get-or-create, so a re-run — or another worker reaching the same conclusion
+— reconciles onto the same ticket instead of filing a duplicate.
+
+Marking and evidence, so the next reader does not repeat your work:
+
+```bash
+remits-cli ticket tag      --ticket 22454 --tags firestore-index,cluster-aug
+remits-cli ticket artifact --ticket 22454 --type log --label "Failing query" --content "..."
+remits-cli ticket note     --ticket 22454 --message "Internal: same cause as 23465"
+remits-cli ticket field    --ticket 22454 --key customerReference --value CR-9182
+```
+
+`note` is internal — the next worker and a reviewer see it, the requester does not. Use `message` for
+anything the requester should read. `field` writes your **organization's own** field, outside the
+platform's bounded planning slots.
+
+**`message`, `answer` and `note` are separated by who reads the result, not by tone.** They are easy to
+confuse and they do different things to the ticket:
+
+| Command | Who reads it | What it does to the ticket |
+|---|---|---|
+| `ticket message --message "..."` | the requester | appends a public entry. **Does not send anything** |
+| `ticket note --message "..."` | the next worker, a reviewer | appends an internal entry |
+| `ticket answer --message "..."` | whoever asked | answers the open question and **re-routes**, so a fresh worker resumes |
+
+`ticket reply` is an **alias of `answer`** — kept because every existing brief says it. Do not read it as
+"reply to the customer"; that is `message`. (Some account tools spell the conversational verb `reply`,
+which is exactly why this surface teaches `answer`.)
+
+**Appending a message is not emailing anyone.** The record is deliberately vendor-agnostic; the account
+owns the transport. To ask for something to actually go out:
+
+```bash
+remits-cli ticket deliver --ticket 22454 --channel email --to ops@acme.test \
+    --subject "Waiting on you" --idempotency-key waiting-22454
+remits-cli ticket deliveries --ticket 22454          # what is queued, and what already went
+```
+
+That records an outbox request. An account-owned Rule or scheduled Action sends it and marks the result
+(`ticket delivered --delivery-id ...` / `ticket delivery-failed --delivery-id ... --reason "..."`). Use
+this when a ticket is waiting on somebody who is not watching the queue.
+
+### When a worker needs a decision from a human
+
+There are **three** ways a run can end, not two, and the third is what stops an agent guessing:
+
+| Outcome | Verb | Means |
+|---|---|---|
+| Done | `ticket complete --resolution` | finished, here is what I did |
+| **Blocked on a choice** | `ticket ask --question` | I understand the work; the DECISION is not mine |
+
+| Could not finish | `ticket status --status pending_review` + `ticket progress` | stuck, here is the hand-off |
+
+`ask` puts the question on the ticket as an outbound message and parks it. The queue then shows it as
+**awaiting a response** — distinct from "done, review me", which `pending_review` alone cannot express.
+
+Someone answers with `remits-cli ticket answer --message "..."` (`reply` is an alias), or through an
+operator Embeddable.
+That **re-routes the ticket by default**, so the supervisor's next poll starts a **fresh worker whose
+brief already contains the exchange**. Resumption costs nothing because a worker is one process per
+ticket — there is no session to restore.
+
+Ask when the choice is genuinely not yours: which of two behaviours is wanted, whether to touch live
+data, an ambiguity in the request. Do not ask for reassurance about something you can determine
+yourself, and ask **once**, with the options laid out.
+
+Inside an autonomous worker `--ticket` defaults to the ticket that worker was launched for.
+
+A refusal is an **answer**: "accept it first", "already assigned to someone else", "reopen it
+first". Act on the sentence — do not go looking for another tool that lets you skip the step.
+
+**`mcp_support_ticket` is an account convention, not a platform guarantee.** It belongs to one
+particular System Account: it may not exist on the platform you are on, it scopes to its own
+account, and it will refuse a ticket owned by a different one. Use it only when you are working in
+that account and want its product-specific workflow on top of the record. It offers:
+- `read` — always start here to load current state
+- `accept` — claim the ticket so other agents do not work it concurrently
+- `update_status` — move to `in_progress` or `pending_review`
+- `complete` — resolve the ticket with a summary of what was done
+- `release` — unassign if you cannot continue
+- **Pulling a ticket by number is enough — you do NOT need to know its account first.** The `ticketId` IS the ticket's globally-unique anchor id, and `mcp_support_ticket` resolves the owning account from it for every action that operates on an existing ticket (`read`, `accept`, `update_status`, `complete`, `release`, `record_progress`, `add_artifact`, `get_attachment`). So when a user says "pull ticket 19463", just call `read` with `{ "action": "read", "ticketId": "19463" }` from any authenticated **prod** session (the ticket lives in prod data) — omit `accountId` entirely. The response returns the resolved `accountId`/`accountName` (and `implementationAccountId` when set); use those for any follow-up work. **Only `create` requires an explicit `accountId`** (a brand-new ticket has no anchor to resolve from). If a bare `ticketId` returns "Support ticket not found", double-check you are in `--data-mode prod`, then fall back to passing an explicit `accountId`.
+- `read` can return `documentState:'missing_or_empty'` with `ticket.mirrorOnly:true` and `ticket.canMutate:false`. That means the support-ticket anchor exists and the queue row is real, but the backing Firestore `support_tickets/{ticketId}` document is missing or metadata-only. Treat this as a degraded ticket, not as "ticket not found"; run or request the System Account action `Restore Support Ticket Documents From Anchor Mirrors` for the owning account before lifecycle mutations. The restore recovers mirrored scalar fields, but document-only arrays such as alert snapshots, email threads, attachments, worklog entries, and artifacts may be lost.
+- If a ticket is part of the request, manage the lifecycle proactively. Do not wait for the human user to remind you to read, accept, update, complete, or release it.
+
+Ticket-routing context:
+- `accountId` / `accountName` identify the account that owns the ticket.
+- If present, `implementationAccountId` / `implementationAccountName` identify the owning `PLATFORM` or `PRODUCT` implementation context.
+- Prefer `implementationAccountId` when choosing the working directory for a ticket, falling back to `accountId` when the platform/product repo is not available locally. Routing already uses that same ladder, so the repo you were routed through is usually the right one.
+- For enhancement work, prefer the platform/product implementation context when deciding where code changes belong.
+- For defect investigations, start from the owning ticket account, then move to the platform/product context if the root cause is in shared components.
+
+Sandbox note:
+- Every `remits-cli` command that reaches the Remits service (`auth`, `tools`, `tool`, `components`, `test`, `token`, and all of `ticket` / `agent`) needs outbound network access.
+- **Inside an autonomous ticket worker this is already arranged** — the supervisor launches the worker with network enabled, in both the editing and the investigating phase. An investigating worker is restricted from *writing the repository*, never from *talking to the platform*: reading its ticket, running a diagnostic and recording a finding are the whole of what investigating means.
+- Elsewhere, `ENOTFOUND`, `EAI_AGAIN`, `ECONNREFUSED`, `EPERM` or a bare exit 6 / `HTTP:000` from a sandboxed session means the command needs escalated permissions or must run outside the sandbox. Do not read it as "the platform is down" — check a second command before concluding anything about the service.
+
+Use the same repo/context rules as other tools:
+- If the ticket targets a `CLIENT` account, do not assume that client's repo is the implementation repo. Confirm the parent `PLATFORM` / `PRODUCT` relationship first.
+- Read `~/.remits-cli/account-repos.json` before choosing which local repo to open.
+- If the correct repo for the relevant account type exists locally, switch there, confirm/pull the relevant
+  branch when clean, 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`.