@agent-native/core 0.121.2 → 0.122.1

package/corpus/templates/design/AGENTS.md

@@ -1,11 +1,12 @@
 # Design — Agent Guide
 
-Design is an agent-native prototyping app. The agent creates and edits complete
-interactive HTML prototypes, design systems, variants, and handoff exports
-through actions against the shared SQL state.
+Design is an agent-native prototyping app. The agent creates and edits
+complete interactive HTML prototypes, design systems, variants, and handoff
+exports through actions against the shared SQL state.
 
-Keep this file essential. Detailed generation, design-system, export, and UI
-patterns live in `.agents/skills/`.
+Keep this file essential — it is loaded into the agent's context every turn.
+Real depth lives in `.agents/skills/`; read the relevant skill before deeper
+work in that area.
 
 Before building common workspace or agent UI, read `agent-native-toolkit` to
 inventory existing public kits and installed package seams. Use
@@ -18,517 +19,101 @@ ladder.
   base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
   thumbnails, or replay chunks in app tables, `application_state`, `settings`,
   or `resources`; persist URLs, ids, or handles instead.
-- 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.
+- 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.
-- A message beginning with `[Reprompt selection]` is preview-only. Call
+- A message beginning with `[Reprompt selection]` is preview-only: call
   `propose-node-rewrite` with its exact `repromptId`, target, and base hash;
-  never call `edit-design`, `update-design`, `update-file`, `generate-design`,
-  `apply-visual-edit`, or another content writer. Only the frontend-only
-  `resolve-node-rewrite` action may persist an explicitly accepted proposal.
-- A message beginning with `[Selection question]` is read-only. Answer about
-  the captured element and subtree without calling content-writing actions.
-- 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.
+  never call a content writer (`edit-design`, `generate-design`,
+  `apply-visual-edit`, ...) — only the frontend-only `resolve-node-rewrite`
+  persists an accepted proposal (see `visual-edit`'s "Select And Reprompt").
+  `[Selection question]` is read-only: answer about the captured element and
+  subtree without calling content-writing actions.
 - Call `view-screen` before editing a specific design if the current design or
   selected file is not already clear from context.
-- For shared prototype feedback, use the persisted review actions
-  (`list-review-comments`, `get-review-feedback`, `create-review-comment`,
-  `reply-review-comment`, `resolve-review-thread`, `consume-review-feedback`,
-  `send-review-thread-to-agent`, and `set-review-status`). Work one thread at a time, prefer its stable node
-  anchor, verify saved edits before resolving, and read
-  `.agents/skills/design-review-feedback/SKILL.md` for the full loop.
-- Generated files must be complete, standalone HTML unless the user asks for a
-  different export format. They should render in the iframe without a build step.
-- For design generation, ground the work in a concrete audience, primary job,
-  and visual thesis before writing. For existing products, inspect current
-  screens, linked design systems, tokens, and component language before
-  inventing a new direction. Use realistic content/copy and one signature choice
-  per direction; avoid lorem ipsum, generic SaaS filler, and decorative
-  placeholders. Include expected responsive/accessibility states, run
-  `run-design-audit`, and call `take-design-screenshot` on each changed screen
-  before calling it ready — see the `design-generation` skill's Phase 5.
-- For editable reusable building blocks inside Design, use
-  `list-design-native-assets` first, then `insert-design-native-asset` with the
-  chosen kind. These are Design-native HTML primitives/components, not external
-  media, so prefer them when the user asks for a Figma Assets-style library that
-  supports our own primitives.
-- For raster image generation, restyling, or editing existing screenshots/photos,
-  use the available first-party Assets MCP tool such as `generate-asset` instead
-  of placeholders or generic stock imagery. Default to `tier: "fast"` (the cheap
-  Gemini flash "nanobanana"-class model) unless the user explicitly asks for
-  best quality; pass `aspectRatio` matching the layout slot (e.g. `21:9` hero,
-  `4:3` card, `1:1` avatar); include the linked design system's
-  `imageStyle.styleDescription` in the prompt when one is linked; and always
-  pass `callerAppId: "design"`. When the Assets picker returns a
-  selected asset, preserve `assetId`, `runId`, and URLs verbatim; if a design is
-  open, call `insert-asset` with the chosen URL/id, then refine placement with
-  `get-design-snapshot` and `edit-design` as needed. If no Assets MCP tool is
-  available, use the first-party Assets app via `call-agent` with agent
-  `"assets"` when available. If the user attached an image, use its hosted
-  chat-attachment URL or call `upload-image` to create one before delegating. If
-  no image/upload provider is configured, say that specific setup is needed and
-  continue any non-image Design work separately.
-- For reusable Figma library components, use `list-figma-library-assets` with a
-  Figma file URL or file key. It returns components/component sets with
-  thumbnails, rendered insert URLs, and Figma provenance. Insert with
-  `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. 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 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). 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 accepts an optional Figma frame URL alongside the
-  file. When the URL contains a `node-id`, only that frame or its containing
-  top-level frame is imported; a mismatch falls back to all frames. This path
-  uses no Figma REST API quota 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, `import-figma-clipboard` falls
-  back to a local Kiwi binary decode: geometry, auto-layout, text, solid fills,
-  and strokes are editable immediately; image fills become annotated
-  placeholders (`data-figma-image-ref="<sha1>"`) that can be filled in later two
-  ways. (1) Token-free: upload the original `.fig` — the paste-result dialog's
-  "Fill images from .fig" option, or `hydrateFileIds` on the `.fig` upload route
-  (`/api/import-design-file`) — which matches each placeholder's SHA-1 hash to
-  the `.fig`'s embedded `images/` bytes, mirrors them to durable storage, and
-  needs no Figma API. (2) With a token: `hydrate-figma-paste-images` resolves the
-  same placeholders through Figma's REST image endpoint. This is not a
-  full-fidelity import — report which image fills are still unresolved and offer
-  to hydrate them. Clipboard paste is the fast no-quota path; the original `.fig`
-  is what carries the real image bytes for both upload and paste-hydration.
-- 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
-  `data-screen="file.html"` attribute, or `#` anchors — never real/relative
-  URLs, which would navigate the preview iframe to the app itself.
-- To refine an existing design, make the smallest change: read it with
-  `get-design-snapshot`, then use `edit-design` (search/replace). Reserve
-  `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.
-- When the user references a template, prior design, or past work, call both
-  `list-design-templates` and `list-designs` before generating so the existing
-  starting point is resolved instead of recreated. 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.
-  Read the `design-templates` skill for the complete copy/adaptation workflow.
-- 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
-  edits are needed, use `get-design-snapshot` first and persist the complete
-  updated tweak definition list through `generate-design`.
-- Design editor extensions render in the right inspector slot
-  `design.editor.inspector`. When creating an extension for that panel, call
-  `create-extension`, then `add-extension-slot-target` with that slot id, then
-  `install-extension` so it appears inline. Extensions receive
-  `window.slotContext` with the current design id, active screen, selected
-  element, zoom, mode, tool, and tweak values. For AI-driven style/artboard
-  changes, extension HTML should call `agentNative.chat.send(...)` with the
-  selected element selector/sourceId and request; the agent should call
-  `view-screen` first, prefer `apply-visual-edit` for element style/class/text
-  changes, and use `update-design` or `generate-design` with `canvasFrames` for
-  overview artboard placement changes. If creating the extension opens the
-  standalone extension editor, return to the same design with `navigate` and
-  `inspectorTab: "extensions"` after installing it.
-- Follow linked design-system tokens and `customInstructions` whenever present;
-  explicit user instructions in the current turn still win.
-- Before generation, follow the creative-context reuse ladder in
-  `.agents/skills/creative-context/SKILL.md`: explicit request and current
-  design first, then a pinned/current pack, then narrow library search. Respect
-  `creative-context.contextMode: "off"` without silently restoring a pack.
-- To submit a design to a governed Creative Context, use the Context tab or
-  `manage-context-membership`; it captures one immutable live design snapshot.
-  Reuse only a returned opaque native clone reference through the Design clone action.
-  Use `operation="submit-latest"` with a Library membership id when its native
-  update status reports `update-available`.
-- 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 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
-  design system from raw Figma/code sources.
-- When a user wants one-off tokens from design.md, CSS, theme/tokens JSON,
-  Tailwind config, local files, or the current design, call
-  `import-design-tokens` and preserve its `tokens`, `filesAnalyzed`, and
-  provenance in your answer. Manual `apply-design-token-edit` / one-by-one
-  token entry is the fallback for a small one-off token, not the primary import
-  workflow.
+- Generated files must be complete, standalone HTML (Alpine.js + Tailwind CDN)
+  that renders in the iframe without a build step. See `design-generation` for
+  the full generation workflow — phases, the aesthetic quality bar, and the
+  audit/screenshot pass required before calling a design "ready".
+- Treat `data-agent-native-locked="true"` as authoritative: locked elements
+  and descendants stay byte-for-byte unchanged (server-enforced). Ask the user
+  to unlock the layer in the Layers panel if they want it changed.
+- Figma import/read/paste and design-system/token workflows
+  (`import-figma-frame`, `get-figma-design-context`, `list-figma-library-assets`,
+  clipboard paste, `.fig` upload) are fully covered in `design-systems` — read
+  it before guessing the calling convention. Never claim universal lossless
+  Figma import/export; consult `FIGMA_INTEROPERABILITY.md` for the real
+  fidelity contract. For open-ended GitHub/Figma API questions, use
+  `provider-api-catalog`/`provider-api-docs`/`provider-api-request` rather than
+  treating provider actions as a capability ceiling; non-read Figma requests
+  need human approval.
 - Persist useful work early: create/update the design and files as soon as a
   coherent candidate exists, then iterate.
-- For a brief or ambiguous _new_ design prompt, ask before generating:
-  create/open the design shell, call `show-design-questions` with a small
-  tailored set, stop while the main canvas shows the questions, then continue
-  from the user's answers. Skip asking when the prompt is already specific,
-  it's a tweak/edit to an existing design, the user already answered a
-  question set for this design and is now iterating, or they say "decide for
-  me"/"surprise me"/"just build it" — see the `design-generation` skill for
-  how to size and word the questions.
-- For multiple screens/states, call `generate-screens` first. It opens the
-  infinite screen overview and returns target filenames plus `canvasFrame`
-  placements. Then call `generate-design` with those files and pass the matching
-  `canvasFrames` entries so screens appear in the overview instead of only in
-  the file list.
-- After generation or broad updates, leave the user in the screen overview when
-  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
-  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.
-- Single-screen mode is for scrolling, interacting with prototype behavior, and
-  editing the DOM/code layers inside one screen. Do not use it as the default
-  landing mode for multi-screen generation unless the user asks to focus a
-  specific screen.
-- The layers panel shows screens as top-level frames and nests DOM/code layers
-  beneath the active screen. Rename DOM/code layers by safely editing source to
-  set `data-agent-native-layer-name`; this is the stable human-readable layer
-  name. `data-code-layer-id` and similar ids are for selection stability, not
-  display naming.
-- For inline/Alpine screens, stamp and preserve unique
-  `data-agent-native-node-id` attributes on selectable DOM nodes. Treat
-  generated CSS selectors as a compatibility fallback only. For localhost React
-  screens, resolve through build-time source/debug metadata (stable generated
-  ids, component name, file, and line) before falling back to selectors.
-- For inline/Alpine motion, use `get-motion-timeline` to inspect the active
-  file's saved or CSS-recovered timeline, then call `apply-motion-edit` with the
-  same `sourceRef`/`fileId` to update it. Motion edits persist as durable
-  managed keyframes in `<style data-agent-native-motion>` plus editable timeline
-  metadata; it is not a one-way export. Real CSS module or `motion/react`
-  write-back remains a localhost/fusion follow-up capability.
-- For multi-variant work, use `present-design-variants` so every candidate is
-  saved as a normal overview-board screen and the user gets one inline chat
-  button per screen name. Keep each variant compact: prefer concise labels,
-  descriptions, accent colors, and feature bullets, and omit full HTML when it
-  would make the tool input too large. The action can render representative
-  screens from direction data. After the user picks, delete the unchosen
-  variant screens before continuing from the kept screen.
-- Use framework sharing actions for design and design-system visibility/grants.
-- `/visual-edit` is a public entry route and public `/design/:id` links may
-  render read-only public designs without a session. Do not open anonymous write
-  actions: save, share, generation, localhost connection, and screen persistence
-  should send signed-out visitors through `/_agent-native/sign-in?return=...`,
-  then save or copy the design into the authenticated account before sharing.
-- When the user asks to download/export, use export actions or point to the
-  editor download menu.
-- Design source modes are `inline`, `localhost`, and `fusion`. Inline is the
-  current SQL-backed prototype mode. Localhost connections come from
-  `npx @agent-native/core@latest design connect` and are persisted with
-  `connect-localhost`; list them with `list-localhost-connections` before
-  creating or resolving local-code artboards. Fusion designs are full-app
-  designs backed by a running Builder Fusion container, created via
-  `create-fusion-app` when the `full-app-building` feature flag is enabled;
-  preserve the
-  design's `fusionApp` linkage data whenever present and never invent it.
-- Localhost route manifests are scaffolding for URL-backed Flow Canvas
-  artboards. Use `add-localhost-screens` to place routes or path/query states as
-  iframe screens in overview mode. Preserve route ids, paths, `sourceType`,
-  bridge URL, and snapshot/state references when moving between actions so later
-  flow-edge derivation has stable anchors.
+- In dev, call actions with `pnpm action <name>`; in production, call the
+  native tool.
+- For shared prototype feedback, use the persisted review actions
+  (`get-review-feedback`, `create-review-comment`, `resolve-review-thread`, ...)
+  — read `design-review-feedback` for the one-thread-at-a-time loop.
+- Follow linked design-system tokens and `customInstructions` whenever
+  present; explicit user instructions in the current turn still win. Before
+  generation, follow the `creative-context` reuse ladder and respect
+  `contextMode: "off"` without silently restoring a pack.
+- When the user references a template or prior design, call
+  `list-design-templates`/`list-designs`; use `create-design-from-template` and
+  `get-design-snapshot` before `edit-design`.
+- Design source modes are `inline` (current SQL-backed default), `localhost`
+  (`visual-edit`), and `fusion` (flag-gated, `full-app-build`). Preserve a
+  design's `fusionApp`/localhost connection data verbatim; never invent it.
+  Public `/visual-edit` and `/design/:id` links can render read-only without a
+  session — never run anonymous write actions (save/share/generate/localhost
+  connect); send signed-out visitors through
+  `/_agent-native/sign-in?return=...` first.
+- For multi-variant exploration, use `present-design-variants` (2-5 variants,
+  three by default) — see `design-generation` Phase 2 for the full
+  pick → delete-unchosen → refine flow; never call `generate-design` after a
+  variant pick.
+- When the user asks to download/export, use the export actions or point to
+  the editor download menu — see `export-handoff`.
 
 ## Application State
 
-- `navigation` tells you the current view, design id, file id, and related UI
-  state.
-- `navigate` moves the UI and is auto-deleted after the client consumes it.
-- `design-selection` includes active screen, selected element, overview mode,
+- `navigation` — current view, design id, file id, and related UI state.
+- `navigate` — moves the UI; auto-deleted after the client consumes it.
+- `design-selection` — active screen, selected element, overview mode,
   inspector tab, zoom, and screen list for the current tab.
-- `design-generation-session:<designId>` contains agent-facing multi-screen
-  generation planning state created by `generate-screens` (canvas region
-  assignments and per-frame instructions consumed by `generate-design` and
-  `view-screen`; not rendered as canvas overlays).
-- `design-reprompt-pending:<designId>:<fileId>` is the client-captured source
-  selection, instruction, base hash, and authoritative current request id for
-  a scoped regenerate request. The frontend starts requests through the
-  compare-and-set `begin-node-rewrite-request` action and must not overwrite a
-  `resolving` acceptance reservation.
-- `design-reprompt-proposal:<designId>:<fileId>:<repromptId>` is one
-  request-specific preview-only subtree proposal. Candidate payloads have a
-  256 KiB aggregate serialized limit. Proposal publication, resolution, and
-  cancellation use atomic multi-key compare-and-set transitions. Acceptance
-  reserves its matching pending request before writing design content, so a
-  newer request and an older acceptance cannot both win.
-  `view-screen` lists only proposals paired to the current pending request as
-  `pendingCandidateReviews`.
-- `show-design-questions` opens focused pre-generation questions in the main
-  design canvas (`show-questions` application state).
-- `guided-questions` may contain a one-click chat choice for the current
-  variant set. Variants themselves are normal design files with `canvasFrames`
-  and `screenMetadata`.
-
-## Code Layers
-
-- `get-code-layer-projection` reads inline HTML/JSX and returns selectable layer
-  nodes, selectors, names, and edit intents for agent and UI workflows.
-- `apply-visual-edit` supports deterministic local edits for HTML-backed code
-  layers: text, classes, styles, attributes, source order, and small structural
-  changes. Use it for selected-element edits before falling back to full
-  `update-design` / `generate-design` rewrites.
-- For localhost JSX/TSX, `apply-visual-edit` also supports a narrow deterministic
-  slice: single-instance leaf text, literal `className`/`class`, and flat literal
-  `style={{ ... }}` properties. Pass `source.kind: "local-file"`, `designId`,
-  `connectionId`, the verified project-relative `path`, and
-  `intent.target.sourceAnchor`. Call once without `persist` and inspect
-  `proposedDiff`; call again with `persist: true` only when it is exact. The
-  action reads the current bridge version and writes through `write-local-file`,
-  so human consent and compare-and-swap remain mandatory.
-- For localhost React/TSX screens, treat compiler/debug metadata (project-relative
-  source file, line, column, component, and runtime multiplicity) as evidence
-  for locating source, not as permission to run a generic AST transform.
-  Compiler tooling may verify an anchor, classify a literal edit, and validate
-  syntax. Reparenting, grouping/ungrouping, wrappers, dynamic expressions,
-  repeated `.map()` instances, shared components, and cross-file changes must
-  be handed to the coding agent with both runtime relationships and exact
-  source anchors so it can inspect the surrounding program semantics.
-- A localhost React handoff must read each source file first, write with the
-  exact returned `versionHash` as `expectedVersionHash` with
-  `requireExpectedVersionHash: true`, re-read and re-plan on conflict, and leave the
-  optimistic canvas preview in place until the dev server/HMR confirms the
-  runtime result. Never report a semantic canvas change as persisted merely
-  because it was submitted to the coding agent.
-- Prefer `data-agent-native-layer-name="Readable name"` on meaningful elements.
-  The projection uses it before semantic/text fallbacks, and layer renames should
-  persist by updating that attribute.
-- Inline/Alpine screens continue to use deterministic HTML code-layer edits.
-  Localhost React/TSX screens use the semantic coding-agent handoff above;
-  deterministic direct React writes remain intentionally limited to the leaf
-  literal slice above and never include generic structural transforms,
-  breakpoint writes, dynamic expressions, repeated renders, shared component
-  definitions, generated/out-of-root paths, or remote URLs.
-
-## Code Workspace
-
-- The editor left rail has a wide `code` panel: a VS Code-style workbench
-  (`app/components/design/code-workbench/`) with an explorer, workspace search,
-  editor tabs, quick open (⌘P), a command palette (⇧⌘P), and a status bar. Open
-  it with `navigate --view editor --designId <id> --leftPanel code` and
-  optionally pass `fileId`, `filename`, or `screen` to focus a file.
-- The explorer shows one root per workspace source: the design's SQL-backed
-  files (`designfs://<designId>/`, backend `virtual-inline`) always, plus one
-  root per localhost connection referenced by the design's screens
-  (`list-local-files` / `read-local-file` proxy the `design connect` bridge;
-  writes go through `write-local-file` and its user-approved consent grant).
-- Inline design files are auto-formatted with Prettier the first time they are
-  opened in the workbench and the formatted result is persisted; local files
-  are never auto-formatted.
-- Use `list-source-files` to inspect the inline source workspace and
-  `read-source-file` for file contents; preserve its `versionHash` before
-  writing. Do not return full file content from `view-screen`; it reports only
-  active code file metadata and dirty state.
-- Use `preview-source-edit` to show a diff without saving, then
-  `apply-source-edit` with the prior `versionHash` to save either a full replace
-  or exact replace. These actions update the same inline file state as the UI;
-  agent edits show up live in open workbench buffers.
-- Use `resolve-selection-source` when the user has a canvas element selected and
-  you need the best matching inline file location/snippet.
-- The workbench session (open tabs, active file, sidebar layout) persists per
-  design in application state under `code-workbench:<designId>`.
-
-## Localhost Source Actions
-
-- `connect-localhost`: registers or refreshes a localhost source connection
-  emitted by `npx @agent-native/core@latest design connect`. Pass
-  `devServerUrl`, optional `bridgeUrl`, optional `rootPath`, and either `routes`
-  or a full `routeManifest`.
-- `list-localhost-connections`: lists the current user's saved localhost
-  connections and route manifests. Use this before referring to local-code
-  artboards.
-- `add-localhost-screens`: creates or refreshes URL-backed iframe screens from
-  the latest localhost connection or a specific `connectionId`. Pass `routes`
-  with `path`/`url` when visualizing a flow; pass `paths` for a concise route
-  list. Then call `navigate --view editor --designId <id> --editorView overview`.
-- `write-local-file`: writes/patches a local file through the bridge, but only
-  when a user-approved write-consent grant exists. Granting is human-only
-  (`grant-localhost-write-consent` is hidden from agents), so you cannot approve
-  it yourself.
-- `request-localhost-write-consent`: call this when `write-local-file` fails
-  with "no write-consent grant". It opens the write-consent dialog in the
-  editor (or reports `alreadyGranted`). Tell the user to click "Allow writes",
-  then retry `write-local-file`. Do not keep retrying blindly — the write stays
-  blocked until the user approves.
-
-## Review, Breakpoints, Screen States & Components
-
-- **Review**: `run-design-audit` runs a read-only accessibility audit over a
-  design's rendered HTML (missing alt/labels, tap-target size,
-  focus-visibility, reduced-motion coverage, a contrast hint) and returns
-  `A11yFinding[]`. `apply-a11y-fix` applies one deterministic inline fix for a
-  finding (contrast, tap-target size, focus ring) when `fixAvailable: true`.
-  `get-design-review` compares two design snapshots/branches and returns a
-  file-level visual diff (added/removed/modified). See the `design-generation`
-  skill's Phase 5 for when to run these.
-- **Breakpoints**: `add-breakpoint`, `remove-breakpoint`, and
-  `set-active-breakpoint` manage the design's device-width frame set and which
-  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`
-  manage named DOM/Alpine states (Loading/Empty/Error), static data fixtures,
-  and live app captures. See the same skill section.
-- **Components**: `create-component` promotes a selected element into a
-  recognised reusable component; `index-components` scans a design's HTML for
-  existing component annotations; `list-design-components` scans all HTML
-  screens for swap targets; `get-component-details`,
-  `preview-component-prop-edit`, `apply-component-prop-edit`, and
-  `open-component-source` inspect, preview, persist, and navigate to a
-  component instance. Use `go-to-main-component` to select the earliest known
-  instance, `swap-component-instance` to replace an inline/Alpine instance
-  while preserving same-named prop overrides, and
-  `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
-
-Flag-gated by `FULL_APP_BUILDING` in `shared/full-app.ts` (key
-`full-app-building`, default off) and requires Builder connected. See
-`full-app-build` skill for the full flow.
-
-- `create-fusion-app`: creates the app branch via the Builder cloud agent; one
-  branch per design; returns existing linkage if already created.
-- `sync-fusion-app`: boots/attaches the container; poll while building; on
-  ready, updates `previewUrl` and upserts URL-backed screens.
-- `add-fusion-screens`: places more routes as screens once `previewUrl` is
-  known.
-- `queue-fusion-edit`: queues one edit intent against a fusion screen.
-- `list-fusion-edits`: inspects the queued edits.
-- `apply-fusion-edits`: batches pending edits into one prompt for the app's
-  in-container agent (fire-and-forget); marks them "sent".
-- `send-fusion-message`: relays a freeform request to the app's coding agent.
-- `push-fusion-app`: pushes the branch's code to its git remote.
-- `deploy-fusion-app`: reserves `<slug>.builder.cloud` and triggers a deploy.
-- `get-fusion-deploy-status`: polls deploy status until live/failed/canceled.
-- Fusion screens are URL-backed iframes, same model as localhost screens.
-  Never inline-edit a fusion screen's HTML or use `generate-design` /
-  `edit-design` / `apply-visual-edit` on it — queue and dispatch edits
-  instead. When not configured, actions return a connect CTA like
-  `migrate-inline-design-to-app`; never throw or invent `fusionApp` data.
-
-## App-Backed Skill Distribution
-
-- The preferred hosted install path is
-  `npx @agent-native/core@latest skills add design-exploration`,
-  `npx @agent-native/core@latest skills add visual-edit`, or `design` for the
-  full Design bundle. It installs the exported Design instructions and registers
-  the hosted Design MCP connector together.
-- The open Skills CLI path
-  `npx skills@latest add BuilderIO/agent-native --skill visual-edit` installs
-  exported instructions only.
-- For local-code visual editing, `/visual-edit` should run the target app dev
-  server, run
-  `npx @agent-native/core@latest design connect --url http://localhost:<port> --root .`,
-  register that manifest with `connect-localhost`, call `add-localhost-screens`,
-  and open the editor in overview mode.
-- For human-in-the-loop UI exploration, create a design shell, call
-  `present-design-variants` with 2-5 concise directions (three by default),
-  wait for the user to pick one in chat, delete each other generated variant
-  screen with `delete-file` at most once, call `get-design-snapshot` exactly
-  once with the selected screen's `fileId`, then call `edit-design` exactly once
-  on that same `fileId` for follow-up refinement. The kept variant screen is a
-  representative direction, not the final deliverable: use `mode:
-"replace-file"` to replace it with the actual requested app/product UI in the
-  chosen visual style. Keep the replacement complete but compact: prioritize
-  the primary workflow, and if the requested feature list is too large for one
-  reliable edit, represent secondary details as visible controls, states, or
-  affordances instead of expanding the action input. Do not leave a direction
-  board, variant brief, summary card, or prose description as the final screen.
-  Do not repeat delete/snapshot cycles, and do not call `generate-design` after
-  a variant pick.
-- If inline chat choice buttons are unavailable, the user can tell you the
-  preferred screen name. Do not show a separate variant picker or ask them to
-  paste a copyable handoff summary.
+- `design-generation-session:<designId>` — multi-screen generation planning
+  state from `generate-screens` (canvas region assignments, per-frame
+  instructions consumed by `generate-design`).
+- `design-reprompt-pending:<designId>:<fileId>` /
+  `design-reprompt-proposal:<designId>:<fileId>:<repromptId>` — the
+  compare-and-set reprompt request/proposal pair; see `visual-edit`'s
+  "Select And Reprompt" for the full lifecycle.
+- `show-design-questions` opens pre-generation questions in the main canvas
+  (`show-questions` state). `guided-questions` may hold a one-click chat
+  choice for the current variant set.
 
 ## Skills
 
 Read the relevant skill before deeper work:
 
-- `design-generation` for creating/editing prototype HTML and variant flows.
-- `design-templates` for resolving, saving, copying, and adapting templates or
-  prior Design work without fresh generation.
-- `responsive-breakpoints` for Framer-style breakpoint editing (single DOM,
-  cascading width-scoped overrides, the managed breakpoints media block).
-- `design-systems` for tokens, brand extraction, and linked systems.
-- `creative-context` for cross-app source reuse, pinned packs, provenance, and
-  context opt-out.
-- `export-handoff` for HTML/PNG/SVG/ZIP/code handoff.
-- `full-app-build` for flag-gated fusion-backed full app building.
-- `shader-fills` for code-backed GLSL shader fills/effects (editable source
-  in screen HTML, uniform knobs, preset library, and the picker's "Create a
-  custom shader fill." prompt).
-- `frontend-design` and `shadcn-ui` for app UI changes.
-- `actions`, `delegate-to-agent`, `security`, and `self-modifying-code` for
-  framework patterns.
+- `design-generation` — 5-phase generation flow, aesthetic quality bar, code
+  layers/code workspace, editor extensions, breakpoints/screen
+  states/components, motion, imagery.
+- `design-templates` — resolving, saving, copying, adapting templates or prior
+  Design work without fresh generation.
+- `responsive-breakpoints` — Framer-style breakpoint editing.
+- `design-systems` — tokens, brand extraction, and Figma import/read.
+- `creative-context` — cross-app source reuse, pinned packs, provenance,
+  context opt-out, submitting a design to a governed Context.
+- `design-review-feedback` — persisted, element-anchored review comments to a
+  verified close.
+- `export-handoff` — HTML/PNG/SVG/ZIP/code and coding-handoff export.
+- `visual-edit` — editing a real local app visually (localhost bridge, Code
+  tab, reprompt write boundary).
+- `full-app-build` — flag-gated fusion-backed full app building.
+- `shader-fills` — code-backed GLSL shader fills/effects.
+- `sharing` — design and design-system visibility/grants.
+- `frontend-design`, `shadcn-ui` for UI; `actions`, `delegate-to-agent`,
+  `security`, `self-modifying-code` for framework patterns.

package/corpus/templates/design/_gitignore

@@ -44,3 +44,4 @@ learnings.md
 /e2e/.auth/
 data/e2e.db
 data/e2e.db-*
+.agent-native/