@remits/remits-cli 0.1.101 → 0.1.103

package/README.md

@@ -90,6 +90,7 @@ remits-cli install --skills --overwrite true
 - Test activity is streamed from websocket `TestSuite` events while final status is also polled from `/cli/test`.
 - Tool execution writes the full response to a separate file so large payloads do not bloat the session log.
 - `--variant-branch <name|none>` is available on `test run`, `token`, `tools`, and `tool`. Use it to probe a committed branch variant from any checkout; omit it to resolve the execution account's normal subscription, or pass `none`/`trunk` to force subscription semantics from a variant checkout.
+- On `test run`, `--branch <name>` is only the Redis staging namespace. Pair an unused value with `--variant-branch none` when existing staged entries on the real git branch would shadow committed trunk/variant rows. Do not apply that shortcut to `components sync` or `components commit`, where `--branch` names the GitHub branch to reconcile.
 
 ## Service, Dashboard, WebSocket, and Tmux Lifecycle
 
@@ -100,6 +101,7 @@ remits-cli install --skills --overwrite true
 - `remits-cli start` starts a detached background process by default. Use `remits-cli start --foreground true` only when you want to run the daemon in the current terminal.
 - `remits-cli status` reports whether the background service is alive, prints the dashboard URL when available, and prints the resolved session tuple: Account ID, User ID, current git branch, and active data mode.
 - `remits-cli whoami` prints only the resolved session tuple. Use `--base-url`, `--account-id`, and `--data-mode` to prove the exact host/account/lane before running a tool or test.
+- Both print **two** data modes. "Data mode" governs `tool` / `tools` / `token` and falls back to the stored session lane; "Data mode (test run)" governs `test run`, which ignores the session and defaults to `test` unless `--data-mode prod` is passed.
 - `remits-cli stop` stops the background service, kills the shared tmux session, and clears pane tracking state.
 - The service starts a localhost dashboard that acts as a control center for remits-cli integration state.
 - The dashboard shows websocket connection health, topic subscriptions, tmux session/panes, the discovered account repo index, global state files, and per-repo remits-cli files.

package/index.js

@@ -335,6 +335,10 @@ function resolveSessionIdentity(cwd, flags = {}) {
     userName: user.name || user.username || user.email || null,
     branchName,
     dataMode,
+    // `test run` resolves its lane from the FLAG ONLY (testRunCommand), never the stored session, so that
+    // an account whose session is parked on prod cannot have a test run silently follow it. Report both
+    // rather than a single number that governs only some commands.
+    testRunDataMode: requestedDataMode || DEFAULT_DATA_MODE,
     baseUrl: normalizeBaseUrl((session && session.baseUrl) || requestedBaseUrl || DEFAULT_BASE_URL),
     updatedAt: session ? session.updatedAt : null,
     sessionResolutionWarning
@@ -352,7 +356,8 @@ function printSessionIdentity(identity, options = {}) {
     console.log('Account ID:', identity.accountId || 'unresolved');
     console.log('User ID:', 'unresolved');
     console.log('Branch:', identity.branchName || 'unresolved');
-    console.log('Data mode:', identity.dataMode || DEFAULT_DATA_MODE);
+    console.log('Data mode:', (identity.dataMode || DEFAULT_DATA_MODE) + ' (applies to tool/tools/token)');
+    console.log('Data mode (test run):', identity.testRunDataMode || DEFAULT_DATA_MODE);
     console.log('Base URL:', identity.baseUrl);
     return;
   }
@@ -375,7 +380,12 @@ function printSessionIdentity(identity, options = {}) {
     console.log('  User:', identity.userName);
   }
   console.log('  Branch:', identity.branchName);
-  console.log('  Data mode:', identity.dataMode);
+  console.log('  Data mode:', identity.dataMode, '(applies to tool/tools/token)');
+  // `test run` deliberately ignores the stored session lane and defaults to test, so a session sitting on
+  // prod would otherwise read as "prod" here while the next test run went to the test lane. Say so rather
+  // than letting the tuple imply a lane it does not govern.
+  console.log('  Data mode (test run):', identity.testRunDataMode,
+    identity.testRunDataMode === identity.dataMode ? '' : '— test run ignores the session lane; pass --data-mode prod to override');
   console.log('  Base URL:', identity.baseUrl);
   if (identity.updatedAt) {
     console.log('  Session updated:', identity.updatedAt);
@@ -5694,7 +5704,7 @@ function printComponentsHelp(subcommand) {
 }
 
 function printTestHelp() {
-  console.log('Usage: 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|none]');
+  console.log('Usage: remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names name1,name2] [--watch true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none]');
   console.log('');
   console.log('Runs a Test component against the staged/variant world for this checkout.');
   console.log('Examples:');
@@ -5704,6 +5714,10 @@ function printTestHelp() {
   console.log('Notes:');
   console.log('  --names is comma-delimited, so avoid commas in individual test case names.');
   console.log('  --as-account changes the execution account so subscriber branch edges apply.');
+  console.log('  --variant-branch <name> probes a committed variant branch; use "none" or "trunk"');
+  console.log('       to force production/subscription semantics from a variant checkout.');
+  console.log('  --branch changes only the CLI staging namespace for test execution. Pair an unused');
+  console.log('       value with --variant-branch none when existing staged entries would shadow DB rows.');
   console.log('  --data-mode prod intentionally targets live production data.');
 }
 
@@ -5797,7 +5811,7 @@ async function main() {
     console.log('  remits-cli components branch <name> --subscribe <accountId>      # make an account resolve this branch');
     console.log('  remits-cli components branch <name> --unsubscribe <accountId>    # return that account to trunk');
     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 test run --test <id|name> [--base-url URL] [--branch stagingScope] [--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('');

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -166,31 +166,52 @@ For access questions — "who can see this client account?", "why does this user
 `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:
+**Test-data flags are first-class safety evidence.** `Account.testAccount` and `User.testUser` are set by
+the `account(...)` / `user(...)` factories when the execution data lane is `test` (which is how
+`mcp_account_user_admin` creates); prod-data creates leave them false. Two limits worth knowing: a record
+built some other way (`new Account(...).save()` inside a component) is only flagged during an **automated
+Test** in the test lane, so `testAccount:false` on something you created in test mode means it is a real
+account; and updating an existing real account/user in test mode does not convert it into test data,
+though its Firestore extension-field writes still go to the test lane. `Object.testMode` /
+`Event.testMode` / `Alert.testMode` (and `testMode` inside test-lane Audit documents) 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_record_listing`: top-level `dataMode` (the lane it searched — listings are **filtered** by lane,
+  so `totalItems:0` in the wrong lane reads exactly like "no such record"), plus `testMode` per record.
+- `mcp_record_view`: `record.dataMode` (the lane read in) next to `record.testMode` (the lane the row
+  belongs to). This one loads **by id and does not filter**, so those two can legitimately disagree —
+  and when they do, that is the finding.
 - `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`.
+- `remits-cli token inspect`: owner `account.testAccount` and `user.testUser`, plus a `safety` block
+  carrying `dataMode`, `dataModeDeclared`, and an explicit warning when the token does not declare one.
+- `remits-cli whoami`: the resolved account / user / branch / lane / host tuple for the **next tool
+  call**. It does not describe `remits-cli test run`, which ignores the stored session lane — see below.
 
-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.
+Two surfaces deliberately have **no** lane flags, and both mislead if you forget it:
+
+- **`mcp_sql_query` reads MySQL directly and is lane-blind.** `object` / `event` / `alert` come back with
+  **both lanes mixed**, and `user` / `account` with test fixtures mixed into real records. Filter
+  explicitly — `test_mode = 0`, `test_user = 0`, `test_account = 0` — or use the purpose-built tool.
+- **Persisted AI session rows** store no durable per-grouping `testMode` / `dataMode`. Use
+  `mcp_ai_session_search.dataMode` as the current execution lane only, never as proof of the historical
+  grouping's 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.
 
+**A tool's `dataMode` input never widens the lane.** Tools that accept a `dataMode` argument clamp it
+against the lane the *command* was launched with: it may narrow `prod` -> `test`, never escalate
+`test` -> `prod`. So `--data-mode test --input '{"dataMode":"prod"}'` stays in **test**, and the response's
+`dataMode` — not your input — is the truth. To reach prod data, pass `--data-mode prod` on the command
+line. (Under MCP, the launch lane is the caller's own `dataMode` argument, which defaults to `prod`.)
+
 Use `remits-cli` for everything else: staging changes, running tests, generating embeddable tokens,
 committing work, and diagnosing production issues.
 
@@ -297,8 +318,11 @@ Key implications:
    `git add -A && git commit && git push`, `remits-cli components sync`, `git pull --ff-only`.
 
 **Create a new component:** add `new_Name.groovy` (+ `.json` / `.meta.yml` as applicable). Sync assigns the
-durable id and renames the files. Do not create a direct database row to work around an id/name mismatch, and
-never create a replacement for a component that was unexpectedly deleted or renumbered.
+durable id and renames the files. Standalone Prompts live in `components/prompts/new_Name.md`, and their
+sidecar must include `name`, `summary`, `description`, and `purpose` (usually `CUSTOM`). AGENT prompts do
+not live there; they are the `.md` sidecar beside the Utility in `components/agents/`. Do not create a
+direct database row to work around an id/name mismatch, and never create a replacement for a component
+that was unexpectedly deleted or renumbered.
 
 **Delete a component (deliberate only):** remove **all** of that component's files from the repo, confirm via
 `git status` that only those files are gone, then sync — the delete phase removes exactly that DB row. Deletion
@@ -811,6 +835,8 @@ components/embeddables/new_MerchantPortal.groovy     # source
 components/embeddables/new_MerchantPortal.html       # markup
 components/embeddables/new_MerchantPortal.js         # client script
 components/embeddables/new_MerchantPortal.meta.yml   # metadata sidecar
+components/prompts/new_PricingReviewPrompt.md        # standalone Prompt body
+components/prompts/new_PricingReviewPrompt.meta.yml  # standalone Prompt metadata
 ```
 
 **Do NOT put an `id:` in a new component's sidecar.** `id` is what links a sidecar to an *existing*
@@ -833,6 +859,10 @@ mermaid: |
     A[Request] --> B[Load documents]
 ```
 
+For `components/prompts/new_*.meta.yml`, include `description` and `purpose: CUSTOM`; missing
+`description` fails trunk validation, and missing/mismatched `purpose` leaves a post-promotion Prompt
+overlay instead of pruning cleanly.
+
 > **Staging creates nothing in the database, so a `new_` component has no id yet — address it BY NAME.**
 > `remits-cli test run --test "My Suite"`, not `--test <id>`. Component-to-component resolution and
 > request-level addressing are name-based too; the component guides cover those. After a trunk sync the
@@ -1322,6 +1352,18 @@ remits-cli token --path embeddable/index/50 --as-account 101   # subscriber -> v
 remits-cli token --path embeddable/index/50                    # owner      -> trunk
 ```
 
+If `components status` shows staged entries that you cannot safely clear, isolate verification in an
+unused staging namespace instead of deleting someone else's cache:
+
+```bash
+remits-cli test run --test "Invoice Tests" --branch promotion-check-empty --variant-branch none --as-account 101
+remits-cli token --path embeddable/index/50 --branch promotion-check-empty --variant-branch none --as-account 101
+```
+
+Here `--branch` is only the CLI staging-cache namespace, and `--variant-branch none` keeps runtime
+resolution on production/subscription semantics. Do **not** use this pattern with `components sync` or
+`components commit`: for those commands `--branch` is the GitHub branch to reconcile.
+
 ### The SDLC is identical on a variant branch
 
 ```bash
@@ -1337,7 +1379,9 @@ remits-cli components sync           # writes ComponentVariant overlays ONLY
 
 Promotion back to trunk is a **git** operation followed by a **trunk** sync — the platform merges nothing
 for you, and merging a branch promotes its **deletions** as hard deletes. Do not improvise it: follow
-`features/subscriber-branch-promotions.md`.
+`features/subscriber-branch-promotions.md`. For a real trunk promotion with many `new_` files, use
+`remits-cli components sync --summary --timeout-ms 300000`; the platform may need longer than the default
+60 seconds to create rows, push rename/meta commits, and regenerate account metadata.
 
 ### Subscribing, unsubscribing, retiring
 
@@ -1662,8 +1706,23 @@ intended and `testAccount:false` for real provisioning. `testAccount:true` means
 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.
+`testAccount:true` for **newly created** accounts (or `testUser:true` for created users).
+
+Read `reusedExisting` before reading anything into the flag. `account_create` is find-or-create, and a
+**test**-lane create can legitimately match a **real** account: real accounts are visible in both lanes,
+so a rehearsal for a name that already exists in prod returns `reusedExisting:true` /
+`testAccount:false` and changes nothing. That is correct reuse, not a lane error. Only
+`reusedExisting:false` with `testAccount:false` in a test rehearsal means the lane was not the one you
+intended. (The prod direction is not symmetrical: a prod-lane create never resolves onto a test
+CLIENT/PROVIDER account, so the same name can exist once per lane.)
+
+**A test-lane account does not get the `code` the prod one will.** `code` is derived from `name` and is
+globally unique, so a test-lane create with no explicit `code` is assigned `test_<code>_<parentId>`.
+A namespace resolves as `databaseName ?: platform.code ?: code`, so a rehearsal **does not prove the
+storage namespace** the real create will land in unless you set `databaseName` explicitly. Conversely,
+passing an explicit `code` in a test rehearsal opts out of the prefix, and the later prod create then
+fails on `code unique:true` — as it also will against a test account created before this rule existed.
+Check the existing account's `code` before assuming a name is free.
 
 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
@@ -2326,6 +2385,23 @@ SELECT parent_id, is_primary, branch_name, database_name, domain_name, active
   FROM account_relationship WHERE account_id = ?;
 ```
 
+**This tool is lane-blind — filter the data lane yourself.** Every other record surface segments test from
+prod data for you; raw SQL does not. `object`, `event`, and `alert` carry a `test_mode` column, `user`
+carries `test_user`, and `account` carries `test_account`, and an unfiltered query returns **both lanes
+mixed** — so "who has access to this account" silently includes throwaway test users, and a row count
+silently includes test fixtures. Add the predicate explicitly:
+
+```sql
+-- prod lane only (legacy rows predate the column, so NULL counts as prod)
+SELECT id, name, status FROM object
+  WHERE account_id = ? AND (test_mode IS NULL OR test_mode = 0);
+
+-- real users of an account, excluding test fixtures
+SELECT u.id, u.username, u.enabled FROM user u
+  JOIN user_account ua ON ua.user_id = u.id
+  WHERE ua.account_id = ? AND (u.test_user IS NULL OR u.test_user = 0);
+```
+
 Prefer the purpose-built tools when one fits — they apply account scoping, data-mode segmentation, and
 resolution awareness that raw SQL does not. Reach for SQL when nothing else models the question.
 
@@ -2453,6 +2529,12 @@ It prints the resolved Account ID, User ID, current git branch, data mode, and b
 prints the same session tuple after the service/dashboard status. Pass `--base-url`, `--account-id`, and
 `--data-mode` when host or lane matters; do not infer those values from the repo directory or account name.
 
+**The reported data mode describes the next `tool` / `tools` / `token` call, not `test run`.** It falls back
+to the stored session lane, whereas `remits-cli test run` deliberately ignores that and defaults to `test`
+unless you pass `--data-mode prod` explicitly. So `whoami` can read `prod` while a test run goes to the test
+lane — which is the safe direction, but not the one you would predict from the output alone. `whoami` says
+so in its own output; when a test run genuinely needs prod data, pass the flag.
+
 ## Persistent Service, Control Center, and Agent Dispatch
 
 The current mental model is a **background remits-cli service**, not just a listener.
@@ -2608,7 +2690,7 @@ remits-cli components branch <name> --subscribers [--json]
 remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>]   # 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> [--names "a,b"] [--watch true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]
+remits-cli test run --test <id|name> [--branch <stagingScope>] [--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>]
@@ -2623,6 +2705,10 @@ For tests specifically:
   (*"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.
   Omit both and the working tree decides — see "Branched Component Variants".
+- `--branch <stagingScope>` on `test run` selects the Redis staging namespace only. It is useful with
+  `--variant-branch none` when an existing staged cache on the real git branch would shadow committed trunk
+  or variant rows. On `components sync` / `commit`, `--branch` is different: it names the GitHub branch to
+  reconcile.
 - `--force-tombstones` is only for non-trunk variant syncs, when missing trunk component files are known,
   intentional tombstone overrides. It is rejected on trunk.
 - `--dry-run` is only for `components sync` on non-trunk variant branches. It reports the variant write
@@ -2694,6 +2780,7 @@ For tests specifically:
 | A variant Test suite fails wholesale, asserting trunk where you expect a variant | You are almost certainly running it from a **variant checkout**: `variantBranch` outranks every subscription, so the suite's own fixture accounts resolve YOUR branch. Re-run from trunk or with `--variant-branch none` before treating it as a regression. |
 | `components sync` on a branch says "No changes detected" but trunk has moved | Re-run it; a trunk sync now invalidates the branch's cached verdict. If it still skips, the branch genuinely matches trunk - check `components branch <name>` for what is actually stored. |
 | After promoting a `new_*` component to trunk, the branch still shows it as `added` | You have not re-synced the branch since the trunk sync. Merge trunk into the branch and `components sync`: the file adopts the promoted id and, if unchanged, removes its own overlay. If the branch carries BOTH `new_Foo.*` and `<id>_Foo.*`, the id file wins and the `new_` one is reported `skipped: superseded` - delete it. |
+| After promoting a standalone Prompt, the branch still shows `OVERRIDDEN prompt:<id>` with only `purpose` changed | The trunk Prompt row does not match repo metadata. Ensure the Prompt sidecar has `description` and `purpose: CUSTOM`, run a platform build that imports Prompt `purpose`, re-sync trunk, merge back, and re-sync the branch. |
 | A branch preview reports a `removed` component nobody deleted | Check whether that component has a file on **trunk**. A DB row with no trunk file is missing from every branch, so it reads as a removal everywhere (and the trunk sync tries to hard-delete it each run). Repair trunk, not the branch. |
 | `--as-account <id>` resolves trunk, or 404s | The account probably has several edges each carrying a branch, so the anchor is ambiguous and the platform refuses to guess. Name the branch with `--variant-branch <name>`, and confirm the edge with `components branch <name> --subscribers`. |
 | A branch variant is reported DRIFTED | The origin component changed after the variant was cut, so the branch is based on a stale version. `remits-cli components branch <name> --diff <id> --component-type <kind>` to compare, then reconcile the branch. |