@figs-so/cli 0.1.14 → 0.1.16

package/README.md

@@ -6,8 +6,9 @@ Figs is the open protocol — and the place — for how AI employees report to a
 Every agent you run (Claude Code, Codex, Cursor) publishes what it owns, what it's done, and what it
 needs from a person — into one shared view your whole team can see.
 
-> **Git, but for your AI workforce.** The `.figs` format is an open standard (this repo). The hosted app
-> at **[app.figs.so](https://app.figs.so)** is the easiest place to read it; you can also self-host.
+> **The open standard for how AI employees report to humans.** The `.figs` format is that standard (this
+> repo). The hosted app at **[app.figs.so](https://app.figs.so)** is the easiest place to read it; you can
+> also self-host.
 
 [![CLI on npm](https://img.shields.io/npm/v/%40figs-so%2Fcli?label=%40figs-so%2Fcli)](https://www.npmjs.com/package/@figs-so/cli)
  ·  License: **MIT** (this repo — protocol + CLI)  ·  The app: **AGPL-3.0**
@@ -26,17 +27,16 @@ what happened; you read Figs. And when an agent hits something only a human can
 silently — it **hands off** to you.
 
 We don't reinvent the agent. Your agent is already Claude Code / Codex / Cursor, and it's only getting
-better. Figs is the human-facing layer on top: the one place a whole team can see the AI workforce.
+better. Figs is the human-facing layer on top: the one place a whole team can see the fleet.
 
 ## Quickstart (60 seconds)
 
 Run these from your agent's repo (or have the agent run them):
 
 ```bash
-npx @figs-so/cli@latest login                    # approve in your browser (the agent never sees a token)
-npx @figs-so/cli@latest workspaces               # find your workspace slug
-npx @figs-so/cli@latest init --workspace <slug>  # creates .figs/ with the agent's identity
-# describe the agent in .figs/agent.json — its name, mandate, what it owns
+npx @figs-so/cli@latest login                    # opens your browser — sign up & approve (the agent never sees a token)
+npx @figs-so/cli@latest init                     # scaffolds .figs/ — uses your only workspace (--workspace <slug> to pick)
+# fill in .figs/agent.json — its name, mandate, what it owns (figs doctor flags any placeholders)
 npx @figs-so/cli@latest push                     # publish → it appears in your org chart
 ```
 
@@ -51,8 +51,9 @@ SDK in your agent's code. From there you decide, deliberately, how much of its r
   *rendered artifacts* (reports/charts shown in a sandboxed viewer). No display DSL to learn.
 - **Identity is the agent's own.** An agent generates a UUID once; that UUID *is* its identity. Many people
   can run the same agent (it's a repo) and their pushes aggregate.
-- **You read it on Figs.** The hosted app turns the pushes into an org chart of your AI workforce, a glance
-  view per agent, and an inbox of the **handoffs** — the things an agent needs a human to decide.
+- **You read it on Figs.** The hosted app turns the pushes into an org chart of your AI employees, a glance
+  view per agent, and a **needs-you inbox** — the handoffs an employee flags for a human, answered when you
+  have time (a message, not a blocking gate).
 
 The full `.figs` contract is specified in **[`SPEC.md`](./SPEC.md)** (`figs-spec v1`). Anyone can implement
 it — that's the point of an open protocol.
@@ -62,11 +63,15 @@ it — that's the point of an open protocol.
 `@figs-so/cli` (command `figs`) is zero-dependency, Node ≥ 18, and built to be run *by the agent*:
 non-interactive, `--json` on read commands, and errors that say what to do next.
 
+**Invoke it with `npx @figs-so/cli@latest <cmd>`** — no install needed; the `figs <cmd>` forms below
+are shorthand for exactly that (always current, no version drift). Prefer a real local command?
+`npm i -g @figs-so/cli`, then `figs <cmd>` directly.
+
 | Command | What |
 |---|---|
 | `figs login` / `logout` | device-flow browser approve / remove local token |
 | `figs workspaces [--json]` | list your workspaces (create one in the web app) |
-| `figs init --workspace <slug>` | generate identity + write `.figs/` |
+| `figs init [--workspace <slug>]` | generate identity + write `.figs/` (omit the flag: uses your only workspace, else lists them) |
 | `figs doctor` | validate `.figs/` against the contract before pushing |
 | `figs push` | one-way publish of `.figs/` |
 | `figs status [--json]` | login / workspace / agent state |
@@ -76,7 +81,7 @@ Override the endpoint for local dev with `FIGS_ENDPOINT` (e.g. `http://localhost
 
 ## What Figs is — and is NOT
 
-**Is:** the human-facing reporting + handoff layer for your AI workforce. The neutral, multiplayer place
+**Is:** the human-facing reporting + handoff layer for your fleet. The neutral, multiplayer place
 that makes a fleet of agents *legible* to a whole team.
 
 **Is NOT:**
@@ -90,18 +95,27 @@ that makes a fleet of agents *legible* to a whole team.
 > at fleet scale — not a tamper-proof audit trail (agent state is self-reported). We're building in the
 > open; expect rough edges and tell us where it breaks.
 
-## Run it your way
+## Run it
 
-- **Hosted (easiest):** [app.figs.so](https://app.figs.so) — sign in, create a workspace, push.
-- **Self-host:** the app is open source (AGPL-3.0) at **[figs-so/app](https://github.com/figs-so/app)** —
-  bring your own Postgres + storage. See its README for setup.
+- **Hosted:** [app.figs.so](https://app.figs.so) — sign in, create a workspace, push. The app is a hosted
+  product; the CLI + protocol in this repo are MIT and run anywhere.
 
 ## Licensing
 
 - **This repo — the `.figs` protocol + the CLI: [MIT](./LICENSE).** Use it, embed it, build on it, emit
   `.figs` from anything. Zero friction is the point.
-- **The hosted app: AGPL-3.0** ([figs-so/app](https://github.com/figs-so/app)). Open and self-hostable; the
-  defensive license keeps the hosted layer honest.
+- **The hosted app at [app.figs.so](https://app.figs.so) is a commercial product** (closed source). Your
+  data isn't locked in, though — it's `.figs`, an open format you can read or export anytime.
+
+## The Figs ecosystem
+
+Figs is one stack in three pieces — **build → report → govern**. Land on any repo; here's the whole picture:
+
+| Layer | Repo | License | Role |
+|---|---|---|---|
+| 🏗️ Build | **[OpenFigs](https://github.com/figs-so/openfigs)** | MIT | build trustworthy back-office AI employees — conventions + skeleton, runtime-agnostic |
+| 📤 Report | **[`.figs` + CLI](https://github.com/figs-so/figs)** | MIT | the open standard an agent reports its state in — **← you're here** |
+| 👁️ Govern | **[Figs app](https://app.figs.so)** | hosted | the org chart + handoff inbox humans read |
 
 ## Links
 

package/SPEC.md

@@ -41,16 +41,17 @@ Non-secret. Pins one shared identity so many runners' pushes aggregate.
 |---|---|---|
 | `endpoint` | string (URL) | Where to publish (default `https://app.figs.so`). |
 | `workspaceId` | UUID | The workspace this agent belongs to. |
-| `agentId` | UUID | The agent's identity. Equal to `agent.json#id`. |
+| `agentId` | UUID | The agent's identity, generated once by `figs init`. The CLI attaches it as the agent's `id` on push (you don't hand-author `id` in `agent.json`). |
 
 ## 4. `agent.json` — the charter
 
-The agent's self-description. Authoring this and publishing makes the agent *appear*. Only `id` and `name`
-are required; everything else is optional and rendered when present.
+The agent's self-description. Authoring this and publishing makes the agent *appear*. The only field you
+author that's required is `name` — **do not hand-author `id`**: `figs init` mints it into `config.json` and
+the CLI attaches it on push. Everything else is optional and rendered when present.
 
 | Field | Type | Req | Meaning |
 |---|---|:--:|---|
-| `id` | UUID | ✓ | Identity; must equal `config.json#agentId`. |
+| `id` | UUID | ✓ | Identity. **Supplied from `config.json#agentId` by the CLI on push — not written in this file.** |
 | `name` | string | ✓ | Display name. |
 | `key` | string | | Display slug; derived from `name` if absent. |
 | `type` | `"agent"` \| `"human"` | | Default `"agent"`. |
@@ -102,7 +103,7 @@ primitive** — the agent reached the edge of its autonomy.
 | Field | Type | Req | Meaning |
 |---|---|:--:|---|
 | `id` | string | ✓ | Stable id (upsert key). |
-| `type` | enum | ✓ | `blocked` \| `needs-decision` \| `confirm-assumption` \| `sign-off`. |
+| `type` | enum | ✓ | `blocked` \| `needs-decision` \| `sign-off` \| `fyi`. `fyi` is a non-blocking heads-up (no decision needed). (`confirm-assumption` still validates but is **deprecated** — use `needs-decision` or `fyi`.) |
 | `status` | `"open"` \| `"resolved"` | | Default `"open"`. |
 | `title` | string | ✓ | The ask, in one line. |
 | `unit` | string | | The `Unit.id` this concerns. |
@@ -174,9 +175,8 @@ Deliberately out of scope for v1, named here so implementers don't repurpose the
 ```
 
 ```jsonc
-// .figs/agent.json
+// .figs/agent.json   (no `id` here — `figs init` puts it in config.json; the CLI attaches it on push)
 {
-  "id": "…uuid… (== config.agentId)",
   "name": "Reconciliation",
   "type": "agent",
   "role": "Reconciliation Officer",
@@ -210,7 +210,7 @@ Deliberately out of scope for v1, named here so implementers don't repurpose the
 
 ```jsonc
 // .figs/asks.jsonl   (one object per line)
-{ "id": "acme-bridge", "ts": "2026-05-28T21:05:00Z", "type": "confirm-assumption", "status": "open", "unit": "acme",
+{ "id": "acme-bridge", "ts": "2026-05-28T21:05:00Z", "type": "needs-decision", "status": "open", "unit": "acme",
   "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.",

package/figs.mjs

@@ -3,7 +3,7 @@
  * `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                          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]
@@ -35,8 +35,9 @@ import {
   writeFileSync,
 } from "node:fs"
 import { homedir } from "node:os"
-import { join } from "node:path"
+import { basename, join } from "node:path"
 import { randomUUID } from "node:crypto"
+import { spawn } from "node:child_process"
 
 // Single source of truth for the version: package.json (shipped alongside this
 // file in the published package). One edit keeps `figs version`, the floor
@@ -72,7 +73,7 @@ const COMMANDS = {
     flags: [],
     desc: "log in — browser device-flow, or save a pasted token",
     more: [
-      "no arg → device flow: a human approves in a browser (you never see the token).",
+      "no arg → device flow: opens a browser for a human to approve (you never see the token).",
       "<token> → save a token you already have to ~/.figs/credentials.json.",
     ],
     eg: "figs login",
@@ -85,11 +86,13 @@ const COMMANDS = {
     eg: "figs workspaces",
   },
   init: {
-    args: "--workspace <slug-or-id> [--endpoint <url>]",
+    args: "[--workspace <slug-or-id>] [--endpoint <url>]",
     flags: ["--workspace", "--endpoint"],
-    desc: "set up .figs/ here (identity UUID + config + pointer GUIDE.md)",
+    desc: "scaffold .figs/ here (identity + charter/contract/guide templates)",
     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.",
     ],
     eg: "figs init --workspace acme-corp",
   },
@@ -212,9 +215,9 @@ function cmpSemver(a, b) {
   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).
+ * Cached (daily) compatibility check — off the hot path. `hardFail` exits when
+ * below the server's 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")
@@ -233,14 +236,11 @@ async function checkVersion({ force = false, hardFail = false } = {}) {
     }
   }
   const min = info?.cli?.min
-  const latest = info?.cli?.latest
   // cmpSemver returns null on an unparseable version → skip (never fail closed).
   if (min && cmpSemver(VERSION, min) === -1) {
     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) === -1) {
-    console.warn(`figs: a newer CLI is available (${latest}) — npx @figs-so/cli@latest`)
   }
 }
 
@@ -311,9 +311,30 @@ function saveToken(token) {
   }
 }
 
+// Best-effort: pop the approval page in the user's default browser so they only
+// have to click Approve. Silent no-op when it can't (headless / remote / CI) —
+// the link is always printed above as the fallback. Detached + unref'd so it
+// never blocks or ties the polling loop to the browser process.
+function openBrowser(url) {
+  try {
+    const [cmd, args] =
+      process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+          ? ["cmd", ["/c", "start", "", url]]
+          : ["xdg-open", [url]]
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true })
+    child.on("error", () => {}) // swallow ENOENT / no opener available
+    child.unref()
+  } catch {
+    /* ignore — the printed link is the fallback */
+  }
+}
+
 /**
- * `figs login` → device flow (the human approves in a browser; the agent never
- * handles the token). `figs login <token>` → save a pasted token (fallback).
+ * `figs login` → device flow: opens the approval page in the user's browser
+ * (the printed link is the fallback); the human clicks Approve and the agent
+ * never handles the token. `figs login <token>` → save a pasted token (fallback).
  */
 async function login(token) {
   if (token) {
@@ -325,9 +346,10 @@ async function login(token) {
   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("figs: opening your browser to approve this CLI — just click Approve there.")
+  console.log(`        if it doesn't open, visit: ${d.verification_uri_complete}`)
   console.log(`        (or go to ${d.verification_uri} and enter code: ${d.user_code})`)
+  openBrowser(d.verification_uri_complete)
   console.log("figs: waiting for approval…")
 
   const deadline = Date.now() + (d.expires_in ?? 600) * 1000
@@ -339,6 +361,7 @@ async function login(token) {
     if (status === "approved" && r.data.token) {
       saveToken(r.data.token)
       console.log("figs: ✓ authorized — token saved to ~/.figs/credentials.json")
+      console.log("figs: next — run `figs init` to scaffold .figs/ here")
       return
     }
     if (status === "denied") die("authorization denied")
@@ -515,18 +538,92 @@ are a gitignored outbox. The token is the human's job — never generate one you
 `
 }
 
-async function init() {
-  const workspaceArg = flag("--workspace")
-  if (!workspaceArg) {
-    die("usage: figs init --workspace <slug-or-id> [--endpoint <url>]")
+/**
+ * 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;
+ * `figs doctor` refuses to bless a charter that still has them. `name` defaults
+ * to the folder name (a sensible first guess), `id` is intentionally absent —
+ * the CLI attaches the identity UUID from config.json on push.
+ */
+function agentJsonStub(name) {
+  return (
+    JSON.stringify(
+      {
+        name,
+        role: "<one line — what you are>",
+        status: "in_dev",
+        mandate: "<one sentence — what you are accountable for>",
+        org: { department: "<your team / department>" },
+        runtime: "<what runs you, e.g. Claude Code>",
+        cadence: "<on-demand · weekly · monthly · …>",
+        responsibilities: ["<an area of work you own — list a few, or use steps>"],
+        properties: [{ k: "<fact>", v: "<value>" }],
+      },
+      null,
+      2,
+    ) + "\n"
+  )
+}
+
+/** A starter activity contract — written by `figs init` only when none exists. */
+function contractStub(name) {
+  return `# Activity 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.
+
+> **Maintain:** edit when the surfacing agreement changes (a new stream, a sensitivity change).
+> Keep it honest to what you actually push.
+
+## What I surface
+
+| 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 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.
+`
+}
+
+/**
+ * Find string values still left as `<…>` template placeholders, with their JSON
+ * path. Used by `figs doctor` to block publishing a half-filled charter. Matches
+ * a value that is *entirely* a placeholder (e.g. "<one line — what you are>") so
+ * real content containing stray angle brackets isn't flagged.
+ */
+function findPlaceholders(obj) {
+  const out = []
+  const walk = (v, path) => {
+    if (typeof v === "string") {
+      if (/^<.*>$/.test(v.trim())) out.push({ path: path || "(root)", value: v })
+    } else if (Array.isArray(v)) {
+      v.forEach((x, i) => walk(x, `${path}[${i}]`))
+    } else if (v && typeof v === "object") {
+      for (const [k, x] of Object.entries(v)) walk(x, path ? `${path}.${k}` : k)
+    }
   }
-  const endpoint = (flag("--endpoint") || resolveEndpoint()).replace(/\/+$/, "")
+  walk(obj, "")
+  return out
+}
 
-  // 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)) {
+/**
+ * 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.
+ */
+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)")
     }
@@ -536,12 +633,40 @@ async function init() {
     }
     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
+    if (!match) die(`no workspace matching "${workspaceArg}" — run \`figs workspaces\` to see yours`)
+    return match.id
   }
 
+  // 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)
+}
+
+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.
   const existing = readJson(join(repoDir, "config.json"), null)
   const agentId = existing?.agentId || randomUUID()
   mkdirSync(repoDir, { recursive: true })
@@ -549,48 +674,87 @@ async function init() {
     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 + CONTRACT.md + GUIDE.md.",
-        "# Activity is a transient outbox: emitted per run, aggregated remotely.",
-        "runs.jsonl",
-        "asks.jsonl",
-        "artifacts/",
-        "credentials.json",
-        "",
-      ].join("\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 created = []
+  const ensure = (rel, contents) => {
+    const p = join(repoDir, rel)
+    if (existsSync(p)) return false
+    writeFileSync(p, contents)
+    created.push(rel)
+    return true
   }
-  writeFileSync(join(repoDir, "GUIDE.md"), guideStub(endpoint))
+  ensure(
+    ".gitignore",
+    [
+      "# Figs — commit config.json + agent.json + CONTRACT.md + GUIDE.md.",
+      "# Activity is a transient outbox: emitted per run, aggregated remotely.",
+      "runs.jsonl",
+      "asks.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", "")
+  mkdirSync(join(repoDir, "artifacts"), { recursive: true })
 
   console.log(
-    `figs: ✓ .figs/config.json + .gitignore + GUIDE.md written (agentId ${agentId})`,
+    `figs: ✓ .figs/ ready — config.json written (agentId ${agentId}, workspace ${workspaceId})`,
   )
+  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.",
+    )
+  } else {
+    console.log(
+      "        Your charter (.figs/agent.json) is already here — `figs doctor` && `figs push` to publish.",
+    )
+  }
   console.log(
-    `        Phase 1: author .figs/agent.json (your charter), then \`figs doctor\` && \`figs push\` to appear.`,
+    "        Anchor Figs in the file you load every session (CLAUDE.md/AGENTS.md/…): paste the",
   )
+  console.log(`        figs:begin block from ${endpoint}/llms.txt, or future sessions forget Figs.`)
   console.log(
-    `        Then anchor Figs in the instruction file you load every session (CLAUDE.md/AGENTS.md/…) — see /llms.txt; without it, future sessions forget Figs.`,
+    "        Commit config.json + agent.json + CONTRACT.md + GUIDE.md; never commit credentials.json.",
   )
   console.log(`        Full guide: ${endpoint}/llms.txt`)
 }
 
 /** 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")
+  // Local checks first (no token/network needed) — fail fast and offline.
+  if (!existsSync(repoDir)) die("no .figs/ here — run `figs init` first")
   const config = readJson(join(repoDir, "config.json"), {})
   if (!config.workspaceId || !config.agentId) {
-    die("config missing workspaceId/agentId — run `figs init --workspace <id>`")
+    die("config missing workspaceId/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)")
 
+  // Refuse to bless a charter that still has `<…>` template placeholders — `figs
+  // init` scaffolds them, and pushing them would publish "<one line — what you
+  // 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`)")
+    process.exit(1)
+  }
+
+  if (!getToken()) die("not logged in — run `figs login`")
   const r = await api("POST", "/api/validate", {
     workspaceId: config.workspaceId,
     agent: { ...agentJson, id: config.agentId },
@@ -621,11 +785,11 @@ async function push() {
   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")
+    die("no .figs/ here — run `figs init` first")
   }
   const config = readJson(join(repoDir, "config.json"), {})
   if (!config.workspaceId || !config.agentId) {
-    die("config missing workspaceId/agentId — run `figs init --workspace <id>`")
+    die("config missing workspaceId/agentId — run `figs init`")
   }
   const endpoint =
     process.env.FIGS_ENDPOINT || config.endpoint || DEFAULT_ENDPOINT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figs-so/cli",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Figs CLI — publish your AI agent's state to Figs (figs.so). Run by the agent.",
   "type": "module",
   "bin": {