@agent-native/core 0.62.1 → 0.63.1

package/docs/content/server.md

@@ -189,9 +189,17 @@ Inbound webhooks should verify, persist, and return quickly. Long-running agent
 
 Do not rely on unawaited promises after returning a response. See [Messaging](/docs/messaging) for the canonical integration queue.
 
-## Programmatic H3 Servers {#create-server}
+## Advanced: Escape Hatches {#advanced-escape-hatches}
 
-For custom packages or tests that need an H3 app directly, `createServer()` returns a preconfigured app and router:
+Most templates never need these. Nitro file routes and the framework's agent
+chat plugin already wire up the app server and the production agent handler.
+Reach for them only when building a custom server integration outside the
+standard template plugin stack.
+
+### Programmatic H3 servers {#create-server}
+
+For custom packages or tests that need an H3 app directly, `createServer()`
+returns a preconfigured app and router:
 
 ```ts
 import { createServer } from "@agent-native/core/server";
@@ -205,11 +213,13 @@ router.get(
 );
 ```
 
-Most templates do not need this helper because Nitro file routes and framework plugins handle the app server.
+### Production agent handler {#agent-handler}
 
-## Production Agent Handler {#agent-handler}
-
-The framework's agent chat plugin mounts the production agent handler for templates. Only call `createProductionAgentHandler()` directly when building a custom server integration outside the standard template plugin stack.
+The framework's agent chat plugin already mounts the production agent handler
+for templates. Only call `createProductionAgentHandler()` directly when building
+a custom server integration outside the standard template plugin stack —
+otherwise customize the agent through `AGENTS.md`, skills, actions, and the
+agent chat plugin.
 
 ```ts
 import { createProductionAgentHandler } from "@agent-native/core/server";
@@ -219,5 +229,3 @@ const handler = createProductionAgentHandler({
   systemPrompt: "You are the app agent...",
 });
 ```
-
-Standard templates should customize the agent through `AGENTS.md`, skills, actions, and the agent chat plugin rather than hand-mounting this route.

package/docs/content/sharing.md

@@ -159,12 +159,7 @@ registerShareableResource({
 
 ## Security guarantees {#security}
 
-Sharing rides on the framework's broader data-scoping model. The two non-negotiable rules:
-
-- **No unscoped queries.** Every query against an ownable table must go through `accessFilter()` (lists), `resolveAccess()` (read-by-id), or `assertAccess()` (writes). A CI guard fails the build if a query against an ownable table runs without one of these helpers.
-- **Org isolation.** Resources tagged with an `org_id` are invisible to users from other orgs even to the agent. The active-org session value flows through to SQL, so cross-org leaks are impossible by construction.
-
-See [Security & Data Scoping](/docs/security) for the full model and threat surface.
+Sharing rides on the framework's broader data-scoping model — list/read/write access to ownable tables goes through `accessFilter()` / `resolveAccess()` / `assertAccess()`, and `org_id`-tagged resources are invisible across orgs. See [Security → Data Scoping](/docs/security#data-scoping) for the full pipeline, the CI guard, and the threat surface.
 
 ## See also {#see-also}
 

package/docs/content/skills-guide.md

@@ -15,7 +15,7 @@ Every skill's frontmatter `name` and `description` are always injected into the
 
 ## Framework skills {#framework-skills}
 
-These skills ship with the default template and are available in every new agent-native app:
+These are the skills bundled with the **default template**. The exact set available in any given app depends on the template you scaffolded from — check that template's `.agents/skills/` directory for what it actually ships.
 
 | Skill                 | When to use                                             |
 | --------------------- | ------------------------------------------------------- |
@@ -172,6 +172,8 @@ If the knowledge applies to _everyone_ working in the app ("always prefer CTEs o
 
 ---
 
+# Advanced
+
 ## App-backed skills — full details {#app-backed-skills-full}
 
 App-backed skills package an agent-native app as a skill marketplace artifact.

package/docs/content/template-analytics.md

@@ -221,4 +221,4 @@ To add a new data source, drop a script in `actions/` that calls the provider an
 
 To add a new chart type, extend the `ChartType` union in `app/pages/adhoc/sql-dashboard/types.ts`, handle it in `SqlChartCard.tsx`, and the agent can use it in any panel.
 
-For the broader pattern on extending templates, see the [adding-a-feature skill](/docs/skills-guide) and [actions](/docs/actions).
+For the broader pattern on extending templates, see the [Skills guide](/docs/skills-guide) and [Actions](/docs/actions).

package/docs/content/template-assets.md

@@ -7,10 +7,17 @@ description: "An agent-native digital asset manager and cross-agent generation s
 
 Assets is an agent-native workspace for creating and managing brand-consistent media. It organizes uploads and generated results into libraries and folders, lets teams collect examples for blog heroes, diagrams, landing pages, product shots, videos, and logos, then routes generation through the agent chat so every asset can be reviewed and refined.
 
-Use it when your team needs reusable visual direction and searchable source assets instead of one-off generic media prompts.
-
 ![Assets library for brand media and generated output](https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F769092170a14474f998cbca47384f891?format=webp&width=1200)
 
+When you open the app, you see your libraries and folders on the left, the assets in the selected library in the middle, and a chat composer for generating new media. The agent can browse, search, generate, refine, and export every asset through the same actions the UI uses.
+
+## When to pick it
+
+- **Your team needs reusable visual direction**, not one-off generic media prompts — collect approved logos, product shots, and style examples so generations stay on brand.
+- **You want generated media reviewed and refined**, with a full audit log of prompts, models, references, and lineage for every run.
+- **Other apps need an asset picker or generator** — Slides, Design, Content, a blog editor, or a site builder can embed the picker or call Assets over A2A.
+- **You want brand media available from your coding agent** — Codex, Claude Code, Claude, or ChatGPT can generate and pick assets without leaving the chat.
+
 ## Getting started
 
 Live demo: [assets.agent-native.com](https://assets.agent-native.com).
@@ -95,7 +102,9 @@ npx @agent-native/core@latest create my-assets --standalone --template assets
 
 ### Data model
 
-All data lives in SQL via Drizzle ORM (binary media lives in object storage, or the local file-upload fallback during development). Schema: `templates/assets/server/db/schema.ts`. Libraries carry the standard `ownableColumns` and a matching framework shares table, so they slot into the per-user / per-org sharing model. The SQL table names keep the legacy `image_*` prefix from when the app was called Images.
+All data lives in SQL via Drizzle ORM (binary media lives in object storage, or the local file-upload fallback during development). Schema: `templates/assets/server/db/schema.ts`. Libraries carry the standard `ownableColumns` and a matching framework shares table, so they slot into the per-user / per-org sharing model.
+
+Note: the SQL table names keep the legacy `image_*` prefix from when the app was called Images. They cover videos and other media too.
 
 | Table                            | What it holds                                                                                                                                                                            |
 | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

package/docs/content/template-brain.md

@@ -21,11 +21,35 @@ surfaces for connecting data, approving proposals, and inspecting cited memory.
 
 ![Brain company chat with cited memory sources](https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F9c9fe3b5b9494e33803cd3f494cba356?format=webp&width=1200)
 
+When you open the app, **Ask** is front and center — a clean chat over reviewed
+company memory. **Sources**, **Review**, and **Knowledge** sit alongside it as
+admin surfaces for connecting data, approving proposals, and inspecting cited
+entries.
+
+## When to pick it
+
 Use Brain when your team wants agents to answer questions like "why did we make
 this product decision?", "how does this in-development feature work?", or "what
 changed in this process?" with links back to the source conversation, meeting,
 or issue.
 
+Brain and Dispatch are complementary but do different jobs:
+
+- **Brain owns company memory.** It ingests sources, reviews raw captures,
+  distills durable facts/decisions/processes, answers from cited evidence, and
+  exposes approved knowledge to agents.
+- **Dispatch owns the workspace control plane.** It centralizes messaging,
+  secrets, recurring jobs, approvals, A2A orchestration, and the distribution
+  and approval of workspace-wide resources.
+
+In a multi-app workspace, Dispatch can route a question to Brain over A2A and
+can grant Brain shared provider credentials. Brain remains the specialist for
+approved source ingestion, review, retrieval, and cited Company Brain answers.
+Brain exposes read-only, citation-backed retrieval as its public A2A capability
+so Dispatch and sibling apps can ask company-memory questions — the A2A agent
+card is public discovery metadata, while retrieval still happens inside Brain's
+authenticated action surface.
+
 ## What you can do with it
 
 - **Ask cited questions.** Ask is the main product surface: a clean chat over
@@ -51,14 +75,6 @@ or issue.
   apps can use them as context. Both flows preview the exact Markdown before the
   resource is written or removed.
 
-## Useful prompts
-
-- "What did we decide about annual pricing, and where was that discussed?"
-- "Find the most recent onboarding-process change and cite the source."
-- "Summarize what this GitHub discussion means for the launch plan."
-- "Review the pending memory proposals and flag anything too vague to publish."
-- "Which sources are stale or failing sync?"
-
 ## Getting started
 
 Live demo: [brain.agent-native.com](https://brain.agent-native.com).
@@ -79,9 +95,17 @@ For a public demo, the seeded corpus demonstrates product-decision recall,
 citation links, supersede behavior, review gating, redaction, personal-content
 exclusion, and honest not-found behavior without connecting a real workspace.
 
+### Useful prompts
+
+- "What did we decide about annual pricing, and where was that discussed?"
+- "Find the most recent onboarding-process change and cite the source."
+- "Summarize what this GitHub discussion means for the launch plan."
+- "Review the pending memory proposals and flag anything too vague to publish."
+- "Which sources are stale or failing sync?"
+
 ## For developers
 
-The rest of this section is for anyone forking or extending the Brain template.
+The rest of this doc is for anyone forking the Brain template or extending it.
 
 ### Quick start
 
@@ -96,6 +120,12 @@ Open the app and choose **Start demo** to see cited memory without connecting a
 
 ### Data model
 
+Brain intentionally uses SQL text search and agentic query expansion — there is
+no vector-database requirement, so the template stays portable across SQLite,
+Postgres, Neon, D1, Turso, and similar hosts. Application state mirrors the
+current route, filters, and selected IDs so the agent always knows the current
+navigation and selection.
+
 Brain's schema lives in `templates/brain/server/db/schema.ts`. Eight tables:
 
 | Table                    | What it holds                                                                                                                                  |
@@ -124,17 +154,7 @@ Grouped by area (`templates/brain/actions/`):
 - **Context & navigation** — `view-screen`, `navigate`
 - **Provider APIs** — `provider-api-catalog`, `provider-api-docs`, `provider-api-request`
 
-### Customizing it
-
-Key places to look when extending Brain:
-
-- `templates/brain/actions/` — every agent-callable operation. Add a new file with `defineAction` to expose a new capability.
-- `templates/brain/app/routes/` — the UI surface: Ask, Sources, Review, Knowledge, Settings, and Team routes.
-- `templates/brain/.agents/skills/` — Brain-specific guidance for distillation and retrieval.
-- `templates/brain/AGENTS.md` — top-level agent guide. Update when you add major features.
-- `templates/brain/server/db/schema.ts` — data model. Additive migrations only.
-
-## Connecting sources
+### Connecting sources
 
 Brain resolves provider credentials from a granted workspace connection first,
 then from backward-compatible Brain-local or registered vault credentials.
@@ -171,44 +191,7 @@ notes, or any other source that can produce a bounded capture.
 Slack, Granola, and GitHub sources can opt into background `autoSync` with a
 poll cadence once review quality is proven.
 
-## Brain vs Dispatch
-
-Brain and Dispatch are complementary, but they do different jobs:
-
-- **Brain owns company memory.** It ingests sources, reviews raw captures,
-  distills durable facts/decisions/processes, answers from cited evidence, and
-  exposes approved knowledge to agents.
-- **Dispatch owns the workspace control plane.** It centralizes messaging,
-  secrets, recurring jobs, approvals, A2A orchestration, and the distribution
-  and approval of workspace-wide resources.
-
-In a multi-app workspace, Dispatch can route a question to Brain over A2A and
-can grant Brain shared provider credentials. Brain remains the specialist for
-approved source ingestion, review, retrieval, and cited Company Brain answers.
-Brain exposes read-only, citation-backed retrieval as its public A2A capability
-so Dispatch and sibling apps can ask company-memory questions — the A2A agent
-card is public discovery metadata, while retrieval still happens inside Brain's
-authenticated action surface.
-
-## Data model
-
-Brain intentionally uses SQL text search and agentic query expansion. There is
-no vector database requirement, so the template stays portable across SQLite,
-Postgres, Neon, D1, Turso, and similar hosts.
-
-- **Sources** hold connector configuration: provider, allow-listed channels or
-  repositories, sync cursors, review posture, and distillation state.
-- **Raw captures** store transcripts, channel exports, notes, and webhook
-  imports in portable SQL with dedupe keys and source metadata. Raw content is
-  redacted from listing/search surfaces by default.
-- **Distilled knowledge** holds atomic entries with kind, topic, entities,
-  confidence, exact evidence quotes, and supersede links.
-- **Proposals** queue company-tier or sensitive entries for review before they
-  become durable company memory.
-- **Application state** mirrors route, filters, and selected IDs so the agent
-  always knows the current navigation and selection.
-
-## Privacy and gating
+### Privacy and gating
 
 Brain is designed for company memory, not personal surveillance:
 
@@ -223,22 +206,31 @@ Brain is designed for company memory, not personal surveillance:
   approval, citation requirements, email redaction, and connector error
   notifications.
 
-## Customizing it
-
-The template follows the agent-native four-area contract:
+### Customizing it
 
-- **UI:** Ask, Search, Knowledge, Review, Sources, and Settings routes.
-- **Actions:** imports, source management, pilot reports, distillation, proposal
-  review, cited search, and navigation/context actions.
-- **Skills/instructions:** Brain-specific guidance for distillation and
-  retrieval in `templates/brain/.agents/skills/`.
-- **Application state:** route, filters, and selected IDs mirror into
-  `application_state` for agent context.
+Brain follows the agent-native four-area contract — change behavior by editing
+the matching area, and the agent can make these edits for you:
+
+- `templates/brain/app/routes/` — the UI surface: Ask, Search, Knowledge,
+  Review, Sources, Settings, and Team routes.
+- `templates/brain/actions/` — every agent-callable operation (imports, source
+  management, pilot reports, distillation, proposal review, cited search,
+  navigation/context). Add a new file with `defineAction` to expose a new
+  capability.
+- `templates/brain/.agents/skills/` — Brain-specific guidance for distillation
+  and retrieval. Update or add a skill when you teach the agent a new workflow.
+- `templates/brain/AGENTS.md` — top-level agent guide. Update when you add major
+  features.
+- `templates/brain/server/db/schema.ts` — data model. Additive migrations only;
+  route, filters, and selected IDs mirror into `application_state` for agent
+  context.
 
 Ask the agent to make changes for you — it can edit its own source. See
 [Self-Modifying Code](/docs/key-concepts#agent-modifies-code).
 
-See [Dispatch](/docs/dispatch) for the workspace control plane, the
-[Dispatch template](/docs/template-dispatch) for the scaffolded app,
-[Workspace](/docs/workspace) for shared resources, and
-[A2A Protocol](/docs/a2a-protocol) for cross-app delegation.
+## What's next
+
+- [**Dispatch**](/docs/dispatch) — the workspace control plane
+- [**Dispatch template**](/docs/template-dispatch) — the scaffolded coordination app
+- [**Workspace**](/docs/workspace) — shared resources across apps
+- [**A2A Protocol**](/docs/a2a-protocol) — cross-app delegation

package/docs/content/template-chat.md

@@ -12,12 +12,12 @@ If you want the smallest action-only runtime with no browser UI, start with [Pur
 <!-- screenshot:
   app: chat
   view: /
-  shows: Full-page chat app with standard left sidebar, chat threads on the left, centered composer, suggested prompts, and no domain data
+  shows: Full-page chat app with standard left sidebar, centered empty-state composer, model controls, and no domain data
   account: screenshot-account (no domain data needed — chat ships with no seed schema)
-  capture: 1400x800 viewport, cropped 90px from bottom (final 1400x710)
+  capture: 2434x1440 app screenshot
 -->
 
-![Chat template with a full-page agent chat surface and thread sidebar](/screenshots/chat.png)
+![Chat template with a centered agent composer and app navigation sidebar](/screenshots/chat.png)
 
 ## What's in it {#whats-in-it}
 
@@ -60,7 +60,35 @@ Or start with no UI and add a chat surface later:
 npx @agent-native/core@latest create my-agent --headless
 ```
 
-From there, copy the Chat template's `/` route and sidebar thread list into your app, or scaffold a Chat app and move your headless actions into its `actions/` directory. The key invariant stays the same: actions are the shared surface for chat, UI, HTTP, MCP, A2A, and CLI.
+From there, copy the Chat template's `/` route and sidebar thread list into your app, or scaffold a Chat app and move the actions from your headless agent into its `actions/` directory. The key invariant stays the same: actions are the shared surface for chat, UI, HTTP, MCP, A2A, and CLI.
+
+## First code to inspect {#first-code}
+
+- `actions/hello.ts` is the starter behavior the agent can call. Replace it or
+  add actions beside it.
+- `app/routes/_index.tsx` renders the full-page chat surface. Adjust the
+  suggestions, empty state, composer, or surrounding layout here.
+- `AGENTS.md` tells the built-in agent how to work inside this app.
+
+The chat page is intentionally thin:
+
+```tsx
+// app/routes/_index.tsx
+import { AgentChatSurface } from "@agent-native/core/client";
+
+export default function ChatRoute() {
+  return (
+    <AgentChatSurface
+      mode="page"
+      suggestions={[
+        "What can you do?",
+        "Help me customize this chat app",
+        "Show me the actions and pages I can add",
+      ]}
+    />
+  );
+}
+```
 
 ## Use your own agent backend {#own-agent-backend}
 

package/docs/content/template-clips.md

@@ -1,6 +1,6 @@
 ---
 title: "Clips"
-description: "Async screen recording, calendar-synced meeting notes, and push-to-talk voice dictation — all transcribed, summarized, and searchable in one app you own."
+description: "Async screen recording, calendar-synced meeting notes, and push-to-talk voice dictation — paste Clips links into agents and they can read transcripts, visuals, and summaries."
 ---
 
 # Clips
@@ -17,7 +17,7 @@ A capture-everything app: screen recordings, meeting notes from your calendar, a
 
 ![Clips library with recordings, folders, and spaces](/screenshots/clips.png)
 
-Think along the lines of Loom + Granola + Wispr Flow rolled into one app — but the agent is a first-class editor across every surface, and the recordings, meetings, and dictations are yours, not a SaaS vendor's.
+Think along the lines of Loom + Granola + Wispr Flow rolled into one app — but the agent is a first-class editor across every surface, and the recordings, meetings, and dictations are yours, not a SaaS vendor's. Clips also makes shared recordings agent-readable: paste a normal Clips share link into an agent, and it can "hear" the transcript and "see" timestamped frames even when the underlying model cannot ingest raw video or audio.
 
 ## What you can do with it
 
@@ -27,9 +27,28 @@ Think along the lines of Loom + Granola + Wispr Flow rolled into one app — but
 - **Get an auto-generated title, summary, and chapter markers** for every recording — the agent fills them in and keeps them current.
 - **Search across every transcript** — screen recordings, meetings, and dictations all in one library. "Find the clip where we discussed the rollout plan."
 - **Share clips** with per-clip permissions (public, team, private). Link tracking and threaded comments work too.
+- **Paste Clips links into agents** so they can discover the agent-readable context: metadata, transcript segments, recommended frames, and timestamped frame images without receiving the raw video file.
 - **Smart library views.** Group by project, filter by speaker, auto-tag based on content.
 - **Edit the transcript through chat.** "Fix the mis-transcribed word at 1:42." "Pull three quotes for a blog post." The agent edits the transcript and the UI updates live.
 
+## Agent-readable clips
+
+Paste a normal public Clips share link into an agent. The share page advertises
+a compact agent context URL, and that context points to the transcript and frame
+APIs, so models that only accept text or still images can still understand what
+happened in the recording.
+
+| Endpoint                                          | What agents get                                                                                                |
+| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `/api/agent-context.json?id=<recordingId>`        | Clip metadata, transcript status, chapters, CTAs, recommended frames, and links to the transcript/frame APIs   |
+| `/api/agent-transcript.json?id=<recordingId>`     | Timestamped transcript segments with `startMs`, `endMs`, readable timestamps, text, and optional source labels |
+| `/api/agent-frame.jpg?id=<recordingId>&atMs=<ms>` | A JPEG frame extracted from the video at an original-video timestamp                                           |
+
+The endpoints follow the same public/password/expiry rules as the share page.
+Password-protected clips require the password once; successful responses return
+short-lived tokenized links so downstream agents do not need the plaintext
+password.
+
 ## Getting started
 
 Live demo: [clips.agent-native.com](https://clips.agent-native.com).
@@ -43,7 +62,7 @@ Live demo: [clips.agent-native.com](https://clips.agent-native.com).
 4. **Search and reuse.** Ask for the clip, quote, action item, or decision you
    need, then share the result with the right visibility.
 
-## Useful Prompts
+### Useful prompts
 
 - "Summarize this clip for a product update."
 - "Find the meeting where we discussed the rollout plan."
@@ -55,7 +74,7 @@ Live demo: [clips.agent-native.com](https://clips.agent-native.com).
 
 The rest of this doc is for anyone forking the Clips template or extending it.
 
-### Scaffolding
+### Quick start
 
 ```bash
 npx @agent-native/core@latest create my-clips --standalone --template clips
@@ -70,6 +89,18 @@ Clips is a larger template with a native recorder (it ships a desktop companion
 2. **Google Calendar (optional).** To sync upcoming meetings, connect a Google Calendar account from Settings. The OAuth callback URL in dev is `http://localhost:8094/_agent-native/google/callback`. Set up a Google OAuth client in [Google Cloud Console](https://console.cloud.google.com/) with the Gmail and Google Calendar APIs enabled.
 3. **Screen-capture permissions.** On macOS, grant Screen Recording permission to the browser (or the desktop companion app) in System Settings → Privacy & Security → Screen Recording.
 
+### Key features (technical)
+
+**One library, three capture types.** Screen recordings, calendar-sourced meetings, and push-to-talk dictations all live in the same searchable library. Recordings and transcripts are deliberately split into separate tables so the library grid and the transcript view each render fast.
+
+**Transcript and AI pipeline.** Each recording gets timestamped transcript segments (`{startMs, endMs, text}`), an auto-generated title, summary, and chapter markers. `cleanup-transcript` and `finalize-meeting` are server-side media-pipeline calls; most other AI features (titles, summaries, quotes) delegate to the agent chat.
+
+**Non-destructive editing.** Trim, split, filler-word removal, silence removal, and stitching accumulate in a recording's `edits_json` rather than re-encoding. The client concatenates and exports through ffmpeg.wasm, so the original media stays intact.
+
+**Agent-readable share links.** A public Clips share link advertises a compact agent context URL that points at the transcript and frame APIs, so text- and image-only models can understand a recording without ingesting raw video — see [Agent-readable clips](#agent-readable-clips) above.
+
+**Meetings compose with recordings.** A meeting owns the recording it captures, but the `recordings` row stays the source of truth for the video and per-segment transcript instead of duplicating media.
+
 ### Data model
 
 All data lives in SQL via Drizzle ORM. Schema: `templates/clips/server/db/schema.ts`. Recordings, meetings, dictations, calendar accounts, and vocabulary all carry the standard `ownableColumns` and have a matching framework shares table, so they slot into the per-user / per-org sharing model.

package/docs/content/template-design.md

@@ -7,10 +7,17 @@ description: "An agent-native HTML prototyping studio — generate, refine, prev
 
 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.
 
-Use it when you want a polished landing page concept, product UI direction, brand exploration, or interactive prototype that can leave the tool as real HTML.
-
 ![Design studio showing generated HTML prototypes and tweak controls](https://cdn.builder.io/api/v1/image/assets%2F348da13fcd8b414c87de9066196f7266%2F961bedb713a94463b834c1f2f4643bcf?format=webp&width=1200)
 
+When you open the app, you see your designs on the left, the generated prototype rendered in an iframe in the middle, and the agent plus tweak controls on the right. Everything the agent produces is real HTML you can refine, export, or hand off.
+
+## When to pick it
+
+- **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.
+
 ## 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.
@@ -45,10 +52,13 @@ Live demo: [design.agent-native.com](https://design.agent-native.com).
 
 The rest of this doc is for anyone forking the Design template or extending it.
 
-### Scaffolding
+### Quick start
 
 ```bash
 npx @agent-native/core@latest create my-design --standalone --template design
+cd my-design
+pnpm install
+pnpm dev
 ```
 
 ### Data model
@@ -78,6 +88,12 @@ Every agent-callable operation is a TypeScript file in `templates/design/actions
 - **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 grid), `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 grid 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.
+
 ### Customizing it
 
 Design is a complete, cloneable template. Some practical extension ideas:

package/docs/content/template-dispatch.md

@@ -127,8 +127,17 @@ 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.)
+
 ## First local run {#first-local-run}
 
 From the workspace root:

package/docs/content/template-forms.md

@@ -41,7 +41,7 @@ Live demo: [forms.agent-native.com](https://forms.agent-native.com).
 4. **Connect destinations.** Route new submissions to Slack, Discord, Google
    Sheets, webhooks, or your own extension point.
 
-## Useful prompts
+### Useful prompts
 
 - "Create a beta signup form with role, team size, and priority use case."
 - "Add a required NPS question and a free-text follow-up."
@@ -51,10 +51,15 @@ Live demo: [forms.agent-native.com](https://forms.agent-native.com).
 
 ## For developers
 
-### Scaffolding
+The rest of this doc is for anyone forking the Forms template or extending it.
+
+### Quick start
 
 ```bash
 npx @agent-native/core@latest create my-forms --standalone --template forms
+cd my-forms
+pnpm install
+pnpm dev
 ```
 
 For a workspace with Forms alongside other apps:
@@ -65,6 +70,14 @@ npx @agent-native/core@latest create my-platform
 
 Pick Forms and any other templates you want during the workspace setup.
 
+### Key features (technical) {#key-features}
+
+Forms are defined as JSON field arrays (`FormField[]`) and stored in a single `fields` column — no separate table per field type. This makes the schema additive and the agent's edits surgical: changing a field label is a JSON-patch on one column, not a row update across a join table. All field types (text, email, number, long text, select, multi-select, checkbox, radio, date, rating, scale) are handled by the renderer and editor without schema changes.
+
+The public fill page is fully unauthenticated. `toPublicFormSettings` strips integration URLs and other owner-private settings before the form data reaches the browser, so secrets never leak to respondents.
+
+Integrations (Slack, Discord, Google Sheets, webhooks) are stored as settings inside the form's `settings` JSON column and executed server-side at submission time.
+
 ### Data model
 
 All data lives in SQL via Drizzle ORM. Schema: `templates/forms/server/db/schema.ts`. Forms carry the standard `ownableColumns` and a matching framework shares table, so they slot into the per-user / per-org sharing model.
@@ -77,14 +90,6 @@ All data lives in SQL via Drizzle ORM. Schema: `templates/forms/server/db/schema
 
 The `fields` and `settings` JSON shapes are defined in `templates/forms/shared/types.ts` (`FormField`, `FormSettings`). Owner-private settings such as integration webhook URLs and allowed origins are stripped before any data reaches the public fill page via `toPublicFormSettings`.
 
-### Key features (technical) {#key-features}
-
-Forms are defined as JSON field arrays (`FormField[]`) and stored in a single `fields` column — no separate table per field type. This makes the schema additive and the agent's edits surgical: changing a field label is a JSON-patch on one column, not a row update across a join table. All field types (text, email, number, long text, select, multi-select, checkbox, radio, date, rating, scale) are handled by the renderer and editor without schema changes.
-
-The public fill page is fully unauthenticated. `toPublicFormSettings` strips integration URLs and other owner-private settings before the form data reaches the browser, so secrets never leak to respondents.
-
-Integrations (Slack, Discord, Google Sheets, webhooks) are stored as settings inside the form's `settings` JSON column and executed server-side at submission time.
-
 ### Key actions
 
 Every operation is a TypeScript file in `templates/forms/actions/`, auto-mounted at `POST /_agent-native/actions/:name`:

package/docs/content/template-plan.md

@@ -5,6 +5,13 @@ description: "Agent-Native Plans turns your coding agent's plan into a structure
 
 # Visual Plans
 
+> **Most people install Plan as a skill, not a scaffolded app.** One CLI command
+> adds the `/visual-plan` and `/visual-recap` skills plus the hosted Plan
+> connector to your coding agent — see [Plan plugin & marketplace](/docs/plan-plugin)
+> for the plugin and marketplace routes. Forking the Plan template (covered under
+> [For developers](#for-developers)) is the secondary path, for self-hosting or
+> building on Plan itself.
+
 Agent-Native Plans is visual plan mode for coding agents. It turns an ordinary
 Codex, Claude Code, Markdown, or pasted implementation plan into a structured
 review surface with rich text, diagrams, wireframes, annotated code walkthroughs