@agent-native/core 0.92.12 → 0.94.0

package/corpus/templates/design/.agents/skills/capture-learnings/SKILL.md

@@ -11,11 +11,14 @@ metadata:
 
 # Capture Learnings
 
-This is background knowledge, not a slash command. **Your memory index is loaded at the start of every conversation.** Use `save-memory` proactively when you learn something worth remembering.
+This is background knowledge, not a slash command. **Organization learnings and your personal memory index are loaded at the start of every conversation, including Slack/integration turns.** Capture durable context proactively when you learn something worth remembering.
 
 ## How to Read & Write Memories
 
-Memories are stored as **resources** in the SQL database (personal scope), not as files on disk.
+Memories are stored as **resources** in the SQL database, not as files on disk.
+
+- **Team/organization knowledge:** shared `LEARNINGS.md`. Read it first, merge the new fact, then write the full updated file with the `resources` tool using `scope: "shared"`. Shared scope resolves to the active organization; it must never leak to another organization in the same deployment.
+- **Personal knowledge:** `memory/MEMORY.md` plus `memory/<name>.md`, written with `save-memory`.
 
 - **Save a memory:** `save-memory --name <name> --type <type> --description "..." --content "..."`
 - **Read a memory:** `resource-read --path memory/<name>.md`
@@ -33,6 +36,14 @@ Memories are stored as **resources** in the SQL database (personal scope), not a
 
 ## When to Capture
 
+### Team and organization knowledge (`LEARNINGS.md`, shared scope)
+- Canonical destinations and workflows (for example, which Content database receives a type of Slack request)
+- Required intake fields, ownership, prioritization conventions, metric definitions, and approved terminology
+- Durable external references that the whole team needs, including the canonical page/database URL
+- Corrections or decisions that should affect every organization member's future Slack and app conversations
+
+Store the fact and a concise provenance link when available. Do not paste full private conversations, customer data, credentials, or secrets into learnings. Put stable always-on policy in shared `AGENTS.md`; put learned facts and evolving conventions in shared `LEARNINGS.md`.
+
 ### User Preferences & Memory (`user`)
 - **Tone and style** — "I prefer casual tone", "don't use emojis", "keep replies short"
 - **Personal context** — contacts, relationships, habits ("my wife's email is...", "I'm in PST timezone")
@@ -58,19 +69,21 @@ Memories are stored as **resources** in the SQL database (personal scope), not a
 - Things obvious from reading the code
 - Standard language/framework behavior
 - Temporary debugging notes
-- Anything already in AGENTS.md or skills
+- Anything already in AGENTS.md, shared LEARNINGS.md, or skills
 - Ephemeral task details (use tasks/plans instead)
 
 ## Key Rules
 
-1. **Save proactively — don't ask permission.** When you learn something, save it immediately.
-2. **One memory per topic** — e.g. `coding-style`, `project-alpha`, not one giant dump
-3. **Read before updating** — if a memory exists, read it first and merge, don't overwrite
-4. **Keep descriptions concise** — the index is loaded every conversation
-5. **Memories are SQL-backed** — safe for personal info, persist across sessions, not in git
+1. **Save proactively — don't ask permission.** When you learn something durable, save it immediately at the correct scope.
+2. **Choose scope by audience.** Organization workflow or reference → shared `LEARNINGS.md`; one person's preference/context → personal memory.
+3. **One memory per topic** — e.g. `coding-style`, `project-alpha`, not one giant dump
+4. **Read before updating** — if a memory exists, read it first and merge, don't overwrite
+5. **Keep descriptions concise** — the index is loaded every conversation
+6. **Memories are SQL-backed** — they persist across sessions and are not in git; still minimize sensitive content
 
 ## Graduation
 
 When a memory is referenced repeatedly, it may belong in AGENTS.md or a skill:
-- Saving a memory is lightweight (auto-apply, personal scope)
+- Saving a personal memory is lightweight (auto-apply, personal scope)
+- Shared LEARNINGS.md is the lightweight organization knowledge layer
 - Updating AGENTS.md or a skill is heavier (affects all users/agents)

package/corpus/templates/design/.agents/skills/design-generation/SKILL.md

@@ -278,6 +278,32 @@ pnpm action generate-design \
 
 Always pass `canvasFrames` with an explicit `width`/`height` matching the form-factor answer (mobile ≈ 390×844, tablet ≈ 768×1024, desktop ≈ 1440×1024 as above) — a screen saved without a placement falls back to a generic default that won't match a desktop-intended design. For multiple screens generated together, call `generate-screens` first and pass `deviceType` (`"mobile"` / `"tablet"` / `"desktop"`) per screen; it returns the matching `canvasFrame` to forward to each `generate-design` call.
 
+#### Non-web sizes — ad units, print one-pagers, social sizes
+
+`canvasFrames` accepts any exact `width`/`height` in px, so "create a 300x250
+ad" style requests work the same way — no special action, just the pixel
+dimensions the artifact actually needs. The editor's own Frame tool preset
+list (`app/components/design/inspector/frame-size-presets.ts`) documents the
+canonical sizes to reuse instead of guessing:
+
+- **Ad units (IAB standard)**: Medium Rectangle 300×250, Leaderboard 728×90,
+  Wide Skyscraper 160×600, Mobile Leaderboard 320×50, Billboard 970×250.
+- **Print (96dpi CSS px, matching this app's PNG/PDF export unit)**: US
+  Letter 816×1056, A4 794×1123, A5 559×794, Tabloid 1056×1632. Design print
+  one-pagers with real multi-column layout, tables, and a footer — a
+  fixed-size print artifact has no responsive fallback, so lay out the exact
+  canvas once. The editor's Download PDF export renders these at a
+  print-quality floor (2x raster, ~192dpi) regardless of the export panel's
+  default scale setting.
+- **Social**: Instagram Post 1080×1080, Instagram Story 1080×1920, X Post
+  1200×675, Facebook Cover 820×312, LinkedIn Cover 1584×396.
+
+At small ad-unit sizes (320×50, 160×600), text commonly runs 9-11px — smaller
+than this skill's general 16px body-text floor — because there is no room to
+reflow. That is expected for these formats; it stays legible in @2x+ exports
+since the export scale multiplies raster resolution, not the authored CSS
+size. Avoid dense multi-line copy at these sizes regardless.
+
 ### Phase 4 — Always ship tweaks with the design
 
 `generate-design` accepts a `--tweaks` array — pass 3-6 of the most impactful knobs bound to CSS custom properties the design's `:root` block actually defines. Surface controls users will actually want to adjust (accent color, density, radius, dark-mode toggle, font choice). Don't ship a generic preset; let the design's structure pick the knobs.

package/corpus/templates/design/.agents/skills/design-systems/SKILL.md

@@ -119,6 +119,25 @@ fingerprint.
 
 If this is the user's first design system, it is automatically set as the default.
 
+### Starting from an established public system
+
+Use the curated production templates instead of recreating familiar systems
+from memory:
+
+```bash
+pnpm action create-design-system --templateId material-3
+pnpm action create-design-system --templateId carbon-white
+pnpm action create-design-system --templateId primer-light
+```
+
+Each template is a source-linked, versioned snapshot with real semantic tokens,
+type scales, spacing, shapes, CSS variables, state guidance, attribution, and
+brand-misrepresentation guardrails. The action may accept a custom `title`,
+`description`, or additional `customInstructions`, but it intentionally rejects
+`data` overrides when `templateId` is present so the named snapshot cannot
+silently become a lookalike. Use `get-design-system` after creation when the
+full stored snapshot is needed.
+
 ### Reading a Design System
 
 ```bash
@@ -229,10 +248,27 @@ notes, then pass that summary to `index-design-system-with-builder` as an
 uploaded text context file. Do not build a local design system from the Figma
 summary unless the user explicitly asks for a manual local fallback.
 
-**When the user uploads a raw `.fig` file**, send it to Builder design-system
-indexing through the setup page upload route. Do not parse `.fig` files locally
-and do not call `create-design-system` from raw `.fig` output; Builder owns the
-indexed brand kit, generated docs, and usage guidance.
+**When the user uploads a raw `.fig` file on the Design System Setup page**,
+send it to Builder design-system indexing through the setup page upload route.
+Do not parse `.fig` files locally for this flow and do not call
+`create-design-system` from raw `.fig` output; Builder owns the indexed brand
+kit, generated docs, and usage guidance. This is unchanged and is specifically
+about **token/brand-kit extraction**.
+
+**When the user uploads a raw `.fig` file in the Design editor's Import panel**
+(not Design System Setup), it takes a different, narrower path: the server
+decodes the container/Kiwi document locally (`fig-file-decoder.ts`) and maps
+its `NodeChange` tree to editable HTML screens (`fig-file-to-html.ts`,
+`fig-file-import.ts`) through the same `saveImportedDesignFiles` path as other
+Design imports — no Builder connection required. This is explicitly scoped to
+**screens only**, not tokens: it does not create or update a design system, and
+it is separate from (and does not reopen) the Design System Setup `.fig`
+upload above. Treat it as experimental — the `.fig` container is a proprietary,
+undocumented format, so unsupported node types, geometry, or schema variants
+fail closed with an explicit warning/placeholder rather than a silent
+approximation. Read the returned `fidelityReport` (`stats`, `warnings`) back to
+the user, and see `FIGMA_INTEROPERABILITY.md`'s "`.fig` upload" row for the
+current fidelity contract and required verification corpus.
 
 **When the user wants a Figma Assets-style native component drawer inside
 Design**, do not use Figma or media assets. Use `list-design-native-assets` to
@@ -298,11 +334,11 @@ copied frame **link** carry fundamentally different information:
 
 - **A copied frame link** (`?node-id=...`) names an exact node. Always exact —
   use `import-figma-frame`.
-- **A plain clipboard paste** only carries Figma's `figmeta` marker, which is
-  `{fileKey, pasteID, dataType}` — **no node id at all**, and `pasteID` is an
-  ephemeral, server-side identifier that the public REST API can't resolve
-  back to a node. So a clipboard paste can only ever get an exact node import
-  on a **best-effort match**, never a guarantee.
+- **A current Figma clipboard paste** carries `figmeta.selectedNodeData`; each
+  comma-separated entry begins with the exact REST node id. Design imports
+  those selected nodes directly, including multi-selection. This field is not
+  a public Figma contract, so older or future clipboard formats may still need
+  the conservative matching fallback below.
 
 The canvas paste listener (`app/lib/figma-clipboard.ts` +
 `import-figma-clipboard`) handles this automatically:
@@ -312,10 +348,10 @@ The canvas paste listener (`app/lib/figma-clipboard.ts` +
    `import-figma-clipboard` (figmeta present) or the legacy
    `import-design-source` HTML path (no figmeta — not a Figma paste, or an
    older Figma client that doesn't emit the marker).
-2. `import-figma-clipboard` fetches the file's shallow structure (top-level
-   frames + their direct children, `server/lib/figma-node-import.ts`'s
-   `fetchFileStructure(fileKey, 3)`) and heuristically matches it against the
-   pasted content's visible text (`server/lib/figma-clipboard-match.ts`):
+2. When `selectedNodeData` is present, `import-figma-clipboard` fetches those
+   exact node ids immediately. Otherwise it fetches the file's shallow
+   structure and heuristically matches it against pasted visible text
+   (`server/lib/figma-clipboard-match.ts`):
    a frame is only imported when its **name** or at least **two distinct
    text-layer contents** appear verbatim in the paste. Anything ambiguous or
    unmatched imports **nothing structural** — it never guesses and never
@@ -330,9 +366,63 @@ The canvas paste listener (`app/lib/figma-clipboard.ts` +
    both cases: connect the Figma access token, or paste a frame **link**
    instead for a guaranteed-exact import.
 
-Tell users who want guaranteed pixel-exact imports to copy a frame **link**
-("Copy link to selection" in Figma), not just Cmd+C — a plain paste is
-convenient but only best-effort.
+Tell users who need a path based only on Figma's public contract to copy a
+frame **link** ("Copy link to selection" in Figma). Current Cmd+C is exact
+when `selectedNodeData` is present, with conservative fallback if it changes.
+
+### Reading a Figma file/frame without importing it
+
+**When the user just asks a question about a Figma file/frame** ("what's in
+this file?", "what's in this frame?", "show me a screenshot of this Figma
+frame", "what components/instances does it use?") — do not call
+`import-figma-frame` just to inspect it; that persists a new Design screen.
+Use `get-figma-design-context` instead, the chat equivalent of the official
+Figma MCP's `get_metadata` + `get_design_context` for this app:
+
+```bash
+# No nodeId: lists pages and top-level frames (like get_metadata with no node id)
+pnpm action get-figma-design-context --figmaUrl "https://www.figma.com/design/<fileKey>/<name>"
+# A specific frame/node: full structural summary + screenshot
+pnpm action get-figma-design-context --figmaUrl "https://www.figma.com/design/<fileKey>/<name>?node-id=<id>"
+```
+
+- **Overview mode** (no `nodeId`, none parsed from the URL) returns the file's
+  pages and each page's top-level frames (id, name, type, child count) so the
+  agent can pick a frame before drilling in — mirrors the official MCP's
+  `get_metadata` behavior when called with no node id.
+- **Node mode** (a `nodeId`, or a link with `?node-id=`) returns a
+  depth-limited, size-capped tree (`depth`/`maxNodes` args) describing box
+  geometry, fills/strokes/effects/corner-radii (including per-corner arrays),
+  auto-layout, text/style (font, case, decoration, line-height), and
+  component/instance identity (`isComponent`/`isInstance`/`componentId`) for
+  every visible descendant — plus a rendered screenshot URL by default
+  (`includeScreenshot: false` to skip it). It never writes anything; use
+  `import-figma-frame` afterward if the user wants the frame brought in as a
+  real, editable screen.
+- This also answers "what components does this file use?" for **local,
+  unpublished** components/instances that never show up in
+  `list-figma-library-assets` — that action's REST source
+  (`/files/:key/components`) only returns components **published to a team
+  library**, not every `COMPONENT`/`INSTANCE` node in the file. Use
+  `get-figma-design-context` for "what components exist in this file/frame",
+  and `list-figma-library-assets` + `insert-figma-library-asset` for "insert a
+  reusable library component". The screenshot URL `get-figma-design-context`
+  returns for a component/instance node can be passed straight to
+  `insert-figma-library-asset` as `renderUrl` even when the component isn't
+  published.
+- For Figma **variables** ("what tokens/variables does this file define?"),
+  give an honest answer instead of guessing: the REST Variables API is
+  Enterprise-plan-gated, so `get-figma-design-context`'s summary of a node's
+  own paints only shows resolved colors, not variable bindings, and
+  `get-figma-styles` only covers the file's published FILL/TEXT/EFFECT/GRID
+  **Styles** (a separate, non-Enterprise feature) — neither is the Variables
+  API. If the user has Enterprise access and a connected Figma MCP with
+  `get_variable_defs`, call that directly for real variable definitions and
+  pass the result to `index-design-system-with-builder`. Otherwise, tell the
+  user variables need Enterprise access or a connected Figma MCP, and offer
+  Styles (`get-figma-styles`) or a manual `import-design-tokens` /
+  `apply-design-token-edit` pass as the available fallback — do not claim to
+  have enumerated variables from a plain `FIGMA_ACCESS_TOKEN`.
 
 ### Source: Brand Analysis (combines website + notes)
 

package/corpus/templates/design/AGENTS.md

@@ -16,13 +16,19 @@ patterns live in `.agents/skills/`.
 - Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Use the app actions for designs, files, versions, design systems, variants,
   export, and sharing. Do not write design rows directly with SQL.
-- Treat repository import actions as shortcuts, not capability limits. When the
-  exact GitHub endpoint, search query, request body, pagination mode, metadata
-  field, or API version matters, use `provider-api-catalog`,
-  `provider-api-docs`, and `provider-api-request` against the real GitHub API.
-  The provider API resolves auth from the saved `GITHUB_TOKEN` secret and never
-  exposes the token value. For large scans, stage results with `stageAs` and
-  analyze them with `query-staged-dataset`.
+- When a user wants an established public system as a starting point, call
+  `create-design-system` with `templateId: material-3`, `carbon-white`, or
+  `primer-light`. These are source-linked, versioned token snapshots with
+  system-specific generation guidance; preserve that data instead of
+  reconstructing a lookalike palette.
+- Treat provider-specific actions as shortcuts, not capability limits. Use
+  `provider-api-catalog`, `provider-api-docs`, and `provider-api-request` for
+  open-ended GitHub and Figma API questions. Auth resolves from the saved,
+  user-scoped `GITHUB_TOKEN` or `FIGMA_ACCESS_TOKEN` and never exposes secret
+  values. Stage large reads with `stageAs` and analyze them through
+  `query-staged-dataset`. Figma REST can read files, nodes, components, styles,
+  images, comments, versions, and Enterprise variables, but it cannot create
+  arbitrary canvas layers; non-read Figma requests require human approval.
 - In dev, call actions with `pnpm action <name>`; in production, call the native
   tool. The action schema is the source of truth for parameters.
 - Call `view-screen` before editing a specific design if the current design or
@@ -64,20 +70,53 @@ patterns live in `.agents/skills/`.
   `insert-figma-library-asset`, preserving `fileKey`, `nodeId`, `componentKey`,
   `sourceUrl`, and the rendered URL. This path requires the saved
   `FIGMA_ACCESS_TOKEN` secret; never ask the user to paste that token into chat
-  or pass it as an action parameter. Figma styles and variables are design-system
-  inputs, not draggable media assets; route full file/design-system extraction
-  through Builder-backed indexing.
+  or pass it as an action parameter. Token setup needs `current_user:read` for
+  validation and `file_content:read` for frame/node import; add library or
+  Enterprise variable scopes only when needed. Figma styles and variables are
+  design-system inputs, not draggable media assets; route reusable system
+  extraction through Builder-backed indexing.
 - To import a Figma frame/screen as a real, editable Design screen (not a
   rendered image), use `import-figma-frame` with a `figmaUrl` (or
-  `fileKey`/`nodeId`) — it maps position, auto-layout, text, fills/gradients,
-  strokes, corner radii, effects, opacity, and blend modes pixel-accurately,
-  falling back to an exact PNG only for vector networks/boolean ops/unsupported
-  node types, and saves the result as a new screen. Read the returned
+  `fileKey`/`nodeId`) — it maps supported position, auto-layout, text,
+  fills/gradients, strokes, corner radii, effects, opacity, and blend modes,
+  falling back to a rendered PNG for masks, vector/boolean geometry,
+  lines/arcs, advanced strokes/text, transformed image crops, and unsupported
+  node types, then saves the result as a new screen. Read the returned
   `fidelityReport` (`approximated`, `imageFallbacks`) back to the user when
   non-trivial. Use `get-figma-styles` for a file's published style names (not
   the Enterprise Variables API; full token extraction still routes through
-  Builder-backed indexing). See the `design-systems` skill's "Import from
-  Figma" section.
+  Builder-backed indexing). Never claim universal lossless import/export:
+  consult `FIGMA_INTEROPERABILITY.md` for the feature-level fidelity contract,
+  fallback rules, scale limits, and real-file golden corpus. See the
+  `design-systems` skill's "Import from Figma" section.
+- Uploading a raw `.fig` file in the Design editor's Import panel decodes the
+  container/Kiwi document locally into editable screens — no Builder
+  connection needed — and is scoped to screens only; it never creates or
+  updates a design system. This is separate from uploading `.fig` on the
+  Design System Setup page, which still indexes tokens/brand-kit data through
+  Builder and does not parse `.fig` locally. See the `design-systems` skill
+  for both paths.
+- A current Figma Cmd+C clipboard includes exact selected node ids in
+  `figmeta.selectedNodeData`; `import-figma-clipboard` uses those before any
+  heuristic matching and supports multi-selection. Clipboard metadata is not a
+  public Figma contract, so a copied frame link remains the stable exact path
+  if Figma changes that field. Without a token, current Figma's binary-only
+  clipboard has no browser-readable HTML fallback; give setup guidance instead
+  of claiming a successful import.
+- For "what's in this Figma file/frame?" or "show me a screenshot of this
+  frame" without importing anything, use `get-figma-design-context` — no
+  `nodeId` lists pages/top-level frames (like the official Figma MCP's
+  `get_metadata`), a `nodeId`/node-id link returns a depth-limited structural
+  summary (box, fills/strokes/effects, auto-layout, text/style,
+  component/instance identity) plus a rendered screenshot URL. It never
+  creates a screen; use `import-figma-frame` for that. It also surfaces local,
+  unpublished components/instances that `list-figma-library-assets` cannot see
+  (that action's REST source only returns library-published components). For
+  variables, `get-figma-design-context` and `get-figma-styles` are honest
+  fallbacks, not the Enterprise Variables API — say so plainly rather than
+  guessing when no connected Figma MCP/Enterprise access is available. See the
+  `design-systems` skill's "Reading a Figma file/frame without importing"
+  section.
 - Use Alpine.js and Tailwind CDN for interactive prototypes. Prefer Alpine
   directives over raw inline event handlers.
 - Navigate between prototype screens with Alpine state (`x-show`), a
@@ -88,6 +127,17 @@ patterns live in `.agents/skills/`.
   `generate-design` for new files. For broad rewrites of an existing selected
   file, use `edit-design` with `mode: "replace-file"` and the exact `fileId`;
   never resend files you aren't changing.
+- For reusable starting points, call `list-design-templates`. Use
+  `save-design-as-template` to snapshot an editable inline design, including
+  its screens, canvas dimensions, defaults, and locked layers. Use
+  `create-design-from-template` to instantiate a normal design. If the user
+  supplies a prompt, call `get-design-snapshot` once and refine the copied
+  files with `edit-design`; never regenerate the template from scratch.
+- Treat `data-agent-native-locked="true"` as an authoritative template
+  boundary. Locked backgrounds, logos, and their descendants must remain
+  byte-for-byte unchanged during agent edits. The server rejects attempts to
+  change or remove them; ask the user to unlock the layer in the Layers panel
+  if they explicitly want it changed.
 - When the user asks to add tweak controls, preserve existing useful tweaks,
   add or update the requested `tweaks` definitions, and make sure each control
   is backed by a CSS custom property the rendered file actually uses. If source
@@ -110,7 +160,8 @@ patterns live in `.agents/skills/`.
   explicit user instructions in the current turn still win.
 - For reusable design-system setup from Figma, connected code/GitHub, local
   code/design files, or optional `design.md`, use Builder-backed DSI indexing
-  through `index-design-system-with-builder` or `import-file --format fig`.
+  through `index-design-system-with-builder` or the Design System Setup `.fig`
+  upload.
   Pass readable `design.md` content as `designMd`, use the returned local design
   system id in Design flows, and call `get-design-system` before generation to
   hydrate Builder docs/tokens when available. Do not create a duplicate local
@@ -140,7 +191,7 @@ patterns live in `.agents/skills/`.
   the work involves multiple screens or artboard placement. Overview is the
   primary editing surface: users can select screens, move/resize/drop static
   frames and canvas primitives, edit layers in place, and use the frame's
-  full-view button to enter focused editing.
+  Interact button to enter focused editing.
 - To move the user's editor, call `navigate` with `view: "editor"` and
   `editorView: "overview"` for the screen overview, or `editorView: "single"`
   plus `fileId`, `filename`, or `screen` to focus one screen.
@@ -306,6 +357,8 @@ patterns live in `.agents/skills/`.
   frame new edits target. Breakpoint frames are one document with a
   Framer-style cascade (base = widest frame; narrower-frame edits persist as
   width-scoped overrides via `apply-visual-edit` + `activeFrameWidthPx`).
+  `set-active-breakpoint.editScope` is `cascade-smaller` by default; use
+  `only` when the user explicitly wants a bounded, breakpoint-only override.
   Read the `responsive-breakpoints` skill before responsive edits.
 - **Design states**: `create-design-state`, `apply-design-state`,
   `capture-design-state`, `list-design-states`, and `delete-design-state`
@@ -323,6 +376,14 @@ patterns live in `.agents/skills/`.
   `detach-component-instance` to turn an instance into plain editable markup.
   See the `design-generation` skill's "Component reuse" section — promote a
   3+ times repeated pattern instead of inventing another near-duplicate.
+- **Suggested auto layout**: for an absolute/freeform container, first measure
+  its direct children and present the proposed direction, visual order, gap,
+  four-side padding, alignment, and sizing. Do not mutate source until the user
+  applies the preview. Inline HTML/Alpine applies the reviewed proposal through
+  one `apply-visual-edit`-backed content transaction so undo restores the exact
+  prior structure. Local React uses the semantic source handoff (never generic
+  AST rewriting), preserves nested absolute descendants and responsive logic,
+  and applies the approved proposal as one reversible source edit.
 
 ## Full App Building
 

package/corpus/templates/design/DESIGN.md

@@ -9,7 +9,7 @@ and later blend hosted/fusion sources without changing the artboard model.
 Design is overview-first for multi-screen work. Generation and broad updates
 should land in the screen overview: an infinite canvas where each screen is a
 static frame that can be selected, moved, resized, dropped, or duplicated.
-Use the frame's full-view button when a screen needs focused scrolling or
+Use the frame's Interact button when a screen needs focused scrolling or
 prototype interaction.
 
 Single-screen mode is the scroll/interact/edit surface for one rendered file. It

package/corpus/templates/design/DEVELOPING.md

@@ -114,7 +114,7 @@ Design has two editor views:
 - **Overview** is the default multi-screen canvas after generation or broad
   updates. It renders every screen as a static, movable frame on an infinite
   surface. Users can select screens, move/resize/drop frames and primitives,
-  edit layers in place, and use a frame's full-view button to focus it.
+  edit layers in place, and use a frame's Interact button to focus it.
 - **Single screen** renders one file in the iframe editor. Use it for scrolling,
   interacting with prototype behavior, text/DOM selection, and local visual
   edits inside that screen.

package/corpus/templates/design/FIGMA_INTEROPERABILITY.md

@@ -0,0 +1,116 @@
+# Figma interoperability and fidelity contract
+
+This is the acceptance contract for Figma interoperability in Design. It is
+deliberately stricter than a feature checklist: a path is only **exact** when
+the original visual result and the relevant editable semantics survive. A
+rendered fallback can be pixel-faithful while still losing editability, so it
+is reported separately.
+
+Figma's REST API exposes file/node JSON and rendered exports, but it does not
+offer a general REST operation for creating arbitrary native canvas layers.
+Native canvas writes belong to Figma's official MCP/Plugin API path. The `.fig`
+container and Figma clipboard binary are private formats and can change without
+notice. Those boundaries make a universal lossless round trip impossible; the
+product must report them instead of claiming success.
+
+## Capability matrix
+
+| Workflow or feature          | Current behavior                                                                                                                                                                                                   | Fidelity                                                                                                                                                         | Required verification                                                                               |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Figma frame URL / file key   | Reads the exact node through `file_content:read`, converts it to a new Design screen, mirrors expiring images into durable storage, and returns a per-node fidelity report.                                        | Mixed; see node matrix below.                                                                                                                                    | REST fixture, authenticated file, screenshot comparison.                                            |
+| Figma URL without a node id  | Imports the first top-level object on the first page. A specific frame URL is recommended for deterministic results.                                                                                               | Same as node import.                                                                                                                                             | Multi-page and empty-page fixtures.                                                                 |
+| Figma branch URL             | Uses the branch key and imports that branch's node.                                                                                                                                                                | Same as node import.                                                                                                                                             | Main/branch pair with divergent content.                                                            |
+| Figma clipboard to Design    | Uses private `figmeta.selectedNodeData` ids when present, then the same REST converter. Older visible HTML is only a fallback. Binary-only clipboard data without ids/token is not decoded.                        | Exact selection identity while Figma's private metadata shape remains compatible; node fidelity is mixed.                                                        | Real Chrome copy from single, multi, nested, and 100+ node selections.                              |
+| `.fig` upload                | Bounded best-effort decoding of known Kiwi/ZIP variants into editable HTML. Embedded images are moved to durable storage.                                                                                          | Experimental. The format is proprietary and has no compatibility guarantee.                                                                                      | Corpus of real files from multiple Figma versions; never only generated containers.                 |
+| Design to Figma clipboard    | Copies an SVG built from the live rendered DOM. Figma imports supported SVG primitives as editable layers.                                                                                                         | Visual/vector handoff, not a native semantic round trip. Auto layout, variables, components, prototypes, HTML state, and code identity are not recreated by SVG. | Paste into real Figma and inspect layer types, text, images, effects, clipping, and bounds.         |
+| Design SVG download          | Same conversion as clipboard, with a server-render fallback when a live DOM is unavailable.                                                                                                                        | Same SVG limits; the export report lists approximations and omissions.                                                                                           | Live and server paths, selected layer and whole screen.                                             |
+| Native Design to Figma write | Use Figma's official MCP `use_figma` write-to-canvas path when the connected client/account supports it.                                                                                                           | Native Figma structures, subject to Figma MCP beta limitations and permissions.                                                                                  | Full-seat/edit-permission account and a real destination file.                                      |
+| `.fig` download              | Not supported. There is no documented public `.fig` authoring contract.                                                                                                                                            | Unsupported.                                                                                                                                                     | Do not label SVG/ZIP as `.fig`.                                                                     |
+| Open-ended Figma chat        | Provider catalog/docs/request expose the REST surface allowed by the user's scoped token; non-read calls require approval. Native canvas authoring requires official Figma MCP, not a personal access token alone. | Endpoint-dependent.                                                                                                                                              | Read scopes, expired/revoked token, rate limiting, Enterprise-variable permissions, MCP connection. |
+
+## REST node conversion matrix
+
+| Figma construct                                                            | Representation in Design                                                                                                                             | Fidelity and residual limit                                                                                                                                                                                              |
+| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Frames, groups, sections, rectangles, full ellipses                        | Nested HTML boxes with fixed imported geometry.                                                                                                      | Exact at the imported canvas size for supported paints/effects.                                                                                                                                                          |
+| Horizontal/vertical auto layout                                            | Flexbox with direction, padding, gap, wrap, alignment, FILL/HUG sizing, and min/max sizes. Absolute children remain out of flow.                     | Strong structural mapping, but Figma and browser layout engines are not identical. GRID and less common layout flags need golden comparison.                                                                             |
+| Nested freeform positioning and clipping                                   | Parent-relative absolute geometry; `clipsContent` becomes `overflow:hidden`.                                                                         | Exact for axis-aligned bounds.                                                                                                                                                                                           |
+| Rotation                                                                   | CSS rotation reconstructed from the post-rotation bounding box.                                                                                      | Approximated because the pre-rotation box/pivot requires geometry transforms. Listed in the fidelity report.                                                                                                             |
+| Solid and multi-layer fills                                                | CSS background layers in Figma stacking order.                                                                                                       | Exact for supported paint stacks.                                                                                                                                                                                        |
+| Linear gradients                                                           | CSS gradient derived from Figma handles in pixel space.                                                                                              | Exact for the supported linear model.                                                                                                                                                                                    |
+| Radial/angular/diamond gradients                                           | CSS radial/conic approximation.                                                                                                                      | Approximated and reported.                                                                                                                                                                                               |
+| Image fills                                                                | Durable mirrored URL with FILL/FIT/TILE/STRETCH.                                                                                                     | Exact for axis-aligned transforms. Filtered, rotated, or skewed crops become rendered fallbacks. Missing image URLs fail the import instead of silently disappearing.                                                    |
+| Text                                                                       | Editable text with font family, size, weight, italic, line height, tracking, alignment, case, decoration, whitespace, and ordinary mixed-style runs. | Exact only when the same font is available and the feature is representable by CSS. Lists, paragraph typography, hyperlinks, OpenType overrides, gradient/image text, and other advanced runs become rendered fallbacks. |
+| Uniform solid strokes                                                      | Border/outline/inset-shadow mapping according to alignment.                                                                                          | Exact for the covered model. Per-side CENTER/OUTSIDE is approximated and reported.                                                                                                                                       |
+| Multiple, dashed, gradient, or image strokes                               | Rendered PNG fallback for the smallest affected subtree.                                                                                             | Pixel-oriented fallback; not structurally editable.                                                                                                                                                                      |
+| Drop/inner shadows                                                         | CSS shadows.                                                                                                                                         | Exact for ordinary CSS-compatible shadows. Non-normal effect blending becomes a fallback.                                                                                                                                |
+| Layer/background blur                                                      | CSS filter/backdrop-filter.                                                                                                                          | Approximated because Figma's radius mapping is not a public 1:1 contract.                                                                                                                                                |
+| Blend modes                                                                | CSS `mix-blend-mode` when available; closest mapping for a few Figma-only modes.                                                                     | Exact or approximated as reported. Paint/effect blend modes that cannot be preserved become fallbacks.                                                                                                                   |
+| Lines, partial/ring ellipses, vectors, boolean operations, stars, polygons | Rendered fallback requested from Figma.                                                                                                              | Visual fallback, not editable geometry. Figma caps rendered images at 32 megapixels and may downscale them.                                                                                                              |
+| Masks                                                                      | The smallest container whose children participate in the mask is rendered as one fallback.                                                           | Preserves visual composition, loses structural editability within that subtree. Alpha/vector/luminance masks are not misrepresented as ordinary layers.                                                                  |
+| Components, instances, and variants                                        | Resolved child visuals become HTML; component id/properties remain bounded `data-figma-*` metadata.                                                  | Visual conversion plus provenance, not a live link to the Figma master. Instance swaps/variant semantics do not round trip through HTML/SVG.                                                                             |
+| Variables                                                                  | Resolved visuals are imported and `boundVariables` ids remain bounded metadata.                                                                      | Bindings are not live Design tokens. Full variable enumeration also depends on Enterprise plan/seat/scopes.                                                                                                              |
+| Prototype interactions                                                     | Preserved as inert metadata.                                                                                                                         | Deliberately do not navigate the editor iframe. No executable prototype round trip yet.                                                                                                                                  |
+| Videos, emoji paints, FigJam-only and unknown node types                   | Rendered fallback when Figma can render the node.                                                                                                    | Visual fallback only.                                                                                                                                                                                                    |
+| Hidden or 0%-opacity subtrees                                              | Omitted without downloading their assets.                                                                                                            | Visually exact and avoids unnecessary work.                                                                                                                                                                              |
+
+## Safety and scale limits
+
+- REST responses are capped at 4 MB. Multi-selection requests split
+  recursively; one frame that exceeds the cap fails with "import a smaller
+  selection" rather than truncating.
+- Node trees are capped at 75,000 nodes and 256 levels before recursive
+  rendering. Cycles are rejected.
+- Fallback/image-fill references are capped at 256, fetched/uploaded with a
+  concurrency of four, limited to 15 MB per image and 64 MB total, and checked
+  by MIME signature.
+- Figma render/image URLs are fetched through the SSRF-safe path, then mirrored
+  into user-scoped durable file storage. Expiring provider URLs and binary data
+  are not stored in SQL.
+- A required fallback or image fill that Figma fails to return aborts the import.
+  The importer never reports success after silently deleting visible content.
+- Metadata attributes are capped at 16 KB per property; oversized metadata is
+  omitted and reported as an approximation.
+
+## Golden corpus required for release confidence
+
+Generated unit fixtures protect parsing and failure behavior but cannot prove
+pixel parity. Maintain a permission-safe private test file/corpus with these
+real cases and compare both screenshots and editable structure:
+
+1. Nested horizontal, vertical, wrapping, negative-gap, grid, absolute-child,
+   min/max, baseline, and responsive auto layout.
+2. Mixed fonts/scripts/emoji, missing and custom fonts, variable fonts, lists,
+   OpenType features, text-on-path, truncation, and mixed hyperlinks.
+3. Every gradient, fill stack, image crop/filter/tile, stroke alignment/dash,
+   effect, blend mode, mask type, vector network, boolean op, and arc.
+4. Local/remote components, nested instances, variants, exposed properties,
+   overrides, swaps, variables/modes/aliases, and published libraries.
+5. Prototype overlays, scroll behaviors, links, interactive components, media,
+   and conditional actions, verifying they stay inert while editing.
+6. Rotated/skewed/flipped nested frames and clipping at fractional coordinates.
+7. Single/multi/cross-page clipboard selections, 100+ node selections, revoked
+   tokens, inaccessible files, branches, rate limits, null renders, and expired
+   image URLs.
+8. Small through near-limit documents, deeply nested documents, 32-megapixel
+   fallback boundaries, many images, slow storage, cancellation, and retries.
+9. Round trips through live-DOM SVG, server SVG, clipboard paste into Figma,
+   official MCP native write, PDF export, and re-import with a structural diff.
+
+Release evidence should record the Figma file version, browser/app version,
+font environment, screenshot diff thresholds, structural assertions, timing,
+memory, warnings, and every fallback. "The import completed" is not a fidelity
+assertion.
+
+## Primary references
+
+- Figma REST file/node/image endpoints:
+  <https://developers.figma.com/docs/rest-api/file-endpoints/>
+- Figma REST node types and mask/interaction/geometry properties:
+  <https://developers.figma.com/docs/rest-api/file-node-types/>
+- Figma Variables API requirements:
+  <https://developers.figma.com/docs/rest-api/variables/>
+- Figma MCP write to canvas and current limitations:
+  <https://developers.figma.com/docs/figma-mcp-server/write-to-canvas/>
+- Figma MCP code to canvas:
+  <https://developers.figma.com/docs/figma-mcp-server/code-to-canvas/>