@remits/remits-cli 0.1.112 → 0.1.114

package/skills/remits-cli/references/command-reference.md

@@ -0,0 +1,268 @@
+# Getting Started and Command Reference
+
+> A `remits-cli` skill reference. **Load this when** you need the exact command surface: authentication, host versus data mode, the tool execution lifecycle, hierarchy-scoped reads, and every flag.
+>
+> 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
+
+- [Getting Started](#getting-started)
+  - [Authentication](#authentication)
+  - [Host vs Data Mode](#host-vs-data-mode)
+  - [Tool Execution Lifecycle](#tool-execution-lifecycle)
+  - [Hierarchy-scoped tool reads](#hierarchy-scoped-tool-reads)
+  - [Data Mode](#data-mode)
+- [Command Reference](#command-reference)
+  - [Prod banners and retryable failures](#prod-banners-and-retryable-failures)
+
+## Getting Started
+
+### Authentication
+
+Authenticate once per session. Opens the user's browser for OAuth login:
+
+```bash
+remits-cli auth --account-id <ACCOUNT_ID>
+remits-cli auth --account-id <ACCOUNT_ID> --base-url http://localhost:8080
+```
+
+- `--account-id` is auto-resolved from `account-info.json` when you're inside an account repo, so you can usually just run `remits-cli auth`. Pass `--account-id <ID>` explicitly to target a different account (e.g., authenticating into a child account from a parent-account repo) — the explicit flag always wins over the repo's `account-info.json` and any prior session.
+- `--base-url` targets a specific platform instance (e.g., localhost for development). Sessions are stored per account + base URL + data mode, so authenticating against localhost does not overwrite a production session for the same account.
+- If any command returns a 401 error, re-run `remits-cli auth` (with the same `--base-url` if you were targeting a non-default instance).
+
+### Host vs Data Mode
+
+Treat host selection and data mode as two separate decisions:
+
+- `--base-url` chooses the Remits host: localhost vs a deployed environment.
+- `--data-mode` chooses the data segment on that host: `test` vs `prod`.
+
+Examples:
+
+```bash
+# Deployed prod host, but test data segment
+remits-cli tools --base-url https://your-prod-host --data-mode test
+
+# Localhost host, but prod data segment on that localhost instance
+remits-cli tool --base-url http://localhost:8080 --name mcp_account_view --data-mode prod
+```
+
+Do not assume `--data-mode prod` implies the deployed prod host, or that `--data-mode test` implies localhost. If host matters, read `~/.remits-cli/sessions.json` first and pass `--base-url` explicitly.
+
+### Tool Execution Lifecycle
+
+`remits-cli tool` supports both synchronous and asynchronous execution. Use normal synchronous execution
+for quick investigation tools:
+
+```bash
+remits-cli tool --name "mcp_account_view" --input '{"accountId": 37}' --data-mode prod
+```
+
+**There are two independent async mechanisms — do not confuse or stack them:**
+
+1. **The tool's own async mode** (`mcp_run_action` / `mcp_run_agent`, via `executionMode:"async"` in the
+   tool input). The tool spawns the long work server-side and **returns immediately in the same HTTP
+   response** with its own run identifiers — `actionRunId` (or `agentRunId`) and, for agents, a stable
+   `sessionId`. You poll it with the tool's **own** status protocol (`controlAction:"status"`). This is the
+   preferred path for long Actions/Agents, because the run ids come back on the very first call.
+
+2. **The CLI transport async** (`--async true`). This wraps *any* tool call in a background server task and
+   returns a CLI-level `callId` immediately, which you poll with `remits-cli tool status --call-id`. Use it
+   for long tools that do **not** have their own async mode. Its start response carries `callId`,
+   `status:"running"`, `threadGroupingId`, `accountId`, `branchName`, and `dataMode` — but **not** any
+   tool-specific ids, because the tool has not run yet; those arrive inside the `result` of the polled
+   completed status.
+
+For `mcp_run_action` / `mcp_run_agent`, prefer mechanism (1) alone — it already makes the call non-blocking
+**and** returns the run ids up front. Pass your own `actionRunId`/`agentRunId` so you can poll it
+deterministically:
+
+```bash
+remits-cli tool --name "mcp_run_action" --input '{"accountId":49,"actionId":200,"executionMode":"async","actionRunId":"my-stable-run-id","actionInput":{"sourceDocumentId":"..."}}' --data-mode prod
+```
+
+Every tool response is saved to `./.remits-cli/tool-responses/<callId>.json`.
+
+### Hierarchy-scoped tool reads
+
+For read/discovery tools, the account resolved from the checkout/session is the **scope root**, not proof
+that the business record is owned by that account. This closes the common support loop where you know a
+precise document, object, event, or indexed source id but do not yet know which child account owns it.
+
+Use the tool flags rather than editing JSON by hand:
+
+```bash
+remits-cli tool --name mcp_firestore_search \
+  --input '{"collection":"statements","documentId":"1234"}' \
+  --scope children --data-mode prod
+```
+
+Available flags:
+
+| Flag | Meaning |
+|---|---|
+| `--scope self|children|hierarchy` | Expand from the repo/session account for read/discovery. Exact-id lookups usually default to `children`; broad searches default to `self` unless widened. |
+| `--target-account-id ID` | Exact owner/execution account when already known. Required by mutating tools. |
+| `--account-ids 1,2,3` | Explicit bounded owner list. The platform verifies every id against the scope root. |
+| `--anchor-account-id ID` | Path-disambiguation anchor for multi-parent account relationships. |
+
+The CLI merges these into `--input`; a value already present in `--input` wins. Tool responses echo
+`scopeRootAccountId`, `scope`, `accountIds`, and, when an exact owner is discovered,
+`resolvedTargetAccountId`. Feed that returned owner to `mcp_firestore_patch`, action/test runs, and browser
+tokens. Mutating tools do not infer or fan out writes.
+
+The implicit account ceiling is intentionally different by shape: broad searches stay capped at 100 accounts
+unless the tool says otherwise, while exact-id discovery may span up to 1000 accounts by default. If a broad
+tool returns `scopeTooBroad`, narrow with `--target-account-id`, `--account-ids`, or a smaller `--scope`.
+
+`mcp_firestore_search` handles exact Firestore document ids. `mcp_index_search` handles fuzzy/semantic
+lookup through Vertex. `mcp_bigquery_query` handles warehouse lookup/query with server-resolved
+`{table_current}`/`{table}` placeholders and the scoped `{account_filter}` predicate. BigQuery is a prod
+analytics surface, so use `--data-mode prod` when you intend to query it.
+
+Poll a CLI-transport async call (mechanism 2) by call id:
+
+```bash
+remits-cli tool status --call-id <callId> --data-mode prod
+```
+
+Pass `--wait true` to have the CLI process poll locally until the transport call completes (short polling
+requests instead of one long HTTP connection):
+
+```bash
+remits-cli tool --name "some_long_tool_without_its_own_async" --async true --wait true --input '{...}' --data-mode prod
+```
+
+Stacking both (`--async true` **and** `executionMode:"async"`) works but is redundant: the tool's
+`actionRunId`/`agentRunId`/`sessionId` then appear only in the polled completed `result`, not in the CLI
+start response — which is why the start response looks "incomplete." Pick one mechanism.
+
+`--timeout-ms <ms>` controls the per-request HTTP timeout. Prefer async execution over a large timeout for
+multi-minute work so the server task is not tied to one HTTP connection.
+
+### Data Mode
+
+Controls whether you work with test data or production data. **Default is `test`.**
+
+```bash
+remits-cli data-mode                  # Show current mode
+remits-cli data-mode set prod         # Switch to prod for investigations
+remits-cli data-mode set test         # Switch back to test for development
+```
+
+## Command Reference
+
+```
+remits-cli auth [--base-url URL] [--account-id ID] [--data-mode test|prod]
+remits-cli sessions [list|remove] [--account-id ID]
+remits-cli config [set] [--agent claude|codex|gemini]
+remits-cli agent serve [--worker-agent claude|codex|gemini] [--max-concurrent N] [--mode edit|investigate] [--label NAME] [--data-mode test|prod]
+remits-cli agent workers [--json]
+remits-cli agent register [--label NAME] [--data-mode test|prod] [--account-id ID] [--max-concurrent N]
+remits-cli agent work [--wait SECONDS] [--json]
+remits-cli agent status [--state idle|working|paused] [--ticket ID] [--activity "..."] [--step "..."]
+remits-cli agent list [--account-id ID] [--json]
+remits-cli agent map [--account-ids 1,4] [--json]       # who is EDITING which repository, from which checkout/branch/staging lane
+remits-cli agent release
+remits-cli ticket read|accept|status|progress|complete|release|reopen|assign|planning --ticket ID [--status S] [--resolution "..."] [--summary "..."] [--category C] [--assignee EMAIL] [--workstream VALUE] [--planned-in VALUE] [--board-stage VALUE] [--rank N] [--size VALUE] [--blocked-by VALUE] [--notes "..."]
+remits-cli ticket lease|unlease|force-unlease --ticket ID [--reason "..."]   # force-unlease breaks SOMEBODY ELSE'S lease; operator only
+remits-cli ticket where --ticket ID                    # WHERE this work is: repo account, checkout, branch, staging lane, live lease + holder's location, claim, your phase
+remits-cli ticket ask --ticket ID --question "..." [--context "..."] [--to WHO]   # park on a human decision
+remits-cli ticket answer --ticket ID --message "..." [--route false]             # answer it (alias: reply); re-routes by default
+remits-cli ticket message --ticket ID --message "..." [--to a@x,b@y] [--subject "..."] [--channel email]  # PUBLIC — the requester reads it
+remits-cli ticket note --ticket ID --message "..."     # INTERNAL — the next worker and a reviewer read it
+remits-cli ticket deliver --ticket ID --channel email --to a@x [--template T] [--subject "..."] [--idempotency-key K]   # ask for it to be SENT
+remits-cli ticket deliveries --ticket ID [--channel email]   # what is queued to go out, and what already went
+remits-cli ticket delivered --ticket ID --delivery-id ID | ticket delivery-failed --ticket ID --delivery-id ID --reason "..."
+remits-cli ticket tag --ticket ID --tags a,b           # make a cluster of near-identical tickets visible as one
+remits-cli ticket artifact --ticket ID --type TYPE --label "..." [--url U | --content "..."]
+remits-cli ticket participant --ticket ID --email E [--role watcher|requester|agent]
+remits-cli ticket field --ticket ID --key K --value V  # the ORGANIZATION's own field, outside the planning slots
+remits-cli ticket reclaim [--ticket ID | --account-id ID] [--stale-hours 24] [--apply]   # OPERATOR: take back an agent's abandoned ticket
+remits-cli ticket queue --account-id ID [--status ...] [--unrouted] [--unassigned] [--awaiting-response] [--workstream W] [--board-stage S] [--planned-in P] [--search "..."] [--sort-by ...] [--json]
+remits-cli ticket create --account-id ID --subject "..." --type defect|question|task|incident|enhancement [--priority P] [--description "..."] [--tags a,b] [--workstream W] [--affected-component C] [--implementation-account-id ID] [--reference-id KEY]
+remits-cli start [--foreground true] [--port 8787]
+remits-cli stop
+remits-cli status [--base-url URL] [--account-id ID] [--data-mode test|prod] [--json]
+remits-cli whoami [--base-url URL] [--account-id ID] [--data-mode test|prod] [--json]
+remits-cli listen [stop|status] [--foreground true]   # compatibility alias
+remits-cli data-mode [set test|prod]
+remits-cli components stage [--branch <name>] [--workspace <name>] [--changed-only] [--data-mode test|prod] [--json|--verbose]
+remits-cli workspace [show | use <name> | use --auto | clear]
+remits-cli components status [--branch <name>] [--component-type <type>] [--component-id <id>] [--json|--verbose]
+remits-cli components clear [--branch <name>] [--component-type <type>] [--component-id <id>] [--all] [--json|--verbose]   # id alone scopes to one component when unambiguous (ids are type-local; add --component-type if the same id is staged in multiple families); no filter clears the whole branch scope; --all forces the full wipe
+remits-cli components sync [--branch <name>] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary] [--changed-only [--changed-since <ref>]]   # gated; on trunk = full repo->DB reconcile, on a variant branch = ComponentVariant overlays only
+remits-cli components commit [--message "msg"] [--data-mode test|prod] [--force-tombstones]
+remits-cli components branches [--json]                                # branches carrying committed variants, with counts + drift
+remits-cli components branch <name> [--json]                           # one branch: overridden / added / removed, drift flags, subscribers
+remits-cli components branch <name> --diff <componentId> --component-type <kind> [--json]
+remits-cli components branch <name> --subscribers [--json]
+remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]   # make an account resolve this branch
+remits-cli components branch <name> --unsubscribe <accountId>                          # return that account to trunk
+remits-cli components branch <name> --retire [--force]                                 # delete the branch's overlays
+remits-cli test run --test <id|name> [--branch <stagingScope>] [--names "a|b"] [--watch true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]
+remits-cli token [--path <embeddablePathOrId>] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]
+remits-cli token inspect --token <token|tokenKey|URL>                  # inspect token metadata, safety/dataMode evidence, and full context
+remits-cli tools [--branch <name>] [--data-mode test|prod] [--variant-branch <name|none>]
+remits-cli tool --name <toolName> [--branch <name>] [--input "{...}"] [--data-mode test|prod] [--variant-branch <name|none>] [--timeout-ms 60000] [--async true --wait true]
+remits-cli tool status --call-id <callId> [--data-mode test|prod]
+```
+
+For tests specifically:
+- If `--data-mode` is omitted, `remits-cli test run` uses `test`.
+- `--names` is `|`-delimited (a comma still splits a single value) and may be repeated; an unmatched
+  selector fails the run instead of reporting zero cases as success.
+- `--as-account <ID>` runs AS a descendant subscriber so its edge selects the component branch
+  (*"what does customer X get?"*); `--variant-branch <name>` probes a branch from any checkout
+  (*"what does branch Y look like?"*), and `--variant-branch none` forces production/subscription semantics.
+  Omit both and the working tree decides — see `branch-variants.md`.
+- `--branch <stagingScope>` on `test run` selects the Redis staging namespace only. It is useful with
+  `--variant-branch none` when an existing staged cache on the real git branch would shadow committed trunk
+  or variant rows. On `components sync` / `commit`, `--branch` is different: it names the GitHub branch to
+  reconcile.
+- `--force-tombstones` is only for non-trunk variant syncs, when missing trunk component files are known,
+  intentional tombstone overrides. It is rejected on trunk.
+- `--dry-run` is only for `components sync` on non-trunk variant branches. It reports the variant write
+  plan without writing rows, caching the sync SHA, or clearing staging.
+- `--summary` on `components sync --dry-run` prints compact counts, removals/tombstones, skipped items, errors,
+  and warnings instead of the full override/add/remove payload.
+- **Fail-closed sync gates.** On non-trunk variant branches these flags now force a server dry-run first,
+  evaluate that plan before any overlay row is written, and only then run the mutating sync when the plan
+  passes. On trunk, there is no safe dry-run plan, so do not treat these as scoped commit controls:
+  - `--changed-only` — fail unless every planned write is a component **this checkout actually changed**.
+    This is the strongest guard against a sync that quietly rewrites components you never touched. It
+    also fails when the checkout is not a git working tree, because "git could not answer" must never
+    be read as "nothing changed".
+    > **Pair it with `--changed-since <ref>` after you have committed.** On its own `--changed-only`
+    > reads UNCOMMITTED edits, and the documented flow commits and pushes *before* syncing (sync reads
+    > the pushed remote, so it cannot see uncommitted work at all) — so the changed set is empty at
+    > exactly the moment the gate runs, and it refuses the whole plan. `--changed-since origin/main`
+    > (or the commit you branched from) makes the changed set the components your commits touched.
+    > The refusal message says this when it detects the empty-set case.
+  - `--fail-on-removed` — fail if the plan removes or tombstones anything.
+  - `--expected-removed <type:id>` — whitelist the removals you intend (repeatable, or comma-delimited,
+    e.g. `--expected-removed action:5,reader:9`). It **implies** `--fail-on-removed`, so any removal you
+    did not name fails the sync.
+  - `--fail-on-errors` — fail if the server reported any per-component sync error.
+  - `--names-only` — dry-run and print only `BUCKET type:id name` lines for the planned writes, then stop
+    without writing overlays.
+
+  A good default for an unattended promotion is:
+  `remits-cli components sync --summary --changed-only --fail-on-errors`
+
+### Prod banners and retryable failures
+
+- Every command that can touch production (`tool`, `test run`, `components sync`) prints a `PROD DATA`
+  banner naming the operation, the resolved account, and the host — and distinguishes a live **WRITE**
+  from a live **READ** and from a **DRY RUN**. `remits-cli tool` also prints an explicit **TEST DATA WRITE**
+  banner for mutating tool calls in the test lane, including multi-action tools such as
+  `mcp_account_user_admin` where the write is signaled by `input.action` (`account_create`, `user_update`,
+  `edge_update`, etc.). If you see a WRITE banner you did not intend, stop.
+- A tool call that fails **in the platform runtime** rather than in the tool (Groovy reflective dispatch
+  of a runtime-compiled component, an empty connection pool, a Redis reconnect, a lock-wait timeout)
+  now comes back as HTTP `503` with `failureClass: "transient_infrastructure"` and `retryable: true`,
+  and the CLI prints `TRANSIENT INFRASTRUCTURE FAILURE (retryable)`. Retry that **once**; prefer an
+  idempotent input if the tool has side effects. A genuine tool error stays HTTP `500` with
+  `failureClass: "tool_error"` — do **not** retry it, fix the input or the component.

package/skills/remits-cli/references/component-integrity.md

@@ -0,0 +1,175 @@
+# Component Integrity: Repo to Database Reconciliation
+
+> A `remits-cli` skill reference. **Load this when** you are about to run `components sync` or `components commit`, or a sync reported something you did not expect. This is the highest-impact failure mode in remits-cli.
+>
+> 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
+
+- [Component Integrity Rules: Repo ↔ Database Reconciliation (read before any sync/commit)](#component-integrity-rules-repo--database-reconciliation-read-before-any-synccommit)
+  - [How the platform reconciles the repo into the database (the mechanism you must understand)](#how-the-platform-reconciles-the-repo-into-the-database-the-mechanism-you-must-understand)
+  - [The surfaces and their intended behavior](#the-surfaces-and-their-intended-behavior)
+  - [Intended workflows](#intended-workflows)
+  - [Pre-sync safety check (confirm ALL before `components sync` or `components commit`)](#pre-sync-safety-check-confirm-all-before-components-sync-or-components-commit)
+  - [If something looks wrong — stop, don't paper over](#if-something-looks-wrong--stop-dont-paper-over)
+
+## Component Integrity Rules: Repo ↔ Database Reconciliation (read before any sync/commit)
+
+Component source-of-truth mistakes are the highest-impact failure in remits-cli. A repo/DB mismatch can
+hard-delete live components, spawn duplicates, renumber files, or leave the database and repo describing
+different implementations. These rules override the normal fast loop whenever they conflict.
+
+### How the platform reconciles the repo into the database (the mechanism you must understand)
+
+> **First, check which branch you are on.** Everything in this section describes a **TRUNK** sync. Syncing
+> from a **non-trunk branch** is a different, much safer operation — it writes `ComponentVariant` overlays
+> only and can never create, delete, rename, or overwrite a live component row. Run
+> `remits-cli components status` to see which mode your working tree is in, and read
+> `branch-variants.md` for the variant-branch rules (which have their own hazard: tombstones).
+
+`remits-cli components sync` (and the sync phase of `components commit`) calls
+`GitHubClient.syncFromRepository`. On the account's **trunk branch** it is a **full two-way reconcile in
+which the GitHub remote is authoritative over the database.** It reads the **remote repo ZIP — not your
+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).
+- **Delete:** after the create/update pass, **any live DB component whose id has no matching repo file is
+  hard-deleted** (`deleteMissingComponentsFor`), in reverse-dependency order. This runs only when the ZIP
+  "looks healthy" (contains `account-info.json` or `README.md`). Exempt from deletion: `auxiliary` components,
+  README-purpose prompts, and AGENT-purpose prompts.
+
+> ### `auxiliary: true` opts a component OUT of the repo entirely — in BOTH directions
+>
+> This is a silent trap, so know it before you author a sidecar. `auxiliary: true` does not merely
+> "de-emphasize" a component:
+>
+> - **Repo → platform:** the sync **skips the file outright**. A `new_*` component whose `.meta.yml` says
+>   `auxiliary: true` is never created, so it **never gets a real id** and the file is never renamed. It
+>   looks like the sync silently ignored your work — because it did.
+> - **Platform → repo:** the component's save hooks skip pushing source to GitHub, and repo initialization
+>   omits it.
+> - It is also excluded from `getInformation()` (so AI agents do not discover it) and exempt from the
+>   deletion pass above.
+>
+> **Use `auxiliary: true` only for genuinely throwaway components** — ad-hoc reports, experiments, and the
+> ephemeral fixtures a Test creates and deletes at runtime (those are created in Groovy with
+> `auxiliary: true` and must never touch the repo).
+>
+> **Use `auxiliary: false` for anything durable** — above all a Test suite that is a regression guard. If you
+> want it versioned in git, addressable by a stable id, or discoverable by another agent, it is not
+> auxiliary. Symptom to recognize: *"I added `new_Foo.groovy`, synced, and it neither appeared on the account
+> 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 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.** 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
+
+| Command | What it touches | Danger |
+|---|---|---|
+| `remits-cli components stage` (alias: deprecated `push`) | **Redis staging cache only.** Never mutates the DB or git. The safe iteration surface. | none |
+| `remits-cli components status` | Reads this lane's staging scope (account/user/branch/workspace) and branch resolution, and lists every other lane on the branch. | none |
+| `remits-cli components clear` | Clears THIS lane's staging cache without changing DB or git. Never touches another workspace lane. | none |
+| `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 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** |
+
+Key implications:
+- **`stage` is always safe** — stage and test as much as you want; it never reconciles or deletes.
+- **`components commit` is the most dangerous command**, not a mere convenience wrapper: it `git add -A`
+  commits and pushes whatever is in the working tree, then immediately syncs. Never run it while the tree
+  contains drift or unexplained changes. Prefer the explicit, observable
+  `git commit → git push → components sync → git pull` sequence so each phase can be inspected.
+- **`components sync` acts on the pushed remote**, so local edits are invisible to it until committed **and
+  pushed**, and a drifted **remote** is dangerous even when your local tree looks fine.
+- After a successful non-dry-run `components sync` / `components commit`, the server clears the full
+  staging scope for that lane (account/user/branch/workspace). This is the expected clean state: old Redis aliases should not keep shadowing
+  the newly synced DB rows. `components sync --dry-run` intentionally leaves staging untouched.
+
+### Intended workflows
+
+**Change existing components (normal path):**
+1. Edit files under `components/` **keeping each component's existing numeric id** (use `new_*` only for
+   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`.
+
+**Create a new component:** add `new_Name.groovy` (+ `.json` / `.meta.yml` as applicable). Sync assigns the
+durable id and renames the files. Standalone Prompts live in `components/prompts/new_Name.md`, and their
+sidecar must include `name`, `summary`, `description`, and `purpose` (usually `CUSTOM`). AGENT prompts do
+not live there; they are the `.md` sidecar beside the Utility in `components/agents/`. Do not create a
+direct database row to work around an id/name mismatch, and never create a replacement for a component
+that was unexpectedly deleted or renumbered.
+
+**Delete a component (deliberate only):** remove **all** of that component's files from the repo, confirm via
+`git status` that only those files are gone, then sync — the delete phase removes exactly that DB row. Deletion
+is a real, supported outcome of a missing file, which is precisely why an *accidentally* missing or renamed
+file is catastrophic.
+
+### Pre-sync safety check (confirm ALL before `components sync` or `components commit`)
+
+- **You know which sync mode this branch selects.** `remits-cli components status` states it outright. On a
+  variant branch the id/delete/renumber checks below apply to the **overlay set** instead: confirm every
+  component absent from the branch is *meant* to be tombstoned for subscribers.
+- The user intends durable platform promotion now — not just local edits, staging, or verification.
+- `git status --short` shows only intended changes; every rename/delete is explained. **No component file has
+  been renumbered to a different id.**
+- Local branch is committed and pushed; sync will read the intended remote commit.
+- Local filenames and live inventory (`mcp_account_view`) **agree on id and name for every component**: no live
+  component appears locally under a different id, and no expected component is missing a repo file.
+  > **Do not run this comparison against `account-info.json` alone — it will report false orphans.** That
+  > file omits `auxiliary: true` components by design, so every auxiliary component looks like a repo file
+  > with no DB row, i.e. exactly the "a trunk sync will CREATE a duplicate" signal this check exists to
+  > catch. It also omits README- and AGENT-purpose Prompts, which live at the repo root and as `.md`
+  > sidecars in `components/agents/` rather than in `components/prompts/`, so they look like DB rows with
+  > no repo file — the "will be DELETED" signal. Both are benign. Before treating a flagged component as
+  > drift, confirm against the live row: `mcp_component_view`, or
+  > `mcp_run_action controlAction:"describe"` for an Action. A component that answers is not an orphan.
+- You can state the expected create/update/delete set. **If any delete or renumber is unexpected, stop.**
+
+### If something looks wrong — stop, don't paper over
+
+If sync reports unexpected `deleted` / `created` / `renamed`, uniqueness errors, or missing components — or you
+discover id drift — **stop. Do not re-run sync, do not `components commit`, and do not create replacement
+components to "make ids line up" or replace a deleted component.** Those actions compound the corruption.
+Preserve the repo-local session log and tool responses, and reconcile source-of-truth first.
+
+**Safe recovery pattern (repo ↔ DB drift):**
+1. Establish DB truth: `mcp_account_view` for the full live inventory; `mcp_component_view` to confirm and read
+   exact sources.
+2. Fix the **local tree to mirror the live DB** — rename component files back to their real DB ids, reassemble
+   any split components, remove orphan/duplicate files, and **refresh any local source that differs from the
+   live DB** (the DB is the running truth; a stale local file would overwrite good DB source on sync).
+3. Keep files for any components that were wrongly deleted so sync **re-creates** them (new ids are fine —
+   schemas are keyed by title, agents link tools by name).
+4. Make the remote authoritative **non-destructively**: commit the corrected tree, then
+   `git merge -s ours origin/<branch>` (keeps your tree, supersedes drifted remote history) and a fast-forward
+   `git push` — no force-push.
+5. Run **one** `components sync`: it updates everything to identical, creates the missing components, and
+   deletes nothing. Verify with `mcp_account_view`.
+
+If the mismatch is a genuine platform/tooling defect (not agent drift), follow the Back-Stage Escalation
+Workflow in `troubleshooting.md` instead of improvising.