@agent-native/core 0.122.3 → 0.123.0

package/docs/content/template-design-quality-and-components.mdx

@@ -0,0 +1,95 @@
+---
+title: "Quality Passes and Components"
+description: "The accessibility and screenshot audit Design runs before calling a prototype ready, plus reusable components, durable motion timelines, and code-backed shader effects."
+---
+
+# Quality Passes and Components
+
+Design treats a finished-looking prototype and a ready one as different things. This page covers the automatic checks the agent runs before it calls a design done, and three ways to keep a growing prototype consistent: reusable components, editable motion, and code-backed visual effects.
+
+## Why the results don't look generic
+
+Generic AI output happens when one prompt has to pick a font, a color, a layout, and the final code all at once — the safe answer is always the same average look. Design splits that decision into steps instead: it settles on a direction first (asking a couple of quick questions when a prompt is vague), shows a few genuinely different variants side by side so you pick a look rather than getting the first idea, and only then writes the code for the version you chose. That's why two designs from the same account don't come out looking like siblings, and why fonts and colors don't default to the same handful of overused choices.
+
+## The accessibility and screenshot audit {#audit-and-screenshot}
+
+Before reporting a design as ready, the agent runs two automatic passes. The first checks the HTML itself for missing image and field labels, small tap targets, focus visibility, whether animation respects a "reduce motion" preference, a contrast hint, and — on a multi-screen design — whether the shared colors and fonts have drifted between screens. Anything it can fix on its own gets fixed automatically; everything else gets fixed by hand before moving on. A design with open issues from this pass is not considered ready.
+
+<Diagram id="doc-block-design6" title="Generate, check, fix" summary={"Every generation or edit runs through an automatic audit and screenshot pass before the agent calls a design ready."}>
+
+```html
+<div class="diagram-qualityloop">
+  <div class="diagram-box" data-rough>
+    Generate / edit<br /><small class="diagram-muted"
+      >generate-design · edit-design</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box" data-rough>
+    Audit + screenshot<br /><small class="diagram-muted"
+      >run-design-audit · take-design-screenshot</small
+    >
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill warn">Fix</span
+    ><small class="diagram-muted">apply-a11y-fix · edit-design</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-panel center">
+    <span class="diagram-pill ok">Ready</span
+    ><small class="diagram-muted">clean audit + clean screenshot</small>
+  </div>
+</div>
+```
+
+```css
+.diagram-qualityloop {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  flex-wrap: wrap;
+}
+.diagram-qualityloop .diagram-arrow {
+  font-size: 20px;
+  line-height: 1;
+}
+.diagram-qualityloop .center {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 4px;
+}
+```
+
+</Diagram>
+
+The second pass renders the design in a real browser at both desktop and mobile width and checks the actual computed contrast, whether anything overflows its container, broken images, and browser console errors — the same things a person would notice looking at it, checked against the real rendered page instead of by eye.
+
+## Reusable components {#components}
+
+Once a card, button, or nav item repeats three or more times in a design, it can be promoted into a named component instead of staying three separate copies. Existing components are recognized automatically too, so the agent doesn't reinvent a "Feature Card" that's already there. Selecting a component instance opens an inspector showing its variants and props; changing a prop can preview instantly and apply to every instance of that component, or one instance can be detached to diverge on its own. A "Go to main component" link jumps back to the original definition.
+
+<WireframeBlock id="doc-block-design7">
+  <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'>Pricing screen</h1><span class='wf-pill accent'>Inspector</span><div style='flex:1'></div><button>Tweaks</button><button class='primary'>Extensions</button></div><div class='wf-card' style='flex:1;display:grid;grid-template-columns:1fr 260px;gap:14px'><div class='wf-box' style='display:grid;grid-template-columns:repeat(3,1fr);gap:10px;padding:20px'><div class='wf-card' style='min-height:110px'></div><div class='wf-card' style='min-height:110px;outline:2px dashed var(--wf-line)'></div><div class='wf-card' style='min-height:110px'></div></div><div style='display:flex;flex-direction:column;gap:10px;border-left:1.4px solid var(--wf-line);padding-left:14px'><strong>Component · PricingCard</strong><span class='wf-muted'>3 instances on this screen</span><div class='wf-card'><strong>title</strong><span class='wf-muted'>\"Pro plan\"</span></div><div class='wf-card'><strong>price</strong><span class='wf-muted'>\"$49/mo\"</span></div><div class='wf-card'><strong>featured</strong><span class='wf-muted'>true</span></div><button>Swap instance</button><button>Detach instance</button><span class='wf-pill'>Go to main component</span></div></div></div>"
+    }
+  />
+</WireframeBlock>
+
+## Motion {#motion}
+
+Motion in Design is deliberate rather than a uniform default — quick for a hover or button press, a little longer for a panel or modal, and at most one bigger orchestrated reveal on page load. Unlike a one-shot CSS animation baked into the markup, motion is stored as its own editable timeline: it can be inspected and adjusted after the fact the same way a color tweak can, without re-generating the whole screen.
+
+## Shader fills {#shader-fills}
+
+Animated backgrounds and effects — waves, noise, mesh gradients, grain, halftone — can be built as real, editable code instead of a stock video or GIF. Each one is a small shader with a handful of named controls (speed, color, center point) that show up as sliders in the inspector, and the underlying code is visible and editable directly in the Code panel. A library of curated presets covers common looks as a starting point, and from there it's the user's code to change.
+
+## 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
+- [**Review, Handoff, and Full Apps**](/docs/template-design-collaboration-and-full-apps) — visual editing, review feedback, and export
+- [**Extending Design**](/docs/template-design-developers) — the full action reference

package/docs/content/template-design.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Design"
-description: "An agent-native HTML prototyping studio — generate, refine, preview, and export interactive Alpine/Tailwind designs with an agent."
+description: "An agent-native HTML prototyping studio — describe a screen, compare variants, tweak the result, and export real Alpine/Tailwind code with the agent."
 ---
 
 # Design
 
-Design is an agent-native HTML prototyping studio. Instead of a layered drawing canvas, the agent generates complete self-contained Alpine/Tailwind HTML prototypes, renders them in an iframe, and lets you refine the result with prompts and tweak controls.
+Design is an agent-native HTML prototyping studio. Instead of a layered drawing canvas, the agent generates complete, self-contained Alpine/Tailwind HTML prototypes, shows them in a live preview, and lets you refine the result with prompts and tweak controls.
 
-<WireframeBlock id="doc-block-1c2i95a">
+<WireframeBlock id="doc-block-design1">
   <Screen
     surface="desktop"
     html={
@@ -18,7 +18,7 @@ Design is an agent-native HTML prototyping studio. Instead of a layered drawing
 
 When you open the app, the generated prototype is the center of the workspace, with preview modes, prompt revisions, and export controls close at hand. Everything the agent produces is real HTML you can refine, export, or hand off.
 
-<Diagram id="doc-block-1wju9qc" title="One artifact, no translation" summary={"The agent generates standalone Alpine/Tailwind HTML; the iframe, the editable source, and every export all read the same files. A linked design system feeds tokens into each pass."}>
+<Diagram id="doc-block-design2" title="One artifact, no translation" summary={"The agent generates standalone Alpine/Tailwind HTML; the preview, the editable source, and every export all read the same files. A linked design system feeds tokens into each pass."}>
 
 ```html
 <div class="diagram-design">
@@ -35,14 +35,14 @@ When you open the app, the generated prototype is the center of the workspace, w
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
   <div class="diagram-box" data-rough>
-    iframe preview<br /><small class="diagram-muted"
+    Live preview<br /><small class="diagram-muted"
       >tweak knobs · Cmd+I refine</small
     >
   </div>
   <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
   <div class="diagram-panel center">
     <span class="diagram-pill ok">Export</span
-    ><small class="diagram-muted">HTML · ZIP · PDF · handoff</small>
+    ><small class="diagram-muted">HTML · ZIP · PDF · Figma SVG</small>
   </div>
 </div>
 ```
@@ -84,17 +84,17 @@ When you open the app, the generated prototype is the center of the workspace, w
 - **You want a polished landing-page concept, product UI direction, or brand exploration** that can leave the tool as real HTML — not a layered drawing canvas.
 - **You want a working interactive prototype**, with Alpine interactions and Tailwind styling, instead of static mockups.
 - **You want to compare directions fast**, generate a few variants, pick the strongest, and keep refining.
-- **You want design output you own** — export HTML, ZIP, or PDF, or hand the prototype to a coding tool.
+- **You want design output you own** — export HTML, ZIP, PDF, or a Figma-ready vector file, or hand the prototype to a coding tool.
 
 ## What you can do with it
 
-- **Generate complete prototypes.** Describe the screen or page you need and the agent creates a working HTML document with Tailwind styling and Alpine interactions.
-- **Start from reusable templates.** Choose a sized starter for ads, one-pagers, landing pages, and more, or save any inline design as a template. A prompt refines the copied design while locked logo, background, and other fixed layers stay unchanged.
-- **Compare variants.** Start with multiple directions, pick the strongest one, then continue refining.
+- **Generate complete prototypes.** Describe the screen or page you need and the agent writes a working HTML document with Tailwind styling and Alpine interactions.
+- **Start from a template.** Choose a sized starter for ads, one-pagers, landing pages, and more, or save any inline design as a template. A prompt refines the copied design while locked layers — logo, background, other fixed pieces — stay unchanged.
+- **Compare variants.** Start with a few different directions, pick the strongest one, then continue refining.
 - **Tweak visually.** Use the built-in tweak controls for common changes, or ask the agent for copy, layout, color, spacing, and interaction updates.
-- **Apply design systems.** Save and reuse design-system preferences so generated work stays closer to your brand.
-- **Import references.** Bring in existing HTML or reference material as context for a new design pass.
-- **Export real files.** Export HTML, ZIP, or PDF from the generated prototype.
+- **Apply a brand.** Link a design system so every generation stays on-brand, import brand from a website or codebase, or bring in a Figma frame or file for a pixel-accurate starting point. See [Brand Systems and Figma](/docs/template-design-brand-and-figma).
+- **Keep quality consistent.** The agent runs an accessibility and visual check before calling a prototype ready, and repeated patterns can become reusable components. See [Quality Passes and Components](/docs/template-design-quality-and-components).
+- **Export real files.** Export HTML, ZIP, PDF, or a genuinely vector Figma SVG, or hand the prototype to a coding agent with a ready-made handoff bundle. See [Review, Handoff, and Full Apps](/docs/template-design-collaboration-and-full-apps).
 
 ## Getting started
 
@@ -114,341 +114,17 @@ Live demo: [design.agent-native.com](https://design.agent-native.com).
 - "Create three landing-page directions for a technical analytics product."
 - "Make this dashboard denser and easier to scan for an operations team."
 - "Apply our saved design system and simplify the mobile layout."
+- "Paste in this Figma frame link and match it exactly."
+- "Turn this repeated card into a reusable component."
 - "Export this prototype as a ZIP once the final variant is selected."
-- "Turn this HTML into a stronger pricing page without changing the brand colors."
 
-## For developers
-
-The rest of this doc is for anyone forking the Design template or extending it.
-
-### Quick start
-
-```bash
-npx @agent-native/core@latest create my-design --standalone --template design
-cd my-design
-pnpm install
-pnpm dev
-```
-
-### 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. Seven more tables in the same schema back features described elsewhere in this doc rather than the core resource model: `design_localhost_connections` and `design_localhost_write_grants` (localhost source mode), `component_index` (component indexing), `motion_timeline` (motion), `design_state` (editor state snapshots), `design_fusion_edits` (full-app fusion mode), and `design_review_snapshot` (review snapshots).
-
-| 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-1hb5m0c"
-  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.
-
-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`, plus `settings.tsx` and `team.tsx`.
-
-### Key actions
-
-Every agent-callable 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), `update-design`, `get-design`, `list-designs`, `duplicate-design`, `delete-design`, and `apply-tweaks` for persisting live tweak-knob values (accent color, density, etc.).
-- **Files** — `create-file`, `update-file`, `list-files`, `delete-file` for the files inside a design project.
-- **Design systems** — `create-design-system`, `update-design-system`, `get-design-system`, `list-design-systems`, `delete-design-system`, `set-default-design-system`, and `analyze-brand-assets` for gathering brand data ahead of analysis.
-- **Import** — `index-design-system-with-builder` for Builder-backed code/GitHub/Figma file design-system indexing, plus `import-from-url`, `import-document` (DOCX/PPTX/PDF/XLSX), and `import-design-project` for other sources.
-- **Export & handoff** — `export-html`, `export-pdf`, `export-svg`, `export-zip`, and `export-coding-handoff` to turn a design into a coding-tool handoff.
-- **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 iframe renders and every export comes from — there is no separate "AI mockup" format to translate. A linked design system supplies tokens and `custom_instructions` the agent honors on every generation pass. 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.
-
-### Tweaks
-
-Tweaks are named controls for quickly changing the most useful visual properties
-of a design without editing its source. A design can expose color swatches,
-segmented choices, sliders, and toggles for properties such as accent color,
-corner radius, spacing, density, or visibility. Each control is connected to a
-CSS custom property used by the rendered design, so the preview updates as you
-adjust it.
-
-Tweaks follow the editor's cascade. A value set on the base design is inherited
-by its responsive breakpoints and states. Changing a tweak while a breakpoint or
-state is active creates an override for that context; resetting the control
-removes the override and returns to the inherited value. Saved tweak values stay
-with the design. Use **Add tweak controls** or ask the agent to expose another
-visual property when the panel does not include the control you need.
-
-Install `/visual-edit` when a coding agent should open a running local app in
-Design instead of generating standalone prototype HTML:
-
-```bash
-npx @agent-native/core@latest skills add visual-edit
-```
-
-After the target app dev server is running, `/visual-edit` uses
-`npx @agent-native/core@latest design connect` plus `add-localhost-screens` to
-place each requested path or URL as its own URL-backed iframe screen. Numbered
-flows such as `localhost:1234/onboarding/1`, `/onboarding/2`, and
-`/onboarding/3` stay as separate ordered screens in overview mode.
-
-The `/visual-edit` entry route can load before the viewer signs in, and public
-`/design/:id` links can render read-only public designs without a session.
-Persisting the screen layout, generating new screens, or sharing still creates
-account-backed Design data: signed-out users go through
-`/_agent-native/sign-in?return=...`, then Design saves or copies the project
-into that account before opening the share dialog.
-
-For stable layer names, add `data-agent-native-layer-name` to meaningful
-elements. Design uses it before semantic/text fallbacks and can persist layer
-renames by editing that attribute. Inline HTML supports local code-layer edits
-for text, classes, styles, attributes, source order, and small structural
-changes; visual code-layer edits are HTML-only today. Localhost source mode can
-register and resolve local route artboards, but local file reads/writes remain a
-bridge contract until explicit permission controls are hardened.
-
-### Design 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.
-
-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#what-an-extension-can-do) 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.
+Building on Design or forking the template? See [Extending Design](/docs/template-design-developers).
 
 ## What's next
 
+- [**Brand Systems and Figma**](/docs/template-design-brand-and-figma) — design systems, brand import, and Figma
+- [**Quality Passes and Components**](/docs/template-design-quality-and-components) — the audit/screenshot pass, reusable components, motion, shaders
+- [**Review, Handoff, and Full Apps**](/docs/template-design-collaboration-and-full-apps) — visual editing, review feedback, export, and fusion mode
+- [**Extending Design**](/docs/template-design-developers) — data model, actions, and editor extension points
 - [**Templates**](/docs/cloneable-saas) — the clone-and-own model
 - [**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

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

@@ -0,0 +1,121 @@
+---
+title: "Dispatch — architecture for developers"
+description: "How Dispatch's package and generated-app source are split, the orchestrator's remote agent registry, scaffolding a workspace with Dispatch, and customizing or remixing a curated workspace template."
+---
+
+# Dispatch — architecture for developers
+
+This page is for engineers extending Dispatch or forking the template: how the orchestrator finds other agents, how the published package and your generated app source are split, and how to add your own management screens or spin up a private remix of another template.
+
+## Orchestrator agent and remote agent registry {#orchestrator}
+
+The chat is set up as a router: it reads `AGENTS.md` and `LEARNINGS.md` and routes to specialist sub-agents or remote A2A agents. A2A agent manifests are workspace-runtime entries, not a checked-in template source folder: in a multi-app workspace, sibling apps under `apps/` are auto-discovered as A2A peers, with no manual registration needed. Dispatch calls them using the `call-agent` action.
+
+Server plugins register each connected channel's webhook (Slack, Microsoft Teams, Discord, Telegram, WhatsApp) and forward incoming messages to the orchestrator agent. Vault tables (secrets, grants, requests, approvals, audit logs) are Drizzle tables defined in the `@agent-native/dispatch` package (`packages/dispatch/src/db/schema.ts`); the template's own `templates/dispatch/server/db/index.ts` re-exports that same schema via `createGetDb` rather than declaring a template-local `server/db/schema.ts`.
+
+## Package vs app-owned surface split {#package-split}
+
+`@agent-native/dispatch` owns the shell, sidebar, vault schema, and every built-in page — vault, integrations, messaging, operations, destinations, metrics, thread debug, audit, identities, dreams, approvals, automations, and the extensions catalog. Most files under `templates/dispatch/app/routes/` are thin re-exports of those packaged pages (for example `export { default, meta } from "@agent-native/dispatch/routes/pages/operations";`); `integrations.tsx` is the one route that's a full custom page in the template, reusing shared package components directly. The app-owned action surface in `templates/dispatch/actions/` covers Workspace Connections, staged datasets, and the `provider-api-*` escape hatch — everything else (vault, dreams, resources, destinations, approvals, thread debug, audit, identities, metrics) is a packaged action from `@agent-native/dispatch/actions`.
+
+<FileTree
+  id="doc-block-dispatch7"
+  title="packages/dispatch vs templates/dispatch"
+  entries={[
+    {
+      path: "packages/dispatch/src/actions/",
+      note: "Vault, dreams, resources, destinations, approvals, thread-debug, audit, and identities actions",
+    },
+    {
+      path: "packages/dispatch/src/db/schema.ts",
+      note: "Vault, resources, destinations, dreams, approval, and audit tables",
+    },
+    {
+      path: "packages/dispatch/src/routes/pages/",
+      note: "Built-in screens: overview, vault, integrations, messaging, operations, destinations, metrics, thread-debug, audit, identities, tools, new-app, ...",
+    },
+    {
+      path: "templates/dispatch/actions/",
+      note: "App-owned: workspace connections, staged datasets, provider-api-catalog/docs/request, run, view-screen",
+    },
+    {
+      path: "templates/dispatch/app/routes/*.tsx",
+      note: "Mostly thin re-exports of the packaged pages; integrations.tsx is a full custom page",
+    },
+    {
+      path: "templates/dispatch/app/dispatch-extensions.tsx",
+      note: "Where a generated workspace registers its own nav items and query keys",
+    },
+    {
+      path: "templates/dispatch/AGENTS.md",
+      note: "Dispatch-specific agent instructions",
+    },
+  ]}
+/>
+
+## Scaffolding a workspace with Dispatch {#scaffolding}
+
+```bash
+npx @agent-native/core@latest create my-platform
+# pick "Dispatch" in the multi-select picker, plus whichever domain apps you want
+```
+
+If you prefer to name the template directly instead of using the picker:
+
+```bash
+npx @agent-native/core@latest create my-platform --template dispatch
+# add more apps in the same workspace as you go
+```
+
+Dispatch is usually scaffolded into a workspace alongside the apps it coordinates. For a workspace, Dispatch's shared auth, database, and brand are inherited from the workspace core — see [Multi-App Workspace](/docs/multi-app-workspace).
+
+There is no meaningful `--standalone` Dispatch: a control plane with nothing to coordinate is just an empty inbox. Scaffold it into a workspace with at least one domain app so it has agents to route to over A2A. (The flag still works and produces a runnable app, but the orchestrator has no specialists to delegate to until you add sibling apps.)
+
+From the workspace root, `pnpm install` and `pnpm dev` bring up the dev server — see [Getting started](/docs/getting-started) for the rest of local setup, including account creation and connecting an LLM provider.
+
+## Customizing it {#customize}
+
+Dispatch is a full template like any other — see [Templates](/docs/cloneable-saas). Ask the agent to "add a new integration for Datadog" or "route Slack DMs from channel X to the analytics agent" and it'll edit the routing config, add the webhook handler, and wire it up.
+
+For workspace-specific management screens, add local React Router pages and register them in `app/dispatch-extensions.tsx`. The generated workspace owns only the extra tab and route; `@agent-native/dispatch` keeps owning the shell, sidebar, built-in pages, and future package updates.
+
+<AnnotatedCode
+  id="doc-block-dispatch8"
+  title="app/dispatch-extensions.tsx"
+  filename="app/dispatch-extensions.tsx"
+  language="tsx"
+  code={
+    'import type { DispatchExtensionConfig } from "@agent-native/dispatch/components";\nimport { IconChartBar } from "@tabler/icons-react";\n\nexport const dispatchExtensions = {\n  navItems: [\n    {\n      id: "reports",\n      to: "/reports",\n      label: "Reports",\n      icon: IconChartBar,\n      section: "operations",\n    },\n  ],\n  queryKeys: ["list-reports"],\n} satisfies DispatchExtensionConfig;'
+  }
+  annotations={[
+    {
+      lines: "1",
+      note: "`DispatchExtensionConfig` is exported by the package so the generated workspace's extension file stays type-checked against it.",
+    },
+    {
+      lines: "5-13",
+      label: "Extra tab",
+      note: 'Each nav item needs a matching `app/routes/*.tsx` file at `to` — the sidebar renders it, but Dispatch\'s shell and built-in pages don\'t change. `section` is `"primary"` or `"operations"`.',
+    },
+    {
+      lines: "14",
+      label: "Live sync",
+      note: "`queryKeys` lists the action names your new route's queries use, so Dispatch's shared DB-sync refresh loop invalidates them too.",
+    },
+  ]}
+/>
+
+## Curated workspace template remix {#remix}
+
+Curated workspace templates are private remix sources for spinning up an independent app from a reviewed template — mail, calendar, analytics, slides, content, clips, brain, assets, forms, or design.
+
+- **`list-curated-workspace-templates`** returns the reviewed catalog: stable metadata, the live product URL, setup guidance, and whether each source template is already installed in the current workspace.
+- **`remix-workspace-template`** creates a private, independent copy. In a local runtime it scaffolds the template directly; in a hosted workspace it starts a Builder app-creation branch instead. Either way, the remix defaults to a `<template>-remix` app id, and the request is required to use empty or synthetic seed data only — it must never copy the source app's records, credentials, secrets, or private configuration.
+
+## What's next
+
+- [**Dispatch**](/docs/template-dispatch) — the workspace control plane overview
+- [**Secrets, integrations, and workspace connections**](/docs/template-dispatch-vault-integrations) — the vault, integrations, and Workspace Connections
+- [**Messaging, routing, and approvals**](/docs/template-dispatch-messaging-routing) — channels, routing, and approvals
+- [**Operating the workspace**](/docs/template-dispatch-operations) — jobs, Dreams, and the operator console
+- [**Creating Templates**](/docs/creating-templates) — the current build pattern for a full template
+- [**A2A Protocol**](/docs/a2a-protocol) — how Dispatch delegates to specialist agents