@remits/remits-cli 0.1.137 → 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
-- L12742  Agent And Ticket Workflows
-- L16337  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.
@@ -11339,6 +11567,7 @@ function buildRepoSnapshot(entry) {
     ? path.join(localPaths.legacy.sessionsDir, legacySessionName + '.jsonl')
     : null;
   const repoFiles = [
+    { label: 'account-boot.json', path: path.join(directory, 'account-boot.json'), mode: 'json' },
     { label: 'account-info.json', path: entry.accountInfoPath || path.join(directory, 'account-info.json'), mode: 'json' },
     { label: 'account-hierarchy.json', path: path.join(directory, 'account-hierarchy.json'), mode: 'json' },
     { label: 'account-analytics.json', path: path.join(directory, 'account-analytics.json'), mode: 'json' },
@@ -16536,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');
@@ -17083,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.137",
+  "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
@@ -140,6 +151,12 @@ reference named after it.
   (`component-resolution.md`, `command-reference.md`)
 - **Host and data mode are two independent decisions.** `--base-url` picks the Remits host,
   `--data-mode` picks the data segment on it. Neither implies the other. (`command-reference.md`)
+- **Localhost being down is not a verification blocker.** `remits-cli` can talk to any reachable Remits
+  host, including the deployed production host, by passing `--base-url`. If `http://localhost:8080`
+  refuses a connection, retry the same stage/test/tool/status command against the intended deployed host
+  with the same account, branch, workspace and data-mode facts; do not stop unless no reachable host or
+  valid session exists. A deployed host can still run test-lane verification: `--base-url` selects the
+  server, while `test run` still defaults to `--data-mode test`. (`command-reference.md`)
 - **`test run` ignores the stored session data lane.** It defaults to `test` even when `whoami` shows
   the session parked on prod; production Test runs require explicit prod provenance (`--data-mode prod`)
   or Test source declaring `dataMode 'prod'` / `[dataMode:'prod']`. Check returned `dataModeSource`
@@ -163,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
@@ -216,7 +239,8 @@ remits-cli components status      # trunk or variant checkout, staging lane, wor
 remits-cli tools                  # which tools this account actually has (tools are per-account)
 ```
 
-plus the repo's `account-info.json` → `resolution` block for the account's shape.
+plus the repo's `account-boot.json` → `resolution` block for the account's shape (`account-info.json`
+only when you need full inventory detail).
 For a workflow-shaped request, rely on the automatic `remits-cli evidence` trail unless someone else needs
 a checkable verdict. Only then start `remits-cli verify start --summary "..."`, declare claims, and keep
 that envelope active through stage/test/token/sync.
@@ -228,7 +252,8 @@ non-default host).
 `~/.remits-cli/account-repos.json` (every local repo, plus the reserved `platform` entry for the core
 platform clone), `~/.remits-cli/sessions.json` (auth state and lanes), `~/.remits-cli/agents.json`
 (agents registered here), `./.remits-cli/actors/<local-agent>/tool-responses/<callId>.json` (the full
-tool payload), and the repo's `account-info.json`. `cli-state.md` maps every remaining question to its
+tool payload), the repo's `account-boot.json`, and `account-info.json` when compact context is not enough.
+`cli-state.md` maps every remaining question to its
 file, including legacy flat `.remits-cli/` fallbacks.
 Repo-local session JSONL is intentionally a bounded audit log: request payloads and ordinary response
 bodies are summarized with keys, sizes, hashes, and redaction markers. Open actor-scoped tool response
@@ -242,7 +267,7 @@ Keep support and development sessions lean:
   `mcp_component_view` / `mcp_component_grep` are fallback surfaces for agents without that checkout,
   or for confirming what the live DB has stored after you already understand the files. For a ticket
   with `implementationAccountId`, resolve that account's indexed repo first, pull the appropriate
-  branch when the checkout is clean, and inspect `account-info.json` + `components/` there.
+  branch when the checkout is clean, and inspect `account-boot.json` + relevant `components/` there.
 - Do not read entire `.remits-cli/actors/<local-agent>/sessions/*.jsonl` (or legacy flat session logs) or
   large tool response files unless you first narrow to the relevant request, endpoint, tool, or ticket.
 - Prefer targeted Firestore queries: use `documentId`, tight `filters`, narrow `fields`, and low `limit`

package/skills/remits-cli/references/account-targeting.md

@@ -23,13 +23,14 @@
 against, and where a fix belongs are answered by the account's structure — never by its name.
 
 The account model itself — types, component inheritance, primary vs membership edges, the three independent
-edge properties, the user model — is in the always-loaded `platform-overview.md` and in depth in
+edge properties, the user model — is summarized in `platform-core.md` and in depth in
 `features/account-management.md` (`mcp_get_guide`). What follows is only what changes **what you type**.
 
 ### Read the shape first
 
-`account-info.json` (in a repo) and `mcp_account_view` (remotely) both carry a `resolution` block — the one
-place these facts appear. Field-by-field detail is under **`mcp_account_view`** in `tool-reference.md`. The
+`account-boot.json` (in a repo), `account-info.json` (full local inventory), and `mcp_account_view`
+(remotely) all carry a `resolution` block — the one place these facts appear. Field-by-field detail is
+under **`mcp_account_view`** in `tool-reference.md`. The
 four that decide a CLI action:
 
 | Read | To decide |
@@ -57,7 +58,8 @@ Two more, easily confused: top-level **`componentBranches`** lists the variant b
   current before reading source or editing. Run `git fetch origin`; when the tree is clean,
   `git pull --ff-only origin <branch>`; then confirm `git log origin/<branch>..<branch>` and
   `git log <branch>..origin/<branch>` are both empty. A worktree can have an isolated staging workspace
-  and still be based on a stale commit. Then read `account-info.json` and inspect `components/` directly.
+  and still be based on a stale commit. Then read `account-boot.json` and inspect relevant `components/`
+  directly; use `account-info.json` only for full inventory detail.
 - **Inside one repo but supporting a different account**: switch to that account's indexed repo if it
   exists. For tickets, prefer `implementationAccountId` / `implementationAccountName` over the reporting
   `accountId` when choosing that repo; a subscriber or client often reports the symptom while the
@@ -84,7 +86,7 @@ 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
+- `account-boot.json`, `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.

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

@@ -42,6 +42,10 @@ Treat host selection and data mode as two separate decisions:
 
 - `--base-url` chooses the Remits host: localhost vs a deployed environment.
 - `--data-mode` chooses the data segment on that host: `test` vs `prod`.
+- A connection failure to `http://localhost:8080` only says the local back-stage app is not reachable.
+  It does **not** mean staging, testing, tokens, or investigation are blocked. If a deployed Remits host
+  is the right target, pass it explicitly with `--base-url` and keep the same account/branch/workspace
+  and `--data-mode` facts.
 
 Examples:
 
@@ -49,11 +53,20 @@ Examples:
 # Deployed prod host, but test data segment
 remits-cli tools --base-url https://your-prod-host --data-mode test
 
+# Deployed prod host, test data, staged component verification
+remits-cli components stage --workset --base-url https://your-prod-host
+remits-cli test run --test "Statement Reader Calculations" --base-url https://your-prod-host
+
 # Localhost host, but prod data segment on that localhost instance
 remits-cli tool --base-url http://localhost:8080 --name mcp_account_view --data-mode prod
 ```
 
-Do not assume `--data-mode prod` implies the deployed prod host, or that `--data-mode test` implies localhost. If host matters, read `~/.remits-cli/sessions.json` first and pass `--base-url` explicitly.
+Do not assume `--data-mode prod` implies the deployed prod host, or that `--data-mode test` implies
+localhost. Likewise, do not assume localhost is required because the current checkout is a back-stage
+repo or because a previous command used localhost. If host matters, read `~/.remits-cli/sessions.json`,
+`remits-cli whoami`, or the recent `remits-cli evidence` world blocks, then pass `--base-url` explicitly.
+Only call verification blocked after trying the intended reachable host and finding that no authenticated
+session or usable network path exists.
 
 ### Tool Execution Lifecycle
 
@@ -233,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
@@ -566,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.
@@ -172,7 +177,7 @@ wants to proceed rather than reporting the work as done.
 This is how every development task should flow:
 
 #### Step 1: Understand the Request
-Read the user's request. If you may need a repo other than the current one, read `~/.remits-cli/account-repos.json` first. Then review `account-info.json` and `README.md` to understand what components exist and how they relate. Read the source of any component you'll modify before changing it.
+Read the user's request. If you may need a repo other than the current one, read `~/.remits-cli/account-repos.json` first. Then review `account-boot.json` and `README.md` to understand the account shape and component routing inventory. Read `account-info.json` only when the compact file lacks detail you need. Read the source of any component you'll modify before changing it.
 
 **Establish a steady git baseline before the first edit.** The platform syncs from the GitHub remote, not
 from your local files, and a worktree can be stale even when its staging lane is isolated. In the checkout
@@ -191,14 +196,14 @@ that the branch is behind trunk or that overlays were computed from an old SHA,
 code. A workspace prevents staged-cache collisions; it does not make a stale branch current.
 
 **Establish the account's shape too, not just its components.** Read the `resolution` block in
-`account-info.json` (or `mcp_account_view`): the account `type` decides whether this repo is even the right
+`account-boot.json` (or `mcp_account_view`): the account `type` decides whether this repo is even the right
 place to change code, `resolution.relationships` shows whether the account has more than one parent (and
 which link carries a branch/namespace/host), and `resolvedDatabaseName` tells you where its data actually
 lands. See `account-targeting.md` and `features/account-management.md` (`mcp_get_guide`).
 
 **Also establish which world you are working in.** `remits-cli components status` reports whether the
 working tree is a **trunk** checkout or a **variant branch** checkout — which decides both what your test
-runs resolve and what a sync writes. If `account-info.json` carries a `componentBranches` section, branch
+runs resolve and what a sync writes. If `account-boot.json` carries a `componentBranches` section, branch
 variants of these components exist: editing an origin component will drift them, so check
 `remits-cli components branches` before changing shared code. See `branch-variants.md`.
 
@@ -265,7 +270,7 @@ the file. Omit the key; the platform fills it in on sync:
 ```yaml
 # components/embeddables/new_MerchantPortal.meta.yml   — no `id:` yet
 name: Merchant Portal
-summary: One-line statement of what this component is for. This is the compact text account-info.json uses first.
+summary: One-line statement of what this component is for. This is the compact text account-boot.json uses first.
 description: |
   Longer technical description with line-number references to the key logic.
 path: /page/merchant-portal        # Readers and Embeddables only
@@ -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
@@ -568,7 +577,7 @@ If the work is tied to a support ticket:
 
 Before committing, update metadata so the next session understands what changed:
 
-1. **`.meta.yml` sidecars** — Update `summary`, `description`, and `mermaid` for each modified component. `summary` is what drives the compact component description in generated `account-info.json`; `description` is the fallback when no summary is set and is capped in that file. Preserve or explicitly revise dated decision notes; do not delete the evidence the next agent needs.
+1. **`.meta.yml` sidecars** — Update `summary`, `description`, and `mermaid` for each modified component. `summary` is what drives the compact component description in generated `account-boot.json`; `description` is the fallback when no summary is set and is capped there. Preserve or explicitly revise dated decision notes; do not delete the evidence the next agent needs.
 2. **`README.md`** — If the change affects account-level capabilities or workflows.
 3. **New components** — Always fill in `.meta.yml` immediately.
 
@@ -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. |