@figs-so/cli 0.1.2 → 0.1.3

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.3"
 // 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") {
@@ -263,40 +260,88 @@ async function status() {
   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 init() {
-  const workspaceId = flag("--workspace")
-  if (!workspaceId) {
-    die("usage: figs init --workspace <workspaceId> [--endpoint <url>]")
+function isUuid(s) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(
+    String(s),
+  )
+}
+
+/**
+ * The local `.figs/GUIDE.md` is a thin, endpoint-relative pointer — the full,
+ * always-current guide + `agent.json` schema is served at `${endpoint}/llms.txt`
+ * (one source, no frozen copy to drift). Just enough here to act.
+ */
+function guideStub(endpoint) {
+  return `<!-- Written by \`figs init\`. Full, always-current guide + schema: ${endpoint}/llms.txt -->
+# Figs — quickstart for this agent
+
+You are an AI employee. **Figs** is the read-only window your manager uses to see what you're
+responsible for, what you've done, and what you need from them. You publish to it; it never
+writes back into this repo.
+
+**Full guide + \`agent.json\` schema → ${endpoint}/llms.txt** — read this before authoring your charter.
+
+Lifecycle:
+  1. \`figs login\`                    a human approves in a browser — the token is theirs, never yours.
+  2. \`figs init --workspace <slug>\`  done — wrote config.json (your identity UUID) + this file.
+  3. author \`.figs/agent.json\`       derive it from this repo's 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):
+  append a line to runs.jsonl · record blockers in asks.jsonl · copy reports into artifacts/ · \`figs push\`.
+
+Commit config.json + agent.json (identity + charter). runs.jsonl / asks.jsonl / artifacts/ are a
+transient outbox — gitignored, aggregated remotely. The sync is one-way and never deletes on the server.
+`
+}
+
+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(
@@ -320,22 +365,14 @@ 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(
+    `        read .figs/GUIDE.md (full guide: ${endpoint}/llms.txt), author .figs/agent.json, then \`figs doctor\`.`,
   )
-  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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figs-so/cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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`.