@remits/remits-cli 0.1.138 → 0.1.139

package/README.md

@@ -33,6 +33,7 @@ git add -A
 git commit -m "sync passing changes"
 git push
 remits-cli components sync --safe             # variant branch: gated, dry-runs first, refuses surprises
+remits-cli components sync doctor             # read-only sync/promotion/staging diagnosis
 remits-cli components sync
 remits-cli components sync --branch feature_branch --dry-run
 remits-cli components sync --branch feature_branch --dry-run --summary
@@ -84,7 +85,7 @@ remits-cli install --skills --overwrite true
 - `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 non-dry-run sync, the platform clears the branch/user staging scope so staged aliases cannot keep shadowing the newly synced DB rows.
 - On trunk, `components sync` performs the full repo-to-DB reconcile. On a non-trunk branch, it writes `ComponentVariant` overlays only and may refresh branch-local `account-info.json`, `account-hierarchy.json`, and `account-configurations.json` for the subscribing account that initiated the sync. `--dry-run` is accepted only for non-trunk variant syncs and reports overrides/additions/tombstones without writing variants, caching the sync SHA, updating metadata, or clearing staging. Add `--summary` to dry-run output when you only need counts, removals/tombstones, errors, skipped items, and warnings. `--force-tombstones` is accepted only for non-trunk variant syncs and should be used only when missing trunk component files are intentional tombstone overrides.
 - `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 sync` returns the post-sync branch SHA produced by the platform. `components sync doctor` is read-only and assembles local HEAD, origin HEAD, platform last-sync SHA, staging shadow risk, promotion freshness, repository mismatch, and the next safe action when sync state is confusing. `components commit` verifies that `origin/<branch>` and local `HEAD` both match the exact synced 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` (`resolution.accountId`, then the short-lived `repoContext.accountInfoAccountId`, then the legacy top-level id — legacy files are rooted at the hierarchy ROOT, so their top-level `id` may be an ancestor), then the active session.
 - For `remits-cli tool`, read/discovery tools treat that resolved account as the **scope root**. You do not need the owning child account id for an exact document/record lookup: pass `--scope children`, or put `scope:"children"` in `--input`, and use the returned `resolvedTargetAccountId` for follow-up writes/runs. Use `--target-account-id` when you already know the exact owner, `--account-ids` for an explicit bounded owner list, and `--anchor-account-id` only to disambiguate multi-parent paths. Mutating tools still require an exact target.
@@ -100,8 +101,8 @@ remits-cli install --skills --overwrite true
 - 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.
-- `--names` is `|`-delimited and may be repeated. A comma still splits a single value for compatibility,
-  so a case name containing a comma should be passed with `|` or by repeating `--names`.
+- `--names` is `|`-delimited and may be repeated. A comma is part of the selector, so comma-bearing case
+  names can be passed literally.
 - Nested help is available before required-argument validation, including `remits-cli test run --help`, `remits-cli components sync --help`, and `remits-cli tool --help`.
 - `components sync --safe` is the recommended agent path on a variant branch. It expands to `--summary --changed-only --fail-on-errors --fail-on-removed`, resolves `--changed-since` from the branch's merge base with trunk when you did not name one (local refs only; it never runs an implicit `git fetch`), and prints the planned writes before mutating unless `--yes` is passed. On trunk there is no plan to gate, so it states what a trunk reconcile does and requires `--yes`.
 - `components sync` has fail-closed safety gates for unattended/agent use. Each exits non-zero instead of printing a wall of JSON: `--changed-only` (fail unless every planned write is a component this checkout edited), `--names-only` (print only `BUCKET type:id name` lines), `--fail-on-removed`, `--fail-on-errors`, and `--expected-removed <type:id>` (repeatable or comma-delimited; implies `--fail-on-removed`, so any removal you did not name fails). `--changed-only` also fails closed when the checkout is not a git working tree, because "git could not answer" must never be read as "nothing changed".

package/index.js

@@ -11,11 +11,11 @@
 - L4107  Skill Delivery And TOC Resolution
 - L4417  Auth And Component Staging
 - L5032  Component Summaries, Status, And Sync Gates
-- L7104  Branches, Promotion, Commit, And Test Runs
-- L9193  Tokens, Tools, Verification, And Config
-- L10620  Service Dashboard And WebSocket Listener
-- L12743  Agent And Ticket Workflows
-- L16338  Help, Auto Update, And Command Dispatch
+- L7332  Branches, Promotion, Commit, And Test Runs
+- L9421  Tokens, Tools, Verification, And Config
+- L10848  Service Dashboard And WebSocket Listener
+- L12971  Agent And Ticket Workflows
+- L16566  Help, Auto Update, And Command Dispatch
 */
 
 /*
@@ -5994,6 +5994,234 @@ async function clearComponentsCommand(flags) {
   return response;
 }
 
+async function syncDoctorComponentsCommand(rawFlags) {
+  const cwd = process.cwd();
+  const flags = Object.assign({}, rawFlags);
+  ensureLocalState(cwd);
+  const sessionContext = resolveSessionContext(cwd, flags);
+  requireAccountRepoContext(cwd, flags, 'components sync doctor', sessionContext);
+  const { session, accountId } = sessionContext;
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const branchName = flags.branch || currentBranch(cwd);
+  const workspace = resolveWorkspace(cwd, flags);
+  const dataMode = resolveDataMode(flags, session);
+  const api = buildAxios(baseUrl, session.token);
+
+  const statusResponse = await loggedPost(api, cwd, '/cli/components', {
+    token: session.token,
+    accountId,
+    branchName,
+    workspace,
+    dataMode,
+    mode: 'status'
+  }).then((r) => r.data);
+
+  if (!statusResponse.success) {
+    throw new Error(statusResponse.message || 'Staging status failed');
+  }
+
+  statusResponse.freshness = stagingFreshness({
+    head: safeGitValue(cwd, 'git rev-parse HEAD'),
+    originHead: safeGitValue(cwd, 'git rev-parse ' + shellQuote('origin/' + branchName)),
+    lastSyncedSha: statusResponse.branchContext && statusResponse.branchContext.lastSyncedSha,
+    entries: statusResponse.entries,
+    laneSummary: statusResponse.laneSummary,
+    isAncestor: (a, b) => gitIsAncestor(cwd, a, b)
+  });
+  statusResponse.repositoryCheck = repositoryCheck(cwd, statusResponse.branchContext);
+
+  let promotionResponse = null;
+  try {
+    promotionResponse = await loggedPost(api, cwd, '/cli/branches', {
+      token: session.token,
+      accountId,
+      mode: 'promotion',
+      branchName
+    }, { skipSessionLog: true }).then((r) => r.data);
+  } catch (err) {
+    const data = err && err.response && err.response.data;
+    promotionResponse = {
+      success: false,
+      message: data && data.message ? data.message : describeError(err)
+    };
+  }
+
+  const report = buildSyncDoctorReport({
+    accountId,
+    branchName,
+    workspace,
+    dataMode: statusResponse.dataMode || dataMode,
+    baseUrl: normalizeBaseUrl(baseUrl),
+    local: {
+      head: safeGitValue(cwd, 'git rev-parse HEAD'),
+      originHead: safeGitValue(cwd, 'git rev-parse ' + shellQuote('origin/' + branchName)),
+      upstream: safeGitValue(cwd, 'git rev-parse --abbrev-ref --symbolic-full-name @{u}'),
+      aheadBehind: safeGitValue(cwd, 'git rev-list --left-right --count HEAD...origin/' + shellQuote(branchName))
+    },
+    status: statusResponse,
+    promotion: promotionResponse
+  });
+
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify(report, null, 2));
+    return report;
+  }
+
+  printSessionResolutionWarning(sessionContext);
+  printResolvedBaseUrl(baseUrl);
+  printSyncDoctorReport(report);
+  return report;
+}
+
+function selectedPromotionEntry(promotion, branchName) {
+  if (!promotion || promotion.success === false) return null;
+  const entries = Array.isArray(promotion.branches) ? promotion.branches : [promotion];
+  return entries.find((entry) => String(entry && entry.branch || '') === String(branchName)) || entries[0] || null;
+}
+
+function syncDoctorStagedCount(status) {
+  const laneSummary = status && status.laneSummary || {};
+  const candidates = [laneSummary.stagedCount, laneSummary.count, laneSummary.total, status && status.stagedCount];
+  for (const value of candidates) {
+    const number = Number(value);
+    if (Number.isFinite(number)) return number;
+  }
+  return Array.isArray(status && status.entries) ? status.entries.length : 0;
+}
+
+function buildSyncDoctorReport(input) {
+  const status = input.status || {};
+  const promotion = input.promotion || null;
+  const entry = selectedPromotionEntry(promotion, input.branchName);
+  const platform = entry && entry.platform || {};
+  const git = entry && entry.git || {};
+  const branchContext = status.branchContext || {};
+  const stagedCount = syncDoctorStagedCount(status);
+  const report = {
+    success: status.success !== false,
+    accountId: input.accountId,
+    branchName: input.branchName,
+    workspace: input.workspace || null,
+    dataMode: input.dataMode,
+    host: input.baseUrl,
+    local: input.local || {},
+    world: status.variantWorld || null,
+    branchContext,
+    repositoryCheck: status.repositoryCheck || null,
+    staging: {
+      laneId: status.laneSummary && status.laneSummary.laneId || status.stagingLane || null,
+      stagedCount,
+      contentHash: status.laneSummary && status.laneSummary.contentHash || null,
+      freshness: status.freshness || null
+    },
+    platform: {
+      lastSyncedSha: branchContext.lastSyncedSha || null,
+      syncRepository: branchContext.repository || null,
+      mode: branchContextIsTrunk(branchContext) ? 'trunk' : 'variant'
+    },
+    promotion: entry ? {
+      available: true,
+      branch: entry.branch,
+      phase: entry.phase || null,
+      summary: entry.summary || null,
+      remoteBranchHeadSha: git.branchHeadSha || null,
+      remoteTrunkHeadSha: git.trunkHeadSha || null,
+      overlaysComputedFrom: platform.syncedSha || null,
+      overlayFreshness: platform.freshness || null,
+      overridden: platform.overridden,
+      branchOnly: platform.added,
+      tombstoned: platform.removed,
+      drifted: platform.drifted,
+      blockers: entry.blockers || [],
+      nextSteps: entry.nextSteps || []
+    } : {
+      available: false,
+      message: promotion && promotion.message || 'promotion status unavailable'
+    }
+  };
+  report.recommendations = syncDoctorRecommendations(report);
+  return report;
+}
+
+function syncDoctorRecommendations(report) {
+  const recs = [];
+  const repo = report.repositoryCheck;
+  if (repo && repo.matches === false) {
+    recs.push('Run sync from the checkout whose origin matches the platform repository: ' + repo.platformRepository + '.');
+  }
+  const freshness = report.staging && report.staging.freshness || {};
+  if (freshness.landedSinceHead === true) {
+    recs.push('Pull the platform-synced commit before trusting this lane: git fetch origin && git pull --ff-only, then re-stage.');
+  }
+  if (freshness.entriesBehindLastSync > 0) {
+    recs.push('Re-stage from the current checkout with `remits-cli components stage --workset`; the lane shadows rows landed after it was staged.');
+  }
+  if ((report.staging && report.staging.stagedCount || 0) > 0) {
+    recs.push('Committed-variant verification will be shadowed by this staging lane; clear it or use an unused --branch with --variant-branch before proving committed source.');
+  }
+  const promo = report.promotion || {};
+  if (promo.available && Array.isArray(promo.blockers) && promo.blockers.length) {
+    recs.push('Do not sync yet; `components promotion` reports blockers. Follow its next steps before mutating.');
+  } else if (promo.available && promo.overlayFreshness && promo.overlayFreshness !== 'current') {
+    recs.push('Stored overlays are stale relative to the branch/trunk pair. Re-read promotion, merge as instructed, then run one gated sync.');
+  }
+  if (report.platform && report.platform.mode === 'variant') {
+    recs.push('Agent landing path: push the branch, run `remits-cli components sync --safe --yes` once, then `git pull --ff-only`.');
+  } else {
+    recs.push('Trunk sync has no dry-run plan. Use `remits-cli components sync --safe --yes` only when you intend the authoritative trunk reconcile.');
+  }
+  recs.push('If a sync times out client-side, treat the result as unknown: observe with `components sync doctor` or `components promotion`; do not put `components sync` in a polling loop.');
+  return Array.from(new Set(recs));
+}
+
+function printSyncDoctorReport(report) {
+  console.log('Sync doctor');
+  console.log('Account:', report.accountId);
+  console.log('Data mode:', report.dataMode);
+  console.log('Git branch:', report.branchName);
+  console.log('Workspace:', report.workspace || 'shared default lane');
+  console.log('Mode:', report.platform.mode);
+  console.log('');
+  console.log('Local git:');
+  console.log('  HEAD:        ' + short(report.local.head));
+  console.log('  origin HEAD: ' + short(report.local.originHead));
+  if (report.local.upstream) console.log('  upstream:    ' + report.local.upstream);
+  if (report.local.aheadBehind) console.log('  HEAD...origin/' + report.branchName + ': ' + report.local.aheadBehind.trim() + ' (left=local, right=remote)');
+  console.log('');
+  console.log('Platform sync:');
+  console.log('  repository:      ' + (report.platform.syncRepository || 'unknown'));
+  console.log('  last synced SHA: ' + short(report.platform.lastSyncedSha));
+  if (report.repositoryCheck && report.repositoryCheck.matches === false) {
+    console.log('  REPOSITORY MISMATCH: checkout origin is ' + report.repositoryCheck.checkoutOrigin);
+  }
+  console.log('');
+  console.log('Staging lane:');
+  console.log('  staged entries: ' + report.staging.stagedCount);
+  if (report.staging.contentHash) console.log('  content hash:    ' + report.staging.contentHash);
+  printStagingFreshness(report.staging.freshness);
+  console.log('');
+  console.log('Promotion / variant status:');
+  if (report.promotion.available) {
+    console.log('  phase:                 ' + (report.promotion.phase || 'unknown'));
+    console.log('  remote branch HEAD:    ' + short(report.promotion.remoteBranchHeadSha));
+    console.log('  overlays computed from:' + ' ' + short(report.promotion.overlaysComputedFrom) +
+      (report.promotion.overlayFreshness ? ' [' + report.promotion.overlayFreshness + ']' : ''));
+    console.log('  overlays: overridden ' + (report.promotion.overridden ?? 'unknown') +
+      ', branch-only ' + (report.promotion.branchOnly ?? 'unknown') +
+      ', tombstoned ' + (report.promotion.tombstoned ?? 'unknown') +
+      ', drifted ' + (report.promotion.drifted ?? 'unknown'));
+    if (report.promotion.blockers && report.promotion.blockers.length) {
+      console.log('  blockers: ' + report.promotion.blockers.length);
+      report.promotion.blockers.slice(0, 8).forEach((b) => console.log('    - ' + b.code + ': ' + b.message));
+    }
+  } else {
+    console.log('  unavailable: ' + report.promotion.message);
+  }
+  console.log('');
+  console.log('Recommended next action:');
+  report.recommendations.forEach((line) => console.log('  - ' + line));
+}
+
 async function syncComponentsCommand(rawFlags) {
   const cwd = process.cwd();
   // `--safe` is a NAME for the gate combination that should be the default agent path, not a new gate.
@@ -16537,11 +16765,14 @@ function printComponentsHelp(subcommand) {
   }
   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] [--create-variant-branch] [--summary] [--json]');
+    console.log('       remits-cli components sync doctor [--json]');
     console.log('');
     console.log('On trunk this reconciles the pushed repository into live component rows.');
     console.log('On a variant branch this writes ComponentVariant overlays only.');
     console.log('--dry-run is only supported on variant branches and writes nothing.');
     console.log('--summary prints compact counts, removals/tombstones, errors, skipped items, and warnings.');
+    console.log('`sync doctor` is read-only. It assembles local HEAD, origin HEAD, platform last sync,');
+    console.log('staging shadow risk, promotion freshness, repository mismatch, and the next safe action.');
     console.log('');
     console.log('Agent safety gates (each exits non-zero instead of printing a wall of JSON):');
     console.log('  --safe                    THE RECOMMENDED PATH on a variant branch. Expands to');
@@ -17084,6 +17315,11 @@ async function main() {
     return;
   }
 
+  if (command === 'components' && subcommand === 'sync' && String(args._ && args._[2] || '').toLowerCase() === 'doctor') {
+    await syncDoctorComponentsCommand(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.138",
+  "version": "0.1.139",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,

package/skills/remits-cli/SKILL.md

@@ -92,6 +92,12 @@ reference named after it.
   "branch" or "verified"; say what was actually proven: Test pass, browser journey, corpus measurement,
   sync mutation, or ticket lifecycle state. (`component-resolution.md`, `branch-variants.md`,
   `development-loop.md`, `support-tickets.md`)
+- **Embeddable verification is browser verification.** For page, widget, form, upload, or other
+  browser-facing changes, mint a URL with `remits-cli token` and drive it with `playwright-cli`.
+  Prefer this over `curl`: `curl` can prove an HTTP response or inspect an action payload, but it does
+  not run JavaScript, Alpine, CSS/assets, redirects, cookies/session handling, uploads, iframes,
+  shadow-DOM placement, or websocket behavior. (`development-loop.md`,
+  `docs/front-stage/components/embeddable-components.md`, `docs/front-stage/features/web-browser-automation.md`)
 - **Land only from trunk or a real variant branch.** A per-agent/feature branch (`components status` says
   `FEATURE BRANCH … [subscription-fallback]`) is safe to stage and run from — it resolves the same world
   as its target — but `components commit`/`sync` refuse it. Merge into the branch it resolves and land
@@ -107,6 +113,11 @@ reference named after it.
   updating, renaming, and **hard-deleting** rows. Prefer the observable
   `git commit → git push → components sync → git pull`. On trunk it refuses before any git write unless
   you pass `--yes`. (`component-integrity.md`)
+- **Do not hand-roll sync watchers.** A sync is a write; an observation loop must never start a fresh
+  `components sync`. Use `remits-cli components sync doctor` and `components promotion` to read sync /
+  overlay state. If a sync times out client-side, the result is unknown, not failed; observe before any
+  retry. Do not use `setsid`, `nohup`, `disown`, `tmux`, or shell-specific detach tricks to make sync
+  lifecycle work. (`development-loop.md`, `branch-variants.md`)
 - **After anyone lands, ask whether your lane is stale: `remits-cli components status`.** A landing clears
   only the lander's lane; yours keeps shadowing their new rows with content staged from the old base.
   `LANDED SINCE YOUR BASE` / `STALE OVERLAY` mean pull, re-stage, then verify — a pass against a stale
@@ -169,6 +180,12 @@ reference named after it.
   component (preferred, because it becomes regression protection) or a browser flow through
   `remits-cli token`. "Just do it" and "that's fine, commit it" are not evidence. If you genuinely
   cannot verify, say what you would need and ask. (`development-loop.md`)
+- **Match the proof to the claim.** A mocked Test is a seam proof; a sync packet is durable source
+  movement; a token/browser run is journey proof; a corpus consistency report is repeatability proof. If
+  the request says "same file twice", "repeatability", "consistency", "same answer", or "model variance",
+  start with a corpus/evaluation or other repeated live measurement under an explicit AI budget; mocked
+  seam suites are guardrails, not acceptance. (`development-loop.md`, `component-resolution.md`,
+  `docs/front-stage/components/test-components.md`)
 - **`remits-cli evidence` answers "what have I actually run, and in which world?"** Every stage, test,
   token, tool and sync appends one world-stamped line automatically, per actor. Nothing to start,
   nothing to satisfy. Read it before you re-run something, and quote it when you report what you

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

@@ -12,6 +12,7 @@
   - [Which world does your working tree resolve? (read this before you run anything)](#which-world-does-your-working-tree-resolve-read-this-before-you-run-anything)
   - [Two levers, two different questions](#two-levers-two-different-questions)
   - [The SDLC is identical on a variant branch](#the-sdlc-is-identical-on-a-variant-branch)
+  - [Long-running variant sync](#long-running-variant-sync)
   - [Where am I in the promotion loop?](#where-am-i-in-the-promotion-loop)
   - [Subscribing, unsubscribing, retiring](#subscribing-unsubscribing-retiring)
   - [Danger profile on a variant branch (different, not absent)](#danger-profile-on-a-variant-branch-different-not-absent)
@@ -237,7 +238,7 @@ remits-cli test run --test "Invoice Tests"                    # the feature_bran
 remits-cli test run --test "Invoice Tests" --as-account 101   # ...as the real subscriber
 git add -A && git commit -m "..." && git push origin feature_branch
 remits-cli components sync --dry-run # inspect overrides/additions/tombstones without writes
-remits-cli components sync           # writes ComponentVariant overlays ONLY
+remits-cli components sync --safe --yes  # agent/noninteractive: writes ComponentVariant overlays ONLY
 ```
 
 `components stage` validates changed runtime-compiled source through the active branch/workspace lane,
@@ -252,6 +253,41 @@ for you, and merging a branch promotes its **deletions** as hard deletes. Do not
 `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.
 
+### Long-running variant sync
+
+A variant sync writes durable `ComponentVariant` overlays only. The proof that subscribers can resolve the
+new committed branch source is the overlay set's computed SHA, not the fact that your local process once
+started a sync.
+
+Use this shape for agent landings:
+
+```bash
+git push origin <branch>
+remits-cli components sync --safe --yes
+git pull --ff-only origin <branch>
+remits-cli components sync doctor
+remits-cli components promotion --branch <branch> --no-fail
+```
+
+`--safe --yes` skips the interactive prompt after the safe dry-run gates pass; it does not skip the gates.
+If the client times out, the result is **unknown**. Do not immediately re-run `components sync`, and never
+write a polling loop that invokes it. Observe with `components sync doctor` and
+`components promotion --branch <branch> --no-fail`; a read loop may inspect, but only one command should
+start the write.
+
+Read the promotion report precisely:
+
+- `branch HEAD` in the git section says what the remote branch currently points at.
+- `overlays computed from` in the platform section says what subscribers resolve right now.
+- A cached status or a local process exit is not proof that overlays advanced.
+- Immediately after a sync, metadata refresh and compile caches can lag by a moment; committed-variant
+  verification still has to clear or avoid staged overlays first.
+
+Host and account provenance are part of this proof. A subscriber can be subscribed to a branch that
+currently stores zero overlays, which means the selected branch resolves trunk behavior. Before comparing
+uploads or browser runs, read the token/test/tool world: host, execution account, component branch,
+`variantBranchSource`, data lane, and resolved database.
+
 ### Where am I in the promotion loop?
 
 ```bash

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

@@ -246,6 +246,7 @@ remits-cli components lanes [--json]                         # every indexed sta
 remits-cli components entries --lane-id <id> [--json|--verbose]  # authoritative staged files for one lane
 remits-cli components clear [--branch <name>] [--component-type <type>] [--component-id <id>] [--all] [--json|--verbose]   # id alone scopes to one component when unambiguous (ids are type-local; add --component-type if the same id is staged in multiple families); no filter clears the whole branch scope; --all forces the full wipe
 remits-cli components sync [--safe [--yes]] [--branch <name>] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--create-variant-branch] [--summary] [--changed-only [--changed-since <ref>]]   # gated; on trunk = full repo->DB reconcile, on a variant branch = ComponentVariant overlays only
+remits-cli components sync doctor [--branch <name>] [--json]     # read-only: local/remote/platform sync facts, staging shadow risk, promotion freshness, recommended next action
 remits-cli components commit [--yes] [--safe] [--allow-shared-branch] [--create-variant-branch] [--message|-m "msg"] [--data-mode test|prod] [--force-tombstones] [--json [--summary]]   # phase 1 merge-stages + compile-validates changed source (never reconciles the lane); on TRUNK refuses before any git write unless --yes; --safe gates variant sync writes
 remits-cli components branches [--json]                                # branches carrying committed variants, with counts + drift
 remits-cli components branch <name> [--json]                           # one branch: owner account, overridden / added / removed, drift flags, subscribers
@@ -579,6 +580,10 @@ For tests specifically:
 - `--summary` on `components sync` prints compact counts plus named updated (with the fields that
   changed), renamed, skipped, removal/tombstone, error, and gate details instead of the full payload. A
   trunk sync reports an untouched component under `unchanged`, not `updated`.
+- `components sync doctor` does not mutate. Use it when a sync timed out, status/promotion disagree, or
+  you need to know whether staged entries would shadow committed-variant verification. It prints local
+  `HEAD`, `origin/<branch>`, platform last-sync SHA, overlay freshness, repository mismatch, and a
+  recommended next action.
 - `--json` on `components stage`, `components sync`, `components commit`, and `tool` prints one
   parseable JSON document to stdout. Safety banners and prose go to stderr, and sync safety-gate failures
   are reported inside `gateViolations` with a non-zero exit code instead of appending prose after the JSON.

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

@@ -90,6 +90,7 @@ every live component present at its real id, and nothing extra.
 | `remits-cli components stage` (alias: deprecated `push`) | **Redis staging cache only.** Never mutates the DB or git. The safe iteration surface. A plain stage or `--workset` RECONCILES the lane (entries outside the manifest are dropped); `--changed-only` merges. | none for the DB; a lane you share with another agent is reconciled by the first two |
 | `remits-cli components status` | Reads this lane's staging scope (account/user/branch/workspace) and branch resolution, and lists every other lane on the branch. | none |
 | `remits-cli components clear` | Clears THIS lane's staging cache without changing DB or git. Never touches another workspace lane. | none |
+| `remits-cli components sync doctor` | Reads local git, platform status, staging freshness, repository match, and promotion/overlay freshness. It is the safe diagnostic when sync state is confusing. | none |
 | `remits-cli components sync` **on trunk** | **Server-side git→DB reconcile of the whole account** (create/update/**delete**/rename). Reads the pushed remote; ignores local files. | **high** |
 | `remits-cli components sync` **on a variant branch** | Writes `ComponentVariant` overlays for that branch only. Never touches trunk rows or the account's trunk branch. When the checkout identifies a subscribing account, the branch-local `account-info.json` is refreshed for that subscriber; `--dry-run` reports the plan without writes. | medium (a missing file becomes a **tombstone** that hides the component from subscribers) |
 | `remits-cli components commit` | **One shot:** changed-source compile validation (a `--changed-only` MERGE stage, so it never reconciles the lane) + `git add -A` + commit + `git push` + **`components sync`** + `git pull --ff-only`. Blindly stages the *entire* working tree (including any drift) and reconciles it into prod. Inherits the danger of whichever sync mode the branch selects. | **highest on trunk** |

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

@@ -64,6 +64,17 @@ source-layer facts the command observed. A staged test packet is proof of the st
 is proof of a source transition; a token packet is proof of the browser token's resolution tuple. Those
 are not interchangeable.
 
+Use proof words narrowly:
+
+| Evidence | What it proves | What it does NOT prove |
+|---|---|---|
+| `components stage --workset` | The platform accepted the staged workset and compile-checked changed runtime source | Any committed component changed, or any user journey works |
+| `test run` with staged entries | The selected Test passed against this staging lane/world | The committed variant/trunk source passes |
+| `components sync` / sync packet | Durable source moved from the git remote into trunk rows or variant overlays | Browser/upload behavior, or repeated live AI consistency |
+| `components promotion` / `sync doctor` | Which remote SHA and overlay SHA the platform reports now | That a workflow was exercised after the overlay advanced |
+| `token` / browser flow | The browser entry point resolved a host/account/lane/source tuple and the journey worked there | Persisted document fields are stable or equal across repeated runs |
+| `corpus consistency` / repeated live measurement | The same artifact's recorded metrics were stable or unstable across runs in that world | A mocked seam suite caught all customer-facing variance |
+
 Use `remits-cli verify report` before summarizing the work. It will say when the evidence only covered
 staged source, when committed variant/trunk proof is missing, when the manifest world does not match the
 packet world, or when later packet facts made an earlier proof stale. Packets carry a lane content hash,

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

@@ -159,6 +159,11 @@ Two ways to prove it:
 Use a Test when the behavior can be asserted programmatically, a browser when the change is visual.
 Often both.
 
+For Embeddables, prefer `playwright-cli` over `curl`. A `curl` request can confirm the server returned
+something or expose a JSON/action payload, but it is not evidence that the user-facing page works:
+JavaScript, Alpine initialization, assets, cookies/session state, redirects, file controls, iframe/embed
+placement, and websocket updates all require a browser.
+
 **Never skip verification.** "Just do it" and "that's fine, commit it" are not evidence. If you genuinely
 cannot verify — no Test component, no relevant embeddable — say what you would need and ask how the user
 wants to proceed rather than reporting the work as done.
@@ -515,6 +520,10 @@ playwright-cli fill "#amount" "500.00"
 playwright-cli eval "() => document.querySelector('.total-amount').textContent"
 ```
 
+Use this browser path for Embeddable acceptance. `curl` is acceptable for narrow diagnostics such as
+checking an HTTP status or inspecting a server-rendered payload, but it does not prove the page initializes
+or behaves correctly in a browser.
+
 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
@@ -630,12 +639,17 @@ 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
-# On a VARIANT branch — the recommended path. Dry-runs first and refuses a surprising plan.
+# On a VARIANT branch in an agent/noninteractive session — dry-runs first, refuses surprises,
+# and skips only the confirmation prompt, not the gates.
+remits-cli components sync --safe --yes
+git pull --ff-only origin <branch>
+
+# On a VARIANT branch in a human interactive shell — same gates, then asks before writing.
 remits-cli components sync --safe
 git pull --ff-only origin <branch>
 
 # On TRUNK — there is no plan to gate, so --safe explains what a trunk reconcile does and needs --yes.
-remits-cli components sync
+remits-cli components sync --safe --yes
 git pull --ff-only origin <branch>
 ```
 
@@ -655,14 +669,29 @@ remits-cli components sync --safe --expected-removed action:50
 
 `--force-tombstones` stays explicit and human-owned. Never pass it to get past a refusal.
 
+If sync state is confusing, use the read-only diagnostic instead of building shell loops:
+
+```bash
+remits-cli components sync doctor
+remits-cli components promotion --branch <branch> --no-fail
+```
+
+`components sync doctor` assembles local `HEAD`, `origin/<branch>`, the platform's last synced SHA,
+promotion freshness, staging shadow risk, repository mismatch, and a recommended next action. A client
+timeout does **not** prove the sync failed; it means the result is unknown. Observe before retrying.
+Never put `components sync` inside a polling loop, and do not use shell detach tricks (`setsid`, `nohup`,
+`disown`, `tmux`, ...). A loop may read status/promotion/doctor; it must never start writes.
+
 ##### Verifying the COMMITTED variant, not your staging
 
 After a sync, staged entries still win for CLI-scoped runs, so a test that passes may be testing your
-staging rather than what you just committed. Clear the lane first:
+staging rather than what you just committed. Clear the lane first, then verify the subscriber/variant
+world explicitly:
 
 ```bash
 remits-cli components clear --all
 remits-cli test run --test <id-or-name> --as-account <subscriber-id>
+remits-cli components sync doctor
 ```
 
 `remits-cli components sync` is the authoritative platform-sync step. It does not perform local git operations,

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

@@ -28,6 +28,7 @@
 | Tool parameters rejected | Tool schemas may be cached. Run `remits-cli tools` to refresh `.remits-cli/shared/tools/tools.json` with latest schemas. |
 | Tool response missing | Run `remits-cli doctor local-state`, then check `./.remits-cli/actors/<local-agent>/tool-responses/` and any legacy flat `./.remits-cli/tool-responses/` fallback it reports. |
 | Long-running tool times out | For `mcp_run_action`/`mcp_run_agent`, use the tool's own `executionMode:"async"` and poll with a `controlAction:"status"` call (see `command-reference.md` → *Tool Execution Lifecycle*). For other long tools without their own async, use `remits-cli tool --async true` and poll `remits-cli tool status --call-id <callId>`. `--timeout-ms` only adjusts the per-request HTTP timeout; it is not a substitute for async. |
+| `components sync` timed out, or you are unsure whether overlays advanced | Treat the result as **unknown**, not failed. Run `remits-cli components sync doctor` and `remits-cli components promotion --branch <branch> --no-fail`. Do not put `components sync` in a polling loop and do not use shell detach tricks; observation may poll, writes may not. |
 | Need to continue tracking a long Action or Agent after terminal disconnect | Read `./.remits-cli/actors/<local-agent>/tool-responses/<callId>.json` for the returned `actionRunId`/`agentRunId`/`sessionId`/`threadGroupingId` (or the legacy flat fallback if `doctor local-state` reports it there). Re-poll the run with a `controlAction:"status"` call carrying that `actionRunId`/`agentRunId`, or inspect the agent session via `mcp_ai_session_search` with the `sessionId`. |
 | 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 (trunk, or the account's subscribed variant). `commit` to make it durable. See `component-resolution.md`. |
 | Need to know an account's shape (role, type, parents, namespace, branch, host/login routes) | Read `resolution` — from the repo's `account-info.json`, or `mcp_account_user_admin` `action:'account'` (cheap), or `mcp_account_view` (full inventory): `role`/`summary`, `type`, `resolvedDatabaseName`, `domainName`/`resolvedDomainName`, `authPath`/`targetPath`, `relationships`, `componentBranch`, plus top-level `componentBranches`. Never infer structure from the account's name. |