figura-cli 0.24.1 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figura-cli",
-  "version": "0.24.1",
+  "version": "0.26.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_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 *)'
+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_upload_asset, mcp__figura__figura_publish_fig, mcp__figura__figura_commit_fig, mcp__figura__figura_merge_figs, mcp__figura__figura_request_feedback, Bash(figura *), Bash(bunx figura-cli *)'
 ---
 
 # /fig — figure it out before you build it
@@ -19,6 +19,28 @@ place (your team's Figura brand profile) and is injected server-side. That is th
 whole point: a fig is on-brand *by construction*, and this skill can never drift
 from your brand. To change the brand, use the `figura-brand` skill, not this one.
 
+## Hard rules — read before anything else
+
+1. **When you author the markup, a phone fig ⇒ `figura_compose_fig`. Always.
+   No exceptions.** The phone is the only frame the composer builds, and every
+   framed phone screen goes through it. **Web/desktop (browser frame) ⇒
+   `figura_create_fig`**, following the scaffold's `--platform web` frame
+   contract verbatim — markup only, the scaffold owns the CSS.
+   **Tablet has no authoring path** (#869): say so and stop.
+   (`figura_generate_fig` authors nothing locally — step 3 governs it.)
+2. **The frame is Figura's, never yours.** Bezel, notch/Dynamic Island, status
+   bar, home bar, safe insets, artboard geometry and scale are server-owned.
+   You author screen CONTENT only.
+3. **`figura_create_fig` is for web/`document`/exotic figs only.** Never for a
+   phone fig — this is a rule, not a preference. No `compose` on this engine? Say
+   so and stop; the caller upgrades. A hand-framed phone is not the fallback.
+4. **Self-check before you land a phone fig.** Search your own markup for these;
+   any hit means you drew the frame — discard it and rebuild via
+   `figura_compose_fig`:
+   `.fig-device` wrapper · `--fig-safe-*` · notch / Dynamic Island / bezel /
+   home-bar elements · a status-bar row · a phone-shaped `border-radius`
+   container · a hand-written device width/height.
+
 ## When to use
 
 - Asked to mock a screen, visualize a UI state, or "make a fig".
@@ -37,8 +59,22 @@ something in a vacuum — and end up rebuilding what already ships. So every tim
   matching route). If a real implementation exists, **Read it** and treat it as the
   baseline you must show.
 - **Check the team's figs** — `figura fig list --area <area>` (or
-  `figura_list_figs`). If a fig of this screen already exists, **`fig revise` it**
-  (a new version in the same chain), never a fresh duplicate.
+  `figura_list_figs`). If a fig of this screen already exists, **iterate that
+  fig** (step 5), never a fresh duplicate.
+
+★ **The chain is the unit — and Figura now enforces it.** A create that looks
+like the next round of an open question is **refused** (409 `similar_chain`) and
+the response names the chain to revise. That is not an obstacle to route around:
+each round you land as its own fig is a card in the library nobody can walk, and
+a reviewer who opens round 4 sees neither rounds 1–3 nor the discussion held on
+them. Revise the named fig. `new: true` (CLI `--new`) exists for a genuinely
+different question — not for "revising felt like more work".
+
+**Already forked it?** `figura_merge_figs` (CLI `figura fig merge <id> --into
+<id>`) folds the sibling back in: its versions append after the destination's
+head, share links keep resolving, verdicts and decisions follow. Run it with
+`dry_run` first to see the plan. Merging your own fork mid-session is normal
+housekeeping, not an admission of anything.
 
 If any prior design exists → build in **`mode: compare`** and render it as
 **existing (as-is) → proposed**, grounded in the real current state. Even when the
@@ -105,7 +141,7 @@ 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 — write the CONTENT, let Figura own the STRUCTURE.** Build device
+2. **Default — write the CONTENT, let Figura own the STRUCTURE.** Build phone
    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**,
@@ -130,18 +166,35 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
      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
+     markup that goes *inside* the phone (hard rule 2). 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.)
+   - **`childFig`** (instead of that screen's `html`) — compose the frame BY
+     REFERENCE: the id of an existing fig composed with `kind: 'child'`, which
+     Figura embeds in its own iframe. `single` and `compare` only. Reach for it
+     when two screens fight over the same CSS (each child's styles are sealed in
+     its own document and cannot reach the frame or the other screen), or when a
+     screen deserves its own versions, reactions and comments. Compose each child
+     first, then pass their ids, and give the screen the SAME `device` and
+     `orientation` the child was composed with — the frame draws that phone's
+     chrome around the child's own safe-area guides, so a mismatch is refused.
+     The reference is PINNED: a later revision of a child does not change a
+     composition that already exists. A composed-by-reference parent is revised
+     by **typed screens, never by HTML** — see step 5. Publishing the parent is
+     what makes its children reachable at the public link; a child fig has no
+     share link of its own. A referenced screen still takes `notes` on `compare`
+     — the rail and its pins are the parent's markup, so they never reach into
+     the child.
    - **`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`.
+   - Plus `area`, `title`, `orientation`, and a real `description` — the fig's
+     BRIEF, and the reviewer's only view of the thread. Contract: "The brief"
+     below.
 
    **Small screens are the SERVER's job — with one exception that is yours.**
    Below a catalog-derived breakpoint every multi-frame layout (`compare`,
@@ -162,11 +215,11 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
    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.
+   **The other path — `figura_create_fig`** (hard rule 3): a full `html` document
+   you hand-author, for a web/`document`/exotic fig. Fetch the scaffold for the
+   platform (`--platform web` for a browser frame) and follow its frame contract
+   verbatim; the chrome CSS is stamped at save, so author the markup and none of
+   its styles.
 
    **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);
@@ -220,19 +273,31 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
    only the served bytes can tell a working fig from one that renders as empty
    phones. It exits non-zero if a frame class shipped unsized — fix and re-land
    before a human sees it. Then 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 fig open <id>` (the id the landing call 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
+   instead — there is no local-preview fallback; a fig is only viewed on
+   figura.so.
+
+5. **Iterate against the SAME fig, not a fresh one.** On the create path, 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`.
+   **A COMPOSED fig revises by typed screens**: call `figura_revise_fig` with
+   `layout` + `screens` (the same shape compose takes) instead of `html`, and it
+   re-composes into the same chain. Every child reference is carried forward with
+   its pin, label, notes and position; an empty screen `{}` keeps a REFERENCED
+   slot exactly as it was, so changing one side of a by-reference diptych is
+   `screens: [{}, {…}]`. A slot that held INLINE `html` must have its html sent
+   again — Figura never reads content back out of a composed document. Passing
+   `html` for a composed fig is refused (422) — it would leave the references
+   behind. `figura_get_fig` returns the fig's `children` when you need to see the
+   current composition. Never hand-author the framed document to feed `revise`
+   (hard rule 1). A revision takes its own `description` — restate the arc
+   there; whoever reads v4 did not read v1. 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`
@@ -255,9 +320,9 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
    the team (digest-batched) — so at the end of the session, commit exactly
    the fig the user asked for / the final agreed version, and nothing else.
    Explorations, rejected variants, and intermediate iterations STAY drafts.
-   If the deliverable is the fig you're about to create/revise anyway, prefer
-   `commit: true` on that final `figura_create_fig` / `figura_revise_fig`
-   call (CLI: `--commit`) over a separate call; otherwise commit it afterwards
+   If the deliverable is the fig you're about to land anyway, prefer
+   `commit: true` on that final landing call (CLI: `--commit`) over a separate
+   call; otherwise commit it afterwards
    with **`figura_commit_fig`** (CLI: `figura fig commit <id>`). Committed the
    wrong one? `figura_commit_fig` with `uncommit: true` (CLI:
    `figura fig uncommit <id>`) returns it to a draft — the share link is
@@ -269,6 +334,8 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
    **`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.
+   The note names the decision; the fig's `description` carries the context —
+   check it against "The brief" below *before* you send the ask.
 
 ## Presenting a redesign — FOCUS first, overview second
 
@@ -280,8 +347,8 @@ 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:)
+or the frame scaling. (On the `create` path — a web fig — the same pattern is
+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
@@ -291,41 +358,102 @@ 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.
 
+**★ THE LAST PILL IS YOUR READ — a fig that shows options must pick one.**
+Whenever a fig carries more than one *direction* (A / B / …, or any "which way
+do we go" set), the FINAL state is a **verdict state**, not one more variation:
+the options weighed against each other, and one of them named as the pick.
+Without it a reviewer gets a gallery and no argument, and the decision lands back
+on whoever opened the link — which is the exact thing a fig exists to prevent.
+
+The verdict state is one framed screen like any other, labelled `My read`, and
+it carries, tersely:
+
+- **the pick, named in the first line** — "Go with A" — never "both have merit";
+- **one line per option** of what it wins and what it costs (`+` / `–`) — the
+  same pairs the Overview chips carry, so the two views can't disagree;
+- **the deciding reason**: the one constraint that broke the tie (a component
+  that already ships, a cap, a rule the others violate);
+- **what would change your mind**, when the pick is close.
+
+Two states of the SAME direction (a before/after, one layout at two
+orientations) need no verdict — there is nothing to weigh. Three directions and
+no verdict pill is an unfinished fig.
+
 - **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.
-- **Never put annotation chips inside a clipping box.** `position:absolute`
-  cannot escape an ancestor's `overflow:hidden`, so a chip that straddles a
-  rounded-corner frame ships sliced. Hang chips off a positioned wrapper as
-  siblings of the frame, anchored to grow away from its edge.
+  reads as spot-the-difference. This is where the context lives: what's broken
+  today, what each variation improves, what it trades away. Open on the first
+  pill = the honest current state.
+- **★ Annotation NEVER goes on the design — pass `notes`, don't draw chips.**
+  A note written into a screen's `html` lands inside the phone screen, on top of
+  the layout the fig exists to let someone judge. Measured on a shipped fig
+  (`fig_wjgcksh38pix`): 3–4 absolutely-positioned chips per state, every one 100%
+  inside the screen box, together covering **12–19% of the artboard** — sitting
+  on the masonry grid and hero row that were the whole question — while the page
+  around the frame was empty black. So annotation is **data, not markup**: give
+  each screen a `notes` array on `figura_compose_fig` and Figura renders a rail
+  **beside** the frame, with only a ~20px numbered pin on the artboard (~0.3%
+  coverage). Nothing to toggle: the layout and the argument are both fully
+  visible at every viewport, and below the restructure breakpoint the rail
+  stacks under the frame automatically.
+
+  ```jsonc
+  "notes": [
+    // `at` is percent on the SCREEN → a numbered pin there, note N in the rail.
+    { "kind": "broken",   "text": "Hero is score-picked, so it lands mid-row and manufactures a second full-width row (#2755).", "at": { "x": 34, "y": 52 } },
+    { "kind": "improved", "text": "A run IS a collection — a name is always attached.", "at": { "x": 91, "y": 14 } },
+    // No `at` → a point about the state as a whole. Numbered, no pin.
+    { "kind": "tradeoff", "text": "Costs the shipped vertical-advance gesture." }
+  ]
+  ```
+
+  `kind` is `broken` | `improved` | `tradeoff` | `detail` (default `detail`), max 8
+  notes a screen, and `compose` **rejects** notes on `single`/`variations`/
+  `document` — those layouts have no rail, and silently dropping a note drops
+  the argument. If you're hand-authoring via `figura_create_fig` instead, the
+  same rule holds by hand: the rail is a **sibling of the frame**, never a
+  descendant of the clipped `.fig-screen`, and nothing but a pin sits on the
+  design.
+- **Every direction gets the SAME treatment.** If one direction is shown in a
+  second orientation, a second state, or a second breakpoint, they ALL are.
+  A subset argues from unequal evidence and quietly favours whichever direction
+  got the extra look: one fig shipped `Today ↻` and `A ↻` pills while B and
+  Fresh had no landscape frame at all, so two directions were judged turned and
+  two were judged only upright. **Cover the orientations the product actually
+  ships** — on an app that is landscape-native, that means portrait AND
+  landscape for every direction, by default, not as an extra. Narrow to one
+  orientation only when the work itself is scoped to one: a portrait-only bug,
+  or a conversation already about the turn, doesn't need its opposite.
+- **A pill label is plain TEXT.** `label` is a text field, not markup — write
+  the character (`·`, `↻`, `—`), never an HTML entity. The same call carries
+  each screen's `html`, where `&middot;` is exactly right, so the habit crosses
+  over easily; the composer decodes an entity it finds in a label rather than
+  shipping it literally, but the label still means text.
 - **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).
+  horizontally**, at any viewport. Frame scaling is the server's (hard rule 2).
 - **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
-  layout, don't approximate); color-code chips by function (broken / improved /
-  trade-off / detail) using the team's status colors from the fetched design
-  system; mark the recommended variation and close with a short "my read"
-  arguing the pick against the others. Keep the chrome around the frames
-  minimal — the frames are the content; no legends (chips label themselves),
-  no repeated context, fluid `max-width` layout throughout.
+  layout, don't approximate); classify every note by function via its `kind`
+  (`broken` / `improved` / `tradeoff` / `detail`) rather
+  than hand-picking colors — the rail and its pins take the team's status colors
+  from the design system, and a `sharedCss` override of `--fig-note-improved` and
+  friends re-points all of them at once; and mark the recommended direction in
+  both — the pick the verdict state argues for wears its chip here too. Keep the
+  chrome around the frames minimal — the frames are the content; no legends
+  (notes label themselves), no repeated context, fluid `max-width` throughout.
 - **Verify the SERVED fig, not your local draft.** The component kit (device
   frame, status bar, control bar) is stamped **server-side at save** — it does
   **not** exist in the HTML you authored locally, so a headless render of your
   own file shows *unstyled, empty* frames whether or not the fig is actually
   correct. A local screenshot is structurally blind to the most common way a
   framed fig breaks. So verify the fig that actually ships:
-  1. **Land it first** (`figura_create_fig` / `figura_revise_fig`), then dump
-     the stamped bytes: `figura fig open <id> --local --print`. This is the
+  1. **Land it first**, then dump
+     the stamped bytes: `figura fig open <id> --print`. This is the
      served document, kit and all.
   2. **Assert the kit stamped — `figura fig verify <id>`.** One command, and it
      **exits non-zero** if any frame class your markup uses shipped with no CSS
@@ -341,15 +469,26 @@ are enough states that scanning them at once genuinely helps.
      repo's `.figura/figs/` (gitignored), or `~/.figura/figs/` outside a bound
      repo, never `/tmp`/`mktemp`), and render it at a few viewport widths.
      `document.scrollWidth` must equal the viewport in every view and state
-     (sideways scroll = broken), no annotation chip may cover the content it
-     annotates, and no chip may be cut by a clipping ancestor: walk each chip's
-     ancestors up to `<html>` and, wherever computed `overflow` is
-     `hidden`/`clip`, assert the chip's rect stays inside that ancestor's box —
-     the viewport box for `<body>`/`<html>`, whose overflow propagates there.
-     Comparing a chip to the frame's rect alone misses the vertical escape, and
-     no rect test sees a rounded clip, which is why the authoring rule above is
-     the real guarantee. `figura fig open <id> --local` writes the same served
-     bytes to `<repo>/.figura/figs/figura-fig-<id>.html`.
+     (sideways scroll = broken), and **measure how much of the artboard the
+     annotation covers**: sum the intersection of every annotation element with
+     the `.fig-screen` box and divide by its area. With `notes` that number is
+     the pins alone (~0.3%); anything in the double digits means chips got drawn
+     into the design again. Also assert nothing is cut by a clipping ancestor:
+     walk each element's ancestors up to `<html>` and, wherever computed
+     `overflow` is `hidden`/`clip`, assert its rect stays inside that ancestor's
+     box — the viewport box for `<body>`/`<html>`, whose overflow propagates
+     there. Comparing to the frame's rect alone misses the vertical escape, and
+     no rect test sees a rounded clip, which is why keeping the rail a sibling
+     of the frame is the real guarantee. `figura fig open <id> --print` is where
+     those served bytes come from.
+
+  **A fig composed BY REFERENCE has no printable bytes.** Its screens are served
+  per request, so `--print` refuses (non-zero) and names the hosted URL: the
+  stored document is references, not a render. Verify it by opening that URL —
+  `figura fig open <id>` — and screenshotting the hosted page. Steps 1 and 3
+  above assume printable bytes and do not apply; `figura fig verify <id>` still
+  reports on the parent's own markup. Its `notes` rail and pins are the
+  PARENT's markup, so they render and measure the same way.
 
 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
@@ -395,6 +534,54 @@ Example — a GSAP-driven entrance for a mobile screen, pinned + allowlisted:
 </script>
 ```
 
+## The brief — what the reviewer reads before your fig
+
+**`description` is the fig's BRIEF, not a caption.** Figura renders it as the
+**Brief** panel beside the fig, above the discussion: it is the first thing the
+person you assign in step 8 reads, and across a multi-round exercise it is the
+only place the *thread* survives — each round lands as its own fig, and nothing
+in the product links them. The fig argues THIS round. The brief carries what
+happened before it.
+
+★ **Four beats, in this order.**
+
+1. **The objective, in the user's own words.** Quote the sentence that started
+   the exercise, verbatim — and re-quote it in every later round. It is the
+   standard the fig gets judged against, and the first thing to evaporate when a
+   round is written from memory.
+2. **The arc — one line per prior round: what it tried, and what it settled or
+   killed.** Name each round so the reviewer can go and find it.
+3. **What is still open** — the question this round does *not* close.
+4. **The pick, and the decision you want back.**
+
+★ **An abandoned direction stays in the brief, with the reason it was
+abandoned.** "Withdrawn", "superseded", "we tried that" are deletions, not
+summaries. A dead route is the most useful thing a reviewer can be handed: it
+stops them re-proposing it, and it is usually where the unresolved tension is
+still sitting. And when a round was killed by *evidence* — a real user rejected
+it, a constraint bit, a measurement came back — that evidence outranks every
+design argument in the brief, and has to survive into the next round's.
+
+★ **Never write a later round's brief from session memory.** Before composing a
+fig that continues, supersedes, or replaces an earlier one, read the earlier
+briefs — `figura_list_revisions` for the chain you're revising, or
+`figura_list_figs` (by `area`/`tag`) then `figura_get_fig` — and carry the
+objective and the arc forward. A long session compresses; the brief must
+not. The prior fig is on the server, so this costs one call and never depends on
+what is still in your context.
+
+**Which field is which.** `description` is the brief, on every write path
+(`figura_compose_fig` / `figura_create_fig` / `figura_revise_fig` /
+`figura_update_fig`), and it is carried per version — so **a revision restates
+the arc** instead of assuming the reader saw v1. Cap: 2000 characters. `prompt`
+is a different field: the raw brief/instruction you were handed, kept for
+provenance. `intent` (the `figura:context` meta) is a one-line design intent for
+search and is **truncated at 400 characters** — never park the objective there.
+
+**The brief is not the fig.** Don't narrate what the frames already show. If the
+brief and the fig disagree about the recommendation, one of them is stale — fix
+it before you send the ask.
+
 ## 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
@@ -422,7 +609,7 @@ private.
 
 ## Metadata & geometry — stamped for you
 
-Every landed fig is **auto-stamped server-side** (on `create` and `generate`)
+Every landed fig is **auto-stamped server-side** (`compose`, `create`, `generate`)
 with two things you do **not** hand-write:
 
 - A **device kit** `<style>` — the target's hard geometry as CSS custom
@@ -435,53 +622,26 @@ 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).
 
-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
-safe-area insets **before** your `<style>`, so you normally leave those classes
-alone — if you do style one, your rule wins by cascade and the frame still
-works; to shrink a frame use the `.fig-mini` wrapper, never a hand-written
-`.fig-device` width/height/transform), the `figura:context` / `figura:feature`
-metas, and the valid devices all live in the canonical scaffold.
-
-**Scaling a framed device — use `.fig-mini`, never a rule on `.fig-device`.**
-An overview grid needs shrunken frames, and the obvious way to write that is a
-CSS rule on the injected class. Don't: your rule wins over the kit, so the frame
-stops matching real device geometry — and `zoom` is worse, it leaks the unzoomed
-width into scrollable overflow. The kit ships the wrapper instead:
-
-```html
-<div class="fig-mini" style="--fig-scale:.34">
-  <div class="fig-device portrait" data-device="iphone-16">
-    <div class="fig-screen">…</div><div class="fig-di"></div><div class="fig-homebar"></div>
-  </div>
-</div>
-```
-
-`.fig-mini` scales its device with `transform` and takes the **scaled** layout
-box, so a row of minis lays out at its visual size instead of reserving
-full-size phones. Add `landscape` to the device (or the wrapper) and the box
-flips with it. `--fig-scale` defaults to `.34`; set it per element.
+The rest of this section applies ONLY to the **`figura_create_fig`** path (hard
+rule 3), where you hand-author the whole document: the exact rules are
+**fetched, not restated here** — the presentation model, the browser frame
+contract, the `figura:artboard` / `figura:context` / `figura:feature` metas all
+live in the canonical scaffold.
 
 - **`figura_fig_scaffold`** (CLI: `figura fig scaffold`) is authoritative for the
   presentation model, the frame markup, and the output contract. Fetch it and
   follow it verbatim (step 2 above) — do NOT restate design/format rules from
   memory. A bundled skill can pin stale; the scaffold is always current.
-- **`figura_fig_devices`** (CLI: `figura fig devices`) is the full valid-
-  `data-device` catalog — every framed-device id + its geometry (logical dims,
-  safe-area insets, cutout, corner radius). Pick a real id from it for a canvas
-  composition's `<div class="fig-device" data-device="…">`; an unknown id
-  silently gets no frame.
+- **`figura_fig_devices`** (CLI: `figura fig devices`) is the catalog `compose`
+  validates against — pick each screen's **`device`** id from it (an unknown id
+  is a 400).
 
 ## Notes
 
-- **MCP unavailable** (headless / cron, or no interactive auth): fall back to the
-  CLI — `bunx figura-cli fig create` / `fig publish`, with `fig revise` /
+- **MCP unavailable** (headless / cron, or no interactive auth): the CLI has no
+  `compose`, so a phone fig has no CLI path — say so and stop (hard rule 3). For
+  a web/`document` fig fall back to
+  `bunx figura-cli fig create` / `fig publish`, with `fig revise` /
   `fig revisions` for versions, `fig commit` / `fig uncommit` (or `--commit` on
   the final create/revise) for the team library, `bunx figura-cli fig scaffold`
   for the authoring scaffold, and `bunx figura-cli brand --json` for the raw

package/skills/figura-brand/SKILL.md

@@ -71,10 +71,47 @@ Hunt across whatever stack this repo uses — do not assume one framework:
   `src/routes/*`, `src/screens/*`). These become each platform's `surfaces[]` —
   THIS product's real areas ("Feed", "Checkout"), never a generic placeholder
   list and never another product's.
+- **Locales** — which languages the product ships, their script and direction.
+  Run `figura brand detect-locales [path]`: an offline scan returning
+  `locales` (paste-ready `identity.locales`), `evidence` (why each locale got its
+  script/direction), `needsConfirmation`, and the `signals` it fired on. Put the
+  DEFAULT language first.
+
+  Three rules, each from a real miss on a real repo (#998):
+
+  - **NEVER list a vendor directory's languages.** `node_modules`, `Pods`,
+    `dist`, `build`, `.next`, `out`, `vendor`, `DerivedData`, `.git`, `.claude`
+    are not this product. A React Native monorepo's `node_modules` alone carries
+    40+ `*.lproj` languages; listing them makes the brand claim languages the
+    product does not ship. `detect-locales` drops them itself — if you scan by
+    hand instead, exclude every one of those path segments.
+  - **Script and direction come from the message TEXT, not the tag.** A repo can
+    tag Sorani Kurdish `ku`, which any tag table calls Latin/LTR — SHA7N's
+    `locale/ku/general.json` is 4848 Arabic codepoints. Read the locale's message
+    files and judge from the characters. Arabic script plus any of ڕ ڵ ێ ۆ is
+    Sorani → emit the tag **`ckb`** (that is the tag the per-script font
+    resolver's Sorani coverage check keys on; `ku` would let a font missing those
+    letters through), not `ar` and not `ku`.
+  - **Ambiguous tags are a question, not a guess.** `ku ks pa sd az uz tk ha ber
+    mn` are each written in more than one script depending on region or
+    orthography. With message content, classify from it. Without, they arrive in
+    `needsConfirmation` — ASK the user which script that language uses in this
+    product, and do not paste the locale until they answer.
+
+  Show the user the `evidence` line for each locale alongside the JSON, so a
+  wrong call is visible rather than silent.
+
+  Manual signals if the CLI is unavailable: i18n deps in `package.json`
+  (`next-intl`, `react-i18next`, `i18next`, `@lingui/*`, `vue-i18n`), an i18n
+  config's `locales: [...]` array, `locale/*` / `locales/*.json` /
+  `messages/*.json` dirs, `dir="rtl"` in markup, iOS `*.lproj/` dirs +
+  `Localizable.strings`, Android `values-ar/strings.xml`.
 - **Which platform(s)** — detect the target platform(s) so you only emit the
   surfaces that apply:
   - `mobile` — an iOS/Android/React-Native/Expo app (`*.xcodeproj`, `Info.plist`,
     `android/`, `app.json`/Expo, SF Symbols usage, safe-area/tab-bar tokens).
+    Note WHICH OS it targets — an `android/` + Gradle + Material repo is
+    `os: "android"`, an `*.xcodeproj`/SwiftUI repo is `os: "ios"`.
   - `web` — a web app / site (`index.html`, a web router, CSS media queries,
     hover states, a `tailwind.config`).
   - `desktop` — an Electron/Tauri/native-desktop shell.
@@ -93,14 +130,22 @@ EXACTLY (strict keys, hex 3/4/6/8 digits, no blank array entries, only
 
 - **name** — the product/brand name (still required on the write).
 - **identity** — the SHARED brand: `colors` (real palette, each
-  `{ name, hex, role?, meaning? }`), `gradient` (if any), `type`
+  `{ name, hex, role?, meaning? }`), `gradient` (if any), `signature`
+  (`{ kind: solid|gradient|iridescent, stops?: hex[] }` — solid unless the repo's
+  tokens define a gradient identity; see `reference/brand-format.md`), `type`
   (`{ families, ramp, rules }`), `spacing`, `radius`, `voice`
-  (`{ nouns, promise, lines, tone }`), `forbidden` (hard guardrails as
-  `[{ id?, rule }]`).
+  (`{ nouns, promise, lines, tone }`), `locales` (each
+  `{ tag, script, direction, fonts? }` — BCP-47 tag, ISO 15924 script,
+  `ltr`/`rtl`; FIRST entry is the default; per-locale `fonts` override the
+  shared families for that script, e.g. an Arabic display face), `forbidden`
+  (hard guardrails as `[{ id?, rule }]`).
 - **platforms** — a map with a key ONLY for each platform you detected in step 1.
   Each surface: `components` (signature components as `[{ name, spec }]`), `icons`
   (the platform's icon language), `layout` (its frame/shell law), `surfaces` (this
-  product's real areas), `bans` (platform-specific don'ts). Use the per-platform
+  product's real areas), `bans` (platform-specific don'ts). `mobile` ALSO takes
+  `os` (`"ios"` | `"android"`) — set it when the repo names its OS; it drives the
+  fig's device frame, system-bar heights, back affordance, and corner radii.
+  Omit it for an iOS/cross-platform repo (iOS is the default). Use the per-platform
   **`tokensBlock`** escape-hatch ONLY for guidance that genuinely doesn't fit a
   structured field — prefer a structured field.