@remits/remits-cli 0.1.98 → 0.1.99

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.98",
+  "version": "0.1.99",
   "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,10 @@ 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.
 
 Use `remits-cli` for everything else: staging changes, running tests, generating embeddable tokens,
 committing work, and diagnosing production issues.
@@ -512,6 +514,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 +528,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 +795,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 +906,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 +1189,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 +1449,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 +1575,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
@@ -1604,11 +1622,13 @@ account).
 without a browser):
 
 - `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.
+- `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
@@ -1974,6 +1994,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
@@ -2554,13 +2610,13 @@ 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 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. |