@gafj/gafj 0.1.1

package/bin/cli.js

@@ -0,0 +1,628 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * gafj command line. Phases 1 and 1b: store, import, review, lint, ingest.
+ * Later phases add packet, mcp, serve, and the rest. The Node floor is
+ * enforced here because "engines" in package.json is advisory. Every
+ * mutating command logs events with actor cli and the command name.
+ */
+
+const NODE_FLOOR = 24;
+const major = Number(process.versions.node.split(".")[0]);
+if (major < NODE_FLOOR && !process.env.GAFJ_ALLOW_OLD_NODE) {
+  process.stderr.write(`gafj needs Node ${NODE_FLOOR} or newer; found ${process.version}.\n`);
+  process.exit(2);
+}
+
+const fs = require("fs");
+const path = require("path");
+const { resolveHome } = require("../store/home");
+const { open } = require("../store/db");
+const { migrate } = require("../store/migrate");
+const { readConfig, writeConfig } = require("../store/config");
+const { ulid } = require("../core/ulid");
+
+const COMMANDS = {
+  migrate: "apply pending schema migrations to the store",
+  import: "import: --kb <dir> [--tracker <xlsx>] [--rounds <json>] [--fixtures <dir>] [--profile <json>] [--name <candidate name>]",
+  snapshot: "print the campaign snapshot",
+  review: "review queue: review [list [--record <id>]] | review confirm <record> <metric|verb|claim> <value|*> | review drop ... | review edit <record> <dim> <value> --set key=val",
+  lint: "run the validators on plain text: --kind <resume|prep|email|...> --file <text file> [--application <company>]",
+  ingest: "ingest a generated document through the door: --file <json or text> (--run <id> | --op <op> --interview-id <id> | --posting-id <id>) [--route paste|manual]",
+  export: "write a dated tracker xlsx: --out <dir>",
+  backup: "write a consistent copy of the store: [--out <dir>]",
+  restore: "restore a backup: <file> --into <home dir> [--into-live --yes]",
+  "serve-hosted": "the hosted server (plan W): GAFJ_HOSTED_ROOT, GAFJ_HOST, PORT, GAFJ_FIREBASE_PROJECT_ID, GAFJ_FIREBASE_API_KEY, GAFJ_RELAY_URL, GAFJ_RELAY_SERVICE_KEY",
+  packet: "write a paste packet: packet <resume|cover|prep|onepager|deep_answers|followup|practice> (--interview-id <id> | --posting-id <id>) [--out <dir>], or packet discover",
+  "score-freeze": "score a posting: score-freeze --posting-id <id> [--from-scan] [--categories <json>] [--scores <json>] [--propose-only]",
+  render: "write a passed document as Markdown: render --document <id> [--out <dir>]",
+  list: "list ids: list postings|applications|interviews|documents|runs",
+  mcp: "run the stdio MCP server for Claude Desktop or Claude Code (stdout is the wire)",
+  serve: "run the local UI server on 127.0.0.1: serve [--port <n>] [--force] [--no-open]",
+  url: "print a fresh launch URL for the running server (and open the browser): url [--no-open] [--host <allowed host>] [--qr]",
+  "allow-host": "let a local HTTPS proxy front the server for your phone: allow-host <name.tail1234.ts.net> | allow-host --remove <name>",
+  "rotate-token": "rotate the session token; every open browser session ends",
+  "print-mcp-config": "print the Claude Desktop config snippet and the Claude Code command for this machine",
+  "install-startup": "register gafj serve to start at login: install-startup [--print] [--remove]",
+  init: "create a candidate and open an onboarding batch: init --name <name>",
+  onboard: "onboarding: onboard add <files...> | onboard status | onboard packet --source <id> [--out <dir>] | onboard ingest --run <id> --file <json> | onboard dedup | onboard merge <group> [--keep <pending id>] | onboard style",
+};
+
+function usage(code) {
+  const out = ["usage: gafj <command> [options]", ""];
+  for (const [name, help] of Object.entries(COMMANDS)) out.push(`  ${name.padEnd(14)} ${help}`);
+  out.push("", "GAFJ_HOME overrides the data folder. GAFJ_FIXTURES_PRIVATE points at the private calibration set.");
+  (code ? process.stderr : process.stdout).write(out.join("\n") + "\n");
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const opts = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) opts[key] = true;
+      else if (key === "set") { (opts.set = opts.set || []).push(next); i++; }
+      else { opts[key] = next; i++; }
+    } else opts._.push(a);
+  }
+  return opts;
+}
+
+const nowIso = () => new Date().toISOString();
+const ACTOR = (ref) => ({ type: "cli", ref });
+
+function openStore(home) {
+  const db = open(path.join(home.dir, "gafj.db"));
+  migrate(db);
+  return db;
+}
+
+function activeCandidate(home, cfg, db, name) {
+  if (cfg.candidate_id) return cfg.candidate_id;
+  const id = ulid(Date.now());
+  db.prepare("INSERT INTO candidate (id, name, created_at) VALUES (?, ?, ?)").run(id, name || "Candidate", nowIso());
+  cfg.candidate_id = id;
+  writeConfig(home.dir, cfg);
+  return id;
+}
+
+function readFixtureTexts(dir) {
+  if (!dir || !fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir).filter((f) => /\.(txt|md)$/i.test(f) && /resume-live|prep-handbuilt/i.test(f))
+    .map((f) => fs.readFileSync(path.join(dir, f), "utf8"));
+}
+
+/** A QR code in the terminal so a phone can scan the launch link (byte mode, error level L, versions 1 to 10). */
+function qrText(text) {
+  try { return require("../core/qr").render(text); } catch (e) { return `(qr unavailable: ${e.message})`; }
+}
+
+function openBrowser(url) {
+  const { spawn } = require("child_process");
+  try {
+    const p = process.platform === "win32" ? spawn("cmd", ["/c", "start", "", url], { detached: true, stdio: "ignore" })
+      : process.platform === "darwin" ? spawn("open", [url], { detached: true, stdio: "ignore" })
+      : spawn("xdg-open", [url], { detached: true, stdio: "ignore" });
+    p.on("error", () => {});
+    p.unref();
+  } catch (_) { /* no browser here */ }
+}
+
+function findApplication(db, candidate_id, company) {
+  if (!company) return null;
+  const row = db.prepare(`SELECT a.id FROM application a JOIN posting p ON p.id = a.posting_id WHERE p.candidate_id = ? AND lower(p.company) LIKE lower(?) ORDER BY a.applied_at DESC LIMIT 1`)
+    .get(candidate_id, company + "%");
+  if (!row) throw new Error(`no application for a company starting with "${company}"`);
+  return row.id;
+}
+
+function printFindings(out, r) {
+  for (const b of r.blocks) out(`  BLOCK ${b.rule.padEnd(24)} ${b.path || ""}  "${b.span}"  ${b.hint}${b.nearby && b.nearby.length ? "  nearby: " + b.nearby.map((n) => n.id).join(", ") : ""}`);
+  for (const w of r.warnings) out(`  warn  ${w.rule.padEnd(24)} ${w.path || ""}  "${w.span}"  ${w.hint}`);
+}
+
+async function main(argv) {
+  const cmd = argv[0];
+  if (!cmd || cmd === "--help" || cmd === "-h") usage(0);
+  if (!(cmd in COMMANDS)) { process.stderr.write(`unknown command: ${cmd}\n`); usage(2); }
+  const opts = parseArgs(argv.slice(1));
+  const home = resolveHome(process.env);
+  if (home.warning) process.stderr.write(`warning: ${home.warning}\n`);
+  const cfg = readConfig(home.dir);
+  const out = (s) => process.stdout.write(s + "\n");
+
+  if (cmd === "migrate") {
+    const db = openStore(home);
+    try { out(`store ${path.join(home.dir, "gafj.db")} at schema version ${migrate(db)}`); } finally { db.close(); }
+    return;
+  }
+
+  if (cmd === "import") {
+    const { importKb, setProfile } = require("../store/import_kb");
+    const { readTracker, importTracker } = require("../store/import_tracker");
+    const db = openStore(home);
+    try {
+      const now = nowIso();
+      const candidate_id = activeCandidate(home, cfg, db, opts.name);
+      if (opts.profile) {
+        const profile = JSON.parse(fs.readFileSync(opts.profile, "utf8"));
+        setProfile(db, { candidate_id, profile, now, actor: ACTOR("import") });
+        out(`profile stored for candidate ${candidate_id}`);
+      }
+      if (opts.kb) {
+        const accs = JSON.parse(fs.readFileSync(path.join(opts.kb, "accomplishments.json"), "utf8"));
+        const vars = JSON.parse(fs.readFileSync(path.join(opts.kb, "bullet-variations.json"), "utf8"));
+        const fixturesDir = opts.fixtures || process.env.GAFJ_FIXTURES_PRIVATE;
+        const fixtureTexts = readFixtureTexts(fixturesDir);
+        const name = db.prepare("SELECT name FROM candidate WHERE id = ?").get(candidate_id).name;
+        const kb = importKb(db, { candidate: { id: candidate_id, name }, accomplishments: accs.accomplishments || accs,
+          variations: vars.variations || vars, fixtureTexts, now, actor: ACTOR("import") });
+        out(`knowledge base: ${kb.inserted} inserted, ${kb.updated} updated, ${kb.review.length} dimensions to review (${fixtureTexts.length} fixture texts applied)`);
+      }
+      if (opts.tracker) {
+        const tracker = await readTracker(opts.tracker);
+        const manifest = opts.rounds ? JSON.parse(fs.readFileSync(opts.rounds, "utf8")) : {};
+        const postingTexts = {};
+        for (const o of manifest.overrides || []) {
+          if (o.posting_text_file) {
+            const p = path.isAbsolute(o.posting_text_file) ? o.posting_text_file : path.join(path.dirname(opts.rounds), o.posting_text_file);
+            postingTexts[o.posting_text_file] = fs.readFileSync(p, "utf8");
+          }
+        }
+        const tr = importTracker(db, { candidate_id, tracker, manifest, postingTexts, now, actor: ACTOR("import") });
+        out(`tracker: ${tr.postings} postings, ${tr.applications} applications, ${tr.interviews} interviews, ${tr.people} people, ${tr.communications} communications`);
+        for (const w of tr.warnings) out(`  warning: ${w}`);
+      }
+      if (!opts.kb && !opts.tracker && !opts.profile) out("nothing to import; pass --kb, --tracker, or --profile");
+      else out(`run "gafj review" to work the review queue`);
+    } finally { db.close(); }
+    return;
+  }
+
+  if (cmd === "snapshot") {
+    const { snapshot } = require("../store/snapshot");
+    const db = openStore(home);
+    try {
+      if (!cfg.candidate_id) { out("no candidate yet; run import first"); return; }
+      const s = snapshot(db, { candidate_id: cfg.candidate_id, now: nowIso(), thresholds: cfg.thresholds });
+      out(`NEEDS YOU NOW`); for (const n of s.needs_you) out(`  ${n.text}`);
+      out(`UPCOMING`); for (const u of s.upcoming) out(`  ${u.scheduled_at} ${u.tz}  ${u.company} ${u.round} ${u.format}  ${u.people.join(", ")}`);
+      out(`ACTIVE (${s.active.length})`); for (const a of s.active) out(`  ${a.company.padEnd(22)} ${a.title.slice(0, 40).padEnd(40)} ${a.status.padEnd(9)} fit ${a.fit ?? "-"}`);
+      out(`AGING`); for (const a of s.aging) out(`  ${a.text}`);
+      out(`CLOSED (${s.closed.length})`); for (const c of s.closed) out(`  ${c.company.padEnd(22)} ${c.title.slice(0, 40).padEnd(40)} ${c.status}`);
+    } finally { db.close(); }
+    return;
+  }
+
+  if (cmd === "review") {
+    const { listReview, mutate } = require("../store/review");
+    const db = openStore(home);
+    try {
+      const candidate_id = cfg.candidate_id;
+      if (!candidate_id) { out("no candidate yet; run import first"); return; }
+      const sub = opts._[0] || "list";
+      if (sub === "list") {
+        const items = listReview(db, candidate_id, { record: opts.record });
+        out(`${items.length} dimensions to review`);
+        let last = null;
+        for (const it of items) {
+          if (it.id !== last) { out(`\n${it.id}  ${it.company}: ${it.title}`); last = it.id; }
+          out(`   ${it.dimension.padEnd(7)} ${String(it.value).padEnd(28)} ${it.detail || ""}`);
+        }
+        out(`\nconfirm one:  gafj review confirm <record id> <metric|verb|claim> "<value>"\nconfirm all on a record:  gafj review confirm <record id> metric *`);
+        return;
+      }
+      const [record, dimension, value] = opts._.slice(1);
+      if (!record || !dimension || value === undefined) { process.stderr.write("review <confirm|drop|edit> <record> <metric|verb|claim> <value|*>\n"); process.exit(2); }
+      const edits = {};
+      for (const kv of opts.set || []) { const [k, v] = kv.split("="); edits[k] = v; }
+      const r = mutate(db, { candidate_id, record, dimension, value, action: sub, edits, now: nowIso(), actor: ACTOR("review") });
+      out(`${sub}: ${r.changed} changed, ${r.remaining ?? 0} still in review on ${record}`);
+    } finally { db.close(); }
+    return;
+  }
+
+  if (cmd === "lint") {
+    const { lintText } = require("../store/ingest");
+    if (!opts.kind || !opts.file) { process.stderr.write("lint --kind <kind> --file <text file> [--application <company>]\n"); process.exit(2); }
+    const db = openStore(home);
+    try {
+      const text = fs.readFileSync(opts.file, "utf8");
+      const application_id = findApplication(db, cfg.candidate_id, opts.application);
+      const r = lintText(db, { candidate_id: cfg.candidate_id, kind: opts.kind, text, application_id });
+      out(`${path.basename(opts.file)} as ${opts.kind}: ${r.blocks.length} blocks, ${r.warnings.length} warnings`);
+      printFindings(out, r);
+      process.exitCode = r.blocks.length ? 1 : 0;
+    } finally { db.close(); }
+    return;
+  }
+
+  if (cmd === "ingest") {
+    const { saveReply: ingestDocument } = require("../store/reply");
+    if (!opts.file) { process.stderr.write("ingest --file <json or text> (--run <id> | --op <op> --interview-id <id> | --posting-id <id>)\n"); process.exit(2); }
+    const db = openStore(home);
+    try {
+      const content = fs.readFileSync(opts.file, "utf8");
+      const r = ingestDocument(db, { run_id: opts.run, op: opts.op, interview_id: opts["interview-id"], posting_id: opts["posting-id"],
+        content, route: opts.route || "paste", actor: ACTOR("ingest"), now: nowIso() });
+      out(`${r.status.toUpperCase()}  run ${r.run_id}  attempt ${r.attempt}${r.document_id ? "  document " + r.document_id : ""}${r.question_ids ? `  ${r.question_ids.length} questions` : ""}${r.pending_ids ? `  ${r.pending_ids.length} pending rows` : ""}${r.stop ? "  STOP: hand this to the user" : ""}`);
+      for (const e of r.errors || []) out(`  ${e}`);
+      printFindings(out, r);
+      if (r.status === "passed") out(`render it: gafj render --document ${r.document_id}`);
+      else if (!r.stop) out(`fix the reply and run the same command again (attempt ${r.attempt + 1} of 3)`);
+      process.exitCode = r.status === "passed" ? 0 : 1;
+    } finally { db.close(); }
+    return;
+  }
+
+  if (cmd === "export") {
+    const { exportTracker } = require("../store/export_xlsx");
+    const dir = opts.out || cfg.export_dir || path.join(home.dir, "exports");
+    fs.mkdirSync(dir, { recursive: true });
+    const db = openStore(home);
+    try {
+      const r = await exportTracker(db, { candidate_id: cfg.candidate_id, outDir: dir, now: nowIso() });
+      out(`wrote ${r.file} (${r.rows} rows)`);
+    } finally { db.close(); }
+    return;
+  }
+
+  if (cmd === "backup") {
+    const { backupDir, backupTo } = require("../store/backup_dir");
+    const dir = opts.out || backupDir(cfg, cfg.export_dir || home.dir);
+    const db = openStore(home);
+    try {
+      const r = await backupTo(db, dir, nowIso());
+      out(`backup written: ${r.file} (${r.method}${r.pruned ? `, ${r.pruned} old copies removed` : ""})`);
+    } finally { db.close(); }
+    return;
+  }
+
+  if (cmd === "restore") {
+    const { restore } = require("../store/backup");
+    const file = opts._[0];
+    if (!file || !opts.into) { process.stderr.write("restore <backup file> --into <home dir> [--into-live --yes]\n"); process.exit(2); }
+    if (opts["into-live"] && !opts.yes) { process.stderr.write("--into-live replaces a live store; add --yes to confirm\n"); process.exit(2); }
+    const r = await restore(file, opts.into, { intoLive: !!opts["into-live"], now: nowIso() });
+    out(`restored to ${r.file}, schema version ${r.version}`);
+    return;
+  }
+
+  if (cmd === "list") {
+    const db = openStore(home);
+    try {
+      const c = cfg.candidate_id;
+      const what = opts._[0] || "postings";
+      const q = {
+        postings: ["SELECT id, status, company, title, (SELECT count(*) FROM scoring s WHERE s.posting_id = p.id AND s.status = 'frozen') AS frozen FROM posting p WHERE candidate_id = ? ORDER BY captured_at DESC",
+          (r) => `${r.id}  ${r.status.padEnd(8)} ${r.frozen ? "frozen  " : "unscored"} ${r.company}: ${r.title}`],
+        applications: ["SELECT a.id, a.status, p.company, p.title FROM application a JOIN posting p ON p.id = a.posting_id WHERE p.candidate_id = ? ORDER BY a.applied_at DESC",
+          (r) => `${r.id}  ${r.status.padEnd(9)} ${r.company}: ${r.title}`],
+        interviews: ["SELECT i.id, i.round_label, i.format, i.status, i.scheduled_at, i.tz, p.company FROM interview i JOIN application a ON a.id = i.application_id JOIN posting p ON p.id = a.posting_id WHERE p.candidate_id = ? ORDER BY i.scheduled_at DESC",
+          (r) => `${r.id}  ${r.scheduled_at} ${r.tz}  ${r.company} ${r.round_label} ${r.format} ${r.status}`],
+        documents: ["SELECT d.id, d.kind, d.status, d.created_at, d.rendered_rel_path, coalesce(p.company, p2.company, p3.company) AS company FROM document d LEFT JOIN posting p ON p.id = d.posting_id LEFT JOIN interview i ON i.id = d.interview_id LEFT JOIN application a ON a.id = coalesce(d.application_id, i.application_id) LEFT JOIN posting p2 ON p2.id = a.posting_id LEFT JOIN posting p3 ON p3.id = p2.id WHERE d.candidate_id = ? ORDER BY d.created_at DESC",
+          (r) => `${r.id}  ${r.kind.padEnd(12)} ${r.status.padEnd(7)} ${r.created_at}  ${r.company || ""}  ${r.rendered_rel_path || ""}`],
+        runs: ["SELECT r.id, r.operation, r.route, r.final_result, r.started_at, (SELECT count(*) FROM ai_attempt t WHERE t.ai_run_id = r.id) AS attempts FROM ai_run r WHERE r.candidate_id = ? ORDER BY r.started_at DESC LIMIT 50",
+          (r) => `${r.id}  ${r.operation.padEnd(12)} ${r.route.padEnd(7)} ${r.final_result.padEnd(8)} attempts ${r.attempts}  ${r.started_at}`],
+      }[what];
+      if (!q) { process.stderr.write("list postings|applications|interviews|documents|runs\n"); process.exit(2); }
+      for (const r of db.prepare(q[0]).all(c)) out(q[1](r));
+    } finally { db.close(); }
+    return;
+  }
+
+  if (cmd === "serve-hosted") {
+    // The hosted server (plan W): many users, one store each, sign-in instead of a launch cookie. Configured by environment only.
+    const { createHostedServer } = require("../http/hosted");
+    const { firebaseVerifier } = require("../http/identity");
+    const { Log } = require("../store/log");
+    const env = process.env;
+    const root = env.GAFJ_HOSTED_ROOT || "/data";
+    if (!env.GAFJ_FIREBASE_PROJECT_ID) { process.stderr.write("serve-hosted needs GAFJ_FIREBASE_PROJECT_ID (and GAFJ_FIREBASE_API_KEY, GAFJ_FIREBASE_AUTH_DOMAIN for the sign-in page)\n"); process.exit(2); }
+    const log = new Log({ dir: path.join(root, "logs"), stderr: true });
+    log.rotate();
+    const srv = createHostedServer({
+      root, host: env.GAFJ_HOST || null, port: Number(env.PORT || 8080), version: pkg.version, log,
+      verifyIdToken: firebaseVerifier({ projectId: env.GAFJ_FIREBASE_PROJECT_ID }),
+      firebase: { apiKey: env.GAFJ_FIREBASE_API_KEY || null, authDomain: env.GAFJ_FIREBASE_AUTH_DOMAIN || `${env.GAFJ_FIREBASE_PROJECT_ID}.firebaseapp.com`, projectId: env.GAFJ_FIREBASE_PROJECT_ID },
+      relay: env.GAFJ_RELAY_URL ? { url: env.GAFJ_RELAY_URL, service_key: env.GAFJ_RELAY_SERVICE_KEY || "" } : null,
+      insecure: env.GAFJ_HOSTED_INSECURE === "1",
+    });
+    const { origin } = await srv.listen(env.GAFJ_BIND || "0.0.0.0");
+    log.info("serve_start", { entity: "hosted", entity_id: String(env.PORT || 8080), actor: "cli" });
+    out(`gafj ${pkg.version} hosted at ${origin} (root ${root}, host ${env.GAFJ_HOST || "any"})`);
+    const stop = async () => { log.info("serve_stop", { entity: "hosted", entity_id: String(env.PORT || 8080), actor: "cli" }); await srv.close(); process.exit(0); };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    await new Promise(() => {});
+  }
+
+  if (cmd === "packet") {
+    const { openRun } = require("../store/packets");
+    const { renderPasteText } = require("../bridge/paste");
+    const op = opts._[0];
+    if (!op || (op !== "discover" && !opts["interview-id"] && !opts["posting-id"])) { process.stderr.write("packet <op> (--interview-id <id> | --posting-id <id>) [--out <dir>], or packet discover\n"); process.exit(2); }
+    const db = openStore(home);
+    try {
+      if (op === "discover") require("../store/discover").assertCanOpen(db, cfg.candidate_id);
+      const r = openRun(db, { op, candidate_id: cfg.candidate_id, interview_id: opts["interview-id"], posting_id: opts["posting-id"], route: "paste", actor: ACTOR("packet"), now: nowIso() });
+      const dir = opts.out || path.join(cfg.export_dir || home.dir, "packets");
+      fs.mkdirSync(dir, { recursive: true });
+      const file = path.join(dir, `packet-${op}-${r.run_id}.md`);
+      fs.writeFileSync(file, renderPasteText(r.packet, { run_id: r.run_id }), "utf8");
+      out(`run ${r.run_id}`);
+      out(`packet ${file} (${r.packet.kb_ids.length} records, ${Buffer.byteLength(fs.readFileSync(file))} bytes)`);
+      out(`paste it into any chat, save the JSON reply, then: gafj ingest --run ${r.run_id} --file <reply>`);
+    } finally { db.close(); }
+    return;
+  }
+
+  if (cmd === "score-freeze") {
+    const { proposeFromScan, freezeScoring } = require("../store/scoring");
+    if (!opts["posting-id"]) { process.stderr.write("score-freeze --posting-id <id> [--from-scan] [--categories <json>] [--scores <json>] [--propose-only]\n"); process.exit(2); }
+    const db = openStore(home);
+    try {
+      const now = nowIso();
+      let categories = opts.categories ? JSON.parse(fs.readFileSync(opts.categories, "utf8")) : null;
+      if (categories && categories.categories) categories = categories.categories;
+      if (opts["from-scan"]) {
+        const p = proposeFromScan(db, { posting_id: opts["posting-id"], now, actor: ACTOR("score-freeze") });
+        out(`proposed ${p.categories.length} categories from the scan (scoring ${p.scoring_id})`);
+        if (opts["propose-only"]) {
+          const dir = opts.out || path.join(cfg.export_dir || home.dir, "packets");
+          fs.mkdirSync(dir, { recursive: true });
+          const file = path.join(dir, `categories-${opts["posting-id"]}.json`);
+          fs.writeFileSync(file, JSON.stringify({ categories: p.categories }, null, 2) + "\n");
+          out(`edit ${file} then: gafj score-freeze --posting-id ${opts["posting-id"]} --categories ${file}`);
+          return;
+        }
+      }
+      const scores = opts.scores ? JSON.parse(fs.readFileSync(opts.scores, "utf8")) : null;
+      const r = freezeScoring(db, { posting_id: opts["posting-id"], categories, scores: scores && scores.scores || scores, now, actor: ACTOR("score-freeze"), thresholds: cfg.thresholds });
+      out(`frozen ${r.scoring_id}: fit ${r.fit_score} ${r.verdict} (${r.verdict_reason})`);
+      for (const c of r.categories) out(`  w${String(c.weight).padStart(2)} s${c.score}  ${c.category.slice(0, 60).padEnd(60)} ${c.evidence_strength.padEnd(8)} ${c.evidence_ids.slice(0, 3).join(", ")}`);
+    } finally { db.close(); }
+    return;
+  }
+
+  if (cmd === "render") {
+    const { renderDocument } = require("../store/render");
+    if (!opts.document) { process.stderr.write("render --document <id> [--out <dir>]\n"); process.exit(2); }
+    const db = openStore(home);
+    try {
+      const dir = opts.out || path.join(cfg.export_dir || home.dir, "documents");
+      const kind = db.prepare("SELECT kind FROM document WHERE id = ?").get(opts.document);
+      if (kind && kind.kind === "practice") {
+        const { writeWorkbook } = require("../store/practice");
+        const r = await writeWorkbook(db, { document_id: opts.document, outDir: dir, homeDir: home.dir, now: nowIso(), actor: ACTOR("render") });
+        out(`wrote ${r.file} (${r.planted} planted anomalies; the Solution tab is the grader)`);
+        return;
+      }
+      const r = renderDocument(db, { document_id: opts.document, outDir: dir, homeDir: home.dir, now: nowIso(), actor: ACTOR("render") });
+      out(`wrote ${r.file} (${r.bytes} bytes)`);
+    } finally { db.close(); }
+    return;
+  }
+
+  if (cmd === "init") {
+    const onboarding = require("../store/onboarding");
+    const db = openStore(home);
+    try {
+      if (cfg.candidate_id && !opts.force) { out(`a candidate already exists (${cfg.candidate_id}); onboarding continues with: gafj onboard add <files>`); return; }
+      const id = ulid(Date.now());
+      db.prepare("INSERT INTO candidate (id, name, created_at) VALUES (?, ?, ?)").run(id, opts.name || "Candidate", nowIso());
+      cfg.candidate_id = id;
+      writeConfig(home.dir, cfg);
+      const b = onboarding.openBatch(db, { candidate_id: id, now: nowIso(), actor: ACTOR("init") });
+      out(`candidate ${id} (${opts.name || "Candidate"}) with onboarding batch ${b.batch_id}`);
+      out(`next: gafj onboard add <your resumes: docx, pdf, md, txt>`);
+    } finally { db.close(); }
+    return;
+  }
+
+  if (cmd === "onboard") {
+    const onboarding = require("../store/onboarding");
+    const db = openStore(home);
+    try {
+      const candidate_id = cfg.candidate_id;
+      if (!candidate_id) { process.stderr.write("no candidate yet; run gafj init --name <name>\n"); process.exit(2); }
+      const sub = opts._[0] || "status";
+      const now = nowIso();
+      if (sub === "add") {
+        const b = onboarding.openBatch(db, { candidate_id, now, actor: ACTOR("onboard") });
+        for (const f of opts._.slice(1)) {
+          const r = await onboarding.addSource(db, { candidate_id, batch_id: b.batch_id, filename: path.basename(f), buffer: fs.readFileSync(f), now: nowIso(), actor: ACTOR("onboard") });
+          out(`${path.basename(f)}: ${r.created ? (r.empty ? "FAILED: " + r.failure : `${r.chars} characters`) : "already uploaded"}  ${r.source_document_id}`);
+        }
+        out(`next: gafj onboard packet --source <id>`);
+        return;
+      }
+      if (sub === "status") {
+        const v = onboarding.batchView(db, candidate_id);
+        if (!v) { out("no batch; run gafj init"); return; }
+        out(`batch ${v.batch_id} ${v.status}: ${v.sources.length} sources, ${v.pending.length} pending, ${v.groups.length} duplicate groups`);
+        for (const s of v.sources) out(`  ${s.source_document_id}  ${s.filename.padEnd(40)} ${s.empty ? "FAILED" : s.chars + " chars"}  runs ${s.runs}  pending ${s.pending}`);
+        for (const p of v.pending) out(`  pending ${p.pending_id} ${p.dedup_group_id ? "[group " + p.dedup_group_id.slice(-6) + "]" : ""} ${p.draft.company}: ${p.draft.title}`);
+        return;
+      }
+      if (sub === "packet") {
+        const { openRun } = require("../store/packets");
+        const { renderPasteText } = require("../bridge/paste");
+        if (!opts.source) { process.stderr.write("onboard packet --source <source document id>\n"); process.exit(2); }
+        const r = openRun(db, { op: "extract", source_document_id: opts.source, route: "paste", actor: ACTOR("onboard"), now });
+        const dir = opts.out || path.join(cfg.export_dir || home.dir, "packets");
+        fs.mkdirSync(dir, { recursive: true });
+        const file = path.join(dir, `packet-extract-${r.run_id}.md`);
+        fs.writeFileSync(file, renderPasteText(r.packet, { run_id: r.run_id }), "utf8");
+        out(`run ${r.run_id}\npacket ${file}\npaste it into any chat, save the JSON reply, then: gafj onboard ingest --run ${r.run_id} --file <reply>`);
+        return;
+      }
+      if (sub === "ingest") {
+        if (!opts.run || !opts.file) { process.stderr.write("onboard ingest --run <id> --file <json>\n"); process.exit(2); }
+        const r = onboarding.saveExtraction(db, { run_id: opts.run, content: fs.readFileSync(opts.file, "utf8"), route: "paste", actor: ACTOR("onboard"), now });
+        out(`${r.status.toUpperCase()} attempt ${r.attempt}: ${r.pending_ids.length} pending rows${r.stop ? "  STOP: open a fresh packet" : ""}`);
+        for (const e of r.errors) out(`  ${e}`);
+        if (r.status === "passed") out(`next: gafj onboard dedup, then confirm on the knowledge base screen or with gafj review`);
+        process.exitCode = r.status === "passed" ? 0 : 1;
+        return;
+      }
+      if (sub === "dedup") {
+        const v = onboarding.batchView(db, candidate_id);
+        const groups = onboarding.suggestDedup(db, { candidate_id, batch_id: v.batch_id, now, actor: ACTOR("onboard") });
+        out(`${groups.length} duplicate groups suggested; nothing merges without you`);
+        for (const g of groups) out(`  ${g.dedup_group_id} ${g.strength}: ${g.pending_ids.join(", ")}   merge with: gafj onboard merge ${g.dedup_group_id}`);
+        return;
+      }
+      if (sub === "merge") {
+        const r = onboarding.mergeGroup(db, { candidate_id, dedup_group_id: opts._[1], keep_id: opts.keep, now, actor: ACTOR("onboard") });
+        out(`merged ${r.merged} rows into ${r.pending_id}`);
+        return;
+      }
+      if (sub === "style") { out(JSON.stringify(onboarding.proposeStyle(db, candidate_id), null, 2)); return; }
+      process.stderr.write("onboard add|status|packet|ingest|dedup|merge|style\n"); process.exit(2);
+    } finally { db.close(); }
+  }
+
+  if (cmd === "serve") {
+    const { createServer, ensureSessionToken, readLock, writeLock, removeLock, pidAlive } = require("../http/server");
+    const pkg = require("../package.json");
+    if (!cfg.candidate_id) { process.stderr.write("no candidate yet; run gafj import first\n"); process.exit(2); }
+    const lock = readLock(home.dir);
+    if (lock && pidAlive(lock.pid) && !opts.force) {
+      out(`gafj serve is already running (pid ${lock.pid}) at http://127.0.0.1:${lock.port}; run "gafj url" for a launch link, or serve --force`);
+      return;
+    }
+    ensureSessionToken(cfg);
+    writeConfig(home.dir, cfg);
+    const { Log } = require("../store/log");
+    const log = new Log({ dir: path.join(home.dir, "logs") });
+    log.rotate();
+    const db = openStore(home);
+    const abandoned = db.prepare("UPDATE ai_run SET final_result = 'abandoned', finished_at = ? WHERE final_result = 'pending' AND started_at < ?")
+      .run(nowIso(), new Date(Date.now() - 7 * 24 * 3600 * 1000).toISOString()).changes;
+    if (abandoned) out(`${abandoned} stale pending runs marked abandoned`);
+    const exportDir = cfg.export_dir || path.join(home.dir, "exports");
+    {
+      const { backupDir, dailyBackup } = require("../store/backup_dir");
+      const b = await dailyBackup(db, backupDir(cfg, exportDir), nowIso());
+      if (b.error) out(`daily backup skipped: ${b.error}`);
+      else if (!b.skipped) { out(`daily backup written: ${b.file}`); require("../store/settings").recordBackup(home.dir, { file: b.file, at: nowIso(), method: "daily", by: "serve" }); }
+    }
+    const srv = createServer({ db, cfg, home: home.dir, exportDir, port: Number(opts.port || cfg.port || 0) || 0, version: pkg.version, log });
+    const { port, origin } = await srv.listen();
+    writeLock(home.dir, { pid: process.pid, port, started_at: nowIso() });
+    log.info("serve_start", { entity: "server", entity_id: String(port), actor: "cli" });
+    if (!cfg.port) { cfg.port = port; writeConfig(home.dir, cfg); }
+    const url = srv.launchUrl();
+    out(`gafj ${pkg.version} serving ${origin} (store ${path.join(home.dir, "gafj.db")})`);
+    out(`open: ${url}`);
+    if (!opts["no-open"]) openBrowser(url);
+    const stop = async () => { out("stopping"); log.info("serve_stop", { entity: "server", entity_id: String(port), actor: "cli" }); await srv.close(); try { db.exec("PRAGMA wal_checkpoint(TRUNCATE)"); } catch (_) { /* busy */ } db.close(); removeLock(home.dir); process.exit(0); };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    await new Promise(() => {});
+  }
+
+  if (cmd === "url") {
+    const { readLock, pidAlive } = require("../http/server");
+    const lock = readLock(home.dir);
+    if (!lock || !pidAlive(lock.pid)) { process.stderr.write("gafj serve is not running; start it with gafj serve\n"); process.exit(1); }
+    const r = await fetch(`http://127.0.0.1:${lock.port}/launch/new${opts.host ? "?host=" + encodeURIComponent(opts.host) : ""}`, { headers: { "x-gafj-token": cfg.session_token || "", host: `127.0.0.1:${lock.port}` } });
+    if (!r.ok) { process.stderr.write(`the running server refused (${r.status}); tokens may differ, restart serve\n`); process.exit(1); }
+    const { url } = await r.json();
+    out(url);
+    if (opts.qr) out(qrText(url));
+    if (!opts["no-open"] && !opts.host) openBrowser(url);
+    return;
+  }
+
+  if (cmd === "allow-host") {
+    const name = String(opts._[0] || opts.remove || "").toLowerCase().trim();
+    if (!name) { process.stderr.write("allow-host <hostname> | allow-host --remove <hostname>\n"); process.exit(2); }
+    const list = new Set(cfg.allowed_hosts || []);
+    if (opts.remove) list.delete(name); else list.add(name);
+    cfg.allowed_hosts = [...list];
+    writeConfig(home.dir, cfg);
+    out(`allowed hosts: ${cfg.allowed_hosts.join(", ") || "(none)"}; restart gafj serve`);
+    return;
+  }
+
+  if (cmd === "rotate-token") {
+    const crypto = require("crypto");
+    cfg.session_token = crypto.randomBytes(32).toString("hex");
+    writeConfig(home.dir, cfg);
+    out("session token rotated; restart gafj serve and open a fresh launch URL");
+    return;
+  }
+
+  if (cmd === "install-startup") {
+    const { execFileSync } = require("child_process");
+    const cli = path.resolve(__filename);
+    const nodeExe = process.execPath;
+    const os = require("os");
+    const plat = process.platform;
+    let plan;
+    if (plat === "win32") {
+      const tr = `"${nodeExe}" "${cli}" serve --no-open`;
+      plan = { how: "Windows scheduled task GAFJ at logon", commands: opts.remove
+        ? [["schtasks", ["/Delete", "/TN", "GAFJ", "/F"]]]
+        : [["schtasks", ["/Create", "/SC", "ONLOGON", "/TN", "GAFJ", "/TR", tr, "/RL", "LIMITED", "/F"]]] };
+    } else if (plat === "darwin") {
+      const plist = path.join(os.homedir(), "Library", "LaunchAgents", "com.gafj.serve.plist");
+      const xml = `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<plist version="1.0"><dict>\n<key>Label</key><string>com.gafj.serve</string>\n<key>ProgramArguments</key><array><string>${nodeExe}</string><string>${cli}</string><string>serve</string><string>--no-open</string></array>\n<key>EnvironmentVariables</key><dict><key>GAFJ_HOME</key><string>${home.dir}</string></dict>\n<key>RunAtLoad</key><true/><key>KeepAlive</key><false/>\n</dict></plist>\n`;
+      plan = { how: `launchd agent ${plist}`, file: opts.remove ? null : { path: plist, text: xml }, commands: opts.remove
+        ? [["launchctl", ["unload", plist]]] : [["launchctl", ["load", plist]]] };
+    } else {
+      const unit = path.join(os.homedir(), ".config", "systemd", "user", "gafj.service");
+      const text = `[Unit]\nDescription=GAF-J local server\n\n[Service]\nEnvironment=GAFJ_HOME=${home.dir}\nExecStart=${nodeExe} ${cli} serve --no-open\nRestart=on-failure\n\n[Install]\nWantedBy=default.target\n`;
+      plan = { how: `systemd user unit ${unit}`, file: opts.remove ? null : { path: unit, text }, commands: opts.remove
+        ? [["systemctl", ["--user", "disable", "--now", "gafj.service"]]] : [["systemctl", ["--user", "daemon-reload"]], ["systemctl", ["--user", "enable", "--now", "gafj.service"]]] };
+    }
+    out(plan.how);
+    if (plan.file) out(`write ${plan.file.path}:\n${plan.file.text}`);
+    for (const [c, a] of plan.commands) out(`run: ${c} ${a.map((x) => (/\s/.test(x) ? JSON.stringify(x) : x)).join(" ")}`);
+    if (opts.print) return;
+    if (plan.file) { fs.mkdirSync(path.dirname(plan.file.path), { recursive: true }); fs.writeFileSync(plan.file.path, plan.file.text); }
+    if (plan.file && opts.remove === true) { /* nothing to write */ }
+    for (const [c, a] of plan.commands) {
+      try { execFileSync(c, a, { stdio: "inherit" }); } catch (e) { process.stderr.write(`${c} failed: ${e.message}\nrun the command above by hand\n`); process.exitCode = 1; }
+    }
+    if (opts.remove && plat !== "win32" && plan.how) { try { fs.unlinkSync(plat === "darwin" ? path.join(os.homedir(), "Library", "LaunchAgents", "com.gafj.serve.plist") : path.join(os.homedir(), ".config", "systemd", "user", "gafj.service")); } catch (_) { /* gone */ } }
+    return;
+  }
+
+  if (cmd === "mcp") {
+    const { serve } = require("../mcp/server");
+    if (!cfg.candidate_id) { process.stderr.write("no candidate yet; run gafj import first\n"); process.exit(2); }
+    const db = openStore(home);
+    const exportDir = cfg.export_dir || path.join(home.dir, "exports");
+    const handle = await serve({ db, candidate_id: cfg.candidate_id, thresholds: cfg.thresholds, exportDir });
+    const stop = async () => { try { await handle.close(); } catch (_) { /* closing */ } db.close(); process.exit(0); };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+    process.stdin.on("end", stop);
+    return;
+  }
+
+  if (cmd === "print-mcp-config") {
+    const cli = path.resolve(__filename);
+    const snippet = { mcpServers: { gafj: { command: process.execPath, args: [cli, "mcp"], env: { GAFJ_HOME: home.dir } } } };
+    out("Claude Desktop (claude_desktop_config.json), merge into mcpServers:");
+    out(JSON.stringify(snippet, null, 2));
+    out("");
+    out("Claude Code:");
+    out(`  claude mcp add gafj -e GAFJ_HOME=${JSON.stringify(home.dir)} -- ${JSON.stringify(process.execPath)} ${JSON.stringify(cli)} mcp`);
+    out("");
+    out(`Store: ${path.join(home.dir, "gafj.db")}. Never use npx here; the paths above are absolute on purpose.`);
+    return;
+  }
+
+  process.stderr.write(`${cmd}: not built yet (see the plan for its phase)\n`);
+  process.exit(3);
+}
+
+main(process.argv.slice(2)).catch((e) => { process.stderr.write(`${e.message}\n`); process.exit(1); });