@figs-so/cli 0.8.0 → 1.0.0

package/figs.mjs

@@ -2,39 +2,47 @@
 /**
  * `figs` — the agent-side CLI (v1, zero-dependency).
  *
- *   figs status                         show login / workspace / agent state    [--json]
- *   figs login                          opens browser to approve (device flow) — agent never sees the token
- *   figs login <token>                  fallback: save a token you pasted (~/.figs/credentials.json)
- *   figs logout                         remove the locally-saved token (~/.figs/credentials.json)
- *   figs workspaces                     list the user's workspaces               [--json]
- *   figs init --workspace <slug-or-id> [--endpoint <url>]
- *                                         create .figs/config.json + GUIDE.md (generates a stable agent id)
- *   figs report --result '…'            record a run (stamps id/ts, --attach files, auto-push)
- *   figs ask <type> --title '…'         raise an ask (self-contained: options/details/attachments, auto-push)
- *   figs inbox [<ask-id>]               what needs you — answers/verdicts from your humans (pure read)
- *   figs resolve <ask-id>               close an ask (verbatim-checks --chosen; cites the Figs answer it acted on)
- *   figs doctor                         validate .figs/ against the spec before pushing
- *   figs push                           one-way push the .figs/ spine to the ingest endpoint
- *   figs version                        print the CLI version (and check for updates)
+ * LOCAL (no account, no network — the complete product):
+ *   figs init                           scaffold .figs/ here — purely local, mints a stable agent id
+ *   figs report --result '…'            settle a job (stamps id/ts, --attach files)
+ *   figs checkpoint --id … --note '…'   save a job's progress mid-flight (opens it in-flight)
+ *   figs ask <type> --title '…'         raise an ask (self-contained: options/details/attachments)
+ *   figs answer <ask-id> --by '…'       record your human's reply to an ask (you run it, not them)
+ *   figs inbox [<ask-id>]               what needs you (pure local read)
+ *   figs show <id>                      magnify one ask or job (thread/trail + attachments)
+ *   figs close <ask-id>                 close an ask (derives the close from the reply, cites it)
+ *   figs doctor                         validate .figs/ against the spec — runs account-free
+ *   figs status                         local/linked + agent state               [--json]
+ *   figs version                        print the CLI version (offline; --check for updates)
  *   figs help [<command>]               usage; `-h`/`--help` on any command, `-v` for version
  *
- * The writing verbs (report/ask/resolve) are sugar over the same files — they
- * stamp ids + real-clock timestamps, validate on write with teaching errors,
- * copy attachments into artifacts/, then invoke the same push as `figs push`
- * (auto-push IS push — one transport, many entry points; --no-push to batch).
+ * CONNECTED (needs a one-time login + a workspace — strictly additive):
+ *   figs login [<token>]                device-flow approve (agent never sees the token), or save a pasted one
+ *   figs logout                         remove the locally-saved token (~/.figs/credentials.json)
+ *   figs link [--workspace <slug|uuid>] connect .figs/ to a workspace so push can publish
+ *   figs push                           publish the .figs/ spine + attachments to the endpoint
+ *
+ * The writing verbs (report/checkpoint/ask/resolve) are sugar over the same
+ * files — they stamp ids + real-clock timestamps, validate on write with
+ * teaching errors, copy attachments into artifacts/, then (when linked) invoke
+ * the same push as `figs push` (auto-push IS push; --no-push to batch).
  * Hand-writing the JSONL + bare `push` remains fully supported — files are the
  * protocol; the verbs are conveniences.
  *
  * Designed to be driven by an agent: non-interactive, clear output, `--json`
  * on read commands, `-h`/`--help`/`help` everywhere, and errors that say what to
  * do next. Bare `figs` prints help; unknown commands AND unknown flags exit
- * non-zero (no silent no-ops). Flags accept `--name value` or `--name=value`.
- * Network calls time out (30s) instead of hanging the agent.
+ * non-zero. Exit codes: 0 = recorded · 1 = nothing written (fix the input) ·
+ * 2 = recorded locally, publish failed (retry `figs push`, never the verb).
+ * Flags accept `--name value` or `--name=value`. Network calls time out (30s).
  *
- * Auth is the *user* (a token, configured once per machine). Identity is the
- * *agent* — a UUID generated by `init`, stored in the committed, non-secret
- * .figs/config.json ({ endpoint, workspaceId, agentId }). Run from the
- * agent's repo root, where `.figs/` lives.
+ * Two facts decide behavior: local-vs-linked (does config.json declare a
+ * workspaceId?) and authenticated (is there a token?). The config declares
+ * intent; the CLI errors only when declared intent can't be met. Identity is
+ * the *agent* — a UUID minted by `init` into the committed, non-secret
+ * .figs/config.json ({ agentId } locally; + { endpoint, workspaceId } once
+ * `figs link`ed). Auth is the *user* (a token, configured once per machine).
+ * Run from the agent's repo root, where `.figs/` lives.
  */
 
 import {
@@ -91,29 +99,39 @@ const COMMANDS = {
     eg: "figs login",
   },
   logout: { args: "", flags: [], desc: "remove the locally-saved token (~/.figs/credentials.json)" },
-  workspaces: {
-    args: "[--json]",
-    flags: ["--json"],
-    desc: "list your workspaces (read-only; shows the slug)",
-    eg: "figs workspaces",
-  },
   init: {
+    args: "",
+    flags: [],
+    desc: "scaffold .figs/ here — purely local, no account needed (identity + charter/contract/guide)",
+    more: [
+      "Zero flags, zero network: mints a stable agent id into config.json and scaffolds",
+      "the templates. You're fully operational locally from here — record runs/asks/answers,",
+      "validate, navigate. `figs link` later when you want it on the hosted app.",
+      "Idempotent: re-running keeps your identity AND any link (never unlinks), and never",
+      "clobbers an existing agent.json / CONTRACT.md / GUIDE.md / outbox.",
+    ],
+    eg: "figs init",
+  },
+  link: {
     args: "[--workspace <slug-or-id>] [--endpoint <url>]",
     flags: ["--workspace", "--endpoint"],
-    desc: "scaffold .figs/ here (identity + charter/contract/guide templates)",
+    desc: "connect this .figs/ to a workspace on the hosted app (so `figs push` can publish)",
     more: [
-      "--workspace takes a slug (resolved to its UUID) or a raw UUID — get it from `figs workspaces`.",
-      "Omit --workspace and (logged in) it uses your only workspace, or lists them so you can re-run with one.",
-      "Never clobbers: an existing agent.json / CONTRACT.md / GUIDE.md / outbox is left exactly as-is.",
+      "Bare: lists your workspaces (needs login); with exactly one, links it outright.",
+      "--workspace takes a slug (resolved via the API — needs login) or a raw UUID (no login",
+      "needed; get it from the app). --endpoint overrides the destination (default app.figs.so).",
+      "Verifies the workspace when you're logged in; a UUID set while logged out is accepted",
+      "but unverified until your first `figs push`. Writes endpoint + workspaceId into config.json.",
+      "To unlink, delete those two fields from .figs/config.json (your identity + work stay).",
     ],
-    eg: "figs init --workspace acme-corp",
+    eg: "figs link --workspace acme-corp",
   },
   report: {
     args: "--result <text> [options]",
     flags: [
       "--result", "--id", "--unit", "--period", "--status", "--trigger", "--attach", "--no-push",
     ],
-    desc: "file a job's outcome — settles its row in runs.jsonl; stamps id/ts/state, pushes",
+    desc: "settle a job — stamps id/ts/state into runs.jsonl (auto-pushes when linked)",
     more: [
       "One run = one JOB — a unit of work your manager would recognize; the runs",
       "list reads as the job list. Give a job a stable, meaningful --id",
@@ -129,9 +147,10 @@ const COMMANDS = {
       "validation, artifact copy, push).",
       "Single-quote prose values ('…') — inside double quotes your shell expands $,",
       "so \"($4,474.63)\" reaches figs as \"(,474.63)\": silent corruption.",
-      "--attach <file> (repeatable) copies the file into artifacts/ and links it.",
+      "--attach <file> (repeatable) pins a file to this moment (attachments[]) —",
+      "rendered types (html/md/txt/json/images) show inline; data/docs (csv/pdf/xlsx/docx) download.",
       "--no-push writes locally only; `figs push` publishes later.",
-      "Closing an ask is `figs resolve` — a close is not a job; never report one.",
+      "Closing an ask is `figs close` — a close is not a job; never report one.",
       "Hand-writing runs.jsonl works too — this verb is sugar over the same file.",
     ],
     eg: "figs report --id recon-acme-2026-11 --result '88% matched · 31 flagged' --attach ./acme-2025-11.html",
@@ -141,7 +160,7 @@ const COMMANDS = {
     flags: [
       "--id", "--note", "--trigger", "--status", "--unit", "--period", "--attach", "--no-push",
     ],
-    desc: "save a job's progress mid-flight — folds onto its row, marks it in-flight, pushes",
+    desc: "save a job's progress mid-flight — marks it in-flight (auto-pushes when linked)",
     more: [
       "Your first checkpoint OPENS the job (state: in-flight) — make it the first",
       "act of any job that will outlive this sitting: say what triggered it",
@@ -165,10 +184,10 @@ const COMMANDS = {
       "--id", "--title", "--need", "--found", "--option", "--on-approve", "--detail",
       "--attach", "--to", "--unit", "--run", "--stdin", "--no-push",
     ],
-    desc: "raise an ask — one self-contained line in asks.jsonl, pushed so a human sees it",
+    desc: "raise an ask — a self-contained line in asks.jsonl (auto-pushes when linked)",
     more: [
-      "<type> = the answer contract: needs-decision (give me an answer) ·",
-      "sign-off (give me a verdict) · fyi (no answer — a for-the-record note).",
+      "<type> = the answer contract: question (give me an answer) ·",
+      "sign-off (give me a verdict). Two types — the type IS the contract.",
       "Two strangers read every ask — a human deciding, a future session acting;",
       "the record must carry everything both need: --found (what you saw), --need",
       "(what you need), --option (repeatable; short, stable, quotable — answers cite",
@@ -188,36 +207,70 @@ const COMMANDS = {
     ],
     eg: "figs ask sign-off --title 'Send 10 payment reminders' --attach ./previews.html --on-approve 'Send the 10 reminder emails' --on-approve 'Mark the invoices chased' --run recon-2026-06",
   },
+  answer: {
+    args: "<ask-id> --by <who> (--chosen <option> | --text <reply> | --approve | --request-changes | --reject)",
+    flags: [
+      "--by", "--chosen", "--text", "--approve", "--request-changes", "--reject", "--no-push",
+    ],
+    desc: "record your human's out-of-band reply to an ask, verbatim (you run this, not them)",
+    more: [
+      "Humans don't type commands. They answer you in chat ('approved — only the 15');",
+      "you transcribe that into the record. --by names the HUMAN who said it, not you.",
+      "question → --chosen '<option verbatim>' (checked against the ask's options) or",
+      "--text '<what they said>'. sign-off → --approve | --request-changes | --reject",
+      "(a qualified verdict may also carry --chosen). Transcribe verbatim — never summarize,",
+      "never author the reply yourself.",
+      "Replies made IN the app sync down automatically (figs inbox) — `figs answer` is only",
+      "for replies that exist nowhere but your chat.",
+      "Then act, and `figs close <ask-id>` — it cites this reply automatically.",
+    ],
+    eg: "figs answer acme-bridge --chosen 'Strip the alpha prefix' --by 'Sarah (accounting)'",
+  },
   inbox: {
-    args: "[<ask-id>] [--json]",
-    flags: ["--json"],
-    desc: "what needs you — your humans' answers/verdicts on your asks (pure read)",
+    args: "[<ask-id>] [--json] [--no-sync]",
+    flags: ["--json", "--no-sync"],
+    desc: "what needs you — your humans' replies on your asks + your unfinished jobs (pure read)",
     more: [
       "Start every session with this. Bare: lists every ask with thread activity —",
       "answers and verdicts verbatim, plus the exact next command for each.",
       "With an ask id: the full handoff package — the ask, the whole thread, and its",
-      "attached artifacts restored into .figs/artifacts/ (hash-verified) so a fresh",
-      "session can act from the record alone.",
-      "Scope: THIS agent's open asks + human-rejected ones you haven't acknowledged",
-      "+ unfinished jobs (in-flight runs — your past self's work; finish or settle).",
-      "Reads only — closing still happens via figs resolve / figs report.",
+      "attached artifacts.",
+      "Scope: THIS agent's open asks + their replies + unfinished jobs (in-flight runs).",
+      "When linked, a soft messages-only down-sync runs first (degrades loudly, never blocks;",
+      "--no-sync to skip). Reads only — recording a chat reply is figs answer; closing is figs close.",
     ],
     eg: "figs inbox",
   },
-  resolve: {
-    args: "<ask-id> [--chosen <option>] [--by <who>] [--note <text>] [--withdrawn|--rejected]",
-    flags: ["--chosen", "--by", "--note", "--withdrawn", "--rejected", "--no-push"],
-    desc: "close an ask — appends the resolution fold line and pushes",
+  show: {
+    args: "<ask-id|job-id> [--json]",
+    flags: ["--json"],
+    desc: "magnify one ask or job — the folded record + its thread/trail + attachments (pure local)",
     more: [
-      "--chosen must quote one of the ask's options[] verbatim (checked).",
-      "Three closes, by who ended it: resolved (default — the need was met) ·",
-      "--withdrawn (YOU retracted it; nobody acted) · --rejected (a HUMAN declined",
-      "it — record their out-of-band no; rejected is terminal, re-raising = a new ask).",
-      "After an answer, fork on what it unlocked: nothing new → resolve right away;",
-      "real work → do the job, `figs report` it under its own id, THEN resolve —",
-      "cite the job id in --note so a reader can find the work.",
+      "Auto-detects an ask (shows the reply thread) or a job (shows its checkpoint trail).",
+      "Reads local files and folds them for you — no raw-JSONL spelunking. No network:",
+      "an attachment not on this machine is noted (view it in the app), never downloaded.",
     ],
-    eg: "figs resolve acme-bridge --chosen 'Strip the alpha prefix' --by 'Sarah (accounting)'",
+    eg: "figs show acme-bridge",
+  },
+  close: {
+    args: "<ask-id> [--note <text>] [--run <run-id>] [--attach <file>] [--withdrawn]",
+    flags: [
+      "--note", "--run", "--attach", "--withdrawn", "--no-push",
+      // accepted-but-removed: handled with a teaching error pointing to the new path
+      "--chosen", "--by", "--answer-id", "--rejected",
+    ],
+    desc: "close an ask — derives the close from the reply on file and cites it",
+    more: [
+      "A pure close: it reads the newest reply for the ask (recorded by `figs answer`",
+      "or synced from the app) and derives the outcome — resolved on an answer/approval,",
+      "rejected on a reject verdict; it refuses if nothing's answered yet, or if changes",
+      "were requested (revise and re-raise on the same id instead).",
+      "--run <run-id> links the JOB the reply set in motion (so a reader sees what you did).",
+      "--withdrawn = YOU retracted the ask (no reply needed; nobody acted).",
+      "After an answer, fork on what it unlocked: nothing new → close right away;",
+      "real work → do the job, `figs report` it under its own id, then close --run <that id>.",
+    ],
+    eg: "figs close acme-bridge --run apply-bridge-2026-06",
   },
   doctor: {
     args: "",
@@ -235,7 +288,11 @@ const COMMANDS = {
     ],
     eg: "figs push",
   },
-  version: { args: "", flags: [], desc: "print the CLI version and check for updates" },
+  version: {
+    args: "[--check]",
+    flags: ["--check"],
+    desc: "print the CLI version (offline); --check also asks the server for updates",
+  },
   help: { args: "[<command>]", flags: [], desc: "show this help, or detailed help for one command" },
 }
 
@@ -259,6 +316,14 @@ function die(msg) {
 function readJson(path, fallback) {
   return existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : fallback
 }
+/**
+ * The one `--json` envelope for read verbs: `{ ok, data, warnings }`. Uniform
+ * so an agent parses every read the same way and can branch on `ok` and surface
+ * `warnings` (e.g. a degraded sync) without scraping stderr.
+ */
+function printJson(data, { ok = true, warnings = [] } = {}) {
+  console.log(JSON.stringify({ ok, data, warnings }, null, 2))
+}
 /** Read a flag value — supports both `--name value` and `--name=value`. */
 function flag(name) {
   const args = process.argv.slice(2)
@@ -319,21 +384,26 @@ function genId(prefix) {
 // ---------- local validation (the spec's common mistakes, caught on write) ----
 // The server's schema stays the source of truth; these catch what hand-authors
 // and flag typos get wrong, with errors that teach the fix.
-// Three types = three answer contracts: needs-decision (give me an answer) ·
-// sign-off (give me a verdict) · fyi (no answer — a for-the-record note).
-// "blocked" was folded into needs-decision in 0.6.0: a stuck JOB is the run's
-// status, not an ask type; what you need from a human is a needs-decision.
-const ASK_TYPES = ["needs-decision", "sign-off", "fyi"]
+// Two types = two answer contracts, and the type IS the contract:
+//   question → answer (an option or free text) · sign-off → verdict.
+// History (all pre-launch, free to break): "blocked" folded into the type that
+// became "question" (a stuck JOB is the run's status, not an ask type);
+// "needs-decision" was renamed to "question" (1.0); "fyi" was retired (1.0) — a
+// for-the-record note is a settled report, not an ask.
+const ASK_TYPES = ["question", "sign-off"]
 const RUN_STATUSES = ["ok", "warn", "fail"]
 // Lifecycle, orthogonal to status (outcome): checkpoint stamps in-flight,
 // report stamps settled. Absent = settled (a plain report is a complete fact).
 const RUN_STATES = ["in-flight", "settled"]
 const ASK_STATUSES = ["open", "resolved", "withdrawn", "rejected"]
 const TO_VALUES = ["manager", "builder"]
-const ARTIFACT_EXTS = new Set([
-  ".html", ".md", ".txt", ".json", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg",
-])
-const ARTIFACT_MAX = 3 * 1024 * 1024
+// Two render classes. RENDERABLE shows inline in the sandboxed viewer;
+// DOWNLOAD_ONLY (data/docs — back-office work products) is offered as a
+// download, never rendered (lower risk than HTML rendering — nothing executes).
+const RENDERABLE_EXTS = [".html", ".md", ".txt", ".json", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".svg"]
+const DOWNLOAD_ONLY_EXTS = [".csv", ".pdf", ".xlsx", ".xls", ".docx"]
+const ARTIFACT_EXTS = new Set([...RENDERABLE_EXTS, ...DOWNLOAD_ONLY_EXTS])
+const ARTIFACT_MAX = 10 * 1024 * 1024
 
 /** "signoff" → `did you mean "sign-off"?` — normalized nearest match. */
 function didYouMean(value, allowed) {
@@ -355,13 +425,22 @@ function validateRun(r) {
   if (!r.ts) issues.push(`${label}: missing required "ts" (ISO-8601 — \`figs report\` stamps it for you)`)
   checkEnum(issues, r, "status", RUN_STATUSES, label)
   checkEnum(issues, r, "state", RUN_STATES, label)
-  if (r.artifact !== undefined && typeof r.artifact !== "string") {
-    issues.push(`${label}.artifact: must be a single file name (use "artifacts" for a list)`)
+  checkAttachments(issues, r, label)
+  return issues
+}
+/** attachments[] is the unified field (bare file names). The legacy run
+ *  `artifact`/`artifacts` and ask `refs` are still READ (attachmentsOf), so we
+ *  only type-check them here for back-compat; new writes use attachments[]. */
+function checkAttachments(issues, obj, label) {
+  if (obj.attachments !== undefined && (!Array.isArray(obj.attachments) || obj.attachments.some((a) => typeof a !== "string"))) {
+    issues.push(`${label}.attachments: must be an array of file names`)
   }
-  if (r.artifacts !== undefined && (!Array.isArray(r.artifacts) || r.artifacts.some((a) => typeof a !== "string"))) {
-    issues.push(`${label}.artifacts: must be an array of file names`)
+  if (obj.artifact !== undefined && typeof obj.artifact !== "string") {
+    issues.push(`${label}.artifact: legacy field — use attachments[] (an array of file names)`)
+  }
+  if (obj.artifacts !== undefined && (!Array.isArray(obj.artifacts) || obj.artifacts.some((a) => typeof a !== "string"))) {
+    issues.push(`${label}.artifacts: legacy field — use attachments[] (an array of file names)`)
   }
-  return issues
 }
 /** Validate one folded ask record → array of issue strings. */
 function validateAsk(a) {
@@ -374,7 +453,15 @@ function validateAsk(a) {
     )
   } else if (a.type === "blocked") {
     issues.push(
-      `${label}.type: "blocked" was folded into needs-decision — a stuck job is the RUN's status (re-report --status onto the same job id); what you need from a human is a needs-decision ask`,
+      `${label}.type: "blocked" isn't an ask type — a stuck job is the RUN's status (re-report --status onto the same job id); what you need from a human is a "question"`,
+    )
+  } else if (a.type === "needs-decision") {
+    issues.push(
+      `${label}.type: "needs-decision" was renamed to "question" (the type is the answer contract: question → answer · sign-off → verdict)`,
+    )
+  } else if (a.type === "fyi") {
+    issues.push(
+      `${label}.type: "fyi" was retired — a for-the-record note is a settled report (\`figs report\`), not an ask; if you actually need a human it's a "question" or "sign-off"`,
     )
   } else checkEnum(issues, a, "type", ASK_TYPES, label)
   if (!a.title) issues.push(`${label}: missing required "title"`)
@@ -396,16 +483,53 @@ function validateAsk(a) {
     issues.push(`${label}.details: must be [{ "l": "Label", "v": "Value" }]`)
   }
   if (a.refs !== undefined && (!Array.isArray(a.refs) || a.refs.some((r) => !r || typeof r.label !== "string"))) {
-    issues.push(`${label}.refs: must be [{ "label": "…", "artifact": "<file in artifacts/>" }]`)
+    issues.push(`${label}.refs: legacy field — use attachments[] (an array of file names)`)
   }
+  checkAttachments(issues, a, label)
   return issues
 }
-/** Validate the whole local outbox (folded) — returns all issues. */
-function validateOutbox(runs, asks) {
-  return [...runs.flatMap(validateRun), ...asks.flatMap(validateAsk)]
+// ---------- messages.jsonl — the human ledger -------------------------------
+// Human replies to asks: answers + verdicts (later: note/directive). Events,
+// not records — immutable, ids minted once, they accumulate (no fold). `source`
+// is *where* a reply arrived, display only — the verified grade comes from mint
+// origin (server-minted = attested; pushed-up = transcription), never `source`.
+const MSG_KINDS = ["answer", "verdict"]
+const VERDICTS = ["approved", "changes-requested", "rejected"]
+const MSG_SOURCES = ["app", "chat"]
+/** Validate one message event → array of issue strings. */
+function validateMessage(m) {
+  const issues = []
+  const label = `message "${m.id ?? "?"}"`
+  if (!m.id || typeof m.id !== "string") issues.push(`${label}: missing required "id"`)
+  if (!m.ask || typeof m.ask !== "string") issues.push(`${label}: missing required "ask" (the ask id this replies to)`)
+  if (!m.ts) issues.push(`${label}: missing required "ts"`)
+  if (!m.by) issues.push(`${label}: missing required "by" (who said it — the human, not you)`)
+  checkEnum(issues, m, "kind", MSG_KINDS, label)
+  checkEnum(issues, m, "verdict", VERDICTS, label)
+  checkEnum(issues, m, "source", MSG_SOURCES, label)
+  if (m.kind === "verdict" && !m.verdict) {
+    issues.push(`${label}: a verdict message needs "verdict" (${VERDICTS.join(" / ")})`)
+  }
+  if (m.kind === "answer" && !m.chosen && !m.text) {
+    issues.push(`${label}: an answer needs "chosen" or "text"`)
+  }
+  return issues
 }
-function getToken() {
-  return process.env.FIGS_TOKEN || readJson(globalCreds, {}).token
+
+/** Validate the whole local outbox (folded records + message events). */
+function validateOutbox(runs, asks, messages = []) {
+  return [
+    ...runs.flatMap(validateRun),
+    ...asks.flatMap(validateAsk),
+    ...messages.flatMap(validateMessage),
+  ]
+}
+/** Does an ask with this id exist locally — raised here, or known via a message? */
+function askExistsLocally(askId) {
+  return (
+    foldById(readJsonl("asks.jsonl")).some((a) => a.id === askId) ||
+    readJsonl("messages.jsonl").some((m) => m.ask === askId)
+  )
 }
 function resolveEndpoint() {
   const cfg = readJson(join(repoDir, "config.json"), {})
@@ -414,11 +538,96 @@ function resolveEndpoint() {
     "",
   )
 }
+// ---------- credentials, keyed by endpoint origin --------------------------
+// One token per endpoint origin so a prod token is never sent to a localhost
+// dev endpoint (the old single-token file's real bug) and prod + dev can coexist.
+// File shape: { "https://app.figs.so": { "token": "…" }, … }. The pre-1.0 shape
+// was a bare { "token": "…" } — migrated on read to the default endpoint.
+/** Canonical origin (scheme://host:port, no path/trailing slash) of a URL. */
+function originOf(url) {
+  try {
+    return new URL(url).origin
+  } catch {
+    return String(url).replace(/\/+$/, "")
+  }
+}
+/** Load the credentials file, migrating the legacy bare-token shape in memory. */
+function loadCreds() {
+  const raw = readJson(globalCreds, {})
+  if (typeof raw.token === "string") {
+    // Legacy single token — it was always the default endpoint's.
+    return { [originOf(DEFAULT_ENDPOINT)]: { token: raw.token } }
+  }
+  return raw
+}
+function getToken() {
+  return process.env.FIGS_TOKEN || loadCreds()[originOf(resolveEndpoint())]?.token
+}
+
+// ---------- the state model -------------------------------------------------
+// Two orthogonal facts: local-vs-linked (does config declare a workspace?) and
+// authenticated (is there a token?). The rule: the config declares intent; the
+// CLI errors only when declared intent can't be met. A local repo (no
+// workspaceId) is a deliberate, first-class state — never an error.
+
+/** Linked = config declares a destination workspace (intent to publish). */
+function isLinked() {
+  return Boolean(readJson(join(repoDir, "config.json"), {}).workspaceId)
+}
+
+// Exit codes: 0 = recorded (and published, if linked) · 1 = nothing written
+// (fix the input) · 2 = recorded locally, publish failed (retry `figs push`,
+// never re-run the verb). The canonical exit-2 line below is what an agent keys
+// on — the number inverts some CLI priors, so the words carry the contract.
+const RECORDED_LOCALLY =
+  "recorded locally — do NOT re-run this verb; `figs push` retries"
+
+/**
+ * When there's no `.figs/` in cwd, peek UPWARD (read-only) for a parent agent's
+ * folder so we can tell the agent where it is — but never adopt that identity.
+ * The fleet topology forbids walk-up: an openfigs fleet has the recruiter's
+ * `.figs/` at the root and each employee's own `.figs/` in its folder; silently
+ * using the parent would make a child agent report as the recruiter. Bounded;
+ * stops at the filesystem root.
+ */
+function peekParentFigs() {
+  let dir = join(process.cwd(), "..")
+  for (let i = 0; i < 40; i++) {
+    if (existsSync(join(dir, ".figs"))) {
+      return { dir, name: readJson(join(dir, ".figs", "agent.json"), {})?.name }
+    }
+    const parent = join(dir, "..")
+    if (parent === dir) break // filesystem root
+    dir = parent
+  }
+  return null
+}
+/** The "no .figs/ here" message — points at a parent if one exists, never uses it. */
+function noFigsHint() {
+  const p = peekParentFigs()
+  if (p) {
+    return `no .figs/ here, but found one at ${p.dir}${p.name ? ` (agent: ${p.name})` : ""} — if you ARE that agent, cd there; if you're a different agent, run \`figs init\` at YOUR root`
+  }
+  return "no .figs/ here — run `figs init` first"
+}
+
+/**
+ * Auth headers for a token. Standard `Authorization: Bearer` is the contract;
+ * we ALSO send the legacy `x-figs-token` through the transition so a 1.0 CLI
+ * works against an app that hasn't shipped Bearer yet. Drop `x-figs-token` here
+ * once the app requires Bearer (next MIN_CLI bump).
+ */
+function authHeaders(token) {
+  if (!token) return {}
+  return { authorization: `Bearer ${token}`, "x-figs-token": token }
+}
+
 const REQUEST_TIMEOUT_MS = 30000
+const SYNC_TIMEOUT_MS = 5000 // session-start sync degrades fast, never blocks
 /** `fetch` with a hard timeout so a hung server never stalls the agent. */
-async function fetchT(url, opts = {}) {
+async function fetchT(url, opts = {}, timeoutMs = REQUEST_TIMEOUT_MS) {
   const ctrl = new AbortController()
-  const t = setTimeout(() => ctrl.abort(), REQUEST_TIMEOUT_MS)
+  const t = setTimeout(() => ctrl.abort(), timeoutMs)
   try {
     return await fetch(url, { ...opts, signal: ctrl.signal })
   } finally {
@@ -439,7 +648,7 @@ async function request(method, path, body, token = getToken()) {
       method,
       headers: {
         "content-type": "application/json",
-        ...(token ? { "x-figs-token": token } : {}),
+        ...authHeaders(token),
       },
       body: body ? JSON.stringify(body) : undefined,
     })
@@ -526,12 +735,22 @@ function printHelp(name) {
     if (c.eg) console.log(`\n  e.g.  ${c.eg}`)
     return
   }
-  console.log("figs — publish your AI agent's state to Figs (https://figs.so)\n")
+  console.log("figs — your AI agent's work journal; report it to humans at https://figs.so\n")
   console.log("Usage: figs <command> [options]\n")
-  console.log("Commands:")
-  for (const [n, c] of Object.entries(COMMANDS)) {
-    console.log(`  ${`${n} ${c.args}`.trim().padEnd(pad)} ${c.desc}`)
+  // Grouped by layer so the local-first model is legible in the help itself:
+  // LOCAL works with no account; CONNECTED needs a one-time login + a workspace.
+  const LOCAL = ["init", "report", "checkpoint", "ask", "answer", "inbox", "show", "close", "doctor", "status", "version", "help"]
+  const CONNECTED = ["login", "logout", "link", "push"]
+  const printGroup = (title, names) => {
+    console.log(title)
+    for (const n of names) {
+      const c = COMMANDS[n]
+      if (c) console.log(`  ${`${n} ${c.args}`.trim().padEnd(pad)} ${c.desc}`)
+    }
   }
+  printGroup("Local (no account needed):", LOCAL)
+  console.log("")
+  printGroup("Connected (one-time login + a workspace):", CONNECTED)
   console.log("\nGlobal flags:")
   console.log(`  ${"-h, --help".padEnd(pad)} show help (or \`figs help <command>\`)`)
   console.log(`  ${"-v, --version".padEnd(pad)} print the CLI version`)
@@ -544,21 +763,25 @@ function printHelp(name) {
 
 if (cmd === "help" || cmd === "-h" || cmd === "--help") printHelp(process.argv[3])
 else if (cmd === "version" || cmd === "--version" || cmd === "-v" || cmd === "-V") {
+  // Offline by default — printing your own version must never need the network
+  // (contract: no network on the hot path of a local verb). `--check` opts in.
   console.log(VERSION)
-  await checkVersion({ force: true })
+  if (hasFlag("--check")) await checkVersion({ force: true })
 } else if (WANTS_HELP) printHelp(cmd)
 else if (COMMANDS[cmd]) {
   checkFlags(cmd) // reject unknown flags before running
   if (cmd === "login") await login(process.argv[3])
   else if (cmd === "logout") logout()
   else if (cmd === "status") await status()
-  else if (cmd === "workspaces") await workspaces()
   else if (cmd === "init") await init()
+  else if (cmd === "link") await link()
   else if (cmd === "report") await reportCmd()
   else if (cmd === "checkpoint") await checkpointCmd()
   else if (cmd === "ask") await askCmd()
+  else if (cmd === "answer") await answerCmd()
   else if (cmd === "inbox") await inboxCmd()
-  else if (cmd === "resolve") await resolveCmd()
+  else if (cmd === "show") await showCmd()
+  else if (cmd === "close") await closeCmd()
   else if (cmd === "doctor") await doctor()
   else if (cmd === "push") await push()
 } else {
@@ -570,9 +793,13 @@ function sleep(ms) {
   return new Promise((r) => setTimeout(r, ms))
 }
 function saveToken(token) {
+  // Key the token under the endpoint origin we're logging into; preserve tokens
+  // for other origins (migrating the legacy shape in the process).
+  const creds = loadCreds()
+  creds[originOf(resolveEndpoint())] = { token }
   // A bearer token must not be group/other-readable: dir 0700, file 0600.
   mkdirSync(globalDir, { recursive: true, mode: 0o700 })
-  writeFileSync(globalCreds, JSON.stringify({ token }, null, 2) + "\n", { mode: 0o600 })
+  writeFileSync(globalCreds, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 })
   // Enforce perms even if the dir/file pre-existed with looser modes (mode on
   // write only applies at creation).
   try {
@@ -654,15 +881,22 @@ async function login(token) {
  * can't be removed here (unset the env var to fully log out).
  */
 function logout() {
-  if (existsSync(globalCreds)) {
+  const origin = originOf(resolveEndpoint())
+  const creds = loadCreds()
+  if (creds[origin]) {
+    delete creds[origin]
     try {
-      rmSync(globalCreds)
+      if (Object.keys(creds).length) {
+        writeFileSync(globalCreds, JSON.stringify(creds, null, 2) + "\n", { mode: 0o600 })
+      } else if (existsSync(globalCreds)) {
+        rmSync(globalCreds) // nothing left — remove the file entirely
+      }
     } catch (e) {
-      die(`could not remove ${globalCreds}: ${e?.message || e}`)
+      die(`could not update ${globalCreds}: ${e?.message || e}`)
     }
-    console.log("figs: ✓ logged out — removed ~/.figs/credentials.json")
+    console.log(`figs: ✓ logged out of ${origin} (other endpoints' tokens, if any, are kept)`)
   } else {
-    console.log("figs: not logged in — no ~/.figs/credentials.json to remove")
+    console.log(`figs: not logged in to ${origin} — nothing to remove`)
   }
   if (process.env.FIGS_TOKEN) {
     console.warn(
@@ -696,30 +930,30 @@ async function status() {
     }
   }
 
+  const linked = Boolean(cfg?.workspaceId)
+
   if (JSON_OUT) {
-    console.log(
-      JSON.stringify(
-        {
-          version: VERSION,
-          endpoint,
-          loggedIn,
-          account: account
-            ? { id: account.id, email: account.email, name: account.name }
-            : null,
-          workspaces: list?.map((w) => ({ id: w.id, name: w.name, role: w.role })),
-          config: cfg ? { workspaceId: cfg.workspaceId, agentId: cfg.agentId } : null,
-          agentJson: hasAgent,
-          contractMd: hasContract,
-        },
-        null,
-        2,
-      ),
-    )
-    return
+    return printJson({
+      version: VERSION,
+      mode: linked ? "linked" : "local",
+      endpoint,
+      loggedIn,
+      account: account ? { id: account.id, email: account.email, name: account.name } : null,
+      workspaces: list?.map((w) => ({ id: w.id, name: w.name, role: w.role })),
+      config: cfg ? { agentId: cfg.agentId, workspaceId: cfg.workspaceId ?? null } : null,
+      agentJson: hasAgent,
+      contractMd: hasContract,
+    })
   }
 
   const row = (k, v) => console.log(`  ${(k + ":").padEnd(12)} ${v}`)
   console.log("figs status")
+  row(
+    "mode",
+    linked
+      ? "linked — publishes to the hosted app on push"
+      : "local — fully operational offline; `figs link` to publish",
+  )
   row(
     "logged in",
     loggedIn
@@ -728,7 +962,9 @@ async function status() {
         ? `can't reach ${endpoint}`
         : token
           ? "token invalid — run `figs login`"
-          : "no — run `figs login`",
+          : linked
+            ? "no — run `figs login`, then `figs push`"
+            : "no (not needed for local mode)",
   )
   if (loggedIn) {
     row(
@@ -740,9 +976,7 @@ async function status() {
   }
   row(
     "workspace",
-    cfg?.workspaceId
-      ? cfg.workspaceId
-      : "not initialized — run `figs init --workspace <id>`",
+    linked ? cfg.workspaceId : "none — `figs link` to connect one",
   )
   row("agent.json", hasAgent ? "present (identity)" : "missing — author .figs/agent.json")
   row(
@@ -751,65 +985,17 @@ async function status() {
       ? "present (activity) — follow it"
       : "none yet — Activity is optional, agree it with your user",
   )
+  row("journal", "records live on this machine (the app is the durable record once linked)")
   row("endpoint", endpoint)
   row("cli", VERSION)
 }
 
-/**
- * List the user's workspaces (read-only). Creating a workspace is a human,
- * web-side action — the agent only ever joins one it was pointed at. Surfaces
- * the slug, which is what `figs init --workspace <slug>` takes.
- */
-async function workspaces() {
-  const { workspaces: list = [] } = await api("GET", "/api/workspaces")
-  if (JSON_OUT) return void console.log(JSON.stringify(list, null, 2))
-  if (list.length === 0) {
-    console.log("figs: no workspaces yet — create one in the Figs web app, then re-run.")
-    return
-  }
-  console.log(`figs: ${list.length} workspace${list.length === 1 ? "" : "s"}`)
-  for (const w of list) {
-    console.log(`  ${String(w.role).padEnd(6)} ${w.slug}  —  ${w.name}`)
-  }
-  console.log("  → figs init --workspace <slug>")
-}
-
 function isUuid(s) {
   return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
     String(s),
   )
 }
 
-/**
- * The local `.figs/GUIDE.md` is a thin orientation breadcrumb (safe to
- * regenerate) — the full, always-current guide + schema is served at
- * `${endpoint}/llms.txt`, and the agent's own standing agreement lives in the
- * precious, agent-authored `.figs/CONTRACT.md` (which `init` never touches).
- */
-function guideStub(endpoint) {
-  return `<!-- Written by \`figs init\` (safe to regenerate). Orientation only — the full
-     guide lives at the URL below; your own contract lives in CONTRACT.md. -->
-# Figs — this folder
-
-This repo publishes to **Figs** (your manager's read-only window into what you do).
-
-- **Full guide + schema → ${endpoint}/llms.txt** — read this first.
-- **Your contract → ./CONTRACT.md** — what you publish / hold back (you + your user author it).
-- **Identity → config.json** (committed) · **charter → agent.json** (you write).
-- **Stay visible:** keep the \`figs:begin\`…\`figs:end\` block in the instruction file you load every
-  session (CLAUDE.md/AGENTS.md/…). It's what brought you back here — don't remove it. (Phase-1 setup; see /llms.txt.)
-
-**Where are you?** You may be reading this at any time — don't assume you're starting fresh. Run
-\`figs status\` and check \`.figs/\` before acting:
-  • not set up yet → author \`.figs/agent.json\`, then \`figs doctor\` && \`figs push\` to appear (Identity).
-  • CONTRACT.md present → follow it; keep publishing what it says.
-  • no CONTRACT.md yet → agree with your user what work to surface (Activity) — see ${endpoint}/llms.txt.
-
-Commit config.json + agent.json + CONTRACT.md + this file. runs.jsonl / asks.jsonl / artifacts/
-are a gitignored outbox. The token is the human's job — never generate one yourself.
-`
-}
-
 /**
  * A starter `agent.json` — written by `figs init` only when none exists. The
  * `<…>` values are placeholders the agent fills in by reading its own repo;
@@ -837,28 +1023,36 @@ function agentJsonStub(name) {
   )
 }
 
-/** A starter activity contract — written by `figs init` only when none exists. */
+/**
+ * A starter CONTRACT — the going-live record, written by `figs init` only when
+ * none exists. It's the agent↔user agreement, authored in the going-live
+ * conversation (not mechanically). The `<…>` prompts are answered with the user.
+ */
 function contractStub(name) {
-  return `# Activity contract — ${name} on Figs
+  return `# Contract — ${name} on Figs
 
-What this agent surfaces to Figs vs. holds back. **Agree it with your user** — this is the
-deliberate Activity step, not something to do mechanically. See \`.figs/GUIDE.md\` for the why.
+The agreement between this employee and its humans: what counts as real work, what gets surfaced,
+what's held back. **Author this WITH your user** in the going-live conversation (see the guide) —
+not mechanically. Keep it honest and current.
 
-> **Maintain:** edit when the surfacing agreement changes (a new stream, a sensitivity change).
-> Keep it honest to what you actually push.
+> **Maintain:** edit when the work or the surfacing agreement changes.
 
-## What I surface
+## Fit
+<are you a good fit? Figs is for recurring work a human wants to stay in the loop on. "Not yet,
+because X" is a valid, honest answer.>
 
-| Stream | Surface? | Content |
-|--------|----------|---------|
-| **runs** | <yes/no> | one line per run — what I did, de-identified scope, the headline result + status. |
-| **artifacts** | <yes/no> | the report(s) a run produced. |
-| **asks** | when real | genuine blockers / decisions / sign-offs / FYIs for my manager. 0 is a fine number. |
+## What's a job (what I report)
+- **A job is:** <the unit your manager would recognize — e.g. "one monthly reconciliation">
+- **I checkpoint:** <the mid-flight steps a human would recognize, for jobs that outlive a sitting>
+- **A job settles when:** <the headline result that means done>
 
 ## What I never surface
-
 Raw user content — ever. Plus, for this agent: <anything sensitive to its domain>. Use
 **de-identified labels** (\`<scope>-01\`), never customer or system names.
+
+## Inbox cadence
+<when do I process human replies? dedicated schedule (recommended) · spawned sweep · at session
+start. How it's scheduled is a build concern (OpenFigs) + your user's call — record it here.>
 `
 }
 
@@ -884,72 +1078,89 @@ function findPlaceholders(obj) {
 }
 
 /**
- * Resolve which workspace this `.figs/` belongs to. `--workspace` is optional:
- *  - given a UUID  → use it as-is (no network).
- *  - given a slug  → resolve to its UUID via the API (needs auth).
- *  - omitted       → reuse the one already in config.json (idempotent re-init);
- *                    else use the user's only workspace (logged, so it's visible);
- *                    else list them and have the agent re-run with one (when
- *                    there's a real choice, the agent drives it — we never guess).
- * Returns the workspace UUID, or exits with an actionable message.
+ * `figs link` — connect this `.figs/` to a workspace so `figs push` can publish.
+ * The ONLY place remote config (endpoint + workspaceId) is written; `init` stays
+ * purely local. `--workspace`:
+ *  - a UUID → written as-is; verified when logged in, else "unverified until push".
+ *  - a slug → resolved via the API (needs login).
+ *  - omitted → list the user's workspaces (needs login); with exactly one, link it.
+ * Identity (agentId) is preserved untouched.
  */
-async function resolveWorkspaceId(workspaceArg, endpoint) {
-  if (workspaceArg) {
-    if (isUuid(workspaceArg)) return workspaceArg
-    if (!getToken()) {
-      die("not logged in — run `figs login` first (resolving a workspace slug needs auth; or pass the workspace UUID)")
+async function link() {
+  if (!existsSync(repoDir)) die(noFigsHint())
+  const config = readJson(join(repoDir, "config.json"), {})
+  if (!config.agentId) die("config missing agentId — run `figs init` first")
+  // Honor --endpoint, then FIGS_ENDPOINT (dev), then any existing config, then
+  // the baked default — resolveEndpoint() encodes that precedence.
+  const endpoint = (flag("--endpoint") || resolveEndpoint()).replace(/\/+$/, "")
+  const wsArg = flag("--workspace")
+  const token = getToken()
+
+  let workspaceId
+  if (wsArg && isUuid(wsArg)) {
+    workspaceId = wsArg
+    if (token) {
+      // Verify access when we can; a network blip just defers it to first push.
+      const r = await request("GET", "/api/workspaces", null, token)
+      if (r.ok && !(r.data.workspaces ?? []).some((w) => w.id === wsArg)) {
+        die(`workspace ${wsArg} isn't one you can access — run \`figs link\` (no flag) to list yours`)
+      }
+    } else {
+      console.warn("figs: ! linked by UUID while logged out — unverified until your first `figs push`")
     }
-    const r = await request("GET", "/api/workspaces", null, getToken())
-    if (!r.ok) {
-      die(`could not resolve workspace "${workspaceArg}" (${r.status}): ${r.data.error ?? r.data.raw ?? ""}`)
+  } else if (wsArg) {
+    // A slug — only the server can map it to a UUID.
+    if (!token) {
+      die("resolving a workspace slug needs `figs login` first — or pass the workspace UUID (from the app's settings)")
+    }
+    const r = await request("GET", "/api/workspaces", null, token)
+    if (!r.ok) die(`could not resolve workspace "${wsArg}" (${r.status || "network"}): ${r.data.error ?? r.data.raw ?? ""}`)
+    const match = (r.data.workspaces ?? []).find((w) => w.slug === wsArg || w.id === wsArg)
+    if (!match) die(`no workspace matching "${wsArg}" — run \`figs link\` (no flag) to list yours`)
+    workspaceId = match.id
+  } else {
+    // Bare `figs link` — list; with exactly one, link it outright.
+    if (!token) {
+      die("run `figs login` first, then `figs link` to pick a workspace — or `figs link --workspace <uuid>` (no login needed)")
     }
+    const r = await request("GET", "/api/workspaces", null, token)
+    if (!r.ok) die(`could not list workspaces (${r.status || "network"}): ${r.data.error ?? r.data.raw ?? ""}`)
     const list = r.data.workspaces ?? []
-    const match = list.find((w) => w.slug === workspaceArg || w.id === workspaceArg)
-    if (!match) die(`no workspace matching "${workspaceArg}" — run \`figs workspaces\` to see yours`)
-    return match.id
+    if (list.length === 0) die(`no workspaces yet — create one at ${endpoint}, then re-run \`figs link\``)
+    if (list.length === 1) {
+      workspaceId = list[0].id
+      console.log(`figs: linking to ${list[0].slug} (${list[0].name})`)
+    } else {
+      console.log("figs: which workspace? re-run with one:")
+      for (const w of list) console.log(`        figs link --workspace ${w.slug}   (${w.name})`)
+      process.exit(1)
+    }
   }
 
-  // No --workspace: a re-init keeps the workspace already on file.
-  const existing = readJson(join(repoDir, "config.json"), null)
-  if (existing?.workspaceId) return existing.workspaceId
-
-  // First-time init with no workspace named — use the only one, else list them.
-  if (!getToken()) {
-    die("which workspace? run `figs login` first so I can list them, then `figs init --workspace <slug>` (or pass a workspace UUID directly)")
-  }
-  const r = await request("GET", "/api/workspaces", null, getToken())
-  if (!r.ok) die(`could not list workspaces (${r.status}): ${r.data.error ?? r.data.raw ?? ""}`)
-  const list = r.data.workspaces ?? []
-  if (list.length === 0) {
-    die(`no workspaces yet — create one at ${endpoint}, then re-run \`figs init --workspace <slug>\``)
-  }
-  if (list.length === 1) {
-    console.log(`figs: using workspace ${list[0].slug} (${list[0].name})`)
-    return list[0].id
-  }
-  console.log("figs: which workspace? re-run init with one of these:")
-  for (const w of list) console.log(`        figs init --workspace ${w.slug}   (${w.name})`)
-  process.exit(1)
+  // Preserve identity; write the destination. config.json shape when linked:
+  // { agentId, endpoint, workspaceId }.
+  writeFileSync(
+    join(repoDir, "config.json"),
+    JSON.stringify({ agentId: config.agentId, endpoint, workspaceId }, null, 2) + "\n",
+  )
+  console.log(`figs: ✓ linked — workspace ${workspaceId} @ ${endpoint}`)
+  console.log("        next: `figs push` publishes everything recorded so far")
 }
 
 async function init() {
-  const endpoint = (flag("--endpoint") || resolveEndpoint()).replace(/\/+$/, "")
-  const workspaceId = await resolveWorkspaceId(flag("--workspace"), endpoint)
-
-  // config.json (identity + destination) is always (re)written — it's the one
-  // file the CLI owns. A re-init reuses the existing identity UUID so every
-  // runner of this repo pushes to the same agent.
+  // Purely local — `init` never touches the network, so it can never need an
+  // account. Idempotent: keep the existing identity AND any link fields (a
+  // re-init must NOT unlink), and never clobber an authored charter/contract/
+  // guide or the outbox.
   const existing = readJson(join(repoDir, "config.json"), null)
   const agentId = existing?.agentId || randomUUID()
   mkdirSync(repoDir, { recursive: true })
-  writeFileSync(
-    join(repoDir, "config.json"),
-    JSON.stringify({ endpoint, workspaceId, agentId }, null, 2) + "\n",
-  )
+  const config = { agentId }
+  if (existing?.endpoint) config.endpoint = existing.endpoint
+  if (existing?.workspaceId) config.workspaceId = existing.workspaceId
+  writeFileSync(join(repoDir, "config.json"), JSON.stringify(config, null, 2) + "\n")
 
-  // Everything else is scaffolded create-if-missing — `figs init` gives a fresh
-  // repo a complete, ready-to-fill `.figs/`, and never clobbers an agent's
-  // authored charter/contract/guide or its activity outbox.
+  const endpoint = resolveEndpoint()
   const created = []
   const ensure = (rel, contents) => {
     const p = join(repoDir, rel)
@@ -961,54 +1172,55 @@ async function init() {
   ensure(
     ".gitignore",
     [
-      "# Figs — commit config.json + agent.json + CONTRACT.md + GUIDE.md.",
-      "# Activity is a transient outbox: emitted per run, aggregated remotely.",
+      "# Figs — commit config.json + agent.json + CONTRACT.md.",
+      "# The journal below is a machine-local outbox: records live on this machine;",
+      "# the hosted app is the durable record once you `figs link` + `figs push`.",
       "runs.jsonl",
       "asks.jsonl",
+      "messages.jsonl",
       "artifacts/",
       "credentials.json",
       "",
     ].join("\n"),
   )
-  ensure("GUIDE.md", guideStub(endpoint))
   const name = basename(process.cwd())
   const charterCreated = ensure("agent.json", agentJsonStub(name))
   ensure("CONTRACT.md", contractStub(name))
   ensure("runs.jsonl", "")
   ensure("asks.jsonl", "")
+  ensure("messages.jsonl", "")
   mkdirSync(join(repoDir, "artifacts"), { recursive: true })
 
-  console.log(
-    `figs: ✓ .figs/ ready — config.json written (agentId ${agentId}, workspace ${workspaceId})`,
-  )
+  console.log(`figs: ✓ .figs/ ready — you're operational locally (agentId ${agentId})`)
   if (created.length) console.log(`        scaffolded: ${created.join(", ")}`)
   if (charterCreated) {
     console.log(
-      "        Phase 1: fill in .figs/agent.json — it's a template; replace the <…> placeholders",
-    )
-    console.log(
-      "        (`figs doctor` flags any you miss), then `figs doctor` && `figs push` to appear.",
+      "        next: fill in .figs/agent.json — replace the <…> placeholders (`figs doctor` checks them)",
     )
   } else {
     console.log(
-      "        Your charter (.figs/agent.json) is already here — `figs doctor` && `figs push` to publish.",
+      "        your charter (.figs/agent.json) is already here — `figs doctor` to validate it",
     )
   }
   console.log(
-    "        Anchor Figs in the file you load every session (CLAUDE.md/AGENTS.md/…): paste the",
+    "        record work: `figs report` / `figs checkpoint` · raise asks: `figs ask` · recover: `figs inbox`",
+  )
+  console.log(
+    `        publish to the hosted app (optional)${existing?.workspaceId ? " — already linked" : ": `figs link`"}, then \`figs push\``,
+  )
+  console.log(
+    `        Anchor Figs in the file you load each session (CLAUDE.md/AGENTS.md/…): paste the figs:begin block from ${endpoint}/llms.txt.`,
   )
-  console.log(`        figs:begin block from ${endpoint}/llms.txt, or future sessions forget Figs.`)
   console.log(
-    "        Commit config.json + agent.json + CONTRACT.md + GUIDE.md; never commit credentials.json.",
+    "        Commit config.json + agent.json + CONTRACT.md; never commit credentials.json.",
   )
-  console.log(`        Full guide: ${endpoint}/llms.txt`)
 }
 
 // ====================== the writing verbs ===================================
-// report / ask / resolve — sugar over the same files (hand-writing stays
-// first-class). The agent supplies content; the CLI stamps id + real-clock ts,
-// validates with teaching errors, copies attachments, then invokes the same
-// push as `figs push`.
+// report / checkpoint / ask / answer / close — sugar over the same files
+// (hand-writing stays first-class). The agent supplies content; the CLI stamps
+// id + real-clock ts, validates with teaching errors, copies attachments, then
+// (when linked) invokes the same push as `figs push`.
 //
 // NOTE — no session auto-capture (removed in 0.5.0). The CLI used to infer a
 // `session` trace (runtime/model/tokens) from "the newest transcript on this
@@ -1019,15 +1231,47 @@ async function init() {
 // from the runtime's own records at work-time.
 
 function requireFigs() {
-  if (!existsSync(repoDir)) die("no .figs/ here — run `figs init` first")
+  if (!existsSync(repoDir)) die(noFigsHint())
   const config = readJson(join(repoDir, "config.json"), {})
-  if (!config.workspaceId || !config.agentId) {
-    die("config missing workspaceId/agentId — run `figs init`")
-  }
+  // Identity is all a writing verb needs — workspaceId is only required to
+  // publish (push/link). A repo without it is in deliberate local mode.
+  if (!config.agentId) die("config missing agentId — run `figs init`")
 }
 function appendJsonl(name, obj) {
   appendFileSync(join(repoDir, name), JSON.stringify(obj) + "\n")
 }
+
+// ---------- reference checks (warn, never block) ----------------------------
+// A dangling link is damage-limited; a blocked verb is not — so reference
+// checks WARN, they don't die. (Closing/answering a nonexistent ask DOES die —
+// that lives with those verbs.) Under the topology rule the local journal is
+// complete, so these checks are trustworthy.
+
+/** Announce whether a stable --id opened a new record or folded onto one. */
+function announceFold(kind, id, isNew, suffix = "") {
+  console.log(
+    isNew
+      ? `figs:   new ${kind} opened: ${id}${suffix}`
+      : `figs:   folded onto existing ${kind} ${id}`,
+  )
+}
+/** --unit should name a charter unit; warn on a typo (only once units exist). */
+function warnUnknownUnit(unit) {
+  if (!unit) return
+  const units = (readJson(join(repoDir, "agent.json"), {}).units ?? [])
+    .map((u) => u?.id)
+    .filter(Boolean)
+  if (units.length && !units.includes(unit)) {
+    console.warn(`figs: ! --unit "${unit}" isn't one of your charter units (${units.join(", ")}) — typo?`)
+  }
+}
+/** --run should name a job in this journal; warn on a dangling link. */
+function warnUnknownRun(runId) {
+  if (!runId) return
+  if (!foldById(readJsonl("runs.jsonl")).some((r) => r.id === runId)) {
+    console.warn(`figs: ! --run "${runId}" isn't a job in this journal — typo? this link will dangle`)
+  }
+}
 /** Copy attachments into artifacts/ — ext + size checks; immutable once there. */
 function attachFiles(paths) {
   const names = []
@@ -1039,7 +1283,7 @@ function attachFiles(paths) {
     }
     const bytes = readFileSync(p)
     if (bytes.length > ARTIFACT_MAX) {
-      die(`--attach: ${basename(p)} is ${(bytes.length / 1048576).toFixed(1)} MB — over the 3 MB cap; compress or split it`)
+      die(`--attach: ${basename(p)} is ${(bytes.length / 1048576).toFixed(1)} MB — over the ${ARTIFACT_MAX / 1048576} MB cap; compress or split it`)
     }
     const name = basename(p)
     const dest = join(repoDir, "artifacts", name)
@@ -1072,7 +1316,11 @@ function warnEatenDollar(...texts) {
   }
 }
 
-// ---------- the inbox (the DOWN direction — a pure read) ---------------------
+// ---------- the inbox + show (the DOWN view — pure local reads) -------------
+// Everything here reads local files: in-flight jobs (runs.jsonl), open asks
+// (asks.jsonl), reply threads (messages.jsonl). No win-logic — the agent gets
+// the complete, time-ordered truth and judges. (The soft messages-only
+// down-sync when linked is layered on top in a later step.)
 
 /** Relative time for inbox lines — rough on purpose. */
 function agoStr(iso) {
@@ -1081,295 +1329,462 @@ function agoStr(iso) {
   if (mins < 60 * 48) return `${Math.round(mins / 60)}h ago`
   return `${Math.round(mins / 1440)}d ago`
 }
-
-/** Fetch this agent's inbox; null on any failure when `soft` (auto-cite path). */
-async function fetchInbox({ soft = false } = {}) {
-  const config = readJson(join(repoDir, "config.json"), {})
-  if (!config.agentId) {
-    if (soft) return null
-    die("config missing agentId — run `figs init`")
-  }
-  const r = await request("GET", `/api/inbox?agent=${config.agentId}`)
-  if (!r.ok) {
-    if (soft) return null
-    die(`inbox failed (${r.status || "network"}): ${r.data.error ?? r.data.raw ?? ""}`)
-  }
-  return r.data
+/** Replies for an ask, oldest-first (messages accumulate; order by ts). */
+function repliesFor(messages, askId) {
+  return messages
+    .filter((m) => m.ask === askId)
+    .sort((a, b) => new Date(a.ts) - new Date(b.ts))
 }
-
-/** One human event, verbatim — answers are instructions; never paraphrase them. */
-function eventLine(e) {
+/** One reply, verbatim — never paraphrase a human's words. `(transcribed)`
+ *  marks a chat reply (self-reported); app replies are attested by mint origin. */
+function messageLine(m) {
   const head =
-    e.kind === "verdict"
-      ? `${e.verdict.replace(/_/g, " ")} by ${e.byName} (${e.asRole})`
-      : `answered by ${e.byName} (${e.asRole})`
-  const body = [e.chosen ? `→ "${e.chosen}"` : null, e.text ? `"${e.text}"` : null]
+    m.kind === "verdict"
+      ? `${String(m.verdict).replace(/-/g, " ")} by ${m.by}`
+      : `answered by ${m.by}`
+  const grade = m.source === "app" ? "" : " (transcribed)"
+  const body = [m.chosen ? `→ "${m.chosen}"` : null, m.text ? `"${m.text}"` : null]
     .filter(Boolean)
     .join(" · ")
-  return `${head} · ${agoStr(e.createdAt)}${body ? `\n      ${body}` : ""}`
-}
-
-/** The type×state matrix → the exact next command. The stranger never needs
- *  to know the state machine — the protocol tells them their move. */
-function nextMove(a) {
-  if (a.status === "rejected") {
-    return `a human declined this — acknowledge it: figs resolve ${a.id} --rejected`
-  }
-  const last = a.events[a.events.length - 1]
-  if (!last) return "waiting on your human — nothing for you to do"
-  if (last.kind === "verdict" && last.verdict === "approved") {
-    // A qualified verdict carries the chosen answer path — cite it in the close.
-    const chosen = last.chosen ? ` --chosen '${last.chosen}'` : ""
-    return (
-      `approved — verify any prerequisites in the ask, then fork on what it unlocked:` +
-      `\n      nothing left to do → figs resolve ${a.id}${chosen}` +
-      `\n      real work → do the job, figs report it under its own --id, then figs resolve ${a.id}${chosen} --note 'job <id>'`
-    )
+  return `${head}${grade} · ${agoStr(m.ts)}${body ? `\n      ${body}` : ""}`
+}
+/** Attachments on a record — the new `attachments[]`, falling back to the old
+ *  run `artifact`/`artifacts` and ask `refs` shapes (forward-compatible reads). */
+function attachmentsOf(rec) {
+  if (Array.isArray(rec.attachments)) return rec.attachments
+  return [
+    ...[rec.artifact, ...(rec.artifacts ?? [])].filter(Boolean),
+    ...(rec.refs ?? []).map((r) => r?.artifact).filter(Boolean),
+  ]
+}
+/** The newest reply on an ask → the exact next command. */
+function nextMove(ask, replies) {
+  const last = replies[replies.length - 1]
+  if (!last) {
+    return "waiting on your human — relay the ask to them in chat; record their reply with `figs answer`"
   }
-  if (last.kind === "verdict" && last.verdict === "changes_requested") {
-    return `revise, then re-raise on the same id: figs ask ${a.type} --id ${a.id} --title '…' …`
+  if (last.kind === "verdict" && last.verdict === "changes-requested") {
+    return `changes requested — revise, then re-raise on the same id: figs ask ${ask.type ?? "sign-off"} --id ${ask.id} --title '…' …`
   }
-  if (last.chosen) {
-    // Pre-fill the cited option verbatim — the note is substance for --note, never for --chosen.
-    const note = last.text ? ` --note '…'` : ""
-    return `act on the answer (real work → figs report it under its own --id), then: figs resolve ${a.id} --chosen '${last.chosen}'${note}`
+  if (last.kind === "verdict" && last.verdict === "rejected") {
+    return `declined — acknowledge it: figs close ${ask.id}`
   }
-  return `act on the answer (real work → figs report it under its own --id), then: figs resolve ${a.id} --note '…'`
+  return `act on it (real work → figs report it under its own --id), then: figs close ${ask.id}${"" /* --run <job> when work was done */}`
 }
 
-/** Restore an ask's refs into artifacts/ — hash-verified; never clobbers. */
-async function fetchRefs(config, refs) {
-  for (const ref of refs ?? []) {
-    if (!ref.artifact) continue
-    const name = ref.artifact
-    let res
-    try {
-      res = await fetchT(
-        `${resolveEndpoint()}/api/artifacts/raw?agent=${config.agentId}&name=${encodeURIComponent(name)}`,
-        { headers: { "x-figs-token": getToken() } },
-      )
-    } catch (e) {
-      console.warn(`figs: ! couldn't fetch artifacts/${name} (${netReason(e)})`)
-      continue
-    }
-    if (!res.ok) {
-      console.warn(`figs: ! couldn't fetch artifacts/${name} (${res.status})`)
-      continue
-    }
-    const bytes = Buffer.from(await res.arrayBuffer())
-    const want = res.headers.get("x-figs-sha256")
-    if (want && createHash("sha256").update(bytes).digest("hex") !== want) {
-      console.warn(`figs: ! artifacts/${name}: bytes didn't match the server's hash — skipped`)
-      continue
-    }
-    const dest = join(repoDir, "artifacts", name)
-    if (existsSync(dest)) {
-      if (readFileSync(dest).equals(bytes)) {
-        console.log(`figs:   ✓ artifacts/${name} (already present)`)
-      } else {
-        console.warn(
-          `figs: ! artifacts/${name} exists locally with different content — left untouched (the published copy stays one fetch away)`,
-        )
-      }
-      continue
-    }
-    mkdirSync(join(repoDir, "artifacts"), { recursive: true })
-    writeFileSync(dest, bytes)
-    console.log(`figs:   ✓ artifacts/${name} (fetched, hash ok)`)
+/**
+ * The one thing that flows DOWN (spec v2 §8): this agent's human messages,
+ * merged into `messages.jsonl` (append-if-id-absent). Soft — it never blocks
+ * the inbox; returns a status the caller surfaces. Runs only when linked + a
+ * token is present. The trust grade is the server's to enforce (it forces
+ * `source:"chat"` on transcriptions); the CLI just folds messages in by id.
+ */
+async function syncMessages() {
+  const config = readJson(join(repoDir, "config.json"), {})
+  if (!config.workspaceId) return { ran: false, reason: "local" }
+  const token = getToken()
+  if (!token) return { ran: false, reason: "not logged in" }
+  const base = resolveEndpoint()
+  let res
+  try {
+    res = await fetchT(
+      `${base}/api/messages?agent=${config.agentId}`,
+      { headers: authHeaders(token) },
+      SYNC_TIMEOUT_MS,
+    )
+  } catch (e) {
+    return { ran: false, reason: `couldn't reach ${base} (${netReason(e)})` }
+  }
+  if (!res.ok) {
+    const t = await res.text().catch(() => "")
+    return { ran: false, reason: `sync failed (${res.status})${t ? `: ${t.slice(0, 120)}` : ""}` }
   }
+  let data
+  try {
+    data = await res.json()
+  } catch {
+    return { ran: false, reason: "sync returned non-JSON" }
+  }
+  const incoming = Array.isArray(data.messages) ? data.messages : []
+  const have = new Set(readJsonl("messages.jsonl").map((m) => m.id))
+  let added = 0
+  for (const m of incoming) {
+    if (!m?.id || have.has(m.id)) continue // immutable + id-keyed → dedup is exact
+    appendJsonl("messages.jsonl", m)
+    have.add(m.id)
+    added++
+  }
+  return { ran: true, added, truncated: Boolean(data.truncated) }
 }
 
 /**
- * `figs inbox` — session start. Bare: every ask with thread activity + the
- * next command for each. With an id: the zero-context handoff package (the
- * ask, the whole thread verbatim, refs restored to disk). Pure read — writes
- * nothing to the outbox; closing happens via resolve.
+ * `figs inbox` — session start. When linked, a soft messages-only down-sync
+ * runs first (degradable; loud on failure/truncation), then everything is a
+ * local read: open asks grouped by reply state + unfinished jobs, each with its
+ * next command. With an id: routes to `figs show <id>` (the magnifier).
  */
 async function inboxCmd() {
   requireFigs()
-  const config = readJson(join(repoDir, "config.json"), {})
-  const data = await fetchInbox()
-  const items = data.asks ?? []
-  const askId = positional()
+  if (positional()) return showCmd() // `figs inbox <id>` → show
 
-  if (hasFlag("--json") && !askId) {
-    console.log(JSON.stringify(data, null, 2))
-    return
-  }
+  // Down-sync first (unless --no-sync): a stale inbox that says "nothing needs
+  // you" is the worst failure mode, so we touch the network here — softly.
+  const sync = hasFlag("--no-sync") ? { ran: false, reason: "skipped" } : await syncMessages()
 
-  if (askId) {
-    const a = items.find((x) => x.id === askId)
-    if (!a) {
-      die(
-        `ask "${askId}" isn't in your inbox (open asks + unacknowledged rejections only — closed history lives in the app)`,
-      )
-    }
-    console.log(`figs: ${a.title}`)
-    console.log(`      ${a.type} · ${a.status}${a.to ? ` · for the ${a.to}` : ""} · raised ${agoStr(a.ts)}`)
-    if (a.found) console.log(`\n  What it found:\n      ${a.found}`)
-    if (a.need) console.log(`\n  What it needs:\n      ${a.need}`)
-    if (a.options?.length) {
-      console.log(`\n  Options (answers cite these verbatim):`)
-      for (const o of a.options) console.log(`      · ${o}`)
-    }
-    if (a.details?.length) {
-      console.log(`\n  Details:`)
-      for (const d of a.details) console.log(`      ${d.l}: ${d.v}`)
-    }
-    if (a.events.length) {
-      console.log(`\n  THE THREAD (your humans' words, verbatim):`)
-      for (const e of a.events) console.log(`    · ${eventLine(e)}`)
-    } else {
-      console.log(`\n  No answer yet.`)
-    }
-    if (a.refs?.length) {
-      console.log(`\n  Attached artifacts (restoring to .figs/artifacts/):`)
-      await fetchRefs(config, a.refs)
-    }
-    console.log(`\n  → next: ${nextMove(a)}`)
-    return
+  const asks = foldById(readJsonl("asks.jsonl"))
+  const messages = readJsonl("messages.jsonl")
+  const jobs = foldById(readJsonl("runs.jsonl")).filter((r) => r.state === "in-flight")
+  const open = asks
+    .filter((a) => (a.status ?? "open") === "open")
+    .map((a) => ({ a, replies: repliesFor(messages, a.id) }))
+  const answered = open.filter(
+    ({ replies }) => replies.length && replies[replies.length - 1].verdict !== "changes-requested",
+  )
+  const changes = open.filter(
+    ({ replies }) => replies.length && replies[replies.length - 1].verdict === "changes-requested",
+  )
+  const quiet = open.filter(({ replies }) => !replies.length)
+
+  // Orphan replies: a synced message whose ask isn't in this copy's journal
+  // (a fresh clone). Surface it — never silently drop a human's reply.
+  const localAskIds = new Set(asks.map((a) => a.id))
+  const orphanAskIds = [...new Set(messages.map((m) => m.ask).filter((id) => id && !localAskIds.has(id)))]
+
+  // Warnings the agent can act on without scraping stderr.
+  const warnings = []
+  if (sync.ran && sync.truncated) {
+    warnings.push("sync incomplete — the server returned a partial set; some replies may be missing")
+  } else if (!sync.ran && sync.reason !== "local" && sync.reason !== "skipped") {
+    warnings.push(`showing local state — couldn't sync (${sync.reason})`)
   }
 
-  if (data.truncated) {
-    console.warn(`figs: ! showing the first ${items.length} — more exist (close some asks)`)
+  if (hasFlag("--json")) {
+    return printJson(
+      {
+        asks: open.map(({ a, replies }) => ({
+          id: a.id, type: a.type, title: a.title, status: a.status ?? "open", replies,
+        })),
+        jobs,
+        orphanAsks: orphanAskIds,
+        sync,
+      },
+      { warnings },
+    )
   }
-  const jobs = data.jobs ?? []
-  if (items.length === 0 && jobs.length === 0) {
+
+  for (const w of warnings) console.warn(`figs: ! ${w}`)
+
+  if (open.length === 0 && jobs.length === 0 && orphanAskIds.length === 0) {
     console.log("figs: ✓ inbox empty — no open asks, no unfinished jobs, nothing needs you")
     return
   }
-  const rejected = items.filter((a) => a.status === "rejected")
-  const answered = items.filter((a) => a.status === "open" && a.events.length > 0)
-  const quiet = items.filter((a) => a.status === "open" && a.events.length === 0)
   console.log(
-    `figs: inbox — ${answered.length} answered · ${rejected.length} rejected to acknowledge · ${quiet.length} waiting on your human` +
+    `figs: inbox — ${answered.length} answered · ${changes.length} need revision · ${quiet.length} waiting on your human` +
       (jobs.length ? ` · ${jobs.length} job${jobs.length === 1 ? "" : "s"} in flight` : ""),
   )
-  const printItem = (a) => {
-    const last = a.events[a.events.length - 1]
-    console.log(`\n  ${a.id} · ${a.type} — ${a.title}`)
-    if (last) console.log(`    ${eventLine(last)}`)
-    console.log(`    → ${nextMove(a)}${a.events.length > 1 ? `   (full thread: figs inbox ${a.id})` : ""}`)
+  const printItem = ({ a, replies }) => {
+    console.log(`\n  ${a.id} · ${a.type ?? "?"} — ${a.title ?? ""}`)
+    if (replies.length) console.log(`    ${messageLine(replies[replies.length - 1])}`)
+    console.log(`    → ${nextMove(a, replies)}${replies.length > 1 ? `   (full thread: figs show ${a.id})` : ""}`)
   }
-  for (const a of [...rejected, ...answered]) printItem(a)
+  for (const item of [...answered, ...changes]) printItem(item)
   if (quiet.length) {
-    console.log(`\n  Waiting on your human (nothing for you to do):`)
-    for (const a of quiet) console.log(`    · ${a.id} · ${a.type} — ${a.title} (raised ${agoStr(a.ts)})`)
+    console.log(`\n  Waiting on your human — relay these in chat, then \`figs answer\` their reply:`)
+    for (const { a } of quiet) console.log(`    · ${a.id} · ${a.type ?? "?"} — ${a.title ?? ""} (raised ${a.ts ? agoStr(a.ts) : "—"})`)
   }
   if (jobs.length) {
     console.log(`\n  Unfinished jobs — in flight (your past self's work; finish or settle):`)
     for (const j of jobs) {
+      console.log(`    · ${j.id}${j.result ? ` — ${j.result}` : ""} (last update ${agoStr(j.ts)})`)
+      console.log(`      → continue it (\`figs checkpoint --id ${j.id}\` as you go); \`figs report --id ${j.id}\` settles it`)
+    }
+  }
+  if (orphanAskIds.length) {
+    console.log(`\n  Replies on asks not in this copy's journal (raised elsewhere — full context in the app):`)
+    for (const id of orphanAskIds) console.log(`    · ${id}  → figs show ${id}`)
+  }
+}
+
+/**
+ * `figs show <id>` — the magnifier, pure local. Auto-detects an ask or a job
+ * and prints the folded record + its thread/trail + attachment names. No
+ * network: an attachment not on disk is noted (view it in the app), never
+ * downloaded — local is the source of truth.
+ */
+function showCmd() {
+  requireFigs()
+  const id = positional()
+  if (!id) die("show needs an id: figs show <ask-id|job-id>")
+  const asks = foldById(readJsonl("asks.jsonl"))
+  const runs = foldById(readJsonl("runs.jsonl"))
+  const messages = readJsonl("messages.jsonl")
+  const ask = asks.find((a) => a.id === id)
+  const replies = repliesFor(messages, id)
+
+  if (ask || replies.length) {
+    if (hasFlag("--json")) return printJson({ ask: ask ?? null, replies })
+    if (ask) {
+      console.log(`figs: ${ask.title ?? id}`)
       console.log(
-        `    · ${j.id}${j.result ? ` — ${j.result}` : ""} (last update ${agoStr(j.updatedAt ?? j.ts)})`,
+        `      ${ask.type ?? "?"} · ${ask.status ?? "open"}${ask.to ? ` · for the ${ask.to}` : ""}${ask.ts ? ` · raised ${agoStr(ask.ts)}` : ""}`,
       )
+      if (ask.found) console.log(`\n  What it found:\n      ${ask.found}`)
+      if (ask.need) console.log(`\n  What it needs:\n      ${ask.need}`)
+      if (ask.options?.length) {
+        console.log(`\n  Options (a reply cites one verbatim):`)
+        for (const o of ask.options) console.log(`      · ${o}`)
+      }
+      if (ask.details?.length) {
+        console.log(`\n  Details:`)
+        for (const d of ask.details) console.log(`      ${d.l}: ${d.v}`)
+      }
+      // Union across all of the ask's raw lines (raise/revise/close) — folding
+      // would drop an intermediate; attachments belong to their moment.
+      showAttachmentNames(
+        readJsonl("asks.jsonl").filter((a) => a.id === id).flatMap(attachmentsOf),
+      )
+    } else {
+      console.log(`figs: ask ${id} — not in this copy's journal (full context in the app); showing the replies that are here`)
+    }
+    if (replies.length) {
+      console.log(`\n  THE THREAD (your humans' words, verbatim):`)
+      for (const m of replies) console.log(`    · ${messageLine(m)}`)
+    } else {
+      console.log(`\n  No reply yet.`)
+    }
+    console.log(`\n  → next: ${nextMove(ask ?? { id }, replies)}`)
+    return
+  }
+
+  const run = runs.find((r) => r.id === id)
+  if (run) {
+    const trail = readJsonl("runs.jsonl").filter((r) => r.id === id)
+    if (hasFlag("--json")) return printJson({ run, trail })
+    console.log(`figs: job ${id}${run.unit ? ` · ${run.unit}` : ""}${run.period ? ` · ${run.period}` : ""}`)
+    console.log(`      ${run.state ?? "settled"}${run.status ? ` · ${run.status}` : ""} — ${run.result ?? ""}`)
+    console.log(`\n  Trail (each checkpoint/report at the moment it happened):`)
+    for (const l of trail) {
+      const atts = attachmentsOf(l)
       console.log(
-        `      → continue it (\`figs checkpoint --id ${j.id}\` as you go); \`figs report --id ${j.id}\` settles it`,
+        `    · ${l.ts ? agoStr(l.ts) : "—"} [${l.state ?? "settled"}] ${l.result ?? ""}${atts.length ? `  · ${atts.join(", ")}` : ""}`,
       )
     }
+    showAttachmentNames(trail.flatMap(attachmentsOf))
+    return
+  }
+
+  die(`"${id}" isn't a run or an ask in this journal — \`figs inbox\` lists what's here`)
+}
+
+/** Print attachment names (deduped), noting any not present on this machine. */
+function showAttachmentNames(names) {
+  const unique = [...new Set(names)]
+  if (!unique.length) return
+  console.log(`\n  Attachments:`)
+  for (const name of unique) {
+    const here = existsSync(join(repoDir, "artifacts", name))
+    console.log(`      · ${name}${here ? "" : "  (not in this copy — view it in the app)"}`)
   }
 }
 
-// ---------- the resolution fold (`resolve` — the one closing verb) ----------
+// ---------- figs answer — record the human's reply (you run it, not them) ----
 /**
- * Build the closing fold line. Best-effort, the verified path: fetches this
- * agent's inbox and, when the ask has human events, cites the one acted on —
- * `via: "figs"` + `resolution.answer: <event-id>` (+ `by` from the event) —
- * attribution by mechanism, not testimony. An ask found on the server but
- * missing locally is appended first (its own bytes coming home), so the fold
- * lands on a complete record. Offline or any failure → today's self-reported
- * `via: "human"` path, unchanged.
+ * `figs answer <ask-id>` transcribes a human's out-of-band reply into
+ * `messages.jsonl`. It's a plain writing verb (append + auto-push). `--by` names
+ * the HUMAN; the CLI stamps id/ts/source — the agent never authors plumbing.
  */
-async function buildResolution(askId, { chosen, by, note, withdrawn, rejected }) {
-  if (withdrawn && rejected) {
-    die("--withdrawn and --rejected are different closes: withdrawn = YOU retracted the ask; rejected = a HUMAN declined it. Pick the one that's true.")
-  }
-  if ((withdrawn || rejected) && chosen) {
-    die(`--chosen marks the need as met — it can't combine with ${withdrawn ? "--withdrawn" : "--rejected"} (use --note for the account)`)
+async function answerCmd() {
+  requireFigs()
+  const askId = positional()
+  if (!askId) {
+    die("answer needs the ask id: figs answer <ask-id> --by '<who>' (--chosen … | --text … | --approve|--request-changes|--reject)")
+  }
+  if (!askExistsLocally(askId)) {
+    die(`ask "${askId}" isn't in this journal — \`figs inbox\` shows your open asks. You record a human's reply to an ask YOU raised; you don't answer one that doesn't exist here.`)
+  }
+  const by = flag("--by")
+  if (!by) die("answer needs --by '<who said it>' — the human's name, not yours (you're transcribing their words)")
+
+  const verdicts = [
+    ["--approve", "approved"],
+    ["--request-changes", "changes-requested"],
+    ["--reject", "rejected"],
+  ].filter(([f]) => hasFlag(f))
+  if (verdicts.length > 1) die("pick one verdict: --approve | --request-changes | --reject")
+
+  const chosen = flag("--chosen")
+  const text = flag("--text")
+  const msg = {
+    id: genId("msg"),
+    kind: verdicts.length ? "verdict" : "answer",
+    ask: askId,
+    by,
+    ts: nowIso(),
+    source: "chat", // transcribed here; app-minted replies arrive via inbox sync
+  }
+  if (verdicts.length) msg.verdict = verdicts[0][1]
+  if (chosen) msg.chosen = chosen
+  if (text) msg.text = text
+  if (msg.kind === "answer" && !chosen && !text) {
+    die("answer needs --chosen '<option verbatim>' or --text '<what they said>' (or a verdict flag for a sign-off)")
+  }
+
+  // --chosen must quote one of the ask's options verbatim (when the ask is local).
+  if (chosen) {
+    const ask = foldById(readJsonl("asks.jsonl")).find((a) => a.id === askId)
+    const options = ask?.options ?? []
+    if (options.length && !options.includes(chosen)) {
+      const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "")
+      const near = options.find((o) => norm(o) === norm(chosen))
+      if (near) die(`--chosen must quote the option verbatim — did you mean "${near}"?`)
+      die(
+        `--chosen "${chosen}" doesn't match any of the ask's options:\n` +
+          options.map((o) => `    · ${o}`).join("\n") +
+          "\n  (quote one verbatim, or use --text for a free-text reply)",
+      )
+    }
   }
-  const warnings = []
-  let ask = foldById(readJsonl("asks.jsonl")).find((a) => a.id === askId)
-
-  // The verified path (soft — never blocks a close).
-  let serverAsk = null
-  if (getToken()) {
-    const inbox = await fetchInbox({ soft: true })
-    serverAsk = inbox?.asks?.find((a) => a.id === askId) ?? null
-  }
-  if (!ask && serverAsk) {
-    // Its own bytes coming home: append the record so the fold has something
-    // local to land on (the cross-machine close, solved inside the verb).
-    const record = { ...serverAsk }
-    delete record.events
-    delete record.updatedAt
-    if (record.resolution == null) delete record.resolution
-    appendJsonl("asks.jsonl", record)
-    warnings.push(`fetched "${askId}" from Figs (raised elsewhere) — recorded locally before closing`)
-    ask = record
-  } else if (!ask) {
-    warnings.push(
-      `ask "${askId}" isn't in the local asks.jsonl (raised on another machine, or pruned) — recording the close anyway; the server folds it onto the full record`,
+
+  // Double-transcription guard: a reply made in the app syncs down on its own,
+  // so re-typing it here would mint a duplicate (a weaker-grade copy).
+  const priorSame = readJsonl("messages.jsonl").some(
+    (m) =>
+      m.ask === askId &&
+      ((chosen && m.chosen === chosen) ||
+        (text && m.text === text) ||
+        (msg.verdict && m.verdict === msg.verdict)),
+  )
+  if (priorSame) {
+    console.warn(
+      "figs: ! a reply on this ask already carries that — replies made in the app sync down automatically; `figs answer` is only for replies that exist nowhere but your chat",
     )
   }
 
-  const options = ask?.options ?? serverAsk?.options ?? []
-  if (chosen && options.length && !options.includes(chosen)) {
-    const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, "")
-    const near = options.find((o) => norm(o) === norm(chosen))
-    if (near) die(`--chosen must quote the option verbatim — did you mean "${near}"?`)
-    die(
-      `--chosen "${chosen}" doesn't match any of the ask's options:\n` +
-        options.map((o) => `    · ${o}`).join("\n") +
-        "\n  (quote one verbatim, or use --note for a free-text account)",
-    )
+  warnEatenDollar(msg.chosen, msg.text)
+  const issues = validateMessage(msg)
+  if (issues.length) die(`not written:\n  ${issues.join("\n  ")}`)
+  appendJsonl("messages.jsonl", msg)
+  console.log(`figs: ✓ reply recorded — ${JSON.stringify(msg)}`)
+  console.log(
+    `figs:   transcribed ${by}'s reply. Act on it, then \`figs close ${askId}\` (it cites this) — real work first → report it, then \`figs close ${askId} --run <job>\`.`,
+  )
+  await autoPush()
+}
+
+// ---------- figs close — the one closing verb (derives from the reply) -------
+/** The old resolve surface → teaching errors (the migration path). A function,
+ *  not a top-level const: the CLI dispatches during module eval, so a const
+ *  declared after the dispatch block would still be in its TDZ when called. */
+function closeCutFlags() {
+  return {
+    "--chosen":
+      "replies are recorded with `figs answer <id> --chosen '…' --by '<who>'`; close only ends the ask (it cites the reply on file automatically)",
+    "--by":
+      "the answerer is named on the reply: `figs answer <id> … --by '<who>'`; close cites it automatically",
+    "--answer-id":
+      "close auto-cites the NEWEST reply on file — you don't name it",
+    "--rejected":
+      "record the human's reject as a verdict first: `figs answer <id> --reject --by '<who>'`, then `figs close <id>` derives 'rejected' from it",
   }
+}
+/** The teaching menu when an ask has no reply on file yet. */
+function closeMenu(askId) {
+  return (
+    `no reply on file for "${askId}" — close needs to know what happened:\n` +
+    `    · answered in chat?   → record it first: figs answer ${askId} --by '<who>' (--chosen … | --text …)\n` +
+    `    · YOU retracted it?   → figs close ${askId} --withdrawn\n` +
+    `    · cleared on its own? → figs close ${askId} --note '<what happened>'  (recorded via: self)`
+  )
+}
+async function closeCmd() {
+  requireFigs()
+  const askId = positional()
+  if (!askId) die("close needs the ask id: figs close <ask-id> [--note …] [--run …] [--withdrawn]")
+  // The old resolve surface → teaching errors (the migration path).
+  for (const [f, help] of Object.entries(closeCutFlags())) {
+    if (hasFlag(f) || flag(f) !== undefined) die(`\`${f}\` is gone — ${help}`)
+  }
+  if (!askExistsLocally(askId)) {
+    die(`ask "${askId}" isn't in this journal — \`figs inbox\` shows your open asks`)
+  }
+  const withdrawn = hasFlag("--withdrawn")
+  const note = flag("--note")
+  const runRef = flag("--run")
+  warnUnknownRun(runRef)
+  const attached = attachFiles(flagAll("--attach")) // proof of what was done
+
+  // The newest reply for this ask drives the close (messages accumulate; sort by ts).
+  const replies = readJsonl("messages.jsonl")
+    .filter((m) => m.ask === askId)
+    .sort((a, b) => new Date(a.ts) - new Date(b.ts))
+  const newest = replies[replies.length - 1]
 
   const resolution = {}
-  if (chosen) resolution.chosen = chosen
-  if (by) resolution.by = by
-  if (note) resolution.note = note
-  // `via` says where the unblock came from; out-of-band human answers are
-  // "human". A rejection is inherently a human's call; otherwise set it only
-  // when there's evidence of one (a chosen/by), never on withdrawn (nobody
-  // acted — that's the point).
-  if (rejected || (!withdrawn && (chosen || by))) resolution.via = "human"
-
-  // Cite the event acted on, when one exists: prefer the latest answer whose
-  // chosen matches, else the latest event (e.g. the approval, the rejection).
-  const events = serverAsk?.events ?? []
-  if (!withdrawn && events.length) {
-    // Any human event can carry the chosen path — an answer, or a qualified
-    // verdict (verdict + chosen together). Match on the text, not the kind.
-    const match = chosen ? [...events].reverse().find((e) => e.chosen === chosen) : null
-    const cited = match ?? events[events.length - 1]
+  let status
+  if (withdrawn) {
+    status = "withdrawn" // the agent's own act — no reply needed, nobody acted
+  } else if (!newest) {
+    if (!note) die(closeMenu(askId))
+    status = "resolved" // cleared on its own — self-reported
+    resolution.via = "self"
+  } else if (newest.kind === "verdict" && newest.verdict === "changes-requested") {
+    die(
+      `changes were requested on "${askId}" — revise and re-raise on the same id (\`figs ask sign-off --id ${askId} …\`); this isn't a close`,
+    )
+  } else {
+    // an answer, an approval, or a rejection — all derive a close, citing it
+    status = newest.verdict === "rejected" ? "rejected" : "resolved"
     resolution.via = "figs"
-    resolution.answer = cited.id
-    if (!by && cited.byName) resolution.by = cited.byName
+    resolution.answer = newest.id
+    if (newest.by) resolution.by = newest.by
+    if (newest.chosen) resolution.chosen = newest.chosen
   }
-
-  // The close's own clock — machine-stamped, never typed (same posture as the
-  // record `ts`). It lives INSIDE resolution so the fold can't collide with
-  // the record's raise `ts` (folds are field-level merges); the reader stamps
-  // its own receipt (`closedAt`) at ingest — two clocks, claim vs receipt.
+  if (note) resolution.note = note
+  if (runRef) resolution.run = runRef
+  // Machine-stamped, inside resolution so the fold can't collide with the raise ts.
   resolution.ts = nowIso()
 
   warnEatenDollar(resolution.chosen, resolution.note)
-  const line = {
-    id: askId,
-    status: withdrawn ? "withdrawn" : rejected ? "rejected" : "resolved",
-    resolution,
-  }
-  return { line, warnings }
+  const line = { id: askId, status, resolution }
+  if (attached.length) line.attachments = attached // pinned to the close moment
+  appendJsonl("asks.jsonl", line)
+  const cite =
+    resolution.answer && newest
+      ? ` — ${status === "rejected" ? "acknowledging" : "acting on"} ${newest.by ?? "the"} reply${newest.chosen ? ` '${newest.chosen}'` : ""}`
+      : ""
+  console.log(`figs: ✓ ask ${askId} ${status}${cite}`)
+  await autoPush()
 }
 
-/** The verbs' shared final step — same transport as `figs push`. */
+/**
+ * The verbs' shared final step. The write already succeeded locally before this
+ * runs, so the record is safe no matter what happens here — that's why every
+ * not-published outcome is exit 2 (retry `figs push`), never exit 1.
+ *
+ *  - local mode (not linked)  → don't attempt; calm note; exit 0.
+ *  - --no-push                → deliberately deferred; exit 0.
+ *  - linked, no token         → exit 2 + the canonical line.
+ *  - linked, push fails       → exit 2 + the canonical line.
+ *  - linked, push ok          → exit 0.
+ */
 async function autoPush() {
   if (hasFlag("--no-push")) {
     console.log("figs:   saved locally (--no-push) — `figs push` publishes it")
     return
   }
-  if (!(await doPush())) {
-    console.warn("figs: ! saved locally — the push failed (see above); fix and run `figs push`")
-    process.exitCode = 1
+  if (!isLinked()) {
+    console.log("figs:   local mode — `figs link` to publish")
+    return
+  }
+  if (!getToken()) {
+    console.warn("figs: ! not logged in — `figs login`, then `figs push`")
+    console.warn(`figs: ! ${RECORDED_LOCALLY}`)
+    process.exitCode = 2
+    return
+  }
+  if (!(await doPush()).ok) {
+    console.warn(`figs: ! ${RECORDED_LOCALLY}`)
+    process.exitCode = 2
   }
 }
 
@@ -1381,7 +1796,11 @@ async function reportCmd() {
   }
   // state is verb-stamped, never typed: report settles the job (checkpoint
   // marks it in-flight). The settling fold overrides any earlier checkpoint.
-  const run = { id: flag("--id") || genId("r"), ts: nowIso(), result, state: "settled" }
+  const idGiven = flag("--id")
+  const id = idGiven || genId("r")
+  // Before the append, so "new" means new-to-this-outbox (the typo catch).
+  const isNew = !foldById(readJsonl("runs.jsonl")).some((r) => r.id === id)
+  const run = { id, ts: nowIso(), result, state: "settled" }
   const unit = flag("--unit")
   if (unit) run.unit = unit
   const period = flag("--period")
@@ -1391,13 +1810,16 @@ async function reportCmd() {
   const trigger = flag("--trigger")
   if (trigger) run.session = { trigger }
   const attached = attachFiles(flagAll("--attach"))
-  if (attached.length === 1) run.artifact = attached[0]
-  else if (attached.length > 1) run.artifacts = attached
+  if (attached.length) run.attachments = attached
   warnEatenDollar(run.result)
+  warnUnknownUnit(unit)
   const issues = validateRun(run)
   if (issues.length) die(`not written:\n  ${issues.join("\n  ")}`)
   appendJsonl("runs.jsonl", run)
   console.log(`figs: ✓ run recorded — ${JSON.stringify(run)}`)
+  // Announce new-vs-fold only for an explicit --id — that's where a typo means
+  // "I meant to continue a job but opened a sibling" (auto-ids are always new).
+  if (idGiven) announceFold("job", id, isNew, " (settled)")
   // Teaching, never a gate: a settled job with open asks citing it is the
   // normal tail-of-job pattern (the ask owns the waiting) — but if the job's
   // OUTCOME depends on an answer, in-flight is the honest state. Local fold
@@ -1445,25 +1867,37 @@ async function checkpointCmd() {
   const trigger = flag("--trigger")
   if (trigger) run.session = { trigger }
   const attached = attachFiles(flagAll("--attach"))
-  if (attached.length === 1) run.artifact = attached[0]
-  else if (attached.length > 1) run.artifacts = attached
+  if (attached.length) run.attachments = attached
   warnEatenDollar(run.result)
+  warnUnknownUnit(unit)
   const issues = validateRun(run)
   if (issues.length) die(`not written:\n  ${issues.join("\n  ")}`)
+  // A new sitting on a SETTLED id is a legitimate reopen (the warn→ok story),
+  // but usually means "I should have used a new id" — nudge without blocking.
+  const settledBefore = foldById(readJsonl("runs.jsonl")).some(
+    (r) => r.id === id && r.state === "settled",
+  )
   appendJsonl("runs.jsonl", run)
   console.log(`figs: ✓ checkpoint recorded — ${JSON.stringify(run)}`)
   if (isNew) {
     console.log(
       `figs:   new job opened: ${id} (in flight) — checkpoint as you go; \`figs report --id ${id}\` settles it`,
     )
+  } else if (settledBefore) {
+    console.warn(
+      `figs: ! reopening a settled job (${id}) — continue only if it's truly the same job; new work wants a new id`,
+    )
+  } else {
+    console.log(`figs:   folded onto existing job ${id} (in flight)`)
   }
   await autoPush()
-  // A checkpoint exists to survive a crash — local-only protects nothing.
-  // autoPush already said "saved locally"; for THIS verb that reads like
-  // success, so say what it actually means.
-  if (process.exitCode === 1) {
+  // A checkpoint exists to survive a crash — but only when this repo intends to
+  // publish (linked). In local mode the file IS the protection, so the calm
+  // "local mode" line autoPush printed is the whole truth. When linked, a failed
+  // push (exit 2) means the crash-stub never reached the server — say so loudly.
+  if (process.exitCode === 2) {
     console.warn(
-      `figs: ! this checkpoint is NOT protecting the job yet — nothing reached the server. Run \`figs push\` before continuing the work.`,
+      `figs: ! this checkpoint is NOT protecting the job remotely yet — nothing reached the server. Run \`figs push\` before continuing the work.`,
     )
   }
 }
@@ -1528,11 +1962,17 @@ async function askCmd() {
     die('--run takes the explicit run id (no "last" — another session may have reported since); `figs report` prints the id of what it wrote')
   }
   if (runRef) ask.run = runRef
+  warnUnknownRun(runRef)
+  warnUnknownUnit(ask.unit)
   const attached = attachFiles(flagAll("--attach"))
-  if (attached.length) {
-    ask.refs = [...(base.refs ?? []), ...attached.map((n) => ({ label: n, artifact: n }))]
-  }
-  if (ask.type === "sign-off" && !ask.refs?.length) {
+  // Unified attachments[] (bare file names). Accept attachments[] from --stdin,
+  // and normalize a legacy refs[] into it (the filename is the label now).
+  const baseAtts = Array.isArray(base.attachments)
+    ? base.attachments
+    : (base.refs ?? []).map((r) => r?.artifact).filter(Boolean)
+  delete ask.refs
+  if (attached.length || baseAtts.length) ask.attachments = [...baseAtts, ...attached]
+  if (ask.type === "sign-off" && !ask.attachments?.length) {
     console.warn(
       "figs: ! tip: a sign-off reviews best with attachments — the exact content to approve, plus a brief (what to do once approved + what it requires). Add --attach <file>",
     )
@@ -1552,42 +1992,37 @@ async function askCmd() {
   )
   const issues = validateAsk(ask)
   if (issues.length) die(`not written:\n  ${issues.join("\n  ")}`)
+  const askIdGiven = flag("--id") ?? base.id
+  const askIsNew = !foldById(readJsonl("asks.jsonl")).some((a) => a.id === ask.id)
   appendJsonl("asks.jsonl", ask)
   console.log(`figs: ✓ ask raised — ${JSON.stringify(ask)}`)
+  // Announce new-vs-fold for an explicit id — re-raising the same id (a revision)
+  // folds; a typo'd id silently opens a sibling ask. Catch it.
+  if (askIdGiven) announceFold("ask", ask.id, askIsNew)
   if (!ask.to) {
     console.log("figs:   tip: address asks with --to manager|builder so they route to the right person")
   }
   await autoPush()
+  // Local: the agent must put the ask in front of the human — nothing else
+  // surfaces it. When linked, the app surfaces it too.
   console.log(
-    "figs:   your human answers in the app — start your next session with `figs inbox` to read it",
+    isLinked()
+      ? "figs:   show this ask to your human (it's also in the app); record their reply with `figs answer`, read it back with `figs inbox`"
+      : "figs:   show this ask to your human in chat now — nothing else surfaces it. Record their reply with `figs answer`.",
   )
 }
 
-async function resolveCmd() {
-  requireFigs()
-  const askId = positional()
-  if (!askId) die("resolve needs the ask id: figs resolve <ask-id> [--chosen …] [--withdrawn]")
-  const { line, warnings } = await buildResolution(askId, {
-    chosen: flag("--chosen"),
-    by: flag("--by"),
-    note: flag("--note"),
-    withdrawn: hasFlag("--withdrawn"),
-    rejected: hasFlag("--rejected"),
-  })
-  for (const w of warnings) console.warn(`figs: ! ${w}`)
-  appendJsonl("asks.jsonl", line)
-  console.log(`figs: ✓ ask ${askId} ${line.status} — ${JSON.stringify(line)}`)
-  await autoPush()
-}
-
-/** Validate the local .figs/ payload against the spec — no write, no push. */
+/**
+ * `figs doctor` — the spec's conformance validator. Local validation is
+ * normative and **runs account-free**: a fresh, no-token, offline repo gets a
+ * full pass and exit 0. Server validation (when linked + logged in) is an
+ * additive second opinion, never the gate.
+ */
 async function doctor() {
   // Local checks first (no token/network needed) — fail fast and offline.
-  if (!existsSync(repoDir)) die("no .figs/ here — run `figs init` first")
+  if (!existsSync(repoDir)) die(noFigsHint())
   const config = readJson(join(repoDir, "config.json"), {})
-  if (!config.workspaceId || !config.agentId) {
-    die("config missing workspaceId/agentId — run `figs init`")
-  }
+  if (!config.agentId) die("config missing agentId — run `figs init`")
   const agentJson = readJson(join(repoDir, "agent.json"), null)
   if (!agentJson) die("missing .figs/agent.json — author it first (see .figs/GUIDE.md)")
 
@@ -1596,9 +2031,13 @@ async function doctor() {
   // are>" to the org chart. This is the "not ready to push" signal.
   const placeholders = findPlaceholders(agentJson)
   if (placeholders.length) {
-    console.log("figs: ✗ .figs/agent.json still has template placeholders — fill these in before pushing:")
-    for (const p of placeholders) console.log(`  ${p.path}: ${p.value}`)
-    console.log("  (replace the <…> values by reading your own repo, then re-run `figs doctor`)")
+    if (JSON_OUT) {
+      printJson({ valid: false, placeholders }, { ok: false })
+    } else {
+      console.log("figs: ✗ .figs/agent.json still has template placeholders — fill these in before pushing:")
+      for (const p of placeholders) console.log(`  ${p.path}: ${p.value}`)
+      console.log("  (replace the <…> values by reading your own repo, then re-run `figs doctor`)")
+    }
     process.exit(1)
   }
 
@@ -1607,26 +2046,41 @@ async function doctor() {
   const localIssues = validateOutbox(
     foldById(readJsonl("runs.jsonl")),
     foldById(readJsonl("asks.jsonl")),
+    readJsonl("messages.jsonl"),
   )
   if (localIssues.length) {
-    console.log("figs: ✗ local validation issues:")
-    for (const i of localIssues) console.log(`  ${i}`)
+    if (JSON_OUT) {
+      printJson({ valid: false, scope: "local", issues: localIssues }, { ok: false })
+    } else {
+      console.log("figs: ✗ local validation issues:")
+      for (const i of localIssues) console.log(`  ${i}`)
+    }
     process.exit(1)
   }
 
-  if (!getToken()) die("not logged in — run `figs login`")
+  // Local conformance passed. Server validation is the additive layer — it
+  // needs both a destination (linked) and a token; without either, we're done,
+  // and that is a full, legitimate pass (the spec's conformance is local).
+  if (!config.workspaceId || !getToken()) {
+    const why = !config.workspaceId ? "not linked" : "not logged in"
+    if (JSON_OUT) return printJson({ valid: true, scope: "local", serverValidation: "skipped", reason: why })
+    console.log(`figs: ✓ .figs/ passes local conformance — server validation skipped (${why})`)
+    return
+  }
   const r = await api("POST", "/api/validate", {
     workspaceId: config.workspaceId,
     agent: { ...agentJson, id: config.agentId },
     runs: foldById(readJsonl("runs.jsonl")),
     asks: foldById(readJsonl("asks.jsonl")),
+    messages: readJsonl("messages.jsonl"),
   })
   if (r.ok) {
+    if (JSON_OUT) return printJson({ valid: true, scope: "server" })
     console.log("figs: ✓ .figs/ is valid — ready to push")
     return
   }
   if (JSON_OUT) {
-    console.log(JSON.stringify(r.issues, null, 2))
+    printJson({ valid: false, scope: "server", issues: r.issues }, { ok: false })
   } else {
     console.log("figs: ✗ validation issues:")
     for (const i of r.issues) {
@@ -1640,9 +2094,14 @@ async function doctor() {
   process.exit(1)
 }
 
-/** `figs push` — the bare transport; exits non-zero on any failure. */
+/**
+ * `figs push` — the bare transport. Exit 1 on a **structural** failure (fix
+ * something: not linked, no agent.json, bad data), exit 2 on a **transient** one
+ * (network/server — the records are safe; retry later).
+ */
 async function push() {
-  if (!(await doPush())) process.exit(1)
+  const r = await doPush()
+  if (!r.ok) process.exit(r.retryable ? 2 : 1)
 }
 
 /**
@@ -1651,29 +2110,31 @@ async function push() {
  * append (auto-push IS push — one transport, many entry points). Runs the same
  * local checks as `figs doctor` first, so a malformed hand-written line never
  * reaches the server as a confusing 4xx. Prints its own errors and returns
- * false on failure — callers decide whether that's fatal.
+ * `{ ok, retryable }` — callers map that to an exit code.
  */
 async function doPush() {
-  const fail = (msg) => {
+  const fail = (msg, retryable = false) => {
     console.error(`figs: ✗ push: ${msg}`)
-    return false
+    return { ok: false, retryable }
+  }
+  if (!existsSync(repoDir)) return fail(noFigsHint())
+  const config = readJson(join(repoDir, "config.json"), {})
+  if (!config.agentId) return fail("config missing agentId — run `figs init`")
+  if (!config.workspaceId) {
+    return fail("not linked — local records are safe; `figs link` to publish")
   }
   const token = getToken()
   if (!token) return fail("not logged in — run `figs login` (or set FIGS_TOKEN)")
   await checkVersion({ hardFail: true })
-  if (!existsSync(repoDir)) return fail("no .figs/ here — run `figs init` first")
-  const config = readJson(join(repoDir, "config.json"), {})
-  if (!config.workspaceId || !config.agentId) {
-    return fail("config missing workspaceId/agentId — run `figs init`")
-  }
-  const endpoint =
-    process.env.FIGS_ENDPOINT || config.endpoint || DEFAULT_ENDPOINT
 
+  const endpoint = process.env.FIGS_ENDPOINT || config.endpoint || DEFAULT_ENDPOINT
   const agentJson = readJson(join(repoDir, "agent.json"), null)
-  if (!agentJson) return fail("missing .figs/agent.json")
+  if (!agentJson) return fail("missing .figs/agent.json — author it, then `figs doctor`")
   const agent = { ...agentJson, id: config.agentId }
   const runs = foldById(readJsonl("runs.jsonl"))
   const asks = foldById(readJsonl("asks.jsonl"))
+  // Messages are immutable events — sent whole (no fold); the server dedupes by id.
+  const messages = readJsonl("messages.jsonl")
 
   // Local pre-flight — fail fast, offline, with teaching errors.
   const placeholders = findPlaceholders(agentJson)
@@ -1682,7 +2143,7 @@ async function doPush() {
       `agent.json still has template placeholders (${placeholders.map((p) => p.path).join(", ")}) — fill them in; \`figs doctor\` lists them`,
     )
   }
-  const issues = validateOutbox(runs, asks)
+  const issues = validateOutbox(runs, asks, messages)
   if (issues.length) return fail(`local validation failed:\n  ${issues.join("\n  ")}`)
 
   const base = endpoint.replace(/\/+$/, "")
@@ -1690,39 +2151,43 @@ async function doPush() {
   try {
     res = await fetchT(`${base}/api/ingest`, {
       method: "POST",
-      headers: { "content-type": "application/json", "x-figs-token": token },
-      body: JSON.stringify({ workspaceId: config.workspaceId, agent, runs, asks }),
+      headers: { "content-type": "application/json", ...authHeaders(token) },
+      body: JSON.stringify({ workspaceId: config.workspaceId, agent, runs, asks, messages }),
     })
   } catch (e) {
-    return fail(`cannot reach ${base} (${netReason(e)})`)
+    // Network/timeout — transient; the records are safe locally.
+    return fail(`cannot reach ${base} (${netReason(e)})`, true)
   }
   const text = await res.text()
-  if (!res.ok) return fail(`server rejected it (${res.status}): ${text}`)
+  // 4xx = the payload is wrong (re-pushing won't help) → structural; 5xx = transient.
+  if (!res.ok) return fail(`server rejected it (${res.status}): ${text}`, res.status >= 500)
   console.log(
-    `figs: ✓ pushed ${agent.name ?? agent.id} — ${runs.length} runs, ${asks.length} asks`,
+    `figs: ✓ pushed ${agent.name ?? agent.id} — ${runs.length} runs, ${asks.length} asks, ${messages.length} messages`,
   )
   // The wow-moment link — relay this to your human so they can see the agent.
   console.log(`       view at ${base}/w/${config.workspaceId}`)
 
-  return pushArtifacts(base, token, config, runs, asks)
+  // The spine landed; an artifact-stage failure is transient/oversize — retry.
+  return (await pushArtifacts(base, token, config))
+    ? { ok: true }
+    : { ok: false, retryable: true }
 }
 
 /**
- * Upload the files referenced by runs (run.artifact) and ask refs (refs[].artifact).
- * The spine ingest is JSON-only; artifacts go to a separate endpoint that stores
- * them content-addressed (an unchanged file is skipped server-side). Content is
- * sent base64-encoded so any type — html, markdown, text, json, images — survives.
- * A **server rejection** (auth/size/etc.) is fatal: it prints ✗ and exits non-zero
- * so the agent never believes a report published when it didn't (esp. the ~3 MB
- * cap → 413). A **missing local file** is only a warning — that's the agent
- * referencing an artifact it didn't actually produce, not a publish failure.
+ * Upload the files attached anywhere in the journal. Collected from the RAW
+ * lines (not the folded records) so a file attached at a checkpoint isn't lost
+ * when a later report folds over it — attachments belong to their moment. The
+ * spine ingest is JSON-only; files go to a separate content-addressed endpoint
+ * (an unchanged file is skipped server-side), base64-encoded so any type
+ * survives. A **server rejection** (auth/size) is fatal; a **missing local
+ * file** is only a warning (the agent referenced something it didn't produce).
  */
-async function pushArtifacts(base, token, config, runs, asks) {
-  const refNames = (asks ?? []).flatMap((a) =>
-    (a.refs ?? []).map((r) => r.artifact),
-  )
-  const runNames = runs.flatMap((r) => [r.artifact, ...(r.artifacts ?? [])])
-  const names = [...new Set([...runNames, ...refNames].filter(Boolean))]
+async function pushArtifacts(base, token, config) {
+  const names = [
+    ...new Set(
+      [...readJsonl("runs.jsonl"), ...readJsonl("asks.jsonl")].flatMap(attachmentsOf),
+    ),
+  ]
   if (names.length === 0) return true
 
   let uploaded = 0
@@ -1741,7 +2206,7 @@ async function pushArtifacts(base, token, config, runs, asks) {
     try {
       res = await fetchT(`${base}/api/artifacts/upload`, {
         method: "POST",
-        headers: { "content-type": "application/json", "x-figs-token": token },
+        headers: { "content-type": "application/json", ...authHeaders(token) },
         body: JSON.stringify({
           workspaceId: config.workspaceId,
           agentId: config.agentId,
@@ -1782,18 +2247,35 @@ async function pushArtifacts(base, token, config, runs, asks) {
 function readJsonl(name) {
   const p = join(repoDir, name)
   if (!existsSync(p)) return []
+  const lines = readFileSync(p, "utf8").split("\n")
+  // A process killed mid-append leaves a half-written FINAL line — the journal
+  // must survive the agent dying while writing it. Tolerate exactly one broken
+  // last (non-empty) line: warn + skip, keep the rest. A broken INTERIOR line is
+  // real corruption — die loudly. (`name` files are append-only, so only the
+  // tail can be torn.)
+  let lastNonEmpty = -1
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (lines[i].trim()) {
+      lastNonEmpty = i
+      break
+    }
+  }
   const out = []
-  readFileSync(p, "utf8")
-    .split("\n")
-    .forEach((line, i) => {
-      const s = line.trim()
-      if (!s) return
-      try {
-        out.push(JSON.parse(s))
-      } catch {
+  lines.forEach((line, i) => {
+    const s = line.trim()
+    if (!s) return
+    try {
+      out.push(JSON.parse(s))
+    } catch {
+      if (i === lastNonEmpty) {
+        console.warn(
+          `figs: ! last line of .figs/${name} is broken — likely a crash mid-write; skipped it (re-record that entry). The rest is intact.`,
+        )
+      } else {
         die(`malformed JSON in .figs/${name} line ${i + 1}: ${s.slice(0, 80)}`)
       }
-    })
+    }
+  })
   return out
 }