@remits/remits-cli 0.1.113 → 0.1.115

package/skills/remits-cli/references/branch-variants.md

@@ -0,0 +1,391 @@
+# Branched Component Variants
+
+> A `remits-cli` skill reference. **Load this when** one account needs different behavior from a component another account owns, or you are working from a non-trunk checkout, or you are promoting a branch back to trunk.
+>
+> The table of contents below carries **real line numbers** (`- L84  Some Heading`), resolved when
+> this file is installed, so they are never stale. Read the head, pick your sections, and offset-read
+> only those. The entry text is the heading verbatim, so it also greps.
+
+## Table of Contents
+
+- [Branched Component Variants (per-account component overrides)](#branched-component-variants-per-account-component-overrides)
+  - [Which world does your working tree resolve? (read this before you run anything)](#which-world-does-your-working-tree-resolve-read-this-before-you-run-anything)
+  - [Two levers, two different questions](#two-levers-two-different-questions)
+  - [The SDLC is identical on a variant branch](#the-sdlc-is-identical-on-a-variant-branch)
+  - [Where am I in the promotion loop?](#where-am-i-in-the-promotion-loop)
+  - [Subscribing, unsubscribing, retiring](#subscribing-unsubscribing-retiring)
+  - [Danger profile on a variant branch (different, not absent)](#danger-profile-on-a-variant-branch-different-not-absent)
+  - [Inspecting branches and drift](#inspecting-branches-and-drift)
+  - [Diagnosing a variant](#diagnosing-a-variant)
+
+## Branched Component Variants (per-account component overrides)
+
+When one account — often a customer nested several levels down — needs *slightly* different behavior from
+a component owned by its platform or product account, the answer is a **branch variant**: a durable,
+branch-scoped overlay of that component, resolved only by accounts subscribed to that branch. The wrong
+answer is per-account `if/then` logic inside the origin component.
+
+> **`features/subscriber-branch-promotions.md` (`mcp_get_guide`) is the guide for this.** It owns the
+> mental model, the five scenarios you will actually meet, the full promotion procedure, what happens to a
+> `new_` component across a promotion, merge-conflict resolution file by file, removals, and the approval
+> gates for running a promotion as a coding agent. **Load it before promoting anything.** This section
+> covers only the CLI surface and the traps that bite at the command line.
+
+Three facts that everything else follows from:
+
+- **A branch is not an account.** Subscription is many-to-many, it applies to the subscribing account
+  *and its descendants*, and a subscribing account still has its own trunk components which merge on top.
+- **A variant keeps the origin's component id** — it is an overlay, not a copy. That is what makes drift
+  computable.
+- **Sparseness is computed at sync time, not declared.** A git branch physically contains every file; only
+  the ones whose content *differs from trunk* become variants. A file that is absent becomes a
+  **tombstone**; a file whose id prefix is not a live trunk id (`new_Foo.groovy`) becomes a **branch-only**
+  component keyed by name.
+
+### Which world does your working tree resolve? (read this before you run anything)
+
+You will work from **two different checkouts of the same repo**, and they behave differently on both ends
+of 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_branch`) | that branch | trunk + **`feature_branch`** overlays | **`ComponentVariant` overlays on that branch only** — never touches trunk rows |
+
+Do not infer this from the branch name. Ask:
+
+```bash
+remits-cli components status
+```
+
+```
+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)
+```
+
+**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 that suite — including fixture accounts subscribed to their own generated branches —
+to your branch, where they have no variants, and they all read trunk. The suite fails in a way that looks
+exactly like a resolution regression. (Live example: a branch-variant suite scored 4/15 from a variant
+checkout and 15/15 from trunk, with no code difference.) **Run branch-variant suites from trunk, or pass
+`--variant-branch none`.** Before concluding "variant resolution is broken", re-run from trunk.
+
+**Two other things differ from trunk while you work on a branch:**
+
+- **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 and never repoints the account's trunk
+  branch. A `new_*` file stays `new_*`.
+
+**Start from a current branch, not just an isolated workspace.** Before the first edit in a variant
+checkout:
+
+```bash
+git fetch origin
+git status --porcelain
+git log origin/<branch>..<branch>              # must be empty: nothing local-only
+git log <branch>..origin/<branch>              # must be empty: not behind the remote
+remits-cli components promotion --branch <branch>
+```
+
+`components promotion` reads the remote and reports whether the branch is also current with trunk. If it
+says `diverged` or `STALE`, merge trunk in or sync first, as instructed, before writing new work. A
+workspace lane prevents another agent from overwriting your staged Redis snapshot; it does not say which
+commit your files are based on.
+
+**Branch-local `account-info.json` can describe a subscriber.** On a variant branch the repository is
+still the OWNER's component repo — files overlay that owner's trunk ids and sync writes overlays owned by
+that owner. But when the checkout was synced from a subscribing account reached through an
+`AccountRelationship` edge, and the branch has **exactly one** subscriber, the branch's
+`account-info.json` is intentionally rooted at that subscriber. With **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. Overlay ownership is unaffected either way.
+
+Read `resolution` before acting from any checkout — in particular `resolution.accountId` (the account this
+checkout should be treated as; **read this, not the top-level `id`**), `resolution.role`,
+`resolution.componentOwnerAccountId` (whose trunk ids the files overlay and whose overlays a sync writes),
+and `resolution.componentBranch` / `resolution.scopeAccountId` (the branch and the path anchor that made
+this subscriber resolution possible). 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
+(`remits-cli components sync --account-id 101`), then `git pull --ff-only`.
+
+### Two levers, two different questions
+
+- **`--as-account <id>`** changes **who** the run executes as, so that account's own edge picks the branch.
+  Answers *"what does customer X actually get?"* Only narrows downward (the target must be reachable from
+  an account you already have access to). It works for a `parentId`-less, membership-only subscriber too:
+  the anchor is derived from the branch you name, or from the account's single branch subscription. It
+  **refuses to guess** when an account has several edges each carrying a different branch — the run then
+  resolves trunk, and you must name the branch.
+- **`--variant-branch <name>`** changes **which branch**, from any checkout. Answers *"what does branch Y
+  look like?"* — most useful for verifying a freshly committed branch **before** any edge subscribes to
+  it. `--variant-branch none` (or `trunk`) forces production/subscription semantics without leaving the
+  branch.
+
+Both work on `remits-cli test run` and `remits-cli token`; `--variant-branch` also works on
+`remits-cli tools` and `remits-cli tool`, so tests, browser URLs, tool discovery, and tool execution can
+all inspect the same committed variant world.
+
+The strongest end-to-end proof for a UI-visible variant is a token, not a log line:
+
+```bash
+remits-cli token --path embeddable/index/50 --as-account 101   # subscriber -> variant
+remits-cli token --path embeddable/index/50                    # owner      -> trunk
+```
+
+Each answer carries a **`resolution`** block for the account the token executes as — `role`,
+`componentBranch` and its owner, `resolvedDatabaseName`, `resolvedDomainName`, `scopeAccountId`, and a
+one-sentence `summary`. Read it before opening the URL: `accountId` alone does not say whether a branch
+overlay applies or which storage namespace the page will read, and those are exactly what
+`--as-account` is being used to change.
+
+Separate branch fields, because these questions answer differently and can disagree:
+
+| Field | Answers |
+|---|---|
+| `componentBranch` | what **this token** will resolve |
+| `componentBranchSource` | `probe` (an explicit `--variant-branch`), `subscription` (the account's edge), or `trunk` |
+| `subscribedComponentBranch` | what the **account graph** says, independent of this token |
+| `componentBranchAnchored` | whether **this resolution actually reached** that subscription |
+
+A single `componentBranch` field would have reported `trunk` under `--variant-branch X`, for a token that
+resolves `X`.
+
+**Subscribing to a branch and resolving through it are different facts.** An account subscribes on an
+edge; a *request* resolves through that edge only when something named the path (`--as-account`, the
+edge's own host, an explicit `--variant-branch`). An account with no `parentId` and several upward links
+resolves trunk by design — the resolver refuses to guess a path. So this is a normal, explainable state:
+
+```
+"componentBranch": null,              // this token resolves TRUNK
+"componentBranchSource": "trunk",
+"subscribedComponentBranch": "forked", // ...but the account does subscribe
+"componentBranchAnchored": false       // ...and nothing anchored this request to it
+```
+
+Reading `componentBranch` alone there tells you the account is on trunk, which is true — and leads you to
+conclude it has no branch, which is false. If several edges carry branches, none is picked for you:
+`subscribedComponentBranch` is `null` and `subscribedComponentBranches` lists them.
+
+Under a probe, `componentOwnerAccountId` is the **nearest account on the token's resolution path that owns
+variant rows for X** — not an edge lookup, which answers `null` for the ordinary case of a variant
+committed before anything subscribes to it. `null` means no account on that path owns rows for X, and what
+that implies depends on the account, so read `summary`:
+
+- **on trunk** — the page resolves what it would without the probe; the branch is not committed yet.
+- **resolving through a subscription** — the probe **suppresses** it. `variantBranch` outranks the
+  subscription before it is consulted, so the page resolves **trunk**, not the overlays that account
+  normally gets. Drop `--variant-branch` to see the subscription.
+- **subscribed but not anchored** — it was already resolving trunk before you probed. Dropping
+  `--variant-branch` will *not* by itself show you the branch; name the path as well.
+
+The page itself then states the same facts. Its hidden `remits-session-info` line — which appears in an
+accessibility snapshot with no script — carries `Account` (what it runs as), `Addressed Account` (what
+the URL/token named), `Data Lane`, `Component Branch`, `Variant Applied`, and `Scope Account`.
+
+**`Component Branch` is the branch SELECTED; `Variant Applied` is what actually overlaid.** They are two
+fields because a branch can be selected and overlay nothing: `--variant-branch missing_branch` reports
+`Component Branch: missing_branch` while the page renders trunk components. So read `Variant Applied` —
+the `ComponentVariant` row id this page's component resolved through, or `none` — when the question is
+"did my variant apply?". That is a far sharper signal than inspecting the rendered markup for a style you
+expected.
+
+If `components status` shows staged entries that you cannot safely clear, isolate verification in an
+unused staging namespace instead of deleting someone else's cache:
+
+```bash
+remits-cli test run --test "Invoice Tests" --branch promotion-check-empty --variant-branch none --as-account 101
+remits-cli token --path embeddable/index/50 --branch promotion-check-empty --variant-branch none --as-account 101
+```
+
+Here `--branch` is only the CLI staging-cache namespace, and `--variant-branch none` keeps runtime
+resolution on production/subscription semantics. Do **not** use this pattern with `components sync` or
+`components commit`: for those commands `--branch` is the GitHub branch to reconcile.
+
+### The SDLC is identical on a variant branch
+
+```bash
+git fetch origin
+git checkout feature_branch
+git pull --ff-only origin feature_branch
+remits-cli components promotion --branch 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"                    # the feature_branch world
+remits-cli test run --test "Invoice Tests" --as-account 101   # ...as the real subscriber
+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
+```
+
+Promotion back to trunk is a **git** operation followed by a **trunk** sync — the platform merges nothing
+for you, and merging a branch promotes its **deletions** as hard deletes. Do not improvise it: follow
+`features/subscriber-branch-promotions.md`. For a real trunk promotion with many `new_` files, use
+`remits-cli components sync --summary --timeout-ms 300000`; the platform may need longer than the default
+60 seconds to create rows, push rename/meta commits, and regenerate account metadata.
+
+### Where am I in the promotion loop?
+
+```bash
+remits-cli components promotion            # the branch you are standing on
+remits-cli components promotion --branch forked --json
+```
+
+**Run this before every promotion step and after every one.** It reports only — no git, no writes — and it
+reads the remote (which is what the platform syncs from, not your working tree). It works from either
+checkout, because it resolves the branch's owner itself. It exits non-zero while blockers remain, so treat
+that as "do not proceed".
+
+| Phase | Meaning | Next |
+|---|---|---|
+| `converged` | branch == trunk | nothing to do; this is also what a **finished** promotion looks like |
+| `ready` | ahead of trunk, current with it | promote |
+| `diverged` | behind trunk | `git merge <trunk>` into the branch, re-sync, re-read the plan |
+| `awaiting-merge-back` | fully contained in trunk, trunk has moved on | **steps 4–5 are owed** — merge trunk back and re-sync |
+
+Two things it tells you that nothing else does:
+
+- **Which commit the stored counts describe, on BOTH axes.** An overlay is stored only while a file
+  differs from trunk, so the stored set is a statement about a (branch, trunk) pair and either side moving
+  makes it stale: `[STALE — does not match the branch HEAD]` (the branch was pushed since) or
+  `[STALE — matches the branch HEAD, but trunk has moved since]`. The second is the easy one to miss —
+  measured live, a branch at its own synced HEAD reported 2 stored overlays against a real plan of 21.
+- **That a promotion is unfinished.** `awaiting-merge-back` is what a promotion that *looked* successful
+  leaves behind: trunk is correct and its tests pass, while the subscriber silently keeps resolving its
+  pre-promotion overlays — including for any fix made afterwards. **A trunk sync succeeding is step 2 of 5,
+  not completion.**
+
+### Subscribing, unsubscribing, retiring
+
+```bash
+remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]
+remits-cli components branch <name> --unsubscribe <accountId>
+remits-cli components branch <name> --retire [--force]
+```
+
+Branch administration commands act **as the account you are running from**, which is treated as the branch
+**owner** — run them from the owner's trunk checkout. Authorization is downward-only.
+
+- **`--subscribe` sets the branch on an edge that must already exist — it cannot create one.** Failure
+  reads *"Account N has no relationship edge to 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.
+  - **Many older accounts have no relationship row at all** — the edge table was added after the fact and
+    never backfilled, so an account whose parent link is only `Account.parentId` resolves fine but has
+    nothing 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** with `--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 one you intended. `--subscribers` prints
+  `via primary|membership edge -> parent N` so you can confirm.
+- **Primary-edge subscriptions are structural.** If the selected edge is the account's `parentId` edge,
+  subscribing it makes that account and descendants resolve the branch by default even though `parentId`
+  still points at the same parent. The server refuses this write unless you pass
+  `--confirm-primary-edge`; run `--dry-run` first and prefer a membership edge for fork/pilot
+  subscriptions.
+- **Retiring is explicit.** Deleting the *git* branch does **not** remove its overlays; subscribers would
+  keep resolving a branch that no longer exists. `--retire` refuses while subscribers remain unless you
+  pass `--force`.
+
+**Every component kind can be varied** — `schema`, `reader`, `action`, `embeddable`, `i18n`, `htmltemplate`,
+`rule`, `test`, `utility` (agent), `tool`, `prompt` — including tombstones and branch-only additions. A
+**schema** variant deserves the same care as a trunk schema change: it can change the JSON schema *and*
+`collectionName`, so it changes validation and where the subscriber's documents physically land. A
+branch-only agent (a `new_*` file under `components/agents/`) defaults to `type: AI` so agent lookups
+find it.
+
+A variant speaks the same `.meta.yml` vocabulary trunk does; keys outside that set are ignored on purpose,
+because trunk cannot express them either — allowing them would mean a branch behaves one way and silently
+loses that behavior the moment it is promoted. **One documented exception: an agent's `tools:` list cannot
+be overridden by a variant.** It maps to a GORM association that `agent()` populates from the trunk row, so
+a `tools:` list on a branch is ignored. Change trunk, or have the agent select tools at runtime.
+
+### Danger profile on a variant branch (different, not absent)
+
+The `component-integrity.md` worst case — *"a missing file hard-deletes a live component"* — **does not
+apply on a variant branch.** Variant sync writes overlay rows only; it cannot create, delete, rename, or
+overwrite a trunk component. That makes a variant branch a genuinely safer place to iterate.
+
+The analogous hazard is different, and you must still respect it:
+
+- **A trunk component with no file on the branch becomes a TOMBSTONE**, which *hides* that component from
+  every subscriber. It is reversible (restore the file, re-sync) and never touches trunk — but to a
+  subscribing account it looks exactly like the component was deleted. Confirm every omission is
+  deliberate before syncing.
+- **Deleting a file means "remove the component", not "stop overriding it."** To withdraw an override,
+  make the file identical to trunk again — the sync then removes the variant row.
+- **Keep the branch rebased.** A branch physically carries every file, so anything trunk added *after* the
+  branch was cut is absent from it. The sync now asks git which of those absences are real deletions
+  (comparing against the merge base) and refuses to tombstone the rest, reporting them as
+  `skipped: absent from the branch but never deleted on it`. Treat any such entry as "merge trunk in" —
+  if an older sync already stored one of those absences as a tombstone, a non-dry-run sync prunes it and a
+  dry run reports `wouldPrune: true`. The classification falls back to a conservative ratio guard when
+  GitHub's compare is unavailable or its file list comes back truncated, which the sync output says
+  explicitly.
+- **Use `components sync --dry-run` before risky variant syncs.** It reports `overridden`, `added`,
+  `removed`, `unchanged`, `skipped`, and `errors` without writing rows, caching the sync SHA, or clearing
+  staging. Existing overlay ids appear as `variantId`; an `unchanged` row with `pruned:true` means the
+  branch has converged back to trunk and the overlay would be removed. It is rejected on trunk, and
+  `components commit --dry-run` is unsupported because `commit` performs local git writes before syncing.
+- **The sync refuses a wholesale removal.** Above roughly a third of a kind — or **100% of a kind at any
+  size** — it aborts that kind, reports why, and points at a rebase. Rebasing is almost always the real
+  fix. Only when the removals are genuinely deliberate, re-run with `--force-tombstones`.
+- **Deleting a trunk component cascades**: its overlays on every branch are removed with it.
+- **A removal you did not author usually means TRUNK is drifted**, not that the branch deleted something.
+  A component that exists in the DB with **no file on trunk** is missing from every branch too, so it
+  shows up as a phantom `removed` in *every* branch preview — while the trunk sync separately tries to
+  hard-delete it on every run. Check whether the file exists on trunk before "fixing" it on the branch;
+  the repair is to mirror the live DB source back into the trunk repo (`component-integrity.md`).
+
+### Inspecting branches and drift
+
+```bash
+remits-cli components branches                                  # branches with variants, counts, drift
+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
+remits-cli components branch feature_branch --json              # the stored overlay content
+```
+
+**Drift is the number to watch.** Each variant records the trunk content hash at the moment it was cut
+(`originHash`). When the origin component later changes, the variant is reported **DRIFTED** — the branch
+is now based on a stale version and someone should reconcile it. Before editing an origin component, check
+whether variants of it exist: the owner account's `account-info.json` carries a `componentBranches`
+summary, and `components branches` gives the live view. A change to the origin silently drifts every
+branch that overlays it.
+
+**`components branches` only lists branches that already have overlays.** A branch you just pushed is
+invisible here until its first sync — that is not an error. Preview it by name (`components sync --dry-run`
+from that checkout).
+
+**Trunk moving also invalidates a branch.** Variant sparseness compares branch content against *current*
+trunk, so a trunk change can make an overlay obsolete without the branch changing at all. A trunk sync
+drops the affected branches' cached sync verdicts, so the next `components sync` on the branch really
+re-evaluates instead of answering *"No changes detected"*. After promoting anything, re-sync each live
+branch.
+
+**The admin UI has the same surface**, which is what to point a non-CLI user at: the *owner* account page's
+**Component branches** box (per-branch counts, drift, subscribers, and Preview / Sync / Retire), and the
+*subscriber* account page's **Branch variants** box plus **GitHub → Fetch `<branch>` variants**. Both open
+the same result panel — grouped plan, subscribers, a Monaco diff of trunk vs branch per changed field, and
+a confirm-gated override when the removal guard refuses. Preview there is the same `--dry-run`.
+
+### Diagnosing a variant
+
+- `remits-cli components branch <name> --json` — the stored overlay content and what it overrides.
+- The compile signature `variant:<id>:<hash>` in `Using Cached BCD` logs — proves a variant actually ran.
+- A test/tool response reports `testComponentSource` as `staged` | `variant` | `db`, so you can see which
+  layer the run resolved without reading logs.
+
+> **A populated staging cache makes a variant look broken.** Anything carrying a CLI `TestMode` — a
+> `remits-cli token` URL, `/s/<tokenKey>/...`, an `X-Auth-Token` request, a script-loader embed — resolves
+> the STAGED layer, which outranks the variant. So with components staged under the same branch/user, a
+> tokenized page reports `Component Branch: <branch>` but `Variant Applied: none` and renders trunk, while
+> an anonymous `?account_id=` request to the same page reports the variant. That is the documented
+> precedence (staged -> variant -> trunk) working correctly, and it reads exactly like "tokens break
+> variant resolution". **Run `remits-cli components clear --all` before verifying variant resolution
+> through any tokenized entry point**, or check `remits-cli components status` first.

package/skills/remits-cli/references/cli-state.md

@@ -0,0 +1,158 @@
+# Local State: What remits-cli Knows and Where
+
+> A `remits-cli` skill reference. **Load this when** a question is about repo discovery, authentication state, what a command actually sent or received, or where a large tool response went.
+>
+> The table of contents below carries **real line numbers** (`- L84  Some Heading`), resolved when
+> this file is installed, so they are never stale. Read the head, pick your sections, and offset-read
+> only those. The entry text is the heading verbatim, so it also greps.
+
+## Table of Contents
+
+- [Required Local Index Reads](#required-local-index-reads)
+- [Big Picture: How remits-cli State Is Organized](#big-picture-how-remits-cli-state-is-organized)
+- [Account Repository Index](#account-repository-index)
+- [Local State Files](#local-state-files)
+
+## Required Local Index Reads
+
+These files are decision inputs. Read them when the related decision depends on them.
+
+- `~/.remits-cli/account-repos.json`
+  - The inventory of every local Remits repo. Account repos are keyed by numeric account id.
+  - It also contains the reserved **`platform`** entry: the local clone of the core Remits platform repo (`type:'PLATFORM_REPO'`, with its `directory` path). `remits-cli` clones it on first authenticated run if it is missing (default `~/remits`, override with `REMITS_PLATFORM_DIR`). Read this entry when you need to analyze a back-stage seam or open a platform-fix PR.
+  - Read before choosing a repo outside the current working directory.
+  - Read when a support ticket references an account and you need to locate the correct local repo.
+  - Read before concluding that a repo does not exist locally.
+- `~/.remits-cli/config.json`
+  - Read when service lifecycle, dashboard, or preferred-agent behavior matters.
+- `~/.remits-cli/service-state.json`
+  - Read when the local control center URL, current dashboard port, repo-scan summary, or websocket status matters.
+  - Read when the user asks whether the remits-cli service is running or where to open the browser view.
+- `~/.remits-cli/agents.json`
+  - The agent sessions registered from THIS machine, each with the process it is anchored to.
+  - Read when `remits-cli agent work` says no agent is registered, or when several agents are
+    registered and a command needs `--agent-id`.
+- `~/.remits-cli/activity.log`
+  - Read when diagnosing service lifecycle, websocket, agent registration, or ticket-routing failures.
+- `~/.remits-cli/sessions.json`
+  - Read when authentication state, active accounts, base URLs, websocket topics, or per-account data mode matters.
+- `./.remits-cli/current-session.txt`
+  - Read before opening repo-local session logs so you know which session file is current.
+- `./.remits-cli/sessions/<current-session>.jsonl`
+  - Read when the question is about what HTTP calls the repo recently made through remits-cli, which payload was sent, or what response/error came back.
+- `./.remits-cli/tool-responses/<callId>.json`
+  - Read when `remits-cli tool` says the full payload was stored externally.
+- `./.remits-cli/tools/tools.json`
+  - Read when the question is about available tool names, cached schemas, or why a tool invocation shape may be invalid.
+- `account-info.json`
+  - Read in the target repo before making component changes or assuming account ownership.
+- `account-configurations.json`
+  - Read only when account configuration values matter. It is generated separately because configuration maps can be large and `account-info.json` deliberately omits them.
+
+Do not rely on memory for these indexes. Read the file that governs the decision you are making.
+
+## Big Picture: How remits-cli State Is Organized
+
+Think about remits-cli as two cooperating layers:
+
+1. **Global machine state** in `~/.remits-cli/`
+   - This is the cross-repo control plane.
+   - It answers questions like:
+     - which accounts are authenticated
+     - which repos exist locally
+     - whether the background service is running
+     - where the control center lives
+     - which agent sessions are registered from this machine
+
+2. **Per-repo state** in `./.remits-cli/`
+   - This is the request/response and cache layer for one specific working tree.
+   - It answers questions like:
+     - which repo-local session log is current
+     - which `/cli/*` calls were made from this repo
+     - where a large tool response was written
+     - which tool schemas were most recently cached here
+
+When a user asks an indirect question, map it to the right layer first:
+
+- "Why did this ticket open in the wrong repo?" → start in global state.
+- "What exact payload did this tool call send?" → start in per-repo state.
+- "Why is the dashboard showing stale repos?" → start in `service-state.json` and `account-repos.json`.
+- "Why is the browser page not showing websocket activity?" → start in `service-state.json` and `activity.log`.
+- "Why is my agent not getting tickets?" → start in `agents.json`, then `remits-cli agent list`.
+
+Agents should use this mental model before guessing.
+
+## Account Repository Index
+
+The account repository index file is located at: `{{ACCOUNT_REPO_INDEX_PATH}}`
+
+This JSON file is automatically maintained by `remits-cli` and tracks all known Remits account repositories on this machine. It is updated whenever any `remits-cli` command runs from an account repo directory. The file maps account IDs to their metadata:
+
+```json
+{
+  "37": {
+    "accountId": 37,
+    "name": "Acme Corp",
+    "directory": "/Users/you/Projects/remits-acme-corp",
+    "updatedAt": "2026-03-23T12:00:00.000Z"
+  }
+}
+```
+
+**Use this index to:**
+- Discover which account repos exist on this machine when working from a different directory
+- Navigate to another account's repo to read its `account-info.json` and component source
+- Resolve account names and IDs without making remote API calls
+- Support cross-account workflows where an agent in one repo needs context from another
+
+If the index file doesn't exist yet, run any `remits-cli` command from an account repo to bootstrap it.
+
+## Local State Files
+
+**Global** (`~/.remits-cli/`):
+- `sessions.json`
+  - Source of truth for authenticated account sessions, keyed by `accountId + dataMode + baseUrl` so the same account can hold separate sessions for different environments (e.g., localhost vs production).
+  - Each entry contains auth token, user info, websocket topic, data mode, base URL, and timestamp.
+  - Read this when a question involves auth, account selection, websocket topic coverage, or which session a command should resolve.
+- `config.json`
+  - Global CLI preferences.
+  - Currently most important for preferred agent selection, but treat it as the general machine-level config file.
+- `service-state.json`
+  - Runtime snapshot for the currently running remits-cli service.
+  - Includes dashboard URL, chosen port, repo-discovery summary, and websocket connection state.
+  - This is the first file to read when the user asks "is remits-cli running?", "what port is the dashboard on?", or "why isn't the browser page showing my connections?"
+- `account-repos.json`
+  - Index of all known account repositories on this machine.
+  - Built from `account-info.json` discovery plus best-effort updates when commands run inside an account repo.
+  - This is the repo-resolution file. Read it before deciding that a repo is unavailable locally.
+- `listener.pid`
+  - PID of the background remits-cli service process.
+  - Use it only to confirm process presence; use `service-state.json` for richer service details.
+- `agents.json`
+  - The agent sessions registered from this machine, each with the process it is anchored to.
+  - Read this when a command asks for `--agent-id`, or when an agent appears registered locally but
+    is missing from `remits-cli agent list` (that gap IS the "why am I not getting tickets" answer).
+- `activity.log`
+  - Human-readable chronological event log for service lifecycle, websocket events, agent
+    registration/heartbeat, and ticket routing.
+  - This is usually the best forensic file for "what happened?" questions.
+
+**Per-repo** (`./.remits-cli/`):
+- `tools/tools.json`
+  - Cached tool definitions for this repo context.
+  - Read this when tool availability or input shape is unclear.
+- `sessions/<name>.jsonl`
+  - Repo-local HTTP request/response log for `/cli/*` calls.
+  - Tokens are redacted and large content fields are summarized.
+  - This is the first file to inspect when the question is "what exactly did remits-cli send or receive from this repo?"
+- `tool-responses/<callId>.json`
+  - Full payload for `remits-cli tool` responses that were too large for the session log.
+  - Prefer this over terminal summaries when investigating tool behavior.
+- `current-session.txt`
+  - Pointer to the active repo-local session log name.
+  - Always read this before opening `sessions/<name>.jsonl`.
+
+Reading rules:
+- Read `current-session.txt` before opening a session log by name.
+- When a tool call says the response was stored externally, open `tool-responses/<callId>.json` instead of inferring from the terminal summary.
+- If a question spans both global and repo-local behavior, inspect both layers and explain which facts came from which layer.