@remits/remits-cli 0.1.164 → 0.1.166

package/README.md

@@ -101,7 +101,8 @@ remits-cli install --skills --overwrite true
 - Auth sessions are stored per `accountId + dataMode + baseUrl`, so the same account can stay authenticated against both localhost and production without overwriting the other session.
 - Active verification envelopes are scoped per `baseUrl + accountId + branch + workspace + dataMode`, so a localhost envelope does not silently capture evidence from a production command. Pass `--verify-envelope <id>` for an intentional cross-context attachment.
 - `--base-url` and `--data-mode` are independent. `--base-url` chooses the Remits host (`http://localhost:8080` vs deployed prod), while `--data-mode` chooses the data segment on that host (`test` vs `prod`). Do not assume `--data-mode prod` means the deployed prod host, or that `--data-mode test` means localhost.
-- `remits-cli start` scans the machine for `account-info.json` files and rebuilds `~/.remits-cli/account-repos.json` before bringing up the background service.
+- `remits-cli start` scans for `account-info.json` files and updates `~/.remits-cli/account-repos.json` before bringing up the background service. While running, it rescans every five minutes using asynchronous directory reads, then reports the refreshed inventory to the platform. Repos cloned outside the CLI are discovered without a restart or a command run inside them. Both scans use `REMITS_CLI_SCAN_ROOTS` (default: the home directory), the same depth limit and directory exclusions. For immediate discovery, use `remits-cli agent repos --rescan` or **Rescan Account Repos** in the control center.
+- Scans preserve manually selected repository directories and record competing checkouts as ambiguity. `remits-cli agent repos --account-id <id> --forget` suppresses rediscovery until an explicit registration (`--directory <path>`) or a CLI command run from that account repo restores it.
 - Front-stage guides are **not** bundled with the CLI npm package. For account-work commands (`components`, `test`, `token`, `tools`, `tool`) and on `auth`, `remits-cli` downloads the latest guides from the authenticated `/cli/guides` endpoint and writes them into the current account repo: root `platform-overview.md` / `development-guide.md`, `guides/*.md`, `guides/features/*.md`, and the agent-guidance files `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` (from `docs/front-stage/remits-components-zip-readme.md`).
 - Guide sync requires authentication. If no valid session exists and the terminal is interactive, the CLI auto-authenticates first; in non-interactive contexts (CI, agent sandboxes) it skips silently so guides are only ever delivered to users who can authenticate to the platform.
 - On every command, `remits-cli` refreshes the installed remits-cli `SKILL.md` and reference files for `claude`, `codex`, `gemini`, and `antigravity` so local agents stay on the latest packaged instructions.

package/index.js

@@ -4,18 +4,18 @@
 ## Table of Contents
 
 - L22  Runtime Bootstrap And Shared State
-- L125  Sessions, Account Resolution, And Production Guards
-- L631  Local State, Workspaces, And Verification Evidence
-- L2669  Account Repos, Guide Sync, And Platform Repo
-- L3509  Component Discovery And HTTP Logging
-- L4277  Skill Delivery And TOC Resolution
-- L4592  Auth And Component Staging
-- L5224  Component Summaries, Status, And Sync Gates
-- L7548  Branches, Promotion, Commit, And Test Runs
-- L9802  Tokens, Tools, Verification, And Config
-- L11319  Service Dashboard And WebSocket Listener
-- L13829  Agent And Ticket Workflows
-- L18090  Help, Auto Update, And Command Dispatch
+- L126  Sessions, Account Resolution, And Production Guards
+- L632  Local State, Workspaces, And Verification Evidence
+- L2670  Account Repos, Guide Sync, And Platform Repo
+- L3569  Component Discovery And HTTP Logging
+- L4339  Skill Delivery And TOC Resolution
+- L4654  Auth And Component Staging
+- L5286  Component Summaries, Status, And Sync Gates
+- L7610  Branches, Promotion, Commit, And Test Runs
+- L9873  Tokens, Tools, Verification, And Config
+- L11390  Service Dashboard And WebSocket Listener
+- L13900  Agent And Ticket Workflows
+- L18202  Help, Auto Update, And Command Dispatch
 */
 
 /*
@@ -75,6 +75,7 @@ const DASHBOARD_HOST = '127.0.0.1';
 const DEFAULT_DASHBOARD_PORT = Number(process.env.REMITS_CLI_DASHBOARD_PORT || 8787);
 const DEFAULT_SCAN_MAX_DEPTH = Number(process.env.REMITS_CLI_SCAN_MAX_DEPTH || 8);
 const SERVICE_MAINTENANCE_INTERVAL_MS = Number(process.env.REMITS_CLI_SERVICE_MAINTENANCE_INTERVAL_MS || 15000);
+const ACCOUNT_REPO_RESCAN_INTERVAL_MS = 5 * 60 * 1000;
 const WEBSOCKET_RECONNECT_DELAY_MS = Number(process.env.REMITS_CLI_WEBSOCKET_RECONNECT_DELAY_MS || 5000);
 const WEBSOCKET_HEARTBEAT_MS = Number(process.env.REMITS_CLI_WEBSOCKET_HEARTBEAT_MS || 10000);
 const WEBSOCKET_CONNECTION_TIMEOUT_MS = Number(process.env.REMITS_CLI_WEBSOCKET_CONNECTION_TIMEOUT_MS || 15000);
@@ -899,7 +900,7 @@ function localStateWarnings(cwd, flags = {}) {
       .sort((a, b) => Date.parse(b.updatedAt || 0) - Date.parse(a.updatedAt || 0));
     const shown = recent.slice(0, 3).map((a) => a.actor);
     const stale = report.foreignActors.length - recent.length;
-    const setOne = 'Name this one with --actor <name> (or REMITS_AGENT_ID) if another agent shares this checkout.';
+    const setOne = 'Name this one with --local-agent <name> (or REMITS_LOCAL_AGENT_ID) if another agent shares this checkout; REMITS_AGENT_ID also declares agent identity to the platform.';
     const pruneHint = stale
       ? stale + ' spent actor dir(s) (idle, or left behind by finished processes) can be cleared with `remits-cli doctor local-state --prune-actors`.'
       : '';
@@ -3253,7 +3254,8 @@ function countAccountRepos(index) {
  */
 function mergeAccountRepoEntries(entries, options = {}) {
   const nextIndex = options.existingIndex ? { ...options.existingIndex } : {};
-  const rank = (entry) => (isAccountCheckout(entry.directory) ? 2 : 0) + (entry.source === 'cwd' ? 1 : 0);
+  const sourceRank = (entry) => entry.source === 'manual' ? 2 : (entry.source === 'cwd' ? 1 : 0);
+  const rank = (entry) => (isAccountCheckout(entry.directory) ? 3 : 0) + sourceRank(entry);
 
   for (const entry of entries) {
     if (!entry || !entry.accountId || !entry.directory) {
@@ -3261,8 +3263,15 @@ function mergeAccountRepoEntries(entries, options = {}) {
     }
     const key = String(entry.accountId);
     const current = nextIndex[key];
+    // Forget is an explicit opt-out, not a temporary absence until the next service scan.
+    if (current && current.source === 'forgotten' && entry.source === 'scan') continue;
     if (!current || !current.directory || current.directory === entry.directory) {
-      nextIndex[key] = { ...entry, ambiguousWith: (current && current.ambiguousWith) || [] };
+      nextIndex[key] = {
+        ...entry,
+        source: current && current.directory === entry.directory && sourceRank(current) > sourceRank(entry)
+          ? current.source : entry.source,
+        ambiguousWith: (current && current.ambiguousWith) || []
+      };
       continue;
     }
 
@@ -3305,19 +3314,17 @@ function defaultAccountScanRoots() {
   return [home].filter((dir) => fs.existsSync(dir));
 }
 
-function walkForAccountInfo(dir, depth, matches, visited, platformMatches) {
+// Share traversal rules between the synchronous command path and asynchronous service scans.
+// The driver supplies directory entries so the service never blocks its WebSocket on readdirSync.
+function* accountRepoScanSteps(dir, depth, matches, visited, platformMatches) {
   const resolvedDir = path.resolve(dir);
   if (visited.has(resolvedDir)) {
     return;
   }
   visited.add(resolvedDir);
 
-  let entries;
-  try {
-    entries = fs.readdirSync(resolvedDir, { withFileTypes: true });
-  } catch (_) {
-    return;
-  }
+  const entries = yield resolvedDir;
+  if (!entries) return;
 
   const names = new Set(entries.map((entry) => entry.name));
   for (const entry of entries) {
@@ -3347,7 +3354,17 @@ function walkForAccountInfo(dir, depth, matches, visited, platformMatches) {
     if (entry.name.startsWith('.') && entry.name !== '.config') {
       continue;
     }
-    walkForAccountInfo(path.join(resolvedDir, entry.name), depth + 1, matches, visited, platformMatches);
+    yield* accountRepoScanSteps(path.join(resolvedDir, entry.name), depth + 1, matches, visited, platformMatches);
+  }
+}
+
+function walkForAccountInfo(dir, depth, matches, visited, platformMatches) {
+  const steps = accountRepoScanSteps(dir, depth, matches, visited, platformMatches);
+  let step = steps.next();
+  while (!step.done) {
+    let entries = null;
+    try { entries = fs.readdirSync(step.value, { withFileTypes: true }); } catch (_) { /* unreadable */ }
+    step = steps.next(entries);
   }
 }
 
@@ -3359,7 +3376,29 @@ function discoverAccountRepos() {
   for (const root of roots) {
     walkForAccountInfo(root, 0, matches, visited, platformMatches);
   }
+  return reconcileDiscoveredAccountRepos(roots, matches, platformMatches);
+}
+
+async function discoverAccountReposInBackground() {
+  const matches = [];
+  const platformMatches = [];
+  const visited = new Set();
+  const roots = defaultAccountScanRoots();
+  for (const root of roots) {
+    const steps = accountRepoScanSteps(root, 0, matches, visited, platformMatches);
+    let step = steps.next();
+    while (!step.done) {
+      let entries = null;
+      try { entries = await fs.promises.readdir(step.value, { withFileTypes: true }); } catch (_) { /* unreadable */ }
+      step = steps.next(entries);
+    }
+  }
+  // Read the latest index only at reconciliation: CLI commands may register a repo during the scan.
+  // Background maintenance discovers existing files; it must never clone or pull repositories.
+  return reconcileDiscoveredAccountRepos(roots, matches, platformMatches, { background: true });
+}
 
+function reconcileDiscoveredAccountRepos(roots, matches, platformMatches, options = {}) {
   const entries = [];
   for (const file of matches) {
     try {
@@ -3380,7 +3419,7 @@ function discoverAccountRepos() {
     const found = platformMatches.find(looksLikePlatformRepo);
     if (found) {
       setPlatformRepoEntry(found, 'scan');
-    } else {
+    } else if (!options.background) {
       try { ensurePlatformRepoLocal({ allowClone: true }); } catch (_) { /* best-effort */ }
     }
   }
@@ -3395,6 +3434,27 @@ function discoverAccountRepos() {
   };
 }
 
+let accountRepoDiscoveryInFlight = null;
+let lastAccountRepoDiscoveryAttemptAt = 0;
+
+function refreshAccountReposIfDue(now = Date.now()) {
+  if (accountRepoDiscoveryInFlight) return accountRepoDiscoveryInFlight;
+  const lastScanAt = Date.parse(runtimeState.discovery.scannedAt || '') || 0;
+  if (now - Math.max(lastScanAt, lastAccountRepoDiscoveryAttemptAt) < ACCOUNT_REPO_RESCAN_INTERVAL_MS) return;
+  lastAccountRepoDiscoveryAttemptAt = now;
+  accountRepoDiscoveryInFlight = discoverAccountReposInBackground()
+    .then((summary) => {
+      recordDiscoverySummary(summary);
+      // Publish the refreshed inventory on the next maintenance tick, even if presence isn't due yet.
+      for (const managedClient of managedClients) managedClient.lastPresenceAt = 0;
+    })
+    .catch((err) => {
+      appendGlobalActivityLog('listener', 'repos.discovery.failed', { error: describeError(err) }, 'error');
+    })
+    .finally(() => { accountRepoDiscoveryInFlight = null; });
+  return accountRepoDiscoveryInFlight;
+}
+
 function resolvePreferredAccountId(cwd, flags, session) {
   // Explicit --account-id wins over the repo's account-info.json so users can
   // target a child account (e.g. a customer) from a parent-account repo.
@@ -3669,7 +3729,9 @@ function collectComponents(cwd) {
         component.html = content;
       } else if (type === 'htmltemplate' && ext === 'json') {
         component.previewData = content;
-      } else if (type === 'tool' && ext === 'json') {
+      } else if ((type === 'tool' || type === 'action') && ext === 'json') {
+        // An Action's .json sidecar is its input schema (manual-run form and x-remits-operations), exactly as
+        // repository sync maps it; staging used to drop it, so a staged declaration silently did not apply.
         component.inputSchema = content;
       } else if (type === 'i18n' && ext === 'json') {
         component.messages = content;
@@ -3850,7 +3912,7 @@ function componentPathInfo(cwd, filePath) {
   else if (type === 'embeddable' && ext === 'js') field = 'javascript';
   else if (type === 'htmltemplate' && ext === 'html') field = 'html';
   else if (type === 'htmltemplate' && ext === 'json') field = 'previewData';
-  else if (type === 'tool' && ext === 'json') field = 'inputSchema';
+  else if ((type === 'tool' || type === 'action') && ext === 'json') field = 'inputSchema';
   else if (type === 'i18n' && ext === 'json') field = 'messages';
   else if (type === 'schema' && ext === 'json') field = 'schema';
 
@@ -9130,10 +9192,18 @@ async function waitForToolStatus(api, cwd, options) {
 
 // One compact progress line for a streamed TestSuite frame: a finished case, or the suite roll-up.
 function testSuiteProgressLine(payload = {}) {
+  if (payload.event === 'case_started') {
+    return '[ws] running ' + (payload.activeCases || []).map((c) =>
+      c.name + (c.traceId ? ' [trace ' + c.traceId + ']' : '')).join(', ');
+  }
   if (payload.total != null || Array.isArray(payload.tests)) {
     const total = payload.total != null ? payload.total : (payload.tests || []).length;
     const passed = payload.passed != null ? payload.passed : (payload.tests || []).filter((t) => t && t.passed).length;
-    return '[ws] ' + (payload.testName || 'suite') + ': ' + passed + '/' + total + ' passed';
+    const active = (payload.activeCases || []).map((c) => c.name + (c.traceId ? ' [trace ' + c.traceId + ']' : ''));
+    const queued = (payload.shards || []).filter((s) => s.status === 'queued').length;
+    return '[ws] ' + (payload.testName || 'suite') + ': ' + passed + '/' + total + ' passed' +
+      (payload.status ? ' (' + payload.status + ')' : '') +
+      (active.length ? '; running: ' + active.join(', ') : '') + (queued ? '; ' + queued + ' workers queued' : '');
   }
   const mark = payload.passed === false ? 'FAIL' : 'pass';
   const detail = payload.outcome && payload.outcome !== 'passed' ? ' [' + payload.outcome + ']' : '';
@@ -9172,7 +9242,7 @@ function watchWebsocket(baseUrl, topicId, taskId, options = {}) {
           if (payload.taskId && followed.length && !followed.includes(payload.taskId)) {
             return;
           }
-          if (payload.tests || payload.name || payload.total != null) {
+          if (payload.tests || payload.name || payload.total != null || payload.event === 'case_started') {
             // Progress, not the payload. This used to print the whole suite result — every case, every
             // stacktrace — as one enormous line immediately before the readable summary said the same thing,
             // which buried the run world, the outcomes and the pivots an agent actually reads. --verbose still
@@ -9345,6 +9415,7 @@ async function testCommand(flags) {
     workspace,
     dataMode,
     dataModeSource,
+    caseConcurrency: flags.parallel !== undefined && runOptions.parallel === 1 ? 1 : undefined,
     testId: /^\d+$/.test(String(testRef)) ? Number(testRef) : undefined,
     testName: /^\d+$/.test(String(testRef)) ? undefined : String(testRef),
     tests: names
@@ -15900,6 +15971,7 @@ async function ticketCommand(flags, subcommand) {
     requiresRepositoryWork: firstDefined(flags['repo-work'], flags['requires-repository-work']),
     tags: flags.tags ? String(flags.tags).split(',').map((v) => v.trim()).filter(Boolean) : undefined,
     label: flags.label,
+    ...(action === 'artifact' ? ticketArtifactFields(flags) : {}),
     url: flags.url,
     body: flags.body,
     role: flags.role,
@@ -16645,7 +16717,7 @@ function printTicketHelp() {
   console.log('  tag --tags a,b                        Mark it, for a HUMAN reading the queue. When the');
   console.log('      tickets genuinely share a cause, use `relate` instead or as well: the platform reads');
   console.log('      that one, and a tag it cannot read will not stop a cluster being worked N times.');
-  console.log('  artifact --type TYPE --label "..." [--url U | --content "..."]');
+  console.log('  artifact --type TYPE --label "..." (--content "..." | --file PATH | --url U) [--filename F] [--content-type T]');
   console.log('      Attach evidence — a log, a query result, a repro. Better than pasting it into a');
   console.log('      worklog summary, where it is neither typed nor retrievable.');
   console.log('  note --message "..."                  An INTERNAL note. The next worker and a reviewer');
@@ -16690,6 +16762,44 @@ function printTicketHelp() {
  * One helper so the lease, the claim and the registration cannot describe this process three ways —
  * the same reason the platform builds the tuple in exactly one class (AgentRunContext).
  */
+/**
+ * The evidence half of `ticket artifact`. Bytes always travel as `contentBase64`: it is the one form every
+ * deployed platform accepts (JSON cannot carry a byte[], and older platforms ignored a `content` string), so
+ * `--content "text"` and `--file path` behave the same against every host. The help promised `--type` and
+ * `--content` for a long time while neither was sent, and every artifact was refused as `type [null]`; the
+ * refusals here name the missing flag before anything reaches the platform.
+ */
+function ticketArtifactFields(flags = {}, readFile = (p) => fs.readFileSync(p)) {
+  const text = (v) => (typeof v === 'string' && v.trim() ? v : undefined);
+  const type = text(flags.type);
+  if (!type) {
+    throw new Error('ticket artifact needs --type (screenshot, pdf, trace, video, log, test_result, link or other).');
+  }
+  if (!text(flags.label)) {
+    throw new Error('ticket artifact needs --label "...".');
+  }
+  const fields = { type, filename: text(flags.filename), contentType: text(flags['content-type'] || flags.contentType) };
+  const filePath = text(flags.file);
+  const content = typeof flags.content === 'string' ? flags.content : undefined;
+  if (filePath) {
+    const bytes = readFile(filePath);
+    fields.contentBase64 = Buffer.from(bytes).toString('base64');
+    fields.filename = fields.filename || path.basename(filePath);
+    if (!fields.contentType) {
+      const ext = path.extname(filePath).toLowerCase();
+      fields.contentType = ({ '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.pdf': 'application/pdf',
+        '.json': 'application/json', '.zip': 'application/zip', '.webm': 'video/webm', '.html': 'text/html',
+        '.md': 'text/markdown', '.txt': 'text/plain', '.log': 'text/plain' })[ext];
+    }
+  } else if (content !== undefined) {
+    fields.contentBase64 = Buffer.from(content, 'utf8').toString('base64');
+    fields.contentType = fields.contentType || 'text/plain; charset=utf-8';
+  } else if (!text(flags.url)) {
+    throw new Error('ticket artifact needs something to attach: --content "...", --file PATH or --url URL.');
+  }
+  return fields;
+}
+
 function runContextPayload(flags = {}) {
   const cwd = process.cwd();
   return {
@@ -17493,7 +17603,7 @@ async function agentReposCommand(flags) {
   if (Number.isFinite(accountId) && accountId > 0 && flagEnabled(flags.forget)) {
     const index = readAccountRepoIndex();
     const previous = index[String(accountId)];
-    delete index[String(accountId)];
+    index[String(accountId)] = { accountId, source: 'forgotten', updatedAt: new Date().toISOString() };
     writeAccountRepoIndex(index);
     console.log(previous
       ? 'account ' + accountId + ' removed (was ' + previous.directory + '). Its tickets will now park ' +
@@ -18001,6 +18111,8 @@ async function listenCommand(flags) {
         activeSessionSignature = currentSignature;
       }
 
+      // Do not await the filesystem scan: a slow/unavailable volume must not stall socket upkeep.
+      refreshAccountReposIfDue();
       await runManagedWebsocketWatchdog();
       updateRuntimeServiceState();
     } catch (err) {

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -96,6 +96,13 @@ 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`)
+- **There are no environments to deploy to, so translate SDLC words before acting.** "Let me try it" means a
+  token link to your staged lane. "Put it in UAT" means a sync to the pre-production component branch, or
+  a link if UAT is a link on this account. "Push to prod" means the promotion loop. "Roll it back" means
+  `git revert` plus a sync, and it does not undo emails or external writes. People who simply sign in never
+  see staged code. Syncing a branch others use, every promotion gate, and a trunk edit on a release-train
+  account each need the person's go for that step. (the account repo's core platform guide → *How A Change Reaches People*,
+  `branch-variants.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
@@ -181,10 +188,15 @@ reference named after it.
   from `./.remits-cli/actors/<local-agent>/tool-responses/<callId>.json` (or the legacy flat fallback
   if `doctor local-state` says the response is there) before reporting the work as done.
   (`tool-reference.md`)
-- **Workspace and local actor are different.** `workspace` is the server-side staging lane namespace;
-  `local actor` is the repo-local filesystem namespace for session logs, tool responses, and verification
-  mirrors. Use `REMITS_AGENT_ID=<name>` or `--local-agent <name>` when agents share a checkout, and run
-  `remits-cli doctor local-state` when inheriting one. (`cli-state.md`, `component-resolution.md`)
+- **Workspace, local actor and agent identity are three different things.** `workspace` is the
+  server-side staging lane. The **local actor** is only the repo-local folder for session logs, tool
+  responses and verification mirrors: name it with `--local-agent <name>` or `REMITS_LOCAL_AGENT_ID` when
+  agents share a checkout, and run `remits-cli doctor local-state` when inheriting one. **Agent identity**
+  (`--agent-id` / `REMITS_AGENT_ID`) is what the PLATFORM sees: it is sent on every call, it makes the
+  call an `agent` to the account's policy rules, and it decides ticket ownership. `REMITS_AGENT_ID` also
+  names the local folder when no local actor is set, which is why setting it "just for the folder" changes
+  how the platform treats you. If you are an AI agent, setting it is correct: say who you are, and let the
+  account's agent rules apply to you. (`cli-state.md`, `agent-sessions.md`)
 - **Writing the code is not finishing the job.** A change is complete when it is verified — a Test
   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
@@ -232,6 +244,11 @@ reference named after it.
 - **Reading and investigating are parallel-safe; editing one account's repository is exclusive**, via a
   lease. A refusal is not an error — carry on read-only and hand off with `ticket progress --next-step`.
   Never wait or poll for a lease. (`support-tickets.md`)
+- **`Refused by this account's '<rule>' rule` is a POLICY decision, not a missing capability.** The
+  sentence says who the call presented as (`[This call presents as agent (agentId=…)]`). Find the rule in
+  the account's `OPERATIONS.md` `remits-policy` block, report its id, its `when`/`forbid`, and why your call
+  matched, then ask a person. Never generalize it ("syncs are impossible here"), and never drop your agent
+  identity to get past it. (`support-tickets.md`)
 - **A brief's `## Rules you will be held to` section is ENFORCED, not requested.** The platform refuses
   the verb and the message says what to do instead — act on that sentence rather than retrying or
   looking for another door. A `[require]` rule needs a person; hand off. (`support-tickets.md`)

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

@@ -76,13 +76,19 @@ Think about remits-cli as two cooperating layers:
      - where a large tool response was written
      - which tool schemas were most recently cached here
 
-Per-repo state has two independent namespaces:
+Per-repo state has two independent namespaces, and one identity sits beside them:
 
 - **Workspace** (`--workspace`, `REMITS_WORKSPACE`, `.remits-cli/workspace`) chooses the server-side
   Redis staging lane. It changes what staged entries a run resolves.
-- **Local actor** (`--local-agent`, `REMITS_AGENT_ID`, generated fallback) chooses the local filesystem
-  namespace under `.remits-cli/actors/<local-agent>/`. It changes where session logs, tool responses,
-  verification mirrors, and diagnostics are written.
+- **Local actor** (`--local-agent` / `--actor`, then `REMITS_AGENT_ID`, then `REMITS_LOCAL_AGENT_ID`, then a
+  generated fallback) chooses the local filesystem namespace under `.remits-cli/actors/<local-agent>/`. It
+  changes where session logs, tool responses, verification mirrors, and diagnostics are written. To name
+  only the folder, use `--local-agent` or `REMITS_LOCAL_AGENT_ID`.
+- **Agent identity** (`--agent-id`, then `REMITS_AGENT_ID`) is not local state. The CLI sends it to the
+  platform on every call (`X-Remits-Agent-Id` and the payload `agentId`), so the call is an `agent` to the
+  account's `remits-policy` rules, owns the tickets it claims, and is attributed to that agent. Without it
+  the call is the signed-in person. `REMITS_AGENT_ID` therefore does two jobs, folder and identity; an AI
+  agent should set it deliberately, as identity.
 
 Run `remits-cli doctor local-state` to print the active actor, state directory, workspace source,
 foreign actors, git-tracked `.remits-cli` files, legacy flat state, and large/suspicious logs.
@@ -108,7 +114,7 @@ Agents should use this mental model before guessing.
 
 The account repository index file is located at: `{{ACCOUNT_REPO_INDEX_PATH}}`
 
-This JSON file is automatically maintained by `remits-cli` and tracks all known Remits account repositories on this machine. It is updated whenever any `remits-cli` command runs from an account repo directory. The file maps account IDs to their metadata:
+This JSON file is automatically maintained by `remits-cli` and tracks known Remits account repositories on this machine. It is updated when a CLI command runs from an account repo directory, at service startup, and by background discovery every five minutes while the service runs. Background scans use the same configured roots, depth limit and exclusions as startup; they report newly discovered repos to the platform without restarting. Use `remits-cli agent repos --rescan` for immediate discovery. The file maps account IDs to their metadata:
 
 ```json
 {
@@ -127,6 +133,8 @@ This JSON file is automatically maintained by `remits-cli` and tracks all known
 - Resolve account names and IDs without making remote API calls
 - Support cross-account workflows where an agent in one repo needs context from another
 
+Manual directory selections survive rescans; competing checkouts are recorded as ambiguity. `agent repos --account-id <id> --forget` stores an opt-out without a directory, so scans do not silently restore it. Explicitly register a directory or run a CLI command from that repo to restore registration.
+
 If the index file doesn't exist yet, run any `remits-cli` command from an account repo to bootstrap it.
 
 ## Local State Files

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

@@ -234,7 +234,7 @@ remits-cli ticket deliver --ticket ID --channel email --to a@x [--template T] [-
 remits-cli ticket deliveries --ticket ID [--channel email]   # what is queued to go out, and what already went
 remits-cli ticket delivered --ticket ID --delivery-id ID | ticket delivery-failed --ticket ID --delivery-id ID --reason "..."
 remits-cli ticket tag --ticket ID --tags a,b           # make a cluster of near-identical tickets visible as one
-remits-cli ticket artifact --ticket ID --type TYPE --label "..." [--url U | --content "..."]
+remits-cli ticket artifact --ticket ID --type TYPE --label "..." (--content "..." | --file PATH | --url U)
 remits-cli ticket participant --ticket ID --email E [--role watcher|requester|agent]
 remits-cli ticket field --ticket ID --key K --value V  # the ORGANIZATION's own field, outside the planning slots
 remits-cli ticket reclaim [--ticket ID | --account-id ID] [--stale-hours 24] [--apply]   # OPERATOR: take back an agent's abandoned ticket
@@ -284,10 +284,12 @@ remits-cli corpus retire --corpus <name> --case <caseKey> [--case ...] [--restor
 `test run` starts a server-side task immediately. By default the CLI process polls until the task is
 terminal; `--watch false` disables websocket progress streaming but still waits. Pass `--wait false` to
 return after launch with the task id. A single run with `--names "a|b|c"` selects cases into one suite task,
-and those cases execute sequentially in declaration order. To overlap independent slow cases, launch
-separate `remits-cli test run --names "<case>" --wait false` commands from the same staged lane and keep the
-printed task ids; complete each proof with `test status --task-id <id>`. Avoid parallel runs for cases that
-share mutable fixtures, suite-level side effects, or undeclared live AI/provider calls.
+and those cases execute sequentially by default. Test metadata `caseConcurrency` (1–16, default 1)
+enables native server workers. Explicit `--parallel N` overrides it; `--parallel 1` forces serial.
+Parent/group IDs work with `test status` and corpus commands; case results retain child task and trace IDs.
+Scheduled batches additionally accept `suiteConcurrency` (1–16, default 1) and overlap only suites marked
+`parallelSafe: true`; other suites run as exclusive barriers. Avoid concurrency for shared mutable
+fixtures or order-dependent setup. See the Test component guide's Configuring Parallel Execution section.
 
 ### Reading a failing run
 

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

@@ -430,8 +430,9 @@ id + content hash, platform sync vs local HEAD. If it is not the world you meant
 about a different world.
 
 The platform launch is asynchronous. By default `remits-cli test run` waits for its task to finish, and any
-cases selected by `--names "a|b"` execute sequentially inside that suite task. If several slow cases are
-independent, use `--parallel N`. It splits the selected cases across N shards that run side by side, and the run
+cases selected by `--names "a|b"` execute sequentially by default. A Test sidecar can set
+`caseConcurrency: 2` for native server workers, including scheduled runs. Explicit `--parallel N`
+overrides that setting (`--parallel 1` forces serial). It splits the selected cases across N shards that run side by side, and the run
 keeps ONE id (`grp-…`) for `test status` and every corpus command. An instance runs only a few suites at once
 (two by default), so shards beyond that wait for a slot. Ask for 2–4. Starting separate
 `test run --names "<case>" --wait false` commands also works for one-off proofs, but every such run is a separate
@@ -807,3 +808,11 @@ Some users want to review every change before staging. Others want you to move f
 - If they say "you don't need to ask me" or "stop asking" — remember this preference and work autonomously through the full loop.
 
 The default should be: make the change, stage it, verify it, and present the results. Only block on the user when you're genuinely unsure about intent.
+
+**Four steps always need the person's go for that step, whatever they said earlier:**
+- syncing a component branch that a pre-production or client account uses;
+- each promotion gate (`features/subscriber-branch-promotions.md` → *The three approval gates*);
+- unsubscribing an account or retiring a branch;
+- editing trunk on an account that runs a release-train branch.
+
+A general "just do it" covers staging and verifying, not these. Each one changes what live accounts run.

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

@@ -32,6 +32,7 @@
   - [Component branches](#component-branches)
   - [`mcp_cache`](#mcp_cache)
   - [`mcp_sql_query`](#mcp_sql_query)
+  - [`mcp_usage`](#mcp_usage)
   - [`mcp_index_search`](#mcp_index_search)
   - [`mcp_get_guide`](#mcp_get_guide)
   - [`mcp_test_fixture`](#mcp_test_fixture)
@@ -931,6 +932,30 @@ SELECT u.id, u.username, u.enabled FROM user u
 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.
 
+### `mcp_usage`
+Administrator-only usage reports and configuration through the platform's `usageControl` API. The
+System Account owns this global tool; deploy the platform API before staging or syncing its wrapper.
+
+| Parameter | Description |
+|---|---|
+| `operation` | `status` (default), `report`, `gaps`, `savePrice`, `replacePrice`, `endPrice`, `saveBillingMap`, `deleteBillingMap`, `saveManualCharge`, `deleteManualCharge`, `configure`, `runSettle`, `runBilling`, `flushMeter` |
+| `query` | `usage(...)` selectors for reports/gaps: dates, accountId, includeDescendants, lanes, includeSuites, grouping. Omit accountId for platform scope. |
+| `values` | Rate, mapping, charge or settings fields; status lists supported units and allowed settings. `replacePrice` requires the old id and full successor rate. |
+| `apply` | `false` by default: mutations return their normalized plan. `true` applies the authorized change. Configuration is platform-wide, independently of the test/prod data selector. |
+
+Read `status.pricingNotes` first. Rates start at future UTC hour boundaries; overlapping or historical
+changes are refused. Use `replacePrice` for an atomic rate change. Do not price a storage byte counter
+as byte-months or wall time as billed CPU time. `gaps` returns account/provider/model grouping so exact
+missing rate keys are visible. Shared platform overhead is excluded from account hierarchies.
+Provider invoices and estimates remain separate when filters do not match invoice scope.
+
+```bash
+remits-cli tool --name mcp_usage --input '{"operation":"status"}'
+remits-cli tool --name mcp_usage --input '{"operation":"report","query":{"accountId":41,"includeDescendants":true,"from":"2026-10-01"}}'
+```
+
+The full field contract and examples are in `features/usage-and-cost.md` → Configuring usage through MCP.
+
 ### `mcp_index_search`
 Query and **diagnose** the Vertex AI Search index through the platform's Vertex DSL. Use it to check what a
 RAG/search-backed component actually retrieves before blaming the component.

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

@@ -62,7 +62,7 @@
 | Unsure whether a run used staged vs DB source | Query `mcp_system_logs` for `Using Cached BCD` — `Signature: cli:<hash>` = staged, `version:<N>:<sourceHash12>` = DB. CLI/MCP tool results also report `componentSource` and `componentSignature` when available. |
 | Service already running | Run `remits-cli status` to get the dashboard URL, or `remits-cli stop` before restarting. |
 | Control center URL unknown | Read `~/.remits-cli/service-state.json` or run `remits-cli status` |
-| Dashboard missing repos | Rebuild `~/.remits-cli/account-repos.json` with `remits-cli start` or the control center rescan action |
+| Dashboard or GitHub menu missing local repos | The running service rediscovers repos every five minutes. Use `remits-cli agent repos --rescan` or the control center rescan action for immediate discovery; allow the next presence update (normally within 30 seconds). Check scan roots if still absent. A forgotten account needs explicit registration with `agent repos --account-id <id> --directory <path>`. |
 | Agent dispatch to wrong directory | Check `~/.remits-cli/account-repos.json` has the correct directory and that you resolved the account type correctly. A `CLIENT` ticket may still belong to a parent `PLATFORM` or `PRODUCT` repo for code changes. |
 
 ### When Something Doesn't Work as Expected