@figs-so/cli 0.1.2 → 0.1.5

package/README.md

@@ -9,14 +9,15 @@ manager's window into the agents a company runs as back-office employees.
 ## 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
+npx @figs-so/cli@latest login                    # browser approve (device flow)
+npx @figs-so/cli@latest workspaces               # list your workspaces (shows the slug)
+npx @figs-so/cli@latest init --workspace <slug>  # 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.
+The full, always-current guide + `agent.json` schema is served at **`<endpoint>/llms.txt`**
+(`figs init` drops a thin pointer to it at `.figs/GUIDE.md`).
 
 ## Commands
 
@@ -24,8 +25,8 @@ After `init`, read **`.figs/GUIDE.md`** for the full agent integration guide.
 |---|---|
 | `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 workspaces [--json]` | list your workspaces (read-only; create one in the web app) |
+| `figs init --workspace <slug-or-id>` | resolve the workspace, generate identity UUID + config + pointer GUIDE.md |
 | `figs doctor` | validate `.figs/` against the contract |
 | `figs push` | one-way publish of `.figs/` |
 | `figs version` | print version + check for updates |

package/figs.mjs

@@ -5,8 +5,8 @@
  *   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>]
+ *   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 doctor                         validate .figs/ against the contract before pushing
  *   figs push                           one-way push the .figs/ spine to the ingest endpoint
@@ -28,13 +28,10 @@ import {
   writeFileSync,
 } from "node:fs"
 import { homedir } from "node:os"
-import { dirname, join } from "node:path"
-import { fileURLToPath } from "node:url"
+import { join } from "node:path"
 import { randomUUID } from "node:crypto"
 
-const cliDir = dirname(fileURLToPath(import.meta.url))
-
-const VERSION = "0.1.2"
+const VERSION = "0.1.5"
 // 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://app.figs.so"
@@ -148,7 +145,7 @@ async function checkVersion({ force = false, hardFail = false } = {}) {
 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 === "init") await init()
 else if (cmd === "doctor") await doctor()
 else if (cmd === "push") await push()
 else if (cmd === "version" || cmd === "--version") {
@@ -200,6 +197,10 @@ async function login(token) {
     }
     if (status === "denied") die("authorization denied")
     if (status === "expired") die("code expired — run `figs login` again")
+    if (status === "already_claimed") {
+      die("this login was already completed (on another run) — run `figs status` to check; re-run `figs login` if no token was saved")
+    }
+    if (status === "not_found") die("login code not found — run `figs login` again")
     // pending → keep polling
   }
   die("timed out waiting for approval — run `figs login` again")
@@ -210,6 +211,7 @@ async function status() {
   const token = getToken()
   const cfg = readJson(join(repoDir, "config.json"), null)
   const hasAgent = existsSync(join(repoDir, "agent.json"))
+  const hasContract = existsSync(join(repoDir, "CONTRACT.md"))
   const endpoint = resolveEndpoint()
 
   let loggedIn = false
@@ -232,6 +234,7 @@ async function status() {
           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,
@@ -258,45 +261,98 @@ async function status() {
       ? cfg.workspaceId
       : "not initialized — run `figs init --workspace <id>`",
   )
-  row("agent.json", hasAgent ? "present" : "missing — author .figs/agent.json")
+  row("agent.json", hasAgent ? "present (identity)" : "missing — author .figs/agent.json")
+  row(
+    "contract",
+    hasContract
+      ? "present (activity) — follow it"
+      : "none yet — Activity is optional, agree it with your user",
+  )
   row("endpoint", endpoint)
   row("cli", VERSION)
 }
 
-/** List the user's workspaces, or create one with --create "<name>". */
+/**
+ * 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 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>"`')
+    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.name}  ${w.id}`)
+    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),
+  )
 }
 
-function init() {
-  const workspaceId = flag("--workspace")
-  if (!workspaceId) {
-    die("usage: figs init --workspace <workspaceId> [--endpoint <url>]")
+/**
+ * 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).
+
+**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.
+`
+}
+
+async function init() {
+  const workspaceArg = flag("--workspace")
+  if (!workspaceArg) {
+    die("usage: figs init --workspace <slug-or-id> [--endpoint <url>]")
+  }
+  const endpoint = (flag("--endpoint") || resolveEndpoint()).replace(/\/+$/, "")
+
+  // A UUID is the canonical workspace id (used as-is, no network). A slug is the
+  // human-friendly handle — resolve it to its UUID via the API, and store the
+  // UUID so a later workspace rename can't break this agent's pushes.
+  let workspaceId = workspaceArg
+  if (!isUuid(workspaceArg)) {
+    if (!getToken()) {
+      die("not logged in — run `figs login` first (resolving a workspace slug needs auth; or pass the workspace UUID)")
+    }
+    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 ?? ""}`)
+    }
+    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`)
+    }
+    workspaceId = match.id
   }
+
   const existing = readJson(join(repoDir, "config.json"), null)
-  const endpoint =
-    flag("--endpoint") || existing?.endpoint || DEFAULT_ENDPOINT
   const agentId = existing?.agentId || randomUUID()
   mkdirSync(repoDir, { recursive: true })
   writeFileSync(
@@ -310,7 +366,7 @@ function init() {
     writeFileSync(
       giPath,
       [
-        "# Figs — commit config.json + agent.json (identity + charter).",
+        "# Figs — commit config.json + agent.json + CONTRACT.md + GUIDE.md.",
         "# Activity is a transient outbox: emitted per run, aggregated remotely.",
         "runs.jsonl",
         "asks.jsonl",
@@ -320,22 +376,15 @@ function init() {
       ].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
-  }
+  writeFileSync(join(repoDir, "GUIDE.md"), guideStub(endpoint))
 
   console.log(
-    `figs: ✓ .figs/config.json + .gitignore${guide} written (agentId ${agentId})`,
+    `figs: ✓ .figs/config.json + .gitignore + GUIDE.md written (agentId ${agentId})`,
+  )
+  console.log(
+    `        Phase 1: author .figs/agent.json (your charter), then \`figs doctor\` && \`figs push\` to appear.`,
   )
-  console.log("        read .figs/GUIDE.md, then author .figs/agent.json and run `figs doctor`.")
+  console.log(`        Full guide: ${endpoint}/llms.txt`)
 }
 
 /** Validate the local .figs/ payload against the contract — no write. */
@@ -408,8 +457,10 @@ async function push() {
  * 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.
+ * 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.
  */
 async function pushArtifacts(base, token, config, runs, asks) {
   const refNames = (asks ?? []).flatMap((a) =>
@@ -422,10 +473,13 @@ async function pushArtifacts(base, token, config, runs, asks) {
 
   let uploaded = 0
   let unchanged = 0
+  let missing = 0
+  let failed = 0
   for (const name of names) {
     const p = join(repoDir, "artifacts", name)
     if (!existsSync(p)) {
       console.warn(`figs: ! artifact missing, skipped: artifacts/${name}`)
+      missing++
       continue
     }
     const content = readFileSync(p).toString("base64")
@@ -440,8 +494,13 @@ async function pushArtifacts(base, token, config, runs, asks) {
       }),
     })
     if (!res.ok) {
-      const t = await res.text()
-      console.warn(`figs: ! artifact upload failed (${res.status}) ${name}: ${t}`)
+      const t = await res.text().catch(() => "")
+      const hint =
+        res.status === 413 ? " — too large (>3 MB); compress or split it" : ""
+      console.error(
+        `figs: ✗ artifact upload failed (${res.status}) ${name}${hint}${t ? `: ${t}` : ""}`,
+      )
+      failed++
       continue
     }
     const body = await res.json().catch(() => ({}))
@@ -449,8 +508,13 @@ async function pushArtifacts(base, token, config, runs, asks) {
     else uploaded++
   }
   console.log(
-    `figs: ✓ artifacts — ${uploaded} uploaded, ${unchanged} unchanged`,
+    `figs: ${failed ? "✗" : "✓"} artifacts — ${uploaded} uploaded, ${unchanged} unchanged` +
+      (missing ? `, ${missing} missing` : "") +
+      (failed ? `, ${failed} failed` : ""),
   )
+  // The spine already landed; signal a non-zero exit so an agent's run loop can
+  // catch that an artifact the manager needs to read did not publish.
+  if (failed) process.exit(1)
 }
 
 function readJsonl(name) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figs-so/cli",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "description": "Figs CLI — publish your AI agent's state to Figs (figs.so). Run by the agent.",
   "type": "module",
   "bin": {
@@ -8,7 +8,6 @@
   },
   "files": [
     "figs.mjs",
-    "GUIDE.template.md",
     "README.md"
   ],
   "engines": {

package/GUIDE.template.md

@@ -1,147 +0,0 @@
-<!-- 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`.