figura-cli 0.25.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figura-cli",
-  "version": "0.25.0",
+  "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_upload_asset, 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
@@ -62,6 +62,20 @@ something in a vacuum — and end up rebuilding what already ships. So every tim
   `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
 proposal is better, it must be argued against what's there — that's the whole
@@ -178,7 +192,9 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
    - **`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`,
@@ -280,7 +296,8 @@ so you hand it the studied structure in the brief (see step 3, "Server render").
    `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). Publishing is
+   (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`
@@ -317,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
 
@@ -339,6 +358,27 @@ 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: what's broken
@@ -374,6 +414,21 @@ are enough states that scanning them at once genuinely helps.
   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
@@ -387,8 +442,8 @@ are enough states that scanning them at once genuinely helps.
   (`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; mark the recommended variation and
-  close with a short "my read" arguing the pick against the others. Keep the
+  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
@@ -479,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

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.
 

package/skills/figura-brand/reference/brand-format.md

@@ -8,21 +8,41 @@ so it can't drift). This page is only orientation + one worked example.
 
 Two halves:
 - **`identity`** — the SHARED brand (same on every platform): `colors`
-  (`[{ name, hex, role?, meaning? }]`), `gradient?`, `type?`
-  (`{ families?: { slot: fontName }, ramp?: number[], rules? }`), `spacing?`,
-  `radius?`, `voice?` (`{ nouns?, promise?, lines?, tone? }`), `forbidden?`
-  (`[{ id?, rule }]`).
+  (`[{ name, hex, role?, meaning? }]`), `gradient?`,
+  `signature?` (`{ kind: "solid" | "gradient" | "iridescent", stops?: hex[] }`),
+  `type?` (`{ families?: { slot: fontName }, ramp?: number[], rules? }`), `spacing?`,
+  `radius?`, `voice?` (`{ nouns?, promise?, lines?, tone? }`), `locales?`
+  (`[{ tag, script, direction, fonts?: { display?, body?, mono? } }]` — the
+  languages the product ships: BCP-47 `tag` ("en", "ar", "ckb"), ISO 15924
+  `script` ("Latn", "Arab"), `direction` `ltr`|`rtl`; the FIRST entry is the
+  default; per-locale `fonts` override the shared type families for that
+  script), `forbidden?` (`[{ id?, rule }]`).
+
+  `signature` is the brand page's hero treatment. The rule: **solid unless the
+  repo's tokens define a gradient identity** — a signature gradient named in the
+  design system, not a stray mention of the word (a "avoid gradients" guardrail is
+  a solid brand). `gradient`/`iridescent` require 2–5 `stops` (the gradient's own
+  hexes, in order). Omit the field entirely for a plain solid-accent brand.
 - **`platforms`** — a map keyed by `mobile` / `web` / `desktop`. Include ONLY the
   platforms the product targets. Each surface: `components?` (`[{ name, spec }]`),
   `icons?`, `layout?`, `surfaces?` (this product's real areas), `bans?`,
   `tokensBlock?` (the prose ESCAPE HATCH for guidance that genuinely doesn't fit a
-  structured field — use sparingly).
+  structured field — use sparingly). `mobile` also takes `os?` (`"ios"` |
+  `"android"`), which drives the fig's device frame and OS chrome geometry;
+  unset means iOS. `os` on `web`/`desktop` is rejected.
 
 Validation the schema enforces (a violation is a 400 at `PUT /brand`): **strict
 keys** (an unknown/misspelled key is rejected); **hex** = `#` + exactly 3/4/6/8
 digits; **no blank** array entries; platform keys exactly `mobile`/`web`/`desktop`;
-caps on array lengths + string lengths (the fetched schema carries the exact
-numbers). Author against the fetched schema, not these prose notes.
+`locales` when present needs >= 1 entry with unique tags; caps on array lengths +
+string lengths (the fetched schema carries the exact numbers). Author against the
+fetched schema, not these prose notes.
+
+Locales drive fig generation: the scaffold states them, `fig create --locale ar`
+(or the `locale` param on `figura_create_fig`/`figura_revise_fig`) stamps
+`<html lang dir>` and loads a per-script font — a family that does not cover the
+script (Inter has no Arabic) resolves to a recorded fallback instead of a silent
+browser substitute.
 
 ## Worked example — a web/desktop brand ("Ledgerline")
 
@@ -36,6 +56,7 @@ numbers). Author against the fetched schema, not these prose notes.
       { "name": "Ink", "hex": "#101312", "role": "ground", "meaning": "near-black base background" }
     ],
     "gradient": "linear-gradient(90deg, #1F6F54, #C9A227)",
+    "signature": { "kind": "gradient", "stops": ["#1F6F54", "#C9A227"] },
     "type": {
       "families": { "display": "Fraunces", "body": "Inter", "mono": "JetBrains Mono" },
       "ramp": [12, 14, 16, 18, 20, 24, 30, 36, 48],
@@ -43,6 +64,10 @@ numbers). Author against the fetched schema, not these prose notes.
     },
     "spacing": [4, 8, 12, 16, 20, 24, 32, 40, 48, 64],
     "radius": [4, 8, 12, 999],
+    "locales": [
+      { "tag": "en", "script": "Latn", "direction": "ltr" },
+      { "tag": "ar", "script": "Arab", "direction": "rtl", "fonts": { "body": "IBM Plex Sans Arabic" } }
+    ],
     "voice": {
       "nouns": ["ledger", "balance", "month-end"],
       "promise": "Books, balanced.",

package/skills/skills.json

@@ -1,13 +1,13 @@
 {
-  "$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.",
+  "$comment": "Skill version manifest (#752) \u2014 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.08.11.1",
-      "releasedAt": "2026-08-11T17:35:23.364Z"
+      "version": "2026.08.27",
+      "releasedAt": "2026-08-27T00:00:00.000Z"
     },
     "figura-brand": {
-      "version": "2026.07.26",
-      "releasedAt": "2026-07-26T00:00:00.000Z"
+      "version": "2026.08.25.2",
+      "releasedAt": "2026-08-26T00:00:00.000Z"
     }
   }
 }