@remits/remits-cli 0.1.112 → 0.1.114

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

@@ -0,0 +1,209 @@
+# Component Resolution: Staged, Variant, Trunk
+
+> A `remits-cli` skill reference. **Load this when** a change "is not working", you need to prove which version of a component actually ran, or several agents share one branch.
+>
+> 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 Resolution: Staging Cache vs DB (which "version" actually runs)](#component-resolution-staging-cache-vs-db-which-version-actually-runs)
+  - [The three source layers + the compile cache](#the-three-source-layers--the-compile-cache)
+  - [Staging cache key format](#staging-cache-key-format)
+  - [How the platform picks staged vs DB (the compile signature)](#how-the-platform-picks-staged-vs-db-the-compile-signature)
+  - [When staged overrides apply](#when-staged-overrides-apply)
+  - [Diagnosing which version is in play](#diagnosing-which-version-is-in-play)
+  - [Working alongside other agents: the staging WORKSPACE](#working-alongside-other-agents-the-staging-workspace)
+  - [Stage / sync / clear with remits-cli](#stage--sync--clear-with-remits-cli)
+  - [Stale after sync / commit (the in-memory compile cache)](#stale-after-sync--commit-the-in-memory-compile-cache)
+
+## Component Resolution: Staging Cache vs DB (which "version" actually runs)
+
+When the platform executes a component it resolves the source from one of two places, then compiles it
+behind an in-memory cache. Understanding this is the difference between "my change isn't working" guesses
+and a precise diagnosis.
+
+### The three source layers + the compile cache
+
+1. **CLI staging cache (Redis, 240-min TTL).** Branch + user + account scoped overrides written by
+   `remits-cli components stage`. These shadow the layers below **only during CLI/test-mode execution**
+   (see "When staged overrides apply" below).
+2. **Committed branch variants (`ComponentVariant`, MySQL).** Durable, branch-scoped overlays of a
+   component. Unlike staging these are **not** user-scoped, do **not** expire, and **do** apply to normal
+   production traffic — for the accounts that subscribe to that branch. See
+   `branch-variants.md`. Most accounts have none, in which case this layer is inert.
+3. **Database trunk row (the committed live component).** What `mcp_component_view` reads, what an
+   unsubscribed prod run uses, and what a trunk `commit` writes to.
+
+Resolution order is **staged → variant → trunk**, and each layer *layers over* the one beneath it rather
+than replacing it: a payload that only carries `source` inherits `path`, `objectType`, `inputSchema` etc.
+from the layer below. A staged edit made on a variant branch therefore layers over **that variant**, not
+over trunk.
+
+Plus the compile cache:
+
+- **Compiled-closure cache (`BaseClosureDomain.CLOSURE_CACHE`).** An in-memory, **per-JVM-instance** Guava
+  cache of the parsed closure, keyed by `(componentId, type, compileSignature)`. This is why a change that
+  is correctly in the DB can still execute stale on a running instance — see "Stale after sync" below.
+
+### Staging cache key format
+
+```
+# default lane (no workspace)
+account:<accountId>:cli:<cliUserId>:components:<branch>:<family>:id:<componentId>
+account:<accountId>:cli:<cliUserId>:components:<branch>:<family>:name:<normalizedName>
+
+# workspace lane
+account:<accountId>:cli:<cliUserId>:components:<branch>:ws:<workspace>:<family>:id:<componentId>
+```
+
+The staging scope is therefore **account + cli user + branch + workspace**. `workspace` is optional and
+absent by default; see "Working alongside other agents: the staging WORKSPACE" above.
+
+`<family>` is the lowercased component family (`reader`, `action`, `test`, `embeddable`, ...). Both an
+`id:` and a `name:` key are written per stage. The entry value carries: `kind` (the family), `type` (the
+component's OWN type enum such as `ObjectType`/`RuleType`, or absent — **never** the family), `hash`,
+`updatedAt`, the staged content field(s) (`source`/`prompt`/`html`/`javascript`/`schema`/
+`inputSchema`/`previewData`), and `.meta.yml` metadata fields such as `description`, `summary`, `mermaid`,
+`path`, Embeddable `injectionType`, `category`, and Schema flags (`enableTrigger`, `enableFullText`, `enableRAG`, `enableRevisions`,
+`enableBigQuerySync`, `enableRules`, `anchor`, `auxiliary`).
+
+### How the platform picks staged vs DB (the compile signature)
+
+At compile time the platform computes a **signature** that tells you which layer won:
+
+- Staged override present → `compileSignature = "cli:<hash>"` (the staged content hash).
+- Committed branch variant → `compileSignature = "variant:<variantId>:<hash12>"`.
+- Neither → `compileSignature = "version:<N>:<sourceHash12>"` (the DB row version plus a source hash
+  prefix, so source changes cannot reuse a stale compile entry on the same instance).
+
+The three namespaces are distinct on purpose: a component's staged, variant, and trunk closures coexist in
+the compile cache without colliding.
+
+That signature is logged. Querying for it is the single most reliable way to know what ran:
+
+```bash
+remits-cli tool --name mcp_system_logs --input '{"node":"remitsAdmin-east5","timeRange":"1h","filter":"Using Cached BCD"}' --data-mode prod
+```
+
+> **Pass the bare phrase — never hand-write a `textPayload:` filter.** In production the platform's
+> logback encoder writes every `log.*` line to **`jsonPayload.message`**; only `println`/stdout lands in
+> `textPayload`. A `textPayload:"..."` filter therefore matches **zero** rows for nearly every platform
+> log line, and zero rows is indistinguishable from "it never happened" — which has already caused a real
+> misdiagnosis. `mcp_system_logs` now widens a bare phrase (and any `textPayload:"..."` clause) to cover
+> both shapes, and echoes the executed filter back as `filterApplied`. A filter that names `jsonPayload`
+> explicitly is passed through untouched.
+
+`Using Cached BCD [ID: 230, Type: Action, Signature: cli:08cc...]` → ran a **staged** override.
+`...Signature: variant:14:9f2c1a...]` → ran a **committed branch variant**.
+`...Signature: version:37:abc123def456]` → ran the **committed trunk** version.
+
+### When staged overrides apply
+
+Staged overrides resolve whenever the execution carries a **CLI-scoped TestMode** — i.e.
+`TestMode.branchName` and `TestMode.cliUserId` are set. That includes:
+
+- `remits-cli test run`
+- `remits-cli tool`
+- `remits-cli tools`
+- tokenized runs minted with a branch-aware CLI token
+
+For `remits-cli tool`, the CLI TestMode now stays active for the **entire tool execution**, not just the
+top-level tool lookup. That means nested `reader()`, `action()`, `utility()`, `account.getTool()`, and
+similar component resolution inside the tool also see the staged branch context.
+
+`dataMode` is separate from staged resolution:
+
+- `branchName` + `cliUserId` decide whether staged components can resolve.
+- `dataMode:test|prod` decides which data surface the tool/test/token runs against.
+
+So a `remits-cli tool --data-mode prod` call can intentionally execute **staged code against prod data**
+for investigation or recall testing, while a normal live webhook / non-CLI runtime path with no CLI
+TestMode still uses the committed DB source. Staging remains a dev/verification surface, not a deploy.
+
+### Diagnosing which version is in play
+
+- **See staging metadata for a component:** `mcp_component_view` (omit `fieldName`) returns `staging` /
+  `stagedFields`, telling you whether a staged entry exists and which fields are staged.
+- **Inspect the raw staged entry + TTL in Redis:** use `mcp_cache`.
+  ```bash
+  # find staged entries for one component
+  remits-cli tool --name mcp_cache --input '{"action":"scan","pattern":"account:52:cli:*:components:*:reader:id:181","includeValuePreview":true}' --data-mode prod
+  # dump one exact key
+  remits-cli tool --name mcp_cache --input '{"action":"inspect","key":"account:52:cli:23:components:main:reader:id:181"}' --data-mode prod
+  ```
+  The preview shows `kind`/`type`/`hash`/`updatedAt` + a source snippet — confirm it's your content and
+  that `type` is NOT the family (a family value in `type` is a tool bug that crashes hydration, e.g.
+  `No enum constant ObjectType.reader`).
+- **Confirm the DB version:** `mcp_component_view` reads the live DB source directly (no staging, no compile
+  cache), so it is the source of truth for "what was committed."
+- **Ask the CLI what is staged:** `remits-cli components status` lists this lane's staged entries,
+  including staged fields, aliases, hashes, and TTLs. The default terminal output is concise; pass `--json` or
+  `--verbose` when you need the full staged-entry payload. `remits-cli components clear` removes those entries
+  when you intentionally want to fall back to DB source.
+
+### Working alongside other agents: the staging WORKSPACE
+
+Staging is scoped by `(account, cli user, branch, workspace)`. Account and user are fixed for a repo, so
+**without a workspace the git branch is the only isolation axis** — and `components stage` uploads the
+ENTIRE repo and REPLACES the lane rather than merging into it. Two agents on one branch therefore
+overwrite each other, and a `components commit` clears the lane out from under the other one.
+
+If more than one agent is working on the same branch, give each its own workspace:
+
+```bash
+git worktree add ../repo-agent-a forked      # one checkout per agent, same branch
+cd ../repo-agent-a
+remits-cli workspace use --auto              # names the lane after this directory
+remits-cli components stage                  # isolated: nobody else sees it, nobody overwrites it
+remits-cli test run --test 42
+remits-cli token --path /page/whatever
+```
+
+A workspace narrows STAGING and nothing else. A commit still targets the same branch and the same owner
+account, and the run still resolves whatever committed variant branch the account subscribes to — so it
+does **not** have the side effects of inventing a throwaway git branch per agent (which would make a
+commit write `ComponentVariant` overlays for a branch nobody subscribes to).
+
+- `.remits-cli/workspace` is per-checkout and gitignored, so each worktree keeps its own lane.
+- Precedence: `--workspace NAME` > `REMITS_WORKSPACE` > `.remits-cli/workspace` > shared default lane.
+- `--no-workspace` targets the shared lane for one command without clearing the file.
+- Every stage / test run / token / clear prints its `Staging lane:` — if a change seems to have had no
+  effect, check that line FIRST. A mismatched lane resolves committed source, which looks identical to
+  "the stage did not work".
+- `remits-cli components status` lists every lane staged on the branch, so you can see whether another
+  agent is working alongside you.
+- `remits-cli components clear --all` is scoped to YOUR lane and never touches another agent's.
+
+### Stage / sync / clear with remits-cli
+
+- `remits-cli components stage` writes local file changes into the Redis staging cache for the current
+  branch/user/workspace scope. This is the normal edit/test loop.
+- `remits-cli components stage --changed-only` stages just the components this working tree edited. It
+  does NOT reconcile, so entries for components it did not mention are left alone rather than deleted.
+  Useful on a large repo; a full stage is still the default and the safest.
+- `remits-cli components status` shows which branch/variant world the checkout resolves, plus staged entries,
+  staged fields, aliases, hashes, and TTLs. Use `--json` or `--verbose` for the full staged-entry payload.
+- **A full `stage` makes the `.meta.yml` AUTHORITATIVE.** Staging layers a payload over what is already
+  staged, which is what lets `mcp_component_edit` write a single field without blanking the others. But a
+  `remits-cli components stage` sends the whole sidecar, so a key you DELETE from a sidecar is removed from
+  the staged entry rather than lingering — "restore the file and re-stage" restores the staged state, which
+  is the only mental model that is safe to have. Content fields still layer (they come from separate files),
+  so a partial stage is unaffected.
+- `remits-cli components clear` drops staged entries when you intentionally want to fall back to committed DB
+  source. An empty staging scope is clean state, not a failure.
+- `remits-cli components sync` syncs the DB from the pushed git remote and then clears staged entries for the
+  synced components, so a clean promotion leaves a clean staging cache. Because sync reconciles the remote repo
+  into the live component database, it must pass `component-integrity.md` first. Never use sync only to
+  clear staging, to recover from a mismatched ID, or to retry after an unexpected create/delete/rename response.
+
+### Stale after sync / commit (the in-memory compile cache)
+
+After a `git sync` or a `commit` updates the DB source, a **running instance can keep executing the
+previously-compiled closure** until the version-keyed signature changes and that instance's
+`CLOSURE_CACHE` misses (or the instance recycles). Symptoms: `mcp_component_view` shows the new source, but
+behaviour (or a freshly-staged entry produced by an edited *tool*) still reflects the old code. This is the
+standard Grails no-hot-reload caveat — it is environmental, not a code defect. Verify the live entry/source
+with `mcp_cache` / `mcp_component_view`, and if a platform/tool source change must take effect immediately,
+the platform owner recycles the instance.

package/skills/remits-cli/references/development-loop.md

@@ -0,0 +1,366 @@
+# The Development Loop
+
+> A `remits-cli` skill reference. **Load this when** you are building or changing a component: the edit to stage to verify to commit fast loop, end to end.
+>
+> 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
+
+- [Two Workflows](#two-workflows)
+  - [Test Mode vs Prod Mode](#test-mode-vs-prod-mode)
+- [Development Workflow](#development-workflow)
+  - [The Golden Rule: Writing Code Is Not Finishing the Job](#the-golden-rule-writing-code-is-not-finishing-the-job)
+  - [The Development Fast Loop](#the-development-fast-loop)
+    - [Step 1: Understand the Request](#step-1-understand-the-request)
+    - [Step 2: Make the Change](#step-2-make-the-change)
+    - [Step 3: Stage to Platform](#step-3-stage-to-platform)
+    - [Step 4: Verify the Change](#step-4-verify-the-change)
+    - [Step 5: Iterate If Needed](#step-5-iterate-if-needed)
+    - [Step 6: Update Documentation](#step-6-update-documentation)
+    - [Temporary Experiment Workflow](#temporary-experiment-workflow)
+    - [Step 7: Commit and Durable Sync](#step-7-commit-and-durable-sync)
+    - [Step 8: Close the Ticket](#step-8-close-the-ticket)
+  - [User Confirmation Preferences](#user-confirmation-preferences)
+
+## Two Workflows
+
+1. **Development** (test mode) — Build, modify, and verify components using isolated test data.
+2. **Production Support** (prod mode) — Investigate live data, debug issues, trace execution.
+
+Every CLI response includes `dataMode` so you always know which context you're in.
+
+### Test Mode vs Prod Mode
+
+Treat these as two different jobs:
+
+- **Prod mode** is for investigation.
+  - Read live Firestore documents.
+  - Inspect live object activity, events, alerts, and logs.
+  - Confirm what actually happened to a customer.
+  - Do not use prod mode as your final verification environment for a code fix.
+
+- **Test mode** is for verification.
+  - Stage local component changes.
+  - Run Test components.
+  - Generate token URLs and verify behavior in isolated browser flows.
+  - Confirm the fix without mutating or depending on live customer processing.
+
+The correct support loop is usually:
+1. Investigate in **prod mode**
+2. Identify the responsible implementation repo and make the code change locally
+3. Move back to **test mode** for verification
+4. Verify with a Test component, Playwright/browser confirmation, or both
+
+If a production issue needs realistic verification, do **not** copy live customer data from a production account into another account's test collection.
+
+The right model is:
+- investigate the source document in **prod mode**
+- model the relevant conditions in a **Test** component
+- or reproduce the scenario through a controlled **test-mode** embeddable/browser flow
+- verify the fix there
+
+Never treat "it looks right in prod data inspection" as sufficient proof that a code change is verified.
+
+## Development Workflow
+
+### The Golden Rule: Writing Code Is Not Finishing the Job
+
+**A change is not complete until it is verified.** Writing the component is the first step, not the last.
+Two ways to prove it:
+
+1. **A Test component** (preferred) — it exercises the change *and* becomes permanent regression
+   protection. Run it with `remits-cli test run`.
+2. **Visual verification** — `remits-cli token` for a browser URL, then drive it with `playwright-cli`.
+   This is how most users think about verification: "let me see it working."
+
+Use a Test when the behavior can be asserted programmatically, a browser when the change is visual.
+Often both.
+
+**Never skip verification.** "Just do it" and "that's fine, commit it" are not evidence. If you genuinely
+cannot verify — no Test component, no relevant embeddable — say what you would need and ask how the user
+wants to proceed rather than reporting the work as done.
+
+> The *design* rule that pairs with this — never solve interpretive problems with regex cascades, keyword
+> lists, or layout-specific branching when the platform's AI surface is the right tool — is in the account
+> repo's `CLAUDE.md` and, in depth, in `features/ai-strategy.md`.
+
+### The Development Fast Loop
+
+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.md` 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
+variants of these components exist: editing an origin component will drift them, so check
+`remits-cli components branches` before changing shared code. See `branch-variants.md`.
+
+#### 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
+components/prompts/new_PricingReviewPrompt.md        # standalone Prompt body
+components/prompts/new_PricingReviewPrompt.meta.yml  # standalone Prompt metadata
+```
+
+**Do NOT put an `id:` in a new component's sidecar.** `id` is what links a sidecar to an *existing*
+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. This is the compact text account-info.json uses first.
+description: |
+  Longer technical description with line-number references to the key logic.
+path: /page/merchant-portal        # Readers and Embeddables only
+injectionType: DIRECT              # Embeddables only: DIRECT or IFRAME
+category: default
+auxiliary: false                   # `true` means the sync SKIPS the file entirely — see Auxiliary
+mermaid: |
+  graph TD
+    A[Request] --> B[Load documents]
+```
+
+For `components/prompts/new_*.meta.yml`, include `description` and `purpose: CUSTOM`; missing
+`description` fails trunk validation, and missing/mismatched `purpose` leaves a post-promotion Prompt
+overlay instead of pruning cleanly.
+
+> **Staging creates nothing in the database, so a `new_` component has no id yet — address it BY NAME.**
+> `remits-cli test run --test "My Suite"`, not `--test <id>`. Component-to-component resolution and
+> request-level addressing are name-based too; the component guides cover those. After a trunk sync the
+> component has a real id and either form works.
+
+#### Step 3: Stage to Platform
+
+```bash
+remits-cli components stage
+```
+
+This uploads your local file changes to the platform's staging cache (Redis, 240-minute TTL). It does NOT commit anything. The platform cannot see your local edits until you stage them.
+
+**THE STAGE-BEFORE-RUN RULE:** You MUST run `remits-cli components stage` after EVERY file edit and BEFORE any test run or verification. The platform executes whatever version is in the staging cache at the moment the test starts. If you edit a file and run a test without staging first, the test runs the OLD code — not your changes. This is the single most common mistake. Never skip staging. The sequence is always: **edit → stage → run**.
+
+This applies to:
+- Creating new components (the platform won't find them until staged)
+- Editing existing components (the platform runs the previously staged version until you re-stage)
+- Every iteration of the fix loop — every edit requires a fresh stage before the next test run
+
+#### Step 4: Verify the Change
+
+**Option A — Run Tests** (if Test components exist for this area):
+
+```bash
+remits-cli test run --test <TEST_ID_OR_NAME>
+remits-cli test run --test "Invoice Tests" --names "specific test case"
+```
+
+Tests run on the platform against your staged snapshot. They stream results in real-time. If they fail, fix the code, re-stage, and re-run.
+
+Important test-runner constraints:
+- `remits-cli test run` now defaults to `test` dataMode unless you explicitly pass `--data-mode prod`.
+- **`--names` is delimited by `|`, and may be repeated.** A comma still splits a single `--names` value
+  (legacy behaviour), which is why a case name containing a comma used to be cut in half and match
+  nothing. Prefer `|` or repetition whenever a name might contain punctuation:
+  ```bash
+  remits-cli test run --test 13 --names "a case, with a comma|another case"
+  remits-cli test run --test 13 --names "a case, with a comma" --names "another case"
+  ```
+- **A selector that matches no case FAILS the run.** It used to report `0 passed, 0 failed`,
+  `completed`, and exit 0 — indistinguishable from a suite where everything passed. The run now names
+  the unmatched selectors and lists the cases the suite actually declared, and exits non-zero.
+
+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`) 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"):
+
+```bash
+# Generate a browser-accessible URL for an embeddable
+remits-cli token --path embeddable/index/<EMBEDDABLE_ID>
+```
+
+This returns an `embeddableUrl`. Use Playwright to open and interact with it:
+
+```bash
+# Open the embeddable in a headed browser
+playwright-cli open --headed "<embeddableUrl>"
+
+# Take a snapshot to see the current state
+playwright-cli snapshot
+
+# Interact with elements
+playwright-cli click "text=Submit"
+playwright-cli fill "#amount" "500.00"
+
+# Verify specific content
+playwright-cli eval "() => document.querySelector('.total-amount').textContent"
+```
+
+The `testMode` metadata confirms you're testing against staged changes, not production.
+
+**Two different token keys come back, for two different jobs.** When `--path` resolves to an
+Embeddable, the response carries an `embedTokenKey` and a paste-ready `embedSnippet` alongside the usual
+`tokenKey` / `embeddableUrl`:
+
+| Field | Use it for |
+|---|---|
+| `tokenKey` / `embeddableUrl` | Opening the page in a browser (Playwright, or clicking the link) |
+| `embedTokenKey` / `embedSnippet` | The `<script>` embed loader — verifying the page as a HOST SITE embeds it |
+
+They are not interchangeable. The loader's request carries **no path**, so it resolves the component
+purely from the embeddable-scoped token key's persisted context. The browser `tokenKey` names the account
+preview URL; `embedTokenKey` names the host-loader credential. The response also echoes `injectionType` /
+`renderMode` / `headMode`, which decide what a host actually receives
+(`guides/components/embeddable-components.md`).
+
+**This works for a `new_` component that has never been synced.** The embed token key carries the
+component NAME as well as its id, so a staged, id-less Embeddable is loader-addressable — you do not
+have to sync it, or borrow another component's id, just to verify a host embed.
+
+**Option C — Use investigation tools** (for backend/data changes):
+
+For changes to Readers, Actions, or Rules that process data rather than display UI, verify by examining the data they produce:
+
+```bash
+# After triggering the component (via test or manual action), check the result
+remits-cli tool --name "mcp_firestore_search" --input '{"accountId": <ID>, "collection": "<collection>", "limit": 5, "sort": [{"field": "_lastModifiedAt", "direction": "DESC"}]}'
+```
+
+For long-running backend verification, use the Action runner's own async mode (`executionMode:"async"`) and
+poll by `actionRunId` rather than holding a single request open (see `command-reference.md` → *Tool Execution Lifecycle* for why not
+to also stack the CLI `--async` flag):
+
+```bash
+remits-cli tool --name "mcp_run_action" --input '{"accountId": <ID>, "actionId": <ACTION_ID>, "executionMode": "async", "actionInput": {...}}' --data-mode test
+# then poll:  {"controlAction":"status","accountId": <ID>, "actionRunId":"<actionRunId>"}
+```
+
+#### Step 5: Iterate If Needed
+
+If verification reveals issues, repeat the loop: **edit → stage → run**. Every iteration must include a fresh `remits-cli components stage` after your edits and before the next test run. Never run a test immediately after editing without staging first — the platform will execute the previous version, not your latest changes.
+
+Don't ask the user for permission to re-iterate — just do it. Only stop to ask if you're stuck or unsure about the intended behavior.
+
+If the work is tied to a support ticket:
+- Use `remits-cli ticket status --status in_progress` once you have started substantive work.
+- If a new reply arrives, re-read the ticket and incorporate the reply into your current plan.
+
+#### Step 6: Update Documentation
+
+Before committing, update metadata so the next session understands what changed:
+
+1. **`.meta.yml` sidecars** — Update `summary`, `description`, and `mermaid` for each modified component. `summary` is what drives the compact component description in generated `account-info.json`; `description` is the fallback when no summary is set and is capped in that file.
+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. Component
+entries prefer `summary`, fall back to capped `description`, and cap `mermaid`; relationships remain as
+generated. 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.
+
+#### Temporary Experiment Workflow
+
+Use this when you need to prove a guard or assertion by temporarily making a local component fail. The staged
+Redis cache can affect later test/tool runs, so always clear it after restoring the file:
+
+```bash
+# make temporary local edit
+remits-cli components stage
+remits-cli test run --test <id-or-name> --names "<case name>"
+git restore <file>
+remits-cli components clear --all
+remits-cli components status
+```
+
+For narrower cleanup when only one staged component should be cleared:
+
+```bash
+remits-cli components clear --component-type Action --component-id 25
+```
+
+#### Step 7: Commit and Durable Sync
+
+Once verified and documented, create a normal git commit first:
+
+```bash
+git add -A
+git commit -m "description of what changed and why"
+git push origin <branch>
+```
+
+This separates the local failure boundaries cleanly:
+1. Local git commit
+2. Remote push
+
+After the push, run the **`component-integrity.md`** safety checks before any durable platform sync. Do not run
+`remits-cli components sync` when local files, `account-info.json`, and live inventory disagree about component
+IDs or when unexpected deletes/renumbers are present.
+
+Only after those checks pass, and only when the user intends to promote the repo to the platform database:
+
+```bash
+remits-cli components sync
+git pull --ff-only origin <branch>
+```
+
+`remits-cli components sync` is the authoritative platform-sync step. It does not perform local git operations,
+and it is capable of reconciling creates/deletes/renames from the remote repository into the database. Treat it
+as a gated promote/reconciliation command, not as an exploratory command or fallback.
+
+The CLI now returns the post-sync branch SHA from the platform and verifies that your `git fetch` and final `git pull --ff-only` land on that exact commit. If that SHA does not match `origin/<branch>` or local `HEAD`, stop immediately and investigate the race or branch drift instead of guessing.
+
+`remits-cli components commit` still exists as a convenience wrapper, but agents should not call unsupported
+subcommand help variants such as `remits-cli components commit --help` to discover behavior. Consult the `remits-cli` skill and its references,
+the CLI source, or `remits-cli components` documentation instead. If an exploratory or commit command behaves
+unexpectedly, stop and inspect the repo-local session log before running any mutating follow-up command.
+
+**Git is required for durable sync.** The platform syncs by pulling from the git remote (`GitHubClient.syncFromRepository`). If `git push` fails, the server has nothing new to sync. You can still **stage** and **test** without git — only durable sync requires it.
+
+#### Step 8: Close the Ticket
+
+If the request came from a support ticket, the task is not complete until you update the ticket lifecycle yourself:
+
+1. Re-read the ticket if needed to confirm the latest state and replies.
+2. If the work is done and verified, call `remits-cli ticket complete` and include a concise resolution summary.
+3. If you cannot finish, use `remits-cli ticket status` or `remits-cli ticket release` with clear notes so the next agent can continue.
+4. Do this automatically. The human user should not need to instruct you to update the ticket.
+
+Options:
+```bash
+--message "commit msg"         # Commit message (default: auto-generated timestamp)
+--allow-empty true             # Allow empty git commits
+```
+
+### User Confirmation Preferences
+
+Some users want to review every change before staging. Others want you to move fast and only stop if something breaks. **Pay attention to how the user communicates:**
+
+- If they say "just fix it" or "go ahead" — move through the loop without asking for confirmation at each step. Stage, verify, commit.
+- If they say "show me first" or "wait before committing" — pause at the appropriate step.
+- If they say "you don't need to ask me" or "stop asking" — remember this preference and work autonomously through the full loop.
+
+The default should be: make the change, stage it, verify it, and present the results. Only block on the user when you're genuinely unsure about intent.