figura-cli 0.13.1 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figura-cli",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "Command-line client for the Figura visualization SaaS",
   "license": "MIT",
   "type": "module",

package/skills/fig/SKILL.md

@@ -2,7 +2,7 @@
 name: fig
 description: "Mock up a screen as an on-brand, shareable HTML fig via your Figura team — render a UI state in seconds before writing the real code. Use when asked to visualize a screen, mock a UI, or 'make a fig'. iPhone-framed by default; browser frame for web/desktop."
 argument-hint: '<what to visualize>'
-allowed-tools: 'mcp__figura__figura_whoami, mcp__figura__figura_generate_fig, mcp__figura__figura_create_fig, Bash(figura *), Bash(bunx figura-cli *)'
+allowed-tools: 'mcp__figura__figura_whoami, mcp__figura__figura_generate_fig, mcp__figura__figura_create_fig, mcp__figura__figura_revise_fig, mcp__figura__figura_publish_fig, Bash(figura *), Bash(bunx figura-cli *)'
 ---
 
 # /fig — figure it out before you build it
@@ -65,30 +65,63 @@ greenfield.
 
 2. **Default — build it yourself, with YOUR Claude.** Fetch the team's design
    system — `bunx figura-cli brand --json` — and hand-build the fig's HTML against
-   it, then land it with **`figura_create_fig`** (`publish: true`), setting
+   it, then land it with **`figura_create_fig`**, setting
    `area`, `orientation` (`portrait` / `landscape` / `both`), `mode` (`single` /
    `compare` / `variations` — default to `compare` when Existing-first turned up a
    baseline), `title`, and a real description. This uses the
    caller's own Claude (the model running this skill) — no extra cost, full control
    for precise broken-vs-proposed diptychs — and applies the team's brand from the
    fetched design system. **Follow that design system verbatim; never invent brand
-   values.** `figura_create_fig` returns a shareable `figura.so/f/<id>` link.
+   values.**
+
+   **Landing IS hosting — leave `publish` unset.** Creating a fig always persists
+   it to Figura (there is no separate "save it for real" step); the response's
+   **`viewUrl`** is a link you can open right now, whether or not anyone has
+   decided to share it wider. Don't pass `publish: true` just to get something
+   viewable — that makes a first-draft iteration PUBLIC. Publishing is a
+   deliberate, later step (see step 5).
 
 3. **Server render — the user's call, never yours.** Figura can also render the
    fig server-side against the team brand: **`figura_generate_fig`** with a
-   natural-language brief (same `area` / `orientation` / `mode` / `title` /
-   `publish: true`). Use it only when the **user explicitly asks** for a server
-   render ("let Figura render it", headless/CI flows with no local model) — or
-   when you've offered both paths and they picked this one. It runs as an
-   **async job the tool polls for you** — expect ~30–90s before the landed fig
-   returns; don't re-call while one is in flight. Unlike the default path, this
-   **spends the team's Figura credits** (a `403` means no active subscription).
-   Pass **`fidelity: 'high'`** to render on the better model (the default
-   `'fast'` is lighter — fine for rough states, weaker on brand). Never pick
-   this path on your own to save effort: it costs credits and hand-built figs
-   track the brand better.
-
-4. **Review** the returned link, share it, move on.
+   natural-language brief (same `area` / `orientation` / `mode` / `title`, and
+   again leave `publish` unset by default). Use it only when the **user
+   explicitly asks** for a server render ("let Figura render it", headless/CI
+   flows with no local model) — or when you've offered both paths and they
+   picked this one. It runs as an **async job the tool polls for you** — expect
+   ~30–90s before the landed fig returns; don't re-call while one is in flight.
+   Unlike the default path, this **spends the team's Figura credits** (a `403`
+   means no active subscription). Pass **`fidelity: 'high'`** to render on the
+   better model (the default `'fast'` is lighter — fine for rough states, weaker
+   on brand). Never pick this path on your own to save effort: it costs credits
+   and hand-built figs track the brand better.
+
+4. **Open the HOSTED fig for approval — never a local file.** Run
+   `figura fig open <id>` (the id `figura_create_fig`/`figura_generate_fig` just
+   returned). It opens **`viewUrl`** in the reviewer's browser — the actual
+   Figura render (brand chrome, CSP, favicon, responsive frame), team-scoped so
+   any signed-in teammate can open it even though nothing was published. That's
+   what gets approved, and it's the exact page that ships once published — not a
+   `file://` reconstruction that can drift from it. No display reachable (a
+   headless/CI session)? Paste the printed `viewUrl` into the conversation
+   instead, or fall back to `figura fig open <id> --local` for a local sandboxed
+   HTML preview.
+
+5. **Iterate against the SAME fig, not a fresh one.** Changes from review go
+   through **`figura_revise_fig`** (`id`, the updated `html`) — it joins the
+   existing chain as a new version and returns a fresh `viewUrl`. Publishing is
+   NOT inherited automatically: a revision of an already-published fig still
+   lands unpublished by default (`viewUrl` is a team-scoped view, and the
+   existing public link keeps serving the OLD version) — pass `publish: true`
+   on the revise call itself if the fig is already live and the public link
+   needs to move to this version. Re-open it (`figura fig open <id>`) and
+   repeat until approved.
+
+6. **Approve, then share.** Once the human signs off AND wants a link people
+   outside the team can open, publish it explicitly —
+   **`figura_publish_fig`** (or `figura fig publish <id>`) — Figura's
+   `figura.so/f/<id>` share link. Team-only review never needed this; treat
+   publishing as a deliberate call the human makes, not something create/revise
+   does on its own.
 
 ## Presenting a redesign — overview ⇄ focus
 
@@ -124,8 +157,10 @@ CSS-only radio tabs, since figs carry no `<script>`:
   **deterministic**, project-scoped path — the repo's `.figura/figs/` (already
   gitignored), or `~/.figura/figs/` outside a bound repo — never `/tmp` or
   `mktemp`. A stable path means a rerun overwrites the same file instead of
-  littering volatile temp locations, and matches where `figura fig open` writes
-  (`<repo>/.figura/figs/figura-fig-<id>.html`).
+  littering volatile temp locations, and matches where `figura fig open --local`
+  writes (`<repo>/.figura/figs/figura-fig-<id>.html`) — this is YOUR headless
+  self-check copy, separate from the hosted `viewUrl` a human reviewer opens
+  (step 4 above).
 
 A **wipe-slider** stays the narrow tool for exactly two states of the same
 layout with pixel-level tweaks. Never ship a squeezed side-by-side as the
@@ -164,5 +199,12 @@ So when you **hand-build** a fig (the default path), do your part of the contrac
 - **MCP unavailable** (headless / cron, or no interactive auth): fall back to the
   CLI — `bunx figura-cli fig create` / `fig publish`, with `fig revise` /
   `fig revisions` for versions, and `bunx figura-cli brand --json` for the brand.
+- **`figura_create_fig`/`figura_revise_fig` itself fails** (no network, API down,
+  auth expired): the fig never entered Figura, so there is no `id`/`viewUrl` to
+  open. Only THEN write the HTML to a local scratch file (project-scoped —
+  `.figura/figs/`, never `/tmp`) and tell the user it's a local-only draft that
+  still needs landing once connectivity is back — this is the degraded fallback,
+  not the default path. Don't reach for it just because publishing felt like
+  an extra step; `figura_create_fig` hosts on the first call, every time.
 - **One job, one place.** Brand = the Figura brand profile. Generation = the Figura
   engine. This skill only decides *when* to fig and *which MCP call* to make.

package/skills/figura-brand/SKILL.md

@@ -48,13 +48,18 @@ Hunt across whatever stack this repo uses — do not assume one framework:
 - **Identity** — app/brand name + one-line description: `package.json` (name/description), `Info.plist` (`CFBundleName`), app-store copy, the README's first paragraph.
 - **Role/usage notes** — inline comments next to tokens often state the role
   (e.g. `// primary brand accent; record button`). Carry those into the tokens block.
+- **Product areas** — the app's own top-level sections, e.g. a tab bar, a
+  sidebar's nav items, or the router's top-level route folders (`app/(tabs)/*`,
+  `src/routes/*`, `src/screens/*`). These become `surfaces` — THIS product's
+  real areas ("Feed", "Checkout"), never a generic placeholder list and never
+  another product's areas.
 
 Use `Glob`/`Grep` to locate, `Read` to extract real values. Use the REAL hexes,
 fonts, and sizes from the repo — never invent them.
 
 ### 2. Synthesize the brand profile
 
-Produce three fields (see `reference/brand-format.md` for the exact tokensBlock shape):
+Produce four fields (see `reference/brand-format.md` for the exact tokensBlock shape):
 
 - **name** — the product/brand name.
 - **appDescription** — one clause: what it is + who it's for.
@@ -66,30 +71,40 @@ Produce three fields (see `reference/brand-format.md` for the exact tokensBlock
   - **Icon language** — SF Symbols / inline SVG / icon set the product uses; ban emoji if the brand does.
   - **Voice** — 3–5 short brand voice lines + a one-line tone rule, inferred from the docs/copy.
   - **Conventions** — any hard rules you found ("never use X", aspect ratios, chrome shape).
+- **surfaces** — THIS product's own key areas/sections, short labels (e.g.
+  `["Feed", "Profile", "Settings"]`), read from the real navigation/routes you
+  found in step 1. Drives the Studio Area picker. 3–10 is typical; skip
+  (leave unset) if the repo genuinely has no discoverable navigation — never
+  guess or reuse a generic/other-product list. Capped at 24 areas / 40
+  characters each.
 
 This synthesis IS the value — enrich the raw tokens with the roles, voice, and
 conventions you read from the repo. Keep it grounded in what's actually there.
 
 ### 3. Confirm, then push
 
-Show the user the synthesized `name`, `appDescription`, and the full `tokensBlock`,
-and confirm the target team (`figura whoami`). On approval:
+Show the user the synthesized `name`, `appDescription`, `surfaces`, and the full
+`tokensBlock`, and confirm the target team (`figura whoami`). On approval:
 
-- **MCP (preferred):** call `figura_set_brand` with `{ name, appDescription, tokensBlock }`.
-- **CLI fallback:** pipe the block over stdin —
+- **MCP (preferred):** call `figura_set_brand` with `{ name, appDescription, tokensBlock, surfaces }`.
+- **CLI fallback:** pipe the tokens block over stdin, pass surfaces as a flag —
   ```bash
-  cat <<'TOKENS' | figura brand set --name "<name>" --description "<one clause>" --tokens -
+  cat <<'TOKENS' | figura brand set --name "<name>" --description "<one clause>" --tokens - --surfaces "Feed,Profile,Settings"
   … the tokensBlock …
   TOKENS
   ```
   (Use `bunx figura-cli` in place of `figura` if it isn't on PATH.)
 
+A user can always add/rename/remove/reorder areas later on the brand page — this
+is a starting point, not a one-shot lock-in.
+
 ### 4. Verify
 
 `figura brand --json` (or the `figura_whoami` → `figura brand` read) → confirm
-`isCustom: true` and that the saved tokens match. The response also carries
-`platformProfile` — the engine auto-detects mobile / web / both from the tokens
-you just wrote (breakpoints, font stacks, safe-area/tab-bar tokens, hover
+`isCustom: true` and that the saved tokens AND `surfaces` match what you set.
+The response also carries `platformProfile` — the engine auto-detects mobile /
+web / both from the tokens you just wrote (breakpoints, font stacks,
+safe-area/tab-bar tokens, hover
 states — deterministic, no LLM) every time you save, so nothing extra to do
 here. It only ever changes on its own until the team explicitly overrides it
 on the brand page (Studio then defaults its device frame off that value —
@@ -99,5 +114,5 @@ suggest trying `/fig <a screen>` to see it render on-brand.
 ## Output
 
 Report the brand you set (name + a one-line summary of the palette/type/voice you
-captured) and confirm it's live for the team. Don't paste the entire tokensBlock
-again unless asked.
+captured, plus the surfaces list) and confirm it's live for the team. Don't
+paste the entire tokensBlock again unless asked.