@agent-native/core 0.122.4 → 0.123.0

package/docs/content/template-design-brand-and-figma.mdx

@@ -0,0 +1,150 @@
+---
+title: "Brand Systems and Figma"
+description: "How Design applies brand tokens and design systems, imports Figma frames and clipboard pastes, and reports exactly what converts versus what only approximates."
+---
+
+# Brand Systems and Figma
+
+A design system is the brand identity — colors, fonts, spacing, logos — that Design applies to every prototype linked to it. This page covers building one from scratch, from a public starting point, or from your own site, code, or documents, plus what a Figma import into Design can and can't do exactly.
+
+## Design systems
+
+Create a design system by describing your brand, or start from a real, maintained public system — Material 3, Carbon, or Primer — instead of recreating one from memory. Each of these ships real semantic tokens, a type scale, spacing, and attribution, and Design won't let a prompt quietly turn one into a lookalike with different data underneath. The first design system you create becomes your default automatically, and only one system is default at a time.
+
+Every design system also carries an optional set of custom instructions and a described image style, so generated photography and illustration stay in the same visual language as the rest of the brand instead of reading like stock art.
+
+## Importing brand from somewhere else
+
+- **Website** — paste a URL and Design pulls colors, fonts, the favicon, and the social preview image straight off the live site.
+- **GitHub repo or code files** — Design indexes the actual CSS and tokens from your codebase, so the system matches what's really deployed rather than a guess.
+- **Documents** — DOCX, PPTX, or PDF uploads; presentations are usually the strongest signal for brand colors and fonts.
+- **An existing design or design system** — fork one you already have instead of starting over.
+
+When several sources come in together, Design cross-references them — code sources are the most trustworthy, the website confirms what's actually shipped, documents fill in gaps — before merging everything into one system.
+
+<Diagram id="doc-block-design3" title="Multiple sources, one system" summary={"Website, code, Figma, and document sources all feed the same design system, and every design linked to it inherits the tokens on each generation pass."}>
+
+```html
+<div class="diagram-brandflow">
+  <div class="diagram-col">
+    <div class="diagram-node">
+      Website URL<br /><small class="diagram-muted"
+        >colors, fonts, favicon</small
+      >
+    </div>
+    <div class="diagram-node">
+      GitHub repo / code files<br /><small class="diagram-muted"
+        >indexed brand kit</small
+      >
+    </div>
+    <div class="diagram-node">
+      Figma file or frame<br /><small class="diagram-muted"
+        >styles, screenshot, or MCP variables</small
+      >
+    </div>
+    <div class="diagram-node">
+      Documents<br /><small class="diagram-muted">DOCX / PPTX / PDF</small>
+    </div>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill accent">create-design-system</span
+    ><small class="diagram-muted">or index-design-system-with-builder</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    Design system<br /><small class="diagram-muted"
+      >colors · type · spacing · logos</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill ok">Every generation</span
+    ><small class="diagram-muted">:root tokens + fonts + logo</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-brandflow {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-brandflow .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  align-items: flex-start;
+}
+.diagram-brandflow .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
+}
+.diagram-brandflow .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+```
+
+</Diagram>
+
+## Figma {#figma}
+
+### Bringing in a frame (pixel-accurate import)
+
+Paste a Figma frame or file share link and Design imports it as a real, editable screen — not a screenshot. Position, auto-layout (mapped to flexbox), text styling, fills, strokes, corner radii, shadows, and blend modes all come across structurally. A shape Figma allows but CSS structurally can't express — a vector network, a boolean operation — is rendered as an exact image instead of a guessed approximation, and every import returns a fidelity report saying exactly which properties landed in which bucket.
+
+### Pasting instead of linking
+
+A plain clipboard copy from Figma (Cmd+C, then Cmd+V on the Design canvas) is handled differently from a share link, because a link names one exact node while a clipboard paste doesn't always carry that. A current version of Figma includes hidden data in the paste that lets Design import the exact selection; without it, Design falls back to matching the pasted content against the file's own text, and only imports something when it's confident — a frame's name or two distinct pieces of visible text have to match verbatim. If it isn't confident, it imports nothing rather than guessing. Copying a frame's share link is the more reliable path when exactness matters.
+
+### Inserting one component, or just reading a file
+
+To drop in a single published component instead of a whole screen, Design can insert one from your Figma-connected library, with its source recorded. To ask a question about a file or frame — what's in it, what components it uses — without importing anything, Design can read the file's structure and pull a screenshot without creating a new screen.
+
+<Table
+  id="doc-block-design4"
+  title="Figma import paths"
+  columns={["Path", "What it is", "When to use it"]}
+  rows={[
+    [
+      "Frame link",
+      "A pasted Figma share URL naming one exact frame or node — always maps to structural, editable HTML/CSS",
+      "Bringing in a whole named frame as a real, editable screen",
+    ],
+    [
+      "Clipboard paste (Cmd+C / Cmd+V)",
+      "A copy from Figma pasted directly onto the canvas — exact when Figma's clipboard metadata is present, conservative text-matching otherwise",
+      "Fast iteration without leaving the canvas or copying a link",
+    ],
+    [
+      "Library asset insert",
+      "One published component or component set, with its source recorded",
+      "You want a reusable library component, not a whole screen",
+    ],
+    [
+      "Read without importing",
+      "Pages, frames, components, and a screenshot of a file or frame",
+      "You just want to know what's in a file before deciding what to bring in",
+    ],
+  ]}
+/>
+
+## Honest fidelity limits {#fidelity-limits}
+
+<Callout id="doc-block-design5" tone="info">
+
+Every Figma import returns a fidelity report, not a promise: which properties matched exactly, which ones CSS can only approximate (rotation, per-side stroke weights, some gradient shapes), and which subtrees had to fall back to a flat image because the shape can't be represented in HTML/CSS at all. Design surfaces this report so you know what to expect if you go on to edit that part of the screen — it never claims a lossless round trip.
+
+</Callout>
+
+## What's next
+
+- [**Design**](/docs/template-design) — back to the overview
+- [**Quality Passes and Components**](/docs/template-design-quality-and-components) — the audit/screenshot pass and reusable components
+- [**Review, Handoff, and Full Apps**](/docs/template-design-collaboration-and-full-apps) — export formats, including Figma-vector SVG
+- [**Extending Design**](/docs/template-design-developers) — the full action reference

package/docs/content/template-design-collaboration-and-full-apps.mdx

@@ -0,0 +1,125 @@
+---
+title: "Review, Handoff, and Full Apps"
+description: "Editing a real running app visually, leaving and resolving element-anchored review comments, exporting or handing a design to a coding agent, and building a full running app from Design."
+---
+
+# Review, Handoff, and Full Apps
+
+Once a prototype is in good shape, this page covers what happens next: pulling in a real running app to edit visually, collecting and resolving feedback from reviewers, getting the design out as files or code, and — behind a flag — turning a design into a real deployed app instead of a prototype.
+
+## Editing a real running app (/visual-edit) {#visual-edit}
+
+Design isn't only for prototypes generated from a prompt — a coding agent can install `/visual-edit` to bring a real, already-running local app into Design as its own screens. Each requested path or URL becomes its own screen on the canvas, and a numbered flow (an onboarding step 1, 2, 3) stays as separate ordered screens instead of collapsing into one. The entry route renders before sign-in, and a shared design link works read-only without an account — but saving the layout, generating new screens, or sharing still requires signing in first.
+
+<Diagram id="doc-block-design8" title="Three source modes" summary={"A design's source is inline, localhost, or fusion — the mode decides where an edit actually lands."}>
+
+```html
+<div class="diagram-sourcemodes">
+  <div class="diagram-box" data-rough>
+    <span class="diagram-pill accent">Inline</span
+    ><small class="diagram-muted"
+      >design_files rows · generate-design / edit-design write HTML
+      directly</small
+    >
+  </div>
+  <div class="diagram-box" data-rough>
+    <span class="diagram-pill">Localhost</span
+    ><small class="diagram-muted"
+      >your own dev server via /visual-edit · edits touch your local
+      files</small
+    >
+  </div>
+  <div class="diagram-box" data-rough>
+    <span class="diagram-pill ok">Fusion</span
+    ><small class="diagram-muted"
+      >cloud container · queue-fusion-edit dispatches to the app's own
+      agent</small
+    >
+  </div>
+</div>
+```
+
+```css
+.diagram-sourcemodes {
+  display: flex;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-sourcemodes .diagram-box {
+  flex: 1;
+  min-width: 200px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+```
+
+</Diagram>
+
+## Review feedback {#review-feedback}
+
+Anyone with access to a shared prototype can leave a comment pinned to a specific element rather than a generic note on the whole screen. A reviewer can leave it as a plain note, or send it straight to the agent to act on. When the agent works through a comment, it edits the exact part of the design the comment points at, checks that the change actually landed, then either resolves the thread with a one-line note of what changed, or replies asking the person to decide when it isn't something the agent should resolve on its own.
+
+<WireframeBlock id="doc-block-design9">
+  <Screen
+    surface="desktop"
+    html={
+      "<div style='display:flex;flex-direction:column;gap:14px;padding:18px;min-height:520px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Onboarding screen</h1><span class='wf-pill accent'>2 open comments</span><div style='flex:1'></div><button class='primary'>Share</button></div><div class='wf-card' style='flex:1;display:grid;grid-template-columns:1fr 260px;gap:14px'><div class='wf-box' style='padding:24px;position:relative'><div style='display:flex;flex-direction:column;gap:10px;max-width:60%'><strong style='font-size:20px'>Welcome to Acme</strong><span class='wf-muted'>Set up your workspace in under a minute.</span><button class='primary' style='width:fit-content'>Continue</button></div><span class='wf-pill accent' style='position:absolute;top:20px;right:60px;border-radius:999px'>1</span></div><div style='display:flex;flex-direction:column;gap:8px;border-left:1.4px solid var(--wf-line);padding-left:14px'><strong>Comment</strong><span class='wf-muted'>\"Continue button reads oddly next to the muted subhead — bump contrast?\"</span><button class='primary'>Send to agent</button><button>Resolve</button></div></div></div>"
+    }
+  />
+</WireframeBlock>
+
+## Export and handoff {#export-and-handoff}
+
+<Table
+  id="doc-block-design10"
+  title="Export formats"
+  columns={["Format", "What it's for"]}
+  rows={[
+    [
+      "HTML",
+      "One self-contained file with Tailwind/Alpine CDN links baked in — opens directly in any browser",
+    ],
+    [
+      "ZIP",
+      "All design files organized by type (HTML/CSS/JSX/assets) plus a metadata file",
+    ],
+    [
+      "PDF",
+      "Client-side rendered PDF of the design — the print-size presets are built for this",
+    ],
+    [
+      "SVG",
+      "An SVG wrapper around the live HTML — good for embedding, not editable in Figma",
+    ],
+    [
+      "Figma-vector SVG",
+      "Real vector shapes, text, and gradients Figma can import as editable layers — copy/paste or drag in as a file",
+    ],
+    [
+      "Coding handoff",
+      "Design tokens, Alpine state, and a ready-to-paste prompt for an external coding agent to turn the prototype into production code",
+    ],
+  ]}
+/>
+
+Whatever the destination, exporting always reflects the design's current state — including any applied tweaks — not the first generated version. Duplicate the design first if you want to keep iterating on a copy after handing one version off.
+
+## Full App Building (fusion mode) {#full-app-building}
+
+<Callout id="doc-block-design13" tone="warning">
+
+Full App Building is off by default and has to be explicitly enabled for a workspace — most Design projects stay inline prototypes. Even when enabled, it also needs Builder credentials connected before it will run.
+
+</Callout>
+
+When enabled, Full App Building turns a design into a real, running app instead of an inline HTML prototype — backed by a live dev server in a cloud container, one branch per design. Screens on the canvas become real routes on that running app rather than saved HTML files, the same URL-backed model `/visual-edit` uses for a local dev server, just running remotely.
+
+Editing works differently here: a change gets queued first, then dispatched as a batch to the app's own coding agent, which applies it to the real codebase. This is asynchronous — dispatching a change doesn't mean it has landed yet, only that the app's agent has started on it. Once the app is in the shape you want, its branch can be pushed and deployed to a real URL, and a fusion-backed design's branch can also be diffed against an earlier version to review what changed before publishing.
+
+## What's next
+
+- [**Design**](/docs/template-design) — back to the overview
+- [**Brand Systems and Figma**](/docs/template-design-brand-and-figma) — design systems and Figma import
+- [**Quality Passes and Components**](/docs/template-design-quality-and-components) — the audit/screenshot pass and reusable components
+- [**Extending Design**](/docs/template-design-developers) — the full action reference, including the fusion action group

package/docs/content/template-design-developers.mdx

@@ -0,0 +1,358 @@
+---
+title: "Extending Design"
+description: "The data model, action reference, and editor extension points for forking or building on the Design template."
+---
+
+# Extending Design
+
+This page is for anyone forking the Design template or building on top of it directly: the data model, the full action surface, and how the editor's overview canvas and extension points fit together.
+
+### Quick start
+
+```bash
+npx @agent-native/core@latest create my-design --standalone --template design
+```
+
+See [Getting started](/docs/getting-started) for installing dependencies, running the dev server, and the rest of the setup. For a workspace with Design alongside other apps, run `npx @agent-native/core@latest create my-platform` and pick Design during setup.
+
+### Where the code lives
+
+<FileTree
+  id="doc-block-design12"
+  title="templates/design/ — actions and skills"
+  entries={[
+    { path: "actions/", note: "~240 files — one per agent-callable operation" },
+    { path: "actions/create-design.ts", note: "Create the empty design shell" },
+    {
+      path: "actions/generate-design.ts",
+      note: "Write generated HTML/JSX file content",
+    },
+    {
+      path: "actions/edit-design.ts",
+      note: "Surgical search/replace edits to an existing file",
+    },
+    {
+      path: "actions/export-coding-handoff.ts",
+      note: "The canonical design-to-code handoff bundle",
+    },
+    { path: "app/routes/design.$id.tsx", note: "The editor route" },
+    { path: "app/routes/present.$id.tsx", note: "Presentation / share view" },
+    {
+      path: "server/db/schema.ts",
+      note: "Drizzle schema — designs, files, versions, systems, shares, plus 7 feature tables",
+    },
+    {
+      path: ".agents/skills/design-generation/SKILL.md",
+      note: "5-phase generation flow, aesthetic quality bar",
+    },
+    {
+      path: ".agents/skills/design-systems/SKILL.md",
+      note: "Brand tokens, Figma import/read/paste",
+    },
+    {
+      path: ".agents/skills/full-app-build/SKILL.md",
+      note: "Flag-gated fusion (full app) mode",
+    },
+  ]}
+/>
+
+Core routes in the UI live under `templates/design/app/routes/`: `_index.tsx` (list), `design.$id.tsx` (editor), `present.$id.tsx` (presentation), `design-systems.tsx` and `design-systems_.setup.tsx`, `templates.tsx`, `examples.tsx`, `extensions.tsx` and its nested routes, `observability.tsx`, `visual-edit.tsx`, plus `settings.tsx` and `team.tsx`.
+
+## Data model
+
+All data lives in SQL via Drizzle ORM. Schema: `templates/design/server/db/schema.ts`. Designs and design systems carry the standard `ownableColumns` and a matching framework shares table, so they slot into the per-user / per-org sharing model.
+
+The table below covers the core ownable resources — designs, files, templates, versions, and design systems.
+
+| Table                                    | What it holds                                                                                                                                    |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `designs`                                | A design project — `title`, `description`, `project_type` (`prototype` / `other`), the `data` JSON blob, and an optional `design_system_id` link |
+| `design_files`                           | Individual files belonging to a design (`filename`, `content`, `file_type` defaulting to `html`)                                                 |
+| `design_templates`                       | Reusable template metadata, dimensions, defaults, source design reference, and locked-layer count                                                |
+| `design_template_files`                  | Snapshotted template files copied into a normal editable design when a user starts from a template                                               |
+| `design_template_shares`                 | Framework shares table for private, org, explicitly shared, and public template discovery                                                        |
+| `design_versions`                        | Point-in-time `snapshot`s of a design with an optional `label`, for history and rollback                                                         |
+| `design_systems`                         | Reusable brand tokens — `data` (colors/typography/spacing), `assets`, `custom_instructions`, and an `is_default` flag                            |
+| `design_shares` / `design_system_shares` | Framework shares tables mapping principals (users or orgs) to roles (viewer, editor, admin)                                                      |
+
+<DataModel
+  id="doc-block-design11"
+  title="Design data model"
+  summary={
+    "A design owns its files and versioned snapshots, and optionally links a reusable design system. Both designs and systems are ownable, each with a framework shares table."
+  }
+  entities={[
+    {
+      id: "designs",
+      name: "designs",
+      note: "A design project (ownable)",
+      fields: [
+        {
+          name: "id",
+          type: "id",
+          pk: true,
+        },
+        {
+          name: "title",
+          type: "text",
+        },
+        {
+          name: "description",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "project_type",
+          type: "text",
+          note: "prototype / other",
+        },
+        {
+          name: "data",
+          type: "json",
+          note: "starts as {}",
+        },
+        {
+          name: "design_system_id",
+          type: "id",
+          fk: "design_systems.id",
+          nullable: true,
+        },
+      ],
+    },
+    {
+      id: "files",
+      name: "design_files",
+      note: "Files in a design",
+      fields: [
+        {
+          name: "design_id",
+          type: "id",
+          fk: "designs.id",
+        },
+        {
+          name: "filename",
+          type: "text",
+        },
+        {
+          name: "content",
+          type: "text",
+        },
+        {
+          name: "file_type",
+          type: "text",
+          note: "defaults to html",
+        },
+      ],
+    },
+    {
+      id: "versions",
+      name: "design_versions",
+      note: "History / rollback",
+      fields: [
+        {
+          name: "design_id",
+          type: "id",
+          fk: "designs.id",
+        },
+        {
+          name: "snapshot",
+          type: "json",
+        },
+        {
+          name: "label",
+          type: "text",
+          nullable: true,
+        },
+      ],
+    },
+    {
+      id: "systems",
+      name: "design_systems",
+      note: "Reusable brand tokens (ownable)",
+      fields: [
+        {
+          name: "id",
+          type: "id",
+          pk: true,
+        },
+        {
+          name: "data",
+          type: "json",
+          note: "colors / typography / spacing",
+        },
+        {
+          name: "assets",
+          type: "json",
+          nullable: true,
+        },
+        {
+          name: "custom_instructions",
+          type: "text",
+          nullable: true,
+        },
+        {
+          name: "is_default",
+          type: "boolean",
+        },
+      ],
+    },
+    {
+      id: "design_shares",
+      name: "design_shares",
+      note: "Framework shares table",
+      fields: [
+        {
+          name: "design_id",
+          type: "id",
+          fk: "designs.id",
+        },
+        {
+          name: "role",
+          type: "text",
+          note: "viewer / editor / admin",
+        },
+      ],
+    },
+    {
+      id: "system_shares",
+      name: "design_system_shares",
+      note: "Framework shares table",
+      fields: [
+        {
+          name: "design_system_id",
+          type: "id",
+          fk: "design_systems.id",
+        },
+        {
+          name: "role",
+          type: "text",
+          note: "viewer / editor / admin",
+        },
+      ],
+    },
+  ]}
+  relations={[
+    {
+      from: "designs",
+      to: "files",
+      kind: "1-n",
+    },
+    {
+      from: "designs",
+      to: "versions",
+      kind: "1-n",
+    },
+    {
+      from: "systems",
+      to: "designs",
+      kind: "1-n",
+      label: "applied to",
+    },
+    {
+      from: "designs",
+      to: "design_shares",
+      kind: "1-n",
+    },
+    {
+      from: "systems",
+      to: "system_shares",
+      kind: "1-n",
+    },
+  ]}
+/>
+
+A design project is a shell until it has content: `create-design` makes an empty row (`data: "{}"`), then `generate-design` writes the actual standalone HTML/JSX files. The generated artifact, the editable source, and every export all come from the same HTML, so there is no separate "AI mockup" format to translate. A linked design system supplies tokens and `custom_instructions` that the agent honors on every generation pass.
+
+Seven more tables back features covered elsewhere in this tree rather than the core resource model: `design_localhost_connections` and `design_localhost_write_grants` back the [`/visual-edit` bridge](/docs/template-design-collaboration-and-full-apps#visual-edit), `component_index` backs [reusable components](/docs/template-design-quality-and-components#components), `motion_timeline` backs [editable motion](/docs/template-design-quality-and-components#motion), `design_state` holds named alternate states, static fixtures, and live-app captures for a design, `design_fusion_edits` backs the [fusion edit queue](/docs/template-design-collaboration-and-full-apps#full-app-building), and `design_review_snapshot` caches the accessibility findings and visual diff behind `get-design-review` (see [the audit pass](/docs/template-design-quality-and-components#audit-and-screenshot)).
+
+Persisted review comments and threads (`get-review-feedback`, `resolve-review-thread`, and the rest — see [review feedback](/docs/template-design-collaboration-and-full-apps#review-feedback)) are not a Design-specific table at all: they're the shared framework review system from `@agent-native/core/review` (`agent_review_comments` / `agent_review_statuses`), scoped to a design the same way any app can attach it.
+
+## Key actions
+
+Every design-specific operation is a TypeScript file in `templates/design/actions/`, auto-mounted at `POST /_agent-native/actions/:name` and runnable from the CLI as `pnpm action <name>`. The groupings:
+
+- **Designs** — `create-design` (empty shell), `generate-design` (write generated HTML/JSX content), `edit-design`, `update-design`, `get-design`, `list-designs`, `duplicate-design`, `delete-design`, `apply-tweaks` for persisting live tweak-knob values, `present-design-variants` for the side-by-side variant picker, `show-design-questions`, and `generate-screens`.
+- **Files** — `create-file`, `update-file`, `list-files`, `delete-file`.
+- **Templates** — `list-design-templates`, `create-design-from-template`, `save-design-as-template`, `delete-design-template`.
+- **Design systems & brand import** — `create-design-system`, `update-design-system`, `get-design-system`, `list-design-systems`, `delete-design-system`, `set-default-design-system`, `analyze-brand-assets`, `import-from-url`, `index-design-system-with-builder`, `import-design-tokens`, `import-document`, `import-design-project`.
+- **Figma** — `import-figma-frame`, `import-figma-clipboard`, `get-figma-design-context`, `get-figma-styles`, `get-figma-connection-status`, `list-figma-library-assets`, `insert-figma-library-asset`, `hydrate-figma-paste-images`.
+- **Breakpoints and screen states** — `add-breakpoint`, `remove-breakpoint`, `set-active-breakpoint`, `create-design-state`, `apply-design-state`, `capture-design-state`, `list-design-states`, `delete-design-state`.
+- **Components** — `create-component`, `index-components`, `get-component-details`, `preview-component-prop-edit`, `apply-component-prop-edit`, `detach-component-instance`, `swap-component-instance`, `go-to-main-component`, `open-component-source`.
+- **Motion & shaders** — `get-motion-timeline`, `apply-motion-edit`, `remove-motion-timeline`, `apply-shader`, `apply-shader-fill`, `preview-shader-fill`, `get-shader`.
+- **Quality** — `run-design-audit`, `apply-a11y-fix`, `take-design-screenshot`, `get-design-review`.
+- **Review feedback** (framework-level, not in `templates/design/actions`) — `get-review-feedback`, `create-review-comment`, `reply-review-comment`, `resolve-review-thread`, `send-review-thread-to-agent`, `consume-review-feedback`, `list-review-comments`, `delete-review-comment`, `set-review-status`.
+- **Export & handoff** — `export-html`, `export-zip`, `export-pdf`, `export-svg`, `export-design-as-figma-svg`, `export-coding-handoff`.
+- **Full App Building** (fusion, flag-gated) — `create-fusion-app`, `sync-fusion-app`, `add-fusion-screens`, `queue-fusion-edit`, `list-fusion-edits`, `apply-fusion-edits`, `send-fusion-message`, `push-fusion-app`, `deploy-fusion-app`, `get-fusion-deploy-status`, `create-design-branch`, `get-design-branch-diff`, `deploy-design-preview`, `migrate-inline-design-to-app`, `connect-builder-app`.
+- **Localhost bridge** (`/visual-edit`) — `connect-localhost`, `list-localhost-connections`, `add-localhost-screens`, `request-localhost-write-consent`, `grant-localhost-write-consent`, `revoke-localhost-write-consent`.
+- **Local/code source editing** — `read-source-file`, `apply-source-edit`, `list-source-files`, `get-code-layer-projection`, `read-local-file`, `write-local-file`, `list-local-files` — for localhost- and fusion-backed designs where the underlying files aren't inline HTML rows.
+- **Context & navigation** — `view-screen` (current design, open file, view, pending question or variant choice), `get-design-snapshot` (current state for an external agent to continue from), and `navigate`.
+
+### Working with the agent
+
+The agent always knows what you have open. The current design, the open file, the active view, and any pending question or variant choice are returned by `view-screen` and injected into every message, so you can say "make this denser" or "export this variant" without naming the design.
+
+Because a design is just standalone HTML/JSX files, the agent edits the same source the preview renders and every export comes from — there is no separate "AI mockup" format to translate. Select text or a region in the preview and hit Cmd+I to focus the agent on exactly that part.
+
+## Editor model
+
+Design is overview-first for multi-screen work. After generation or broad
+updates, the editor opens the screen overview: an infinite canvas where each
+screen is a static frame you can select, move, resize, drop, or duplicate.
+Use a frame's full-view button when one screen needs focused scrolling or
+prototype interaction.
+
+Single-screen mode is for scrolling, interacting with prototype behavior, and
+editing the DOM/code layers inside one rendered file. The layers panel reflects
+that split: screens are top-level frames, with nested DOM/code layers for the
+active screen.
+
+Every screen is one document rendered at different widths, not separate
+copies per breakpoint: a base (widest) frame cascades down, and edits made at
+a narrower active breakpoint persist as width-scoped overrides on top of it.
+
+## Editor extensions
+
+The editor includes an **Extensions** inspector tab after **Tweaks**. It works
+like a Design-specific plugin lane: users can click **+ Extension** to ask the
+agent to build an extension, or install an extension that declares the
+`design.editor.inspector` slot — using the framework's `create-extension`,
+`add-extension-slot-target`, and `install-extension` actions, not a
+Design-specific action.
+
+Design extensions render inline beside the artboard through the standard
+extension sandbox. The host passes `window.slotContext` and
+`window.onSlotContext(...)` updates with the current `designId`, active file,
+screen list, selected screen ids, selected element metadata, view mode, zoom,
+active tool, and tweak values. That lets an extension show information about
+the current selection, offer style controls, or build compact workflows around
+the open design.
+
+For deterministic work, extensions can call app actions through the extension
+bridge. For AI-driven changes, have the extension call
+`agentNative.chat.send(...)` with the selected element selector/source id and
+requested change. The agent should call `view-screen` first, then use
+`apply-visual-edit` for element style, class, text, or move changes, or
+`update-design` / `generate-design` with `canvasFrames` for artboard placement
+changes. See [Extensions](/docs/extensions#capabilities) for the
+sandbox, persistent state, and bridge APIs.
+
+## Customizing it
+
+Design is a complete, cloneable template. Some practical extension ideas:
+
+- "Add a reusable ecommerce design system with our tokens and sample components."
+- "Add an export step that uploads the ZIP to our internal review system."
+- "Let me paste existing landing-page HTML and ask the agent for three stronger versions."
+- "Add a saved prompt library for product-page, dashboard, and onboarding-screen briefs."
+- "Add a custom PDF export preset for stakeholder review."
+
+The agent edits routes, components, actions, and SQL-backed models as needed. See [Templates](/docs/cloneable-saas) for the full clone, customize, deploy flow, and [Getting Started](/docs/getting-started) if this is your first agent-native template.
+
+## What's next
+
+- [**Design**](/docs/template-design) — back to the overview
+- [**Brand Systems and Figma**](/docs/template-design-brand-and-figma) — design systems and Figma import
+- [**Quality Passes and Components**](/docs/template-design-quality-and-components) — the audit/screenshot pass, components, motion, shaders
+- [**Review, Handoff, and Full Apps**](/docs/template-design-collaboration-and-full-apps) — visual editing, review feedback, export, and fusion mode
+- [**Context Awareness**](/docs/context-awareness) — how the agent knows what the user is viewing
+- [**Creating Templates**](/docs/creating-templates) — current build patterns for agent-native templates