@remits/remits-cli 0.1.98 → 0.1.100

package/README.md

@@ -34,6 +34,8 @@ remits-cli components sync --branch feature_branch --dry-run --summary
 remits-cli components sync --branch feature_branch --force-tombstones
 remits-cli token --path page/my-embeddable
 remits-cli token --path page/my-embeddable --variant-branch feature_branch
+remits-cli token inspect --token https://example.test/s/<tokenKey>/page/my-embeddable
+remits-cli tool --name mcp_account_user_admin --data-mode prod --input '{"action":"account_create","parentAccountId":4,"name":"Freto","type":"PRODUCT","dryRun":true}'
 remits-cli data-mode
 remits-cli data-mode set prod
 remits-cli sessions list

package/index.js

@@ -278,9 +278,29 @@ function printResolvedBaseUrl(baseUrl) {
   console.log('Base URL:', normalizeBaseUrl(baseUrl || DEFAULT_BASE_URL));
 }
 
-// Tools whose name signals they mutate state rather than only reading it. Used solely to escalate the
-// prod banner from "reading live data" to "WRITING live data" — never to block or permit anything.
+// Tools/actions whose names signal they mutate state rather than only reading it. Used solely to make
+// data-lane banners precise — never to block or permit anything.
 const MUTATING_TOOL_PATTERN = /(^|_)(patch|edit|create|commit|update|delete|remove|write|set|assign|run|execute|send|pause|unpause|interrupt|restore|repair|migrate|sync)(_|$)/i;
+const MUTATING_TOOL_ACTION_PATTERN = /(^|_)(patch|edit|create|commit|update|delete|remove|write|set|assign|run|execute|send|pause|unpause|interrupt|restore|repair|migrate|sync|add|upsert|reparent|structure|accept|complete|release|record|clear|retire|subscribe|unsubscribe|stop|cancel|kill)(_|$)/i;
+
+function toolInputAction(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const value = input.action || input.controlAction || input.command || input.mode;
+  if (value === undefined || value === null || value === true) return null;
+  const normalized = String(value).trim();
+  return normalized || null;
+}
+
+function isMutatingToolCall(toolName, input) {
+  if (MUTATING_TOOL_PATTERN.test(String(toolName || ''))) return true;
+  const action = toolInputAction(input);
+  return action ? MUTATING_TOOL_ACTION_PATTERN.test(action) : false;
+}
+
+function toolOperationLabel(toolName, input) {
+  const action = toolInputAction(input);
+  return 'tool ' + String(toolName) + (action ? ' action ' + action : '');
+}
 
 function looksLikeDryRun(input) {
   if (!input || typeof input !== 'object') return false;
@@ -294,25 +314,29 @@ function isLocalBaseUrl(baseUrl) {
 }
 
 /**
- * One consistent banner across every surface that can touch production. Agents have repeatedly run a
- * prod write believing they were in test mode, so the banner is loud, states the account it resolved,
- * and distinguishes a live WRITE from a live read.
+ * One consistent banner across risky data-lane surfaces. Agents have repeatedly crossed prod/test
+ * boundaries by assumption, so the banner is loud, states the account it resolved, and distinguishes
+ * live production writes from isolated test-data writes.
  */
 function printProdDataBanner({ dataMode, accountId, baseUrl, operation, mutating = false, dryRun = false }) {
   const normalizedDataMode = String(dataMode || '').toLowerCase();
   const prodData = normalizedDataMode === 'prod';
   const prodHost = baseUrl && !isLocalBaseUrl(baseUrl);
-  if (!prodData && !prodHost) return;
+  if (!prodData && !prodHost && !mutating) return;
   const bar = '='.repeat(72);
   let headline;
   if (prodData) {
     headline = dryRun
       ? 'PROD DATA — DRY RUN (no write will be attempted)'
       : (mutating ? 'PROD DATA WRITE — this runs against LIVE production data' : 'PROD DATA READ — this reads LIVE production data');
-  } else {
+  } else if (prodHost) {
     headline = dryRun
       ? 'PROD HOST / TEST DATA — DRY RUN'
       : (mutating ? 'PROD HOST / TEST DATA WRITE — deployed app, isolated test data' : 'PROD HOST / TEST DATA READ — deployed app, isolated test data');
+  } else {
+    headline = dryRun
+      ? 'TEST DATA — DRY RUN (no write will be attempted)'
+      : 'TEST DATA WRITE — isolated test data';
   }
   console.log(bar);
   console.log('  ' + headline);
@@ -421,6 +445,17 @@ function sessionJsonlFile(cwd) {
 }
 
 const CONTENT_FIELDS = new Set(['source', 'html', 'javascript', 'css', 'schema', 'inputSchema', 'previewData', 'messages']);
+const SECRET_LOG_FIELDS = new Set([
+  'token',
+  'tokeninput',
+  'tokenkey',
+  'authtoken',
+  'xauthtoken',
+  'x-auth-token',
+  'remitstoken',
+  'x-remits-token',
+  'authorization'
+]);
 
 function sanitizeForLog(value) {
   if (value === null || value === undefined) {
@@ -434,7 +469,7 @@ function sanitizeForLog(value) {
   }
   const out = {};
   for (const [k, v] of Object.entries(value)) {
-    if (k.toLowerCase() === 'token') {
+    if (SECRET_LOG_FIELDS.has(k.toLowerCase())) {
       out[k] = '[redacted]';
     } else if (CONTENT_FIELDS.has(k) && typeof v === 'string') {
       out[k] = '[' + v.length + ' chars]';
@@ -2777,6 +2812,12 @@ async function testCommand(flags) {
 }
 
 async function tokenCommand(flags) {
+  const subcommand = flags._ && flags._[1];
+  if (subcommand === 'inspect' || subcommand === 'details' || subcommand === 'decode') {
+    await tokenInspectCommand(flags);
+    return;
+  }
+
   const cwd = process.cwd();
   ensureLocalState(cwd);
   const sessionContext = resolveSessionContext(cwd, flags);
@@ -2829,6 +2870,35 @@ async function tokenCommand(flags) {
   console.log(JSON.stringify(output, null, 2));
 }
 
+async function tokenInspectCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const sessionContext = resolveSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const positional = flags._ && flags._[2];
+  const tokenInput = flags.token || flags['token-key'] || flags.tokenKey || flags.value || flags.url || positional;
+
+  if (!tokenInput || tokenInput === true) {
+    throw new Error('Token inspection requires --token <token|tokenKey|URL>, --token-key <key>, --url <URL>, or a positional value.');
+  }
+
+  const api = buildAxios(baseUrl, session.token);
+  const data = await loggedPost(api, cwd, '/cli/tokenInspect', {
+    token: session.token,
+    accountId,
+    tokenInput
+  }).then((r) => r.data);
+
+  if (!data.success) {
+    throw new Error(data.message || 'Failed to inspect token');
+  }
+
+  printSessionResolutionWarning(sessionContext);
+  printResolvedBaseUrl(baseUrl);
+  console.log(JSON.stringify(data, null, 2));
+}
+
 async function toolsCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
@@ -2957,8 +3027,8 @@ async function toolCommand(flags) {
     dataMode,
     accountId,
     baseUrl,
-    operation: 'tool ' + String(toolName),
-    mutating: MUTATING_TOOL_PATTERN.test(String(toolName)),
+    operation: toolOperationLabel(toolName, input),
+    mutating: isMutatingToolCall(toolName, input),
     dryRun: looksLikeDryRun(input)
   });
 
@@ -5524,8 +5594,10 @@ function printToolsHelp() {
 
 function printTokenHelp() {
   console.log('Usage: remits-cli token [--base-url URL] [--branch BRANCH] [--path embeddable/path] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none]');
+  console.log('       remits-cli token inspect --token <token|tokenKey|URL> [--base-url URL] [--account-id ID]');
   console.log('');
   console.log('Mints a branch-aware browser URL for embeddable verification.');
+  console.log('Inspect decodes a persisted Remits token and prints token metadata, recognized routing fields, safety/dataMode evidence, and full context.');
 }
 
 async function main() {
@@ -5594,6 +5666,7 @@ async function main() {
     console.log('  remits-cli components branch <name> --retire [--force]           # delete the branch\'s overlays');
     console.log('  remits-cli test run --test <id|name> [--base-url URL] [--names name1,name2] [--watch true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME]');
     console.log('  remits-cli token [--base-url URL] [--branch BRANCH] [--path embeddable/path] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none]');
+    console.log('  remits-cli token inspect --token <token|tokenKey|URL> [--base-url URL] [--account-id ID]');
     console.log('');
     console.log('  --as-account <ID> verifies AS a descendant subscriber account, so its relationship edge');
     console.log('  selects the component branch and the run resolves exactly what production will.');

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -89,6 +89,7 @@ description: Use remits-cli for fast branch-scoped component staging, test execu
   - [`mcp_run_agent`](#mcp_run_agent)
     - [Controlling a live agent — `pause` / `unpause` / `interrupt`](#controlling-a-live-agent--pause--unpause--interrupt)
   - [`mcp_system_logs`](#mcp_system_logs)
+  - [`mcp_user_activity`](#mcp_user_activity)
   - [`mcp_performance_trace`](#mcp_performance_trace)
   - [`mcp_event_diagnostics`](#mcp_event_diagnostics)
   - [`mcp_component_view`](#mcp_component_view)
@@ -160,9 +161,35 @@ Two more, easily confused: top-level **`componentBranches`** lists the variant b
   account type and parent hierarchy first, and work only from an existing indexed repo unless the user
   explicitly asks you to clone one.
 
-There is no dedicated user MCP tool. For access questions — "who can see this client account?", "why does
-this user see the wrong data?" — use `mcp_sql_query` against `user` / `user_account`. Remember a user's
-custom fields are stored **per bound account**, so the same person can differ per account.
+For access questions — "who can see this client account?", "why does this user see the wrong data?" — use
+`mcp_account_user_admin` first (`action:'users'`, `action:'user'`, or `action:'user_update'`). Use
+`mcp_sql_query` only when you need raw join-table investigation. Remember a user's custom fields are stored
+**per bound account**, so the same person can differ per account.
+
+**Test-data flags are first-class safety evidence.** `Account.testAccount` and `User.testUser` are set for
+accounts/users created while the execution data lane is `test` (including `mcp_account_user_admin`
+creation paths); prod-data creates leave them false. Updating an existing real account/user in test mode
+does not convert it into test data, but its Firestore extension-field writes still go to the test lane.
+`Object.testMode` / `Event.testMode` / `Alert.testMode` identify lifecycle rows in the test data lane.
+Agent-facing surfaces expose these fields:
+
+- `account-info.json`, `account-hierarchy.json`, and `mcp_account_view`: `resolution.testAccount` for the
+  described account, and `testAccount` on returned hierarchy nodes.
+- `mcp_account_user_admin`: `testAccount` on `hierarchy`, `account`, and `account_create` results;
+  `testUser` on `users` / `user` results.
+- `mcp_record_listing` / `mcp_record_view`: `testMode` on `object`, `event`, and `alert` records.
+- `mcp_object_activity`: top-level `dataMode`, `object.testMode`, and `testMode` on Event/Alert
+  timeline entries.
+- `mcp_event_diagnostics`: top-level `dataMode` and `result.event.testMode`.
+- `remits-cli token inspect`: owner `account.testAccount` and `user.testUser`, plus token `dataMode`.
+
+Persisted AI session rows currently do **not** store durable per-grouping `testMode` / `dataMode`; use
+`mcp_ai_session_search.dataMode` only as the current tool execution lane, not as proof of the historical
+grouping's data lane.
+
+If any of those fields contradict the lane you intended, stop and rerun the command with an explicit
+`--data-mode test` or `--data-mode prod`. Never infer prod/test from an account name, URL, branch name, or
+the mere existence of a created account.
 
 Use `remits-cli` for everything else: staging changes, running tests, generating embeddable tokens,
 committing work, and diagnosing production issues.
@@ -398,6 +425,7 @@ Use `mcp_support_ticket` to manage lifecycle:
 - `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:
@@ -512,6 +540,7 @@ here is the tool and the filterable fields:
 | `object_log` | `mcp_record_listing` / `mcp_record_view` | `type`, `description`, `content`, `threadGroupingId` |
 | `event` | `mcp_record_listing` / `mcp_record_view` | `action`, `status`, `eventDate`, `threadGroupingId` |
 | `alert` | `mcp_record_listing` / `mcp_record_view` | `status`, `type`, `active`, `threadGroupingId` |
+| user activity session | `mcp_user_activity` | `userId`, `accountId`, `sessionKey`, `focusedOnly`, `traceId` pivots |
 
 `mcp_record_listing` finds candidates when you do not know the id; `mcp_record_view` opens an exact one;
 `mcp_object_activity` returns one Object's whole timeline in order.
@@ -525,6 +554,8 @@ different lanes (see `platform-overview.md` → *Test and Production Data Lanes*
 - **`threadGroupingId`** — groups every record and log line from one processing chain, and is also the
   request's trace id. Pivot into `mcp_system_logs` and `mcp_performance_trace`.
 - **`node`** — resolves to `serviceName` + `region` for log queries (table below).
+- **`sessionKey`** — salted user-activity session key. Pivot `mcp_user_activity` `sessions` → `story`;
+  each beat then carries a `traceId` / `threadGroupingId` for trace and log investigation.
 - **`sessionId`** — pivots into persisted AI activity via `mcp_ai_session_search`.
 
 ### Reading a record's `content` — persisted context, not a memory dump
@@ -790,7 +821,7 @@ the file. Omit the key; the platform fills it in on sync:
 ```yaml
 # components/embeddables/new_MerchantPortal.meta.yml   — no `id:` yet
 name: Merchant Portal
-summary: One-line statement of what this component is for.
+summary: One-line statement of what this component is for. This is the compact text account-info.json uses first.
 description: |
   Longer technical description with line-number references to the key logic.
 path: /page/merchant-portal        # Readers and Embeddables only
@@ -901,13 +932,15 @@ If the work is tied to a support ticket:
 
 Before committing, update metadata so the next session understands what changed:
 
-1. **`.meta.yml` sidecars** — Update `description` and `mermaid` for each modified component.
+1. **`.meta.yml` sidecars** — Update `summary`, `description`, and `mermaid` for each modified component. `summary` is what drives the compact component description in generated `account-info.json`; `description` is the fallback when no summary is set and is capped in that file.
 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. On a trunk sync it
-describes the owning repo account. On a subscriber-initiated variant sync it describes the subscribing
-account reached through the branch edge, even though the component files still belong to the owner's repo.
+`account-info.json` is read-only — never edit it. It regenerates automatically after sync. Component
+entries prefer `summary`, fall back to capped `description`, and cap `mermaid`; relationships remain as
+generated. On a trunk sync it describes the owning repo account. On a subscriber-initiated variant sync it
+describes the subscribing account reached through the branch edge, even though the component files still
+belong to the owner's repo.
 
 #### Temporary Experiment Workflow
 
@@ -1182,8 +1215,9 @@ link carries what?"
   the edge `domainName`. An **edge** host wins over the account's own, and additionally supplies the path
   travelled — which is what makes that edge's branch variants apply.
 
-**Users are not part of this graph** (see `platform-overview.md`). There is no user MCP tool — use
-`mcp_sql_query` against `user` / `user_account`.
+**Users are not part of this graph** (see `platform-overview.md`). Use `mcp_account_user_admin`
+(`action:'users'`, `action:'user'`, or `action:'user_update'`) for user membership and account-scoped user
+fields. Drop to `mcp_sql_query` against `user` / `user_account` only for raw join-table evidence.
 
 ## Branched Component Variants (per-account component overrides)
 
@@ -1441,9 +1475,19 @@ Before starting an investigation outside the confirmed current repo:
 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_performance_trace` — for slow/sluggish reports, start with `action:"slowest"` when you only have a window, or `action:"trace"` when you have a `threadGroupingId`; this is the MCP wrapper for the Diagnostics page request-trace data.
-9. `mcp_system_logs` — correlate via `threadGroupingId` for raw log context when the trace needs supporting log lines.
-10. `mcp_component_view`/`mcp_component_grep` — explain how the responsible component works.
+8. `mcp_user_activity` — for "user X is slow right now" reports, list sessions by `userId`/`accountId`, open the session story, and use the returned beat pivots.
+9. `mcp_performance_trace` — for slow/sluggish reports, open the beat `traceId` with `action:"trace"`; use `action:"slowest"` when you only have a broad time window.
+10. `mcp_system_logs` — correlate via `threadGroupingId` for raw log context when the trace needs supporting log lines.
+11. `mcp_component_view`/`mcp_component_grep` — explain how the responsible component works.
+
+**Slow / sluggish user report:**
+
+1. Resolve the reporting user/account with `mcp_account_user_admin` if you only have an email/name.
+2. Call `mcp_user_activity` with `action:"sessions"` and `userId` or `accountId`.
+3. Open the likely row with `action:"story"` and inspect beat labels, status, `ms`, `node`, and `traceId`.
+4. Open slow or failed beat pivots with `mcp_performance_trace` before querying raw logs.
+5. Use the returned `mcp_system_logs` pivot only when the trace needs surrounding log lines.
+6. If there is no live session, call `mcp_user_activity` `action:"watch"` for the user/account, ask for reproduction, then read `sessions`/`story` again. Focused sessions retain sanitized request detail and emit archived `REMITS_ACTIVITY` log lines.
 
 **Error or Alert Investigation:**
 1. `mcp_record_listing` — search by alert type, content, error text, action, status, `threadGroupingId`, or other exact-match record properties when you do not yet know the record ID.
@@ -1557,8 +1601,8 @@ its behavior against component source:
   `databaseName` (the account's own override, often null) vs `resolvedDatabaseName` (the storage namespace
   actually in effect); `branchName` (the repo sync branch) and `lastRepoSync`; `domainName` vs
   `resolvedDomainName` (the custom host in effect, which differs when reached through an edge host);
-  `editMode`; and — when a component branch is in effect — `componentBranch` plus `componentOwnerAccountId`
-  / `componentOwnerAccountName`.
+  `authPath` / `targetPath` (login and post-login landing routes); `editMode`; and — when a component
+  branch is in effect — `componentBranch` plus `componentOwnerAccountId` / `componentOwnerAccountName`.
 - `resolution.relationships` — **every structural link upward**, primary first: `parentAccountId` /
   `parentAccountName` / `parentAccountCode` / `parentAccountType`, `primary` (true for the one link that
   mirrors the account's primary parent), `active`, and the three independent link-scoped properties
@@ -1584,15 +1628,16 @@ account).
 
 - `action: 'hierarchy'` (default) — the descendant tree trimmed to `depth` (1-10, default 2; nodes cut off
   are marked `truncated` and still report their child count) and/or the anchored ancestor chain plus every
-  edge (`direction: 'down'|'up'|'both'`). **This is how you get the deep tree account-info.json omits.**
-- `action: 'account'` — one account's `resolution` block plus masked configuration fields, without paying
-  for the component inventory.
+  edge (`direction: 'down'|'up'|'both'`). Nodes include `testAccount`. **This is how you get the deep tree
+  account-info.json omits.**
+- `action: 'account'` — one account's `resolution` block, including `testAccount`, plus masked
+  configuration fields, without paying for the component inventory.
 - `action: 'users'` — an account's users at a hierarchy `scope` (`self`/`children`/`parents`/`hierarchy`),
-  optional `email` substring filter. Extension fields are omitted here on purpose: they are stored **per
-  account** and these users are bound to their own.
+  optional `email` substring filter. Rows include `testUser`. Extension fields are omitted here on purpose:
+  they are stored **per account** and these users are bound to their own.
 - `action: 'user'` — one user (`userId` or `email`) with roles, account memberships, and extension fields
-  **correctly scoped to the requested account**. It never grants membership as a side effect of a read, and
-  tells you when the fields shown belong to a different account.
+  **correctly scoped to the requested account**, plus `testUser`. It never grants membership as a side
+  effect of a read, and tells you when the fields shown belong to a different account.
 - `action: 'account_update'` — write Account-schema configuration `fields`, and/or `name`/`status`
   (`ACTIVE`/`ON_HOLD`/`PENDING`).
 - `action: 'user_update'` — write User-schema `fields` under the named account, plus `name`/`enabled` and
@@ -1603,12 +1648,37 @@ account).
 **Building an account hierarchy** (the structural writes — this is how a coding agent provisions accounts
 without a browser):
 
+**Data-lane rule for provisioning:** `remits-cli tool` defaults to `--data-mode test`. That is correct for
+fixtures and rehearsals, but it means `mcp_account_user_admin` `action:'account_create'` creates test-lane
+accounts unless the command explicitly passes `--data-mode prod`. For real platform/product/customer
+provisioning, always dry-run in prod first, check the response's `dataMode`, then run the write in prod:
+
+```bash
+remits-cli tool --name mcp_account_user_admin --data-mode prod --input '{"action":"account_create","parentAccountId":4,"name":"Freto","type":"PRODUCT","dryRun":true}'
+```
+
+After the real write, verify the response (or re-read `action:'account'`) shows the command `dataMode` you
+intended and `testAccount:false` for real provisioning. `testAccount:true` means you created a test-data
+account, even if the name and structure look correct.
+
+For a test rehearsal, make the opposite assertion explicit: the response should show `dataMode:'test'` and
+`testAccount:true` for created accounts (or `testUser:true` for created users). A false test flag in a
+test rehearsal means the data lane or the returned entity is not the one you intended.
+
+Account/User schema `fields` are Firestore-backed extension fields. Their physical storage follows the
+same data lane as the tool call: `--data-mode test` writes under `testing/<resolvedDatabaseName>/...`, while
+`--data-mode prod` writes under `accounts/<resolvedDatabaseName>/...` (for modern segmented accounts). If a
+test-lane rehearsal should become real provisioning, rerun the create/update in prod mode; do not assume the
+test-lane Firestore fields moved.
+
 - `action: 'account_create'` — create a child under `parentAccountId`, with its **primary relationship edge**,
-  applying `type` / `databaseName` / `domainName` / `code` / `repositoryNameOverride` / `branchName` /
-  `editMode` / … **at birth**. That ordering matters: the storage namespace is resolved from those properties,
-  and the parent's cascaded schema fields are written into it during creation. Idempotent — an existing
-  same-name account under that parent comes back with `reusedExisting: true`, unchanged.
-- `action: 'account_structure'` — change those properties on an existing account.
+  applying `type` / `databaseName` / `domainName` / `authPath` / `targetPath` / `code` /
+  `repositoryNameOverride` / `branchName` / `editMode` / … **at birth**. That ordering matters: the storage
+  namespace is resolved from those properties, and the parent's cascaded schema fields are written into it
+  during creation. Idempotent — an existing same-name account under that parent comes back with
+  `reusedExisting: true`, unchanged. The response includes `testAccount`.
+- `action: 'account_structure'` — change those properties on an existing account, including account-level
+  custom host, login path, and landing path.
 - `action: 'edge_add'` / `'edge_update'` / `'edge_remove'` — manage a membership `AccountRelationship` edge to
   `parentAccountId`, including the three independent edge properties `branchName` (which component code runs),
   `databaseName` (a path-scoped storage-namespace override — **live**, and inherited by everything below
@@ -1732,8 +1802,11 @@ Object lifecycle timeline — metadata + recent activity.
 |-----------|----------|-------------|
 | `accountId` | yes | Account ID |
 | `objectId` | yes | Object ID (from `object_id` in documents) |
+| `dataMode` | no | Explicit lane: `prod` or `test`. Response echoes `dataMode`. |
 | `activityOptions` | no | `{limit, offset, types, start, end, order}`. Default: limit=5, order=desc. Types: `OBJECT_LOG`, `EVENT`, `ALERT`. |
 
+Response fields include `dataMode`, `object.testMode`, and `testMode` on Event/Alert timeline entries.
+
 ### `mcp_record_listing`
 List and search lifecycle records when you do not already know the record ID.
 
@@ -1787,6 +1860,7 @@ Front-stage references:
 | Parameter | Required | Description |
 |-----------|----------|-------------|
 | `action` | no | `search` (default), `detail`, or session control `pause`/`unpause`/`interrupt` |
+| `dataMode` | no | Explicit execution lane: `prod` or `test`. Response echoes `dataMode`, but persisted groupings do not have durable per-row lane flags. |
 | `search` | no | Broad text match against session IDs and grouping IDs |
 | `sessionId` | no | Session ID filter in search mode, or grouping/session key in detail mode |
 | `groupingId` | no | Grouping ID filter in search mode, or grouping key in detail mode |
@@ -1974,6 +2048,42 @@ Query Cloud Run service logs.
 {"node": "remitsAdmin-east5", "timeRange": "4h", "severity": "ERROR"}
 ```
 
+### `mcp_user_activity`
+Read live user activity sessions and control focused capture. Use this before trace/log spelunking when
+the report is user-centric, for example "User abc is reporting slow responses." It wraps the same
+Redis-backed store as System → Activity and returns ready pivots to traces, logs, and component source.
+
+Common flows:
+
+```bash
+# Find what one user is doing right now
+remits-cli tool --name mcp_user_activity --input '{"action":"sessions","userId":3,"limit":10}' --data-mode prod
+
+# Open a returned sessionKey and inspect its beats
+remits-cli tool --name mcp_user_activity --input '{"action":"story","sessionKey":"c_46ee68bba67003a6","limit":50}' --data-mode prod
+
+# Arm focused capture, ask the user to reproduce, then read the story again
+remits-cli tool --name mcp_user_activity --input '{"action":"watch","userId":3,"minutes":30}' --data-mode prod
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `action` | no | `sessions`, `story`, `watch`, `unwatch`, `forget`, `status`, or `archive`. Default: `sessions`. |
+| `userId` / `accountId` | no | Filter sessions/archive or choose the focus subject for `watch`/`unwatch`. One is required for `watch`/`unwatch`. |
+| `sessionKey` | for `story`/`forget` | Salted activity session key returned by `sessions`; not a raw browser/session credential. |
+| `focusedOnly` | no | For `sessions`, return only focused/watched sessions. |
+| `sinceMs` | no | For `sessions`, lower bound on last-seen epoch milliseconds. Defaults to the activity TTL window. |
+| `limit` | no | Session/story/archive row cap. Defaults: sessions=100, story=200, archive=50. |
+| `minutes` | no | Watch TTL for `watch`; defaults to `activity.focus.ttl.minutes`. |
+| `traceId` / `threadGroupingId` | no | For `archive`, narrow focused activity log pivot to one trace. |
+| `lookbackHours` | no | For `archive`, Cloud Logging window in the returned `mcp_system_logs` pivot. Default 24, max 168. |
+| `node` / `serviceName` / `region` | no | For `archive`, target for the returned `mcp_system_logs` pivot. `node` defaults to `remitsAdmin-east5`. |
+
+Reading rule: use `sessions` → `story` to build the behavioral timeline, then open a slow or failed beat's
+`mcp_performance_trace` pivot. Use `watch` when the user can reproduce and no live story exists. Use
+`archive` only for watched/focused sessions; ordinary activity lives in Redis and expires with the activity
+TTL.
+
 ### `mcp_performance_trace`
 Read Remits request traces through the same `traces(...)` DSL that powers the admin Diagnostics "Request
 traces" panel. Use this before raw log spelunking for slow or sluggish requests because it returns profiled
@@ -2135,6 +2245,7 @@ This keeps file retrieval self-contained — no separate download endpoint is ne
 
 **Recommended flow** — `accountId` is optional throughout; `ticketId` resolves the owning account:
 1. `read` — check ticket state and any attachments
+   - If `read` returns `ticket.mirrorOnly:true`, use the mirrored fields for triage context, restore the backing document first, then claim/update/complete it.
 2. **`accept`** (with `assignee`) — this is a **hard precondition for `update_status`**, not just etiquette
 3. `get_attachment` if attachments are present and relevant to the investigation
 4. `update_status` — `in_progress` while working, `pending_review` when the fix is done but not yet deployed
@@ -2300,6 +2411,10 @@ optional class-histogram sampling, **no heap dump and no JFR**.
 List and filter tickets **across an account and its descendants** so you can choose what to work on. Lifecycle
 actions stay on `mcp_support_ticket`.
 
+Queue rows are built from support-ticket anchor mirrors by default. A row in this list means a
+support-ticket anchor exists; it does not guarantee the full Firestore document is healthy. Open the
+ticket with `mcp_support_ticket read` before lifecycle work and honor `mirrorOnly` / `documentState` if present.
+
 | Parameter | Required | Description |
 |-----------|----------|-------------|
 | `action` | no | `list` (default) |
@@ -2488,6 +2603,7 @@ remits-cli components branch <name> --unsubscribe <accountId>
 remits-cli components branch <name> --retire [--force]                                 # delete the branch's overlays
 remits-cli test run --test <id|name> [--names "a,b"] [--watch true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]
 remits-cli token [--path <embeddablePathOrId>] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]
+remits-cli token inspect --token <token|tokenKey|URL>                  # inspect token metadata, safety/dataMode evidence, and full context
 remits-cli tools [--branch <name>] [--data-mode test|prod] [--variant-branch <name|none>]
 remits-cli tool --name <toolName> [--branch <name>] [--input "{...}"] [--data-mode test|prod] [--variant-branch <name|none>] [--timeout-ms 60000] [--async true --wait true]
 remits-cli tool status --call-id <callId> [--data-mode test|prod]
@@ -2528,7 +2644,10 @@ For tests specifically:
 
 - Every command that can touch production (`tool`, `test run`, `components sync`) prints a `PROD DATA`
   banner naming the operation, the resolved account, and the host — and distinguishes a live **WRITE**
-  from a live **READ** and from a **DRY RUN**. If you see a WRITE banner you did not intend, stop.
+  from a live **READ** and from a **DRY RUN**. `remits-cli tool` also prints an explicit **TEST DATA WRITE**
+  banner for mutating tool calls in the test lane, including multi-action tools such as
+  `mcp_account_user_admin` where the write is signaled by `input.action` (`account_create`, `user_update`,
+  `edge_update`, etc.). If you see a WRITE banner you did not intend, stop.
 - A tool call that fails **in the platform runtime** rather than in the tool (Groovy reflective dispatch
   of a runtime-compiled component, an empty connection pool, a Redis reconnect, a lock-wait timeout)
   now comes back as HTTP `503` with `failureClass: "transient_infrastructure"` and `retryable: true`,
@@ -2554,13 +2673,14 @@ For tests specifically:
 | Long-running tool times out | For `mcp_run_action`/`mcp_run_agent`, use the tool's own `executionMode:"async"` and poll with a `controlAction:"status"` call (see "Tool Execution Lifecycle"). For other long tools without their own async, use `remits-cli tool --async true` and poll `remits-cli tool status --call-id <callId>`. `--timeout-ms` only adjusts the per-request HTTP timeout; it is not a substitute for async. |
 | Need to continue tracking a long Action or Agent after terminal disconnect | Read `./.remits-cli/tool-responses/<callId>.json` for the returned `actionRunId`/`agentRunId`/`sessionId`/`threadGroupingId`. Re-poll the run with a `controlAction:"status"` call carrying that `actionRunId`/`agentRunId`, or inspect the agent session via `mcp_ai_session_search` with the `sessionId`. |
 | Staged change has no effect in a live (non-CLI) run | Staged overrides resolve only under a CLI TestMode (`branchName`+`cliUserId`). Live webhooks and other non-CLI runtime paths still use the DB (trunk, or the account's subscribed variant). `commit` to make it durable. See "Component Resolution". |
-| Need to know an account's shape (role, type, parents, namespace, branch) | Read `resolution` — from the repo's `account-info.json`, or `mcp_account_user_admin` `action:'account'` (cheap), or `mcp_account_view` (full inventory): `role`/`summary`, `type`, `resolvedDatabaseName`, `relationships`, `componentBranch`, plus top-level `componentBranches`. Never infer structure from the account's name. |
+| Need to know an account's shape (role, type, parents, namespace, branch, host/login routes) | Read `resolution` — from the repo's `account-info.json`, or `mcp_account_user_admin` `action:'account'` (cheap), or `mcp_account_view` (full inventory): `role`/`summary`, `type`, `resolvedDatabaseName`, `domainName`/`resolvedDomainName`, `authPath`/`targetPath`, `relationships`, `componentBranch`, plus top-level `componentBranches`. Never infer structure from the account's name. |
 | Need the account tree below an account, or its users | In a local repo, read `account-hierarchy.json` for the generated tree. For live data, use `mcp_account_user_admin` (`action:'hierarchy'` with a `depth`, or `action:'users'`). `account-info.json` deliberately omits the tree. |
+| Need to prove whether an account/user/record is test data | Check explicit flags: `resolution.testAccount` / hierarchy `testAccount`, `mcp_account_user_admin` `testAccount` / `testUser`, token inspect owner flags, and `mcp_record_listing` / `mcp_record_view` `testMode` for object/event/alert rows. Do not infer from names or branch labels. |
 | Need account configuration values | In a local repo, read `account-configurations.json`. For live data, use `mcp_account_user_admin` (`action:'account'`) or `mcp_account_view`. `account-info.json` deliberately omits configurations. |
 | An account has two parents and you don't know which one a run used | `resolution.relationships` lists every link with its own `branchName`/`databaseName`/`domainName`. A membership-only account with SEVERAL edges resolves **trunk and inherits nothing** until a path is named (`--as-account`, `--variant-branch`, or an edge host) — that is by design, not a bug. With exactly ONE membership edge it inherits normally, descendants included. |
 | Documents missing / written to the wrong place | Compare `resolution.databaseName` (the account's own override) with `resolution.resolvedDatabaseName` (what is actually in effect), and check for a `databaseName` on one of the `relationships` edges. Data does not inherit; components do. |
 | A custom hostname resolves to an unexpected account | Compare `resolution.domainName` with `resolvedDomainName` and the edge `domainName`s. An **edge** host wins over the account's own host and additionally supplies the path travelled (which is what makes that edge's branch variants apply). |
-| Need users of an account, or accounts of a user | There is no user MCP tool. Use `mcp_sql_query` on `user` / `user_account` (or `account.users([scope:'children'])` inside a component). Remember user custom fields are stored **per bound account**, so the same person can differ per account. |
+| Need users of an account, accounts of a user, or account-scoped user fields | Use `mcp_account_user_admin` (`action:'users'`, `action:'user'`, or `action:'user_update'`). Use `mcp_sql_query` on `user` / `user_account` only for raw join-table investigation. Remember user custom fields are stored **per bound account**, so the same person can differ per account. |
 | One account behaves differently from its siblings on the same component | It probably subscribes to a **branch variant**. Check `remits-cli components branches` and `remits-cli components branch <name> --subscribers`, and reproduce with `remits-cli test run --as-account <ID>`. Do NOT "fix" this by adding per-account logic to the origin component. |
 | Edits on a feature branch seem to run against trunk code | You are likely on the **trunk** branch, or passed `--variant-branch none`. Run `remits-cli components status` — it states which world the working tree resolves. |
 | A component vanished for one account after a variant-branch sync | Its file is missing from that branch, so the sync created a **tombstone** that hides it from subscribers. Restore the file on the branch and re-sync. Trunk is unaffected. |