modelstat 0.0.7 → 0.0.10

package/dist/cli.mjs

@@ -67,6 +67,12 @@ var init_enums = __esm({
       "raw_sdk_anthropic",
       "raw_sdk_openai",
       "raw_sdk_google",
+      // Web chat UIs (Chrome-extension companion). Categorically distinct
+      // from *_cli / *_desktop tools — same provider, different surface.
+      "chatgpt_web",
+      "claude_web",
+      "gemini_web",
+      "grok_web",
       "unknown"
     ];
     PROVIDERS = [
@@ -117,6 +123,7 @@ var init_enums = __esm({
       "snap",
       "manual",
       "docker",
+      "chrome_extension",
       "unknown"
     ];
     OS_FAMILIES = ["macos", "linux", "windows", "other"];
@@ -4258,7 +4265,7 @@ var init_zod = __esm({
 });
 
 // ../../packages/core/src/schemas.ts
-var TokenUsage, TaxonomyHint, SessionSegmentSummary, SessionSummary, GitContext, RawEvent, IngestBatch, DeviceEnrollment, DetectedInstallation, DetectedIdentity, DiscoveryReport, ClassificationConfidenceEnum;
+var TokenUsage, TaxonomyHint, SessionSegmentSummary, SessionSummary, GitContext, RawEvent, IngestBatch, DeviceEnrollment, DeviceSelfRegister, DeviceClaimRequest, ProcessingMetadata, RedactionPolicy, DetectedInstallation, DetectedIdentity, DiscoveryReport, ClassificationConfidenceEnum;
 var init_schemas = __esm({
   "../../packages/core/src/schemas.ts"() {
     "use strict";
@@ -4375,6 +4382,51 @@ var init_schemas = __esm({
       arch: external_exports.enum(["x86_64", "arm64", "other"]),
       agent_version: external_exports.string().max(40)
     });
+    DeviceSelfRegister = external_exports.object({
+      /** Agent-generated UUIDv7 — must pass shape + recent-timestamp checks. */
+      device_uuid: external_exports.string(),
+      /** Base64-encoded ed25519 public key, exactly 32 raw bytes. Optional
+       * but recommended (used for sender-constrained tokens / DPoP later). */
+      public_key: external_exports.string().optional(),
+      /** Free-form snapshot shown to the human on the claim page so they
+       * can sanity-check what they're claiming. */
+      fingerprint: external_exports.object({
+        hostname: external_exports.string().max(120).optional(),
+        os: external_exports.string().max(60).optional(),
+        os_family: external_exports.enum(OS_FAMILIES).optional(),
+        os_version: external_exports.string().max(60).optional(),
+        arch: external_exports.enum(["x86_64", "arm64", "other"]).optional(),
+        agent: external_exports.string().max(80).optional(),
+        agent_version: external_exports.string().max(40).optional()
+        // Allow extra fields for forward-compat without breaking old agents.
+      }).catchall(external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean()])).default({})
+    });
+    DeviceClaimRequest = external_exports.object({
+      claim_code: external_exports.string().max(40),
+      /** Optional org_id if the user belongs to multiple orgs and wants to
+       * claim into a specific one. Defaults to personal org. */
+      org_id: external_exports.string().uuid().optional()
+    });
+    ProcessingMetadata = external_exports.object({
+      redacted_by: external_exports.string().max(120).optional(),
+      redaction_policy: external_exports.string().max(80).optional(),
+      redaction_policy_version: external_exports.string().max(20).optional(),
+      redactions_applied: external_exports.number().int().min(0).optional(),
+      compacted: external_exports.boolean().optional(),
+      summarized: external_exports.boolean().optional(),
+      bytes_saved: external_exports.number().int().min(0).optional(),
+      changes_applied: external_exports.number().int().min(0).optional(),
+      original_size_bytes: external_exports.number().int().min(0).optional(),
+      uploaded_size_bytes: external_exports.number().int().min(0).optional()
+    });
+    RedactionPolicy = external_exports.object({
+      name: external_exports.string().max(60),
+      version: external_exports.string().max(20),
+      description: external_exports.string().max(400),
+      redacts: external_exports.array(external_exports.string()).max(40),
+      is_default: external_exports.boolean().default(false),
+      recommended_for: external_exports.string().max(160).optional()
+    });
     DetectedInstallation = external_exports.object({
       tool: external_exports.enum(TOOLS),
       install_method: external_exports.enum(INSTALL_METHODS),
@@ -5149,7 +5201,7 @@ function machineId() {
 function defaultUserEmail() {
   return process.env.AGENT_USER_EMAIL ?? state.userEmail ?? "aram@dev.local";
 }
-var here, store, state;
+var here, DEFAULT_API_URL, LEGACY_LOCALHOST_API, store, state;
 var init_config = __esm({
   "src/config.ts"() {
     "use strict";
@@ -5162,20 +5214,35 @@ var init_config = __esm({
       }
       if (d === "/") break;
     }
+    DEFAULT_API_URL = "https://modelstat.ai";
+    LEGACY_LOCALHOST_API = "http://localhost:3010";
     store = new Conf({
       projectName: "modelstat-agent-dev",
       defaults: {
-        apiUrl: process.env.AGENT_API_URL ?? "http://localhost:3010",
+        // Intentionally empty — the apiUrl getter below computes this
+        // from env + stored value + DEFAULT_API_URL. Keeping the stored
+        // default empty avoids freezing a stale value into the config
+        // file the way 0.0.7 did.
+        apiUrl: "",
         bearerToken: null,
         deviceId: null,
+        deviceUuid: null,
+        claimCode: null,
+        claimUrl: null,
         userEmail: null,
         defaultOrgId: null,
         cursor: {}
       }
     });
     state = {
+      /** Resolution order: env var → stored value (if user ran `setApiUrl`
+       * or paired pre-0.0.8) → production default. The legacy localhost
+       * value is ignored so upgrades from 0.0.7 self-heal. */
       get apiUrl() {
-        return store.get("apiUrl");
+        if (process.env.AGENT_API_URL) return process.env.AGENT_API_URL;
+        const stored = store.get("apiUrl");
+        if (stored && stored !== LEGACY_LOCALHOST_API) return stored;
+        return DEFAULT_API_URL;
       },
       setApiUrl(v) {
         store.set("apiUrl", v);
@@ -5198,6 +5265,24 @@ var init_config = __esm({
       setUserEmail(v) {
         store.set("userEmail", v);
       },
+      get deviceUuid() {
+        return store.get("deviceUuid");
+      },
+      setDeviceUuid(v) {
+        store.set("deviceUuid", v);
+      },
+      get claimCode() {
+        return store.get("claimCode");
+      },
+      setClaimCode(v) {
+        store.set("claimCode", v);
+      },
+      get claimUrl() {
+        return store.get("claimUrl");
+      },
+      setClaimUrl(v) {
+        store.set("claimUrl", v);
+      },
       getCursor(path) {
         return store.get("cursor")[path];
       },
@@ -5215,6 +5300,27 @@ var init_config = __esm({
 
 // src/api.ts
 import { request } from "undici";
+async function selfRegister(input) {
+  const res = await request(`${state.apiUrl}/v1/devices/self-register`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(input)
+  });
+  if (res.statusCode >= 300) {
+    throw new Error(`self-register failed: ${res.statusCode} ${await res.body.text()}`);
+  }
+  return await res.body.json();
+}
+async function fetchDeviceMe(secret) {
+  const res = await request(`${state.apiUrl}/v1/devices/me`, {
+    method: "GET",
+    headers: { authorization: `Bearer ${secret}` }
+  });
+  if (res.statusCode >= 300) {
+    throw new Error(`devices/me failed: ${res.statusCode} ${await res.body.text()}`);
+  }
+  return await res.body.json();
+}
 async function startDeviceCode() {
   const res = await request(`${state.apiUrl}/v1/auth/device_code`, {
     method: "POST",
@@ -5800,6 +5906,7 @@ init_api();
 init_config();
 init_scan();
 import { spawn } from "child_process";
+import { randomBytes } from "crypto";
 import { platform as platform4, release, arch as cpuArch, hostname as hostname2 } from "os";
 import { setTimeout as delay } from "timers/promises";
 
@@ -6044,6 +6151,78 @@ function osArch() {
   if (a === "arm64") return "arm64";
   return "other";
 }
+function generateUuidV7() {
+  const ms = Date.now();
+  const tsHex = ms.toString(16).padStart(12, "0");
+  const rand = randomBytes(10);
+  rand[0] = rand[0] & 15 | 112;
+  rand[2] = rand[2] & 63 | 128;
+  const hex = tsHex + rand.toString("hex");
+  return [
+    hex.slice(0, 8),
+    hex.slice(8, 12),
+    hex.slice(12, 16),
+    hex.slice(16, 20),
+    hex.slice(20, 32)
+  ].join("-");
+}
+async function cmdSelfRegister() {
+  const deviceUuid = state.deviceUuid ?? generateUuidV7();
+  const fingerprint = {
+    hostname: hostname2(),
+    os_family: osFamily(),
+    os_version: release(),
+    arch: osArch(),
+    agent: "modelstat-agent-dev",
+    agent_version: AGENT_VERSION3
+  };
+  const res = await selfRegister({
+    device_uuid: deviceUuid,
+    fingerprint
+  });
+  state.setDeviceUuid(res.device_uuid);
+  state.setDeviceId(res.device_id);
+  state.setBearer(res.device_secret);
+  state.setClaimCode(res.claim_code);
+  state.setClaimUrl(res.claim_url);
+  console.log(`\u2713 self-registered`);
+  console.log(`  device_uuid:    ${res.device_uuid}`);
+  console.log(`  device_id:      ${res.device_id}`);
+  console.log(`  secret_prefix:  ${res.secret_prefix}\u2026`);
+  console.log();
+  console.log(`  Claim this device to attach it to your account:`);
+  console.log(`    ${res.claim_url}`);
+  console.log(`    code: ${res.claim_code}`);
+  console.log();
+  console.log(`  state: ${state.storePath}`);
+}
+async function cmdAwaitClaim() {
+  const secret = state.bearer;
+  if (!secret) {
+    console.error("not registered \u2014 run `modelstat self-register` first");
+    process.exit(1);
+  }
+  const url = state.claimUrl ?? "(visit your dashboard)";
+  console.log(`waiting for human to claim this device:
+    ${url}
+`);
+  while (true) {
+    let me;
+    try {
+      me = await fetchDeviceMe(secret);
+    } catch (e) {
+      console.error(`poll failed: ${e.message}`);
+      await delay(5e3);
+      continue;
+    }
+    if (me.status === "claimed") {
+      console.log(`\u2713 claimed by user_id=${me.user_id}`);
+      return;
+    }
+    process.stdout.write(".");
+    await delay(2e3);
+  }
+}
 async function cmdRegister() {
   const email = defaultUserEmail();
   const res = await enrollDevice({
@@ -6055,6 +6234,9 @@ async function cmdRegister() {
     agent_version: AGENT_VERSION3,
     user_email: email
   });
+  if (!res.bearer_token || !res.device_id) {
+    throw new Error("enroll response missing bearer or device_id");
+  }
   state.setBearer(res.bearer_token);
   state.setDeviceId(res.device_id);
   state.setUserEmail(email);
@@ -6064,28 +6246,103 @@ async function cmdRegister() {
   console.log(`  bearer:    ${res.bearer_token.slice(0, 16)}\u2026`);
   console.log(`  state:     ${state.storePath}`);
 }
-async function cmdConnect() {
-  const init = await startDeviceCode();
-  const url = init.verification_url;
-  const opened = tryOpenBrowser(url);
-  const line = "\u2501".repeat(60);
-  console.log();
-  console.log(line);
-  console.log(
-    opened ? "  Opening your browser to approve this device\u2026" : "  Open this URL in any browser to approve this device:"
+var DASHBOARD_URL = "https://modelstat.ai/dashboard";
+function emitEvent(opts, event, fields = {}) {
+  if (!opts.json) return;
+  process.stdout.write(
+    `${JSON.stringify({ v: 1, ts: Date.now(), event, ...fields })}
+`
   );
+}
+async function cmdConnect(opts) {
+  if (!state.deviceUuid || !state.bearer || !state.deviceId) {
+    await cmdSelfRegister();
+  }
+  const claimCode = state.claimCode ?? "(unknown)";
+  const claimUrl = state.claimUrl ?? `https://modelstat.ai/d/${claimCode}`;
+  const agentUrl = `https://modelstat.ai/da/${claimCode}`;
+  emitEvent(opts, "registered", {
+    device_uuid: state.deviceUuid,
+    device_id: state.deviceId,
+    claim_code: claimCode,
+    claim_url: claimUrl,
+    agent_url: agentUrl
+  });
+  let serviceOk = false;
+  try {
+    const svc = installService();
+    serviceOk = true;
+    emitEvent(opts, "service_installed", { path: svc.path, logs: svc.logs });
+  } catch (e) {
+    emitEvent(opts, "service_install_failed", { error: e.message });
+  }
+  if (!opts.json) {
+    const line = "\u2501".repeat(60);
+    console.log();
+    console.log(line);
+    console.log(`  \u2713 Device registered \u2014 streaming your AI usage to modelstat.`);
+    console.log();
+    console.log(`  Open your dashboard (no sign-up needed):`);
+    console.log(`    \x1B[1;36m${claimUrl}\x1B[0m`);
+    console.log();
+    console.log(`  Agent-friendly (for LLMs / MCPs):`);
+    console.log(`    \x1B[2m${agentUrl}\x1B[0m`);
+    console.log();
+    console.log(`  Claim this device so it keeps analyzing past 100M tokens/mo:`);
+    console.log(`    \x1B[2m${claimUrl}/claim\x1B[0m`);
+    console.log(line);
+    console.log();
+  }
+  if (!opts.noBrowser) {
+    const opened = tryOpenBrowser(claimUrl);
+    emitEvent(opts, "browser_open_attempted", { opened });
+  }
+  emitEvent(opts, "done", { claim_url: claimUrl, agent_url: agentUrl });
+  if (serviceOk) {
+    return;
+  }
+  if (opts.json) {
+    return;
+  }
+  console.log("  Service install not supported on this platform \u2014 running in foreground.");
+  console.log("  Press Ctrl-C to stop.");
   console.log();
-  console.log(`    \x1B[1;36m${url}\x1B[0m`);
-  console.log();
-  console.log("  Pairing code (if you'd rather type it manually):");
-  console.log();
-  console.log(`    \x1B[1;33m${init.user_code}\x1B[0m`);
-  console.log();
-  console.log(`  Waiting for approval (expires in ${init.expires_in}s)`);
-  console.log(line);
-  console.log();
+  const { runDaemon: runDaemon2 } = await Promise.resolve().then(() => (init_daemon(), daemon_exports));
+  await runDaemon2();
+}
+async function cmdConnectOAuth(opts) {
+  const init = await startDeviceCode();
+  const url = init.verification_url;
+  emitEvent(opts, "device_code_issued", {
+    verification_url: url,
+    user_code: init.user_code,
+    expires_in: init.expires_in,
+    interval: init.interval
+  });
+  const opened = opts.noBrowser ? false : tryOpenBrowser(url);
+  if (!opts.noBrowser) {
+    emitEvent(opts, "browser_open_attempted", { opened });
+  }
+  if (!opts.json) {
+    const line = "\u2501".repeat(60);
+    console.log();
+    console.log(line);
+    console.log(
+      opened ? "  Opening your browser to approve this device\u2026" : "  Open this URL in any browser to approve this device:"
+    );
+    console.log();
+    console.log(`    \x1B[1;36m${url}\x1B[0m`);
+    console.log();
+    console.log("  Pairing code:");
+    console.log(`    \x1B[1;33m${init.user_code}\x1B[0m`);
+    console.log();
+    console.log(`  Waiting for approval (expires in ${init.expires_in}s)`);
+    console.log(line);
+    console.log();
+  }
   const deadline = Date.now() + init.expires_in * 1e3;
   let dots = 0;
+  let lastPollEmit = 0;
   while (Date.now() < deadline) {
     await delay(init.interval * 1e3);
     try {
@@ -6093,8 +6350,11 @@ async function cmdConnect() {
       if (res.status === "approved") {
         state.setBearer(res.bearer_token);
         state.setUserEmail(`user:${res.user_id}`);
-        console.log();
-        console.log("\u2713 approved \u2014 bearer stored");
+        emitEvent(opts, "approved", { user_id: res.user_id });
+        if (!opts.json) {
+          console.log();
+          console.log("\u2713 approved \u2014 bearer stored");
+        }
         let enroll = null;
         try {
           enroll = await enrollDevice({
@@ -6106,43 +6366,72 @@ async function cmdConnect() {
             agent_version: AGENT_VERSION3
           });
         } catch (e) {
-          console.error();
-          console.error(`\u2717 device enrollment failed: ${e.message}`);
-          console.error(
-            "  The approval went through but the server couldn't register this"
-          );
-          console.error(
-            "  machine. Check that your modelstat API is reachable at"
-          );
-          console.error(`  ${state.apiUrl} \u2014 then run \`modelstat connect\` again.`);
+          const message = e.message;
+          emitEvent(opts, "error", { code: "enroll_failed", message });
+          if (!opts.json) {
+            console.error();
+            console.error(`\u2717 device enrollment failed: ${message}`);
+            console.error(
+              "  The approval went through but the server couldn't register this"
+            );
+            console.error(
+              "  machine. Check that your modelstat API is reachable at"
+            );
+            console.error(`  ${state.apiUrl} \u2014 then run \`modelstat connect\` again.`);
+          }
           process.exit(1);
         }
         if (!enroll?.device_id) {
-          console.error("\n\u2717 enrollment returned no device_id. Aborting.");
+          emitEvent(opts, "error", {
+            code: "enroll_failed",
+            message: "enrollment returned no device_id"
+          });
+          if (!opts.json) {
+            console.error("\n\u2717 enrollment returned no device_id. Aborting.");
+          }
           process.exit(1);
         }
         state.setDeviceId(enroll.device_id);
-        console.log(`\u2713 device registered  (${enroll.device_id.slice(0, 8)}\u2026)`);
+        emitEvent(opts, "device_enrolled", { device_id: enroll.device_id });
+        if (!opts.json) {
+          console.log(`\u2713 device registered  (${enroll.device_id.slice(0, 8)}\u2026)`);
+        }
         try {
           const svc = installService();
-          console.log(`\u2713 service installed    (${svc.path})`);
-          console.log(`  logs:                ${svc.logs}`);
-          console.log();
-          const banner = "\u2501".repeat(60);
-          console.log(banner);
-          console.log("  You're connected. The agent is now running in the");
-          console.log("  background and will start on login.");
-          console.log();
-          console.log("  Manage it from the dashboard:");
-          console.log("    \x1B[1;36mhttps://modelstat.ai/dashboard\x1B[0m");
-          console.log();
-          console.log("  Stop it any time:   \x1B[2mmodelstat stop\x1B[0m");
-          console.log("  Uninstall:          \x1B[2mmodelstat uninstall\x1B[0m");
-          console.log(banner);
+          emitEvent(opts, "service_installed", {
+            path: svc.path,
+            logs: svc.logs
+          });
+          if (!opts.json) {
+            console.log(`\u2713 service installed    (${svc.path})`);
+            console.log(`  logs:                ${svc.logs}`);
+            console.log();
+            const banner = "\u2501".repeat(60);
+            console.log(banner);
+            console.log("  You're connected. The agent is now running in the");
+            console.log("  background and will start on login.");
+            console.log();
+            console.log("  Manage it from the dashboard:");
+            console.log(`    \x1B[1;36m${DASHBOARD_URL}\x1B[0m`);
+            console.log();
+            console.log("  Stop it any time:   \x1B[2mmodelstat stop\x1B[0m");
+            console.log("  Uninstall:          \x1B[2mmodelstat uninstall\x1B[0m");
+            console.log(banner);
+          }
+          emitEvent(opts, "done", { dashboard_url: DASHBOARD_URL });
           return;
         } catch (err) {
+          const message = err.message;
+          emitEvent(opts, "service_install_failed", {
+            error: message,
+            fallback: opts.json ? "manual" : "foreground"
+          });
+          if (opts.json) {
+            emitEvent(opts, "done", { dashboard_url: DASHBOARD_URL });
+            return;
+          }
           console.warn();
-          console.warn(`\u26A0 couldn't install as a background service: ${err.message}`);
+          console.warn(`\u26A0 couldn't install as a background service: ${message}`);
           console.warn("  Running in the foreground instead \u2014 press Ctrl-C to stop.");
           console.warn("  (Install globally with `npm i -g modelstat` then re-run `modelstat connect`.)");
           console.warn();
@@ -6152,13 +6441,31 @@ async function cmdConnect() {
         }
       }
     } catch (e) {
-      if (dots % 15 === 0) console.warn(`
+      if (dots % 15 === 0 && !opts.json) {
+        console.warn(`
 [retry] ${e.message}`);
+      }
     }
     dots += 1;
-    process.stdout.write(".");
+    if (opts.json) {
+      const now = Date.now();
+      if (now - lastPollEmit >= 1e4) {
+        emitEvent(opts, "polling", {
+          seconds_remaining: Math.max(0, Math.round((deadline - now) / 1e3))
+        });
+        lastPollEmit = now;
+      }
+    } else {
+      process.stdout.write(".");
+    }
+  }
+  emitEvent(opts, "error", {
+    code: "device_code_expired",
+    message: "device_code expired before approval"
+  });
+  if (!opts.json) {
+    console.error("\ndevice_code expired before approval");
   }
-  console.error("\ndevice_code expired before approval");
   process.exit(1);
 }
 async function cmdDiscover() {
@@ -6211,22 +6518,58 @@ async function cmdStatus() {
   if (paired) {
     console.log(`  user:    ${state.userEmail ?? "(unknown)"}`);
     console.log(`  device:  ${state.deviceId}`);
+    console.log(`  uuid:    ${state.deviceUuid ?? "(not self-registered)"}`);
   }
   console.log(`service: ${s.running ? "running" : "stopped"}  (${s.hint})`);
   console.log(`logs:    ${logsDir()}`);
   console.log(`state:   ${state.storePath}`);
+  console.log(`api:     ${state.apiUrl}`);
+}
+function cmdPaths(args) {
+  const data = {
+    state: state.storePath,
+    logs: logsDir(),
+    api: state.apiUrl,
+    paired: !!state.bearer && !!state.deviceId
+  };
+  if (args.includes("--json")) {
+    process.stdout.write(`${JSON.stringify(data)}
+`);
+    return;
+  }
+  for (const [k, v] of Object.entries(data)) {
+    console.log(`${k.padEnd(8)} ${String(v)}`);
+  }
+}
+function parseConnectOpts(argv) {
+  return {
+    json: argv.includes("--json"),
+    noBrowser: argv.includes("--no-browser"),
+    // --oauth selects the legacy device-code flow (for users who
+    // already have an account and want to stream straight into their
+    // personal org). Default is the new self-register flow.
+    oauth: argv.includes("--oauth")
+  };
 }
 async function main() {
   const cmd = process.argv[2];
+  const rest = process.argv.slice(3);
   switch (cmd) {
     case void 0:
     case "start":
-      if (!state.bearer || !state.deviceId) return cmdConnect();
+      if (!state.bearer || !state.deviceId)
+        return cmdConnect(parseConnectOpts(rest));
       return cmdStart();
-    case "connect":
-      return cmdConnect();
+    case "connect": {
+      const opts = parseConnectOpts(rest);
+      return opts.oauth ? cmdConnectOAuth(opts) : cmdConnect(opts);
+    }
     case "register":
       return cmdRegister();
+    case "self-register":
+      return cmdSelfRegister();
+    case "await-claim":
+      return cmdAwaitClaim();
     case "discover":
       return cmdDiscover();
     case "scan":
@@ -6238,20 +6581,28 @@ async function main() {
       return cmdStop();
     case "status":
       return cmdStatus();
+    case "paths":
+      cmdPaths(rest);
+      return;
     default:
       console.log(
-        "usage: modelstat [connect|status|stop|start|discover|scan|watch|register]"
+        "usage: modelstat [connect|self-register|await-claim|status|paths|stop|start|discover|scan|watch|register]"
       );
       console.log();
-      console.log("  (no args)   \u2014 pair if needed, then run the daemon in the foreground");
-      console.log("  connect     \u2014 pair + install as a background service, then exit");
-      console.log("  status      \u2014 show pairing + service state");
-      console.log("  stop        \u2014 stop and uninstall the background service");
-      console.log("  start       \u2014 run the daemon (used by the installed service)");
-      console.log("  discover    \u2014 one-shot report of installs/identities");
-      console.log("  scan        \u2014 one-shot parse + upload of local JSONL");
-      console.log("  watch       \u2014 continuous (chokidar) with periodic backstop");
-      console.log("  register    \u2014 DEV shortcut (email-only, no OAuth)");
+      console.log("  (no args)       \u2014 pair if needed, then run the daemon in the foreground");
+      console.log("  connect         \u2014 OAuth device-code pair + install service, then exit");
+      console.log("                    flags: --json (NDJSON events on stdout), --no-browser");
+      console.log("  self-register   \u2014 agent-first: generate UUIDv7, get device_secret + claim code");
+      console.log("                    (no human required for the first call)");
+      console.log("  await-claim     \u2014 block until a human claims this self-registered device");
+      console.log("  status          \u2014 show pairing + service state");
+      console.log("  paths           \u2014 print state file + log dir + api URL (use --json for machine-readable)");
+      console.log("  stop            \u2014 stop and uninstall the background service");
+      console.log("  start           \u2014 run the daemon (used by the installed service)");
+      console.log("  discover        \u2014 one-shot report of installs/identities");
+      console.log("  scan            \u2014 one-shot parse + upload of local JSONL");
+      console.log("  watch           \u2014 continuous (chokidar) with periodic backstop");
+      console.log("  register        \u2014 DEV shortcut (email-only, no OAuth)");
       process.exit(1);
   }
 }