@remits/remits-cli 0.1.86 → 0.1.89

package/README.md

@@ -29,10 +29,10 @@ git add -A
 git commit -m "sync passing changes"
 git push
 remits-cli components sync
-remits-cli components sync --branch feature_forked --dry-run
-remits-cli components sync --branch feature_forked --force-tombstones
+remits-cli components sync --branch feature_branch --dry-run
+remits-cli components sync --branch feature_branch --force-tombstones
 remits-cli token --path page/my-embeddable
-remits-cli token --path page/my-embeddable --variant-branch feature_forked
+remits-cli token --path page/my-embeddable --variant-branch feature_branch
 remits-cli data-mode
 remits-cli data-mode set prod
 remits-cli sessions list
@@ -62,11 +62,11 @@ remits-cli install --skills --overwrite true
 - `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.
 - `components stage`, `components status`, and `components clear` print concise summaries by default. Add `--json` or `--verbose` to print the full server response.
 - `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.
-- 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.
+- 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.
 - `components commit` is a convenience wrapper that performs local git commit/push, then `components sync`, then local `git fetch`/`git pull --ff-only`.
 - `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.
 - `components push` is deprecated and currently behaves the same as `components stage`.
-- `accountId` resolution for CLI commands: explicit `--account-id` flag wins, then the current repo's `account-info.json`, then the active session. For `remits-cli tool` calls the server applies a further precedence — explicit `--account-id` > `input.accountId` > session/repo default — so a tool can execute against a different account than the surrounding repo.
+- `accountId` resolution for CLI commands: explicit `--account-id` flag wins, then the current repo's `account-info.json` (`resolution.accountId`, then the short-lived `repoContext.accountInfoAccountId`, then the legacy top-level id — legacy files are rooted at the hierarchy ROOT, so their top-level `id` may be an ancestor), then the active session. For `remits-cli tool` calls the server applies a further precedence — explicit `--account-id` > `input.accountId` > session/repo default — so a tool can execute against a different account than the surrounding repo.
 - Auth sessions are stored per `accountId + dataMode + baseUrl`, so the same account can stay authenticated against both localhost and production without overwriting the other session.
 - `--base-url` and `--data-mode` are independent. `--base-url` chooses the Remits host (`http://localhost:8080` vs deployed prod), while `--data-mode` chooses the data segment on that host (`test` vs `prod`). Do not assume `--data-mode prod` means the deployed prod host, or that `--data-mode test` means localhost.
 - `remits-cli start` scans the machine for `account-info.json` files and rebuilds `~/.remits-cli/account-repos.json` before bringing up the background service.

package/index.js

@@ -477,7 +477,21 @@ function loadAccountId(cwd) {
     throw new Error('account-info.json not found in current directory');
   }
   const data = JSON.parse(fs.readFileSync(file, 'utf8'));
-  return Number(data.id || data.accountId || (data.account && data.account.id));
+  return Number(accountIdFromAccountInfo(data));
+}
+
+// `resolution.accountId` is the account the export DESCRIBES, and the only key that is unambiguous in
+// every shape: a legacy account-info.json is rooted at the hierarchy ROOT, so its top-level `id` is an
+// ancestor, not this repo's account. `repoContext` is a short-lived earlier name for the same fact and is
+// still read so checkouts written during that window keep resolving.
+function accountIdFromAccountInfo(info) {
+  return (info && (
+    (info.resolution && info.resolution.accountId) ||
+    (info.repoContext && info.repoContext.accountInfoAccountId) ||
+    info.id ||
+    info.accountId ||
+    (info.account && info.account.id)
+  )) || null;
 }
 
 function loadAccountInfo(cwd) {
@@ -512,14 +526,23 @@ function buildAccountRepoEntryFromInfo(info, directory, source = 'discovered') {
   if (!info || typeof info !== 'object') {
     return null;
   }
-  const accountId = Number(info.id || info.accountId || (info.account && info.account.id));
+  const accountId = Number(accountIdFromAccountInfo(info));
   if (!Number.isFinite(accountId) || accountId <= 0) {
     return null;
   }
   return {
     accountId,
-    name: info.name || info.accountName || (info.account && info.account.name) || '',
-    type: info.type || info.accountType || (info.account && info.account.type) || null,
+    name: (info.resolution && info.resolution.accountName) ||
+      (info.repoContext && info.repoContext.accountInfoAccountName) ||
+      info.name ||
+      info.accountName ||
+      (info.account && info.account.name) ||
+      '',
+    type: (info.resolution && info.resolution.type) ||
+      info.type ||
+      info.accountType ||
+      (info.account && info.account.type) ||
+      null,
     platformAccountId: info.platformAccountId || (info.platform && info.platform.id) || null,
     directory: path.resolve(directory),
     accountInfoPath: path.join(path.resolve(directory), 'account-info.json'),

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -7,118 +7,223 @@ description: Use remits-cli for fast branch-scoped component staging, test execu
 
 ## Table of Contents
 
-- Line 102: Account Targeting Model
-- Line 125: Component Integrity Rules: Repo ↔ Database Reconciliation (read before any sync/commit)
-- Line 131: How the platform reconciles the repo into the database (the mechanism you must understand)
-- Line 186: The surfaces and their intended behavior
-- Line 210: Intended workflows
-- Line 229: Pre-sync safety check (confirm ALL before `components sync` or `components commit`)
-- Line 242: If something looks wrong — stop, don't paper over
-- Line 266: Required Local Index Reads
-- Line 300: Big Picture: How remits-cli State Is Organized
-- Line 330: Support Ticket Mental Model
-- Line 366: Efficiency Rules
-- Line 378: Account Repository Index
-- Line 403: Two Workflows
-- Line 410: Test Mode vs Prod Mode
-- Line 442: Platform Mental Model: Front Stage vs Back Stage
-- Line 449: Documents vs Records
-- Line 459: HTTP Audits
-- Line 513: Record `content` / Context Mental Model
-- Line 533: Provenance Fields
-- Line 551: Why Persisted Context Looks Different From Runtime Context
-- Line 572: Investigation Rule for Record Context
-- Line 587: AI Request Response Records
-- Line 594: AI Session Groupings
-- Line 613: Correlation Keys
-- Line 619: Node Reference Table
-- Line 629: Repository vs External Context
-- Line 636: Getting Started
-- Line 638: Authentication
-- Line 651: Host vs Data Mode
-- Line 670: Tool Execution Lifecycle
-- Line 724: Data Mode
-- Line 734: Development Workflow
-- Line 736: The Golden Rule: Writing Code Is Not Finishing the Job
-- Line 748: Avoid Brittle Front-Stage Intelligence
-- Line 761: The Development Fast Loop
-- Line 928: User Confirmation Preferences
-- Line 938: Component Resolution: Staging Cache vs DB (which "version" actually runs)
-- Line 944: The three source layers + the compile cache
-- Line 967: Staging cache key format
-- Line 982: How the platform picks staged vs DB (the compile signature)
-- Line 1004: When staged overrides apply
-- Line 1028: Diagnosing which version is in play
-- Line 1049: Stage / commit / clear with the MCP tools
-- Line 1073: Stale after sync / commit (the in-memory compile cache)
-- Line 1083: Account Resolution: how a request travels the account graph
-- Line 1153: Branched Component Variants (per-account component overrides)
-- Line 1161: The model (three moving parts)
-- Line 1228: Which world does your working tree resolve? (read this before you run anything)
-- Line 1260: Two levers, two different questions
-- Line 1274: The SDLC is identical on a variant branch
-- Line 1298: Promotion: getting the branch back into trunk
-- Line 1340: Verifying as the subscriber
-- Line 1359: Agents (Utility) on a variant branch
-- Line 1371: Danger profile on a variant branch (different, not absent)
-- Line 1399: Inspecting branches and drift
-- Line 1431: Diagnosing a variant
-- Line 1438: Production Support Workflow
-- Line 1446: Investigation Strategy
-- Line 1476: Presenting Findings
-- Line 1484: Verifying a Production Issue Fix
-- Line 1497: Tool Reference
-- Line 1499: Execute a Tool
-- Line 1528: `mcp_account_view`
-- Line 1546: `mcp_firestore_search`
-- Line 1584: `mcp_object_activity`
-- Line 1593: `mcp_record_listing`
-- Line 1618: `mcp_record_view`
-- Line 1631: `mcp_ai_session_search`
-- Line 1667: `mcp_run_action`
-- Line 1711: `mcp_run_agent`
-- Line 1747: `mcp_system_logs`
-- Line 1770: `mcp_component_view`
-- Line 1793: `mcp_component_grep`
-- Line 1806: `mcp_support_ticket`
-- Line 1855: `mcp_run_test`
-- Line 1864: `mcp_component_edit`
-- Line 1879: `mcp_component_create`
-- Line 1893: `mcp_component_commit`
-- Line 1901: `mcp_cache`
-- Line 1913: Multi-Session Support
-- Line 1933: Persistent Service, Control Center, and Agent Dispatch
-- Line 1942: Starting the Service
-- Line 1968: Control Center
-- Line 1983: Agent Dispatch
-- Line 2004: Configuring the Preferred Agent
-- Line 2015: Local State Files
-- Line 2063: Command Reference
-- Line 2105: Troubleshooting
-- Line 2141: When Something Doesn't Work as Expected
+- Line 127: Account Targeting Model
+- Line 134: Account types
+- Line 149: How accounts connect (and why it changes what runs)
+- Line 179: Users are a separate model — don't reason about them as a tree
+- Line 192: Reading the shape
+- Line 218: Repo selection rules
+- Line 230: Component Integrity Rules: Repo ↔ Database Reconciliation (read before any sync/commit)
+- Line 236: How the platform reconciles the repo into the database (the mechanism you must understand)
+- Line 298: The surfaces and their intended behavior
+- Line 322: Intended workflows
+- Line 343: Pre-sync safety check (confirm ALL before `components sync` or `components commit`)
+- Line 356: If something looks wrong — stop, don't paper over
+- Line 380: Required Local Index Reads
+- Line 414: Big Picture: How remits-cli State Is Organized
+- Line 444: Support Ticket Mental Model
+- Line 480: Efficiency Rules
+- Line 492: Account Repository Index
+- Line 517: Two Workflows
+- Line 524: Test Mode vs Prod Mode
+- Line 556: Platform Mental Model: Front Stage vs Back Stage
+- Line 563: Documents vs Records
+- Line 573: HTTP Audits
+- Line 627: Record `content` / Context Mental Model
+- Line 647: Provenance Fields
+- Line 665: Why Persisted Context Looks Different From Runtime Context
+- Line 686: Investigation Rule for Record Context
+- Line 701: AI Request Response Records
+- Line 708: AI Session Groupings
+- Line 727: Correlation Keys
+- Line 733: Node Reference Table
+- Line 743: Repository vs External Context
+- Line 750: Getting Started
+- Line 752: Authentication
+- Line 765: Host vs Data Mode
+- Line 784: Tool Execution Lifecycle
+- Line 838: Data Mode
+- Line 848: Development Workflow
+- Line 850: The Golden Rule: Writing Code Is Not Finishing the Job
+- Line 862: Avoid Brittle Front-Stage Intelligence
+- Line 875: The Development Fast Loop
+- Line 879: Step 1: Understand the Request
+- Line 894: Step 2: Make the Change
+- Line 932: Step 3: Stage to Platform
+- Line 947: Step 4: Verify the Change
+- Line 1012: Step 5: Iterate If Needed
+- Line 1022: Step 6: Update Documentation
+- Line 1034: Step 7: Commit and Durable Sync
+- Line 1072: Step 8: Close the Ticket
+- Line 1087: User Confirmation Preferences
+- Line 1097: Component Resolution: Staging Cache vs DB (which "version" actually runs)
+- Line 1103: The three source layers + the compile cache
+- Line 1126: Staging cache key format
+- Line 1141: How the platform picks staged vs DB (the compile signature)
+- Line 1163: When staged overrides apply
+- Line 1187: Diagnosing which version is in play
+- Line 1208: Stage / commit / clear with the MCP tools
+- Line 1232: Stale after sync / commit (the in-memory compile cache)
+- Line 1242: Account Resolution: how a request travels the account graph
+- Line 1335: Branched Component Variants (per-account component overrides)
+- Line 1343: The model (three moving parts)
+- Line 1410: Which world does your working tree resolve? (read this before you run anything)
+- Line 1476: Two levers, two different questions
+- Line 1490: The SDLC is identical on a variant branch
+- Line 1515: Promotion: getting the branch back into trunk
+- Line 1557: Verifying as the subscriber
+- Line 1576: Agents (Utility) on a variant branch
+- Line 1588: Danger profile on a variant branch (different, not absent)
+- Line 1616: Inspecting branches and drift
+- Line 1648: Diagnosing a variant
+- Line 1655: Production Support Workflow
+- Line 1663: Investigation Strategy
+- Line 1693: Presenting Findings
+- Line 1701: Verifying a Production Issue Fix
+- Line 1714: Tool Reference
+- Line 1716: Execute a Tool
+- Line 1745: `mcp_account_view`
+- Line 1777: `mcp_account_user_admin`
+- Line 1812: `mcp_firestore_search`
+- Line 1850: `mcp_object_activity`
+- Line 1859: `mcp_record_listing`
+- Line 1884: `mcp_record_view`
+- Line 1897: `mcp_ai_session_search`
+- Line 1933: `mcp_run_action`
+- Line 1977: `mcp_run_agent`
+- Line 2013: `mcp_system_logs`
+- Line 2036: `mcp_component_view`
+- Line 2059: `mcp_component_grep`
+- Line 2072: `mcp_support_ticket`
+- Line 2121: `mcp_run_test`
+- Line 2130: `mcp_component_edit`
+- Line 2145: `mcp_component_create`
+- Line 2159: `mcp_component_commit`
+- Line 2167: `mcp_component_branches`
+- Line 2186: `mcp_cache`
+- Line 2198: `mcp_sql_query`
+- Line 2233: `mcp_index_search`
+- Line 2253: `mcp_get_guide`
+- Line 2265: `mcp_test_fixture`
+- Line 2278: `mcp_embeddable_test_url`
+- Line 2290: `mcp_playwright_replay`
+- Line 2305: `mcp_jvm_spike_triage`
+- Line 2318: `mcp_support_ticket_queue`
+- Line 2335: Multi-Session Support
+- Line 2355: Persistent Service, Control Center, and Agent Dispatch
+- Line 2364: Starting the Service
+- Line 2390: Control Center
+- Line 2405: Agent Dispatch
+- Line 2426: Configuring the Preferred Agent
+- Line 2437: Local State Files
+- Line 2485: Command Reference
+- Line 2527: Troubleshooting
+- Line 2569: When Something Doesn't Work as Expected
+- Line 2580: Back-Stage Escalation Workflow (platform defect/limitation)
+- Line 2589: Escalation Bundle (tooling/operational issue)
 
 `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.
 
 ## Account Targeting Model
 
-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`.
+**Establish the account's shape before you touch anything.** Which repo you work in, which account you run
+against, where a fix belongs, and why one account behaves unlike its siblings are all answered by the account
+structure — never by the account's name. Read it from `account-info.json` (in the repo) or `mcp_account_view`
+(remotely). Both return the same thing.
 
-- **`PLATFORM`** = a use-case/platform implementation account. This is often where the shared Remits components live.
-- **`PRODUCT`** = a product/use-case account under a platform. This can also hold shared implementation components.
-- **`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.
+### Account types
 
-Do not guess from the account name alone.
+| Type | What it is | Components | Business data |
+|---|---|---|---|
+| `PLATFORM` | Top of a use-case tree. Owns the shared implementation and the git repository. | **Owned here** | Rarely — mostly configuration |
+| `PRODUCT` | A product/use case under a platform. May own shared components too. | **Owned here or above** | Rarely |
+| `CLIENT` | An actual customer. Where an issue is observed. | Usually **inherited**, not owned | **Here** — the customer's documents and lifecycle records |
+| `PROVIDER` | A partner/vendor participant in a use case | Rarely | Sometimes |
+
+- **Feature, enhancement, component change, shared behavior fix** → the implementation target is usually the
+  owning `PLATFORM` or `PRODUCT` account, **not** the `CLIENT` that reported it.
+- **Production investigation or client-specific data issue** → start with the affected `CLIENT` account's
+  data and runtime history.
+- **Both** → confirm symptoms on the `CLIENT`, then move to the owning `PLATFORM`/`PRODUCT` repo to change code.
+
+### How accounts connect (and why it changes what runs)
+
+Components are **inherited downward** and de-duplicated **by component name, nearest owner wins** — so a
+client can run an Action owned three levels up, and can override it just by owning one with the same name.
+Business data does **not** inherit; it belongs to the account that wrote it, in that account's storage
+namespace.
+
+An account is linked upward in two ways, and they coexist:
 
-- 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.
-- If the work is a **production investigation or client-specific data issue**, start with the affected `CLIENT` account's data and runtime history.
-- 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.
+- **The primary parent** — one per account. The overwhelming majority of accounts have only this.
+- **Membership edges** — extra links letting the *same account* be reached through **more than one** parent
+  (a customer in two product lines; a branch deployment reaching the same owner).
 
-Apply these rules before making remote tool calls:
+Any link can independently carry three things. They are **orthogonal** — never infer one from another:
 
-- **Inside the target implementation repo**: read `account-info.json` (the same data that `mcp_account_view` returns) and inspect `/components` directly.
-- **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`.
+| Edge property | Means |
+|---|---|
+| `branchName` | **Which code runs** — the component-variant branch this account subscribes to (see "Branched Component Variants") |
+| `databaseName` | **Where data lives** — a storage-namespace override scoped to this link |
+| `domainName` | **Which host reaches it** — a custom hostname that resolves this account *and* this link's parent as the path travelled |
+
+Two consequences that generate most "this account is weird" tickets:
+
+1. **The same account can legitimately resolve differently depending on how the request reached it** — a
+   different component version, a different namespace, a different host. Establish which path a failing
+   request travelled before comparing behavior. (Full detail in "Account Resolution: how a request travels
+   the account graph".)
+2. **An account with no primary parent and several membership edges inherits nothing and runs trunk** until
+   a path is named — the platform refuses to guess between equally valid parents. That is by design.
+
+### Users are a separate model — don't reason about them as a tree
+
+- A user is **global, keyed by email**. There is no per-account copy of a person.
+- A user **belongs to many accounts** (a membership list, not a parent pointer).
+- A user's **custom fields are per-account**: the same person can be `role: 'Admin'` on one account and
+  `role: 'Viewer'` on another. A field written while bound to the wrong account lands on the wrong account.
+- **Access reach is a union over every link** — a user credentialed on a parent can act on an account below
+  it through any link, which is deliberately broader than the single-path component inheritance.
+
+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`, or `account.users([scope:
+'children'])` from inside a component. See `features/account-management.md` (`mcp_get_guide`).
+
+### Reading the shape
+
+`account-info.json` / `mcp_account_view` carry a `resolution` block — the ONE place these facts appear
+(nothing in it is repeated elsewhere in the file). Read it in this order:
+
+- **`role`** + **`summary`** — `OWNER` (resolves its own component trunk: the files here ARE its components)
+  or `SUBSCRIBER` (resolves ANOTHER account's components with a variant branch applied). `summary` says it
+  in one sentence, naming the owner. Read this before you touch anything.
+- **`accountId`** — the account described. In a repo export the top-level `id` is the same account; in a
+  legacy export it is the hierarchy ROOT, so prefer `resolution.accountId`.
+- **`type`** — decide repo/ownership per the table above.
+- **`resolvedDatabaseName`** vs **`databaseName`** — the namespace actually in effect vs the account's own
+  override. Check this first when documents are "missing".
+- **`relationships`** — every link upward, primary first, each with its own `branchName` / `databaseName` /
+  `domainName`. **This is where you see that an account has two parents, and which link carries what.**
+- **`componentBranch`** (+ `componentOwnerAccountId` / `componentOwnerAccountName`) — the component-variant
+  branch in effect for this resolution and who owns it. A `SUBSCRIBER` with no `componentBranch` subscribes
+  through an edge that nothing anchored this resolution to (multi-parent, no path named) — `summary` says so.
+- **`branchName`** — the account **repo's** trunk sync branch. Not a component-variant branch. Do not confuse
+  these two.
+- **`parents`** / **`children`** — the anchored ancestor chain and a DIRECT-child summary with counts (repo
+  exports only; the default `mcp_account_view` shape carries the full tree instead). The deep tree is a
+  lookup — `mcp_account_user_admin` with `action:'hierarchy'` and a `depth` — never a committed artifact.
+- **`componentBranches`** (top level) — variant branches this account **owns**, with drift and subscriber
+  counts. Check it before editing a shared component.
+
+### Repo selection rules
+
+- **Inside the target implementation repo**: read `account-info.json` and inspect `/components` directly.
+- **Inside one repo but supporting a different account**: switch to the correct repo for that account if
+  available; otherwise use `mcp_account_view` / `mcp_component_view` / `mcp_component_grep`.
 - **Outside any repo**: rely on the tools for account structure and component source.
-- **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.
+- **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.
 
 Use `remits-cli` for everything else: staging changes, running tests, generating embeddable tokens, committing work, and diagnosing production issues.
 
@@ -144,6 +249,11 @@ local working tree** — and:
 - **Match / update:** each component is matched to a DB row by the **numeric id prefix of its files**
   (`58_x.groovy` → component 58), not by name. Matching files overwrite that component's DB fields
   (source/schema/html/etc.).
+- **Rename:** changing the component's `name:` in `.meta.yml` is supported as a normal update **as long as
+  the numeric id prefix stays the same**. On staging, the CLI updates the id/name cache aliases and prunes
+  stale old-name aliases for that id. On trunk sync, the platform canonicalizes the repo filenames to the
+  current component name (`58_OldName.groovy` with `name: New Name` becomes `58_NewName.groovy`, plus
+  sidecars) and reports those moves in `syncResults.renamed`.
 - **Create:** a file whose id prefix is **not** a live component on the account — including any `new_*` file —
   is created as a **brand-new DB row with a fresh server-assigned id**, and the platform renames the repo files
   to that id (the `Rename X→Y after component creation` / `Delete old file` commits).
@@ -175,13 +285,15 @@ local working tree** — and:
 > nor got renamed."* Check the sidecar's `auxiliary` flag first.
 
 **The single most important consequence:** the id in a component's **filename is load-bearing**. If a file's id
-no longer matches its DB row (a rename/renumber), the next sync will **create a duplicate at the new id and
-hard-delete the original at the old id**. If a component's files are missing from the repo at sync time, that
-component is **hard-deleted from the DB**. This is exactly how a prior session deleted live schemas and an
-embeddable.
+no longer matches its DB row (a renumber or move across ids), the next sync will **create a duplicate at the
+new id and hard-delete the original at the old id**. If a component's files are missing from the repo at sync
+time, that component is **hard-deleted from the DB**. This is exactly how a prior session deleted live schemas
+and an embeddable.
 
-**Therefore: never renumber, rename-across-ids, or remove component files as a side effect.** Before any sync,
-the repo must already mirror the live DB: every live component present at its real id, and nothing extra.
+**Therefore: never renumber, rename-across-ids, or remove component files as a side effect.** Name-only
+renames are fine when every file keeps the same numeric id; either rename the local filename stem yourself or
+let trunk sync canonicalize it from `.meta.yml`. Before any sync, the repo must already mirror the live DB:
+every live component present at its real id, and nothing extra.
 
 ### The surfaces and their intended behavior
 
@@ -191,7 +303,7 @@ the repo must already mirror the live DB: every live component present at its re
 | `mcp_component_edit` `mode:'stage'` | Redis staging cache for one component/field. | none |
 | `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) |
 | `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** |
-| `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) |
+| `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) |
 | `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** |
 | `mcp_component_create` | Writes a **new** component row **directly to the DB** (immediate, new id). | medium (can create duplicates) |
 
@@ -211,7 +323,9 @@ Key implications:
 
 **Change existing components (normal path):**
 1. Edit files under `components/` **keeping each component's existing numeric id** (use `new_*` only for
-   genuinely new components).
+   genuinely new components). To rename a component, update `name:` in its `.meta.yml`; keep the id prefix
+   fixed. Renaming the file stem is optional before trunk sync because the platform will canonicalize it, but
+   doing it locally keeps the working tree easier to read.
 2. `remits-cli components stage` → verify in test mode. Iterate (edit → stage → run).
 3. When ready to promote: pass the pre-sync safety check below, then
    `git add -A && git commit && git push`, `remits-cli components sync`, `git pull --ff-only`.
@@ -765,6 +879,12 @@ This is how every development task should flow:
 #### Step 1: Understand the Request
 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.
 
+**Establish the account's shape too, not just its components.** Read the `resolution` block in
+`account-info.json` (or `mcp_account_view`): the account `type` decides whether this repo is even the right
+place to change code, `resolution.relationships` shows whether the account has more than one parent (and
+which link carries a branch/namespace/host), and `resolvedDatabaseName` tells you where its data actually
+lands. See "Account Targeting Model" and `features/account-management.md` (`mcp_get_guide`).
+
 **Also establish which world you are working in.** `remits-cli components status` reports whether the
 working tree is a **trunk** checkout or a **variant branch** checkout — which decides both what your test
 runs resolve and what a sync writes. If `account-info.json` carries a `componentBranches` section, branch
@@ -774,6 +894,41 @@ variants of these components exist: editing an origin component will drift them,
 #### Step 2: Make the Change
 Edit component files under `components/`. This is local file editing — the platform doesn't know about your changes yet.
 
+**Creating a component that does not exist yet.** Files are named `<id>_<Name>.<ext>`, where the numeric
+prefix is the platform's component id. A new component has no id, so name its files with the **`new_`
+prefix** and let the sync assign one (it then renames the files to that id):
+
+```
+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
+```
+
+**Do NOT put an `id:` in a new component's sidecar.** `id` is what links a sidecar to an *existing*
+component and is parsed as a number, so a placeholder (`id: new`, `id: TBD`) fails the **entire**
+stage/sync request with a `NumberFormatException` — not just that one file, and the error does not name
+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.
+description: |
+  Longer technical description with line-number references to the key logic.
+path: /page/merchant-portal        # Readers and Embeddables only
+category: default
+auxiliary: false                   # `true` means the sync SKIPS the file entirely — see Auxiliary
+mermaid: |
+  graph TD
+    A[Request] --> B[Load documents]
+```
+
+> **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
+> component has a real id and either form works.
+
 #### Step 3: Stage to Platform
 
 ```bash
@@ -806,7 +961,9 @@ Important test-runner constraints:
 
 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.
 
-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.
+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.
+
+**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.
 
 **Option B — Visual verification with Playwright** (for UI changes or when the user wants to "see it"):
 
@@ -870,7 +1027,9 @@ Before committing, update metadata so the next session understands what changed:
 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.
+`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.
 
 #### Step 7: Commit and Durable Sync
 
@@ -1108,8 +1267,8 @@ edge's *child* as the execution account **and** the edge's *parent* as the branc
 makes that edge's branch variants apply. An account-level host resolves the account with **no** anchor
 (today's behavior). Edge wins, then the account's own host, so removing an edge degrades cleanly instead
 of taking the hostname offline. Hosts are stored as bare lowercase hostnames; a full URL is normalized on
-the way in. This is what lets a forked/branch deployment get its own domain without a separate account
-tree — `forked.example.com` and `app.example.com` can serve the same owner's components, one overlaid
+the way in. This is what lets a branch deployment get its own domain without a separate account
+tree — `branch.example.com` and `app.example.com` can serve the same owner's components, one overlaid
 with a branch.
 
 **Two traversals, deliberately different.** Confusing them is the usual source of wrong conclusions:
@@ -1139,17 +1298,40 @@ disambiguate it by branch name; from the CLI you supply it explicitly.
 legitimately resolve a different component variant *and* a different data segment. When you investigate
 such an account, always establish which anchor the failing request used before comparing behavior.
 
+**How to actually see an account's edges.** `mcp_account_view` (and the repo's `account-info.json`) returns
+`resolution.relationships` — one entry per structural link, primary first, each carrying its own
+`branchName` / `databaseName` / `domainName`. The hierarchy tree flattens every link into one shape, so this
+block is the only place that answers "how many parents does this account really have, and which link carries
+what?" Start here for any resolution question:
+
+```bash
+remits-cli tool --name mcp_account_view --input '{"accountId": 101}' --data-mode prod
+# then read: resolution.relationships, resolution.resolvedDatabaseName, resolution.componentBranch
+```
+
 **Practical checklist when a subscription "doesn't work":**
 
-1. Does the account have a `parentId`, or is it membership-only? (Membership-only + multiple edges ⇒
+1. Does the account have a primary parent, or is it membership-only? Count the entries in
+   `resolution.relationships` and check which one is `primary: true`. (Membership-only + multiple edges ⇒
    ambiguous ⇒ trunk.)
-2. Which **edge** carries the `branchName` — `remits-cli components branch <name> --subscribers` prints
-   `via primary|membership edge -> parent N`.
+2. Which **edge** carries the `branchName` — it is on the edge in `resolution.relationships`, and
+   `remits-cli components branch <name> --subscribers` prints `via primary|membership edge -> parent N`.
 3. Was the run anchored through *that* edge's parent? Re-run with `--as-account <subscriberId>` so the
    account's own edge selects the branch, exactly as production would.
 4. Check the resolved layer, not the source text: `testComponentSource` / the `variant:<id>:<hash>`
    compile signature (see "Diagnosing a variant").
 
+**The same block answers the non-branch resolution questions too:** "why are this account's documents not
+where I expect?" → compare `databaseName` vs `resolvedDatabaseName` and any edge `databaseName`. "Why does
+this hostname land on the wrong account?" → `domainName` vs `resolvedDomainName` and the edge `domainName`
+(an edge host wins over the account's own, and additionally supplies the path travelled).
+
+**Users are not part of this graph.** A user is global, belongs to many accounts, and can reach an account
+below one they are credentialed on through **any** link — a deliberately broader rule than the single-path
+component inheritance above. Their custom fields (`role`, `team`, …) are stored **per account**, so the same
+person can differ per account. There is no user MCP tool: use `mcp_sql_query` against `user` /
+`user_account`, and read `features/account-management.md` (`mcp_get_guide`) for the model.
+
 ## Branched Component Variants (per-account component overrides)
 
 Sometimes one account — often a customer nested several levels down a hierarchy — needs *slightly*
@@ -1162,14 +1344,14 @@ resolve.
 
 1. **The origin account owns the component and the branch.** Say platform account 1 owns
    `Extract Invoice` (Action 50). Its repo `remits-<name>` has trunk branch `main` and a second git branch
-   `feature_forked`.
-2. **A `ComponentVariant` row is the overlay.** Committing on `feature_forked` stores rows owned by
-   **account 1**, on branch `feature_forked`, for the components whose content **differs from trunk**. A git
+   `feature_branch`.
+2. **A `ComponentVariant` row is the overlay.** Committing on `feature_branch` stores rows owned by
+   **account 1**, on branch `feature_branch`, for the components whose content **differs from trunk**. A git
    branch physically contains every file; only the *differing* ones become variants. That is computed at
    sync time — you never declare it.
 3. **A child account subscribes via its relationship edge.** Account 101's `AccountRelationship` edge
-   carries `branchName = 'feature_forked'`. Resolution then walks 101's inheritance chain and applies
-   account 1's `feature_forked` overlays.
+   carries `branchName = 'feature_branch'`. Resolution then walks 101's inheritance chain and applies
+   account 1's `feature_branch` overlays.
 
 Consequences worth internalizing:
 
@@ -1187,8 +1369,14 @@ Consequences worth internalizing:
   only subscribe an account reachable from one you already have access to.
   - **`--subscribe` sets the branch on an edge that must already exist — it cannot create one.** If the
     account has no relationship edge to the owner you will get *"Account N has no relationship edge to
-    subscribe; add a membership edge first"*. Creating a membership edge is an **admin** operation (the
-    account page), not a CLI one.
+    subscribe; add a membership edge first"*. Create it with
+    `mcp_account_user_admin` `action:'edge_add'` (`targetAccountId` = the child, `parentAccountId` = the
+    owner), which also accepts `branchName` so you can create and subscribe in one call. The admin account
+    page does the same thing.
+    - **Many older accounts have no relationship row at all.** The edge table was introduced after the fact
+      and never backfilled, so an account whose parent link is only `Account.parentId` resolves fine but has
+      nothing for `--subscribe` to attach to. `mcp_account_user_admin` `action:'reparent'` with the account's
+      *current* parent is the one-call repair: it creates the missing primary edge and changes nothing else.
   - **When the account has several parents, say which edge you mean:**
     `--subscribe <accountId> --parent-account <ownerId>`. Without it the CLI picks the edge to the owner
     whose branch you are managing, then falls back to the account's primary edge — which may not be the
@@ -1233,7 +1421,7 @@ the loop. The rule turns entirely on **trunk vs non-trunk**:
 | Working tree | Staging scope | A run resolves | `components sync`/`commit` writes |
 |---|---|---|---|
 | **trunk** (`main`, or whatever `account-info.json` says) | that branch | trunk + **each account's subscribed** variant branch (production semantics) | the **live component rows** — full reconcile, creates/updates/**deletes** |
-| **any other branch** (`feature_forked`) | that branch | trunk + **`feature_forked`** overlays | **`ComponentVariant` overlays on that branch only** — never touches trunk rows |
+| **any other branch** (`feature_branch`) | that branch | trunk + **`feature_branch`** overlays | **`ComponentVariant` overlays on that branch only** — never touches trunk rows |
 
 **The precedence trap that costs the most time:** `variantBranch` OUTRANKS every account's subscription. So
 running a Test suite that asserts *production* semantics from a **variant checkout** pins every account in
@@ -1250,13 +1438,47 @@ remits-cli components status
 ```
 
 ```
-Working tree: VARIANT BRANCH "feature_forked"  (trunk is "main")
-  runs resolve:   trunk + the 'feature_forked' variant overlays
-  commit writes:  ComponentVariant overlays on 'feature_forked' (never touches trunk rows)
+Working tree: VARIANT BRANCH "feature_branch"  (trunk is "main")
+  runs resolve:   trunk + the 'feature_branch' variant overlays
+  commit writes:  ComponentVariant overlays on 'feature_branch' (never touches trunk rows)
   variants stored on this branch: 3
   subscribing accounts: 101 (Acme Child)
 ```
 
+**Branch-local `account-info.json` can describe a subscriber.** On a variant branch, the same git repository
+is still the OWNER's component repo: files under `components/` overlay that owner's trunk component ids, and
+`components sync` writes `ComponentVariant` rows owned by that parent account. But if the checkout was synced
+from a subscribing account reached through an `AccountRelationship` edge, the branch's `account-info.json`
+is intentionally rooted at that subscriber and refreshed from the subscriber's resolved account information.
+That is what lets a branch checkout answer "who am I acting as?" while preserving "who owns these component
+variants?"
+
+Read the `resolution` block before acting from any checkout — it is the ONE place account-info states this
+(nothing in it is repeated elsewhere in the file):
+
+- `resolution.role` — `OWNER` for a trunk/owner export, `SUBSCRIBER` for an account reached through an
+  `AccountRelationship` branch edge. `resolution.summary` says the same thing in one sentence.
+- `resolution.accountId` — the account the local checkout should be treated as. **This, not the top-level
+  `id`, is the key to read**: an `account-info.json` predating this shape is rooted at the hierarchy root.
+- `resolution.componentOwnerAccountId` — the account whose trunk component ids the files overlay and whose
+  `ComponentVariant` rows sync writes. Equals `resolution.accountId` for an `OWNER`.
+- `resolution.componentBranch` / `resolution.scopeAccountId` — the branch and the path anchor that made this
+  subscriber resolution possible.
+- `resolution.parents` / `resolution.children` / `resolution.relationships` — the account graph, stated once
+  and compactly. The full descendant tree is a lookup (`mcp_account_user_admin`, `mcp_account_view`), not a
+  committed artifact.
+
+**One branch, one `account-info.json`.** There is exactly one git branch, so when a branch has MORE THAN ONE
+subscriber the refresh is skipped (the sync result says so under `accountInfo.skipped`/`reason`) and the file
+keeps describing the owner — which is at least true for all of them. Otherwise each subscriber's sync would
+rewrite the file as its own and hand the other subscriber's agent a file naming the wrong account. Overlay
+ownership is unaffected either way: variants always belong to the owner account.
+
+Consequence: if a variant checkout's `account-info.json` is stale and still names the owner, run the first
+repair sync with an explicit subscriber target, for example `remits-cli components sync --account-id 101`.
+After that sync and `git pull --ff-only`, normal commands from that checkout should resolve the subscriber
+from `account-info.json` and continue writing variants under the owner selected by the branch edge.
+
 ### Two levers, two different questions
 
 - **`--as-account <id>`** changes **who** the run executes as, so that account's own edge picks the branch.
@@ -1276,13 +1498,13 @@ Both work on `remits-cli test run` and `remits-cli token`; `--variant-branch` al
 The loop does not change shape — `edit → stage → verify → commit`:
 
 ```bash
-git checkout feature_forked          # or: git checkout -b feature_forked
+git checkout feature_branch          # or: git checkout -b feature_branch
 # edit components/actions/50_ExtractInvoice.groovy   (KEEP the trunk id)
 remits-cli components stage          # Redis, scoped to this branch — same as always
-remits-cli test run --test "Invoice Tests"          # resolves the feature_forked world
+remits-cli test run --test "Invoice Tests"          # resolves the feature_branch world
 remits-cli test run --test "Invoice Tests" --as-account 101   # ...as the real subscriber
 # promote:
-git add -A && git commit -m "..." && git push origin feature_forked
+git add -A && git commit -m "..." && git push origin feature_branch
 remits-cli components sync --dry-run # inspect overrides/additions/tombstones without writes
 remits-cli components sync           # writes ComponentVariant overlays ONLY
 ```
@@ -1291,9 +1513,10 @@ Two things that differ from trunk:
 
 - **Keep the origin id in the filename.** `50_ExtractInvoice.groovy` on the branch overlays Action 50. That
   is what preserves component identity and lets drift be computed against the origin.
-- **Nothing is renamed.** A variant sync never renames files, never regenerates `account-info.json`, and
-  never repoints the account's trunk branch. A `new_*` file stays `new_*` and becomes a branch-only
-  component keyed by name.
+- **Nothing is renamed.** A variant sync never renames files and never repoints the account's trunk branch.
+  When launched from a subscribing account, it may refresh that branch's `account-info.json` so the checkout
+  describes the account reached through the branch edge. A `new_*` file stays `new_*` and becomes a
+  branch-only component keyed by name.
 
 ### Promotion: getting the branch back into trunk
 
@@ -1302,12 +1525,12 @@ by a **trunk** sync — the platform does not merge anything for you.
 
 ```bash
 # 1. merge the branch into trunk (review the diff FIRST - see the deletion hazard below)
-git checkout main && git merge feature_forked && git push origin main
+git checkout main && git merge feature_branch && git push origin main
 # 2. trunk sync: creates real rows for new_* files, assigns ids, RENAMES those files on trunk
 remits-cli components sync
 git pull --ff-only origin main
 # 3. bring trunk back into the branch so the two stop diverging
-git checkout feature_forked && git merge origin/main && git push origin feature_forked
+git checkout feature_branch && git merge origin/main && git push origin feature_branch
 remits-cli components sync                        # reconciles the branch's overlays
 ```
 
@@ -1400,9 +1623,9 @@ The analogous hazard is different and you must still respect it:
 
 ```bash
 remits-cli components branches                                  # branches with variants, counts, drift
-remits-cli components branch feature_forked                     # overridden / added / removed + subscribers
-remits-cli components branch feature_forked --diff 50 --component-type action
-remits-cli components branch feature_forked --subscribers
+remits-cli components branch feature_branch                     # overridden / added / removed + subscribers
+remits-cli components branch feature_branch --diff 50 --component-type action
+remits-cli components branch feature_branch --subscribers
 ```
 
 **Drift is the number to watch.** Each variant records the trunk content hash at the moment it was cut
@@ -1531,18 +1754,118 @@ Returns complete account structure — schemas, components, relationships.
 Also returns two blocks that explain how the account RESOLVES, which is what you need before comparing
 its behavior against component source:
 
-- `resolution` — `databaseName` (the account's own override, often null) vs `resolvedDatabaseName` (the
-  storage namespace actually in effect), `branchName` (the repo sync branch), `domainName` vs
-  `resolvedDomainName` (the custom host in effect, which differs when reached through an edge host),
-  `editMode`, and — when the account subscribes to a component branch — `componentBranch` plus
-  `componentBranchOwnerAccountId`.
+- `resolution` — `role` (`OWNER` = resolves its own component trunk, `SUBSCRIBER` = resolves another
+  account's components through a branch edge) and a one-sentence `summary`; `accountId` (the account
+  described — the top level of this shape is the hierarchy ROOT, so do not read identity from there);
+  `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`.
+- `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
+  `branchName` (which component-variant code runs), `databaseName` (where data lives), `domainName` (which
+  host reaches the account through this link). The hierarchy tree flattens all links into one shape, so this
+  is the **only** place that answers "does this account have more than one parent, and which link carries the
+  branch/namespace/host?" More than one entry ⇒ this account can resolve differently depending on the path a
+  request travelled — establish which one a failing request used before comparing behavior.
 - `componentBranches` — the variant branches this account OWNS, with override/add/remove, subscriber, and
   drift counts. Same summary the owner's `account-info.json` carries.
 
+Note: this tool does **not** return users, and it returns EVERYTHING about one account. For users, for the
+deep account tree, or for small account/user updates, use `mcp_account_user_admin`.
+
 | Parameter | Required | Description |
 |-----------|----------|-------------|
 | `accountId` | yes | Account ID |
 
+### `mcp_account_user_admin`
+The account-graph and user surface: the middle ground between `account-info.json` (which states structure
+compactly, because it is read into your context every session) and `mcp_account_view` (everything about one
+account).
+
+- `action: 'hierarchy'` (default) — the descendant tree trimmed to `depth` (1-10, default 2; nodes cut off
+  are marked `truncated` and still report their child count) and/or the anchored ancestor chain plus every
+  edge (`direction: 'down'|'up'|'both'`). **This is how you get the deep tree account-info.json omits.**
+- `action: 'account'` — one account's `resolution` block plus masked configuration fields, without paying
+  for the component inventory.
+- `action: 'users'` — an account's users at a hierarchy `scope` (`self`/`children`/`parents`/`hierarchy`),
+  optional `email` substring filter. Extension fields are omitted here on purpose: they are stored **per
+  account** and these users are bound to their own.
+- `action: 'user'` — one user (`userId` or `email`) with roles, account memberships, and extension fields
+  **correctly scoped to the requested account**. It never grants membership as a side effect of a read, and
+  tells you when the fields shown belong to a different account.
+- `action: 'account_update'` — write Account-schema configuration `fields`, and/or `name`/`status`
+  (`ACTIVE`/`ON_HOLD`/`PENDING`).
+- `action: 'user_update'` — write User-schema `fields` under the named account (refused unless the user is a
+  member or you pass `addAccount: true`, because the write would otherwise land on another account), plus
+  `name`/`enabled` and membership add/remove.
+
+**Building an account hierarchy** (the structural writes — this is how a coding agent provisions accounts
+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.
+- `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` (branch-scoped namespace — stored, but inert until segment inheritance is enabled) and
+  `domainName` (which host reaches the account through that edge). Cycles, self-edges, and removing the primary
+  edge are all refused.
+- `action: 'reparent'` — move the account's **primary** edge (and `Account.parentId`) to `parentAccountId`.
+
+> **The namespace guard.** An account's storage namespace resolves as
+> `databaseName ?: platform.code ?: code`, and `Account.setName` **regenerates `code`** — so renaming an
+> account whose namespace falls through to its own code silently repoints its storage. Any write that would
+> move the resolved namespace is **refused** unless you pass `confirmSegmentChange: true`, and the refusal
+> names both namespaces. To rename without moving storage, pin `code` to the old value in the same call.
+>
+> The namespace follows the **path**: the nearest `databaseName` walking up from the account — its own
+> first, then the edge it was reached through, then the same two questions at each account above — falling
+> back to the nearest `PLATFORM` ancestor's `code`. So a namespace set anywhere above is inherited by
+> everything below it until a nearer account or edge overrides it, and an edge answer is path-specific (the
+> same account reached through a different parent can resolve a different namespace).
+
+Every write supports `dryRun: true`, which reports each `from -> to` without writing. Not here by design:
+component-branch subscription reporting and drift (`mcp_component_branches` — though `edge_add`/`edge_update`
+set the branch directly), and account/user **deletion** (admin only, so the destructive-teardown contract
+applies).
+
+**Provisioning recipe** — a new product account under a platform, running its own component branch, with
+client accounts beneath it:
+
+```
+1. mcp_account_user_admin  action:'account_create'   parentAccountId:<platform>  name:'Adyen'
+                           type:'PLATFORM'|'PRODUCT'  [databaseName:'...']
+2. git branch + push in the OWNER's repo, then `remits-cli components sync` from that checkout
+   (non-trunk => writes ComponentVariant overlays only)
+3. mcp_account_user_admin  action:'edge_update'  targetAccountId:<new>  parentAccountId:<platform>
+                           branchName:'<branch>'          # or mcp_component_branches action:'subscribe'
+4. mcp_account_user_admin  action:'account_create'  parentAccountId:<new>  name:'<business unit>'
+                           type:'CLIENT'                  # inherits the branch automatically
+```
+
+> **Put the branch on the account's PRIMARY edge.** Component inheritance follows the *anchored* path, which
+> for an account with a `parentId` is its primary chain. An account that has both a primary edge and a
+> *membership* edge carrying the branch resolves **trunk** by default — the membership edge is never
+> anchored unless a request names it (`--as-account`, `--variant-branch`, or the edge's own host). Descendants
+> then inherit the branch down that primary chain automatically, which is what makes step 4 free.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `action` | no | `hierarchy` (default), `account`, `users`, `user`, `account_update`, `user_update` |
+| `accountId` / `targetAccountId` | no | Account to act on; `targetAccountId` targets another account without moving tool resolution |
+| `depth` / `direction` | no | `hierarchy` only |
+| `scope` | no | `users` only |
+| `userId` / `email` | no | Identify the user (`user`, `user_update`); `email` is a filter for `users` |
+| `fields` / `name` / `status` / `enabled` | no | The update payload |
+| `addAccount` / `removeAccount` | no | Membership changes for `user_update` |
+| `dryRun` | no | Report the change without writing |
+
 ### `mcp_firestore_search`
 Query Firestore documents.
 
@@ -1898,6 +2221,25 @@ Inspect, flush, or clear the CLI staging cache for components.
 | `accountId` | yes | Account ID |
 | `action` | yes | `read` (list staged entries), `commit` (flush staged → DB), or `clear` (drop staged entries without touching the DB) |
 
+### `mcp_component_branches`
+The MCP counterpart of `remits-cli components branches` / `components branch <name>` — use it when you are
+driving the platform **remotely** (no local repo/checkout) and need to know whether a component already has
+committed branch variants, who subscribes, and whether they have drifted.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `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 |
+| `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. |
+| `branchName` | conditional | Required for everything except `list`. Alias: `branch`. |
+| `componentId` / `componentName` / `componentType` | conditional | Address the component for `diff` |
+| `targetAccountId` | conditional | The account to subscribe/unsubscribe |
+| `parentAccountId` | no | Which relationship edge to set the branch on. Without it: the edge toward the branch owner, then the target's primary edge. |
+| `force` | no | `retire` only — proceed while subscribers remain |
+
+Same rules as the CLI: `subscribe` only **sets the branch on an edge that already exists** (creating a
+membership edge is an admin operation), authorization is downward-only, and `retire` refuses while
+subscribers remain unless forced.
+
 ### `mcp_cache`
 Bounded read-only investigation of the platform Redis keyspace — the way to see exactly what a staged
 entry holds (and its TTL) or any other cache key. Read-only: no delete (use `mcp_component_commit clear`
@@ -1910,6 +2252,143 @@ to remove staged entries).
 | `key` | no | Exact key for `action:'inspect'` |
 | `pageSize`/`sampleSize`/`previewChars` | no | Bounding controls |
 
+### `mcp_sql_query`
+Read-only, bounded SQL against the platform database. This is the **catch-all investigation surface** for
+questions the purpose-built tools do not model — above all **users and account membership**, for which there
+is no dedicated tool.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `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. |
+| `queries` | yes* | Batch of up to 10 read-only queries (strings, or `{query, params}` objects) |
+| `params` / `parameters` | no | Positional parameters — **use these instead of interpolating values** |
+| `maxRows` / `limit` | no | Rows per query. Default 100, max 500. |
+| `maxValueChars` | no | Truncation width per string value. Default 2000, max 20000. |
+| `redact` | no | Redact secret-like columns (`password`, `token`, `secret`, `authorization`, …). **Default true — leave it on.** |
+
+*Provide `query`/`sql` or `queries`.
+
+Useful shapes:
+
+```sql
+-- who has access to a client account (and through which membership rows)
+SELECT u.id, u.username, u.enabled FROM user u
+  JOIN user_account ua ON ua.user_id = u.id WHERE ua.account_id = ?;
+
+-- every account a user can reach directly
+SELECT a.id, a.name, a.type FROM account a
+  JOIN user_account ua ON ua.account_id = a.id WHERE ua.user_id = ?;
+
+-- the account's structural links, including membership edges (`primary` is column `is_primary`)
+SELECT parent_id, is_primary, branch_name, database_name, domain_name, active
+  FROM account_relationship WHERE account_id = ?;
+```
+
+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.
+
+### `mcp_index_search`
+Query and **diagnose** the Vertex AI Search index through the platform's Vertex DSL. Use it to check what a
+RAG/search-backed component actually retrieves before blaming the component.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `accountId` | yes | Tenant scoping |
+| `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`) |
+| `query` | conditional | Required for `search`/`diagnose` |
+| `schema` / `projectionType(s)` / `projectionSource` | no | Scope to a schema's Vertex projections |
+| `filters` | no | Vertex-style structured filters on indexed metadata |
+| `pageSize` / `maxResults` / `pageToken` | no | Paging and local trimming |
+| `searchProfile` | no | `ai`/`agent`/`strict` (precision) vs `admin`/`default` (recall) |
+| `includeMatchDiagnostics` | no | Return the applied filter/query plus the pre-strict-filter candidate set |
+| `accountIds` | no | Explicit multi-account search |
+| `dataMode` | no | `test` (default) or `prod` |
+
+When a component "can't find" an obviously-present document, run `action:'inspect'` on its source document id
+first — that shows what was indexed, which is usually the answer.
+
+### `mcp_get_guide`
+Load the packaged front-stage guides — the same `docs/guides/` set `remits-cli` syncs into a repo. Use it when
+you are working **outside a repo** (or the repo's `guides/` is stale) and need the authoritative guidance
+before writing a component.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `guide` | conditional | Short name (`agent-components`), relative path (`features/account-management`), or full path |
+| `list` | no | List available guides instead of loading one |
+| `directory` | no | Scope a list to `components` or `features` |
+| `contains` | no | Substring filter when listing |
+
+### `mcp_test_fixture`
+Seed and remove schema-backed fixture documents in the **forced test** data segment. This is how you construct
+realistic conditions for verification without copying live customer data.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `accountId` | yes | Account owning the target schema/collection |
+| `action` | no | `create` (fails on existing id), `upsert`, or `delete` |
+| `schemaName` / `collection` | conditional | Schema display name or collection name |
+| `documentId` / `documentIds` | no | Explicit Firestore ids for single/batch operations |
+| `data` / `documents` | conditional | Single payload, or a batch array |
+| `dataMode` | no | Must be `test` — **prod-mode writes are rejected** |
+
+### `mcp_embeddable_test_url`
+Mint an authenticated browser URL for an embeddable — the MCP counterpart of `remits-cli token --path
+embeddable/index/<id>`. Returns the URL plus branch/variant/data-mode hints so you know which world the page
+will render.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `accountId` | yes | Account owning the embeddable |
+| `embeddableId` / `embeddableName` | conditional | Provide one |
+| `userId` | no | User to mint for. Defaults to the current user. |
+| `variantBranch` | no | Probe a committed component-variant branch. Usually inherited from the caller. |
+
+### `mcp_playwright_replay`
+Hosted browser automation (the `playwright-relay` service) for visual verification when local `playwright-cli`
+is unavailable — e.g. an agent running remotely. Returns an accessibility snapshot and interactive refs on
+every command, so you navigate iteratively.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `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` |
+| `sessionId` | conditional | Reuse an existing session. `open`/`goto` without one starts a session. |
+| `url` / `target` / `value` / `expression` / `code` | conditional | Per-command inputs (`target` is an element ref or selector) |
+| `compact` | no | Default true — omits bulky raw relay payloads |
+| `includeSnapshot` / `includeAccessibility` / `includeRefs` / `includePage` / `includeResult` / `includeRaw` | no | Response shaping |
+| `pattern` / `level` / `limit` | no | Filters for `console` / `network` |
+| `ticketId` / `artifactType` / `artifactLabel` / `artifactNotes` | no | Attach a screenshot/pdf/trace/video to a support ticket |
+
+### `mcp_jvm_spike_triage`
+Production-aware triage bundle for a Cloud Run service showing a latency/memory spike. Safe by construction:
+optional class-histogram sampling, **no heap dump and no JFR**.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `serviceName` | yes | e.g. `remits`, `remits-actions` |
+| `region` | yes | e.g. `us-east5`, `us-east1` |
+| `sampleHeap` | no | Default true — one class histogram + heap composition sample (brief stop-the-world) |
+| `top` | no | Top classes to return. Default 20, max 100. |
+| `includeThreadDump` / `threadLimit` | no | Fuller thread dump beyond the built-in top-thread preview |
+| `includeLogs` / `logLookbackMinutes` / `logLimit` | no | Recent WARNING+ log signals for the same service |
+
+### `mcp_support_ticket_queue`
+List and filter tickets **across an account and its descendants** so you can choose what to work on. Lifecycle
+actions stay on `mcp_support_ticket`.
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `action` | no | `list` (default) |
+| `accountId` / `accountIds` / `includeChildren` / `includeRoot` | no | Queue scope. Defaults to the current account **and its descendants**. |
+| `statuses` / `status` | no | Defaults to `open`, `accepted`, `in_progress`, `pending_review`. `['all']` disables filtering. |
+| `priorities` / `types` / `sources` / `tags` | no | Additional filters |
+| `assignedTo` / `unassigned` | no | Assignment filters |
+| `implementationAccountId` | no | Filter by owning `PLATFORM`/`PRODUCT` account |
+| `search` | no | Case-insensitive across subject, description, account, affected component, sender, tags |
+| `sortBy` / `sortDirection` | no | `triage` (default-style: critical/high unassigned first), `updated`, `priority`, `status`, `account` |
+| `limit` / `offset` / `scanLimitPerAccount` | no | Paging and scan bounds |
+| `dataMode` | no | Normal agent work uses the **prod** ticket queue |
+
 ## Multi-Session Support
 
 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 +2599,12 @@ 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 the account tree below an account, or its users | `mcp_account_user_admin` (`action:'hierarchy'` with a `depth`, or `action:'users'`). `account-info.json` deliberately carries only direct children plus counts. |
+| 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. |
+| 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. |
 | 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. |