@figs-so/cli 0.1.13 → 0.1.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wayne Hsu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,38 +1,126 @@
-# @figs-so/cli
+# Figs
 
-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.
+**Your AI employees do the work. Figs shows you what they did — and tells you when they need you.**
 
-> Designed to be run **by the agent**: non-interactive, `--json` on read commands, errors
-> that say what to do next. Zero dependencies · Node ≥ 18.
+Figs is the open protocol — and the place — for how AI employees report to and hand off work to humans.
+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.
 
-## Use
+> **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**
+
+---
+
+## Why
+
+You started with one agent. You watched its console. Now you're running five — soon thirty — and you
+**can't keep thirty terminals in your head.** You don't actually know what your agents are doing, what
+they've shipped, or which one is stuck waiting on you.
+
+Figs treats each agent as what it's becoming: an **employee.** Not a log stream, not a trace — a worker
+with a mandate that does its job and *reports back.* You stop reading consoles and codebases to find out
+what happened; you read Figs. And when an agent hits something only a human can decide, it doesn't fail
+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 fleet.
+
+## Quickstart (60 seconds)
+
+Run these from your agent's repo (or have the agent run them):
 
 ```bash
-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
+npx @figs-so/cli@latest login                    # opens your browser to approve (the agent never sees a token)
+npx @figs-so/cli@latest workspaces               # find your workspace slug
+npx @figs-so/cli@latest init --workspace <slug>  # scaffolds .figs/ (identity + a charter template)
+# 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
 ```
 
-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`).
+That's it — your agent now shows up at **[app.figs.so](https://app.figs.so)**. No instrumentation, no
+SDK in your agent's code. From there you decide, deliberately, how much of its real work to surface.
+
+## How it works
+
+- **Local-first, one-way.** Your agent writes a small **`.figs/`** folder and runs `figs push`. Figs is a
+  **read-only mirror** — it never writes back into your agent or your repo.
+- **Two things only:** *structured state* (the agent's charter + its runs, asks, and artifacts) and
+  *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 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.
 
-## Commands
+### The CLI
+
+`@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 status [--json]` | login / workspace / agent state |
-| `figs login` | device-flow browser approve (or `figs login <token>`) |
-| `figs logout` | remove the locally-saved token (`~/.figs/credentials.json`) |
-| `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 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 doctor` | validate `.figs/` against the contract before pushing |
 | `figs push` | one-way publish of `.figs/` |
-| `figs version` | print version + check for updates |
-| `figs help [<command>]` | usage (bare `figs` shows it too) |
+| `figs status [--json]` | login / workspace / agent state |
+| `figs help [<command>]` | usage (`-h`/`--help` on any command; `-v` for version) |
+
+Override the endpoint for local dev with `FIGS_ENDPOINT` (e.g. `http://localhost:3000`).
+
+## What Figs is — and is NOT
+
+**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:**
+- ❌ **An agent / framework / orchestrator** — we wrap the dominant ones; we don't compete with them.
+- ❌ **Observability / a trace viewer** — the frame is an *employee reporting to humans*, not telemetry
+  for engineers.
+- ❌ **A control plane (yet)** — today it's one-way (report + hand off). Two-way (answer-down, sign-off) is
+  on the roadmap. To act on a handoff today, you still go to the agent's own console.
+
+> **Honest status:** Figs is **early** and in active dogfooding. Today's value is *visibility/legibility*
+> 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
+
+- **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 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 |
 
-Global: `-h` / `--help` on any command (or `figs help <command>`), `-v` / `--version` for the version. Unknown commands **and unknown flags** exit non-zero (no silent no-ops). Flags accept `--name value` or `--name=value`. Network calls time out after 30s.
+## Links
 
-Override the endpoint with `FIGS_ENDPOINT` (e.g. `http://localhost:3000` for local dev).
+- 🌐 Landing: **[figs.so](https://figs.so)**
+- 🖥️ App: **[app.figs.so](https://app.figs.so)**
+- 📦 CLI: **[@figs-so/cli](https://www.npmjs.com/package/@figs-so/cli)**
+- 📄 Protocol: **[`SPEC.md`](./SPEC.md)**

package/SPEC.md

@@ -0,0 +1,220 @@
+# The `.figs` Protocol — `figs-spec v1`
+
+> **Status:** v1 — minimal and stable. This spec defines the `.figs/` folder an AI agent writes and how
+> it is published. It is deliberately small: it describes *reporting* (agent → human), which is all v1
+> covers. Two-way (answers/sign-off flowing back to the agent) is **reserved for a future version** — see
+> [Reserved](#reserved-not-in-v1). Licensed **MIT** — implement it in anything.
+
+## 1. Design principles
+
+- **One-way.** An agent *publishes* its state. A Figs reader is a **read-only mirror** — it never writes
+  back into the agent or its repo.
+- **Local-first.** The agent owns a `.figs/` folder on disk. Publishing is an explicit act (`push`), not a
+  live connection.
+- **Upsert-only.** Publishing inserts or updates records by their `id`; it **never deletes** remote rows.
+  The remote is a durable record; the local folder is a transient outbox.
+- **Two content modes, no display language.** Everything is either *structured state* (JSON/JSONL we
+  describe below, rendered by fixed components) or a *rendered artifact* (a file shown in a sandboxed
+  viewer). There is no layout/templating DSL.
+- **Self-describing identity.** An agent generates its own UUID once; that UUID *is* its identity. The same
+  agent (a repo) may be run by many people; their pushes aggregate under that one identity.
+
+## 2. Folder layout
+
+```
+.figs/
+├── config.json        # identity + destination (committed, non-secret)
+├── agent.json         # the charter — who this agent is (committed)
+├── runs.jsonl         # activity log, one JSON object per line (outbox; gitignored)
+├── asks.jsonl         # things needing a human, one per line (outbox; gitignored)
+└── artifacts/         # files referenced by runs/asks (outbox; gitignored)
+```
+
+**Commit** `config.json` + `agent.json` (identity + charter). The activity files (`runs.jsonl`,
+`asks.jsonl`, `artifacts/`) are a transient outbox and are typically gitignored.
+
+## 3. `config.json` — identity + destination
+
+Non-secret. Pins one shared identity so many runners' pushes aggregate.
+
+| Field | Type | Notes |
+|---|---|---|
+| `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, 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*. 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. **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"`. |
+| `avatar` | `{ seed: string }` | | Seed for the generated avatar. |
+| `role` | string | | Short title, e.g. "Reconciliation Officer". |
+| `status` | string | | Free-text lifecycle, e.g. `in_dev`, `active`. |
+| `org` | `{ department?: string }` | | `department` groups the agent into an org-chart column. |
+| `runtime` | string | | What runs it, e.g. "Claude Code". |
+| `cadence` | string | | How often it runs, e.g. "Monthly". |
+| `mandate` | string | | One-paragraph statement of what it's responsible for. |
+| `steps` | string[] | | **Ordered** procedure (numbered render). For pipeline-shaped agents. |
+| `responsibilities` | string[] | | **Unordered** areas of work (bulleted render). For broad/mission agents. |
+| `properties` | `{ k, v }[]` | | Freeform catch-all for facts with no dedicated field. Keep keys short, values single-line. Don't duplicate first-class fields. |
+| `units` | `Unit[]` | | The instances/things the agent operates on (see below). |
+
+Use **`steps`** *or* **`responsibilities`** depending on shape — a fixed pipeline vs. a set of work areas.
+
+### 4.1 `Unit` — a thing the agent operates on
+
+| Field | Type | Req | Meaning |
+|---|---|:--:|---|
+| `id` | string | ✓ | Stable id (referenced by `runs`/`asks` via `unit`). |
+| `name` | string | ✓ | Display name. |
+| `subtitle` | string | | |
+| `status` | string | | Current one-line state. |
+| `period` | string | | The period in view, e.g. `2025-11`. |
+| `detail` | string | | |
+| `stats` | `{ l, v }[]` | | Labelled values (`l` = label, `v` = value). |
+
+## 5. `runs.jsonl` — activity
+
+One JSON object per line (JSON Lines). Each is something the agent did.
+
+| Field | Type | Req | Meaning |
+|---|---|:--:|---|
+| `id` | string | ✓ | Stable id (upsert key). |
+| `ts` | string (ISO-8601 w/ offset) | ✓ | When it ran, e.g. `2026-05-28T23:41:26Z`. |
+| `unit` | string | | The `Unit.id` this run is about. |
+| `period` | string | | |
+| `result` | string | | One-line outcome. |
+| `status` | `"ok"` \| `"warn"` \| `"fail"` | | Default `"ok"`. |
+| `artifact` | string | | File name under `artifacts/` to attach. |
+
+## 6. `asks.jsonl` — handoffs to a human
+
+One JSON object per line. Each is something the agent needs a person to resolve. **This is the handoff
+primitive** — the agent reached the edge of its autonomy.
+
+| Field | Type | Req | Meaning |
+|---|---|:--:|---|
+| `id` | string | ✓ | Stable id (upsert key). |
+| `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. |
+| `found` | string | | What the agent found / why it's stuck. |
+| `need` | string | | What it needs from the human. |
+| `options` | string[] | | Candidate resolutions. |
+| `details` | `{ l, v }[]` | | Labelled facts (e.g. amount at risk). |
+| `refs` | `{ label, artifact? }[]` | | Pointers to artifacts that back the ask. |
+| `ts` | string (ISO-8601 w/ offset) | | |
+
+> In v1, an ask is **one-way**: it announces that a human is needed. Resolution happens in the agent's own
+> workflow (the agent sets `status: "resolved"` on a later push). Answers flowing *back* through Figs are
+> [reserved for a future version](#reserved-not-in-v1).
+
+## 7. `artifacts/` — rendered files
+
+Files referenced by a run's `artifact` or an ask's `refs[].artifact`. Each is content-addressed (an
+unchanged file is skipped on publish).
+
+- **Supported kinds** (by extension): `html`, `markdown` (`.md`), `text` (`.txt`), `json`, and `image`
+  (`.png` `.jpg` `.gif` `.webp` `.svg`).
+- **Size:** keep each file **≤ ~3 MB** (compress images client-side if needed).
+- Artifacts are shown in a **sandboxed iframe** by the reader; an artifact cannot reach the host app.
+
+## 8. Publishing (the wire contract)
+
+`push` sends two things, authenticated by a per-user token in the `x-figs-token` header:
+
+1. **The spine** → `POST {endpoint}/api/ingest`, body:
+   ```jsonc
+   {
+     "workspaceId": "<uuid>",      // from config.json
+     "agent": { /* agent.json */ },
+     "runs":  [ /* runs.jsonl  */ ],   // optional
+     "asks":  [ /* asks.jsonl  */ ]    // optional
+   }
+   ```
+2. **Each referenced artifact** → `POST {endpoint}/api/artifacts/upload`, content base64-encoded (so
+   binaries survive), hash server-verified.
+
+The server upserts the agent by `id` and runs/asks by `id`; it never deletes. An agent **self-registers**
+on first push — there is no "create agent" step.
+
+## 9. Validation & versioning
+
+- A `.figs/` folder can be validated against this contract before publishing (`figs doctor` →
+  `POST {endpoint}/api/validate`). The shapes are the source of truth; readers reject malformed payloads.
+- **`figs-spec` is integer-versioned.** v1 is the current version. **Additive/optional** fields keep the
+  version number (an older `agent.json` still validates). The number is bumped only on a **breaking**
+  change. (Implementations report support via `GET {endpoint}/api/version`.)
+- v1 is intentionally minimal — it defines the smallest useful surface so we don't freeze the wrong
+  abstractions early. Extensions arrive as additive optional fields until a breaking change is unavoidable.
+
+## Reserved (not in v1)
+
+Deliberately out of scope for v1, named here so implementers don't repurpose these concepts:
+
+- **Two-way / answer-down.** A human answer or sign-off flowing *back* to the agent through Figs (vs. the
+  agent resolving in its own workflow). v1 is report-only.
+- **Provenance / signing.** Cryptographic attestation that a report is complete, fresh, and untampered.
+  v1 state is *self-reported*; treat it as visibility, not a tamper-evident audit trail.
+- **Per-record visibility / scoping.** v1 publishes to a workspace where all members can read everything.
+
+## 10. A complete example
+
+```jsonc
+// .figs/config.json
+{ "endpoint": "https://app.figs.so", "workspaceId": "…uuid…", "agentId": "…uuid…" }
+```
+
+```jsonc
+// .figs/agent.json   (no `id` here — `figs init` puts it in config.json; the CLI attaches it on push)
+{
+  "name": "Reconciliation",
+  "type": "agent",
+  "role": "Reconciliation Officer",
+  "status": "in_dev",
+  "avatar": { "seed": "Reconciliation" },
+  "org": { "department": "Finance Ops" },
+  "runtime": "Claude Code",
+  "cadence": "Monthly",
+  "mandate": "Reconciles open invoices every month — flags what doesn't match for review.",
+  "steps": [
+    "Pull our open invoices and the customer's statement for the month.",
+    "Match on PO / delivery-number keys within tolerance.",
+    "Classify every key — matched / needs-review / our-side-only / customer-only — with a 'why'.",
+    "Surface discrepancies. Never write back to the source."
+  ],
+  "properties": [
+    { "k": "Data sources", "v": "Stripe · NetSuite" },
+    { "k": "Escalation", "v": "#finance-ops" }
+  ],
+  "units": [
+    { "id": "acme", "name": "Acme Corp", "status": "88% matched · 31 keys flagged", "period": "2025-11",
+      "stats": [ { "l": "Matched", "v": "2,161 keys" }, { "l": "Needs review", "v": "31 keys" } ] }
+  ]
+}
+```
+
+```jsonc
+// .figs/runs.jsonl   (one object per line)
+{ "id": "acme-2025-11", "ts": "2026-05-28T23:41:26Z", "unit": "acme", "period": "2025-11", "result": "88% matched · 31 keys flagged", "status": "ok", "artifact": "acme-2025-11.html" }
+```
+
+```jsonc
+// .figs/asks.jsonl   (one object per line)
+{ "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.",
+  "options": [ "Strip the alpha prefix", "Use a mapping you provide", "Treat as out-of-scope" ],
+  "details": [ { "l": "Amount at risk", "v": "$50.0M" } ],
+  "refs": [ { "label": "Acme report", "artifact": "acme-2025-11.html" } ] }
+```

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,10 +35,16 @@ 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"
-
-const VERSION = "0.1.13"
+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
+// check, and the npm package in lockstep.
+const VERSION = JSON.parse(
+  readFileSync(new URL("./package.json", import.meta.url), "utf8"),
+).version
 // 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"
@@ -67,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",
@@ -80,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 lists your workspaces so you can re-run with the right one.",
+      "Never clobbers: an existing agent.json / CONTRACT.md / GUIDE.md / outbox is left exactly as-is.",
     ],
     eg: "figs init --workspace acme-corp",
   },
@@ -207,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")
@@ -228,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`)
   }
 }
 
@@ -306,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) {
@@ -320,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
@@ -510,18 +537,91 @@ 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 list the user's workspaces and have them re-run with one
+ *                    (the agent drives the choice — we never silently pick).
+ * 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)")
     }
@@ -531,12 +631,36 @@ 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 — list them so the agent can re-run.
+  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>\``)
+  }
+  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 })
@@ -544,48 +668,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 },
@@ -616,11 +779,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.13",
+  "version": "0.1.15",
   "description": "Figs CLI — publish your AI agent's state to Figs (figs.so). Run by the agent.",
   "type": "module",
   "bin": {
@@ -8,7 +8,9 @@
   },
   "files": [
     "figs.mjs",
-    "README.md"
+    "README.md",
+    "SPEC.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=18"
@@ -21,6 +23,13 @@
   ],
   "license": "MIT",
   "homepage": "https://figs.so",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/figs-so/figs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/figs-so/figs/issues"
+  },
   "publishConfig": {
     "access": "public"
   }