@remits/remits-cli 0.1.76 → 0.1.77

package/README.md

@@ -21,6 +21,8 @@ remits-cli install --skills
 remits-cli tools
 remits-cli tool --base-url http://localhost:8080 --name "My Tool" --input '{"foo":"bar"}'
 remits-cli components stage
+remits-cli components status
+remits-cli components clear
 remits-cli test run --test 45
 remits-cli test run --test "My New Test" --names "test case 1,test case 2"
 git add -A
@@ -51,13 +53,16 @@ remits-cli install --skills --overwrite true
 
 ## How It Works
 
-- `components stage` uploads the current working tree into the staging cache used by test-mode execution.
-- `components sync` performs a server-side sync from the git remote into the Remits platform for the selected branch. It does not run local git commands.
+- `components stage` uploads the current working tree into the staging cache used by test-mode execution. It replaces the branch/user staging scope with the current manifest, so stale aliases from prior stages are removed.
+- `components status` shows the branch/user staging entries that can shadow DB components during CLI-scoped test-mode execution.
+- `components clear` clears the branch/user staging scope. Use `--component-type` + `--component-id` to clear one component; omit them to clear all staged entries for the current branch.
+- `components sync` performs a server-side sync from the git remote into the Remits platform for the selected branch. It does not run local git commands. After a successful sync, the platform clears the branch/user staging scope so staged aliases cannot keep shadowing the newly synced DB rows.
 - `components commit` is a convenience wrapper that performs local git commit/push, then `components sync`, then local `git fetch`/`git pull --ff-only`.
 - `components sync` returns the post-sync branch SHA produced by the platform. `components commit` verifies that `origin/<branch>` and local `HEAD` both match that exact SHA after the final pull.
 - `components push` is deprecated and currently behaves the same as `components stage`.
 - `accountId` resolution for CLI commands: explicit `--account-id` flag wins, then the current repo's `account-info.json`, then the active session. For `remits-cli tool` calls the server applies a further precedence — explicit `--account-id` > `input.accountId` > session/repo default — so a tool can execute against a different account than the surrounding repo.
 - Auth sessions are stored per `accountId + dataMode + baseUrl`, so the same account can stay authenticated against both localhost and production without overwriting the other session.
+- `--base-url` and `--data-mode` are independent. `--base-url` chooses the Remits host (`http://localhost:8080` vs deployed prod), while `--data-mode` chooses the data segment on that host (`test` vs `prod`). Do not assume `--data-mode prod` means the deployed prod host, or that `--data-mode test` means localhost.
 - `remits-cli start` scans the machine for `account-info.json` files and rebuilds `~/.remits-cli/account-repos.json` before bringing up the background service.
 - Front-stage guides are **not** bundled with the CLI npm package. For account-work commands (`components`, `test`, `token`, `tools`, `tool`) and on `auth`, `remits-cli` downloads the latest guides from the authenticated `/cli/guides` endpoint and writes them into the current account repo: root `platform-overview.md` / `development-guide.md`, `guides/*.md`, `guides/features/*.md`, and the agent-guidance files `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` (from `docs/guides/remits-components-zip-readme.md`).
 - Guide sync requires authentication. If no valid session exists and the terminal is interactive, the CLI auto-authenticates first; in non-interactive contexts (CI, agent sandboxes) it skips silently so guides are only ever delivered to users who can authenticate to the platform.
@@ -66,6 +71,7 @@ remits-cli install --skills --overwrite true
 - Authenticated users also get the **core Remits platform repo** locally. After guide sync (and on `auth` / discovery), `remits-cli` first reuses any existing local copy it already knows about, can detect directly (`REMITS_PLATFORM_DIR`, the running CLI source in dev, `~/remits`), or can discover under the configured scan roots; only if none is found does it clone `git@github.com:tmillhouse/remits.git` (default `~/remits`, override with `REMITS_PLATFORM_DIR`; cloning only runs in an interactive terminal). On each authenticated run it also fast-forwards the repo (`git pull --ff-only`, once per process) so back-stage analysis runs against current code — skipped automatically if the working tree is dirty, so local work is never clobbered. The repo is tracked in `~/.remits-cli/account-repos.json` under the reserved `platform` entry so agents can analyze back-stage seams and open a fix PR when a front-stage failure turns out to be platform brittleness.
 - Branch defaults to the current local git branch.
 - Data mode defaults to `test`. For `remits-cli test run`, that default is now enforced even if the most-recent authenticated session for the account is `prod`; a production test run therefore requires an explicit `--data-mode prod` on the command line. Use `remits-cli data-mode set prod` only for production investigation.
+- If the same account is authenticated against more than one host and you omit `--base-url`, the CLI auto-resolves the best matching session and now prints the resolved host. Pass `--base-url` explicitly whenever the target host matters.
 - Avoid commas in individual test names. The `--names` filter is comma-delimited, so a single test case whose name contains commas cannot be targeted cleanly through `remits-cli test run --names ...`.
 - Test activity is streamed from websocket `TestSuite` events while final status is also polled from `/cli/test`.
 - Tool execution writes the full response to a separate file so large payloads do not bloat the session log.

package/index.js

@@ -217,6 +217,30 @@ function readSession(match = {}, options = {}) {
   return candidates[0] || null;
 }
 
+function buildSessionResolutionWarning(accountId, requestedBaseUrl, session) {
+  if (requestedBaseUrl || !accountId || !session) {
+    return null;
+  }
+
+  const entries = listSessionsFromStore(readAllSessions());
+  const accountSessions = entries.filter((entry) => Number(entry.accountId) === Number(accountId));
+  const distinctBaseUrls = [...new Set(
+    accountSessions
+      .map((entry) => normalizeBaseUrl(entry.baseUrl || DEFAULT_BASE_URL))
+      .filter(Boolean)
+  )];
+
+  if (distinctBaseUrls.length <= 1) {
+    return null;
+  }
+
+  const resolvedBaseUrl = normalizeBaseUrl(session.baseUrl || DEFAULT_BASE_URL);
+  const resolvedDataMode = normalizeDataMode(session.dataMode);
+  return 'Multiple authenticated base URLs exist for account ' + accountId +
+    ' (' + distinctBaseUrls.join(', ') + '). Resolved this command to ' + resolvedBaseUrl +
+    ' using dataMode ' + resolvedDataMode + '. Pass --base-url to target a different host.';
+}
+
 function writeSession(accountId, data, options = {}) {
   const sessions = readAllSessions();
   const session = {
@@ -230,6 +254,16 @@ function writeSession(accountId, data, options = {}) {
   writeAllSessions(sessions);
 }
 
+function printSessionResolutionWarning(sessionContext) {
+  if (sessionContext && sessionContext.sessionResolutionWarning) {
+    console.error('Warning:', sessionContext.sessionResolutionWarning);
+  }
+}
+
+function printResolvedBaseUrl(baseUrl) {
+  console.log('Base URL:', normalizeBaseUrl(baseUrl || DEFAULT_BASE_URL));
+}
+
 function readConfig() {
   if (!fs.existsSync(CONFIG_FILE)) {
     return {};
@@ -1047,7 +1081,14 @@ function resolveSessionContext(cwd, flags) {
     accountId = session.accountId;
   }
 
-  return { session, accountId };
+  const sessionResolutionWarning = buildSessionResolutionWarning(accountId, requestedBaseUrl, session);
+
+  return {
+    session,
+    accountId,
+    resolvedBaseUrl: normalizeBaseUrl(session.baseUrl || requestedBaseUrl || DEFAULT_BASE_URL),
+    sessionResolutionWarning
+  };
 }
 
 function collectComponents(cwd) {
@@ -1514,14 +1555,17 @@ async function authCommand(flags) {
   console.log('Data mode:', session.dataMode);
 
   try {
+    const branchName = currentBranch(cwd);
     const toolsData = await loggedPost(api, cwd, '/cli/tools', {
       token: session.token,
       accountId: session.accountId,
+      branchName,
       dataMode: session.dataMode
     }).then((r) => r.data);
     if (toolsData && toolsData.success) {
       const toolsFile = saveToolsSnapshot(cwd, {
         accountId: session.accountId,
+        branchName,
         dataMode: toolsData.dataMode || session.dataMode,
         fetchedAt: new Date().toISOString(),
         tools: toolsData.tools || []
@@ -1567,7 +1611,8 @@ async function authCommand(flags) {
 async function pushComponentsCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
-  const { session, accountId } = resolveSessionContext(cwd, flags);
+  const sessionContext = resolveSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
   const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
   const branchName = flags.branch || currentBranch(cwd);
   const dataMode = resolveDataMode(flags, session);
@@ -1586,18 +1631,92 @@ async function pushComponentsCommand(flags) {
     branchName,
     dataMode,
     mode,
+    replace: true,
     components
   }).then((r) => r.data);
 
+  printSessionResolutionWarning(sessionContext);
+  printResolvedBaseUrl(baseUrl);
   console.log('Data mode:', response.dataMode || dataMode);
   console.log('Mode:', response.mode || mode);
   console.log('Components sync:', JSON.stringify(response, null, 2));
 }
 
+async function statusComponentsCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const sessionContext = resolveSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const branchName = flags.branch || currentBranch(cwd);
+  const dataMode = resolveDataMode(flags, session);
+  const api = buildAxios(baseUrl, session.token);
+
+  const response = await loggedPost(api, cwd, '/cli/components', {
+    token: session.token,
+    accountId,
+    branchName,
+    dataMode,
+    mode: 'status',
+    componentType: flags['component-type'] || flags.type,
+    componentId: flags['component-id'] || flags.id
+  }).then((r) => r.data);
+
+  if (!response.success) {
+    throw new Error(response.message || 'Staging status failed');
+  }
+
+  printSessionResolutionWarning(sessionContext);
+  printResolvedBaseUrl(baseUrl);
+  console.log('Data mode:', response.dataMode || dataMode);
+  console.log('Mode:', response.mode || 'status');
+  console.log('Staged count:', response.stagedCount || 0);
+  console.log('Components staging:', JSON.stringify(response, null, 2));
+  return response;
+}
+
+async function clearComponentsCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const sessionContext = resolveSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const branchName = flags.branch || currentBranch(cwd);
+  const dataMode = resolveDataMode(flags, session);
+  const api = buildAxios(baseUrl, session.token);
+  const componentType = flags['component-type'] || flags.type;
+  const componentId = flags['component-id'] || flags.id;
+
+  const response = await loggedPost(api, cwd, '/cli/components', {
+    token: session.token,
+    accountId,
+    branchName,
+    dataMode,
+    mode: 'clear',
+    clearAll: !(componentType && componentId),
+    componentType,
+    componentId
+  }).then((r) => r.data);
+
+  if (!response.success) {
+    throw new Error(response.message || 'Staging clear failed');
+  }
+
+  printSessionResolutionWarning(sessionContext);
+  printResolvedBaseUrl(baseUrl);
+  console.log('Data mode:', response.dataMode || dataMode);
+  console.log('Mode:', response.mode || 'clear');
+  console.log('Cleared count:', response.clearedCount || 0);
+  console.log('Remaining staged count:', response.remainingCount || 0);
+  console.log('Components staging:', JSON.stringify(response, null, 2));
+  return response;
+}
+
 async function syncComponentsCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
-  const { session, accountId } = resolveSessionContext(cwd, flags);
+  const sessionContext = resolveSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
   const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
   const branchName = flags.branch || currentBranch(cwd);
   const dataMode = resolveDataMode(flags, session);
@@ -1616,6 +1735,8 @@ async function syncComponentsCommand(flags) {
     throw new Error(response.message || 'Server sync failed');
   }
 
+  printSessionResolutionWarning(sessionContext);
+  printResolvedBaseUrl(baseUrl);
   console.log('Data mode:', response.dataMode || dataMode);
   console.log('Mode:', response.mode || 'sync');
   console.log('Components sync:', JSON.stringify(response, null, 2));
@@ -1755,7 +1876,8 @@ function watchWebsocket(baseUrl, topicId, taskId) {
 async function testCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
-  const { session, accountId } = resolveSessionContext(cwd, flags);
+  const sessionContext = resolveSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
   const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
   const branchName = flags.branch || currentBranch(cwd);
   // Test runs must default to test dataMode even when the most-recent authenticated
@@ -1787,6 +1909,8 @@ async function testCommand(flags) {
     throw new Error('Failed to start test run');
   }
 
+  printSessionResolutionWarning(sessionContext);
+  printResolvedBaseUrl(baseUrl);
   console.log('Test run started:', start.taskId);
   runtimeState.currentTestTaskId = start.taskId;
 
@@ -1817,7 +1941,8 @@ async function testCommand(flags) {
 async function tokenCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
-  const { session, accountId } = resolveSessionContext(cwd, flags);
+  const sessionContext = resolveSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
   const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
   const branchName = flags.branch || currentBranch(cwd);
   const dataMode = resolveDataMode(flags, session);
@@ -1842,6 +1967,7 @@ async function tokenCommand(flags) {
 
   const output = {
     success: true,
+    baseUrl: normalizeBaseUrl(baseUrl),
     tokenKey: data.tokenKey,
     accountId: data.accountId,
     branchName: data.branchName,
@@ -1850,20 +1976,24 @@ async function tokenCommand(flags) {
     embeddableUrl
   };
 
+  printSessionResolutionWarning(sessionContext);
   console.log(JSON.stringify(output, null, 2));
 }
 
 async function toolsCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
-  const { session, accountId } = resolveSessionContext(cwd, flags);
+  const sessionContext = resolveSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
   const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const branchName = flags.branch || currentBranch(cwd);
   const dataMode = resolveDataMode(flags, session);
   const api = buildAxios(baseUrl, session.token);
 
   const data = await loggedPost(api, cwd, '/cli/tools', {
     token: session.token,
     accountId,
+    branchName,
     dataMode
   }).then((r) => r.data);
 
@@ -1873,11 +2003,15 @@ async function toolsCommand(flags) {
 
   const toolsFile = saveToolsSnapshot(cwd, {
     accountId,
+    baseUrl: normalizeBaseUrl(baseUrl),
+    branchName,
     dataMode: data.dataMode || dataMode,
     fetchedAt: new Date().toISOString(),
     tools: data.tools || []
   });
 
+  printSessionResolutionWarning(sessionContext);
+  printResolvedBaseUrl(baseUrl);
   console.log('Tools refreshed.');
   console.log('Data mode:', data.dataMode || dataMode);
   console.log('Tools file:', toolsFile);
@@ -1898,7 +2032,8 @@ function parseToolInput(flags) {
 async function toolCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
-  const { session, accountId } = resolveSessionContext(cwd, flags);
+  const sessionContext = resolveSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
 
   const toolName = flags.name || flags.tool;
   if (!toolName) {
@@ -1933,6 +2068,8 @@ async function toolCommand(flags) {
     throw new Error(data.message || 'Tool execution failed');
   }
 
+  printSessionResolutionWarning(sessionContext);
+  printResolvedBaseUrl(baseUrl);
   console.log('Tool call succeeded.');
   console.log('Call ID:', callId);
   console.log('Data mode:', dataMode);
@@ -4270,6 +4407,7 @@ async function main() {
   const originalArgv = process.argv.slice(2);
   const args = parseArgs(originalArgv);
   const [command, subcommand] = args._;
+  const wantsHelp = args.help === true || subcommand === 'help' || subcommand === '--help' || args._.includes('--help');
 
   if (shouldAutoUpdate(command, args)) {
     const requireSuccessfulAutoUpdate = command === 'start';
@@ -4282,7 +4420,7 @@ async function main() {
   // Auto-start the background service if not already running.
   // Skip for lifecycle subcommands and help.
   const isLifecycleCmd = command === 'listen' || command === 'start' || command === 'stop' || command === 'status';
-  const isHelpCmd = !command || command === 'help' || command === '--help';
+  const isHelpCmd = !command || command === 'help' || command === '--help' || wantsHelp;
   if (!isHelpCmd && !isLifecycleCmd && !isListenerRunning()) {
     try {
       const dashboardUrl = await autoStartServiceIfNeeded();
@@ -4298,7 +4436,7 @@ async function main() {
   // only platform-authenticated users ever receive them. `auth` syncs its own
   // guides, so it is excluded here.
   const GUIDE_SYNC_COMMANDS = new Set(['components', 'test', 'token', 'tools', 'tool']);
-  if (GUIDE_SYNC_COMMANDS.has(command)) {
+  if (!isHelpCmd && GUIDE_SYNC_COMMANDS.has(command)) {
     try { await ensureGuidesSynced(process.cwd(), args); } catch (_) { /* best-effort */ }
   }
 
@@ -4317,6 +4455,8 @@ async function main() {
     console.log('  remits-cli tools [--base-url URL] [--account-id ID] [--data-mode test|prod]');
     console.log('  remits-cli tool --name <toolName> [--base-url URL] [--input \"{...}\"|--input-file file.json] [--data-mode test|prod]');
     console.log('  remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod]');
+    console.log('  remits-cli components status [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID]');
+    console.log('  remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID]');
     console.log('  remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod]');
     console.log('  remits-cli components commit [--message \"msg\"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod]');
     console.log('  remits-cli test run --test <id|name> [--base-url URL] [--names name1,name2] [--watch true|false] [--data-mode test|prod]');
@@ -4324,6 +4464,16 @@ async function main() {
     process.exit(0);
   }
 
+  if (command === 'components' && wantsHelp) {
+    console.log('Usage: remits-cli components <stage|status|clear|sync|commit>');
+    console.log('  remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod]');
+    console.log('  remits-cli components status [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID]');
+    console.log('  remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID]');
+    console.log('  remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod]');
+    console.log('  remits-cli components commit [--message \"msg\"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod]');
+    process.exit(0);
+  }
+
   if (command === 'auth') {
     await authCommand(args);
     return;
@@ -4337,6 +4487,16 @@ async function main() {
     return;
   }
 
+  if (command === 'components' && subcommand === 'status') {
+    await statusComponentsCommand(args);
+    return;
+  }
+
+  if (command === 'components' && subcommand === 'clear') {
+    await clearComponentsCommand(args);
+    return;
+  }
+
   if (command === 'components' && subcommand === 'sync') {
     await syncComponentsCommand(args);
     return;

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -30,6 +30,113 @@ Apply these rules before making remote tool calls:
 
 Use `remits-cli` for everything else: staging changes, running tests, generating embeddable tokens, committing work, and diagnosing production issues.
 
+## 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)
+
+`remits-cli components sync` (and the sync phase of `components commit`) calls
+`GitHubClient.syncFromRepository`. 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.).
+- **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.
+
+**The single most important consequence:** the id in a component's **filename is load-bearing**. If a file's id
+no longer matches its DB row (a rename/renumber), the next sync will **create a duplicate at the new id and
+hard-delete the original at the old id**. If a component's files are missing from the repo at sync time, that
+component is **hard-deleted from the DB**. This is exactly how a prior session deleted live schemas and an
+embeddable.
+
+**Therefore: never renumber, rename-across-ids, or remove component files as a side effect.** Before any sync,
+the repo must already mirror the live DB: every live component present at its real id, and nothing extra.
+
+### The surfaces and their intended behavior
+
+| Command / tool | 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 |
+| `mcp_component_edit` `mode:'stage'` | Redis staging cache for one component/field. | none |
+| `mcp_component_edit` `mode:'commit'` / `mcp_component_commit` `commit` | Writes the field(s) to the **live DB** for that exact existing component and clears its staging. Does not create/delete other components. | low (scoped to one known component) |
+| `remits-cli components sync` | **Server-side git→DB reconcile of the whole account** (create/update/**delete**/rename). Reads the pushed remote; ignores local files. | **high** |
+| `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. | **highest** |
+| `mcp_component_create` | Writes a **new** component row **directly to the DB** (immediate, new id). | medium (can create duplicates) |
+
+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 `components sync` / `components commit`, the server clears the full branch/user staging
+  scope. This is the expected clean state: old Redis aliases should not keep shadowing the newly synced DB rows.
+
+### 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).
+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. `mcp_component_create` is the direct-DB alternative for no-repo or
+remote-account work — do not use it to work around an id/name mismatch, and never to replace 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`)
+
+- 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.
+- 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 use
+`mcp_component_create` to "make ids line up" or to 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 instead of improvising.
+
 ## Required Local Index Reads
 
 These files are decision inputs. Read them when the related decision depends on them.
@@ -411,6 +518,25 @@ remits-cli auth --account-id <ACCOUNT_ID> --base-url http://localhost:8080
 - `--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.
+
 ### Data Mode
 
 Controls whether you work with test data or production data. **Default is `test`.**
@@ -534,29 +660,41 @@ Before committing, update metadata so the next session understands what changed:
 
 `account-info.json` is read-only — never edit it. It regenerates automatically after sync.
 
-#### Step 7: Commit and Sync
+#### Step 7: Commit and Durable Sync
 
-Once verified and documented:
+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>
-remits-cli components sync
-git pull --ff-only origin <branch>
 ```
 
-This separates the failure boundaries cleanly:
+This separates the local failure boundaries cleanly:
 1. Local git commit
 2. Remote push
-3. Server sync from the git remote
-4. Local fast-forward pull of the exact platform-generated commit, including updates such as `account-info.json`
 
-`remits-cli components sync` is the authoritative platform-sync step. It does not perform local git operations.
+After the push, run the **Component Integrity Rules** 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 prefer the explicit `git -> remits-cli components sync -> git pull` sequence so each phase is observable and retryable on its own.
+`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 this skill,
+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.
 
@@ -620,7 +758,8 @@ component's OWN type enum such as `ObjectType`/`RuleType`, or absent — **never
 At compile time the platform computes a **signature** that tells you which layer won:
 
 - Staged override present → `compileSignature = "cli:<hash>"` (the staged content hash).
-- No staged override → `compileSignature = "version:<N>"` (the DB row version).
+- No staged override → `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).
 
 That signature is logged. Querying for it is the single most reliable way to know what ran:
 
@@ -629,15 +768,31 @@ remits-cli tool --name mcp_system_logs --input '{"node":"remitsAdmin-east5","tim
 ```
 
 `Using Cached BCD [ID: 230, Type: Action, Signature: cli:08cc...]` → ran a **staged** override.
-`...Signature: version:37]` → ran the **committed DB** version.
+`...Signature: version:37:abc123def456]` → ran the **committed DB** version.
 
 ### When staged overrides apply
 
-Staged overrides resolve **only when the execution carries a CLI TestMode** — i.e. `TestMode.branchName`
-and `TestMode.cliUserId` are set (a `remits-cli test run`, a `mcp_run_test`, or a tokenized run minted with
-those). A **pure production run with no TestMode always uses the DB source**, ignoring staging entirely. So
-"I staged it but the live webhook still runs the old code" is expected — staging is a dev/verification
-surface, not a deploy.
+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`
+- `mcp_run_test`
+- 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
 
@@ -655,6 +810,9 @@ surface, not a deploy.
   `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 the current branch/user staged entries,
+  including `componentSource`, staged fields, aliases, hashes, and TTLs. `remits-cli components clear` removes
+  those entries when you intentionally want to fall back to DB source.
 
 ### Stage / commit / clear with the MCP tools
 
@@ -676,7 +834,9 @@ surface, not a deploy.
   later test runs.
 - `remits-cli components sync` (the `commit`/`sync` mode on the `components` endpoint) syncs the DB from the
   git remote and then **also clears the staged entries** for the synced components, so a clean commit leaves a
-  clean staging cache on both the CLI and MCP-tool surfaces.
+  clean staging cache on both the CLI and MCP-tool surfaces. Because sync reconciles the remote repo into the
+  live component database, it must pass the Component Integrity Rules first. Never use sync 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)
 
@@ -915,6 +1075,12 @@ Query Cloud Run service logs.
 ### `mcp_component_view`
 Read component field content with line numbers.
 
+Note: component source-management tools such as `mcp_component_view`, `mcp_component_grep`,
+`mcp_component_edit`, `mcp_component_create`, and `mcp_component_commit` are primarily for MCP-only
+clients that do not have a local account repo. In a normal `remits-cli` coding workflow, prefer local
+repo files plus `remits-cli components stage` / `remits-cli components sync`; if these component tools
+are absent from `remits-cli tools`, that is expected.
+
 | Parameter | Required | Description |
 |-----------|----------|-------------|
 | `accountId` | yes | Account ID |
@@ -1010,6 +1176,20 @@ auxiliary components). See "Component Resolution" for stage-vs-DB behavior.
 | `editMode` | no | `targeted` (default, anchor-verified line edit via `lineStart`/`lineEnd`/`anchorContent`/`newContent`) or `replace` (full-field `newContent`) |
 | `auxiliary`/`category`/`partnerSlug` | no | Companion metadata applied alongside the edit |
 
+### `mcp_component_create`
+Create a new component row directly in the database. This is a direct-DB operation, not the normal repo-backed
+component creation workflow.
+
+Use it only when:
+- there is no local account repo available, or
+- the user explicitly asks for direct remote creation, or
+- an emergency repair plan intentionally creates a new row after live inventory and git history have been
+  reconciled.
+
+In a repo-backed account, prefer `new_` component files plus stage/test/git/sync after the Component Integrity
+Rules pass. Never use `mcp_component_create` to compensate for an unexpected deletion, a renamed numeric file,
+or a local/live ID mismatch.
+
 ### `mcp_component_commit`
 Inspect, flush, or clear the CLI staging cache for components.
 
@@ -1032,7 +1212,7 @@ to remove staged entries).
 
 ## Multi-Session Support
 
-The CLI supports multiple authenticated sessions simultaneously. Sessions are stored in `~/.remits-cli/sessions.json` as a map keyed by `accountId + dataMode + baseUrl`, so the same account can stay authenticated against both localhost and production without one session overwriting the other. When you run any command from an account repo, the CLI automatically resolves the best matching session based on the `account-info.json` in that directory and any `--base-url` or `--data-mode` flags provided.
+The CLI supports multiple authenticated sessions simultaneously. Sessions are stored in `~/.remits-cli/sessions.json` as a map keyed by `accountId + dataMode + baseUrl`, so the same account can stay authenticated against both localhost and production without one session overwriting the other. When you run any command from an account repo, the CLI automatically resolves the best matching session based on the `account-info.json` in that directory and any `--base-url` or `--data-mode` flags provided. If the same account is authenticated against multiple hosts and you omit `--base-url`, the CLI may legitimately choose either localhost or a deployed host depending on the best session match, so agents should treat `--base-url` as mandatory whenever host matters.
 
 ```bash
 # Authenticate for an account (run from its repo, or pass --account-id)
@@ -1192,12 +1372,14 @@ remits-cli status
 remits-cli listen [stop|status] [--foreground true]   # compatibility alias
 remits-cli data-mode [set test|prod]
 remits-cli components stage [--branch <name>] [--data-mode test|prod]
-remits-cli components sync [--branch <name>] [--data-mode test|prod]
+remits-cli components status [--branch <name>] [--component-type <type>] [--component-id <id>]
+remits-cli components clear [--branch <name>] [--component-type <type>] [--component-id <id>]
+remits-cli components sync [--branch <name>] [--data-mode test|prod]   # gated durable repo->DB reconciliation only
 remits-cli components commit [--message "msg"] [--data-mode test|prod]
 remits-cli test run --test <id|name> [--names "a,b"] [--watch true|false] [--data-mode test|prod]
 remits-cli token [--path <embeddablePathOrId>] [--data-mode test|prod]
-remits-cli tools [--data-mode test|prod]
-remits-cli tool --name <toolName> [--input "{...}"] [--data-mode test|prod]
+remits-cli tools [--branch <name>] [--data-mode test|prod]
+remits-cli tool --name <toolName> [--branch <name>] [--input "{...}"] [--data-mode test|prod]
 ```
 
 For tests specifically:
@@ -1212,15 +1394,17 @@ For tests specifically:
 | `account-info.json not found` | Run from the account repo root |
 | Test not found (404) | New component not staged yet. Run `remits-cli components stage` first. For new tests (no ID), run by name not ID. |
 | Stage shows 0 updated | No changes since last stage (hash dedup) |
-| Test runs old code after edit | You forgot to stage. Run `remits-cli components stage` THEN re-run the test. The platform runs whatever was last staged, not your local files. |
+| Test runs old code after edit | You forgot to stage, or you are looking at DB while a staged entry is still active. Run `remits-cli components status`; then `remits-cli components stage` to update staged code or `remits-cli components clear` to fall back to DB. |
 | "Git credentials" or `git push` error | Git auth is required for commit (server pulls from git remote). Fix git authentication (SSH keys or HTTPS credentials) before retrying. Staging and testing still work without git. |
+| Need to learn command behavior | Read this skill, repo docs, or CLI source. Do not run unsupported mutating subcommand variants such as `remits-cli components commit --help`; if a command unexpectedly mutates or commits, stop and inspect the repo-local session log before doing anything else. |
+| Sync response reports unexpected deletes, creates, renames, uniqueness errors, or component ID drift | Stop immediately. Do not rerun sync, do not patch around it with `mcp_component_create`, and do not promote more changes. Preserve session logs/tool responses, compare `account-info.json`, local filenames, live inventory, and git history, then prepare a repair/escalation summary. |
 | 500 / `Internal Server Error` from Remits | Stop normal task work. Capture the exact command, error, and response artifact, then escalate to a Remits system admin. Do not invent a workaround. |
 | Tool parameters rejected | Tool schemas may be cached. Run `remits-cli tools` to refresh `.remits-cli/tools/tools.json` with latest schemas. |
 | Tool response missing | Check `./.remits-cli/tool-responses/` |
-| Staged change has no effect in a live (non-test) run | Staged overrides resolve only under a CLI TestMode (`branchName`+`cliUserId`). A pure prod run always uses the DB. `commit` to make it durable. See "Component Resolution". |
+| Staged change has no effect in a live (non-CLI) run | Staged overrides resolve only under a CLI TestMode (`branchName`+`cliUserId`). Live webhooks and other non-CLI runtime paths still use the DB. `commit` to make it durable. See "Component Resolution". |
 | New source shown by `mcp_component_view` but old behavior persists after sync/commit | In-memory compile cache (`CLOSURE_CACHE`, version-keyed, per instance) still holds the prior closure. Environmental; the platform owner recycles the instance. |
 | Staged Reader test run throws `No enum constant ObjectType.<family>` | The staged entry has the component family in `type` (should be `kind`). Clear + re-stage; if it persists, the `mcp_component_edit` tool on that instance is on an old/cached version. Inspect with `mcp_cache`. |
-| Unsure whether a run used staged vs DB source | Query `mcp_system_logs` for `Using Cached BCD` — `Signature: cli:<hash>` = staged, `version:<N>` = DB. |
+| Unsure whether a run used staged vs DB source | Query `mcp_system_logs` for `Using Cached BCD` — `Signature: cli:<hash>` = staged, `version:<N>:<sourceHash12>` = DB. CLI/MCP tool results also report `componentSource` and `componentSignature` when available. |
 | Service already running | Run `remits-cli status` to get the dashboard URL, or `remits-cli stop` before restarting. |
 | tmux not installed | Install tmux (`brew install tmux` on macOS). Required for agent dispatch. |
 | Control center URL unknown | Read `~/.remits-cli/service-state.json` or run `remits-cli status` |