figura-cli 0.22.0 → 0.23.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figura-cli",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "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_fig_scaffold, mcp__figura__figura_fig_devices, mcp__figura__figura_generate_fig, mcp__figura__figura_create_fig, mcp__figura__figura_revise_fig, mcp__figura__figura_publish_fig, mcp__figura__figura_commit_fig, Bash(figura *), Bash(bunx figura-cli *)'
+allowed-tools: 'mcp__figura__figura_whoami, mcp__figura__figura_fig_scaffold, mcp__figura__figura_fig_devices, mcp__figura__figura_list_figs, mcp__figura__figura_generate_fig, mcp__figura__figura_compose_fig, mcp__figura__figura_create_fig, mcp__figura__figura_revise_fig, mcp__figura__figura_publish_fig, mcp__figura__figura_commit_fig, mcp__figura__figura_request_feedback, Bash(figura *), Bash(bunx figura-cli *)'
 ---
 
 # /fig — figure it out before you build it
@@ -105,28 +105,57 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
      to the user verbatim (a one-line "figura-mcp is behind / below min — run …"),
      then proceed. It's a passive nudge, shown once per session — never a blocker.
 
-2. **Default — build it yourself, with YOUR Claude.** Fetch the **canonical
-   authoring scaffold** — **`figura_fig_scaffold`** (CLI:
-   `bunx figura-cli fig scaffold --platform <mobile|web> [--device <id>] [--area <str>]`)
-   — and hand-build the fig's HTML against 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.
-
-   The scaffold IS the source of truth: it's the **exact system prompt Figura
-   injects when it renders a fig server-side** — the design rules, exemplars,
-   accent hints, your team's composed brand, and the component/device kit
-   context, all in one. Follow it verbatim; never invent brand values or restate
-   design rules from memory. Match `--platform` to the target (a web fig's
-   scaffold composes the team's *web* brand surface, a mobile fig's the *mobile*
-   one). **Fallback if the scaffold fetch fails** (older engine/CLI, or the
-   `figura_fig_scaffold` tool is unavailable): fetch just the brand with
-   `bunx figura-cli brand --json` and author against that — the scaffold is the
-   preferred path, the raw brand is the degraded one.
-
-   **Landing IS hosting — leave `publish` and `commit` unset.** Creating a fig
+2. **Default — write the CONTENT, let Figura own the STRUCTURE.** Build device
+   figs with **`figura_compose_fig`**: you author only each **screen's CONTENT**
+   (the markup *inside* the phone); Figura owns the parts that used to drift — the
+   iPhone **frame** (bezel + Dynamic Island/notch + home bar), the **safe zone**,
+   the exact catalog **artboard geometry**, and the **composition** (grid /
+   diptych / overview). The frame/safe/device/composition can no longer be wrong:
+   they're sourced from the device catalog server-side, not hand-written, so the
+   chronic failures (a rolled-your-own artboard, a guessed `--fig-safe-top:59px`,
+   a forgotten `data-device`) are impossible by construction.
+
+   First fetch context — the **scaffold** (`figura_fig_scaffold`, CLI:
+   `bunx figura-cli fig scaffold --platform <mobile|web> [--area <str>]`) for the
+   brand tokens + design rules, and the **device catalog**
+   (`figura_fig_devices`) for the valid `device` ids. Then call
+   **`figura_compose_fig`** with:
+
+   - **`layout`** — `single` (one frame), `compare` (as-is → proposed diptych;
+     default this when Existing-first turned up a baseline — pass a `label` per
+     screen), `overview-focus` (**the one for arguing a redesign or several
+     candidate directions** — opens on the full-frame Focus toggle, Overview
+     grid behind the second tab), `variations` (a scan-only grid of states at
+     ~0.34 scale, NO toggle — only for a pure catalogue nobody has to read
+     detail in; never for a redesign argument), or `document` (NO device
+     framing — brand/overview figs).
+   - **`screens`** — an ARRAY. Each screen's **`html` is CONTENT ONLY**: the
+     markup that goes *inside* the phone. Do **NOT** draw a frame, bezel, status
+     bar, or safe padding; do **NOT** set `--fig-safe-*`; do **NOT** wrap it in
+     `.fig-device`. For every device layout each screen also carries the typed
+     intent Figura needs — **`device`** (a real catalog id from
+     `figura_fig_devices`, e.g. `iphone-16`), **`orientation`**
+     (`portrait`/`landscape`), and **`safeZone`** (`respect` = Figura pads your
+     content to the device's real safe insets; `ignore` = edge-to-edge for a
+     splash/hero). (`document` screens need none of these.)
+   - **`sharedCss`** — ONE stylesheet every screen shares: put your brand tokens
+     (from the scaffold) and shared content classes here. Per-screen one-offs go
+     in that screen's `css`.
+   - Plus `area`, `title`, `orientation`, and a real `description`.
+
+   This uses the caller's own Claude — no extra cost. Follow the scaffold's brand
+   values verbatim; never invent brand values or restate design rules from memory.
+   **Fallback if the scaffold fetch fails** (older engine/CLI): fetch just the
+   brand with `bunx figura-cli brand --json` and author your content styles
+   against that.
+
+   **`figura_create_fig` is the escape hatch** — reach for it only for a
+   `document`/exotic fig where you must hand-author the entire HTML (or when
+   `compose` is unavailable on an older engine). It takes a full `html` document
+   and you own the whole contract yourself. For any device fig, prefer
+   `compose` — it can't drift.
+
+   **Landing IS hosting — leave `publish` and `commit` unset.** Composing 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. It lands as a **workspace draft** —
@@ -137,15 +166,14 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
    on an exploration — committing is reserved for the session's final
    recommendation (step 7).
 
-   **Pass the fig markup INLINE as `html` — never a shell reference.** The `html`
-   argument to `figura_create_fig` / `figura_revise_fig` is the *full HTML
-   document itself*, passed directly as the value. An MCP tool argument is **not**
-   a shell: `$(cat "…/fig.html")`, a backtick `` `cat file` ``, any command
+   **Pass markup INLINE — never a shell reference.** The `html` (create) and each
+   screen's `html`/`css` + `sharedCss` (compose) arguments are the *strings
+   themselves*, passed directly as the value. An MCP tool argument is **not** a
+   shell: `$(cat "…/fig.html")`, a backtick `` `cat file` ``, any command
    substitution, or a bare file path will **not** expand — the literal string is
-   stored as the fig, producing a tiny black/empty canvas (the engine now rejects
-   this with a 400). If you authored the HTML in a scratch file to render/verify
-   it (step "Verify before publishing"), **read that file's contents** and pass
-   the contents as `html` — do not reference the path.
+   stored (a tiny black/empty canvas; the engine rejects a shell-ref create with
+   a 400). If you authored content in a scratch file, **read that file's
+   contents** and pass the contents — do not reference the path.
 
 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
@@ -222,27 +250,48 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
    `figura fig uncommit <id>`) returns it to a draft — the share link is
    untouched either way.
 
-## Presenting a redesign — overview ⇄ focus
+8. **Assign a reviewer.** Committing notifies the team in a digest — that is
+   ambient, not an assignment. If the fig argues a change or wants a decision,
+   finish by putting it in front of a named person with
+   **`figura_request_feedback`** (CLI: `figura fig request-feedback <id> --from
+   <name|email> --note <text>`). See "Assign a reviewer" below — this step is
+   what stops a fig from being landed, committed, and never actually read.
+
+## Presenting a redesign — FOCUS first, overview second
 
 When a fig argues a change against a current state (a shipped baseline, or
-several candidate directions), build one fig with **two switchable views** —
-plain CSS-only radio tabs for THIS specific toggle (it's binary, must survive
-truncation, and doesn't need a library):
-
-- **Overview — side by side.** Every state at once: the honest current state
-  first, then each variation, as scaled-down frames in a grid. Under each: a
-  status chip and ONE condensed context line (`+ / –`). This view is for
-  scanning and picking a direction, not for reading detail. The grid must
+several candidate directions), use **`figura_compose_fig` with
+`layout: 'overview-focus'`** — Figura emits the two switchable views (the
+CSS-only radio-tab Focus full-frame toggle ⇄ Overview grid) for you from your
+per-screen content. You supply each state's CONTENT + a `label`; the composition,
+the focus pills, the scaled overview grid, and the no-horizontal-scroll guarantee
+are server-owned. The design intent below still guides WHAT each state's content
+says and which is recommended — you just no longer hand-write the toggle markup
+or the frame scaling. (If you're on the `create` escape hatch instead, the same
+pattern must be hand-authored — plain CSS-only radio tabs, binary, no library:)
+
+**★ FOCUS IS THE DEFAULT VIEW.** The fig opens on ONE full-size frame with state
+pills — on desktop AND mobile. Overview is the *alternative*, behind the second
+tab. Never open a redesign fig on the scaled grid: `layout: 'variations'` (a
+scan-only grid at the kit's `--fig-scale:0.34`) is NOT a redesign presentation —
+using it for one shipped a 4-state fig as 134px phones with ~3px annotation
+chips. A Focus-only fig is **complete on its own**; add Overview only when there
+are enough states that scanning them at once genuinely helps.
+
+- **Focus — full frame (default).** One state at a time behind state pills
+  (Today / A / B / …), each state framed identically so flipping states in place
+  reads as spot-the-difference. This is where the context lives, pinned on the
+  frame as annotation chips: what's broken today, what each variation improves,
+  what it trades away. Open on the first pill = the honest current state.
+- **Overview — side by side (alternative).** Every state at once: the honest
+  current state first, then each variation, as scaled-down frames in a grid.
+  Under each: a status chip and ONE condensed context line (`+ / –`). This view
+  is for scanning and picking a direction, not for reading detail. The grid must
   wrap to one column before it can overflow — **a fig never scrolls
   horizontally**, at any viewport. To shrink the framed phones, wrap each in the
   kit's **`.fig-mini`** wrapper (see "Scaling a framed device" below), never a
   rule on `.fig-device` and never CSS `zoom` (zoom leaks an unzoomed
   `scrollWidth` into horizontal overflow — the exact thing this view forbids).
-- **Focus — full frame.** One state at a time behind state pills (Today / A /
-  B / …), each state framed identically so flipping states in place reads as
-  spot-the-difference. This is where the context lives, pinned on the frame
-  as annotation chips: what's broken today, what each variation improves,
-  what it trades away.
 - **In both views:** render the current state honestly from the shipped
   implementation — **reconstructed from source** per "Reconstruct the baseline
   from SOURCE" (no screenshot ⇒ study the component file(s) and rebuild the real
@@ -279,8 +328,8 @@ truncation, and doesn't need a library):
 
 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
-*only* view of desktop frames, and never a full-frame toggle as the only
-view of many variations — each is one half of the pair above.
+*only* view — a scan-only grid is never the whole argument. The reverse is
+NOT true: a Focus-only toggle is a complete fig, however many states it has.
 
 ## JavaScript is ALLOWED — use it for high-fidelity animation
 
@@ -321,6 +370,31 @@ Example — a GSAP-driven entrance for a mobile screen, pinned + allowlisted:
 </script>
 ```
 
+## Assign a reviewer — a proposal fig isn't done until someone's on it
+
+**A link nobody was pointed at is a fig nobody saw.** Landing, publishing, and
+committing all produce a URL; none of them puts the fig in front of a specific
+person. Committing notifies the team in a *digest*, which is ambient — it is not
+an assignment, and it is not a decision request.
+
+So after landing any fig that **argues a change or wants a decision**, send a
+feedback request as a required final step (step 8 above):
+
+- **MCP:** `figura_request_feedback` — the fig id, the teammate, and a one-line
+  note saying what to look at or decide.
+- **CLI:** `figura fig request-feedback <id> --from <name|email> [--note <text>]`
+  (use this when the MCP is bound to a different team than the fig — the CLI
+  reads the repo's `.figura/config.json`, the MCP may not).
+
+They get an in-app notification, a push, and an email, and the discussion lands
+in the fig's comment thread. **Name what you want from them** ("does 02 close
+#2375?") rather than "thoughts?" — a request with a question attached gets
+answered; a bare link gets deferred.
+
+Ask the user who should review only when it isn't obvious from context. Skip the
+request only for throwaway/exploratory figs, or when the user explicitly wants it
+private.
+
 ## Metadata & geometry — stamped for you
 
 Every landed fig is **auto-stamped server-side** (on `create` and `generate`)
@@ -336,8 +410,11 @@ with two things you do **not** hand-write:
   search and the self-improving loop. Artifact-descriptive only — no team/brand
   ids (the block is served on the public link).
 
-So when you **hand-build** a fig (the default path), you do your part of the
-contract — but the exact rules are **fetched, not restated here**: the
+With **`figura_compose_fig`** you do NOT hand-write any of the frame/safe/device
+contract below — Figura stamps it from your typed params. The rest of this
+section applies ONLY to the **`figura_create_fig` escape hatch**, where you
+hand-author the whole document: the exact rules are **fetched, not restated
+here** —  the
 presentation model (frameless single vs canvas composition), when to emit or
 omit the whole-fig `<meta name="figura:artboard">`, the `.fig-device` /
 `data-device` frame markup (Figura stamps the bezel, Dynamic Island, and

package/skills/skills.json

@@ -0,0 +1,7 @@
+{
+  "$comment": "Skill version manifest (#752) — the source of truth for each Figura skill's OWN version line, DECOUPLED from the figura-cli package version. A release bumps the version here when a skill's content changes, then regenerates the engine seed (bun packages/core/scripts/build-skill-seed.mjs) and re-seeds. Version is a date tag (YYYY.MM.DD[.n]); releasedAt is ISO-8601. The CLI/MCP stamp this version into .figura-version at install; the engine seeds the registry from it.",
+  "skills": {
+    "fig": { "version": "2026.07.28", "releasedAt": "2026-07-28T00:00:00.000Z" },
+    "figura-brand": { "version": "2026.07.26", "releasedAt": "2026-07-26T00:00:00.000Z" }
+  }
+}