openmerit 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.1.9 — 2026-10-24
+
+- Add opt-in coding-agent installation milestones, component/connection diagnostics and consent-gated setup/installation correlation retained across resumed approval and upgrades. Carry browser usage and unlink choices into setup; keep standalone CLI analytics default-off and MCP prompt-content capture off.
+- Add bounded installation-event retries with stable delivery IDs. Report verification and remote revocation failures even when existing local command exit semantics remain successful.
+- Coordinate the independently released Scout browser/device/MCP lifecycle telemetry, correct HTTP-200 logical-error accounting, and distinguish key authorization from verified installation. These are observed events, not skipped-call detection, guaranteed delivery or downstream model-execution tracking.
+- Preserve existing package exports, model-decision guidance and legal metadata. Existing installations need an installer rerun; npm publication does not deploy Scout or the main website.
+
+## 0.1.8 — 2026-10-24
+
+- Install an owned startup rule requiring Scout before explicit or implicit application-model choices, including pretrained/local/browser models, weight downloads and SDK defaults. Keep detailed access-policy and search instructions in the skill. These instructions are guidance, not hard enforcement.
+- Upgrade unchanged skill-only installations without another device approval; include rule ownership, conflict detection, interrupted-update recovery, status, diagnostics and safe removal.
+- Require a new Claude Code session after setup or upgrade; reconnecting `/mcp` alone does not reload startup instructions. Pause model selection when Scout is unavailable or lacks suitable candidates rather than falling back to a remembered model.
+
 ## 0.1.7 — 2026-10-24
 
 - Release coding-agent device sign-in, Claude Code MCP/Scout skill installation, status, diagnostics, removal and project endpoint policy on the stable `latest` channel. Setup requires browser approval; it never requests a pasted key.

package/dist/terminal/src/install.mjs

@@ -1,13 +1,14 @@
 import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { homedir, hostname } from 'node:os';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { openBrowser } from './browser.mjs';
+import { clientVersion, setupHeaders, setupUUID, sendInstallationEvent, setupCorrelationEnabled } from './telemetry.mjs';
 
 // One-command coding-agent setup: device sign-in in the browser, then the MCP
-// server and Scout skill. Built to be run by a person or by a coding agent:
+// server, startup rule and Scout skill. Built to be run by a person or by a coding agent:
 // no interactive prompts, bounded waits, resumable logins and explicit exit codes.
 export const exitCodes = { ok: 0, error: 1, pending: 10, denied: 11, conflict: 20, unreachable: 30 };
 const exec = promisify(execFile);
@@ -15,18 +16,45 @@ const hash = value => createHash('sha256').update(value).digest('hex');
 const policyPath = '.openmerit/scout.json';
 const clients = { 'claude-code': 'Claude Code' };
 
+// No paths frontmatter: Claude loads this before the first model decision,
+// including user-scope sessions in Desktop's automatically created folders.
+export const rule = `# Application model decisions · OpenMerit Scout
+
+Before choosing, recommending, adding, downloading, replacing or configuring
+ANY application inference model, load the \`openmerit-scout\` skill and consult
+\`scout_models\` on the \`openmerit\` MCP server before committing to a model.
+This applies even when the user only asks you to build a feature, never mentions
+models or Scout, or names a model themselves (assess it; do not silently replace it).
+
+A pretrained model, local weights, browser inference, an SDK's default model,
+embeddings, OCR, speech, image classification, detection and segmentation all
+count as model choices, not implementation details. Identify this decision before
+writing model-specific code, installing a model package or downloading weights.
+
+Follow the skill's project access policy. If it is missing, ask and save it first.
+If Scout is unavailable, fails or has no suitable evidence/candidate, disclose the
+gap and pause the model decision; do not fall back to a remembered or SDK-default
+model. You may continue work that does not commit to a model.
+
+Do not consult Scout for unrelated edits, normal inference calls using an unchanged
+approved model, or this coding agent's own model. Do not reselect approved models
+unless the task introduces or changes a model decision.
+`;
+
 export const skill = `---
 name: openmerit-scout
-description: Use when choosing, adding, replacing or configuring an application inference model (an LLM or other model the user's application calls), for example when building extraction, classification, generation or agent features. Consults OpenMerit Scout for an evidence-based shortlist. Not for unrelated edits, ordinary inference calls or this coding agent's own model.
+description: Consults OpenMerit Scout before choosing, adding, downloading, replacing or configuring any application inference model, including implicit choices while building features, pretrained browser/local models, SDK defaults, embeddings, OCR, speech, classification, detection, segmentation, LLMs and agents. Not for unrelated edits, ordinary inference calls or this coding agent's own model.
 ---
 
 # OpenMerit · Scout
 
 Before introducing, recommending, replacing or configuring an application
 inference model, call the \`scout_models\` tool on the \`openmerit\` MCP server.
-This applies even when the user never mentions Scout. Preserve the user's explicit
-model choice; assess it rather than silently replacing it. Leave unchanged,
-approved application selections in place.
+This applies even when the user never mentions models or Scout. Downloading local
+weights, using a pretrained browser model or accepting an SDK default is a model
+decision: consult Scout before model-specific code, installs or downloads.
+Preserve the user's explicit model choice; assess it rather than silently replacing
+it. Leave unchanged, approved application selections in place.
 
 ## Project policy
 
@@ -64,24 +92,26 @@ writes. Report recommendation, endpoint connectivity and application checks as
 separate results, each only after it succeeds. Do not switch this coding agent's
 own model.
 
-If Scout fails, say so and pause the model decision; do not substitute a
-remembered recommendation. If it reports that the device key is missing,
+If Scout fails or has no suitable candidate/evidence for the required deployment,
+say so and pause the model decision; do not substitute a remembered recommendation
+or SDK default. Continue only model-independent work. Local/browser models are not
+exempt when the catalogue lacks coverage. If it reports that the device key is missing,
 expired or revoked, run \`npx -y openmerit@latest login\` and then
 \`npx -y openmerit@latest install\` again. Never ask the user to paste a key.
 `;
 
 export const help = `OpenMerit · coding-agent setup
 
-  openmerit install [--client claude-code] [--scope user|project] [--plan] [--json] [--no-open]
+  openmerit install [--client claude-code] [--scope user|project] [--setup-id UUID] [--plan] [--json] [--no-open]
   openmerit status  [--client claude-code] [--scope user|project] [--check] [--json]
   openmerit remove  [--client claude-code] [--scope user|project] [--plan] [--json]
-  openmerit login   [--json] [--no-open]     Replace this device's key
+  openmerit login   [--setup-id UUID] [--json] [--no-open]     Replace this device's key
   openmerit logout  [--json]                 Revoke this device's key
   openmerit project --policy existing-only|existing-first [--endpoint-id <id> ...] [--plan]
   openmerit doctor  [--json]
 
 install signs this device in through the browser (one Approve click), adds the
-OpenMerit MCP server and the Scout skill, then verifies the connection.
+OpenMerit MCP server, startup rule and Scout skill, then verifies the connection.
 It opens the approval page and waits up to 9 minutes for the Approve click
 (30 seconds when no browser could be opened). If it exits with approval
 pending, rerun the same command: it resumes the same request.
@@ -115,12 +145,12 @@ async function save(path, value) {
   await writeFile(path, typeof value === 'string' ? value : `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
 }
 
-async function request(path, { method = 'GET', body, key } = {}) {
+async function request(path, { method = 'GET', body, key, telemetry } = {}) {
   let response;
   try {
     response = await fetch(`${server()}${path}`, {
       method, redirect: 'error', signal: AbortSignal.timeout(15_000),
-      headers: { ...(body ? { 'Content-Type': 'application/json' } : {}), ...(key ? { Authorization: `Bearer ${key}` } : {}), 'X-Scout-Client': 'cli', 'X-Scout-Analytics-Content': 'off' },
+      headers: { ...(body ? { 'Content-Type': 'application/json' } : {}), ...(key ? { Authorization: `Bearer ${key}` } : {}), ...setupHeaders(telemetry?.properties) },
       ...(body ? { body: JSON.stringify(body) } : {}),
     });
   } catch { throw new Stop(`Could not reach ${server()}. Check your connection and retry.`, exitCodes.unreachable); }
@@ -134,12 +164,13 @@ function detectClient() {
 }
 
 // Claude Code locations. Project scope keeps the key out of the repository:
-// the MCP entry uses Claude's private "local" scope, only the skill is in the project.
+// the MCP entry uses Claude's private "local" scope; rule and skill are in the project.
 function claudePaths(root, scope) {
   const config = resolve(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'));
   const base = scope === 'user' ? config : join(root, '.claude');
   return {
     skill: join(base, 'skills/openmerit-scout/SKILL.md'),
+    rule: join(base, 'rules/openmerit-scout.md'),
     legacyRule: join(base, 'rules/openmerit.md'),
     record: join(base, 'openmerit-install.json'),
     mcpFile: process.env.CLAUDE_CONFIG_DIR ? join(config, '.claude.json') : join(homedir(), '.claude.json'),
@@ -147,7 +178,7 @@ function claudePaths(root, scope) {
   };
 }
 const configuredServer = (config, root, scope) => scope === 'user' ? config.mcpServers?.openmerit : config.projects?.[root]?.mcpServers?.openmerit;
-const serverConfig = key => ({ type: 'http', url: `${server()}/scout/mcp`, headers: { Authorization: `Bearer ${key}`, 'X-Scout-Analytics-Content': 'off' } });
+const serverConfig = (key, telemetry) => ({ type: 'http', url: `${server()}/scout/mcp`, headers: { Authorization: `Bearer ${key}`, ...setupHeaders(telemetry.properties, 'agent') } });
 const canonical = value => Array.isArray(value) ? value.map(canonical) : value && typeof value === 'object' ? Object.fromEntries(Object.keys(value).sort().map(k => [k, canonical(value[k])])) : value;
 const serverHash = value => value ? hash(JSON.stringify(canonical(value))) : null;
 
@@ -164,16 +195,18 @@ async function claude(args, root, key) {
 // Inspect the current Claude Code installation without changing anything.
 async function inspect(root, scope) {
   const paths = claudePaths(root, scope);
-  const [record, config, installedSkill, legacyRule] = await Promise.all([object(paths.record), object(paths.mcpFile), optional(paths.skill), optional(paths.legacyRule)]);
-  const owned = record.version === 2 && record.scope === scope;
+  const [record, config, installedSkill, installedRule, legacyRule] = await Promise.all([object(paths.record), object(paths.mcpFile), optional(paths.skill), optional(paths.rule), optional(paths.legacyRule)]);
+  const owned = [2, 3].includes(record.version) && record.scope === scope;
   const current = configuredServer(config, root, scope);
   const otherScope = configuredServer(config, root, scope === 'user' ? 'project' : 'user');
   const projectFile = await object(join(root, '.mcp.json'));
   return {
-    paths, record, owned, current, installedSkill,
-    // A pending header hash covers an install interrupted between add and record.
-    serverOwned: !current || owned && (serverHash(current) === record.serverHash || !!record.pendingAuth && hash(current.headers?.Authorization ?? '') === record.pendingAuth),
+    paths, record, owned, current, installedSkill, installedRule,
+    // A full pending hash covers interruption without accepting edited headers.
+    // Keep pendingAuth compatibility for records from the earlier installer.
+    serverOwned: !current || owned && (serverHash(current) === record.serverHash || serverHash(current) === record.pendingServerHash || !!record.pendingAuth && hash(current.headers?.Authorization ?? '') === record.pendingAuth),
     skillOwned: installedSkill === null || owned && [record.skillHash, record.pendingSkill].includes(hash(installedSkill)),
+    ruleOwned: installedRule === null || owned && record.version === 3 && [record.ruleHash, record.pendingRule].includes(hash(installedRule)),
     // The pre-release installer recorded its rule hash; only an unchanged rule is removed.
     legacyRule: legacyRule !== null && record.version === 1 && hash(legacyRule) === record.ruleHash ? 'remove' : legacyRule !== null ? 'keep' : 'none',
     shadowed: !!(otherScope || projectFile.mcpServers?.openmerit),
@@ -184,10 +217,20 @@ function conflicts(state) {
   const found = [];
   if (!state.serverOwned) found.push('Claude Code already has an MCP server named "openmerit" that this installer did not create or that was edited. Remove it with "claude mcp remove openmerit", then retry.');
   if (!state.skillOwned) found.push(`${state.paths.skill} exists and was not created by this installer or was edited. Move or delete it, then retry.`);
+  if (!state.ruleOwned) found.push(`${state.paths.rule} exists and was not created by this installer or was edited. Move or delete it, then retry.`);
   if (state.shadowed) found.push('An "openmerit" MCP server exists in another Claude Code scope (or in .mcp.json). Remove it, then retry.');
   return found;
 }
 
+function diagnostics(state) {
+  return {
+    installed: state.owned && !!state.current && state.serverOwned && state.installedSkill !== null && state.skillOwned && state.installedRule !== null && state.ruleOwned && !state.shadowed,
+    server_status: state.current ? state.serverOwned ? 'matches' : 'modified_or_unowned' : 'missing',
+    skill_status: state.installedSkill === null ? 'missing' : state.skillOwned ? 'matches' : 'modified_or_unowned',
+    rule_status: state.installedRule === null ? 'missing' : state.ruleOwned ? 'matches' : 'modified_or_unowned',
+  };
+}
+
 async function credentials() {
   const saved = await object(credentialsPath());
   return saved.version === 1 && saved.server === server() && typeof saved.key === 'string' ? saved : null;
@@ -195,33 +238,56 @@ async function credentials() {
 
 // Device login. Starts or resumes a login, waits a bounded time, and stores the
 // key only on disk. Never prints the key.
-async function login({ client, scope, open, log, wait }) {
+async function login({ client, scope, open, log, wait, telemetry }) {
+  await telemetry.step('login', 'started');
   let pending = await object(pendingPath());
   if (!(pending.server === server() && pending.expiresAt > Date.now() && typeof pending.deviceCode === 'string')) {
     const deviceName = (process.env.OPENMERIT_DEVICE_NAME ?? hostname()).replace(/[^\x20-\x7e]/g, '').slice(0, 64) || 'this device';
-    const { status, data } = await request('/connect/api/device', { method: 'POST', body: { client, scope, device_name: deviceName } });
+    const { status, data } = await request('/connect/api/device', { method: 'POST', body: { client, scope, device_name: deviceName }, telemetry });
     if (status !== 200 || !data.device_code) throw new Stop(data.error ?? `Could not start sign-in (HTTP ${status}).`, status === 429 ? exitCodes.unreachable : exitCodes.error);
-    pending = { server: server(), deviceCode: data.device_code, userCode: data.user_code, url: data.verification_uri_complete, interval: data.interval, expiresAt: Date.now() + data.expires_in * 1000, opened: false };
+    pending = { server: server(), deviceCode: data.device_code, userCode: data.user_code, url: data.verification_uri_complete, interval: data.interval, expiresAt: Date.now() + data.expires_in * 1000, opened: false, setup_id: telemetry.properties.setup_id, installation_id: telemetry.properties.installation_id };
     await save(pendingPath(), pending);
   }
+  const approvalURL = new URL(pending.url);
+  // Rebuild consent on every resume, so old query parameters cannot override a
+  // later refusal. Only opt-in setup IDs are ever sent to the approval page.
+  for (const key of ['setup_id', 'analytics', 'analytics_account']) approvalURL.searchParams.delete(key);
+  if (setupCorrelationEnabled() && setupUUID(telemetry.properties.setup_id)) approvalURL.searchParams.set('setup_id', telemetry.properties.setup_id);
+  // Browser usage consent is independent of CLI opt-in. Only an explicit
+  // cross-surface refusal disables it; account unlinking must not disable usage.
+  if (process.env.DO_NOT_TRACK === '1') approvalURL.searchParams.set('analytics', 'off');
+  if (process.env.OPENMERIT_ANALYTICS_ACCOUNT === 'off' || process.env.DO_NOT_TRACK === '1') approvalURL.searchParams.set('analytics_account', 'off');
+  pending = { ...pending, url: approvalURL.href, setup_id: telemetry.properties.setup_id, installation_id: telemetry.properties.installation_id };
+  await save(pendingPath(), pending);
   log(`Approve this device in your browser (opening it now):\n\n  ${pending.url}\n\n  Code: ${pending.userCode} (expires ${new Date(pending.expiresAt).toLocaleTimeString()})\n`);
+  await telemetry.step('browser_open', 'started');
   if (open && !pending.opened && !pending.openFailed) {
     // Only the approval page on the configured OpenMerit server may be opened.
-    const approvalPage = url => { const u = new URL(url); return `${u.origin}` === server() && u.pathname === '/connect' && [...u.searchParams.keys()].join() === 'code' && !u.username && !u.password && !u.hash; };
+    const approvalPage = url => {
+      const u = new URL(url);
+      return u.origin === server() && u.pathname === '/connect' && !!u.searchParams.get('code')
+        && [...u.searchParams.keys()].every(key => ['code', 'setup_id', 'analytics', 'analytics_account'].includes(key) && u.searchParams.getAll(key).length === 1)
+        && (!u.searchParams.has('setup_id') || setupUUID(u.searchParams.get('setup_id')))
+        && ['analytics', 'analytics_account'].every(key => !u.searchParams.has(key) || u.searchParams.get(key) === 'off')
+        && !u.username && !u.password && !u.hash;
+    };
     const opened = await openBrowser(pending.url, { allowed: approvalPage }).catch(() => false);
     pending = { ...pending, ...(opened ? { opened: true } : { openFailed: true }) };
     await save(pendingPath(), pending);
   }
+  await telemetry.step('browser_open', pending.opened ? 'ok' : pending.openFailed ? 'error' : 'pending');
+  await telemetry.step('login', 'started');
   // With the approval page open, keep waiting for the Approve click (inside a
   // coding agent's 10-minute command limit) so nobody has to rerun anything.
   // Without a browser, return soon so the agent can show the link.
   const deadline = Date.now() + (wait ?? (pending.opened ? 540 : 30)) * 1000;
   let interval = (pending.interval ?? 5) * 1000;
   for (;;) {
-    const { status, data } = await request('/connect/api/token', { method: 'POST', body: { device_code: pending.deviceCode } });
+    const { status, data } = await request('/connect/api/token', { method: 'POST', body: { device_code: pending.deviceCode }, telemetry });
     if (status === 200 && data.access_token) {
-      await save(credentialsPath(), { version: 1, server: server(), key: data.access_token, keyId: data.key_id, createdAt: new Date().toISOString() });
+      await save(credentialsPath(), { version: 1, server: server(), key: data.access_token, keyId: data.key_id, setup_id: telemetry.properties.setup_id, createdAt: new Date().toISOString() });
       await rm(pendingPath(), { force: true });
+      await telemetry.step('login', 'ok');
       return data.access_token;
     }
     if (data.error === 'slow_down') interval += 5000;
@@ -236,80 +302,110 @@ async function login({ client, scope, open, log, wait }) {
 }
 
 // A real MCP initialize and tool discovery with the stored key; no search.
-async function verify(key) {
-  const call = (id, method, params = {}) => request('/scout/mcp', { method: 'POST', key, body: { jsonrpc: '2.0', id, method, params } });
-  const init = await call(1, 'initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'openmerit-cli', version: '1' } });
-  if (init.status === 401) return 'key_rejected';
-  if (init.status !== 200 || !init.data.result) return 'failed';
-  const tools = await call(2, 'tools/list');
-  return tools.data.result?.tools?.some(tool => tool.name === 'scout_models') ? 'connected' : 'failed';
+async function verify(key, telemetry) {
+  await telemetry.step('verification', 'started');
+  const call = (id, method, params = {}) => request('/scout/mcp', { method: 'POST', key, telemetry, body: { jsonrpc: '2.0', id, method, params } });
+  const init = await call(1, 'initialize', { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'openmerit-cli', version: clientVersion ?? 'unknown' } });
+  let connection = init.status === 401 ? 'key_rejected' : 'failed';
+  if (init.status === 200 && init.data.result) {
+    const tools = await call(2, 'tools/list');
+    connection = tools.status === 401 ? 'key_rejected' : tools.status === 200 && tools.data.result?.tools?.some(tool => tool.name === 'scout_models') ? 'connected' : 'failed';
+  }
+  await telemetry.step('verification', connection === 'connected' ? 'ok' : 'error', { connection, ...(connection === 'connected' ? {} : { code: connection === 'key_rejected' ? 'access_denied' : 'command_error' }) });
+  return connection;
 }
 
-async function install(root, { client, scope, plan, open, log, wait }) {
+async function install(root, { client, scope, plan, open, log, wait, telemetry }) {
   const state = await inspect(root, scope);
   const found = conflicts(state);
   const changes = [
     `${state.current ? 'Update' : 'Add'} MCP server "openmerit" in Claude Code (${state.paths.mcpScope} scope, ${state.paths.mcpFile})`,
     `${state.installedSkill === null ? 'Create' : 'Update'} ${state.paths.skill}`,
+    `${state.installedRule === null ? 'Create' : 'Update'} ${state.paths.rule} (loaded at session startup)`,
     ...(state.legacyRule === 'remove' ? [`Remove the unchanged earlier instructions at ${state.paths.legacyRule}`] : []),
     ...(await credentials() ? [] : [`Sign this device in through the browser and store its key in ${credentialsPath()} (mode 600)`]),
   ];
   if (plan) return { action: 'install', applied: false, client, scope, changes, conflicts: found };
   if (found.length) throw new Stop(found.join('\n'), exitCodes.conflict, 'Nothing was changed.');
   await claude(['--version'], root);
+  if (setupCorrelationEnabled()) telemetry.properties.installation_id ??= randomUUID();
+  await telemetry.step('preflight', 'ok');
   let key = (await credentials())?.key;
   // A revoked or expired key gets a fresh sign-in instead of a broken install.
-  if (key && await verify(key) === 'key_rejected') { await rm(credentialsPath(), { force: true }); key = undefined; log('The saved device key is no longer valid; signing in again.'); }
-  key ??= await login({ client, scope, open, log, wait });
-  const next = serverConfig(key);
+  if (key && await verify(key, telemetry) === 'key_rejected') { await rm(credentialsPath(), { force: true }); key = undefined; log('The saved device key is no longer valid; signing in again.'); }
+  key ??= await login({ client, scope, open, log, wait, telemetry });
+  await telemetry.step('configuration', 'started');
+  const next = serverConfig(key, telemetry);
+  const ids = { setup_id: telemetry.properties.setup_id, installation_id: telemetry.properties.installation_id };
   // Record intent first so an interrupted install is repaired by rerunning.
-  await save(state.paths.record, { version: 2, scope, client, serverHash: serverHash(state.current), skillHash: state.installedSkill === null ? null : hash(state.installedSkill), pendingAuth: hash(next.headers.Authorization), pendingSkill: hash(skill) });
-  if (state.current?.url !== next.url || state.current?.headers?.Authorization !== next.headers.Authorization) {
+  await save(state.paths.record, { version: 3, scope, client, ...ids, serverHash: serverHash(state.current), skillHash: state.installedSkill === null ? null : hash(state.installedSkill), ruleHash: state.installedRule === null ? null : hash(state.installedRule), pendingServerHash: serverHash(next), pendingSkill: hash(skill), pendingRule: hash(rule) });
+  telemetry.properties.applied = true;
+  if (serverHash(state.current) !== serverHash(next)) {
     if (state.current) await claude(['mcp', 'remove', '--scope', state.paths.mcpScope, 'openmerit'], root, key);
     await claude(['mcp', 'add-json', '--scope', state.paths.mcpScope, 'openmerit', JSON.stringify(next)], root, key);
   }
   await save(state.paths.skill, skill);
+  await save(state.paths.rule, rule);
   if (state.legacyRule === 'remove') await rm(state.paths.legacyRule, { force: true });
   // Record what Claude actually wrote, so later edits are detected precisely.
   const written = configuredServer(await object(state.paths.mcpFile), root, scope);
   if (!written) throw new Stop('Claude Code did not save the "openmerit" MCP server.', exitCodes.error, 'Run "openmerit doctor".');
-  await save(state.paths.record, { version: 2, scope, client, serverHash: serverHash(written), skillHash: hash(skill), installedAt: new Date().toISOString() });
-  const connection = await verify(key);
+  await save(state.paths.record, { version: 3, scope, client, ...ids, serverHash: serverHash(written), skillHash: hash(skill), ruleHash: hash(rule), installedAt: new Date().toISOString() });
+  await telemetry.step('configuration', 'ok', diagnostics(await inspect(root, scope)));
+  const connection = await verify(key, telemetry);
+  if (connection !== 'connected') telemetry.outcome = 'error';
   if (connection === 'key_rejected') throw new Stop('OpenMerit rejected this device key (expired or revoked).', exitCodes.denied, 'Run "openmerit login", then rerun install.');
   return { action: 'install', applied: true, client, scope, changes, connection,
     next: connection === 'connected'
-      ? `Scout is ready in new ${clients[client]} sessions. In a session that is already open, run /mcp and reconnect "openmerit".`
+      ? `Scout is ready in new ${clients[client]} sessions. Start a new session to load the startup rule and updated skill; reconnecting /mcp alone does not reload instructions.`
       : 'Installed, but the connection check failed. Run "openmerit doctor".' };
 }
 
-async function status(root, { client, scope, check }) {
+async function status(root, { client, scope, check, telemetry }) {
+  await telemetry.step('status', 'started');
   const state = await inspect(root, scope), saved = await credentials();
-  const installed = state.owned && !!state.current && state.serverOwned && state.installedSkill !== null && state.skillOwned && !state.shadowed;
-  return { action: 'status', client, scope, installed, signedIn: !!saved,
-    server: state.current ? state.serverOwned ? 'matches' : 'modified_or_unowned' : 'missing',
-    skill: state.installedSkill === null ? 'missing' : state.skillOwned ? 'matches' : 'modified_or_unowned',
-    conflicts: conflicts(state), connection: check && saved ? await verify(saved.key) : 'not_checked' };
+  const details = diagnostics(state), found = conflicts(state);
+  const connection = check && saved ? await verify(saved.key, telemetry) : 'not_checked';
+  telemetry.outcome = ['failed', 'key_rejected'].includes(connection) ? 'error' : found.length ? 'conflict' : details.installed ? 'ok' : 'not_installed';
+  await telemetry.step('status', telemetry.outcome, { ...details, connection });
+  return { action: 'status', client, scope, installed: details.installed, signedIn: !!saved,
+    server: details.server_status, skill: details.skill_status, rule: details.rule_status,
+    conflicts: found, connection };
 }
 
-async function revokeKey() {
+async function revokeKey(telemetry) {
   const saved = await credentials();
   if (!saved) return false;
-  const { status } = await request('/connect/api/keys/self', { method: 'DELETE', key: saved.key }).catch(() => ({ status: 0 }));
+  await telemetry.step('remove', 'started');
+  const { status } = await request('/connect/api/keys/self', { method: 'DELETE', key: saved.key, telemetry }).catch(() => ({ status: 0 }));
   await rm(credentialsPath(), { force: true });
+  if (status !== 200) telemetry.outcome = 'error';
+  await telemetry.step('remove', status === 200 ? 'ok' : 'error', status === 200 ? {} : {
+    code: status === 0 ? 'openmerit_unreachable' : status === 401 || status === 403 ? 'access_denied' : 'command_error',
+  });
   return status === 200;
 }
 
-async function remove(root, { client, scope, plan }) {
+async function remove(root, { client, scope, plan, telemetry }) {
+  await telemetry.step('remove', 'started');
   const state = await inspect(root, scope);
-  if (!state.owned) return { action: 'remove', applied: false, client, scope, changes: [], note: 'No OpenMerit installation by this installer in this scope.' };
+  if (!state.owned) {
+    telemetry.outcome = 'not_installed';
+    await telemetry.step('remove', 'not_installed');
+    return { action: 'remove', applied: false, client, scope, changes: [], note: 'No OpenMerit installation by this installer in this scope.' };
+  }
   const changes = [...(state.current && state.serverOwned ? [`Remove MCP server "openmerit" (${state.paths.mcpScope} scope)`] : []),
-    ...(state.installedSkill !== null && state.skillOwned ? [`Delete ${state.paths.skill}`] : []), 'Revoke and delete this device key'];
-  const kept = [...(state.serverOwned ? [] : ['the edited "openmerit" MCP server']), ...(state.skillOwned ? [] : [state.paths.skill]), policyPath];
+    ...(state.installedSkill !== null && state.skillOwned ? [`Delete ${state.paths.skill}`] : []),
+    ...(state.installedRule !== null && state.ruleOwned ? [`Delete ${state.paths.rule}`] : []), 'Revoke and delete this device key'];
+  const kept = [...(state.serverOwned ? [] : ['the edited "openmerit" MCP server']), ...(state.skillOwned ? [] : [state.paths.skill]), ...(state.ruleOwned ? [] : [state.paths.rule]), policyPath];
   if (plan) return { action: 'remove', applied: false, client, scope, changes, keeps: kept };
+  telemetry.properties.applied = true;
   if (state.current && state.serverOwned) await claude(['mcp', 'remove', '--scope', state.paths.mcpScope, 'openmerit'], root);
   if (state.installedSkill !== null && state.skillOwned) await rm(dirname(state.paths.skill), { recursive: true, force: true });
+  if (state.installedRule !== null && state.ruleOwned) await rm(state.paths.rule, { force: true });
   await rm(state.paths.record, { force: true });
-  const revoked = await revokeKey();
+  const revoked = await revokeKey(telemetry);
+  await telemetry.step('remove', telemetry.outcome, diagnostics(await inspect(root, scope)));
   return { action: 'remove', applied: true, client, scope, changes, keeps: kept, keyRevoked: revoked };
 }
 
@@ -322,26 +418,29 @@ async function project(root, { policy, ids, plan }) {
   return { action: 'project', applied: !plan, path: policyPath, policy: value, note: 'Endpoint IDs limit discovery only; they do not prove access or authorize spending.' };
 }
 
-async function doctor(root, { scope }) {
+async function doctor(root, { scope, telemetry }) {
+  await telemetry.step('status', 'started');
   const checks = [];
   const add = (name, ok, detail) => checks.push({ name, ok, detail });
   const [major, minor] = process.versions.node.split('.').map(Number);
   add('node', major > 22 || major === 22 && minor >= 19, `Node.js ${process.versions.node} (22.19+ required)`);
   try { const { stdout } = await exec('claude', ['--version'], { timeout: 10_000 }); add('claude', true, stdout.trim().slice(0, 80)); }
   catch { add('claude', false, 'Claude Code (claude) is not on PATH'); }
-  const reach = await request('/scout/api/status').catch(error => ({ status: 0, error }));
+  const reach = await request('/scout/api/status', { telemetry }).catch(error => ({ status: 0, error }));
   add('openmerit', reach.status === 200, reach.status === 200 ? `${server()} reachable` : `${server()} unreachable`);
   const saved = await credentials();
   add('key', !!saved, saved ? `Device key ${saved.keyId ?? ''} stored in ${credentialsPath()}` : 'Not signed in. Run "openmerit install" or "openmerit login".');
-  if (saved && reach.status === 200) { const connection = await verify(saved.key); add('mcp', connection === 'connected', `MCP check: ${connection}`); }
+  if (saved && reach.status === 200) { const connection = await verify(saved.key, telemetry); add('mcp', connection === 'connected', `MCP check: ${connection}`); }
   const state = await inspect(root, scope).catch(() => null);
-  if (state) add('install', state.owned && !conflicts(state).length, state.owned ? conflicts(state).join(' ') || `Installed (${scope} scope)` : `Not installed in ${scope} scope`);
+  if (state) add('install', state.owned && !!state.current && state.installedSkill !== null && state.installedRule !== null && !conflicts(state).length, state.owned ? conflicts(state).join(' ') || (state.current && state.installedSkill !== null && state.installedRule !== null ? `Installed (${scope} scope)` : 'Installation incomplete. Rerun "openmerit install".') : `Not installed in ${scope} scope`);
+  telemetry.outcome = checks.every(check => check.ok) ? 'ok' : 'error';
+  await telemetry.step('status', telemetry.outcome, { ...(state ? diagnostics(state) : {}), ...(reach.status === 200 ? {} : { code: 'openmerit_unreachable', connection: 'failed' }) });
   return { action: 'doctor', ok: checks.every(check => check.ok), checks };
 }
 
 function render(result) {
   if (result.action === 'doctor') return result.checks.map(c => `${c.ok ? '✓' : '✗'} ${c.name}: ${c.detail}`).join('\n');
-  if (result.action === 'status') return [`OpenMerit in ${clients[result.client]} (${result.scope} scope): ${result.installed ? 'installed' : 'not installed'}`, `Signed in: ${result.signedIn ? 'yes' : 'no'} · MCP server: ${result.server} · skill: ${result.skill} · connection: ${result.connection}`, ...result.conflicts].join('\n');
+  if (result.action === 'status') return [`OpenMerit in ${clients[result.client]} (${result.scope} scope): ${result.installed ? 'installed' : 'not installed'}`, `Signed in: ${result.signedIn ? 'yes' : 'no'} · MCP server: ${result.server} · skill: ${result.skill} · rule: ${result.rule} · connection: ${result.connection}`, ...result.conflicts].join('\n');
   if (result.action === 'project') return `${result.applied ? 'Saved' : 'Would save'} ${result.path}: ${result.policy.policy}, ${result.policy.endpointIds.length} endpoint ID(s). ${result.note}`;
   if (result.action === 'login') return result.note;
   if (result.action === 'logout') return result.note;
@@ -352,12 +451,39 @@ function render(result) {
   return lines.join('\n');
 }
 
-export async function main(args, { root = process.cwd(), print = console.log, printError = console.error } = {}) {
+export async function main(args, dependencies = {}) {
+  const telemetry = {
+    stage: 'started', outcome: 'ok',
+    properties: { command: ['install', 'status', 'remove', 'login', 'logout', 'project', 'doctor'].includes(args[0]) ? args[0] : 'unknown', agent: 'claude-code', scope: 'user', applied: false, installed: false, connection: 'not_checked' },
+    async step(stage, outcome, properties = {}) {
+      this.stage = stage;
+      if (outcome === 'ok') delete this.properties.code;
+      Object.assign(this.properties, properties);
+      await sendInstallationEvent({ ...this.properties, stage, outcome });
+    },
+    async fail(error) {
+      this.outcome = ({ 10: 'pending', 11: 'denied', 20: 'conflict' })[error.exit] ?? 'error';
+      const code = ({ 10: 'approval_pending', 11: 'access_denied', 20: 'install_conflict', 30: 'openmerit_unreachable' })[error.exit] ?? 'command_error';
+      await this.step(this.stage, this.outcome, { code, ...(this.stage === 'verification' ? { connection: error.exit === exitCodes.denied ? 'key_rejected' : 'failed' } : {}) });
+    },
+  };
+  try {
+    const code = await runMain(args, dependencies, telemetry);
+    await telemetry.step('completed', telemetry.outcome);
+    return code;
+  } catch (error) {
+    await telemetry.fail(error);
+    await telemetry.step('completed', telemetry.outcome);
+    throw error;
+  }
+}
+
+async function runMain(args, { root = process.cwd(), print = console.log, printError = console.error }, telemetry) {
   const [action, ...rest] = args;
   if (!action || rest.includes('--help') || rest.includes('-h')) { print(help); return exitCodes.ok; }
-  const options = { client: undefined, scope: 'user', plan: false, check: false, json: false, open: true, policy: undefined, ids: [] };
-  const allowed = { install: ['--client', '--scope', '--plan', '--json', '--no-open'], status: ['--client', '--scope', '--check', '--json'], remove: ['--client', '--scope', '--plan', '--json'],
-    login: ['--json', '--no-open'], logout: ['--json'], project: ['--policy', '--endpoint-id', '--plan', '--json'], doctor: ['--scope', '--json'] }[action];
+  const options = { client: undefined, scope: 'user', plan: false, check: false, json: false, open: true, policy: undefined, ids: [], telemetry };
+  const allowed = { install: ['--client', '--scope', '--setup-id', '--plan', '--json', '--no-open'], status: ['--client', '--scope', '--check', '--json'], remove: ['--client', '--scope', '--plan', '--json'],
+    login: ['--setup-id', '--json', '--no-open'], logout: ['--json'], project: ['--policy', '--endpoint-id', '--plan', '--json'], doctor: ['--scope', '--json'] }[action];
   if (!allowed) throw new Error('Unknown command. Run openmerit --help.');
   for (let i = 0; i < rest.length; i++) {
     const option = rest[i];
@@ -365,6 +491,7 @@ export async function main(args, { root = process.cwd(), print = console.log, pr
     const value = () => { const v = rest[++i]; if (v === undefined || v.startsWith('--')) throw new Error(`${option} needs a value.`); return v; };
     if (option === '--client') options.client = value();
     else if (option === '--scope') options.scope = value();
+    else if (option === '--setup-id') { options.setup_id = value(); if (!setupUUID(options.setup_id)) throw new Error('--setup-id must be a UUID v4.'); }
     else if (option === '--policy') options.policy = value();
     else if (option === '--endpoint-id') options.ids.push(value());
     else if (option === '--no-open') options.open = false;
@@ -381,17 +508,41 @@ export async function main(args, { root = process.cwd(), print = console.log, pr
   const wait = process.env.OPENMERIT_LOGIN_WAIT === undefined ? undefined : Number(process.env.OPENMERIT_LOGIN_WAIT);
   const log = text => (options.json ? printError : print)(text);
   try {
+    telemetry.properties.scope = options.scope;
+    // Hydrate correlation without creating identities or writing anything. A
+    // pending approval owns its setup ID even when the resumed command omits it.
+    if (['install', 'status', 'remove', 'doctor'].includes(action)) {
+      telemetry.stage = 'preflight';
+      const state = await inspect(root, options.scope);
+      Object.assign(telemetry.properties, diagnostics(state));
+      if (state.owned) for (const key of ['setup_id', 'installation_id']) if (setupUUID(state.record[key])) telemetry.properties[key] = state.record[key];
+    }
+    if (options.setup_id) telemetry.properties.setup_id = options.setup_id;
+    if (['install', 'login'].includes(action)) {
+      const saved = await credentials();
+      if (!telemetry.properties.setup_id && setupUUID(saved?.setup_id)) telemetry.properties.setup_id = saved.setup_id;
+      const pending = await object(pendingPath());
+      if (pending.server === server() && pending.expiresAt > Date.now() && typeof pending.deviceCode === 'string') {
+        if (setupUUID(pending.setup_id)) telemetry.properties.setup_id = pending.setup_id;
+        if (!telemetry.properties.installation_id && setupUUID(pending.installation_id)) telemetry.properties.installation_id = pending.installation_id;
+      }
+    }
+    await telemetry.step('started', 'started');
+    await telemetry.step('preflight', 'started');
     const result = action === 'install' ? await install(root, { ...options, log, wait })
       : action === 'status' ? await status(root, options)
       : action === 'remove' ? await remove(root, options)
       : action === 'project' ? await project(root, options)
       : action === 'doctor' ? await doctor(root, options)
-      : action === 'logout' ? { action, revoked: await revokeKey(), note: 'Signed out. This device key was revoked and deleted. Agents configured with it stop working until you run install again.' }
-      : (await revokeKey(), await rm(pendingPath(), { force: true }), await login({ client: 'claude-code', scope: 'user', open: options.open, log, wait }), { action, signedIn: true, note: 'Signed in. Run "openmerit install" again to give your coding agents the new key.' });
+      : action === 'logout' ? { action, revoked: await revokeKey(telemetry), note: 'Signed out. This device key was revoked and deleted. Agents configured with it stop working until you run install again.' }
+      : (await revokeKey(telemetry), await login({ client: 'claude-code', scope: 'user', open: options.open, log, wait, telemetry }), { action, signedIn: true, note: 'Signed in. Run "openmerit install" again to give your coding agents the new key.' });
+    if (result.conflicts?.length && telemetry.outcome !== 'error') { telemetry.outcome = 'conflict'; telemetry.properties.code = 'install_conflict'; }
+    if (options.plan) await telemetry.step(telemetry.stage, telemetry.outcome, { applied: false });
     print(options.json ? JSON.stringify({ ok: true, ...result }, null, 2) : render(result));
     return action === 'doctor' && !result.ok ? exitCodes.error : exitCodes.ok;
   } catch (error) {
     if (!(error instanceof Stop)) throw error;
+    await telemetry.fail(error);
     if (options.json) print(JSON.stringify({ ok: false, action, code: Object.keys(exitCodes).find(k => exitCodes[k] === error.exit), message: error.message, next: error.next }, null, 2));
     else printError([error.message, error.next].filter(Boolean).join('\n'));
     return error.exit;

package/dist/terminal/src/telemetry.mjs

@@ -1,7 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 
-let clientVersion;
+export let clientVersion;
 for (const path of ['../../../package.json', '../../../../package.json']) {
   try { const pkg = JSON.parse(readFileSync(new URL(path, import.meta.url), 'utf8')); if (pkg.name === 'openmerit') { clientVersion = pkg.version; break; } } catch {}
 }
@@ -31,6 +31,74 @@ const environment = () => ({ ...(clientVersion ? { client_version: clientVersion
 
 const anonymousId = randomUUID();
 export const telemetryEnabled = () => process.env.OPENMERIT_TELEMETRY === '1' && process.env.DO_NOT_TRACK !== '1';
+export const setupCorrelationEnabled = () => telemetryEnabled() && process.env.OPENMERIT_ANALYTICS_ACCOUNT !== 'off';
+export const setupUUID = value => typeof value === 'string' && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+// Device/verifier traffic is CLI opt-in. Installed MCP usage retains its existing
+// default, but explicit privacy refusals must survive into future agent sessions.
+export function setupHeaders(ids = {}, client = 'cli') {
+  return {
+    'X-Scout-Client': client,
+    'X-Scout-Agent': 'claude-code',
+    ...(clientVersion ? { 'X-Scout-Client-Version': clientVersion } : {}),
+    'X-Scout-Analytics-Content': 'off',
+    ...(client === 'cli' ? { 'X-Scout-Analytics': telemetryEnabled() ? 'on' : 'off' } : process.env.DO_NOT_TRACK === '1' ? { 'X-Scout-Analytics': 'off' } : {}),
+    ...(process.env.OPENMERIT_ANALYTICS_ACCOUNT === 'off' || process.env.DO_NOT_TRACK === '1' ? { 'X-Scout-Analytics-Account': 'off' } : {}),
+    ...(setupCorrelationEnabled() && setupUUID(ids.setup_id) ? { 'X-Scout-Setup-Id': ids.setup_id } : {}),
+    ...(setupCorrelationEnabled() && setupUUID(ids.installation_id) ? { 'X-Scout-Installation-Id': ids.installation_id } : {}),
+  };
+}
+export function installationProperties(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const out = {};
+  const enums = {
+    stage: ['started', 'preflight', 'login', 'browser_open', 'configuration', 'verification', 'status', 'remove', 'completed'],
+    outcome: ['started', 'ok', 'error', 'pending', 'denied', 'conflict', 'not_installed'],
+    command: ['install', 'status', 'remove', 'login', 'logout', 'project', 'doctor', 'unknown'],
+    agent: ['claude-code'], scope: ['user', 'project'],
+    rule_status: ['matches', 'missing', 'modified_or_unowned'],
+    skill_status: ['matches', 'missing', 'modified_or_unowned'],
+    server_status: ['matches', 'missing', 'modified_or_unowned'],
+    connection: ['connected', 'failed', 'key_rejected', 'not_checked'],
+    code: ['command_error', 'approval_pending', 'access_denied', 'install_conflict', 'openmerit_unreachable'],
+  };
+  for (const [key, values] of Object.entries(enums)) {
+    if (input[key] === undefined && !['stage', 'outcome'].includes(key)) continue;
+    if (!values.includes(input[key])) return null;
+    out[key] = input[key];
+  }
+  for (const key of ['setup_id', 'installation_id']) if (setupUUID(input[key])) out[key] = input[key];
+  for (const key of ['applied', 'installed']) if (typeof input[key] === 'boolean') out[key] = input[key];
+  return out;
+}
+export async function sendInstallationEvent(input) {
+  if (!telemetryEnabled()) return;
+  const properties = installationProperties(input);
+  if (!properties) return;
+  if (!setupCorrelationEnabled()) { delete properties.setup_id; delete properties.installation_id; }
+  // One immutable envelope across a transient retry. A hard total deadline
+  // bounds awaited milestones even if the transport ignores cancellation.
+  const body = JSON.stringify({ event: 'scout_installation_step', event_id: randomUUID(), anonymousId, properties: { ...properties, ...environment() } });
+  const controller = new AbortController();
+  let timer;
+  try {
+    await Promise.race([
+      (async () => {
+        for (let attempt = 0; attempt < 2 && !controller.signal.aborted && telemetryEnabled(); attempt++) {
+          try {
+            const response = await fetch('https://openmerit.ai/scout/api/analytics', {
+              method: 'POST', headers: { 'Content-Type': 'application/json', ...setupHeaders(properties) },
+              body, signal: controller.signal, redirect: 'error',
+            });
+            await response.body?.cancel();
+            if (response.ok || response.status !== 429 && response.status < 500) return;
+          } catch { /* Only a bounded retry; never export error text. */ }
+        }
+      })(),
+      new Promise(resolve => { timer = setTimeout(() => { controller.abort(); resolve(); }, 1500); }),
+    ]);
+  } catch { /* Never affect setup, even if the transport ignores abort. */ }
+  finally { clearTimeout(timer); }
+}
 export const errorType = error => ['Error', 'TypeError', 'RangeError', 'SyntaxError', 'ReferenceError', 'URIError', 'EvalError', 'AggregateError', 'AbortError'].includes(error?.name) ? error.name : 'Error';
 export function terminalProperties(event, input) {
   if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
@@ -65,12 +133,13 @@ export function sendTerminalEvent(event, input) {
 }
 async function sendAnalytics(event, properties) {
   const controller = new AbortController();
+  const body = JSON.stringify({ event, event_id: randomUUID(), anonymousId, properties: { ...properties, ...environment() } });
   let timer;
   try {
     await Promise.race([
       Promise.resolve().then(() => fetch('https://openmerit.ai/scout/api/analytics', {
-        method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Scout-Client': 'cli', 'X-Scout-Analytics': 'on' },
-        body: JSON.stringify({ event, anonymousId, properties: { ...properties, ...environment() } }), signal: controller.signal, redirect: 'error',
+        method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Scout-Client': 'cli', 'X-Scout-Analytics': 'on', ...(process.env.OPENMERIT_ANALYTICS_ACCOUNT === 'off' ? { 'X-Scout-Analytics-Account': 'off' } : {}) },
+        body, signal: controller.signal, redirect: 'error',
       })).then(response => response.body?.cancel()),
       new Promise(resolve => { timer = setTimeout(() => { controller.abort(); resolve(); }, 750); timer.unref(); }),
     ]);
@@ -78,7 +147,8 @@ async function sendAnalytics(event, properties) {
   finally { clearTimeout(timer); }
 }
 
-// Consent is independent of terminal discovery. Never persist an identity.
+// Consent is independent of terminal discovery. Command identity is ephemeral;
+// the installer separately manages the owned installation's correlation IDs.
 export function commandTelemetry(args) {
   if (process.env.OPENMERIT_TELEMETRY !== '1' || process.env.DO_NOT_TRACK === '1') return async () => {};
   const started = performance.now();
@@ -90,12 +160,13 @@ export function commandTelemetry(args) {
   async function send(event, properties) {
     if (!telemetryEnabled()) return;
     const controller = new AbortController();
+    const body = JSON.stringify({ event, event_id: randomUUID(), anonymousId, properties: { ...properties, ...environment(), command_id } });
     let timer;
     try {
       await Promise.race([
         Promise.resolve().then(() => fetch('https://openmerit.ai/scout/api/analytics', {
-          method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Scout-Client': 'cli', 'X-Scout-Analytics': 'on' },
-          body: JSON.stringify({ event, anonymousId, properties: { ...properties, ...environment(), command_id } }),
+          method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Scout-Client': 'cli', 'X-Scout-Analytics': 'on', ...(process.env.OPENMERIT_ANALYTICS_ACCOUNT === 'off' ? { 'X-Scout-Analytics-Account': 'off' } : {}) },
+          body,
           signal: controller.signal, redirect: 'error',
         })).then(response => response.body?.cancel()),
         new Promise(resolve => { timer = setTimeout(() => { controller.abort(); resolve(); }, 750); }),

package/docs/inference-terminal.md

@@ -6,6 +6,8 @@ It reads existing evidence independently of inference. It does not call a model,
 
 ## Optional CLI product analytics
 
+**Coding-agent setup telemetry — npm 0.1.9:** opted-in setup adds stage/outcome/component/connection diagnostics and random setup/installation correlation, described in the [Scout lifecycle contract](scout.md#coding-agent-lifecycle-instrumentation-npm-019). Unlike the process-only terminal identity below, an opted-in setup stores its installation UUID in the existing ownership record and installed MCP headers for later calls. No paths, credentials, device names or task content are exported. The copied website prompt explicitly carries usage/unlink preferences; standalone commands still require `OPENMERIT_TELEMETRY=1`, and `DO_NOT_TRACK=1` overrides it. Plans and status checks do not create an installation identity. Older npm 0.1.8 installations need an installer rerun; hosted browser/server collection requires the matching independent Scout deployment.
+
 Available in npm 0.1.7. CLI product analytics are off unless `OPENMERIT_TELEMETRY=1`; `DO_NOT_TRACK=1` always disables them. Terminal `discovery` configuration and `--no-discovery` are unrelated to analytics consent.
 
 When explicitly enabled, the CLI posts `cli_command_started` and `cli_command_completed` to `https://openmerit.ai/scout/api/analytics`, with a fresh `crypto.randomUUID()` identity for that process only. No identity file, cookie, or installation ID is stored. Properties contain only a command category (`help`, `dash`, `eval_init`, `eval_doctor`, `eval_plan`, `eval_run`, `eval_watch`, `eval_report`, or `unknown`), plus completion outcome (`ok` or `error`) and integer elapsed milliseconds capped at one day. Paths, arguments, prompts, configuration, model IDs, error text, environment contents, machine names, and email are not included.

package/docs/scout-data-policy.md

@@ -1,8 +1,10 @@
 # Scout beta data policy
 
-Updated 23 October 2026.
+Updated 24 October 2026.
 
-**Coding-agent reset, 23 October 2026:** this build removes Scout's coding-agent backend and setup/connection tracking. The Claude Code panel is a web-only placeholder with no installation or authentication flow. MCP and agent OAuth metadata routes return HTTP 404 in this build; the website, browser sign-in and JSON API remain. Earlier MCP references below describe the policy before this reset. Existing analytics records and remote grants are not deleted by this reset. A source-only replacement adds device sign-in: Scout stores the approving account, device name you chose (the host name by default), client, scope, timestamps and hashes of device codes and keys, but never a key itself. It is not deployed yet.
+**Coding-agent setup, 24 October 2026:** hosted Scout supports device sign-in and MCP; stable npm 0.1.8 installs Claude Code's MCP configuration, startup rule and Scout skill after approval. This supersedes the 23 October web-placeholder reset. Scout stores the approving account, device name you chose (the host name by default), client, scope, timestamps and hashes of device codes and keys, but never a plaintext key. Local setup stores the key in private configuration; external coding agents have their own data handling. Installation and startup guidance do not guarantee an agent will invoke Scout.
+
+**Lifecycle telemetry — npm 0.1.9 and matching Scout deployment:** this revision adds consent-gated setup-click, clipboard/launch-request, device-authorization, installation/component-verification and MCP-invocation diagnostics. Linked setup uses random setup and installation UUIDs to correlate those milestones; the local ownership record and installed MCP headers retain them across sessions/upgrades. Unlinked mode omits these IDs. Copied setup prompts carry usage/unlink preferences into installation, while standalone CLI telemetry remains opt-in and DNT overrides it. Installed MCP prompt-content capture remains off. The revision also adds bounded delivery retries and sanitized Cloudflare delivery counters, without identity, content, URLs, device codes or credentials in those counters. Existing installations need an installer rerun; these changes do not backfill earlier activity. See the [lifecycle contract](scout.md#coding-agent-lifecycle-instrumentation-npm-019). Release acceptance is recorded separately.
 
 **Version-5 diagnostics:** Scout serving builds collect page views/leaves, bounded engagement, allowlisted acquisition/UTM and browser/device categories, and sampled browser performance observations where supported and usage analytics is enabled. Native URL properties use only reconstructed public paths, never raw visitor URLs, queries or fragments. Linked activity can join same-tab visits, signup and searches; unlinking retains request-only server identity, not a cross-request funnel. Feedback records a useful/not-useful rating and optional fixed reason, with linked trace/retry correlation, not free text. Server diagnostics include bounded stage/provider failure codes and actual pipeline attempt tokens when reported, not invented charges or executions of recommended models. See the [technical contract](scout.md#version-5-instrumentation). Main-site/docs collection and CLI publication have separate release boundaries. No replay or ranking experiment is enabled, and none of the prompt-content or retention controls below change.
 
@@ -22,7 +24,7 @@ Scout processes your submitted task to generate recommendations. With usage anal
 | --- | --- |
 | Submitted task and model restrictions | Required to interpret the task, find suitable models and return recommendations. Scout sends task information to OpenAI even when analytics is off. |
 | Recommendations and search diagnostics | When usage analytics is enabled, PostHog receives task categories, model IDs, ranks, available quality/cost/latency evidence, timings, cache status and outcomes. These describe recommendations, not execution of those models on your data. |
-| Product interactions and errors | Enabled analytics includes visits, preset selections, sign-in activity, results viewed, evidence opened, copies, provider-link clicks and coding-agent setup activity. API/MCP events include method, outcome and confirmed connections. Error reports use bounded categories and application stack locations, not raw error messages. |
+| Product interactions and errors | Enabled analytics includes visits, preset selections, sign-in activity, results viewed, evidence opened, copies, provider-link clicks and coding-agent setup activity. API/MCP events record request outcomes. Lifecycle-enabled builds add allowlisted method/tool, reported agent/harness and version, setup/installation correlation and verified-connection diagnostics. A launch request is not proof an app opened, and key authorization is not proof of installation. Error reports use bounded categories and application stack locations, not raw error messages. |
 | Account details | Clerk handles Google/GitHub login. Enabled account analytics can synchronize your name, verified primary email, signup time and connected providers to PostHog. Account and session lifecycle events help us understand onboarding and returning use. |
 | Optional prompt content | Only when prompt sharing is enabled, PostHog also receives the submitted prompt and written task breakdown, for at most three tasks. Prompt text is limited to 4,000 characters, with up to 1,000 characters per excerpt or five-layer field. Common sensitive patterns are removed where detected; this is not guaranteed anonymization. All such text is confined to `$ai_trace.$ai_input_state={prompt,tasks}`; new ordinary `scout_search_details` events contain no prompt, excerpt or layer prose. |
 
@@ -39,7 +41,7 @@ Open **Privacy & analytics** in the [Scout footer](/scout/#analytics-settings):
 
 Scout respects Do Not Track and Global Privacy Control for these analytics. An authenticated browser also communicates its usage preference to the server; the latest received account preference controls background synchronization. A browser that is offline or not signed in cannot update that account preference until it reconnects and authenticates.
 
-API/MCP clients can send `X-Scout-Analytics: off` to disable analytics. Prompt text still requires explicit `X-Scout-Analytics-Content: on`; general opt-out and supported privacy signals take precedence. CLI content capture is always off. Copied agent setup instructions disable prompt-content sharing and do not inherit this browser's account-linkage setting. See the [technical analytics guide](scout.md#product-analytics) for the full contract.
+API/MCP clients can send `X-Scout-Analytics: off` to disable analytics. Prompt text still requires explicit `X-Scout-Analytics-Content: on`; general opt-out and supported privacy signals take precedence. CLI content capture is always off. Older 0.1.8 setup does not inherit this browser's account-linkage setting; the 0.1.9 lifecycle revision explicitly carries usage and unlink preferences into the command and installed headers. Later browser changes do not rewrite existing agent configuration; rerun setup to update it. Request-only refusals in that revision do not overwrite saved account-wide preferences. See the [technical analytics guide](scout.md#product-analytics) for the full contract.
 
 Enabled signed-in analytics normally uses a stable account identifier linked to the profile above; hashing does not make it anonymous, and a pre-sign-in visit can be joined after login. In unlinking mode the server uses fresh unrelated random identifiers, sends no profile/identify operation, ignores previously linked browser identifiers and supplied trace IDs, and does not return an analytics trace ID for later interactions to reuse. Account opt-out and deletion gates still apply before sending. Clerk profile/lifecycle analytics can continue separately under general usage consent. Past records remain linked; signing out or selecting this option does not unlink them. Unlinked request events cannot support cross-request funnels or automatic account-based historical deletion. Prompt text itself may identify a person: unlinking is not anonymization.
 

package/docs/scout.md

@@ -24,6 +24,28 @@ Examples go through the same interpretation and ranking as typed prompts, with n
 
 ## Product analytics
 
+### Coding-agent lifecycle instrumentation — npm 0.1.9
+
+Npm 0.1.9 includes these installer changes; browser/server instrumentation requires the matching independent Scout deployment. Release acceptance is recorded separately. Rerun the installer to update existing 0.1.8 installations; nothing backfills historical events. This contract supersedes the no-retry and process-only setup-identity descriptions below for lifecycle-enabled builds. Homepage/docs deployment remains separate.
+
+| Touchpoint | Event and meaning |
+|---|---|
+| Add to coding agent | `scout_agent_setup_started` records the click. `scout_agent_launch_requested` records an attempted Claude deep link, **not proof the app opened**. `scout_agent_setup_copied` separately records clipboard success/failure. |
+| Device authorization | Server-owned `scout_connect_step` records device creation, approval-page requests, pending/slow polling, approval or denial, expiry, key collection, device listing and revocation. Expected pending polls are not exceptions. Browser failures use `scout_connect_client_error` with a fixed stage/code. |
+| Installation | Opt-in `scout_installation_step` records preflight, login/browser opening, configuration, verification, status, removal and completion. `applied`, component states and `connection` distinguish a plan, incomplete installation and a verified connection. A command exit of zero alone does not establish installation success. |
+| MCP connection | `scout_request_completed` records every handled MCP request, including initialization/discovery and authentication failures. Allowlisted `mcp_method`, `mcp_tool`, reported agent and package version distinguish verifier probes from agent calls. Unrecognized names become `other`/`unknown`, never raw strings. |
+| Each invocation/task | `scout_tool_invocation_started` and `scout_tool_invocation_completed` bracket authenticated tool dispatch. `scout_search_completed` counts an accepted recommendation attempt; `scout_search_details` retains each task's shortlist. All share the request trace. Protocol/tool errors are failures even with HTTP 200. |
+
+When browser usage analytics is enabled, the copied setup prompt explicitly sets `OPENMERIT_TELEMETRY=1`; usage-disabled prompts instead set `DO_NOT_TRACK=1`. Account-unlinked prompts also set `OPENMERIT_ANALYTICS_ACCOUNT=off`. A linked setup gets a random `--setup-id` UUID that joins the click, resumed login, installation and later invocations. An opted-in installation stores a separate random `installation_id` in its existing ownership record and MCP headers; upgrades reuse it. These identifiers contain no account, hostname or project path. They are correlation hints, not authentication. Plans and status checks do not create an installation identity. Standalone CLI telemetry remains default-off, and `DO_NOT_TRACK=1` wins. Installed MCP content capture remains off.
+
+The approval page initializes the same browser privacy controls and authenticated account preference synchronization as Scout, without inventing a Scout pageview. Installer URL refusals (`analytics=off`, `analytics_account=off`) remain effective without changing the browser's stored settings; a request-only refusal does not overwrite the account preference. A collected key is labelled **authorized**, not a verified installation. Account-wide opt-out still requires the authenticated preference endpoint and continues to gate linked and unlinked account requests. Unlinking removes setup/installation identifiers as well as browser/trace linkage. A privacy change in a browser does not rewrite an already installed agent's headers; rerun setup with the desired settings. Existing account opt-outs are not automatically reset.
+
+First trigger and first task mean **first observed** tool call and task for that installation/account. They are derived from the same event stream, not additional search counts. Discovery is not a trigger. Recommendation completion is not downstream model execution or application-task success. No transcript is read, and this instrumentation cannot prove a startup rule loaded, a model decision occurred without calling Scout, or a native app actually opened. Missing consent, storage, connectivity or abrupt termination can leave a funnel incomplete; missing events must not be presented as a verified zero or a proven skipped call.
+
+Initialization can record an allowlisted harness name and semver-shaped reported harness version; the installed headers report the npm installer version, not Claude's current version or invoking model. The stateless service cannot infer the coding agent's model from Scout's own provider generation events. Installer milestones include a fixed `command` category so status/doctor/project completion is never counted as a new installation. Setup milestone submission allows one transient retry within a hard 1.5-second total deadline; general CLI/terminal delivery retains the separately documented behavior below.
+
+Browser event submission retries one transient failure with a stable event UUID. Server delivery retries transport failures, HTTP 429 and 5xx up to three total attempts, with the same event UUIDs/timestamps and a 1.5-second timeout per attempt. Permanent 4xx responses do not retry. Product responses do not wait for delivery. There is no durable product-event queue or exactly-once guarantee; bounded retries can still exhaust. The serving Worker configuration enables sanitized Cloudflare console counters (`scout_analytics_delivery`: delivered, failed, request-suppressed or account-suppressed), with query redaction and invocation logs disabled. Counters contain no identity, trace, device code, URL, content or credential and remain available independently of PostHog delivery. They are operational diagnostics, not PostHog service-log ingestion or session replay. `X-Scout-Analytics-Status` reports only whether the request permits capture, never a receipt of ingestion.
+
 ### Version-5 instrumentation
 
 This contract applies to version-5 Scout serving builds. The serving rollout is independent of main-site publication and the npm package; npm 0.1.7 includes the opt-in CLI additions, while the website collector remains source-only. Prompt-content choices, redaction, retention and account deletion controls are unchanged. Main-site publication remains blocked by [source divergence](site-documentation.md#website-analytics-source-only-unreleased). Earlier dated receipts below describe earlier releases, not acceptance of version 5.
@@ -396,7 +418,7 @@ The capability index lists each area with its benchmark-series and model counts.
 
 ## Connect a coding agent
 
-**Device sign-in setup — npm 0.1.7:** use the stable `latest` tag for the commands below. Hosted Scout serves `/connect` and `/scout/mcp` independently of npm. Claude Code is the only supported client; other agents are not yet supported. The older `0.1.7-preview.5` package does not contain these commands.
+**Device sign-in setup — npm 0.1.8:** use the stable `latest` tag for the commands below. Version 0.1.8 adds the startup model-decision rule to the device setup introduced in 0.1.7. Hosted Scout serves `/connect` and `/scout/mcp` independently of npm. Claude Code is the only supported client; other agents are not yet supported. The older `0.1.7-preview.5` package does not contain these commands.
 
 Setup takes four steps, and you act in each one only once:
 
@@ -408,13 +430,13 @@ Setup takes four steps, and you act in each one only once:
    ```
 
 3. **Click Approve** on `https://openmerit.ai/connect`, which the command opens for you. Sign in first if needed. The page shows the client, the device name, the scope, an eight-character code that matches the command's output, and the only permission granted: Scout recommendations through MCP. Only approve a request you started yourself.
-4. **Done.** The command has kept waiting, so nothing needs rerunning. It stores the device key, adds the `openmerit` MCP server with `claude mcp add-json`, writes the Scout skill and checks the connection with a real MCP `initialize` and tool discovery (not a search). The approval page switches to *Claude Code is connected* once the command has collected its key, and Claude Code reports the result. Scout is available in new Claude Code sessions; in a session that is already open, reconnect `openmerit` in `/mcp`.
+4. **Done.** The command has kept waiting, so nothing needs rerunning. It stores the device key, adds the `openmerit` MCP server with `claude mcp add-json`, writes the Scout skill and startup rule, and checks the connection with a real MCP `initialize` and tool discovery (not a search). The approval page switches to *Claude Code is connected* once the command has collected its key, and Claude Code reports the result. **Start a new Claude Code session** to load the startup instructions; reconnecting `openmerit` in `/mcp` alone is not enough.
 
 The prompt contains no key, account data or task draft. If the Claude desktop app isn't installed or your browser blocks the link, paste the copied prompt into Claude Code instead. The command needs `npx` (Node.js 22.19 or newer) and the `claude` CLI on the PATH of that session; the installer runs `claude mcp add-json`. Having the desktop app alone does not establish that those commands are available. See [Claude Desktop](https://code.claude.com/docs/en/desktop).
 
 When the command can open a browser, it waits up to nine minutes for the Approve click. When it can't, for example over SSH, it prints the link and code and returns after 30 seconds with exit code 10 so the agent can show them. Rerunning the same command resumes the same request; it does not issue a new code. Codes expire after ten minutes and can be used once. `OPENMERIT_LOGIN_WAIT` sets the wait in seconds.
 
-`--client` defaults to the agent running the command (Claude Code sets `CLAUDECODE=1`). `--scope` defaults to `user`, which makes Scout available in every project. `--scope project` writes the skill to `.claude/skills/` in the current project and stores the MCP server in Claude Code's private per-project (`local`) configuration, so the key never enters the repository. `--plan` lists the changes without making them. `--json` prints one result object for agents.
+`--client` defaults to the agent running the command (Claude Code sets `CLAUDECODE=1`). `--scope` defaults to `user`, which makes Scout available in every project. `--scope project` writes the skill to `.claude/skills/` and startup rule to `.claude/rules/` in the current project and stores the MCP server in Claude Code's private per-project (`local`) configuration, so the key never enters the repository. `--plan` lists the changes without making them. `--json` prints one result object for agents.
 
 | Exit code | Meaning |
 |---|---|
@@ -431,6 +453,8 @@ When the command can open a browser, it waits up to nine minutes for the Approve
 
 Each approval creates one key for one device and client, limited to `scout:recommend`. It is accepted only on `/scout/mcp`; the JSON API and browser still require a Clerk session. The server stores only SHA-256 hashes of keys and device codes. A key expires after 90 days without use; each use extends it. The usual per-user rate limits and analytics preferences apply.
 
+Missing or invalid MCP credentials return HTTP 401 with `device_key_required`. The recovery command is `npx -y openmerit@latest install`; the older preview package does not include the installer.
+
 On the device, the key is stored in `~/.config/openmerit/credentials.json` (mode 600; `OPENMERIT_CONFIG_DIR` or `XDG_CONFIG_HOME` override the location) and in Claude Code's MCP header configuration, which Claude Code stores in plain text. The CLI never prints the key and scrubs it from any failing `claude` output. Do not paste keys into a chat.
 
 Revoke devices under **Connected devices** on `/connect`. `openmerit remove` and `openmerit logout` also revoke this device's key.
@@ -447,14 +471,24 @@ openmerit project --policy existing-only|existing-first [--endpoint-id <id> ...]
 openmerit doctor  # Node.js, claude, reachability, key, MCP check and install state
 ```
 
-Removal deletes the MCP server, the unchanged skill and the install record, and revokes the key. It keeps edited files and `.openmerit/scout.json`.
+Removal deletes the MCP server, the unchanged skill and startup rule, and the install record, and revokes the key. It keeps edited files and `.openmerit/scout.json`.
 
 ### Using Scout from the agent
 
-The `openmerit-scout` skill loads when an application inference model is being chosen, even if you do not mention Scout. It is not loaded for unrelated edits, ordinary inference calls or the agent's own model. On first use in a project, it asks once whether the project is **existing-only** or **existing-first** and which public catalogue endpoint IDs it can reach, then saves them with `openmerit project`. Every search passes the saved `endpointIds`, including `[]`. Existing-only never broadens; existing-first asks before an unscoped search. Task descriptions go to Scout and OpenAI; do not send source files, secrets or customer records.
+Claude can load the `openmerit-scout` skill when choosing an application inference model, even if you do not mention Scout. The skill-only setup in npm 0.1.7 can miss implicit choices while building an app, including selecting pretrained browser models. Availability in the skill list does not prove invocation. Unrelated edits, ordinary inference calls and the coding agent's own model are outside its scope. On first use in a project, the skill instructs Claude to ask once whether the project is **existing-only** or **existing-first** and which public catalogue endpoint IDs it can reach, then save them with `openmerit project`. Every search passes the saved `endpointIds`, including `[]`. Existing-only never broadens; existing-first asks before an unscoped search. Task descriptions go to Scout and OpenAI; do not send source files, secrets or customer records.
 
 The agent compares model and endpoint, evidence, reference cost/time and unknowns, and helps configure the chosen route. New providers, credentials, spending and deployments need separate approval. A skill is a default, not enforcement. The MCP tool, `scout_models`, is read-only and does not execute models.
 
+### Startup model-decision rule — npm 0.1.8
+
+The 0.1.8 installer adds `rules/openmerit-scout.md` alongside the skill. Unlike an on-demand skill, an unscoped [Claude Code rule](https://code.claude.com/docs/en/memory#organize-rules-with-claude/rules/) loads at session startup. The rule requires loading the skill and consulting Scout before any application-model choice, even when the user only asks for a feature. It explicitly includes pretrained/local/browser models, weight downloads, SDK defaults, embeddings, OCR, speech, classification, detection and segmentation. An explicit user model choice must be assessed, not silently replaced. Unchanged approved models and ordinary inference calls do not require another search.
+
+Rerunning `npx -y openmerit@latest install --client claude-code` with version 0.1.8 or later upgrades an unchanged npm 0.1.7 installation without another device approval. User scope writes the rule under `~/.claude/rules/` (or `CLAUDE_CONFIG_DIR`) and covers new projects and Desktop's no-folder sessions. Project scope writes `.claude/rules/openmerit-scout.md` and applies only in that project. The existing skill, private MCP entry and key locations are unchanged. Start a **new Claude Code session** after installation or upgrade; reconnecting `/mcp` alone does not reload startup instructions.
+
+The installer records rule ownership, repairs missing rules, resumes interrupted updates and refuses to overwrite edited or unowned rules. `--plan` includes the rule without writing it; `status` reports its state and `doctor` treats a missing rule as incomplete. `remove` deletes only the unchanged owned rule and retains edited rules and other user instructions.
+
+If policy is missing, Claude must ask before searching. If Scout is unavailable or has no suitable evidence/candidate for the required deployment, the instructions require disclosing the gap and pausing model selection, not choosing from memory or an SDK default. Model-independent work may continue. Catalogue coverage is not guaranteed for local/browser models. These are behavioral instructions, **not hard enforcement**; Claude can still fail to follow them. Older 0.1.7 installations remain skill-only until upgraded; website deployment alone does not update an installed client.
+
 ## JSON API
 
 ```sh

package/docs/security.md

@@ -57,10 +57,14 @@ The [coding-agent setup](scout.md#connect-a-coding-agent) in npm 0.1.7 uses host
 
 **Historical reset, superseded by npm 0.1.7 and hosted device setup.** The reset temporarily removed the installer and MCP transport. The current [Claude Code setup](scout.md#connect-a-coding-agent) uses browser-approved, device-specific keys scoped to MCP recommendations, not pasted session tokens or agent OAuth. The key is stored locally in mode-600 credentials and Claude Code's plain-text MCP configuration. Setup installs an owned Scout skill; conflicts are not overwritten, and removal revokes the device key. Browser Google/GitHub sign-in remains separate.
 
+**npm 0.1.8:** setup also installs an owned, always-loaded `rules/openmerit-scout.md` instruction requiring Scout before implicit or explicit application-model choices, including pretrained/local/browser models and SDK defaults. Edited or unowned rules are not overwritten or removed. Missing policy requires asking; unavailable Scout or insufficient coverage requires pausing model selection. This is model guidance, not an enforced tool gate or authorization to download weights, add providers, spend or deploy. Scope, device-key permissions and task-data handling are unchanged. New sessions are required after upgrading; older npm 0.1.7 installations remain skill-only until upgraded.
+
 Scout serving, main-site documentation and npm publication are separate releases. This reset does not revoke remote grants or clean up files previously installed on other machines. Earlier hosted MCP/authentication descriptions in this guide refer to past deployments, not this build. Browser Google/GitHub sign-in and its Clerk account lifecycle are separate and unchanged.
 
 ## Hosted Scout analytics
 
+**Coding-agent lifecycle instrumentation — npm 0.1.9 and matching Scout deployment:** setup clicks, clipboard/deep-link attempts, device authorization states, opted-in installation/component verification and each dispatched MCP invocation gain typed milestones and fixed error codes. Linked setup uses random setup/installation UUIDs, never paths, machine names, device codes, keys or transcript content. The browser handoff explicitly carries usage/unlink choices into setup; standalone CLI analytics remains opt-in. Setup/installation IDs are omitted in unlinked mode, DNT wins, and installed MCP prompt-content capture stays off. Request-only suppression no longer overwrites the saved account-wide preference. Explicit account opt-out/deletion gates remain in force. See the [lifecycle contract](scout.md#coding-agent-lifecycle-instrumentation-npm-019) for event meanings, bounded delivery retries and diagnostic counters. Existing installations require an installer rerun; release acceptance is separate, and no historical completeness, replay, transcript collection or skipped-call detection is claimed.
+
 **Version-5 instrumentation:** the [serving contract](scout.md#version-5-instrumentation) adds validated native web events and explicit CTA-only `$autocapture` mapping, not general DOM capture. Acquisition/UTM/device values are categorical allowlists; public URL properties are reconstructed without raw URLs. Browser performance is sampled and support-dependent. Linked same-tab signup/search identity is separate from unlinking's request-only identifiers. Logical MCP errors count even with HTTP 200; stage/provider codes, actual attempt tokens and feedback/retry traces exclude raw messages and free text. CLI diagnostics are opt-in in npm 0.1.7, adding sanitized version/platform/runtime and bounded application basename frames, never absolute paths or environment contents. Prompt sharing, retention, deletion gates and necessary provider processing are unchanged. Replay is a separate, inactive spike; no experiment is active. Main-site publication remains blocked by documented source divergence; the Scout rollout does not publish npm or activate alert notifications.
 
 **Beta evaluation rollout, 22 October 2026:** The serving configuration enables `SCOUT_BETA_EVALUATION_LOGGING=true`, alongside `POSTHOG_CAPTURE_CONTENT=true` and complete account-sync/deletion configuration. The browser defaults content on only without a stored content choice; saved off, general opt-out, DNT/GPC and unreadable storage keep it off. API/MCP still require `X-Scout-Analytics-Content: on`; CLI content is always off. This is product evaluation/debugging, not foundation model training. Deployment is owner-approved; this is not legal certification, and beta status establishes no consent or legal basis. Main-site `/docs/` publication remains blocked by source divergence; the [policy](/scout/data-policy/) is generated from the same Markdown and published with Scout instead.

package/docs/testing.md

@@ -1,5 +1,15 @@
 # Testing and validation
 
+## Stable 0.1.7 acceptance — 24 October 2026
+
+Published `openmerit@0.1.7` to npm's `latest` channel after full repository verification: 757 passing tests, one existing skip, syntax/type checks, builds and documentation checks. The `preview` tag remains `0.1.7-preview.5`. A fresh registry installation on macOS ARM64 with Node.js 22.23.1 matched the tested 104-file tarball byte-for-byte. Packed core/protocol/Pi exports and the installed terminal runtime smoke checks passed, including passive collection, source removal, runtime outage/recovery and shutdown.
+
+The live Scout button opened a prefilled Claude Desktop Code session through Chrome. That session ran `npx -y openmerit@latest install --client claude-code`, opened the real device-approval page, and completed after approval of the matching code. This was a clean setup after removing and revoking this test's earlier source installation, not reuse of an existing key. Status then reported the MCP server and skill installed and connected; credentials had mode 600 and other MCP servers were preserved.
+
+A fresh Desktop session received an application-model request that never mentioned Scout. It loaded `openmerit-scout` and called the real `scout_models` tool with the saved empty inventory, returning zero candidates. It asked before broadening; after separate approval, its second MCP call returned five candidates and it produced a provisional recommendation. No application code, providers, candidate inference or deployments were performed by that session. Anonymous MCP access and use of the device key on the JSON API both returned 401, while authenticated tool discovery succeeded.
+
+These are integration observations, not a general guarantee that every agent follows the skill. Both search responses reported stale/degraded source data, including incomplete Parallel research. Their approximately 228,000- and 538,000-character payloads exceeded Desktop's inline tool limit; Claude recovered through saved tool-result files. The flow works, but these checks do not establish catalogue freshness, task accuracy or small response size. A separate recovery-path check exposed an obsolete preview install command in the MCP 401 message; its stable-command regression test failed before the source correction and passed afterward. Hosted correction is a separate deployment from the npm release.
+
 ## Published preview.5 acceptance — 17 October 2026
 
 Published `0.1.7-preview.5` to npm's `preview` channel after all **679 repository tests**, syntax/type checks, builds and documentation checks passed, including 336 Scout tests. Registry integrity matches the reviewed tarball and stable `latest` remains `0.1.6`. All 101 packaged files are accounted for; runtime bytes, public exports and legal metadata are unchanged from preview.4. Version metadata and public guides carry this release. The frozen package contains the preparation record; this post-publication result is maintained here after the registry and VM checks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openmerit",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Evidence-driven model decisions for coding harnesses.",
   "type": "module",
   "bin": {