@remits/remits-cli 0.1.101 → 0.1.104

package/README.md

@@ -33,7 +33,7 @@ remits-cli components sync
 remits-cli components sync --branch feature_branch --dry-run
 remits-cli components sync --branch feature_branch --dry-run --summary
 remits-cli components sync --branch feature_branch --force-tombstones
-remits-cli token --path page/my-embeddable
+remits-cli token --path page/my-embeddable    # returns tokenKey/embeddableUrl, plus embedTokenKey/embedSnippet for host embeds
 remits-cli token --path page/my-embeddable --variant-branch feature_branch
 remits-cli token inspect --token https://example.test/s/<tokenKey>/page/my-embeddable
 remits-cli tool --name mcp_account_user_admin --data-mode prod --input '{"action":"account_create","parentAccountId":4,"name":"Freto","type":"PRODUCT","dryRun":true}'
@@ -90,6 +90,7 @@ remits-cli install --skills --overwrite true
 - 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.
 - `--variant-branch <name|none>` is available on `test run`, `token`, `tools`, and `tool`. Use it to probe a committed branch variant from any checkout; omit it to resolve the execution account's normal subscription, or pass `none`/`trunk` to force subscription semantics from a variant checkout.
+- On `test run`, `--branch <name>` is only the Redis staging namespace. Pair an unused value with `--variant-branch none` when existing staged entries on the real git branch would shadow committed trunk/variant rows. Do not apply that shortcut to `components sync` or `components commit`, where `--branch` names the GitHub branch to reconcile.
 
 ## Service, Dashboard, WebSocket, and Tmux Lifecycle
 
@@ -100,6 +101,7 @@ remits-cli install --skills --overwrite true
 - `remits-cli start` starts a detached background process by default. Use `remits-cli start --foreground true` only when you want to run the daemon in the current terminal.
 - `remits-cli status` reports whether the background service is alive, prints the dashboard URL when available, and prints the resolved session tuple: Account ID, User ID, current git branch, and active data mode.
 - `remits-cli whoami` prints only the resolved session tuple. Use `--base-url`, `--account-id`, and `--data-mode` to prove the exact host/account/lane before running a tool or test.
+- Both print **two** data modes. "Data mode" governs `tool` / `tools` / `token` and falls back to the stored session lane; "Data mode (test run)" governs `test run`, which ignores the session and defaults to `test` unless `--data-mode prod` is passed.
 - `remits-cli stop` stops the background service, kills the shared tmux session, and clears pane tracking state.
 - The service starts a localhost dashboard that acts as a control center for remits-cli integration state.
 - The dashboard shows websocket connection health, topic subscriptions, tmux session/panes, the discovered account repo index, global state files, and per-repo remits-cli files.

package/index.js

@@ -335,6 +335,10 @@ function resolveSessionIdentity(cwd, flags = {}) {
     userName: user.name || user.username || user.email || null,
     branchName,
     dataMode,
+    // `test run` resolves its lane from the FLAG ONLY (testRunCommand), never the stored session, so that
+    // an account whose session is parked on prod cannot have a test run silently follow it. Report both
+    // rather than a single number that governs only some commands.
+    testRunDataMode: requestedDataMode || DEFAULT_DATA_MODE,
     baseUrl: normalizeBaseUrl((session && session.baseUrl) || requestedBaseUrl || DEFAULT_BASE_URL),
     updatedAt: session ? session.updatedAt : null,
     sessionResolutionWarning
@@ -352,7 +356,8 @@ function printSessionIdentity(identity, options = {}) {
     console.log('Account ID:', identity.accountId || 'unresolved');
     console.log('User ID:', 'unresolved');
     console.log('Branch:', identity.branchName || 'unresolved');
-    console.log('Data mode:', identity.dataMode || DEFAULT_DATA_MODE);
+    console.log('Data mode:', (identity.dataMode || DEFAULT_DATA_MODE) + ' (applies to tool/tools/token)');
+    console.log('Data mode (test run):', identity.testRunDataMode || DEFAULT_DATA_MODE);
     console.log('Base URL:', identity.baseUrl);
     return;
   }
@@ -375,7 +380,12 @@ function printSessionIdentity(identity, options = {}) {
     console.log('  User:', identity.userName);
   }
   console.log('  Branch:', identity.branchName);
-  console.log('  Data mode:', identity.dataMode);
+  console.log('  Data mode:', identity.dataMode, '(applies to tool/tools/token)');
+  // `test run` deliberately ignores the stored session lane and defaults to test, so a session sitting on
+  // prod would otherwise read as "prod" here while the next test run went to the test lane. Say so rather
+  // than letting the tuple imply a lane it does not govern.
+  console.log('  Data mode (test run):', identity.testRunDataMode,
+    identity.testRunDataMode === identity.dataMode ? '' : '— test run ignores the session lane; pass --data-mode prod to override');
   console.log('  Base URL:', identity.baseUrl);
   if (identity.updatedAt) {
     console.log('  Session updated:', identity.updatedAt);
@@ -1376,7 +1386,15 @@ function collectComponents(cwd) {
       const key = type + ':' + (id ? 'id:' + id : 'name:' + name.toLowerCase());
 
       if (!byKey.has(key)) {
-        byKey.set(key, { type, id, name });
+        // `metadataAuthoritative` tells the server this payload was assembled from the repo, so the
+        // .meta.yml it carries is the COMPLETE metadata for the component. The server then removes
+        // staged metadata keys the sidecar no longer declares, instead of carrying them forever —
+        // without it, deleting a key from a sidecar and re-staging left the old value staged, so
+        // "restore the file and re-stage" did not restore the staged state.
+        //
+        // A partial stage (mcp_component_edit writing one field) deliberately does NOT set this and
+        // keeps the merge semantics it needs.
+        byKey.set(key, { type, id, name, metadataAuthoritative: true });
       }
       const component = byKey.get(key);
       const filePath = path.join(dir, fileName);
@@ -2332,19 +2350,97 @@ async function syncComponentsCommand(flags) {
   }
   if (namesOnly) {
     printSyncNames(response);
+    printPromotionSignals(response);
     failOnSyncGate(gate);
     return response;
   }
   if (flagEnabled(flags.summary)) {
     console.log('Components sync summary:', JSON.stringify(summary, null, 2));
+    printPromotionSignals(response);
     failOnSyncGate(gate);
     return response;
   }
   console.log('Components sync:', JSON.stringify(response, null, 2));
+  printPromotionSignals(response);
   failOnSyncGate(gate);
   return response;
 }
 
+// A sync is a step in a longer loop, and the steps after it are the ones that get skipped — so print what
+// the server just observed about this branch's relationship to trunk, not only what it wrote.
+function printPromotionSignals(response) {
+  const sync = (response && response.sync) || {};
+
+  const cmp = sync.branchComparison;
+  if (cmp && cmp.comparable) {
+    console.log('');
+    console.log('Branch vs trunk "' + cmp.trunkBranch + '": ' + cmp.aheadBy + ' ahead, ' + cmp.behindBy +
+      ' behind  [phase ' + cmp.phase + ']');
+    if (cmp.phase === 'diverged') {
+      console.log('  This branch has not merged trunk in. Its overlays assert its OLD copy of everything');
+      console.log('  trunk has changed since, and its subscribers are running that copy right now.');
+      console.log('  Fix: git merge ' + cmp.trunkBranch + ' into this branch, push, then sync again.');
+    } else if (cmp.phase === 'awaiting-merge-back') {
+      console.log('  Every commit here is already in trunk and trunk has moved on — a promotion merge-back');
+      console.log('  is outstanding. Until it happens the subscribers stay pinned to the pre-promotion copy.');
+      console.log('  Fix: git merge ' + cmp.trunkBranch + ' into this branch, push, then sync again.');
+    }
+    if (cmp.deletionEvidence !== 'complete') {
+      console.log('  NOTE: deletion evidence is ' + cmp.deletionEvidence + ', so removals fall back to the');
+      console.log('  conservative ratio guard rather than git\'s own answer.');
+    }
+  } else if (cmp) {
+    console.log('');
+    console.log('Branch vs trunk: UNAVAILABLE' + (cmp.message ? ' (' + cmp.message + ')' : ''));
+  }
+
+  const promotion = sync.promotion;
+  if (promotion) {
+    (promotion.tags || []).forEach((t) => {
+      console.log('');
+      console.log('Tagged promotion: ' + t.tag + ' -> ' + short(t.sha) + ' (' + t.ref + ')');
+    });
+    // Older servers sent bare branch names; newer ones send {branch, overlayCount}. Normalize, because the
+    // count decides whether this is an alarm or a tidy-up and the difference must not be guessed.
+    const pending = (promotion.pendingMergeBack || []).map((entry) =>
+      (typeof entry === 'string' ? { branch: entry, overlayCount: -1 } : entry));
+    if (pending.length) {
+      const shadowing = pending.filter((p) => p.overlayCount > 0);
+      const unknown = pending.filter((p) => !(p.overlayCount >= 0));
+      console.log('');
+      if (shadowing.length) {
+        console.log('THE PROMOTION IS NOT FINISHED. Trunk is synced, but ' + shadowing.length +
+          ' variant branch(es) still SHADOW it — their subscribers resolve the PRE-promotion code:');
+      } else if (unknown.length) {
+        // The overlay count could not be read, so say nothing about what is shadowed. "Nothing is
+        // shadowed" would be a claim, and an unverifiable one is the failure this whole change is about.
+        console.log('THE PROMOTION IS NOT FINISHED. Trunk is synced, but ' + pending.length +
+          ' variant branch(es) are behind it and owe a merge-back:');
+      } else {
+        console.log('Merge-back outstanding on ' + pending.length + ' variant branch(es). Nothing is shadowed' +
+          ' (no overlays stored), but the branch is behind trunk until you merge it back:');
+      }
+      pending.forEach((p) => {
+        const detail = p.overlayCount > 0 ? '  (' + p.overlayCount + ' overlay(s) shadowing trunk)'
+          : p.overlayCount === 0 ? '  (0 overlays — converged, just behind)' : '';
+        console.log('  ' + p.branch + ':' + detail);
+        console.log('    git checkout ' + p.branch + ' && git merge ' + (sync.branchName || 'main') + ' && git push');
+        console.log('    remits-cli components sync --branch ' + p.branch);
+      });
+      console.log('  Verify with: remits-cli components promotion --branch <name>');
+    }
+  }
+
+  (sync.advisories || []).forEach((advisory) => {
+    console.log('');
+    console.log('ADVISORY [' + advisory.code + ']: ' + advisory.message);
+    (advisory.findings || []).slice(0, 15).forEach((f) => {
+      console.log('  ' + f.path + ':' + f.line + '  ' + f.call);
+    });
+    if (advisory.truncated) console.log('  ... (list truncated; re-run with --json for the rest)');
+  });
+}
+
 function syncPreflightRequested(flags) {
   return Boolean(
     flagEnabled(flags['names-only']) ||
@@ -2472,9 +2568,41 @@ function failOnSyncGate(gate) {
 function buildSyncSummary(response) {
   const sync = (response && response.sync) || {};
   const results = sync.syncResults || {};
-  const removed = Array.isArray(results.removed) ? results.removed : [];
   const errors = Array.isArray(results.errors) ? results.errors : [];
   const skipped = Array.isArray(results.skipped) ? results.skipped : [];
+
+  // A TRUNK sync and a VARIANT sync report in different vocabularies, and this summary only ever spoke
+  // variant. So the single most consequential line of a promotion — "component X was CREATED on trunk as
+  // id N" — printed as `added: 0`, and the runbook's definition of done ("components created, with their
+  // new ids") could not be satisfied from the summary it tells you to read.
+  if ((sync.mode || 'trunk') === 'trunk') {
+    const created = Array.isArray(results.created) ? results.created : [];
+    const updated = Array.isArray(results.updated) ? results.updated : [];
+    const renamed = Array.isArray(results.renamed) ? results.renamed : [];
+    const deleted = Array.isArray(results.deleted) ? results.deleted : [];
+    const trunkWarnings = [];
+    if (deleted.length) trunkWarnings.push(String(deleted.length) + ' live component(s) DELETED');
+    if (errors.length) trunkWarnings.push(String(errors.length) + ' sync error' + (errors.length === 1 ? '' : 's') + ' present');
+    return {
+      success: response && response.success === true,
+      accountId: response && response.accountId,
+      branchName: sync.branchName || (response && response.branchName),
+      mode: 'trunk',
+      dryRun: false,
+      // Ids are the part that cannot be recovered later: a promotion mints them once, and anything that
+      // recorded the old identity will not line up if they are re-minted.
+      created: created.map((e) => ({ type: e.type, name: e.name, id: e.newId != null ? e.newId : e.id })),
+      updated: updated.length,
+      renamed: renamed.length,
+      deleted: deleted.map((e) => ({ type: e.type, name: e.name, id: e.id })),
+      skipped: skipped.length,
+      errors: errors.length,
+      errorDetails: errors.map((entry) => ({ type: entry.type, id: entry.id, error: entry.error })),
+      warnings: trunkWarnings
+    };
+  }
+
+  const removed = Array.isArray(results.removed) ? results.removed : [];
   const added = Array.isArray(results.added) ? results.added : [];
   const overridden = Array.isArray(results.overridden) ? results.overridden : [];
   const unchanged = Array.isArray(results.unchanged) ? results.unchanged : [];
@@ -2563,6 +2691,8 @@ async function branchesComponentsCommand(flags) {
     // Optional branch-scoped custom host set on the same edge as the subscription.
     // `--domain none` clears it; omitting the flag leaves any existing host untouched.
     domainName: flags.domain || flags['domain-name'],
+    dryRun: flagEnabled(flags['dry-run']) || flagEnabled(flags.dryRun),
+    confirmPrimaryEdge: flagEnabled(flags['confirm-primary-edge']) || flagEnabled(flags.confirmPrimaryEdge),
     force: flagEnabled(flags.force)
   }).then((r) => r.data);
 
@@ -2596,9 +2726,13 @@ function printBranchesSummary(response) {
       console.log('  ' + b.branch +
         '  (overridden ' + b.overridden + ', added ' + b.added + ', removed ' + b.removed +
         ', subscribers ' + b.subscribers + ')' + drift);
+      // Name the commit these counts describe. Without it a three-day-old inventory reads exactly like a
+      // current one, which is how a promotion gets reviewed against the wrong tree.
+      console.log('      computed from ' + short(b.syncedSha) + (b.updated ? ' at ' + b.updated : ''));
     });
     console.log('');
-    console.log('Detail: remits-cli components branch <name>');
+    console.log('Detail:    remits-cli components branch <name>');
+    console.log('Promotion: remits-cli components promotion --branch <name>   # is that commit still the branch HEAD?');
     return;
   }
 
@@ -2656,6 +2790,12 @@ function printBranchesSummary(response) {
 
   if (response.mode === 'subscribe' || response.mode === 'unsubscribe' || response.mode === 'retire') {
     console.log(response.message);
+    if (response.requiresConfirmation) {
+      console.log('Confirmation required: re-run with --confirm-primary-edge if that structural edge should subscribe.');
+    }
+    if (response.edge) {
+      console.log('Edge: ' + response.edge.edgeType + ' -> parent ' + response.edge.parentAccountId);
+    }
     return;
   }
 
@@ -2669,6 +2809,167 @@ function printBranchesSummary(response) {
   });
 }
 
+// The promotion "lay of the land": where this branch sits relative to trunk, whether the platform's
+// stored overlays actually describe the branch's current HEAD, who is affected, and the ordered commands
+// for the next step. Every fact here was already obtainable one command at a time; the point is that a
+// promotion goes wrong by assembling a wrong picture out of individually true answers, so this assembles
+// the picture once, server-side, from the REMOTE (which is what the platform syncs from — not your
+// working tree).
+async function promotionComponentsCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const sessionContext = resolvePromotionSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const api = buildAxios(baseUrl, session.token);
+
+  const positional = flags._ && flags._[2];
+  const branchName = flags.branch || positional || currentBranch(cwd);
+
+  const response = await loggedPost(api, cwd, '/cli/branches', {
+    token: session.token,
+    accountId,
+    mode: 'promotion',
+    branchName
+  }).then((r) => r.data);
+
+  if (!response.success) {
+    throw new Error(response.message || 'Promotion status failed');
+  }
+
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify(response, null, 2));
+  } else {
+    printSessionResolutionWarning(sessionContext);
+    printResolvedBaseUrl(baseUrl);
+    // Say this out loud: the command is named for the operation it reports on, and an agent that reads
+    // "promotion" as "promoted" would skip the git steps this output is telling it to run.
+    console.log('This REPORTS promotion readiness. It performs no git operation and writes nothing.');
+    if (Array.isArray(response.branches)) {
+      response.branches.forEach((entry) => printPromotionStatus(entry, response));
+    } else {
+      printPromotionStatus(response, response);
+    }
+  }
+
+  // Fail closed by default. This command exists to be the gate an agent runs BEFORE touching git, and a
+  // gate that always exits 0 is a suggestion. `--no-fail` is for a human who only wants to look.
+  const blockers = collectPromotionBlockers(response);
+  if (blockers.length && !flagEnabled(flags['no-fail'])) {
+    throw new Error('promotion is blocked (' + blockers.length + '):\n  ' +
+      blockers.map((b) => b.code + ': ' + b.message).join('\n  ') +
+      '\nRe-run with --no-fail to inspect without failing.');
+  }
+  return response;
+}
+
+// A promotion is normally driven from the BRANCH's checkout, and on a single-subscriber branch that
+// checkout's account-info.json describes the SUBSCRIBER — so the CLI resolves the subscriber's account id
+// and demands a session for it, which an owner-side agent has no reason to hold. Every other branch
+// command has the same shape and tells you to pass `--account-id <ownerId>`; this one should not need to
+// be told, because it is READ-ONLY and the server already resolves the branch owner itself.
+//
+// So: if there is no session for the local account, and the checkout names its component owner, retry as
+// the owner. Deliberately scoped to this command — `sync`/`commit` mutate, and there the account the CLI
+// acts as is a decision, not a detail.
+function resolvePromotionSessionContext(cwd, flags) {
+  try {
+    return resolveSessionContext(cwd, flags);
+  } catch (err) {
+    if (flags && flags['account-id']) throw err;
+    let ownerId = null;
+    try {
+      const info = JSON.parse(fs.readFileSync(path.join(cwd, 'account-info.json'), 'utf8'));
+      const resolution = (info && info.resolution) || {};
+      const localId = Number(accountIdFromAccountInfo(info));
+      const candidate = Number(resolution.componentOwnerAccountId);
+      if (Number.isFinite(candidate) && candidate > 0 && candidate !== localId) ownerId = candidate;
+    } catch (_) { /* not an account repo, or no owner recorded */ }
+    if (!ownerId) throw err;
+
+    const ownerContext = resolveSessionContext(cwd, Object.assign({}, flags, { 'account-id': ownerId }));
+    console.log('Note: no session for this checkout\'s account; reporting as its component OWNER, account ' +
+      ownerId + '. Branch overlays belong to the owner, so this is the account that can answer.');
+    return ownerContext;
+  }
+}
+
+function collectPromotionBlockers(response) {
+  if (Array.isArray(response.branches)) {
+    return response.branches.reduce((all, entry) => all.concat(entry.blockers || []), []);
+  }
+  return response.blockers || [];
+}
+
+function printPromotionStatus(entry, envelope) {
+  const git = entry.git || {};
+  const platform = entry.platform || {};
+  console.log('');
+  console.log('Branch:      ' + entry.branch + '   (trunk "' + (entry.trunkBranch || envelope.trunk) + '")');
+  console.log('Owner:       account ' + entry.ownerAccountId + (entry.ownerAccountName ? ' (' + entry.ownerAccountName + ')' : '') +
+    '   repo ' + (entry.repository || '?'));
+  console.log('Phase:       ' + String(entry.phase || 'unknown').toUpperCase());
+  if (entry.summary) console.log('             ' + entry.summary);
+
+  console.log('');
+  console.log('  git (remote):');
+  if (git.comparable) {
+    console.log('    ahead of trunk:  ' + git.aheadBy + ' commit(s)   [work not yet promoted]');
+    console.log('    behind trunk:    ' + git.behindBy + ' commit(s)   [trunk this branch has not merged in]');
+    console.log('    merge base:      ' + short(git.mergeBaseSha));
+    console.log('    branch HEAD:     ' + short(git.branchHeadSha));
+    console.log('    trunk HEAD:      ' + short(git.trunkHeadSha));
+    const deletions = git.deliberateDeletions || [];
+    console.log('    deliberate component deletions on this branch: ' + deletions.length +
+      (git.deletionEvidence === 'complete' ? '' : '   (evidence ' + git.deletionEvidence + ')'));
+    deletions.slice(0, 20).forEach((p) => console.log('      D ' + p));
+  } else {
+    console.log('    UNAVAILABLE' + (git.message ? ': ' + git.message : ''));
+  }
+
+  console.log('');
+  console.log('  platform (what subscribers resolve right now):');
+  console.log('    overridden ' + platform.overridden + ', branch-only ' + platform.added +
+    ', tombstoned ' + platform.removed + ', drifted ' + platform.drifted);
+  // Freshness is decided server-side (BranchPromotion.freshnessOf) because sparseness compares BOTH sides
+  // and there are two independent ways to go stale. Re-deriving that here from separate booleans would be
+  // a second copy of one rule.
+  const FRESHNESS_LABELS = {
+    'current': '   [current]',
+    'stale-branch-moved': '   [STALE — does not match the branch HEAD]',
+    'stale-trunk-moved': '   [STALE — matches the branch HEAD, but trunk has moved since]'
+  };
+  console.log('    overlays computed from: ' + short(platform.syncedSha) +
+    (FRESHNESS_LABELS[platform.freshness] || '   [unknown]'));
+  (platform.subscribers || []).forEach((s) => {
+    console.log('    subscriber: account ' + s.accountId + (s.accountName ? ' (' + s.accountName + ')' : '') +
+      (s.domainName ? '  [host ' + s.domainName + ']' : ''));
+  });
+
+  const blockers = entry.blockers || [];
+  if (blockers.length) {
+    console.log('');
+    console.log('  BLOCKERS (' + blockers.length + '):');
+    blockers.forEach((b) => {
+      console.log('    * ' + b.code);
+      console.log('      ' + b.message);
+      console.log('      fix: ' + b.fix);
+    });
+  }
+
+  const steps = entry.nextSteps || [];
+  if (steps.length) {
+    console.log('');
+    console.log('  NEXT, IN ORDER:');
+    steps.forEach((s, i) => console.log('    ' + (i + 1) + '. ' + s));
+  }
+  console.log('');
+}
+
+function short(sha) {
+  return sha ? String(sha).slice(0, 8) : 'unknown';
+}
+
 async function commitComponentsCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
@@ -2935,13 +3236,18 @@ async function tokenCommand(flags) {
   // Embeddable resolves that account's branch variants rather than the owner's trunk.
   // --variant-branch explicitly probes a committed variant branch before any edge subscribes.
   const variantBranch = flags['variant-branch'];
+  // Send the path so the server can also mint the EMBEDDABLE-SCOPED token key. `tokenKey` opens a
+  // tokenized URL in a browser; `embedTokenKey` lets the `<script>` embed loader resolve the component
+  // from persisted token context because the loader request sends no path.
+  const requestedPath = flags.path || flags['embeddable-path'];
   const data = await loggedPost(api, cwd, '/cli/token', {
     token: session.token,
     accountId,
     asAccountId: flags['as-account'] || flags['as-account-id'],
     variantBranch,
     branchName,
-    dataMode
+    dataMode,
+    path: requestedPath
   }).then((r) => r.data);
 
   if (!data.success) {
@@ -2949,7 +3255,7 @@ async function tokenCommand(flags) {
   }
 
   const base = baseUrl.replace(/\/$/, '');
-  const embeddablePath = flags.path || flags['embeddable-path'];
+  const embeddablePath = requestedPath;
   let embeddableUrl = embeddablePath
     ? (base + '/s/' + data.tokenKey + '/' + String(embeddablePath).replace(/^\/+/, ''))
     : null;
@@ -2970,6 +3276,26 @@ async function tokenCommand(flags) {
     embeddableUrl
   };
 
+  // What the token will RESOLVE AS. `accountId` says which account it executes as; on a hierarchy the
+  // decisive facts are which component branch applies, whose components those are, and which storage
+  // namespace the page reads — none of which are inferable from the id. Present only when the server
+  // could resolve it.
+  if (data.resolution) {
+    output.resolution = data.resolution;
+  }
+
+  // Present only when the path resolved to an Embeddable. `embedTokenKey` is what a host site pastes
+  // into the loader snippet; the render shape is echoed because it decides what that host receives.
+  if (data.embedTokenKey) {
+    output.embeddableId = data.embeddableId;
+    output.embeddableName = data.embeddableName;
+    output.injectionType = data.injectionType;
+    output.renderMode = data.renderMode;
+    output.headMode = data.headMode;
+    output.embedTokenKey = data.embedTokenKey;
+    output.embedSnippet = data.embedSnippet;
+  }
+
   printSessionResolutionWarning(sessionContext);
   console.log(JSON.stringify(output, null, 2));
 }
@@ -5624,6 +5950,23 @@ function autoUpdateIfNeeded(originalArgv, options = {}) {
 }
 
 function printComponentsHelp(subcommand) {
+  if (subcommand === 'promotion' || subcommand === 'promote') {
+    console.log('Usage: remits-cli components promotion [<branch>] [--branch NAME] [--json] [--no-fail]');
+    console.log('');
+    console.log('Reports where a variant branch sits in the promotion loop and what to do next. It performs');
+    console.log('no git operation and writes nothing. Run it from either checkout — it resolves the branch');
+    console.log('OWNER, and it reads the REMOTE, which is what the platform actually syncs from.');
+    console.log('');
+    console.log('Phases:');
+    console.log('  converged            branch == trunk. Nothing to promote.');
+    console.log('  ready                branch is ahead of trunk and current with it -> promote.');
+    console.log('  diverged             branch is behind trunk. Merge trunk IN before reading any plan.');
+    console.log('  awaiting-merge-back  trunk absorbed this branch and moved on. Steps 4-5 are owed, and');
+    console.log('                       until they run the subscribers resolve the PRE-promotion code.');
+    console.log('');
+    console.log('Exits non-zero when there are blockers, so it can gate a runbook. --no-fail just looks.');
+    return;
+  }
   if (subcommand === 'sync') {
     console.log('Usage: remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary] [--json]');
     console.log('');
@@ -5669,7 +6012,7 @@ function printComponentsHelp(subcommand) {
     console.log('components commit does not support --dry-run.');
     return;
   }
-  console.log('Usage: remits-cli components <stage|status|clear|sync|commit|branches|branch>');
+  console.log('Usage: remits-cli components <stage|status|clear|sync|commit|promotion|branches|branch>');
   console.log('  remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--json|--verbose]');
   console.log('  remits-cli components status [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID] [--json|--verbose]');
   console.log('  remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE] [--component-id ID] [--all] [--json|--verbose]');
@@ -5688,13 +6031,13 @@ function printComponentsHelp(subcommand) {
   console.log('  remits-cli components branch <name> [--json]                       # overridden/added/removed + drift');
   console.log('  remits-cli components branch <name> --diff <componentId> --component-type <kind> [--json]');
   console.log('  remits-cli components branch <name> --subscribers [--json]');
-  console.log('  remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>]');
+  console.log('  remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]');
   console.log('  remits-cli components branch <name> --unsubscribe <accountId>');
   console.log('  remits-cli components branch <name> --retire [--force]');
 }
 
 function printTestHelp() {
-  console.log('Usage: remits-cli test run --test <id|name> [--base-url URL] [--names name1,name2] [--watch true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none]');
+  console.log('Usage: remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names name1,name2] [--watch true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none]');
   console.log('');
   console.log('Runs a Test component against the staged/variant world for this checkout.');
   console.log('Examples:');
@@ -5704,6 +6047,10 @@ function printTestHelp() {
   console.log('Notes:');
   console.log('  --names is comma-delimited, so avoid commas in individual test case names.');
   console.log('  --as-account changes the execution account so subscriber branch edges apply.');
+  console.log('  --variant-branch <name> probes a committed variant branch; use "none" or "trunk"');
+  console.log('       to force production/subscription semantics from a variant checkout.');
+  console.log('  --branch changes only the CLI staging namespace for test execution. Pair an unused');
+  console.log('       value with --variant-branch none when existing staged entries would shadow DB rows.');
   console.log('  --data-mode prod intentionally targets live production data.');
 }
 
@@ -5728,7 +6075,8 @@ function printTokenHelp() {
   console.log('Usage: remits-cli token [--base-url URL] [--branch BRANCH] [--path embeddable/path] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none]');
   console.log('       remits-cli token inspect --token <token|tokenKey|URL> [--base-url URL] [--account-id ID]');
   console.log('');
-  console.log('Mints a branch-aware browser URL for embeddable verification.');
+  console.log('Mints a branch-aware tokenKey and browser URL for embeddable verification.');
+  console.log('When --path resolves to an Embeddable, output also includes embedTokenKey and embedSnippet for host-site embeds.');
   console.log('Inspect decodes a persisted Remits token and prints token metadata, recognized routing fields, safety/dataMode evidence, and full context.');
 }
 
@@ -5792,15 +6140,17 @@ async function main() {
     console.log('  remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE] [--component-id ID] [--all] [--json|--verbose]');
     console.log('  remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary]');
     console.log('  remits-cli components commit [--message \"msg\"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones]');
+    console.log('  remits-cli components promotion [<branch>] [--json] [--no-fail]  # promotion readiness + ordered next steps');
     console.log('  remits-cli components branches [--json]                     # committed branch variants for this account');
     console.log('  remits-cli components branch <name> [--diff <componentId> --component-type <kind>] [--subscribers] [--json]');
-    console.log('  remits-cli components branch <name> --subscribe <accountId>      # make an account resolve this branch');
+    console.log('  remits-cli components branch <name> --subscribe <accountId> [--dry-run] [--confirm-primary-edge]');
     console.log('  remits-cli components branch <name> --unsubscribe <accountId>    # return that account to trunk');
     console.log('  remits-cli components branch <name> --retire [--force]           # delete the branch\'s overlays');
-    console.log('  remits-cli test run --test <id|name> [--base-url URL] [--names name1,name2] [--watch true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME]');
+    console.log('  remits-cli test run --test <id|name> [--base-url URL] [--branch stagingScope] [--names name1,name2] [--watch true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME]');
     console.log('  remits-cli token [--base-url URL] [--branch BRANCH] [--path embeddable/path] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none]');
     console.log('  remits-cli token inspect --token <token|tokenKey|URL> [--base-url URL] [--account-id ID]');
     console.log('');
+    console.log('  token output uses tokenKey for browser URLs and embedTokenKey/embedSnippet for host-site embeds.');
     console.log('  --as-account <ID> verifies AS a descendant subscriber account, so its relationship edge');
     console.log('  selects the component branch and the run resolves exactly what production will.');
     console.log('  --variant-branch <NAME> explicitly probes a committed variant branch (e.g. before any');
@@ -5866,6 +6216,11 @@ async function main() {
     return;
   }
 
+  if (command === 'components' && (subcommand === 'promotion' || subcommand === 'promote')) {
+    await promotionComponentsCommand(args);
+    return;
+  }
+
   if (command === 'components' && (subcommand === 'branches' || subcommand === 'branch')) {
     await branchesComponentsCommand(args);
     return;

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -166,31 +166,51 @@ For access questions — "who can see this client account?", "why does this user
 `mcp_sql_query` only when you need raw join-table investigation. Remember a user's custom fields are stored
 **per bound account**, so the same person can differ per account.
 
-**Test-data flags are first-class safety evidence.** `Account.testAccount` and `User.testUser` are set for
-accounts/users created while the execution data lane is `test` (including `mcp_account_user_admin`
-creation paths); prod-data creates leave them false. Updating an existing real account/user in test mode
-does not convert it into test data, but its Firestore extension-field writes still go to the test lane.
-`Object.testMode` / `Event.testMode` / `Alert.testMode` identify lifecycle rows in the test data lane.
-Agent-facing surfaces expose these fields:
+**Test-data flags are first-class safety evidence.** `Account.testAccount` and `User.testUser` are set by
+the `account(...)` / `user(...)` factories when the execution data lane is `test` (which is how
+`mcp_account_user_admin` creates); direct inserts such as `new Account(...).save()` are also flagged by the
+domain `beforeInsert` hook in the test lane. Prod-data creates leave them false. Updating an existing real
+account/user in test mode does not convert it into test data, though its Firestore extension-field writes
+still go to the test lane. `Object.testMode` /
+`Event.testMode` / `Alert.testMode` (and `testMode` inside test-lane Audit documents) identify lifecycle
+rows in the test data lane. Agent-facing surfaces expose these fields:
 
 - `account-info.json`, `account-hierarchy.json`, and `mcp_account_view`: `resolution.testAccount` for the
   described account, and `testAccount` on returned hierarchy nodes.
 - `mcp_account_user_admin`: `testAccount` on `hierarchy`, `account`, and `account_create` results;
   `testUser` on `users` / `user` results.
-- `mcp_record_listing` / `mcp_record_view`: `testMode` on `object`, `event`, and `alert` records.
+- `mcp_record_listing`: top-level `dataMode` (the lane it searched — listings are **filtered** by lane,
+  so `totalItems:0` in the wrong lane reads exactly like "no such record"), plus `testMode` per record.
+- `mcp_record_view`: `record.dataMode` (the lane read in) next to `record.testMode` (the lane the row
+  belongs to). This one loads **by id and does not filter**, so those two can legitimately disagree —
+  and when they do, that is the finding.
 - `mcp_object_activity`: top-level `dataMode`, `object.testMode`, and `testMode` on Event/Alert
   timeline entries.
 - `mcp_event_diagnostics`: top-level `dataMode` and `result.event.testMode`.
-- `remits-cli token inspect`: owner `account.testAccount` and `user.testUser`, plus token `dataMode`.
+- `remits-cli token inspect`: owner `account.testAccount` and `user.testUser`, plus a `safety` block
+  carrying `dataMode`, `dataModeDeclared`, and an explicit warning when the token does not declare one.
+- `remits-cli whoami`: the resolved account / user / branch / lane / host tuple for the **next tool
+  call**. It does not describe `remits-cli test run`, which ignores the stored session lane — see below.
 
-Persisted AI session rows currently do **not** store durable per-grouping `testMode` / `dataMode`; use
-`mcp_ai_session_search.dataMode` only as the current tool execution lane, not as proof of the historical
-grouping's data lane.
+Two surfaces deliberately have **no** lane flags, and both mislead if you forget it:
+
+- **`mcp_sql_query` reads MySQL directly and is lane-blind.** `object` / `event` / `alert` come back with
+  **both lanes mixed**, and `user` / `account` with test fixtures mixed into real records. Filter
+  explicitly — `test_mode = 0`, `test_user = 0`, `test_account = 0` — or use the purpose-built tool.
+- **Persisted AI session rows** store no durable per-grouping `testMode` / `dataMode`. Use
+  `mcp_ai_session_search.dataMode` as the current execution lane only, never as proof of the historical
+  grouping's lane.
 
 If any of those fields contradict the lane you intended, stop and rerun the command with an explicit
 `--data-mode test` or `--data-mode prod`. Never infer prod/test from an account name, URL, branch name, or
 the mere existence of a created account.
 
+**A tool's `dataMode` input never widens the lane.** Tools that accept a `dataMode` argument clamp it
+against the lane the *command* was launched with: it may narrow `prod` -> `test`, never escalate
+`test` -> `prod`. So `--data-mode test --input '{"dataMode":"prod"}'` stays in **test**, and the response's
+`dataMode` — not your input — is the truth. To reach prod data, pass `--data-mode prod` on the command
+line. (Under MCP, the launch lane is the caller's own `dataMode` argument, which defaults to `prod`.)
+
 Use `remits-cli` for everything else: staging changes, running tests, generating embeddable tokens,
 committing work, and diagnosing production issues.
 
@@ -297,8 +317,11 @@ Key implications:
    `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. 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.
+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
@@ -811,6 +834,8 @@ 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*
@@ -833,6 +858,10 @@ mermaid: |
     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
@@ -900,6 +929,25 @@ 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:
@@ -1149,6 +1197,12 @@ TestMode still uses the committed DB source. Staging remains a dev/verification
   branch/user scope. This is the normal edit/test loop.
 - `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
@@ -1322,6 +1376,75 @@ remits-cli token --path embeddable/index/50 --as-account 101   # subscriber -> v
 remits-cli token --path embeddable/index/50                    # owner      -> trunk
 ```
 
+Each answer carries a **`resolution`** block for the account the token executes as — `role`,
+`componentBranch` and its owner, `resolvedDatabaseName`, `resolvedDomainName`, `scopeAccountId`, and a
+one-sentence `summary`. Read it before opening the URL: `accountId` alone does not say whether a branch
+overlay applies or which storage namespace the page will read, and those are exactly what
+`--as-account` is being used to change.
+
+Separate branch fields, because these questions answer differently and can disagree:
+
+| Field | Answers |
+|---|---|
+| `componentBranch` | what **this token** will resolve |
+| `componentBranchSource` | `probe` (an explicit `--variant-branch`), `subscription` (the account's edge), or `trunk` |
+| `subscribedComponentBranch` | what the **account graph** says, independent of this token |
+| `componentBranchAnchored` | whether **this resolution actually reached** that subscription |
+
+A single `componentBranch` field would have reported `trunk` under `--variant-branch X`, for a token that
+resolves `X`.
+
+**Subscribing to a branch and resolving through it are different facts.** An account subscribes on an
+edge; a *request* resolves through that edge only when something named the path (`--as-account`, the
+edge's own host, an explicit `--variant-branch`). An account with no `parentId` and several upward links
+resolves trunk by design — the resolver refuses to guess a path. So this is a normal, explainable state:
+
+```
+"componentBranch": null,              // this token resolves TRUNK
+"componentBranchSource": "trunk",
+"subscribedComponentBranch": "forked", // ...but the account does subscribe
+"componentBranchAnchored": false       // ...and nothing anchored this request to it
+```
+
+Reading `componentBranch` alone there tells you the account is on trunk, which is true — and leads you to
+conclude it has no branch, which is false. If several edges carry branches, none is picked for you:
+`subscribedComponentBranch` is `null` and `subscribedComponentBranches` lists them.
+
+Under a probe, `componentOwnerAccountId` is the **nearest account on the token's resolution path that owns
+variant rows for X** — not an edge lookup, which answers `null` for the ordinary case of a variant
+committed before anything subscribes to it. `null` means no account on that path owns rows for X, and what
+that implies depends on the account, so read `summary`:
+
+- **on trunk** — the page resolves what it would without the probe; the branch is not committed yet.
+- **resolving through a subscription** — the probe **suppresses** it. `variantBranch` outranks the
+  subscription before it is consulted, so the page resolves **trunk**, not the overlays that account
+  normally gets. Drop `--variant-branch` to see the subscription.
+- **subscribed but not anchored** — it was already resolving trunk before you probed. Dropping
+  `--variant-branch` will *not* by itself show you the branch; name the path as well.
+
+The page itself then states the same facts. Its hidden `remits-session-info` line — which appears in an
+accessibility snapshot with no script — carries `Account` (what it runs as), `Addressed Account` (what
+the URL/token named), `Data Lane`, `Component Branch`, `Variant Applied`, and `Scope Account`.
+
+**`Component Branch` is the branch SELECTED; `Variant Applied` is what actually overlaid.** They are two
+fields because a branch can be selected and overlay nothing: `--variant-branch missing_branch` reports
+`Component Branch: missing_branch` while the page renders trunk components. So read `Variant Applied` —
+the `ComponentVariant` row id this page's component resolved through, or `none` — when the question is
+"did my variant apply?". That is a far sharper signal than inspecting the rendered markup for a style you
+expected.
+
+If `components status` shows staged entries that you cannot safely clear, isolate verification in an
+unused staging namespace instead of deleting someone else's cache:
+
+```bash
+remits-cli test run --test "Invoice Tests" --branch promotion-check-empty --variant-branch none --as-account 101
+remits-cli token --path embeddable/index/50 --branch promotion-check-empty --variant-branch none --as-account 101
+```
+
+Here `--branch` is only the CLI staging-cache namespace, and `--variant-branch none` keeps runtime
+resolution on production/subscription semantics. Do **not** use this pattern with `components sync` or
+`components commit`: for those commands `--branch` is the GitHub branch to reconcile.
+
 ### The SDLC is identical on a variant branch
 
 ```bash
@@ -1337,12 +1460,45 @@ remits-cli components sync           # writes ComponentVariant overlays ONLY
 
 Promotion back to trunk is a **git** operation followed by a **trunk** sync — the platform merges nothing
 for you, and merging a branch promotes its **deletions** as hard deletes. Do not improvise it: follow
-`features/subscriber-branch-promotions.md`.
+`features/subscriber-branch-promotions.md`. For a real trunk promotion with many `new_` files, use
+`remits-cli components sync --summary --timeout-ms 300000`; the platform may need longer than the default
+60 seconds to create rows, push rename/meta commits, and regenerate account metadata.
+
+### Where am I in the promotion loop?
+
+```bash
+remits-cli components promotion            # the branch you are standing on
+remits-cli components promotion --branch forked --json
+```
+
+**Run this before every promotion step and after every one.** It reports only — no git, no writes — and it
+reads the remote (which is what the platform syncs from, not your working tree). It works from either
+checkout, because it resolves the branch's owner itself. It exits non-zero while blockers remain, so treat
+that as "do not proceed".
+
+| Phase | Meaning | Next |
+|---|---|---|
+| `converged` | branch == trunk | nothing to do; this is also what a **finished** promotion looks like |
+| `ready` | ahead of trunk, current with it | promote |
+| `diverged` | behind trunk | `git merge <trunk>` into the branch, re-sync, re-read the plan |
+| `awaiting-merge-back` | fully contained in trunk, trunk has moved on | **steps 4–5 are owed** — merge trunk back and re-sync |
+
+Two things it tells you that nothing else does:
+
+- **Which commit the stored counts describe, on BOTH axes.** An overlay is stored only while a file
+  differs from trunk, so the stored set is a statement about a (branch, trunk) pair and either side moving
+  makes it stale: `[STALE — does not match the branch HEAD]` (the branch was pushed since) or
+  `[STALE — matches the branch HEAD, but trunk has moved since]`. The second is the easy one to miss —
+  measured live, a branch at its own synced HEAD reported 2 stored overlays against a real plan of 21.
+- **That a promotion is unfinished.** `awaiting-merge-back` is what a promotion that *looked* successful
+  leaves behind: trunk is correct and its tests pass, while the subscriber silently keeps resolving its
+  pre-promotion overlays — including for any fix made afterwards. **A trunk sync succeeding is step 2 of 5,
+  not completion.**
 
 ### Subscribing, unsubscribing, retiring
 
 ```bash
-remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>]
+remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]
 remits-cli components branch <name> --unsubscribe <accountId>
 remits-cli components branch <name> --retire [--force]
 ```
@@ -1362,6 +1518,11 @@ Branch administration commands act **as the account you are running from**, whic
   Without it the CLI picks the edge to the owner whose branch you are managing, then falls back to the
   account's primary edge — which may not be the one you intended. `--subscribers` prints
   `via primary|membership edge -> parent N` so you can confirm.
+- **Primary-edge subscriptions are structural.** If the selected edge is the account's `parentId` edge,
+  subscribing it makes that account and descendants resolve the branch by default even though `parentId`
+  still points at the same parent. The server refuses this write unless you pass
+  `--confirm-primary-edge`; run `--dry-run` first and prefer a membership edge for fork/pilot
+  subscriptions.
 - **Retiring is explicit.** Deleting the *git* branch does **not** remove its overlays; subscribers would
   keep resolving a branch that no longer exists. `--retire` refuses while subscribers remain unless you
   pass `--force`.
@@ -1394,7 +1555,13 @@ The analogous hazard is different, and you must still respect it:
 - **Deleting a file means "remove the component", not "stop overriding it."** To withdraw an override,
   make the file identical to trunk again — the sync then removes the variant row.
 - **Keep the branch rebased.** A branch physically carries every file, so anything trunk added *after* the
-  branch was cut looks like a deliberate deletion. A small stale gap tombstones silently.
+  branch was cut is absent from it. The sync now asks git which of those absences are real deletions
+  (comparing against the merge base) and refuses to tombstone the rest, reporting them as
+  `skipped: absent from the branch but never deleted on it`. Treat any such entry as "merge trunk in" —
+  if an older sync already stored one of those absences as a tombstone, a non-dry-run sync prunes it and a
+  dry run reports `wouldPrune: true`. The classification falls back to a conservative ratio guard when
+  GitHub's compare is unavailable or its file list comes back truncated, which the sync output says
+  explicitly.
 - **Use `components sync --dry-run` before risky variant syncs.** It reports `overridden`, `added`,
   `removed`, `unchanged`, `skipped`, and `errors` without writing rows, caching the sync SHA, or clearing
   staging. Existing overlay ids appear as `variantId`; an `unchanged` row with `pruned:true` means the
@@ -1662,8 +1829,23 @@ intended and `testAccount:false` for real provisioning. `testAccount:true` means
 account, even if the name and structure look correct.
 
 For a test rehearsal, make the opposite assertion explicit: the response should show `dataMode:'test'` and
-`testAccount:true` for created accounts (or `testUser:true` for created users). A false test flag in a
-test rehearsal means the data lane or the returned entity is not the one you intended.
+`testAccount:true` for **newly created** accounts (or `testUser:true` for created users).
+
+Read `reusedExisting` before reading anything into the flag. `account_create` is find-or-create, and a
+**test**-lane create can legitimately match a **real** account: real accounts are visible in both lanes,
+so a rehearsal for a name that already exists in prod returns `reusedExisting:true` /
+`testAccount:false` and changes nothing. That is correct reuse, not a lane error. Only
+`reusedExisting:false` with `testAccount:false` in a test rehearsal means the lane was not the one you
+intended. (The prod direction is not symmetrical: a prod-lane create never resolves onto a test
+CLIENT/PROVIDER account, so the same name can exist once per lane.)
+
+**A test-lane account does not get the `code` the prod one will.** `code` is derived from `name` and is
+globally unique, so a test-lane create with no explicit `code` is assigned `test_<code>_<parentId>`.
+A namespace resolves as `databaseName ?: platform.code ?: code`, so a rehearsal **does not prove the
+storage namespace** the real create will land in unless you set `databaseName` explicitly. Conversely,
+passing an explicit `code` in a test rehearsal opts out of the prefix, and the later prod create then
+fails on `code unique:true` — as it also will against a test account created before this rule existed.
+Check the existing account's `code` before assuming a name is free.
 
 Account/User schema `fields` are Firestore-backed extension fields. Their physical storage follows the
 same data lane as the tool call: `--data-mode test` writes under `testing/<resolvedDatabaseName>/...`, while
@@ -2326,6 +2508,23 @@ SELECT parent_id, is_primary, branch_name, database_name, domain_name, active
   FROM account_relationship WHERE account_id = ?;
 ```
 
+**This tool is lane-blind — filter the data lane yourself.** Every other record surface segments test from
+prod data for you; raw SQL does not. `object`, `event`, and `alert` carry a `test_mode` column, `user`
+carries `test_user`, and `account` carries `test_account`, and an unfiltered query returns **both lanes
+mixed** — so "who has access to this account" silently includes throwaway test users, and a row count
+silently includes test fixtures. Add the predicate explicitly:
+
+```sql
+-- prod lane only (legacy rows predate the column, so NULL counts as prod)
+SELECT id, name, status FROM object
+  WHERE account_id = ? AND (test_mode IS NULL OR test_mode = 0);
+
+-- real users of an account, excluding test fixtures
+SELECT u.id, u.username, u.enabled FROM user u
+  JOIN user_account ua ON ua.user_id = u.id
+  WHERE ua.account_id = ? AND (u.test_user IS NULL OR u.test_user = 0);
+```
+
 Prefer the purpose-built tools when one fits — they apply account scoping, data-mode segmentation, and
 resolution awareness that raw SQL does not. Reach for SQL when nothing else models the question.
 
@@ -2453,6 +2652,12 @@ It prints the resolved Account ID, User ID, current git branch, data mode, and b
 prints the same session tuple after the service/dashboard status. Pass `--base-url`, `--account-id`, and
 `--data-mode` when host or lane matters; do not infer those values from the repo directory or account name.
 
+**The reported data mode describes the next `tool` / `tools` / `token` call, not `test run`.** It falls back
+to the stored session lane, whereas `remits-cli test run` deliberately ignores that and defaults to `test`
+unless you pass `--data-mode prod` explicitly. So `whoami` can read `prod` while a test run goes to the test
+lane — which is the safe direction, but not the one you would predict from the output alone. `whoami` says
+so in its own output; when a test run genuinely needs prod data, pass the flag.
+
 ## Persistent Service, Control Center, and Agent Dispatch
 
 The current mental model is a **background remits-cli service**, not just a listener.
@@ -2605,10 +2810,10 @@ remits-cli components branches [--json]                                # branche
 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>]   # make an account resolve this branch
+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> [--names "a,b"] [--watch true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]
+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>]
@@ -2623,6 +2828,10 @@ For tests specifically:
   (*"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 "Branched Component Variants".
+- `--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
@@ -2694,6 +2903,7 @@ For tests specifically:
 | A variant Test suite fails wholesale, asserting trunk where you expect a variant | You are almost certainly running it from a **variant checkout**: `variantBranch` outranks every subscription, so the suite's own fixture accounts resolve YOUR branch. Re-run from trunk or with `--variant-branch none` before treating it as a regression. |
 | `components sync` on a branch says "No changes detected" but trunk has moved | Re-run it; a trunk sync now invalidates the branch's cached verdict. If it still skips, the branch genuinely matches trunk - check `components branch <name>` for what is actually stored. |
 | After promoting a `new_*` component to trunk, the branch still shows it as `added` | You have not re-synced the branch since the trunk sync. Merge trunk into the branch and `components sync`: the file adopts the promoted id and, if unchanged, removes its own overlay. If the branch carries BOTH `new_Foo.*` and `<id>_Foo.*`, the id file wins and the `new_` one is reported `skipped: superseded` - delete it. |
+| After promoting a standalone Prompt, the branch still shows `OVERRIDDEN prompt:<id>` with only `purpose` changed | The trunk Prompt row does not match repo metadata. Ensure the Prompt sidecar has `description` and `purpose: CUSTOM`, run a platform build that imports Prompt `purpose`, re-sync trunk, merge back, and re-sync the branch. |
 | A branch preview reports a `removed` component nobody deleted | Check whether that component has a file on **trunk**. A DB row with no trunk file is missing from every branch, so it reads as a removal everywhere (and the trunk sync tries to hard-delete it each run). Repair trunk, not the branch. |
 | `--as-account <id>` resolves trunk, or 404s | The account probably has several edges each carrying a branch, so the anchor is ambiguous and the platform refuses to guess. Name the branch with `--variant-branch <name>`, and confirm the edge with `components branch <name> --subscribers`. |
 | A branch variant is reported DRIFTED | The origin component changed after the variant was cut, so the branch is based on a stale version. `remits-cli components branch <name> --diff <id> --component-type <kind>` to compare, then reconcile the branch. |