@remits/remits-cli 0.1.86 → 0.1.87

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +1 -1
  2. package/package.json +1 -1
  3. package/skills/remits-cli/SKILL.md +473 -117
package/README.md CHANGED
@@ -62,7 +62,7 @@ remits-cli install --skills --overwrite true
62
62
  - `components clear` clears staged entries. Scope it with `--component-type` and/or `--component-id`. Component ids are type-local, so an id alone clears that one component when the id is staged in only one family; if the same id is staged across multiple families it returns an ambiguity error asking you to add `--component-type`. With no filter it clears every staged entry for the current branch; pass `--all` to force the full-branch wipe explicitly.
63
63
  - `components stage`, `components status`, and `components clear` print concise summaries by default. Add `--json` or `--verbose` to print the full server response.
64
64
  - `components sync` performs a server-side sync from the git remote into the Remits platform for the selected branch. It does not run local git commands. After a successful non-dry-run sync, the platform clears the branch/user staging scope so staged aliases cannot keep shadowing the newly synced DB rows.
65
- - On trunk, `components sync` performs the full repo-to-DB reconcile. On a non-trunk branch, it writes `ComponentVariant` overlays only. `--dry-run` is accepted only for non-trunk variant syncs and reports overrides/additions/tombstones without writing variants, caching the sync SHA, or clearing staging. `--force-tombstones` is accepted only for non-trunk variant syncs and should be used only when missing trunk component files are intentional tombstone overrides.
65
+ - On trunk, `components sync` performs the full repo-to-DB reconcile. On a non-trunk branch, it writes `ComponentVariant` overlays only and may refresh branch-local `account-info.json` for the subscribing account that initiated the sync. `--dry-run` is accepted only for non-trunk variant syncs and reports overrides/additions/tombstones without writing variants, caching the sync SHA, updating metadata, or clearing staging. `--force-tombstones` is accepted only for non-trunk variant syncs and should be used only when missing trunk component files are intentional tombstone overrides.
66
66
  - `components commit` is a convenience wrapper that performs local git commit/push, then `components sync`, then local `git fetch`/`git pull --ff-only`.
67
67
  - `components sync` returns the post-sync branch SHA produced by the platform. `components commit` verifies that `origin/<branch>` and local `HEAD` both match that exact SHA after the final pull.
68
68
  - `components push` is deprecated and currently behaves the same as `components stage`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@remits/remits-cli",
3
- "version": "0.1.86",
3
+ "version": "0.1.87",
4
4
  "description": "Local CLI for auth, component sync, and live test execution against Remits",
5
5
  "license": "MIT",
6
6
  "private": false,
package/skills/remits-cli/SKILL.md CHANGED
@@ -7,118 +7,212 @@ description: Use remits-cli for fast branch-scoped component staging, test execu
7
7
 
8
8
  ## Table of Contents
9
9
 
10
- - Line 102: Account Targeting Model
11
- - Line 125: Component Integrity Rules: Repo ↔ Database Reconciliation (read before any sync/commit)
12
- - Line 131: How the platform reconciles the repo into the database (the mechanism you must understand)
13
- - Line 186: The surfaces and their intended behavior
14
- - Line 210: Intended workflows
15
- - Line 229: Pre-sync safety check (confirm ALL before `components sync` or `components commit`)
16
- - Line 242: If something looks wrong — stop, don't paper over
17
- - Line 266: Required Local Index Reads
18
- - Line 300: Big Picture: How remits-cli State Is Organized
19
- - Line 330: Support Ticket Mental Model
20
- - Line 366: Efficiency Rules
21
- - Line 378: Account Repository Index
22
- - Line 403: Two Workflows
23
- - Line 410: Test Mode vs Prod Mode
24
- - Line 442: Platform Mental Model: Front Stage vs Back Stage
25
- - Line 449: Documents vs Records
26
- - Line 459: HTTP Audits
27
- - Line 513: Record `content` / Context Mental Model
28
- - Line 533: Provenance Fields
29
- - Line 551: Why Persisted Context Looks Different From Runtime Context
30
- - Line 572: Investigation Rule for Record Context
31
- - Line 587: AI Request Response Records
32
- - Line 594: AI Session Groupings
33
- - Line 613: Correlation Keys
34
- - Line 619: Node Reference Table
35
- - Line 629: Repository vs External Context
36
- - Line 636: Getting Started
37
- - Line 638: Authentication
38
- - Line 651: Host vs Data Mode
39
- - Line 670: Tool Execution Lifecycle
40
- - Line 724: Data Mode
41
- - Line 734: Development Workflow
42
- - Line 736: The Golden Rule: Writing Code Is Not Finishing the Job
43
- - Line 748: Avoid Brittle Front-Stage Intelligence
44
- - Line 761: The Development Fast Loop
45
- - Line 928: User Confirmation Preferences
46
- - Line 938: Component Resolution: Staging Cache vs DB (which "version" actually runs)
47
- - Line 944: The three source layers + the compile cache
48
- - Line 967: Staging cache key format
49
- - Line 982: How the platform picks staged vs DB (the compile signature)
50
- - Line 1004: When staged overrides apply
51
- - Line 1028: Diagnosing which version is in play
52
- - Line 1049: Stage / commit / clear with the MCP tools
53
- - Line 1073: Stale after sync / commit (the in-memory compile cache)
54
- - Line 1083: Account Resolution: how a request travels the account graph
55
- - Line 1153: Branched Component Variants (per-account component overrides)
56
- - Line 1161: The model (three moving parts)
57
- - Line 1228: Which world does your working tree resolve? (read this before you run anything)
58
- - Line 1260: Two levers, two different questions
59
- - Line 1274: The SDLC is identical on a variant branch
60
- - Line 1298: Promotion: getting the branch back into trunk
61
- - Line 1340: Verifying as the subscriber
62
- - Line 1359: Agents (Utility) on a variant branch
63
- - Line 1371: Danger profile on a variant branch (different, not absent)
64
- - Line 1399: Inspecting branches and drift
65
- - Line 1431: Diagnosing a variant
66
- - Line 1438: Production Support Workflow
67
- - Line 1446: Investigation Strategy
68
- - Line 1476: Presenting Findings
69
- - Line 1484: Verifying a Production Issue Fix
70
- - Line 1497: Tool Reference
71
- - Line 1499: Execute a Tool
72
- - Line 1528: `mcp_account_view`
73
- - Line 1546: `mcp_firestore_search`
74
- - Line 1584: `mcp_object_activity`
75
- - Line 1593: `mcp_record_listing`
76
- - Line 1618: `mcp_record_view`
77
- - Line 1631: `mcp_ai_session_search`
78
- - Line 1667: `mcp_run_action`
79
- - Line 1711: `mcp_run_agent`
80
- - Line 1747: `mcp_system_logs`
81
- - Line 1770: `mcp_component_view`
82
- - Line 1793: `mcp_component_grep`
83
- - Line 1806: `mcp_support_ticket`
84
- - Line 1855: `mcp_run_test`
85
- - Line 1864: `mcp_component_edit`
86
- - Line 1879: `mcp_component_create`
87
- - Line 1893: `mcp_component_commit`
88
- - Line 1901: `mcp_cache`
89
- - Line 1913: Multi-Session Support
90
- - Line 1933: Persistent Service, Control Center, and Agent Dispatch
91
- - Line 1942: Starting the Service
92
- - Line 1968: Control Center
93
- - Line 1983: Agent Dispatch
94
- - Line 2004: Configuring the Preferred Agent
95
- - Line 2015: Local State Files
96
- - Line 2063: Command Reference
97
- - Line 2105: Troubleshooting
98
- - Line 2141: When Something Doesn't Work as Expected
10
+ - Line 126: Account Targeting Model
11
+ - Line 133: Account types
12
+ - Line 148: How accounts connect (and why it changes what runs)
13
+ - Line 178: Users are a separate model — don't reason about them as a tree
14
+ - Line 191: Reading the shape
15
+ - Line 207: Repo selection rules
16
+ - Line 219: Component Integrity Rules: Repo ↔ Database Reconciliation (read before any sync/commit)
17
+ - Line 225: How the platform reconciles the repo into the database (the mechanism you must understand)
18
+ - Line 280: The surfaces and their intended behavior
19
+ - Line 304: Intended workflows
20
+ - Line 323: Pre-sync safety check (confirm ALL before `components sync` or `components commit`)
21
+ - Line 336: If something looks wrong — stop, don't paper over
22
+ - Line 360: Required Local Index Reads
23
+ - Line 394: Big Picture: How remits-cli State Is Organized
24
+ - Line 424: Support Ticket Mental Model
25
+ - Line 460: Efficiency Rules
26
+ - Line 472: Account Repository Index
27
+ - Line 497: Two Workflows
28
+ - Line 504: Test Mode vs Prod Mode
29
+ - Line 536: Platform Mental Model: Front Stage vs Back Stage
30
+ - Line 543: Documents vs Records
31
+ - Line 553: HTTP Audits
32
+ - Line 607: Record `content` / Context Mental Model
33
+ - Line 627: Provenance Fields
34
+ - Line 645: Why Persisted Context Looks Different From Runtime Context
35
+ - Line 666: Investigation Rule for Record Context
36
+ - Line 681: AI Request Response Records
37
+ - Line 688: AI Session Groupings
38
+ - Line 707: Correlation Keys
39
+ - Line 713: Node Reference Table
40
+ - Line 723: Repository vs External Context
41
+ - Line 730: Getting Started
42
+ - Line 732: Authentication
43
+ - Line 745: Host vs Data Mode
44
+ - Line 764: Tool Execution Lifecycle
45
+ - Line 818: Data Mode
46
+ - Line 828: Development Workflow
47
+ - Line 830: The Golden Rule: Writing Code Is Not Finishing the Job
48
+ - Line 842: Avoid Brittle Front-Stage Intelligence
49
+ - Line 855: The Development Fast Loop
50
+ - Line 859: Step 1: Understand the Request
51
+ - Line 874: Step 2: Make the Change
52
+ - Line 877: Step 3: Stage to Platform
53
+ - Line 892: Step 4: Verify the Change
54
+ - Line 955: Step 5: Iterate If Needed
55
+ - Line 965: Step 6: Update Documentation
56
+ - Line 975: Step 7: Commit and Durable Sync
57
+ - Line 1013: Step 8: Close the Ticket
58
+ - Line 1028: User Confirmation Preferences
59
+ - Line 1038: Component Resolution: Staging Cache vs DB (which "version" actually runs)
60
+ - Line 1044: The three source layers + the compile cache
61
+ - Line 1067: Staging cache key format
62
+ - Line 1082: How the platform picks staged vs DB (the compile signature)
63
+ - Line 1104: When staged overrides apply
64
+ - Line 1128: Diagnosing which version is in play
65
+ - Line 1149: Stage / commit / clear with the MCP tools
66
+ - Line 1173: Stale after sync / commit (the in-memory compile cache)
67
+ - Line 1183: Account Resolution: how a request travels the account graph
68
+ - Line 1276: Branched Component Variants (per-account component overrides)
69
+ - Line 1284: The model (three moving parts)
70
+ - Line 1351: Which world does your working tree resolve? (read this before you run anything)
71
+ - Line 1383: Two levers, two different questions
72
+ - Line 1397: The SDLC is identical on a variant branch
73
+ - Line 1421: Promotion: getting the branch back into trunk
74
+ - Line 1463: Verifying as the subscriber
75
+ - Line 1482: Agents (Utility) on a variant branch
76
+ - Line 1494: Danger profile on a variant branch (different, not absent)
77
+ - Line 1522: Inspecting branches and drift
78
+ - Line 1554: Diagnosing a variant
79
+ - Line 1561: Production Support Workflow
80
+ - Line 1569: Investigation Strategy
81
+ - Line 1599: Presenting Findings
82
+ - Line 1607: Verifying a Production Issue Fix
83
+ - Line 1620: Tool Reference
84
+ - Line 1622: Execute a Tool
85
+ - Line 1651: `mcp_account_view`
86
+ - Line 1680: `mcp_firestore_search`
87
+ - Line 1718: `mcp_object_activity`
88
+ - Line 1727: `mcp_record_listing`
89
+ - Line 1752: `mcp_record_view`
90
+ - Line 1765: `mcp_ai_session_search`
91
+ - Line 1801: `mcp_run_action`
92
+ - Line 1845: `mcp_run_agent`
93
+ - Line 1881: `mcp_system_logs`
94
+ - Line 1904: `mcp_component_view`
95
+ - Line 1927: `mcp_component_grep`
96
+ - Line 1940: `mcp_support_ticket`
97
+ - Line 1989: `mcp_run_test`
98
+ - Line 1998: `mcp_component_edit`
99
+ - Line 2013: `mcp_component_create`
100
+ - Line 2027: `mcp_component_commit`
101
+ - Line 2035: `mcp_component_branches`
102
+ - Line 2054: `mcp_cache`
103
+ - Line 2066: `mcp_sql_query`
104
+ - Line 2101: `mcp_index_search`
105
+ - Line 2121: `mcp_get_guide`
106
+ - Line 2133: `mcp_test_fixture`
107
+ - Line 2146: `mcp_embeddable_test_url`
108
+ - Line 2158: `mcp_playwright_replay`
109
+ - Line 2173: `mcp_jvm_spike_triage`
110
+ - Line 2186: `mcp_support_ticket_queue`
111
+ - Line 2203: Multi-Session Support
112
+ - Line 2223: Persistent Service, Control Center, and Agent Dispatch
113
+ - Line 2232: Starting the Service
114
+ - Line 2258: Control Center
115
+ - Line 2273: Agent Dispatch
116
+ - Line 2294: Configuring the Preferred Agent
117
+ - Line 2305: Local State Files
118
+ - Line 2353: Command Reference
119
+ - Line 2395: Troubleshooting
120
+ - Line 2436: When Something Doesn't Work as Expected
121
+ - Line 2447: Back-Stage Escalation Workflow (platform defect/limitation)
122
+ - Line 2456: Escalation Bundle (tooling/operational issue)
99
123
 
100
124
  `remits-cli` is the brainstem for both **development** and **production support**. You might run it inside an account repository (where `account-info.json` and `/components` already exist) or from outside any repo when a user needs help on another account. Your users are business professionals — they think in terms of what they can see in a browser.
101
125
 
102
126
  ## Account Targeting Model
103
127
 
104
- Before deciding which repo or account context to use, read the target account's `type` from `account-info.json` or `Account.getInformation` / `mcp_account_view`.
128
+ **Establish the account's shape before you touch anything.** Which repo you work in, which account you run
129
+ against, where a fix belongs, and why one account behaves unlike its siblings are all answered by the account
130
+ structure — never by the account's name. Read it from `account-info.json` (in the repo) or `mcp_account_view`
131
+ (remotely). Both return the same thing.
105
132
 
106
- - **`PLATFORM`** = a use-case/platform implementation account. This is often where the shared Remits components live.
107
- - **`PRODUCT`** = a product/use-case account under a platform. This can also hold shared implementation components.
108
- - **`CLIENT`** = an actual customer account. This is usually where production data lives and where an issue is observed, but not necessarily where the shared implementation is authored.
133
+ ### Account types
109
134
 
110
- Do not guess from the account name alone.
135
+ | Type | What it is | Components | Business data |
136
+ |---|---|---|---|
137
+ | `PLATFORM` | Top of a use-case tree. Owns the shared implementation and the git repository. | **Owned here** | Rarely — mostly configuration |
138
+ | `PRODUCT` | A product/use case under a platform. May own shared components too. | **Owned here or above** | Rarely |
139
+ | `CLIENT` | An actual customer. Where an issue is observed. | Usually **inherited**, not owned | **Here** — the customer's documents and lifecycle records |
140
+ | `PROVIDER` | A partner/vendor participant in a use case | Rarely | Sometimes |
141
+
142
+ - **Feature, enhancement, component change, shared behavior fix** → the implementation target is usually the
143
+ owning `PLATFORM` or `PRODUCT` account, **not** the `CLIENT` that reported it.
144
+ - **Production investigation or client-specific data issue** → start with the affected `CLIENT` account's
145
+ data and runtime history.
146
+ - **Both** → confirm symptoms on the `CLIENT`, then move to the owning `PLATFORM`/`PRODUCT` repo to change code.
147
+
148
+ ### How accounts connect (and why it changes what runs)
149
+
150
+ Components are **inherited downward** and de-duplicated **by component name, nearest owner wins** — so a
151
+ client can run an Action owned three levels up, and can override it just by owning one with the same name.
152
+ Business data does **not** inherit; it belongs to the account that wrote it, in that account's storage
153
+ namespace.
111
154
 
112
- - If the work is a **feature, enhancement, component change, or shared behavior fix**, the implementation target is usually the relevant `PLATFORM` or `PRODUCT` account, not the `CLIENT` account that reported the issue.
113
- - If the work is a **production investigation or client-specific data issue**, start with the affected `CLIENT` account's data and runtime history.
114
- - If the request spans both, investigate in the `CLIENT` account first to confirm symptoms, then move to the owning `PLATFORM` or `PRODUCT` repo before making code changes.
155
+ An account is linked upward in two ways, and they coexist:
115
156
 
116
- Apply these rules before making remote tool calls:
157
+ - **The primary parent** — one per account. The overwhelming majority of accounts have only this.
158
+ - **Membership edges** — extra links letting the *same account* be reached through **more than one** parent
159
+ (a customer in two product lines; a forked deployment reaching the same owner).
117
160
 
118
- - **Inside the target implementation repo**: read `account-info.json` (the same data that `mcp_account_view` returns) and inspect `/components` directly.
119
- - **Inside one repo but supporting a different account**: switch to the correct repo for that account type if available; otherwise use `mcp_account_view` / `mcp_component_view` / `mcp_component_grep`.
161
+ Any link can independently carry three things. They are **orthogonal** — never infer one from another:
162
+
163
+ | Edge property | Means |
164
+ |---|---|
165
+ | `branchName` | **Which code runs** — the component-variant branch this account subscribes to (see "Branched Component Variants") |
166
+ | `databaseName` | **Where data lives** — a storage-namespace override scoped to this link |
167
+ | `domainName` | **Which host reaches it** — a custom hostname that resolves this account *and* this link's parent as the path travelled |
168
+
169
+ Two consequences that generate most "this account is weird" tickets:
170
+
171
+ 1. **The same account can legitimately resolve differently depending on how the request reached it** — a
172
+ different component version, a different namespace, a different host. Establish which path a failing
173
+ request travelled before comparing behavior. (Full detail in "Account Resolution: how a request travels
174
+ the account graph".)
175
+ 2. **An account with no primary parent and several membership edges inherits nothing and runs trunk** until
176
+ a path is named — the platform refuses to guess between equally valid parents. That is by design.
177
+
178
+ ### Users are a separate model — don't reason about them as a tree
179
+
180
+ - A user is **global, keyed by email**. There is no per-account copy of a person.
181
+ - A user **belongs to many accounts** (a membership list, not a parent pointer).
182
+ - A user's **custom fields are per-account**: the same person can be `role: 'Admin'` on one account and
183
+ `role: 'Viewer'` on another. A field written while bound to the wrong account lands on the wrong account.
184
+ - **Access reach is a union over every link** — a user credentialed on a parent can act on an account below
185
+ it through any link, which is deliberately broader than the single-path component inheritance.
186
+
187
+ There is no dedicated user MCP tool. For access questions ("who can see this client account?", "why does
188
+ this user see the wrong data?") use `mcp_sql_query` against `user` / `user_account`, or `account.users([scope:
189
+ 'children'])` from inside a component. See `features/account-management.md` (`mcp_get_guide`).
190
+
191
+ ### Reading the shape
192
+
193
+ `account-info.json` / `mcp_account_view` carry a `resolution` block. Read it in this order:
194
+
195
+ - **`type`** — decide repo/ownership per the table above.
196
+ - **`resolvedDatabaseName`** vs **`databaseName`** — the namespace actually in effect vs the account's own
197
+ override. Check this first when documents are "missing".
198
+ - **`relationships`** — every link upward, primary first, each with its own `branchName` / `databaseName` /
199
+ `domainName`. **This is where you see that an account has two parents, and which link carries what.**
200
+ - **`componentBranch`** (+ `componentBranchOwnerAccountId`) — the component-variant branch this account
201
+ subscribes to, if any. Present only when subscribed.
202
+ - **`branchName`** — the account **repo's** trunk sync branch. Not a component-variant branch. Do not confuse
203
+ these two.
204
+ - **`componentBranches`** (top level) — variant branches this account **owns**, with drift and subscriber
205
+ counts. Check it before editing a shared component.
206
+
207
+ ### Repo selection rules
208
+
209
+ - **Inside the target implementation repo**: read `account-info.json` and inspect `/components` directly.
210
+ - **Inside one repo but supporting a different account**: switch to the correct repo for that account if
211
+ available; otherwise use `mcp_account_view` / `mcp_component_view` / `mcp_component_grep`.
120
212
  - **Outside any repo**: rely on the tools for account structure and component source.
121
- - **Never create a new local repo/directory just because a ticket references an account name.** First resolve the account type and parent hierarchy. Only work from an existing indexed repo unless the user explicitly asks you to create or clone one.
213
+ - **Never create a new local repo/directory just because a ticket references an account name.** First resolve
214
+ the account type and parent hierarchy. Only work from an existing indexed repo unless the user explicitly
215
+ asks you to create or clone one.
122
216
 
123
217
  Use `remits-cli` for everything else: staging changes, running tests, generating embeddable tokens, committing work, and diagnosing production issues.
124
218
 
@@ -144,6 +238,11 @@ local working tree** — and:
144
238
  - **Match / update:** each component is matched to a DB row by the **numeric id prefix of its files**
145
239
  (`58_x.groovy` → component 58), not by name. Matching files overwrite that component's DB fields
146
240
  (source/schema/html/etc.).
241
+ - **Rename:** changing the component's `name:` in `.meta.yml` is supported as a normal update **as long as
242
+ the numeric id prefix stays the same**. On staging, the CLI updates the id/name cache aliases and prunes
243
+ stale old-name aliases for that id. On trunk sync, the platform canonicalizes the repo filenames to the
244
+ current component name (`58_OldName.groovy` with `name: New Name` becomes `58_NewName.groovy`, plus
245
+ sidecars) and reports those moves in `syncResults.renamed`.
147
246
  - **Create:** a file whose id prefix is **not** a live component on the account — including any `new_*` file —
148
247
  is created as a **brand-new DB row with a fresh server-assigned id**, and the platform renames the repo files
149
248
  to that id (the `Rename X→Y after component creation` / `Delete old file` commits).
@@ -175,13 +274,15 @@ local working tree** — and:
175
274
  > nor got renamed."* Check the sidecar's `auxiliary` flag first.
176
275
 
177
276
  **The single most important consequence:** the id in a component's **filename is load-bearing**. If a file's id
178
- no longer matches its DB row (a rename/renumber), the next sync will **create a duplicate at the new id and
179
- hard-delete the original at the old id**. If a component's files are missing from the repo at sync time, that
180
- component is **hard-deleted from the DB**. This is exactly how a prior session deleted live schemas and an
181
- embeddable.
277
+ no longer matches its DB row (a renumber or move across ids), the next sync will **create a duplicate at the
278
+ new id and hard-delete the original at the old id**. If a component's files are missing from the repo at sync
279
+ time, that component is **hard-deleted from the DB**. This is exactly how a prior session deleted live schemas
280
+ and an embeddable.
182
281
 
183
- **Therefore: never renumber, rename-across-ids, or remove component files as a side effect.** Before any sync,
184
- the repo must already mirror the live DB: every live component present at its real id, and nothing extra.
282
+ **Therefore: never renumber, rename-across-ids, or remove component files as a side effect.** Name-only
283
+ renames are fine when every file keeps the same numeric id; either rename the local filename stem yourself or
284
+ let trunk sync canonicalize it from `.meta.yml`. Before any sync, the repo must already mirror the live DB:
285
+ every live component present at its real id, and nothing extra.
185
286
 
186
287
  ### The surfaces and their intended behavior
187
288
 
@@ -191,7 +292,7 @@ the repo must already mirror the live DB: every live component present at its re
191
292
  | `mcp_component_edit` `mode:'stage'` | Redis staging cache for one component/field. | none |
192
293
  | `mcp_component_edit` `mode:'commit'` / `mcp_component_commit` `commit` | Writes the field(s) to the **live DB** for that exact existing component and clears its staging. Does not create/delete other components. | low (scoped to one known component) |
193
294
  | `remits-cli components sync` **on trunk** | **Server-side git→DB reconcile of the whole account** (create/update/**delete**/rename). Reads the pushed remote; ignores local files. | **high** |
194
- | `remits-cli components sync` **on a variant branch** | Writes `ComponentVariant` overlays for that branch only. Never touches trunk rows, `account-info.json`, or the account's trunk branch. `--dry-run` reports the plan without writes. | medium (a missing file becomes a **tombstone** that hides the component from subscribers) |
295
+ | `remits-cli components sync` **on a variant branch** | Writes `ComponentVariant` overlays for that branch only. Never touches trunk rows or the account's trunk branch. When the checkout identifies a subscribing account, the branch-local `account-info.json` is refreshed for that subscriber; `--dry-run` reports the plan without writes. | medium (a missing file becomes a **tombstone** that hides the component from subscribers) |
195
296
  | `remits-cli components commit` | **One shot:** `git add -A` + commit + `git push` + **`components sync`** + `git pull --ff-only`. Blindly stages the *entire* working tree (including any drift) and reconciles it into prod. Inherits the danger of whichever sync mode the branch selects. | **highest on trunk** |
196
297
  | `mcp_component_create` | Writes a **new** component row **directly to the DB** (immediate, new id). | medium (can create duplicates) |
197
298
 
@@ -211,7 +312,9 @@ Key implications:
211
312
 
212
313
  **Change existing components (normal path):**
213
314
  1. Edit files under `components/` **keeping each component's existing numeric id** (use `new_*` only for
214
- genuinely new components).
315
+ genuinely new components). To rename a component, update `name:` in its `.meta.yml`; keep the id prefix
316
+ fixed. Renaming the file stem is optional before trunk sync because the platform will canonicalize it, but
317
+ doing it locally keeps the working tree easier to read.
215
318
  2. `remits-cli components stage` → verify in test mode. Iterate (edit → stage → run).
216
319
  3. When ready to promote: pass the pre-sync safety check below, then
217
320
  `git add -A && git commit && git push`, `remits-cli components sync`, `git pull --ff-only`.
@@ -765,6 +868,12 @@ This is how every development task should flow:
765
868
  #### Step 1: Understand the Request
766
869
  Read the user's request. If you may need a repo other than the current one, read `~/.remits-cli/account-repos.json` first. Then review `account-info.json` and `README.md` to understand what components exist and how they relate. Read the source of any component you'll modify before changing it.
767
870
 
871
+ **Establish the account's shape too, not just its components.** Read the `resolution` block in
872
+ `account-info.json` (or `mcp_account_view`): the account `type` decides whether this repo is even the right
873
+ place to change code, `resolution.relationships` shows whether the account has more than one parent (and
874
+ which link carries a branch/namespace/host), and `resolvedDatabaseName` tells you where its data actually
875
+ lands. See "Account Targeting Model" and `features/account-management.md` (`mcp_get_guide`).
876
+
768
877
  **Also establish which world you are working in.** `remits-cli components status` reports whether the
769
878
  working tree is a **trunk** checkout or a **variant branch** checkout — which decides both what your test
770
879
  runs resolve and what a sync writes. If `account-info.json` carries a `componentBranches` section, branch
@@ -774,6 +883,41 @@ variants of these components exist: editing an origin component will drift them,
774
883
  #### Step 2: Make the Change
775
884
  Edit component files under `components/`. This is local file editing — the platform doesn't know about your changes yet.
776
885
 
886
+ **Creating a component that does not exist yet.** Files are named `<id>_<Name>.<ext>`, where the numeric
887
+ prefix is the platform's component id. A new component has no id, so name its files with the **`new_`
888
+ prefix** and let the sync assign one (it then renames the files to that id):
889
+
890
+ ```
891
+ components/embeddables/new_MerchantPortal.groovy # source
892
+ components/embeddables/new_MerchantPortal.html # markup
893
+ components/embeddables/new_MerchantPortal.js # client script
894
+ components/embeddables/new_MerchantPortal.meta.yml # metadata sidecar
895
+ ```
896
+
897
+ **Do NOT put an `id:` in a new component's sidecar.** `id` is what links a sidecar to an *existing*
898
+ component and is parsed as a number, so a placeholder (`id: new`, `id: TBD`) fails the **entire**
899
+ stage/sync request with a `NumberFormatException` — not just that one file, and the error does not name
900
+ the file. Omit the key; the platform fills it in on sync:
901
+
902
+ ```yaml
903
+ # components/embeddables/new_MerchantPortal.meta.yml — no `id:` yet
904
+ name: Merchant Portal
905
+ summary: One-line statement of what this component is for.
906
+ description: |
907
+ Longer technical description with line-number references to the key logic.
908
+ path: /page/merchant-portal # Readers and Embeddables only
909
+ category: default
910
+ auxiliary: false # `true` means the sync SKIPS the file entirely — see Auxiliary
911
+ mermaid: |
912
+ graph TD
913
+ A[Request] --> B[Load documents]
914
+ ```
915
+
916
+ > **Staging creates nothing in the database, so a `new_` component has no id yet — address it BY NAME.**
917
+ > `remits-cli test run --test "My Suite"`, not `--test <id>`. Component-to-component resolution and
918
+ > request-level addressing are name-based too; the component guides cover those. After a trunk sync the
919
+ > component has a real id and either form works.
920
+
777
921
  #### Step 3: Stage to Platform
778
922
 
779
923
  ```bash
@@ -806,7 +950,9 @@ Important test-runner constraints:
806
950
 
807
951
  If no relevant Test component exists yet, consider creating one. Test components live in `components/tests/` and follow the same component structure. They provide permanent regression protection — every test you write today saves debugging time tomorrow.
808
952
 
809
- New test files use the `new_` prefix (e.g., `new_MyTest.groovy`). New tests have no database ID, so you must run them **by name**: `remits-cli test run --test "My Test"`. After committing, the platform assigns an ID and renames the file (e.g., `4_MyTest.groovy`) — then you can run by either ID or name.
953
+ New test files use the `new_` prefix (e.g., `new_MyTest.groovy`) and no `id:` in the sidecar — see "Creating a component that does not exist yet" in Step 2. Run them **by name** (`remits-cli test run --test "My Test"`) until a sync assigns an id and renames the file.
954
+
955
+ **How to write the Test itself is not a CLI concern** — what a suite can assert, how mocks behave across HTTP/relay boundaries, driving an embeddable in-process, and the front-stage-only rule all live in `guides/components/test-components.md`. Read that before authoring a suite.
810
956
 
811
957
  **Option B — Visual verification with Playwright** (for UI changes or when the user wants to "see it"):
812
958
 
@@ -870,7 +1016,9 @@ Before committing, update metadata so the next session understands what changed:
870
1016
  2. **`README.md`** — If the change affects account-level capabilities or workflows.
871
1017
  3. **New components** — Always fill in `.meta.yml` immediately.
872
1018
 
873
- `account-info.json` is read-only — never edit it. It regenerates automatically after sync.
1019
+ `account-info.json` is read-only — never edit it. It regenerates automatically after sync. On a trunk sync it
1020
+ describes the owning repo account. On a subscriber-initiated variant sync it describes the subscribing
1021
+ account reached through the branch edge, even though the component files still belong to the owner's repo.
874
1022
 
875
1023
  #### Step 7: Commit and Durable Sync
876
1024
 
@@ -1139,17 +1287,40 @@ disambiguate it by branch name; from the CLI you supply it explicitly.
1139
1287
  legitimately resolve a different component variant *and* a different data segment. When you investigate
1140
1288
  such an account, always establish which anchor the failing request used before comparing behavior.
1141
1289
 
1290
+ **How to actually see an account's edges.** `mcp_account_view` (and the repo's `account-info.json`) returns
1291
+ `resolution.relationships` — one entry per structural link, primary first, each carrying its own
1292
+ `branchName` / `databaseName` / `domainName`. The hierarchy tree flattens every link into one shape, so this
1293
+ block is the only place that answers "how many parents does this account really have, and which link carries
1294
+ what?" Start here for any resolution question:
1295
+
1296
+ ```bash
1297
+ remits-cli tool --name mcp_account_view --input '{"accountId": 101}' --data-mode prod
1298
+ # then read: resolution.relationships, resolution.resolvedDatabaseName, resolution.componentBranch
1299
+ ```
1300
+
1142
1301
  **Practical checklist when a subscription "doesn't work":**
1143
1302
 
1144
- 1. Does the account have a `parentId`, or is it membership-only? (Membership-only + multiple edges ⇒
1303
+ 1. Does the account have a primary parent, or is it membership-only? Count the entries in
1304
+ `resolution.relationships` and check which one is `primary: true`. (Membership-only + multiple edges ⇒
1145
1305
  ambiguous ⇒ trunk.)
1146
- 2. Which **edge** carries the `branchName` — `remits-cli components branch <name> --subscribers` prints
1147
- `via primary|membership edge -> parent N`.
1306
+ 2. Which **edge** carries the `branchName` — it is on the edge in `resolution.relationships`, and
1307
+ `remits-cli components branch <name> --subscribers` prints `via primary|membership edge -> parent N`.
1148
1308
  3. Was the run anchored through *that* edge's parent? Re-run with `--as-account <subscriberId>` so the
1149
1309
  account's own edge selects the branch, exactly as production would.
1150
1310
  4. Check the resolved layer, not the source text: `testComponentSource` / the `variant:<id>:<hash>`
1151
1311
  compile signature (see "Diagnosing a variant").
1152
1312
 
1313
+ **The same block answers the non-branch resolution questions too:** "why are this account's documents not
1314
+ where I expect?" → compare `databaseName` vs `resolvedDatabaseName` and any edge `databaseName`. "Why does
1315
+ this hostname land on the wrong account?" → `domainName` vs `resolvedDomainName` and the edge `domainName`
1316
+ (an edge host wins over the account's own, and additionally supplies the path travelled).
1317
+
1318
+ **Users are not part of this graph.** A user is global, belongs to many accounts, and can reach an account
1319
+ below one they are credentialed on through **any** link — a deliberately broader rule than the single-path
1320
+ component inheritance above. Their custom fields (`role`, `team`, …) are stored **per account**, so the same
1321
+ person can differ per account. There is no user MCP tool: use `mcp_sql_query` against `user` /
1322
+ `user_account`, and read `features/account-management.md` (`mcp_get_guide`) for the model.
1323
+
1153
1324
  ## Branched Component Variants (per-account component overrides)
1154
1325
 
1155
1326
  Sometimes one account — often a customer nested several levels down a hierarchy — needs *slightly*
@@ -1257,6 +1428,18 @@ Working tree: VARIANT BRANCH "feature_forked" (trunk is "main")
1257
1428
  subscribing accounts: 101 (Acme Child)
1258
1429
  ```
1259
1430
 
1431
+ **Branch-local `account-info.json` can describe a subscriber.** On a variant branch, the same git repository
1432
+ is still the OWNER's component repo: files under `components/` overlay that owner's trunk component ids, and
1433
+ `components sync` writes `ComponentVariant` rows owned by that parent account. But if the checkout was synced
1434
+ from a subscribing account reached through an `AccountRelationship` edge, the branch's `account-info.json`
1435
+ is intentionally refreshed from the subscriber's resolved account information. That is what lets a forked
1436
+ checkout answer "who am I acting as?" while preserving "who owns these component variants?"
1437
+
1438
+ Consequence: if a variant checkout's `account-info.json` is stale and still names the owner, run the first
1439
+ repair sync with an explicit subscriber target, for example `remits-cli components sync --account-id 101`.
1440
+ After that sync and `git pull --ff-only`, normal commands from that checkout should resolve the subscriber
1441
+ from `account-info.json` and continue writing variants under the owner selected by the branch edge.
1442
+
1260
1443
  ### Two levers, two different questions
1261
1444
 
1262
1445
  - **`--as-account <id>`** changes **who** the run executes as, so that account's own edge picks the branch.
@@ -1291,9 +1474,10 @@ Two things that differ from trunk:
1291
1474
 
1292
1475
  - **Keep the origin id in the filename.** `50_ExtractInvoice.groovy` on the branch overlays Action 50. That
1293
1476
  is what preserves component identity and lets drift be computed against the origin.
1294
- - **Nothing is renamed.** A variant sync never renames files, never regenerates `account-info.json`, and
1295
- never repoints the account's trunk branch. A `new_*` file stays `new_*` and becomes a branch-only
1296
- component keyed by name.
1477
+ - **Nothing is renamed.** A variant sync never renames files and never repoints the account's trunk branch.
1478
+ When launched from a subscribing account, it may refresh that branch's `account-info.json` so the checkout
1479
+ describes the account reached through the branch edge. A `new_*` file stays `new_*` and becomes a
1480
+ branch-only component keyed by name.
1297
1481
 
1298
1482
  ### Promotion: getting the branch back into trunk
1299
1483
 
@@ -1536,9 +1720,20 @@ its behavior against component source:
1536
1720
  `resolvedDomainName` (the custom host in effect, which differs when reached through an edge host),
1537
1721
  `editMode`, and — when the account subscribes to a component branch — `componentBranch` plus
1538
1722
  `componentBranchOwnerAccountId`.
1723
+ - `resolution.relationships` — **every structural link upward**, primary first: `parentAccountId` /
1724
+ `parentAccountName` / `parentAccountCode` / `parentAccountType`, `primary` (true for the one link that
1725
+ mirrors the account's primary parent), `active`, and the three independent link-scoped properties
1726
+ `branchName` (which component-variant code runs), `databaseName` (where data lives), `domainName` (which
1727
+ host reaches the account through this link). The hierarchy tree flattens all links into one shape, so this
1728
+ is the **only** place that answers "does this account have more than one parent, and which link carries the
1729
+ branch/namespace/host?" More than one entry ⇒ this account can resolve differently depending on the path a
1730
+ request travelled — establish which one a failing request used before comparing behavior.
1539
1731
  - `componentBranches` — the variant branches this account OWNS, with override/add/remove, subscriber, and
1540
1732
  drift counts. Same summary the owner's `account-info.json` carries.
1541
1733
 
1734
+ Note: this tool does **not** return users. For user/access questions use `mcp_sql_query` (`user`,
1735
+ `user_account`).
1736
+
1542
1737
  | Parameter | Required | Description |
1543
1738
  |-----------|----------|-------------|
1544
1739
  | `accountId` | yes | Account ID |
@@ -1898,6 +2093,25 @@ Inspect, flush, or clear the CLI staging cache for components.
1898
2093
  | `accountId` | yes | Account ID |
1899
2094
  | `action` | yes | `read` (list staged entries), `commit` (flush staged → DB), or `clear` (drop staged entries without touching the DB) |
1900
2095
 
2096
+ ### `mcp_component_branches`
2097
+ The MCP counterpart of `remits-cli components branches` / `components branch <name>` — use it when you are
2098
+ driving the platform **remotely** (no local repo/checkout) and need to know whether a component already has
2099
+ committed branch variants, who subscribes, and whether they have drifted.
2100
+
2101
+ | Parameter | Required | Description |
2102
+ |-----------|----------|-------------|
2103
+ | `action` | no | `list` (default) — every branch this owner has variants on, with drift + subscriber counts; `status` — one branch's overridden/added/removed; `diff` — one component's variant beside current trunk; `subscribers` — accounts resolving a branch; `subscribe`/`unsubscribe` — set/clear the branch on a subscriber's existing relationship edge; `retire` — delete a branch's overlays |
2104
+ | `ownerAccountId` | no | The account whose branches are inspected. **Outranks `accountId`**, because `accountId` also selects which account the tool is resolved on — so `accountId` alone cannot target another account's branches. |
2105
+ | `branchName` | conditional | Required for everything except `list`. Alias: `branch`. |
2106
+ | `componentId` / `componentName` / `componentType` | conditional | Address the component for `diff` |
2107
+ | `targetAccountId` | conditional | The account to subscribe/unsubscribe |
2108
+ | `parentAccountId` | no | Which relationship edge to set the branch on. Without it: the edge toward the branch owner, then the target's primary edge. |
2109
+ | `force` | no | `retire` only — proceed while subscribers remain |
2110
+
2111
+ Same rules as the CLI: `subscribe` only **sets the branch on an edge that already exists** (creating a
2112
+ membership edge is an admin operation), authorization is downward-only, and `retire` refuses while
2113
+ subscribers remain unless forced.
2114
+
1901
2115
  ### `mcp_cache`
1902
2116
  Bounded read-only investigation of the platform Redis keyspace — the way to see exactly what a staged
1903
2117
  entry holds (and its TTL) or any other cache key. Read-only: no delete (use `mcp_component_commit clear`
@@ -1910,6 +2124,143 @@ to remove staged entries).
1910
2124
  | `key` | no | Exact key for `action:'inspect'` |
1911
2125
  | `pageSize`/`sampleSize`/`previewChars` | no | Bounding controls |
1912
2126
 
2127
+ ### `mcp_sql_query`
2128
+ Read-only, bounded SQL against the platform database. This is the **catch-all investigation surface** for
2129
+ questions the purpose-built tools do not model — above all **users and account membership**, for which there
2130
+ is no dedicated tool.
2131
+
2132
+ | Parameter | Required | Description |
2133
+ |-----------|----------|-------------|
2134
+ | `query` | yes* | One read-only statement. Alias: `sql`. Must start with `SELECT`, `WITH`, `SHOW`, `DESCRIBE`/`DESC`, or `EXPLAIN`; mutation, DDL, locking, and filesystem constructs are rejected. |
2135
+ | `queries` | yes* | Batch of up to 10 read-only queries (strings, or `{query, params}` objects) |
2136
+ | `params` / `parameters` | no | Positional parameters — **use these instead of interpolating values** |
2137
+ | `maxRows` / `limit` | no | Rows per query. Default 100, max 500. |
2138
+ | `maxValueChars` | no | Truncation width per string value. Default 2000, max 20000. |
2139
+ | `redact` | no | Redact secret-like columns (`password`, `token`, `secret`, `authorization`, …). **Default true — leave it on.** |
2140
+
2141
+ *Provide `query`/`sql` or `queries`.
2142
+
2143
+ Useful shapes:
2144
+
2145
+ ```sql
2146
+ -- who has access to a client account (and through which membership rows)
2147
+ SELECT u.id, u.username, u.enabled FROM user u
2148
+ JOIN user_account ua ON ua.user_id = u.id WHERE ua.account_id = ?;
2149
+
2150
+ -- every account a user can reach directly
2151
+ SELECT a.id, a.name, a.type FROM account a
2152
+ JOIN user_account ua ON ua.account_id = a.id WHERE ua.user_id = ?;
2153
+
2154
+ -- the account's structural links, including membership edges (`primary` is column `is_primary`)
2155
+ SELECT parent_id, is_primary, branch_name, database_name, domain_name, active
2156
+ FROM account_relationship WHERE account_id = ?;
2157
+ ```
2158
+
2159
+ Prefer the purpose-built tools when one fits — they apply account scoping, data-mode segmentation, and
2160
+ resolution awareness that raw SQL does not. Reach for SQL when nothing else models the question.
2161
+
2162
+ ### `mcp_index_search`
2163
+ Query and **diagnose** the Vertex AI Search index through the platform's Vertex DSL. Use it to check what a
2164
+ RAG/search-backed component actually retrieves before blaming the component.
2165
+
2166
+ | Parameter | Required | Description |
2167
+ |-----------|----------|-------------|
2168
+ | `accountId` | yes | Tenant scoping |
2169
+ | `action` | no | `search` (default, `index_search()`), `facets` (`index_facets()` — taxonomy/distinct values), `diagnose` (explain why strict filtering dropped matches), `inspect` (what is actually indexed for given `sourceDocumentIds`) |
2170
+ | `query` | conditional | Required for `search`/`diagnose` |
2171
+ | `schema` / `projectionType(s)` / `projectionSource` | no | Scope to a schema's Vertex projections |
2172
+ | `filters` | no | Vertex-style structured filters on indexed metadata |
2173
+ | `pageSize` / `maxResults` / `pageToken` | no | Paging and local trimming |
2174
+ | `searchProfile` | no | `ai`/`agent`/`strict` (precision) vs `admin`/`default` (recall) |
2175
+ | `includeMatchDiagnostics` | no | Return the applied filter/query plus the pre-strict-filter candidate set |
2176
+ | `accountIds` | no | Explicit multi-account search |
2177
+ | `dataMode` | no | `test` (default) or `prod` |
2178
+
2179
+ When a component "can't find" an obviously-present document, run `action:'inspect'` on its source document id
2180
+ first — that shows what was indexed, which is usually the answer.
2181
+
2182
+ ### `mcp_get_guide`
2183
+ Load the packaged front-stage guides — the same `docs/guides/` set `remits-cli` syncs into a repo. Use it when
2184
+ you are working **outside a repo** (or the repo's `guides/` is stale) and need the authoritative guidance
2185
+ before writing a component.
2186
+
2187
+ | Parameter | Required | Description |
2188
+ |-----------|----------|-------------|
2189
+ | `guide` | conditional | Short name (`agent-components`), relative path (`features/account-management`), or full path |
2190
+ | `list` | no | List available guides instead of loading one |
2191
+ | `directory` | no | Scope a list to `components` or `features` |
2192
+ | `contains` | no | Substring filter when listing |
2193
+
2194
+ ### `mcp_test_fixture`
2195
+ Seed and remove schema-backed fixture documents in the **forced test** data segment. This is how you construct
2196
+ realistic conditions for verification without copying live customer data.
2197
+
2198
+ | Parameter | Required | Description |
2199
+ |-----------|----------|-------------|
2200
+ | `accountId` | yes | Account owning the target schema/collection |
2201
+ | `action` | no | `create` (fails on existing id), `upsert`, or `delete` |
2202
+ | `schemaName` / `collection` | conditional | Schema display name or collection name |
2203
+ | `documentId` / `documentIds` | no | Explicit Firestore ids for single/batch operations |
2204
+ | `data` / `documents` | conditional | Single payload, or a batch array |
2205
+ | `dataMode` | no | Must be `test` — **prod-mode writes are rejected** |
2206
+
2207
+ ### `mcp_embeddable_test_url`
2208
+ Mint an authenticated browser URL for an embeddable — the MCP counterpart of `remits-cli token --path
2209
+ embeddable/index/<id>`. Returns the URL plus branch/variant/data-mode hints so you know which world the page
2210
+ will render.
2211
+
2212
+ | Parameter | Required | Description |
2213
+ |-----------|----------|-------------|
2214
+ | `accountId` | yes | Account owning the embeddable |
2215
+ | `embeddableId` / `embeddableName` | conditional | Provide one |
2216
+ | `userId` | no | User to mint for. Defaults to the current user. |
2217
+ | `variantBranch` | no | Probe a committed component-variant branch. Usually inherited from the caller. |
2218
+
2219
+ ### `mcp_playwright_replay`
2220
+ Hosted browser automation (the `playwright-relay` service) for visual verification when local `playwright-cli`
2221
+ is unavailable — e.g. an agent running remotely. Returns an accessibility snapshot and interactive refs on
2222
+ every command, so you navigate iteratively.
2223
+
2224
+ | Parameter | Required | Description |
2225
+ |-----------|----------|-------------|
2226
+ | `command` | yes | `open`, `goto`, `snapshot`, `click`, `dblclick`, `hover`, `fill`, `select`, `check`, `uncheck`, `eval`, `run-code`, `screenshot`, `pdf`, `console`, `network`, `go-back`, `go-forward`, `reload`, `tab-*`, `close`, `close-all` |
2227
+ | `sessionId` | conditional | Reuse an existing session. `open`/`goto` without one starts a session. |
2228
+ | `url` / `target` / `value` / `expression` / `code` | conditional | Per-command inputs (`target` is an element ref or selector) |
2229
+ | `compact` | no | Default true — omits bulky raw relay payloads |
2230
+ | `includeSnapshot` / `includeAccessibility` / `includeRefs` / `includePage` / `includeResult` / `includeRaw` | no | Response shaping |
2231
+ | `pattern` / `level` / `limit` | no | Filters for `console` / `network` |
2232
+ | `ticketId` / `artifactType` / `artifactLabel` / `artifactNotes` | no | Attach a screenshot/pdf/trace/video to a support ticket |
2233
+
2234
+ ### `mcp_jvm_spike_triage`
2235
+ Production-aware triage bundle for a Cloud Run service showing a latency/memory spike. Safe by construction:
2236
+ optional class-histogram sampling, **no heap dump and no JFR**.
2237
+
2238
+ | Parameter | Required | Description |
2239
+ |-----------|----------|-------------|
2240
+ | `serviceName` | yes | e.g. `remits`, `remits-actions` |
2241
+ | `region` | yes | e.g. `us-east5`, `us-east1` |
2242
+ | `sampleHeap` | no | Default true — one class histogram + heap composition sample (brief stop-the-world) |
2243
+ | `top` | no | Top classes to return. Default 20, max 100. |
2244
+ | `includeThreadDump` / `threadLimit` | no | Fuller thread dump beyond the built-in top-thread preview |
2245
+ | `includeLogs` / `logLookbackMinutes` / `logLimit` | no | Recent WARNING+ log signals for the same service |
2246
+
2247
+ ### `mcp_support_ticket_queue`
2248
+ List and filter tickets **across an account and its descendants** so you can choose what to work on. Lifecycle
2249
+ actions stay on `mcp_support_ticket`.
2250
+
2251
+ | Parameter | Required | Description |
2252
+ |-----------|----------|-------------|
2253
+ | `action` | no | `list` (default) |
2254
+ | `accountId` / `accountIds` / `includeChildren` / `includeRoot` | no | Queue scope. Defaults to the current account **and its descendants**. |
2255
+ | `statuses` / `status` | no | Defaults to `open`, `accepted`, `in_progress`, `pending_review`. `['all']` disables filtering. |
2256
+ | `priorities` / `types` / `sources` / `tags` | no | Additional filters |
2257
+ | `assignedTo` / `unassigned` | no | Assignment filters |
2258
+ | `implementationAccountId` | no | Filter by owning `PLATFORM`/`PRODUCT` account |
2259
+ | `search` | no | Case-insensitive across subject, description, account, affected component, sender, tags |
2260
+ | `sortBy` / `sortDirection` | no | `triage` (default-style: critical/high unassigned first), `updated`, `priority`, `status`, `account` |
2261
+ | `limit` / `offset` / `scanLimitPerAccount` | no | Paging and scan bounds |
2262
+ | `dataMode` | no | Normal agent work uses the **prod** ticket queue |
2263
+
1913
2264
  ## Multi-Session Support
1914
2265
 
1915
2266
  The CLI supports multiple authenticated sessions simultaneously. Sessions are stored in `~/.remits-cli/sessions.json` as a map keyed by `accountId + dataMode + baseUrl`, so the same account can stay authenticated against both localhost and production without one session overwriting the other. When you run any command from an account repo, the CLI automatically resolves the best matching session based on the `account-info.json` in that directory and any `--base-url` or `--data-mode` flags provided. If the same account is authenticated against multiple hosts and you omit `--base-url`, the CLI may legitimately choose either localhost or a deployed host depending on the best session match, so agents should treat `--base-url` as mandatory whenever host matters.
@@ -2120,6 +2471,11 @@ For tests specifically:
2120
2471
  | 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. |
2121
2472
  | 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`. |
2122
2473
  | 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". |
2474
+ | Need to know an account's shape (type, parents, namespace, branch) | `mcp_account_view` → read `resolution` (`type`, `resolvedDatabaseName`, `relationships`, `componentBranch`) and top-level `componentBranches`. Never infer structure from the account's name. |
2475
+ | 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. |
2476
+ | 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. |
2477
+ | 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). |
2478
+ | 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. |
2123
2479
  | 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. |
2124
2480
  | 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. |
2125
2481
  | 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. |