@remits/remits-cli 0.1.167 → 0.1.169

package/lib/local-ai.js

@@ -525,7 +525,7 @@ function help() {
   console.log('Decisions: {"content":"reply","toolCalls":[]} or {"content":null,"toolCalls":[{"name":"tool","arguments":{}}]}');
 }
 
-async function command({ subcommand, flags, context, root, axios, Client, WebSocket, defaultAgent = 'claude' }) {
+async function command({ subcommand, flags, context, root, axios, Client, WebSocket, defaultAgent = 'claude', requestHeaders }) {
   if (!subcommand || flags.help || subcommand === 'help') return help();
   if (!['serve', 'workers', 'work', 'request', 'respond', 'status', 'sessions', 'release'].includes(subcommand)) throw new Error('Unknown ai subcommand');
   const agent = flags.agent || defaultAgent;
@@ -545,7 +545,7 @@ async function command({ subcommand, flags, context, root, axios, Client, WebSoc
     try {
       const result = await axios.post(baseUrl.replace(/\/+$/, '') + '/cli/ai',
         { ...payload, command: action, workerId: worker.workerId, accountId, dataMode },
-        { headers: { Authorization: 'Bearer ' + session.token }, timeout: 15000, maxContentLength: MAX_BYTES, maxBodyLength: MAX_BYTES });
+        { headers: requestHeaders ? requestHeaders(session.token) : { Authorization: 'Bearer ' + session.token }, timeout: 15000, maxContentLength: MAX_BYTES, maxBodyLength: MAX_BYTES });
       if (!result.data?.success) throw new Error(result.data?.message || 'Local AI command failed');
       return result.data;
     } catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.167",
+  "version": "0.1.169",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,

package/skills/remits-cli/SKILL.md

@@ -64,6 +64,9 @@ reference named after it.
 - **edit → stage → run, every time.** The platform executes whatever is in the staging cache at the
   moment a run starts. Edit a file, run a test without `remits-cli components stage`, and the test runs
   the OLD code. This is the single most common mistake. (`development-loop.md`)
+- **Iterate on the failing cases; run the whole suite once before landing.** Waiting on test runs is most
+  of a slow build loop, not staging. After each edit run `test run --test X --failed` (only what did not
+  pass last time) or `--names "a|b"`, not the full suite. (`development-loop.md`)
 - **Staging and sync fail early on broken runtime-compiled Groovy.** Stage validates changed source in the
   active lane; sync validates changed/new compiled components before writing DB rows or branch variants.
   Agent files are Utility components internally. A stage refused BY COMPILE VALIDATION still wrote the

package/skills/remits-cli/references/agent-sessions.md

@@ -100,15 +100,41 @@ whole point is that it needs no supervision. Following the transcript is the way
 strictly better than a terminal would be: the output is structured, so it can be read as events
 rather than scraped back out of ANSI text.
 
-**No worker ever commits.** The brief forbids `git commit`/`git push` and nothing in the supervisor
-runs git — a worker leaves its changes in the working tree and says so on the ticket, for a human to
-review.
+**Whether a worker lands is the account's choice, not the supervisor's.** Nothing in the supervisor runs
+git. The brief states the account's landing profile: by default a person lands (the worker leaves changes in
+the working tree and says so on the ticket); an account with `supportPolicy.landing: agent` lets the worker
+land with `remits-cli components commit`, which re-checks the account's rules when it runs.
+
+**Each worker gets its own credential.** For every child the supervisor mints a credential bound to that
+attempt (agent + ticket + run) and revokes it when the child exits; the child authenticates with it
+(`REMITS_AGENT_TOKEN`). The platform therefore knows which participant is calling from the credential, so a
+missing or wrong identity header cannot make a worker a human or another agent. Against an older platform
+the worker simply uses the supervisor's session, as before. Each poll also reports, per running child, when
+it last produced output and its last progress line — separate from the supervisor's own heartbeat, so
+`agent map` can tell a connected supervisor from a child that is actually producing work.
 
 ### Resolving which agent a command means
 
-Order: `--agent-id`, then `REMITS_AGENT_ID`, then the single agent registered for this working
-directory. With several registered and no way to tell them apart, the command **fails and lists the
-candidates** rather than guessing — routing work to the wrong tab is silent, and a message is not.
+For agent lifecycle commands, explicit `--agent-id` or `REMITS_AGENT_ID` wins; otherwise the CLI looks
+for the registration anchored to this terminal's owning process. It never borrows another terminal's
+registration just because it shares the checkout.
+
+For platform request attribution, set `REMITS_AGENT_ID` for the agent's shell or pass `--agent-id` on
+each command. Both reach the shared HTTP client, including status, tools and local-AI requests.
+Supervised ticket workers receive `REMITS_AGENT_ID`, `REMITS_WORKER_RUN_ID` and
+`REMITS_SUPPORT_TICKET_ID` automatically. A manually named interactive agent does not need to register
+for ticket routing just to declare its identity. Registered roles and labels are accepted only from a
+registration owned by the authenticated user. `--local-agent` / `REMITS_LOCAL_AGENT_ID` remains a local
+folder choice and does not declare platform agent identity.
+
+System → Activity groups these requests under the authenticated user, with separate agent/run sessions
+and source filters. Undeclared CLI requests are labeled **CLI · no declared agent**, never assumed to be
+human. Browser sessions can also be automated. Only platform requests are observed, not local editing
+or reasoning between commands. Creating a preview token does not mark every subsequent browser user
+of that token as an agent.
+
+`ticket route --agent <target>` names the destination. Its legacy `--agent-id` alias also names the
+destination, not the caller; use `REMITS_AGENT_ID` to identify the agent making a routing request.
 
 ### Which agent gets a ticket
 

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

@@ -218,13 +218,21 @@ remits-cli agent register [--label NAME] [--data-mode test|prod] [--account-id I
 remits-cli agent work [--wait SECONDS] [--json]
 remits-cli agent status [--state idle|working|paused] [--ticket ID] [--activity "..."] [--step "..."]
 remits-cli agent list [--account-id ID] [--json]
-remits-cli agent map [--account-ids 1,4] [--json]       # who is EDITING which repository, from which checkout/branch/staging lane
+remits-cli agent map [--account-ids 1,4] [--json]       # who is EDITING which repository, from which checkout/branch/staging lane; first line = live work vs stored (staged/last-reported) facts
+remits-cli capabilities [--json]                        # collaboration features this platform supports, verbs + how they settle, refusal codes
+remits-cli policy explain --point commit|land|stage|complete|deliver|... [--as human|agent] [--workstream W] [--components type:name[:category],...] [--json]   # what the account rules would decide, and why; nothing applied
+remits-cli evidence [--limit N] [--json] | evidence flush   # your world-stamped trail; inside a ticket attempt it is also published to the ticket as receipts
 remits-cli agent inspect [--account-id ID] [--scope self|children] [--user-id ID|--user-email EMAIL] [--limit N] [--json]
 remits-cli activity inspect [--account-id ID] [--scope self|children|related] [--workspace NAME] [--branch NAME] [--workstream ID] [--user-id ID|--user-email EMAIL] [--limit N] [--json]
 remits-cli workstream status [--workstream ID|--workspace NAME] [--json]
 remits-cli agent release
-remits-cli ticket read|accept|status|progress|complete|release|reopen|assign|planning --ticket ID [--status S] [--resolution "..."] [--summary "..."] [--category C] [--assignee EMAIL] [--workstream VALUE] [--planned-in VALUE] [--board-stage VALUE] [--rank N] [--size VALUE] [--blocked-by VALUE] [--notes "..."]
-remits-cli ticket lease|unlease|force-unlease --ticket ID [--reason "..."]   # force-unlease breaks SOMEBODY ELSE'S lease; operator only
+remits-cli ticket read|accept|status|progress|complete|cancel|release|reopen|assign|planning --ticket ID [--status S] [--resolution "..."] [--reason "..."] [--summary "..."] [--category C] [--assignee EMAIL] [--workstream VALUE] [--planned-in VALUE] [--board-stage VALUE] [--rank N] [--size VALUE] [--blocked-by VALUE] [--notes "..."]
+remits-cli ticket cancel --ticket ID --reason "..." [--expected-revision N]  # close with disposition cancelled; history kept; stops worker
+remits-cli ticket reset-budget --ticket ID                                   # OPERATOR: restore run and spend budget after review
+remits-cli ticket redeliver-events --ticket ID                               # OPERATOR: re-dispatch undelivered lifecycle events
+remits-cli ticket lease|unlease|force-unlease --ticket ID [--reason "..."]   # force-unlease breaks SOMEBODY ELSE'S lease; operator only. 503 code=unavailable = holder unknown: investigate, retry
+remits-cli ticket handoff --ticket ID --summary "..." [--next-step "..."] [--findings "a|b"] [--artifact-refs a,b] [--evidence-refs r1,r2] [--waiting-on X] [--needs cap] [--workstream W] [--exclude] [--expected-revision N]
+remits-cli ticket decide|complete ... [--expected-revision N]   # refused with code=stale_revision (nothing written) if the ticket moved past N
 remits-cli ticket where --ticket ID                    # WHERE this work is: repo account, checkout, branch, staging lane, live lease + holder's location, claim, your phase
 remits-cli ticket ask --ticket ID --question "..." [--context "..."] [--to WHO]   # park on a human decision
 remits-cli ticket answer --ticket ID --message "..." [--route false]             # answer it (alias: reply); re-routes by default
@@ -265,7 +273,7 @@ remits-cli components branch <name> --copy-to <newBranch> [--dry-run] [--force]
 remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]   # make an account resolve this branch
 remits-cli components branch <name> --unsubscribe <accountId>                          # return that account to trunk
 remits-cli components branch <name> --retire [--force]                                 # delete the branch's overlays
-remits-cli test run --test <id|name> [--branch <stagingScope>] [--names "a|b"] [--watch true|false] [--wait true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>] [--label <text>] [--param name=value ...] [--repeat N] [--parallel N] [--json]
+remits-cli test run --test <id|name> [--candidate <laneContentHash>] [--branch <stagingScope>] [--names "a|b" | --failed] [--watch true|false] [--wait true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>] [--label <text>] [--param name=value ...] [--repeat N] [--parallel N] [--json]
 remits-cli test status --task-id <taskId|groupId> [--branch <stagingScope>] [--data-mode test|prod] [--json]   # falls back to the DURABLE run record once the live status expires
 remits-cli test runs [--test <id|name>] [--limit 20] [--compare] [--all-lanes] [--as-account <ID>] [--json]  # durable run history: pass counts, live AI cost, lane, content hash
 remits-cli test compare --base <taskId> --head <taskId> [--json]                                            # per-case improved / regressed / changed, cost and world deltas
@@ -281,6 +289,10 @@ remits-cli corpus consistency --corpus <name> --case <caseKey> [--json]
 remits-cli corpus retire --corpus <name> --case <caseKey> [--case ...] [--restore] [--json]    # drop a case from future runs; past measurements stay readable
 ```
 
+`--candidate <hash>` names the staged content you mean to test (the lane content hash `components status`
+reports); if another process restaged or the lane expired, the run is refused with `stale_revision` instead of
+testing different source. It binds the start of the run, not every later lookup.
+
 `test run` starts a server-side task immediately. By default the CLI process polls until the task is
 terminal; `--watch false` disables websocket progress streaming but still waits. Pass `--wait false` to
 return after launch with the task id. A single run with `--names "a|b|c"` selects cases into one suite task,
@@ -589,6 +601,10 @@ For tests specifically:
 - `--names` is `|`-delimited and may be repeated. A selector containing commas matches a case with that
   exact name first, else its comma-separated parts; an unmatched selector fails the run instead of
   reporting zero cases as success.
+- `--failed` re-runs only the cases that did not pass in YOUR last finished run of the suite on this git
+  branch and staging workspace (a `--parallel` run is read as its whole group; the launch lane is preferred,
+  else the lane the suite recorded in). The launch prints the run it read and the cases. "Nothing failed"
+  starts nothing and exits 0; no earlier run is refused. Not combinable with `--names`.
 - `--as-account <ID>` runs AS a descendant subscriber so its edge selects the component branch
   (*"what does customer X get?"*); `--variant-branch <name>` probes a branch from any checkout
   (*"what does branch Y look like?"*), and `--variant-branch none` forces production/subscription semantics.

package/skills/remits-cli/references/development-loop.md

@@ -421,9 +421,17 @@ This applies to:
 ```bash
 remits-cli test run --test <TEST_ID_OR_NAME>
 remits-cli test run --test "Invoice Tests" --names "specific test case"
+remits-cli test run --test "Invoice Tests" --failed
 remits-cli test status --task-id <TASK_ID>
 ```
 
+**Iterate narrowly, and run the whole suite once before landing.** Waiting on test runs is most of
+an hour-long build loop, not staging. A suite whose cases run one after another re-pays every case's
+fixture work on every rerun. Run the suite once to see what fails. After each edit, run `--failed` (the
+cases that did not pass in your last finished run of this suite, on this git branch and staging
+workspace) or `--names` for the cases your change touches. Then run the full suite once before landing.
+A full rerun after every edit, with every case passing, is the most common way an agent spends an hour.
+
 Tests run on the platform against your staged snapshot. They stream results in real-time. **Read the
 `World:` block printed before the run** — host, execution account, data lane, component world, staging lane
 id + content hash, platform sync vs local HEAD. If it is not the world you meant, stop: the result will be

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

@@ -20,6 +20,7 @@
   - [Investigation Strategy](#investigation-strategy)
   - [Presenting Findings](#presenting-findings)
   - [Verifying a Production Issue Fix](#verifying-a-production-issue-fix)
+- [Missing or deleted business documents](#missing-or-deleted-business-documents)
 
 ## The Investigation Model
 
@@ -281,3 +282,23 @@ When a bug is reported from production, use this pattern:
 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.
+
+## Missing or deleted business documents
+
+`PROCESSED` is the MySQL object's processing outcome, not a guarantee that its Firestore document
+still exists. Read `documentEvidence` from `mcp_object_activity` or a current object `mcp_record_view`:
+it includes the resolved path, observed data lane, presence, recent revision metadata, and the latest
+Object `Document Delete` receipt when available. `state` is `present`, `missing`, `deleted`, `unknown`
+(read failed), or `out_of_scope`. `deleted` requires retained deletion evidence; absence alone is not proof.
+A `laneMismatch` means the requested read lane differs from the object's persisted lane.
+
+`Document Delete` ObjectLog entries expose structured `documentOperation` (outcome, document path,
+user/agent, component/action, node, data lane, scope, run and trace ids). The operation's
+`threadGroupingId` can differ from `request.traceId`; both are retained for correlation. Failed deletes
+never generate success revisions or downstream deletion messages. The processing status remains intact.
+
+To read retained history without a live parent document, call `mcp_firestore_search` with one
+`targetAccountId`, `collection`, `documentId`, and `includeHistory: true`. Use `historyLimit` (default 10,
+maximum 100), `includeRevisionSnapshots: true` for the pre-delete business snapshot, or `revisionId`
+for one exact revision. History is explicitly truncated when more rows exist. Legacy revisions may
+identify the user and time without the newer component/request provenance; do not invent missing facts.

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

@@ -26,6 +26,7 @@
   - [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)
   - [Approvals, reviews and handing work on](#approvals-reviews-and-handing-work-on)
+  - [Coming back later, waiting on other tickets, and cost](#coming-back-later-waiting-on-other-tickets-and-cost)
 
 ## Support Ticket Mental Model
 
@@ -346,19 +347,26 @@ discouraged.
 - **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.
+- **`[require]` rules mean a human.** You cannot acknowledge one. A supervised worker authenticates with a
+  credential bound to its own attempt, so the platform knows it is an agent from the credential itself —
+  omitting identity headers does not change that. 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.
 - **Rules can name your role** (`"when":{"role":"triage"}`, or `"role":{"not":["release_manager"]}` for
   "only release managers"). Your role is the one your session registered with; you cannot change it from a
   worker, and passing one on a call does nothing. A refusal naming your role means hand off to the role that
   may.
-- **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.
+- **If you see a policy problem banner**, part of the account's rules could not be parsed. The rules listed
+  under it are still enforced (a broken replacement keeps its last valid version); do not read the absence
+  of a refusal as permission for the rest — say so on the ticket. **`policy_unavailable`** means a published
+  policy could not be read at all: landing, committing, completing and sending are refused until it can be.
+  Retry later; do not look for another door.
+- **Check before you act**: `remits-cli policy explain --point commit --as agent` says what the rules would
+  decide and which rules apply, without applying anything.
+
+The same rules govern `components stage` and `components commit`. Whether you may land at all is the
+account's **landing profile**, stated in your brief: by default a person lands (leave changes in the working
+tree and describe them); an account that sets `supportPolicy.landing: agent` lets you land with
+`remits-cli components commit`, which re-checks the rules when it runs. A `no-commit` rule always wins.
 
 ### Roles and who may launch them
 
@@ -432,6 +440,7 @@ remits-cli ticket accept   --ticket 22454        # claim it before changing anyt
 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 cancel   --ticket 22454 --reason "Customer withdrew request"  # outcome no longer wanted; stops running worker
 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."
@@ -589,9 +598,33 @@ remits-cli ticket handoff --summary "fix staged in ticket-19463; needs independe
 ```
 
 The handoff is queued even if nobody is online, `--exclude` keeps you off it (independent review needs
-that), and your own exit will not undo it. A reviewer decides with `ticket decide --request R3 --decision
+that), and your own exit will not undo it. It is a checkpoint: `--findings`, `--next-step`,
+`--artifact-refs`, `--evidence-refs`, `--waiting-on` and `--needs` land in the next worker's brief, so give
+durable references (artifact ids, receipt ids), never local paths. Add `--expected-revision N` (the revision
+you read) to `handoff`, `decide` or `complete` and a ticket that moved on is refused with `stale_revision`
+instead of being overwritten. Your evidence trail is published to the ticket as receipts automatically;
+`remits-cli evidence flush` sends anything still queued. A reviewer decides with `ticket decide --request R3 --decision
 approve|changes|reject --revision <rev>`; "changes" sends the work back with the reviewer's note.
 
+An approval or review can need several people: `request-approval ... --min-approvals 2` stays open until two
+different eligible deciders approve; one rejection settles it.
+
+### Coming back later, waiting on other tickets, and cost
+
+```bash
+remits-cli ticket wake --in 1440 --reason "requester promised logs tomorrow"   # or --at <ISO time>; --cancel
+remits-cli ticket depends-on --tickets 19463,19470                              # no value clears
+remits-cli ticket cost --usd 1.25                                                # usually reported for you
+```
+
+- **`wake` instead of waiting.** Never sleep or poll inside a run. Record what you are waiting for, set a
+  wake-up, and finish the run; when the time comes a fresh worker gets the ticket with `resumed for: timer`
+  and your reason in its brief.
+- **`depends-on`** when this ticket genuinely cannot start until others are resolved. The sweep holds it
+  until they are; nothing else has to remember to release it.
+- **Cost** is reported automatically by `agent serve` from each worker's transcript. An account can cap a
+  ticket's spend; when it is reached, starts are refused until a person resets the budget.
+
 **`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

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

@@ -141,6 +141,29 @@ The account-graph and user surface: the middle ground between `account-info.json
 compactly, because it is read into your context every session) and `mcp_account_view` (everything about one
 account).
 
+**Recurring schedules:** `action_schedules` lists the target account's Action schedules;
+`action_schedule_update` upserts by `targetAccountId` + `actionId` (or an account-scoped `scheduleId`);
+`action_schedule_delete` removes that schedule and its cloud job. Updates accept `cron`, `timeZone`,
+`enabled` and `dryRun`. Each run executes as the schedule's owner (`ownerUserId` in reads), who defaults to
+whoever first saves it and is rechecked at every run. `enabled:false` pauses; `enabled:true` resumes while preserving omitted settings.
+`regression_schedule` reads the per-account regression settings and latest report;
+`regression_schedule_update` accepts the same scheduling fields plus `resultAction`, `suiteConcurrency`
+(1–16) and explicit `ownerUserId`. Existing owners are preserved. Only admins may assign another owner;
+an eligible caller may take ownership themselves.
+
+Both use five-field cron and IANA time zones, default UTC. Existing Action schedules retain UTC.
+All writes require production mode; `dryRun:true` validates from either lane without writing or creating
+a cloud job. Action jobs resolve committed enabled `job:true` Actions on the target account; regression
+suites run committed source in test data. Optional `includeSchedulerStatus:true` on reads reports cloud
+registration/next delivery/last transport status; this does not prove Action or regression success.
+An empty regression update does not repair registration: explicitly pass cron/timeZone/enabled.
+
+```bash
+remits-cli tool --name mcp_account_user_admin --data-mode test --input '{"action":"action_schedule_update","targetAccountId":4655,"actionId":21,"cron":"0 1 * * *","timeZone":"America/New_York","enabled":true,"dryRun":true}'
+```
+
+Inspect the preview, then omit `dryRun` and use `--data-mode prod` when authorized to save the schedule.
+
 - `action: 'hierarchy'` (default) — the descendant tree trimmed to `depth` (1-10, default 2; nodes cut off
   are marked `truncated` and still report their child count) and/or the anchored ancestor chain plus every
   edge (`direction: 'down'|'up'|'both'`). Nodes include `testAccount`. **This is how you get the deep tree
@@ -299,6 +322,11 @@ evidence at all, is in `investigation.md` → *HTTP audits*.
 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
 ```
 
+Exact-account history reads also accept `includeHistory` (boolean), `historyLimit` (1–100, default 10),
+`includeRevisionSnapshots` (boolean, default false), and `revisionId` (exact Firestore revision id).
+These require one `targetAccountId`, a collection name and `documentId`. They return `documentEvidence`
+even when the live document is deleted. A normal exact-id miss also returns bounded evidence.
+
 ### `mcp_firestore_patch`
 Guarded exact-document Firestore patch tool for bounded repairs. It defaults to `dryRun:true` and refuses broad
 updates, wildcard collections, delete/remove operations, protected identity fields, and `_lastModified*` audit
@@ -329,7 +357,9 @@ Response fields include `dataMode`, `accountId`, `collection`, `documentId`, `dr
 `diff`. Switch to `"dryRun":false` only after the diff and preconditions are exactly what you intended.
 
 ### `mcp_object_activity`
-Object lifecycle timeline — metadata + recent activity.
+Object lifecycle timeline — metadata + recent activity. Object metadata includes `documentEvidence`
+with path, current presence/data lane, recent revisions and latest deletion receipt. Document Delete
+activity entries include structured `documentOperation` evidence; PROCESSED is independent of document presence.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|