@figs-so/cli 0.1.1

package/GUIDE.template.md

@@ -0,0 +1,147 @@
+<!-- This file is emitted by `figs init`. Re-run `figs init` to refresh it. -->
+# Figs — how this `.figs/` folder works
+
+You are an AI employee. **Figs** is the window your manager uses to see what you're
+responsible for, what you've done, and what you need from them. You publish your state to it;
+it's a **read-only mirror** — it never reaches back into your repo.
+
+Schema details here mirror Figs' contract (the source of truth). After you edit anything, run
+**`figs doctor`** — it validates `.figs/` against the live contract and tells you what's wrong.
+
+## The model: `.figs/` is your `dist/`
+
+Everything you want visible goes in the `.figs/` folder, and `figs push` publishes it.
+*If it's in `.figs/`, it's shared; if not, it's private.* The sync is **one-way,
+append-mostly, and never deletes** on the server — the remote is the durable record, so a run
+your manager signed off on doesn't vanish because you cleaned up locally.
+
+```
+.figs/
+  config.json     # { endpoint, workspaceId, agentId }  — written by `figs init` (commit it)
+  agent.json      # who you are: your charter/spine      — you write this  (commit it)
+  runs.jsonl      # what you did, one line per run        — you append      (gitignored)
+  asks.jsonl      # what you need from a human            — you append      (gitignored)
+  artifacts/      # the reports you produced              — you copy in     (gitignored)
+  GUIDE.md        # this file
+```
+
+**Commit `config.json` + `agent.json`** (your identity + charter, non-secret). The activity
+files are a transient outbox — `figs init` gitignores them; the server aggregates them.
+
+## `agent.json` — your charter (the spine)
+
+Write this by reading **your own repo** — your `CLAUDE.md` / `MEMORY.md` already say who you
+are. Derive it, don't invent it, and keep it current as your role changes. **Do not put an
+`id` here** — your identity UUID lives in `config.json` and the CLI attaches it on push.
+
+| Field | Req | What it is |
+|---|---|---|
+| `name` | ✅ | Display name (e.g. "Reconciliation"). |
+| `type` | | `"agent"` (default) or `"human"`. |
+| `role` | | One-line title (bilingual is fine). |
+| `status` | | Free text — your current state (e.g. `"in_dev"`, `"healthy"`). |
+| `mandate` | | **Your 工作執掌** — one sentence: what you're accountable for. Shown loudest. |
+| `avatar` | | `{ "seed": "<string>" }` — seeds your avatar. |
+| `org` | | `{ "department": "...", "manager": "<member email>" }`. **`department` groups you in the org chart.** |
+| `runtime` | | e.g. `"Claude Code"`. |
+| `cadence` | | e.g. `"Monthly"`, `"Quarterly"`. |
+| `method` | | `string[]` — **how you work**, numbered steps. The "How it works" section. |
+| `properties` | | `[{ "k": "...", "v": "..." }]` — free-form facts shown on your card. |
+| `units` | | `[]` — the things you're responsible for (a customer, a job). Optional; omit if none. |
+
+**A `unit`:** `{ id, name, subtitle?, status?, period?, detail?, stats?: [{l,v}] }`. The `id`
+is how your runs link to it (a run's `unit` matches a unit `id`).
+
+```json
+{
+  "name": "Reconciliation",
+  "type": "agent",
+  "role": "對帳專員 · Reconciliation Officer",
+  "status": "in_dev",
+  "avatar": { "seed": "Reconciliation" },
+  "org": { "department": "Finance Ops · CSR", "manager": "you@company.com" },
+  "runtime": "Claude Code",
+  "cadence": "Monthly",
+  "mandate": "Reconciles open invoices every month — flags what doesn't match for review.",
+  "method": [
+    "Pull the WT-side open invoices and the customer-side statement for the month.",
+    "Match on PO / delivery-number keys within tolerance.",
+    "Classify every key — matched / needs-review / WT-only / cust-only — with a 'why'.",
+    "Surface discrepancies. Never write back to the source."
+  ],
+  "properties": [{ "k": "Department", "v": "Finance Ops · CSR" }],
+  "units": [
+    {
+      "id": "compal", "name": "Compal", "subtitle": "仁寶電腦",
+      "status": "88% matched · 31 keys flagged", "period": "2025-11",
+      "stats": [{ "l": "Matched", "v": "2,161 keys" }, { "l": "Needs review", "v": "31 keys" }]
+    }
+  ]
+}
+```
+
+## `runs.jsonl` — what you did (append one line per run)
+
+```json
+{ "id": "compal-2025-11", "ts": "2026-05-28T23:41:26Z", "unit": "compal", "period": "2025-11", "result": "88% matched · 31 keys flagged", "status": "ok", "artifact": "compal-2025-11.html" }
+```
+
+- `id` ✅ and `ts` ✅ (ISO-8601 with offset) are required. `status`: `ok | warn | fail` (default `ok`).
+- `unit` links to a unit `id`. `result` is the one-line outcome. `artifact` is a file in `artifacts/`.
+- **Idempotent by `id`** — re-pushing the same id updates that run, never duplicates. Use a stable id.
+
+## `asks.jsonl` — what you need from a human (append)
+
+Raise your hand when you're stuck. Assemble the full context so the human can act without
+re-gathering anything.
+
+```json
+{
+  "id": "quanta-bridge", "ts": "2026-05-28T21:05:00Z",
+  "type": "confirm-assumption", "status": "open", "unit": "quanta",
+  "title": "No bridge rule for prefixed invoice numbers",
+  "found": "~180 rows can't be matched safely; guessing risks false matches.",
+  "need": "Confirm the bridge rule for prefixed invoice numbers.",
+  "options": ["Strip the alpha prefix", "Use a mapping you provide", "Treat as out-of-scope"],
+  "details": [ { "l": "Amount at risk", "v": "$52.9M" } ],
+  "refs": [ { "label": "Quanta report", "artifact": "quanta-2025-11.html" } ]
+}
+```
+
+- Required: `id`, `type`, `title`. `type`: `blocked | needs-decision | confirm-assumption | sign-off`.
+- Optional context (each renders only if present): `found`, `need`, `options[]`, `details[]`, `refs[]`.
+- **You own the lifecycle.** Close an ask by appending `{ "id": "quanta-bridge", "status": "resolved" }`
+  on a later run. Folded by `id`. Strictly one-way — the human acts in their own workflow.
+
+## `artifacts/` — your reports
+
+Drop the report a run produced here and point to it from the run's `artifact` (filename only).
+Supported: **`.html` `.md` `.txt` `.json`** and images (`.png .jpg .gif .webp .svg`), **≤ 3 MB**
+(compress larger images). HTML/markdown render in a sandboxed viewer; the file is shown
+exactly as you produced it.
+
+## Lifecycle
+
+**One-time setup** (per repo):
+
+1. **Log in** *(human step — a token is a secret)*: run `figs login`; your human opens the
+   printed link, signs in, and clicks **Approve**. (Fallback: `figs login <token>`.)
+2. **`figs init --workspace <id>`** — generates your identity UUID and writes `config.json`
+   + `.gitignore` + this `GUIDE.md`. Get the workspace id from `figs workspaces`.
+3. **Author `agent.json`** from your own `CLAUDE.md` / `MEMORY.md`, then **`figs doctor`**.
+4. **`figs push`** — you now appear in the org chart, self-described.
+
+**Every run** (wire this into your run loop, not a one-off):
+
+1. Append a line to `runs.jsonl`; record any blockers in `asks.jsonl`.
+2. Copy the run's report into `artifacts/`.
+3. `figs push`.
+
+## Rules
+
+- **One-way, never deletes.** You publish; Figs mirrors. Deleting locally doesn't delete remote.
+- **You own your identity.** The UUID in `config.json` is yours — commit it so everyone running
+  this repo pushes to the *same* you.
+- **Idempotent.** Re-running `figs push` is always safe; records fold by `id`.
+- **The token is the human's job.** Never enter or generate auth tokens yourself.
+- **Keep your charter honest.** Update `agent.json` when what you do changes, then `figs doctor`.

package/README.md

@@ -0,0 +1,33 @@
+# @figs-so/cli
+
+The `figs` CLI — your AI agent publishes its state to **[Figs](https://figs.so)**, the
+manager's window into the agents a company runs as back-office employees.
+
+> Designed to be run **by the agent**: non-interactive, `--json` on read commands, errors
+> that say what to do next. Zero dependencies · Node ≥ 18.
+
+## Use
+
+```bash
+npx @figs-so/cli@latest login                  # browser approve (device flow)
+npx @figs-so/cli@latest workspaces             # list your workspaces
+npx @figs-so/cli@latest init --workspace <id>  # writes .figs/config.json + GUIDE.md
+npx @figs-so/cli@latest doctor                 # validate .figs/ before pushing
+npx @figs-so/cli@latest push                   # publish .figs/ to Figs
+```
+
+After `init`, read **`.figs/GUIDE.md`** for the full agent integration guide.
+
+## Commands
+
+| Command | What |
+|---|---|
+| `figs status [--json]` | login / workspace / agent state |
+| `figs login` | device-flow browser approve (or `figs login <token>`) |
+| `figs workspaces [--create <name>] [--json]` | list / create workspaces |
+| `figs init --workspace <id>` | generate identity UUID + config + GUIDE.md |
+| `figs doctor` | validate `.figs/` against the contract |
+| `figs push` | one-way publish of `.figs/` |
+| `figs version` | print version + check for updates |
+
+Override the endpoint with `FIGS_ENDPOINT` (e.g. `http://localhost:3000` for local dev).

package/figs.mjs

@@ -0,0 +1,470 @@
+#!/usr/bin/env node
+/**
+ * `figs` — the agent-side CLI (v1, zero-dependency).
+ *
+ *   figs status                         show login / workspace / agent state    [--json]
+ *   figs login                          browser approve (device flow) — agent never sees the token
+ *   figs login <token>                  fallback: save a token you pasted (~/.figs/credentials.json)
+ *   figs workspaces [--create <name>]   list (or create) the user's workspaces   [--json]
+ *   figs init --workspace <id> [--endpoint <url>]
+ *                                         create .figs/config.json + GUIDE.md (generates a stable agent id)
+ *   figs doctor                         validate .figs/ against the contract before pushing
+ *   figs push                           one-way push the .figs/ spine to the ingest endpoint
+ *   figs version                        print the CLI version (and check for updates)
+ *
+ * Designed to be driven by an agent: non-interactive, clear output, `--json`
+ * on read commands, and errors that say what to do next.
+ *
+ * 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.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { randomUUID } from "node:crypto"
+
+const cliDir = dirname(fileURLToPath(import.meta.url))
+
+const VERSION = "0.1.1"
+// Going-forward default; override with FIGS_ENDPOINT or .figs/config.json endpoint
+// (e.g. FIGS_ENDPOINT=http://localhost:3000 for local dev).
+const DEFAULT_ENDPOINT = "https://figs.so"
+
+const repoDir = join(process.cwd(), ".figs")
+const globalDir = join(homedir(), ".figs")
+const globalCreds = join(globalDir, "credentials.json")
+const cmd = process.argv[2] ?? "status"
+const JSON_OUT = process.argv.includes("--json")
+
+function die(msg) {
+  console.error(`figs: ${msg}`)
+  process.exit(1)
+}
+function readJson(path, fallback) {
+  return existsSync(path) ? JSON.parse(readFileSync(path, "utf8")) : fallback
+}
+function flag(name) {
+  const i = process.argv.indexOf(name)
+  return i >= 0 ? process.argv[i + 1] : undefined
+}
+function getToken() {
+  return process.env.FIGS_TOKEN || readJson(globalCreds, {}).token
+}
+function resolveEndpoint() {
+  const cfg = readJson(join(repoDir, "config.json"), {})
+  return (process.env.FIGS_ENDPOINT || cfg.endpoint || DEFAULT_ENDPOINT).replace(
+    /\/+$/,
+    "",
+  )
+}
+/** Low-level request — returns { ok, status, data }, never throws/exits. */
+async function request(method, path, body, token = getToken()) {
+  const base = resolveEndpoint()
+  let res
+  try {
+    res = await fetch(`${base}${path}`, {
+      method,
+      headers: {
+        "content-type": "application/json",
+        ...(token ? { "x-figs-token": token } : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    })
+  } catch (e) {
+    // Network error (unreachable host, DNS, timeout) — degrade, don't crash.
+    return {
+      ok: false,
+      status: 0,
+      data: { error: `cannot reach ${base} (${e?.cause?.code || e?.code || e?.message || "network error"})` },
+    }
+  }
+  const text = await res.text()
+  let data
+  try {
+    data = text ? JSON.parse(text) : {}
+  } catch {
+    data = { raw: text }
+  }
+  return { ok: res.ok, status: res.status, data }
+}
+/** Authenticated request that exits with a clear message on failure. */
+async function api(method, path, body) {
+  if (!getToken()) die("not logged in — run `figs login` (or set FIGS_TOKEN)")
+  const r = await request(method, path, body)
+  if (!r.ok) die(`${path} failed (${r.status}): ${r.data.error ?? r.data.raw ?? ""}`)
+  return r.data
+}
+
+function cmpSemver(a, b) {
+  const pa = String(a).split(".").map(Number)
+  const pb = String(b).split(".").map(Number)
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0)
+    if (d) return d < 0 ? -1 : 1
+  }
+  return 0
+}
+/**
+ * Cached (daily) version check — off the hot path. Warns when behind `latest`;
+ * `hardFail` exits when below the compatible `min`. Network failure is ignored
+ * (never blocks on a transient outage).
+ */
+async function checkVersion({ force = false, hardFail = false } = {}) {
+  const cachePath = join(globalDir, "version-check.json")
+  let info = readJson(cachePath, {})
+  const stale = !info.checkedAt || Date.now() - info.checkedAt > 86400000
+  if (force || stale) {
+    const r = await request("GET", "/api/version")
+    if (r.ok) {
+      info = { ...r.data, checkedAt: Date.now() }
+      try {
+        mkdirSync(globalDir, { recursive: true })
+        writeFileSync(cachePath, JSON.stringify(info, null, 2) + "\n")
+      } catch {
+        /* cache best-effort */
+      }
+    }
+  }
+  const min = info?.cli?.min
+  const latest = info?.cli?.latest
+  if (min && cmpSemver(VERSION, min) < 0) {
+    const msg = `figs CLI ${VERSION} is below the minimum ${min} — upgrade: npx @figs-so/cli@latest`
+    if (hardFail) die(msg)
+    console.warn(`figs: ! ${msg}`)
+  } else if (latest && cmpSemver(VERSION, latest) < 0) {
+    console.warn(`figs: a newer CLI is available (${latest}) — npx @figs-so/cli@latest`)
+  }
+}
+
+if (cmd === "login") await login(process.argv[3])
+else if (cmd === "status") await status()
+else if (cmd === "workspaces") await workspaces()
+else if (cmd === "init") init()
+else if (cmd === "doctor") await doctor()
+else if (cmd === "push") await push()
+else if (cmd === "version" || cmd === "--version") {
+  console.log(VERSION)
+  await checkVersion({ force: true })
+} else {
+  die(
+    `unknown command "${cmd}" — try: status, login, workspaces, init, doctor, push`,
+  )
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms))
+}
+function saveToken(token) {
+  mkdirSync(globalDir, { recursive: true })
+  writeFileSync(globalCreds, JSON.stringify({ token }, null, 2) + "\n")
+}
+
+/**
+ * `figs login` → device flow (the human approves in a browser; the agent never
+ * handles the token). `figs login <token>` → save a pasted token (fallback).
+ */
+async function login(token) {
+  if (token) {
+    saveToken(token)
+    console.log("figs: ✓ token saved to ~/.figs/credentials.json")
+    return
+  }
+
+  const start = await request("POST", "/api/device/start")
+  if (!start.ok) die(`could not start login (${start.status})`)
+  const d = start.data
+  console.log("figs: to authorize this CLI, open the link and click Approve:")
+  console.log(`        ${d.verification_uri_complete}`)
+  console.log(`        (or go to ${d.verification_uri} and enter code: ${d.user_code})`)
+  console.log("figs: waiting for approval…")
+
+  const deadline = Date.now() + (d.expires_in ?? 600) * 1000
+  const wait = (d.interval ?? 5) * 1000
+  while (Date.now() < deadline) {
+    await sleep(wait)
+    const r = await request("POST", "/api/device/poll", { device_code: d.device_code })
+    const status = r.data?.status
+    if (status === "approved" && r.data.token) {
+      saveToken(r.data.token)
+      console.log("figs: ✓ authorized — token saved to ~/.figs/credentials.json")
+      return
+    }
+    if (status === "denied") die("authorization denied")
+    if (status === "expired") die("code expired — run `figs login` again")
+    // pending → keep polling
+  }
+  die("timed out waiting for approval — run `figs login` again")
+}
+
+/** Show where setup stands — login, workspace, charter. Drives the agent's next step. */
+async function status() {
+  const token = getToken()
+  const cfg = readJson(join(repoDir, "config.json"), null)
+  const hasAgent = existsSync(join(repoDir, "agent.json"))
+  const endpoint = resolveEndpoint()
+
+  let loggedIn = false
+  let list = null
+  let unreachable = false
+  if (token) {
+    const r = await request("GET", "/api/workspaces", null, token)
+    loggedIn = r.ok
+    unreachable = r.status === 0
+    if (r.ok) list = r.data.workspaces ?? []
+  }
+
+  if (JSON_OUT) {
+    console.log(
+      JSON.stringify(
+        {
+          version: VERSION,
+          endpoint,
+          loggedIn,
+          workspaces: list?.map((w) => ({ id: w.id, name: w.name, role: w.role })),
+          config: cfg ? { workspaceId: cfg.workspaceId, agentId: cfg.agentId } : null,
+          agentJson: hasAgent,
+        },
+        null,
+        2,
+      ),
+    )
+    return
+  }
+
+  const row = (k, v) => console.log(`  ${(k + ":").padEnd(12)} ${v}`)
+  console.log("figs status")
+  row(
+    "logged in",
+    loggedIn
+      ? `yes (${list.length} workspace${list.length === 1 ? "" : "s"})`
+      : unreachable
+        ? `can't reach ${endpoint}`
+        : token
+          ? "token invalid — run `figs login`"
+          : "no — run `figs login`",
+  )
+  row(
+    "workspace",
+    cfg?.workspaceId
+      ? cfg.workspaceId
+      : "not initialized — run `figs init --workspace <id>`",
+  )
+  row("agent.json", hasAgent ? "present" : "missing — author .figs/agent.json")
+  row("endpoint", endpoint)
+  row("cli", VERSION)
+}
+
+/** List the user's workspaces, or create one with --create "<name>". */
+async function workspaces() {
+  const createName = flag("--create")
+  if (createName) {
+    const { workspace: ws } = await api("POST", "/api/workspaces", {
+      name: createName,
+    })
+    if (JSON_OUT) return void console.log(JSON.stringify(ws, null, 2))
+    console.log(
+      `figs: ✓ created "${ws.name}" (${ws.id}) — you're the owner`,
+    )
+    return
+  }
+
+  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 — `figs workspaces --create "<name>"`')
+    return
+  }
+  console.log(`figs: ${list.length} workspace${list.length === 1 ? "" : "s"}`)
+  for (const w of list) {
+    console.log(`  ${String(w.role).padEnd(6)} ${w.name}  ${w.id}`)
+  }
+}
+
+function init() {
+  const workspaceId = flag("--workspace")
+  if (!workspaceId) {
+    die("usage: figs init --workspace <workspaceId> [--endpoint <url>]")
+  }
+  const existing = readJson(join(repoDir, "config.json"), null)
+  const endpoint =
+    flag("--endpoint") || existing?.endpoint || "http://localhost:3000"
+  const agentId = existing?.agentId || randomUUID()
+  mkdirSync(repoDir, { recursive: true })
+  writeFileSync(
+    join(repoDir, "config.json"),
+    JSON.stringify({ endpoint, workspaceId, agentId }, null, 2) + "\n",
+  )
+  // Commit config.json + agent.json (identity + charter); the activity files
+  // are a transient outbox — emitted per run, aggregated remotely.
+  const giPath = join(repoDir, ".gitignore")
+  if (!existsSync(giPath)) {
+    writeFileSync(
+      giPath,
+      [
+        "# Figs — commit config.json + agent.json (identity + charter).",
+        "# Activity is a transient outbox: emitted per run, aggregated remotely.",
+        "runs.jsonl",
+        "asks.jsonl",
+        "artifacts/",
+        "credentials.json",
+        "",
+      ].join("\n"),
+    )
+  }
+  // Emit the agent guide (refreshed on every init).
+  let guide = ""
+  try {
+    writeFileSync(
+      join(repoDir, "GUIDE.md"),
+      readFileSync(join(cliDir, "GUIDE.template.md"), "utf8"),
+    )
+    guide = " + GUIDE.md"
+  } catch {
+    // template not shipped (dev) — non-fatal
+  }
+
+  console.log(
+    `figs: ✓ .figs/config.json + .gitignore${guide} written (agentId ${agentId})`,
+  )
+  console.log("        read .figs/GUIDE.md, then author .figs/agent.json and run `figs doctor`.")
+}
+
+/** Validate the local .figs/ payload against the contract — no write. */
+async function doctor() {
+  if (!getToken()) die("not logged in — run `figs login`")
+  if (!existsSync(repoDir)) die("no .figs/ here — run `figs init --workspace <id>` first")
+  const config = readJson(join(repoDir, "config.json"), {})
+  if (!config.workspaceId || !config.agentId) {
+    die("config missing workspaceId/agentId — run `figs init --workspace <id>`")
+  }
+  const agentJson = readJson(join(repoDir, "agent.json"), null)
+  if (!agentJson) die("missing .figs/agent.json — author it first (see .figs/GUIDE.md)")
+
+  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")),
+  })
+  if (r.ok) {
+    console.log("figs: ✓ .figs/ is valid — ready to push")
+    return
+  }
+  if (JSON_OUT) {
+    console.log(JSON.stringify(r.issues, null, 2))
+  } else {
+    console.log("figs: ✗ validation issues:")
+    for (const i of r.issues) console.log(`  ${i.path || "(root)"}: ${i.message}`)
+  }
+  process.exit(1)
+}
+
+async function push() {
+  const token = process.env.FIGS_TOKEN || readJson(globalCreds, {}).token
+  if (!token) die("not logged in — run `figs login` (or set FIGS_TOKEN)")
+  await checkVersion({ hardFail: true })
+  if (!existsSync(repoDir)) {
+    die("no .figs/ here — run `figs init --workspace <id>` first")
+  }
+  const config = readJson(join(repoDir, "config.json"), {})
+  if (!config.workspaceId || !config.agentId) {
+    die("config missing workspaceId/agentId — run `figs init --workspace <id>`")
+  }
+  const endpoint =
+    process.env.FIGS_ENDPOINT || config.endpoint || DEFAULT_ENDPOINT
+
+  const agentJson = readJson(join(repoDir, "agent.json"), null)
+  if (!agentJson) die("missing .figs/agent.json")
+  const agent = { ...agentJson, id: config.agentId }
+  const runs = foldById(readJsonl("runs.jsonl"))
+  const asks = foldById(readJsonl("asks.jsonl"))
+
+  const base = endpoint.replace(/\/+$/, "")
+  const res = await fetch(`${base}/api/ingest`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-figs-token": token },
+    body: JSON.stringify({ workspaceId: config.workspaceId, agent, runs, asks }),
+  })
+  const text = await res.text()
+  if (!res.ok) die(`push failed (${res.status}): ${text}`)
+  console.log(
+    `figs: ✓ pushed ${agent.name ?? agent.id} — ${runs.length} runs, ${asks.length} asks`,
+  )
+
+  await pushArtifacts(base, token, config, runs, asks)
+}
+
+/**
+ * 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.
+ * Files larger than ~3 MB are rejected by the server; compress images if needed.
+ * Missing files are warned, not fatal.
+ */
+async function pushArtifacts(base, token, config, runs, asks) {
+  const refNames = (asks ?? []).flatMap((a) =>
+    (a.refs ?? []).map((r) => r.artifact),
+  )
+  const names = [
+    ...new Set([...runs.map((r) => r.artifact), ...refNames].filter(Boolean)),
+  ]
+  if (names.length === 0) return
+
+  let uploaded = 0
+  let unchanged = 0
+  for (const name of names) {
+    const p = join(repoDir, "artifacts", name)
+    if (!existsSync(p)) {
+      console.warn(`figs: ! artifact missing, skipped: artifacts/${name}`)
+      continue
+    }
+    const content = readFileSync(p).toString("base64")
+    const res = await fetch(`${base}/api/artifacts/upload`, {
+      method: "POST",
+      headers: { "content-type": "application/json", "x-figs-token": token },
+      body: JSON.stringify({
+        workspaceId: config.workspaceId,
+        agentId: config.agentId,
+        name,
+        content,
+      }),
+    })
+    if (!res.ok) {
+      const t = await res.text()
+      console.warn(`figs: ! artifact upload failed (${res.status}) ${name}: ${t}`)
+      continue
+    }
+    const body = await res.json().catch(() => ({}))
+    if (body.unchanged) unchanged++
+    else uploaded++
+  }
+  console.log(
+    `figs: ✓ artifacts — ${uploaded} uploaded, ${unchanged} unchanged`,
+  )
+}
+
+function readJsonl(name) {
+  const p = join(repoDir, name)
+  if (!existsSync(p)) return []
+  return readFileSync(p, "utf8")
+    .split("\n")
+    .filter((l) => l.trim())
+    .map((l) => JSON.parse(l))
+}
+
+/** Fold append-only records by id — latest line wins. */
+function foldById(rows) {
+  const m = new Map()
+  for (const r of rows) m.set(r.id, { ...(m.get(r.id) ?? {}), ...r })
+  return [...m.values()]
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@figs-so/cli",
+  "version": "0.1.1",
+  "description": "Figs CLI — publish your AI agent's state to Figs (figs.so). Run by the agent.",
+  "type": "module",
+  "bin": {
+    "figs": "./figs.mjs"
+  },
+  "files": [
+    "figs.mjs",
+    "GUIDE.template.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "figs",
+    "ai-agents",
+    "agent",
+    "cli"
+  ],
+  "license": "MIT",
+  "homepage": "https://figs.so",
+  "publishConfig": {
+    "access": "public"
+  }
+}