syndes 0.1.0

package/bin/cli.mjs

@@ -0,0 +1,596 @@
+#!/usr/bin/env node
+/**
+ * The command line.
+ *
+ * Verbs match claude-noti and claude-tts wherever they overlap — install, off,
+ * on, doctor, uninstall — because these tools sit side by side in the same
+ * settings.json and the muscle memory should transfer.
+ */
+
+import { readFileSync, writeFileSync, existsSync, unlinkSync, mkdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { join } from 'node:path';
+import {
+  packageRoot, displayPath, dataDir, installDir, workerScript, pauseFile,
+  ensureDataDirs, installedCliScript, isInstalledCopy,
+} from '../runtime/paths.mjs';
+import {
+  bold, grey, cyan, green, red, yellow, write, rule, table, OK, FAIL, WARN, DOT,
+  confirm, compact, usd, duration, percent, bar, width, ask, pad, spinner, banner, beat, stream,
+} from '../src/term.mjs';
+import { install } from '../src/install.mjs';
+import { runBriefing, showBriefingIfPending, clearPending } from '../src/briefing.mjs';
+import { uninstall, purgeImpact } from '../src/uninstall.mjs';
+import { diagnose } from '../src/doctor.mjs';
+import { statusData, streak } from '../src/status.mjs';
+import { report, projectTable } from '../src/report.mjs';
+import { exportLedger } from '../src/export.mjs';
+import { verify } from '../ledger/verify.mjs';
+import { height, tail } from '../ledger/read.mjs';
+import { archive, prune, usage } from '../ledger/retention.mjs';
+import { append } from '../ledger/append.mjs';
+import { draft, KIND } from '../ledger/schema.mjs';
+import { updateRollups, clearRollups } from '../analytics/rollup.mjs';
+import { sessions as listSessions, byProject } from '../analytics/index.mjs';
+import { evaluate, runCoach } from '../practices/engine.mjs';
+import * as budget from '../practices/budget.mjs';
+import { loadConfig, rawConfig, saveConfig, getPath, setPath } from '../runtime/config.mjs';
+import { startServer } from '../dashboard/server.mjs';
+import { mode as authMode, setMode as setAuthMode, describe as describeAuth, MODES } from '../dashboard/auth.mjs';
+import { openUrl } from '../src/open.mjs';
+import { pendingCount } from '../runtime/spool.mjs';
+import { detectAll, adapterFor, ADAPTERS } from '../adapters/index.mjs';
+import { pollTails, resetCursors } from '../collect/tail.mjs';
+
+const VERSION = readVersion();
+
+const COMMANDS = {
+  install: cmdInstall, uninstall: cmdUninstall, doctor: cmdDoctor,
+  status: cmdStatus, report: cmdReport, dashboard: cmdDashboard, ui: cmdDashboard,
+  lock: cmdLock, verify: cmdVerify, sessions: cmdSessions,
+  sources: cmdSources, watch: cmdWatch,
+  projects: cmdProjects, practices: cmdPractices, habits: cmdPractices, coach: cmdCoach,
+  ledger: cmdLedger, export: cmdExport, rebuild: cmdRebuild, drain: cmdDrain,
+  archive: cmdArchive, prune: cmdPrune, config: cmdConfig,
+  on: cmdOn, off: cmdOff, pause: cmdOff, mute: cmdMute, unmute: cmdUnmute,
+  version: () => write(`syndes ${VERSION}`),
+  help: usage_,
+};
+
+await main();
+
+async function main() {
+  const [verb = 'status', ...args] = process.argv.slice(2);
+  const command = COMMANDS[verb];
+
+  if (!command) {
+    write(`${FAIL} unknown command: ${verb}`);
+    usage_();
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    // A postinstall owes the user an explanation; pay it before anything else.
+    if (verb !== 'install') await showBriefingIfPending();
+    await command(args);
+  } catch (error) {
+    write(`${FAIL} ${error.message}`);
+    if (process.env.SYNDES_DEBUG === '1') write(grey(error.stack));
+    process.exitCode = 1;
+  }
+}
+
+// ── Lifecycle ───────────────────────────────────────────────────────────────
+
+async function cmdInstall(args) {
+  const repair = args.includes('--repair');
+  banner();
+
+  const copy = spinner(repair ? 'Repairing the installed copy' : 'Copying to a stable home');
+  await beat();
+  let result;
+  try {
+    result = await install({ repair });
+  } catch (error) {
+    copy.fail(error.message);
+    throw error;
+  }
+  const steps = Object.fromEntries(result.steps.map((step) => [step.step, step]));
+  if (steps.copy?.skipped) copy.skip(steps.copy.detail);
+  else copy.succeed(displayPath(installDir));
+
+  const key = spinner('Minting the chain key');
+  await beat();
+  key.succeed(steps.key?.detail);
+
+  const chain = spinner('Opening the ledger');
+  await beat();
+  chain.succeed(steps.ledger?.detail);
+
+  const hooks = spinner('Wiring Claude Code hooks');
+  await beat();
+  hooks.succeed(`${result.events.length} events`);
+
+  // Other agents are found, not configured: a tail source needs no wiring.
+  const scan = spinner('Looking for other agents');
+  await beat(140);
+  const found = detectAll().filter((agent) => agent.present && agent.id !== 'claude-code');
+  if (found.length) scan.succeed(found.map((agent) => agent.name).join(', '));
+  else scan.skip('none besides Claude Code');
+
+  await runBriefing(result);
+  clearPending();
+}
+
+async function cmdUninstall(args) {
+  const purge = args.includes('--purge');
+
+  if (purge) {
+    const impact = purgeImpact();
+    write(`${WARN} this deletes ${bold(String(impact.records))} records (${Math.round(impact.bytes / 1024)}KB) from ${displayPath(impact.path)}`);
+    write(grey('  the ledger is append-only; there is no undo and no backup'));
+    if (process.stdin.isTTY && !(await confirm('Delete the ledger?'))) return write('cancelled');
+  }
+
+  const result = uninstall({ purge });
+  for (const step of result.steps) {
+    write(`  ${step.destructive ? red('x') : OK} ${step.step.padEnd(7)} ${grey(step.detail)}`);
+  }
+  write();
+  write(`${OK} uninstalled${purge ? ' and purged' : ''}`);
+  if (!purge) write(grey(`  your history is still at ${displayPath(dataDir)}`));
+}
+
+async function cmdDoctor(args) {
+  const result = await diagnose({ deep: args.includes('--full') });
+  write();
+  write(bold('syndes doctor'));
+  write(rule(width()));
+
+  for (const check of result.checks) {
+    const mark = check.ok === true ? OK : check.ok === false ? FAIL : grey(DOT);
+    write(`  ${mark} ${check.name.padEnd(20)} ${check.ok === false ? check.detail : grey(check.detail)}`);
+    if (check.fix) write(`     ${cyan('→')} ${check.fix}`);
+  }
+
+  write();
+  write(result.failures
+    ? `${FAIL} ${result.failures} problem${result.failures === 1 ? '' : 's'}`
+    : `${OK} everything checks out`);
+  if (result.failures) process.exitCode = 1;
+}
+
+// ── Reading ─────────────────────────────────────────────────────────────────
+
+async function cmdStatus() {
+  const data = await statusData('7d');
+
+  if (!data.installed) {
+    write();
+    write(`${WARN} not installed — nothing is being recorded`);
+    write(`  ${cyan('→')} syndes install`);
+    write();
+    return;
+  }
+
+  write();
+  write(`${bold('syndes')} ${grey(DOT)} today`);
+  write(rule(Math.min(58, width())));
+
+  const today = data.today;
+  write(table([
+    [grey('prompts'), String(today.prompts), grey('tool calls'), compact(today.toolCalls)],
+    [grey('active'), duration(today.activeMs), grey('tokens'), compact(today.tokens)],
+    [grey('files'), String(today.files), grey('cost'), usd(today.usd)],
+  ], { align: ['left', 'right', 'left', 'right'] }).map((line) => `  ${line}`).join('\n'));
+
+  write();
+  if (data.score.total !== null) {
+    write(`  ${grey('7-day score')}  ${bar(data.score.total / 100, 20)} ${bold(String(data.score.total))}${grey('/100')}`);
+  }
+  write(`  ${grey('streak')}       ${data.streak} day${data.streak === 1 ? '' : 's'}`);
+  write(`  ${grey('ledger')}       ${data.ledger.seq + 1} records${data.pending ? yellow(` · ${data.pending} pending`) : ''}`);
+
+  if (data.paused) write(`  ${WARN} ${yellow('tracking is paused')}${data.paused.until ? grey(` until ${new Date(data.paused.until).toLocaleTimeString()}`) : ''}`);
+
+  write();
+  write(grey(`  ${cyan('syndes report')} for the week  ${DOT}  ${cyan('syndes dashboard')} for everything`));
+  write();
+}
+
+async function cmdReport(args) {
+  await report(args[0] ?? '7d');
+}
+
+async function cmdSessions(args) {
+  const rows = await listSessions(args[0] ?? '7d');
+  if (!rows.length) return write(grey('no sessions in range'));
+
+  write();
+  write(table([
+    [grey('started'), grey('project'), grey('dur'), grey('active'), grey('prompts'), grey('tools'), grey('tokens')],
+    ...rows.slice(0, 25).map((session) => [
+      new Date(session.startedAt).toLocaleString(undefined, { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' }),
+      (session.projectName ?? '—').slice(0, 22),
+      duration(session.durationMs),
+      session.ended ? grey(session.reason ?? 'ended') : green('open'),
+      String(session.prompts), String(session.toolCalls), compact(session.tokens),
+    ]),
+  ], { align: ['left', 'left', 'right', 'left', 'right', 'right', 'right'] }).map((line) => `  ${line}`).join('\n'));
+  write();
+}
+
+async function cmdProjects(args) {
+  const rows = await byProject(args[0] ?? '30d');
+  if (!rows.length) return write(grey('no projects in range'));
+  write();
+  write(projectTable(rows).map((line) => `  ${line}`).join('\n'));
+  write();
+}
+
+async function cmdPractices(args) {
+  if (args[0] === '--reset') {
+    budget.save({ lastByRule: {}, sent: {}, dismissed: {}, muted: [], snoozedUntil: 0 });
+    return write(`${OK} coach state reset`);
+  }
+
+  const findings = await evaluate();
+  write();
+  if (!findings.length) {
+    write(`  ${green('nothing flagged')} ${grey('— no rule found a pattern worth changing')}`);
+    write();
+    return;
+  }
+
+  for (const finding of findings) {
+    const mark = finding.severity >= 3 ? red('!!') : finding.severity === 2 ? yellow(' !') : grey(' ·');
+    write(`  ${mark} ${bold(finding.title)} ${grey(`[${finding.id}]`)}${finding.muted ? red(' muted') : ''}`);
+    write(`     ${finding.evidence}`);
+    write(`     ${grey(finding.why)}`);
+    write(`     ${cyan('→')} ${finding.fix}`);
+    if (finding.action) write(`     ${cyan('→')} ${finding.action}`);
+    if (!finding.deliverable && !finding.muted) write(`     ${grey(`(not notifying: ${finding.blockedBy})`)}`);
+    write();
+  }
+  write(grey(`  syndes mute <id> to silence one  ${DOT}  --reset to clear all state`));
+  write();
+}
+
+async function cmdCoach() {
+  const result = await runCoach({ force: true });
+  if (!result.sent) return write(grey(`nothing to send: ${result.reason}`));
+  write(`${OK} sent "${result.sent.title}" via ${result.channels.join(', ') || 'no channel'}`);
+}
+
+function cmdMute(args) {
+  if (!args[0]) throw new Error('usage: syndes mute <rule-id>');
+  budget.save(budget.mute(budget.load(), args[0]));
+  write(`${OK} muted ${args[0]}`);
+}
+
+function cmdUnmute(args) {
+  if (!args[0]) throw new Error('usage: syndes unmute <rule-id>');
+  budget.save(budget.unmute(budget.load(), args[0]));
+  write(`${OK} unmuted ${args[0]}`);
+}
+
+// ── The chain ───────────────────────────────────────────────────────────────
+
+async function cmdVerify(args) {
+  const full = args.includes('--full');
+  write();
+  write(grey(`walking the chain${full ? ' and every seal' : ''}…`));
+
+  const result = await verify({ full });
+  write();
+  if (result.ok) {
+    write(`${OK} ${bold(String(result.records))} records across ${result.days} day${result.days === 1 ? '' : 's'} verify clean`);
+    write(grey(`  tip: seq ${result.tip?.seq} ${result.tip?.hash?.slice(0, 16)}…`));
+    if (full) write(grey(`  ${result.checkedSeals} seal${result.checkedSeals === 1 ? '' : 's'} match their segments`));
+  } else {
+    write(`${FAIL} ${result.problems.length} problem${result.problems.length === 1 ? '' : 's'} in ${result.records} records`);
+    for (const problem of result.problems.slice(0, 20)) {
+      write(`  ${red(problem.type)} at seq ${problem.seq ?? '?'} ${grey(problem.detail)}`);
+    }
+    process.exitCode = 1;
+  }
+  write();
+}
+
+async function cmdLedger(args) {
+  const limit = Number(args.find((arg) => /^\d+$/.test(arg)) ?? 20);
+  const records = await tail(limit);
+  write();
+  for (const record of records) {
+    write(`  ${grey(String(record.seq).padStart(6))} ${grey(new Date(record.ts).toLocaleTimeString())} ${cyan(record.kind.padEnd(16))} ${grey(JSON.stringify(record.data).slice(0, 90))}`);
+  }
+  const { bytes } = usage();
+  write();
+  write(grey(`  ${height().seq + 1} records ${DOT} ${Math.round(bytes / 1024)}KB ${DOT} ${displayPath(dataDir)}`));
+  write();
+}
+
+async function cmdExport(args) {
+  const format = (args.find((arg) => arg.startsWith('--format='))?.split('=')[1]) ?? 'ndjson';
+  const range = (args.find((arg) => arg.startsWith('--range='))?.split('=')[1]) ?? 'all';
+  const out = args.find((arg) => arg.startsWith('--out='))?.split('=')[1] ?? null;
+
+  const result = await exportLedger({ format, range, out, withProof: args.includes('--verify') });
+  if (out) write(`${OK} ${result.count} records → ${out}`);
+}
+
+async function cmdRebuild() {
+  clearRollups();
+  const result = await updateRollups({ all: true });
+  write(`${OK} rebuilt ${result.built.length} daily rollup${result.built.length === 1 ? '' : 's'} from the chain`);
+}
+
+/** Run the worker in the foreground, for when the spool has backed up. */
+async function cmdDrain() {
+  const pending = pendingCount();
+  write(grey(`draining ${pending} spooled event${pending === 1 ? '' : 's'}…`));
+  const result = spawnSync(process.execPath, [workerScript], { stdio: 'inherit' });
+  if (result.status !== 0) throw new Error('worker exited non-zero');
+  write(`${OK} spool now ${pendingCount()}`);
+}
+
+async function cmdArchive() {
+  const result = await archive();
+  write(`${OK} compressed ${result.archived.length} segment${result.archived.length === 1 ? '' : 's'}`);
+}
+
+async function cmdPrune(args) {
+  const dryRun = !args.includes('--yes');
+  const result = await prune({ dryRun });
+  if (!result.pruned.length) return write(grey(result.reason ?? 'nothing to prune'));
+
+  if (dryRun) {
+    write(`${WARN} would prune ${result.pruned.length} day(s): ${result.pruned.join(', ')}`);
+    write(grey('  a ledger.prune record is written first, so the gap stays declared'));
+    write(`  ${cyan('→')} syndes prune --yes`);
+    return;
+  }
+  write(`${OK} pruned ${result.pruned.length} day(s), declared in the chain`);
+}
+
+// ── Control ─────────────────────────────────────────────────────────────────
+
+async function cmdOn() {
+  if (existsSync(pauseFile)) unlinkSync(pauseFile);
+  await append([draft(KIND.TRACKING, { data: { state: 'on' } })]);
+  write(`${OK} tracking on`);
+}
+
+async function cmdOff(args) {
+  ensureDataDirs();
+  const spec = args[0];
+  const ms = spec ? parseDuration(spec) : null;
+
+  // Recorded BEFORE the pause takes effect: a gap in the chain must always be
+  // explained by the chain itself.
+  await append([draft(KIND.TRACKING, { data: { state: 'off', forMs: ms } })]);
+  mkdirSync(dataDir, { recursive: true });
+  writeFileSync(pauseFile, ms ? JSON.stringify({ until: Date.now() + ms }) : '');
+
+  write(`${OK} tracking off${ms ? ` for ${duration(ms)}` : ''} ${grey('· syndes on to resume')}`);
+}
+
+function parseDuration(spec) {
+  const match = /^(\d+)\s*(s|m|h|d)?$/.exec(String(spec).trim());
+  if (!match) throw new Error(`cannot read a duration from "${spec}" — try 30m, 2h, 1d`);
+  const units = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+  return Number(match[1]) * (units[match[2] ?? 'm']);
+}
+
+// ── Dashboard ───────────────────────────────────────────────────────────────
+
+async function cmdDashboard(args) {
+  const port = Number(args.find((arg) => arg.startsWith('--port='))?.split('=')[1]) || undefined;
+
+  let server;
+  try {
+    server = await startServer({ port });
+  } catch (error) {
+    // "EADDRINUSE" on its own tells the user nothing they can act on.
+    if (error.code === 'EADDRINUSE') {
+      const taken = port ?? loadConfig().dashboard.port;
+      write(`${FAIL} port ${taken} is already in use`);
+      write(`  ${cyan('→')} syndes dashboard --port=${taken + 1}`);
+      write(`  ${cyan('→')} or change it for good: syndes config dashboard.port ${taken + 1}`);
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  }
+  const { url, base, close } = server;
+  const lock = authMode();
+
+  write();
+  write(`${OK} dashboard on ${cyan(base)}`);
+  write(grey(`  ${DOT} ${lock === 'open'
+    ? 'opens straight in — the link below carries a one-time token'
+    : lock === 'system' ? 'your system will ask before it opens' : 'a PIN is required'}`));
+  write(grey(`  ${DOT} loopback only, read-only over the ledger`));
+  write(grey(`  ${DOT} ctrl-c to stop`));
+  if (lock === 'open') write(grey(`  ${DOT} link: ${url}`));
+  write();
+
+  if (loadConfig().dashboard.openOnStart && !args.includes('--no-open')) openUrl(url);
+
+  const stop = async () => { await close(); process.exit(0); };
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+}
+
+/** `syndes sources` — which agents SynDes can see, and how it reads them. */
+async function cmdSources() {
+  write();
+  write(`  ${bold('Agents')}`);
+  write();
+  const rows = detectAll().map((agent) => {
+    const adapter = adapterFor(agent.id);
+    const status = agent.present ? OK : grey(DOT);
+    const wired = agent.id === 'claude-code' && agent.present
+      ? (adapter.status?.().wired ? green('recording') : yellow('not installed'))
+      : agent.present ? green('following') : grey('not found');
+    return [status, bold(agent.name), grey(agent.capture === 'hook' ? 'hooks' : 'session files'), wired, grey(agent.detail)];
+  });
+  write(table(rows).map((line) => `  ${line}`).join('\n'));
+  write();
+  write(grey('  hooks        the agent calls SynDes on every event — full fidelity'));
+  write(grey('  session files  SynDes follows what the agent writes down — no setup needed'));
+  write();
+}
+
+/** `syndes watch` — poll other agents' session files on a loop. */
+async function cmdWatch(args) {
+  const seconds = Number(args.find((arg) => arg.startsWith('--every='))?.split('=')[1]) || 10;
+
+  if (args.includes('--reset')) {
+    resetCursors();
+    write(`${OK} tail cursors cleared — the next poll re-reads from the top`);
+    // Reset is an errand, not a mode. Falling through into the watch loop meant
+    // `watch --reset` in a script hung forever instead of returning.
+    if (!args.includes('--follow')) return;
+  }
+
+  const targets = detectAll().filter((agent) => agent.present && agent.capture === 'tail');
+  if (!targets.length) {
+    write(grey('  no tail-based agents found — nothing to watch'));
+    write(grey(`  ${cyan('syndes sources')} shows what SynDes can see`));
+    return;
+  }
+
+  if (!args.includes('--once')) {
+    write();
+    write(`${OK} watching ${targets.map((agent) => agent.name).join(', ')} ${grey(`every ${seconds}s`)}`);
+    write(grey('  ctrl-c to stop'));
+    write();
+  }
+
+  const tick = async () => {
+    const { drafts, lines } = pollTails({ firstRunSkipsHistory: false });
+    if (!drafts.length) return;
+    await append(drafts);
+    await updateRollups();
+    write(`  ${OK} ${drafts.length} record(s) from ${lines} new line(s) ${grey(new Date().toLocaleTimeString())}`);
+  };
+
+  await tick();
+  if (args.includes('--once')) return;
+
+  const timer = setInterval(() => { tick().catch(() => {}); }, seconds * 1000);
+  process.on('SIGINT', () => { clearInterval(timer); write(); process.exit(0); });
+}
+
+/** `syndes lock [open|system|pin]` */
+async function cmdLock(args) {
+  const requested = args[0];
+
+  if (!requested) {
+    const state = describeAuth();
+    write();
+    write(`  ${grey('current')}  ${bold(state.mode)}`);
+    write(`  ${grey('system')}   ${state.system.available ? `${state.system.method} available` : state.system.reason}`);
+    write();
+    write(grey('  syndes lock open    no prompt; the launch link is the key'));
+    write(grey('  syndes lock system  ask the operating system (Touch ID)'));
+    write(grey('  syndes lock pin     ask for a PIN you choose'));
+    write();
+    return;
+  }
+
+  if (!MODES.includes(requested)) throw new Error(`unknown lock: ${requested} — one of ${MODES.join(', ')}`);
+
+  let pin;
+  if (requested === 'pin') {
+    pin = await ask('Choose a PIN (4-12 digits): ', { silent: true });
+    const again = await ask('Confirm: ', { silent: true });
+    if (pin !== again) throw new Error('the two PINs did not match');
+  }
+
+  setAuthMode(requested, { pin });
+  write(`${OK} dashboard lock set to ${bold(requested)}`);
+  write(grey('  any open dashboard session has been signed out'));
+}
+
+// ── Config ──────────────────────────────────────────────────────────────────
+
+function cmdConfig(args) {
+  const [key, ...rest] = args;
+
+  if (!key) {
+    const config = loadConfig();
+    write();
+    for (const line of flatten(config)) write(`  ${grey(line[0].padEnd(30))} ${line[1]}`);
+    write();
+    return;
+  }
+
+  if (!rest.length) {
+    write(String(getPath(loadConfig(), key)));
+    return;
+  }
+
+  const value = parseValue(rest.join(' '));
+  const next = rawConfig();
+  setPath(next, key, value);
+  saveConfig(next);
+  write(`${OK} ${key} = ${JSON.stringify(value)}`);
+}
+
+function parseValue(text) {
+  if (text === 'true') return true;
+  if (text === 'false') return false;
+  if (text === 'null') return null;
+  if (/^-?\d+(\.\d+)?$/.test(text)) return Number(text);
+  return text;
+}
+
+function flatten(object, prefix = '') {
+  const out = [];
+  for (const [key, value] of Object.entries(object)) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    if (value && typeof value === 'object' && !Array.isArray(value)) out.push(...flatten(value, path));
+    else out.push([path, JSON.stringify(value)]);
+  }
+  return out;
+}
+
+// ── Help ────────────────────────────────────────────────────────────────────
+
+function usage_() {
+  write();
+  write(`${bold('syndes')} ${grey(VERSION)} ${grey(DOT)} a tamper-evident record of how you use Claude Code`);
+  write();
+  write(table([
+    [cyan('syndes'), 'today at a glance'],
+    [cyan('install'), 'wire the hooks and open the chain'],
+    [cyan('dashboard'), 'the full UI, password-locked, on 127.0.0.1'],
+    [cyan('report [range]'), 'terminal digest — today, 7d, 30d, all'],
+    [cyan('sessions [range]'), 'list sessions and how each one went'],
+    [cyan('projects [range]'), 'per-project breakdown'],
+    [cyan('habits'), 'what is worth changing, with the evidence'],
+    [cyan('verify [--full]'), 'prove the chain has not been altered'],
+    [cyan('ledger [n]'), 'the raw records'],
+    [cyan('export --format=csv'), 'all of it, back out'],
+    [cyan('sources'), 'which coding agents SynDes can see'],
+    [cyan('watch [--once]'), 'follow agents that have no hook API'],
+    [cyan('lock [mode]'), 'how the dashboard unlocks: open, system or pin'],
+    [cyan('doctor [--full]'), 'what is wired and what actually works'],
+    [cyan('off [30m] / on'), 'pause and resume tracking'],
+    [cyan('mute <rule>'), 'silence one practice rule'],
+    [cyan('config [key] [val]'), 'read or change settings'],
+    [cyan('uninstall [--purge]'), 'remove hooks; --purge also deletes history'],
+  ]).map((line) => `  ${line}`).join('\n'));
+  write();
+}
+
+function readVersion() {
+  try {
+    return JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+}

package/bin/postinstall.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/**
+ * Runs after `npm install -g syndes`, so one command does the whole job.
+ *
+ * A postinstall that touches a user's config is intrusive if it fires at the
+ * wrong moment, so this one is heavily guarded and can never fail the install:
+ *
+ *   • Only on a GLOBAL install. Adding syndes as a dependency of some other
+ *     project must not silently wire hooks into that developer's Claude Code.
+ *   • Never in CI, and never when the user opted out.
+ *   • Always exits 0. A postinstall that throws breaks `npm install` itself,
+ *     and a tracker is never worth breaking somebody's package manager over.
+ *
+ * If it skips, the CLI is still installed and `syndes install` does the rest —
+ * so the guard costs the user one command, never the product.
+ */
+
+const SKIP_ENV = ['CI', 'SYNDES_SKIP_POSTINSTALL'];
+
+async function main() {
+  if (process.env.npm_config_global !== 'true') return;
+  if (SKIP_ENV.some((name) => process.env[name])) return;
+  // A dry run should describe, not do.
+  if (process.env.npm_config_dry_run === 'true') return;
+
+  const { install } = await import('../src/install.mjs');
+  const { deferBriefing } = await import('../src/briefing.mjs');
+
+  await install({});
+
+  // npm swallows this stream unless --foreground-scripts, so the real briefing
+  // is deferred to the user's next command, where it will actually be read.
+  deferBriefing();
+  process.stdout.write('\n  SynDes is wired into Claude Code. Run  syndes  to begin.\n\n');
+}
+
+try {
+  await main();
+} catch (error) {
+  // Say what happened and how to finish by hand, then leave with 0.
+  process.stdout.write(`\n  syndes was installed, but wiring it up did not finish:\n`);
+  process.stdout.write(`  ${error?.message ?? error}\n`);
+  process.stdout.write(`  Run  syndes install  to complete it.\n\n`);
+}