@agent-native/core 0.63.2 → 0.63.4

package/docs/content/template-mail.md

@@ -7,17 +7,21 @@ description: "An agent-powered email client. Connect your Gmail and the agent ca
 
 An agent-powered email client. Connect your Gmail account and the agent can read, draft, send, and organize email for you — alongside a fast, keyboard-first inbox you can drive yourself. Think Superhuman, but the agent is a first-class citizen and the codebase is yours to own.
 
-<!-- screenshot:
-  app: mail
-  view: /inbox
-  shows: Inbox listing (Priya Mehta, Acme Billing, Marcus Tang, GitHub, Sasha Park, Linear, Hannah Reyes, Acme Recruiting, Notion, Stripe, Vercel, Calendly, Olivia Brennan, AWS Billing, Dan Kim, Figma) with the agent sidebar open and suggestion chips visible
-  account: screenshot-account (seeded with the email set above via the standard inbound flow)
-  capture: 1400x800 viewport, cropped 90px from bottom (final 1400x710)
--->
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:flex;flex-direction:column;min-height:500px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:12px;padding:12px 16px;border-bottom:1.4px solid var(--wf-line)'><strong>Inbox 16</strong><div style='flex:1'></div><span data-icon='search' aria-label='Search'></span><span data-icon='edit' aria-label='Compose'></span><span data-icon='bell' aria-label='Notify'></span></div><div style='display:flex;flex-direction:column;padding:8px 14px;gap:6px'><div class='wf-box' style='display:grid;grid-template-columns:155px 1fr auto;gap:12px;align-items:center'><strong>Priya Mehta</strong><span><strong>Q3 launch</strong> — final assets ready for review</span><span>★</span></div><div class='wf-box' style='display:grid;grid-template-columns:155px 1fr auto;gap:12px;align-items:center'><strong>Acme Billing</strong><span>Your monthly invoice is ready</span><span>11:10 AM</span></div><div class='wf-box' style='display:grid;grid-template-columns:155px 1fr auto;gap:12px;align-items:center'><span>Marcus Tang</span><span>Onboarding flow research findings</span><span>Yesterday</span></div><div class='wf-box' style='display:grid;grid-template-columns:155px 1fr auto;gap:12px;align-items:center'><span>GitHub</span><span>[framework] PR ready for review</span><span>Yesterday</span></div><div class='wf-box' style='display:grid;grid-template-columns:155px 1fr auto;gap:12px;align-items:center'><span>Linear</span><span>Issue ENG-1287 assigned to you</span><span>May 2</span></div><div class='wf-box' style='display:grid;grid-template-columns:155px 1fr auto;gap:12px;align-items:center'><span>Stripe</span><span>Weekly payments summary</span><span>Apr 29</span></div><div class='wf-box' style='display:grid;grid-template-columns:155px 1fr auto;gap:12px;align-items:center'><span>Calendly</span><span>New booking confirmed</span><span>Apr 28</span></div></div></div>"
+}
+```
 
-![Mail inbox with the agent sidebar](/screenshots/mail.png)
+When you open the app, the keyboard-first inbox and thread view stay focused on the mail itself. The agent always knows which view you're in and which thread you have open, so you can say "archive this" or "draft a friendly decline" without explaining what "this" is.
 
-When you open the app, you'll see your inbox on the left, the open thread in the middle, and the agent in the sidebar on the right. The agent always knows which view you're in and which thread you have open, so you can say "archive this" or "draft a friendly decline" without explaining what "this" is.
+```an-diagram title="How a mail request flows" summary="Keyboard shortcuts and agent prompts run the same actions. Email lives in Gmail; drafts, automations, and tracking live in SQL and application_state."
+{
+  "html": "<div class=\"diagram-flow\"><div class=\"diagram-col\"><div class=\"diagram-node\">You drive<br><small class=\"diagram-muted\">J/K/E/R shortcuts</small></div><div class=\"diagram-node\">You ask the agent<br><small class=\"diagram-muted\">\"draft a friendly decline\"</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Actions</span><small class=\"diagram-muted\">list-emails · get-thread · manage-draft · send</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Gmail<br><small class=\"diagram-muted\">multi-account, via OAuth</small></div><div class=\"diagram-box\">SQL + application_state<br><small class=\"diagram-muted\">drafts · automations · tracking</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-box\">Inbox refreshes live</div></div>",
+  "css": ".diagram-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-flow .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-flow .diagram-arrow{font-size:22px;line-height:1}.diagram-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
 
 ## What you can do with it
 
@@ -112,27 +116,15 @@ To connect Gmail in dev, you need a Google OAuth client:
 
 Tokens are stored in the `oauth_tokens` SQL table and refresh automatically. You can connect multiple Gmail accounts once the first is set up.
 
-### Key features (technical)
-
-**Gmail sync (multi-account).** Connect one or many Google accounts via OAuth. List and search actions query all connected inboxes by default; results carry an `accountEmail` field so you can tell which inbox each thread came from. Scope to a single account with `--account=user@example.com`. OAuth tokens are stored via `@agent-native/core/oauth-tokens` under the `"google"` provider.
-
-**Multiple compose drafts.** The compose panel supports multiple draft tabs at once. Each draft is stored as an `application_state` entry at `compose-{id}` and syncs live between the agent and the UI. The agent can create a new draft with `manage-draft --action=create`, edit your in-progress draft with `--action=update`, or close tabs with `--action=delete`. Drafts use markdown in the body field; the TipTap editor renders it as rich text and converts to HTML on send.
-
-**Queued draft review.** Drafts requested by teammates or Slack are durable SQL rows in `queued_email_drafts`. The agent uses `queue-email-draft` to assign a draft to an org member, returns a review URL such as `/draft-queue/<id>`, and waits for the owner to review or explicitly send. The queue supports listing assigned drafts, editing them, opening one in the compose panel, dismissing it, and sending one or all reviewed drafts.
+### Key features
 
-**AI triage via automations.** Mail supports automation rules that run against new inbox email using AI. A rule has a natural-language condition (for example, `"from a newsletter"` or `"subject contains invoice"`) and a list of actions (`label`, `archive`, `mark_read`, `star`, `trash`). Manage them via `pnpm action manage-automations --action=create|list|update|delete|enable|disable`, or through the Settings page. Rules fire automatically and can be triggered manually with `pnpm action trigger-automations`.
+**Multi-account Gmail.** Connect one or more Google accounts, then list, search, draft, send, label, archive, star, or trash across connected inboxes.
 
-**Send tracking.** Sent messages get open-pixel and link-click tracking injected automatically. Settings live under `mail-settings.tracking` with `tracking.opens` and `tracking.clicks` (both default `true`). Only links in the new portion of a reply or forward are rewritten — quoted content is left alone. Pull stats for any sent message with `pnpm action get-tracking --id=<message-id>`, or from `GET /api/emails/:id/tracking`. Open and click events are stored in the `email_tracking` and `email_link_tracking` tables.
+**Draft workflows.** Multiple compose drafts sync through application state, and queued SQL drafts let teammates or Slack users request mail for the owner to review and send.
 
-**Search.** `pnpm action search-emails --q=<term>` searches across all views and all connected accounts. The UI search bar maps to the same action. Both `search-emails` and `list-emails` take `--compact` for shorter output and `--fields=from,subject,date` to limit returned fields.
+**Automations and tracking.** Natural-language triage rules can label, archive, mark read, star, trash, or trigger manually; sent messages can track opens and clicks.
 
-**Bulk operations and export.**
-
-- `pnpm action bulk-archive --older-than=30` archives everything older than N days.
-- `pnpm action export-emails --view=inbox --output=file.json` dumps a view to JSON.
-- Archive, trash, mark-read, and star all accept comma-separated IDs (`--id=id1,id2,id3`) for bulk changes.
-
-**Inline thread previews in agent chat.** When the agent answers a question about a specific thread, it can embed a live preview of the thread directly in the chat message via an `embed` code fence. The preview is a sandboxed iframe that shows the full conversation without leaving the chat, with an "Open in app" button that navigates the main window to that thread.
+**Search, bulk actions, and previews.** Shared actions power inbox search, bulk archive/export, and inline thread previews the agent can embed in chat.
 
 ### How the agent sees your context
 
@@ -164,6 +156,61 @@ When a Google account is connected, email lives in Gmail — the app is a view o
 
 Emails flowing through the API have the shape `{ id, threadId, from, to, cc, subject, snippet, body, date, isRead, isStarred, isArchived, isTrashed, labelIds, accountEmail, attachments }`.
 
+```an-schema title="Mail SQL tables" summary="Email itself lives in Gmail. The SQL tables hold what Gmail doesn't: queued drafts, send-tracking events, and OAuth tokens. Settings and ephemeral state live in the settings and application_state stores."
+{
+  "entities": [
+    {
+      "id": "queued_email_drafts",
+      "name": "queued_email_drafts",
+      "note": "Teammate/Slack-requested drafts awaiting owner review",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "assignedTo", "type": "string", "note": "org member who reviews/sends" },
+        { "name": "subject", "type": "string" },
+        { "name": "body", "type": "markdown" },
+        { "name": "status", "type": "enum", "note": "review at /draft-queue/<id>" }
+      ]
+    },
+    {
+      "id": "email_tracking",
+      "name": "email_tracking",
+      "note": "Open-pixel events for sent messages",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "messageId", "type": "string" },
+        { "name": "openedAt", "type": "datetime" }
+      ]
+    },
+    {
+      "id": "email_link_tracking",
+      "name": "email_link_tracking",
+      "note": "Link-click events for sent messages",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "messageId", "type": "string", "fk": "email_tracking.messageId" },
+        { "name": "url", "type": "string" },
+        { "name": "clickedAt", "type": "datetime" }
+      ]
+    },
+    {
+      "id": "oauth_tokens",
+      "name": "oauth_tokens",
+      "note": "Framework table — one row per connected Google account",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "provider", "type": "string", "note": "\"google\"" },
+        { "name": "accountEmail", "type": "string" },
+        { "name": "accessToken", "type": "string" },
+        { "name": "refreshToken", "type": "string" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "email_tracking", "to": "email_link_tracking", "kind": "1-n", "label": "click events" }
+  ]
+}
+```
+
 Routes in the UI:
 
 - `/_index.tsx` — redirects to the default inbox view.

package/docs/content/template-plan.md

@@ -23,7 +23,19 @@ commit, branch, or git diff — into a high-altitude visual code review. Both op
 the same review surface, so you annotate, comment, and hand feedback back to the
 agent the same way.
 
-![Agent-Native Plans review surface](https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fdd73f749f8c54dbcb577420ab1a18788)
+```an-diagram title="Two commands, one review surface" summary="Both commands publish through the hosted Plan MCP connector into the same annotate-and-comment surface."
+{
+  "html": "<div class=\"diagram-plan\"><div class=\"diagram-col\"><div class=\"diagram-node\"><span class=\"diagram-pill accent\">/visual-plan</span><small class=\"diagram-muted\">before code — architecture, UI, refactor</small></div><div class=\"diagram-node\"><span class=\"diagram-pill\">/visual-recap</span><small class=\"diagram-muted\">after code — PR, commit, branch, diff</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\">Plan MCP connector<br><small class=\"diagram-muted\">plan.agent-native.com</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">Review surface<br><small class=\"diagram-muted\">diagrams · wireframes · annotated code · comments</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&harr;</div><div class=\"diagram-node\">Coding agent<br><small class=\"diagram-muted\">feedback handed back</small></div></div>",
+  "css": ".diagram-plan{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-plan .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-plan .diagram-arrow{font-size:22px;line-height:1}.diagram-plan .center{display:flex;flex-direction:column;align-items:center;gap:4px;text-align:center}"
+}
+```
+
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:grid;grid-template-columns:1fr 250px;gap:14px;padding:16px;min-height:520px;box-sizing:border-box'><main style='display:flex;flex-direction:column;gap:12px;min-width:0'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Checkout redesign plan</h1><div style='flex:1'></div><button>Share</button><button class='primary'>Approve</button></div><div class='wf-card' style='display:grid;grid-template-columns:1fr 1fr;gap:10px;min-height:150px'><div class='wf-box'>Current wireframe</div><div class='wf-box'>Proposed wireframe</div></div><div class='wf-card' style='flex:1;display:flex;flex-direction:column;gap:10px'><strong>Implementation plan</strong><div class='wf-box'>Decision: keep existing checkout shell</div><div class='wf-box'>Annotated code walkthrough</div><div class='wf-box'>Open questions</div></div></main><aside class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Comments</strong><div class='wf-box'>Pin on primary CTA</div><div class='wf-box'>Question for agent</div><div class='wf-box'>Resolved copy note</div><button class='primary'>Hand back feedback</button></aside></div>"
+}
+```
 
 There are two ways into Plans:
 
@@ -384,6 +396,73 @@ Schema lives in `templates/plan/server/db/schema.ts`. Core tables:
 | `plan_guest_mints` | Rate-limit records for guest session issuance                                                                                                                                           |
 | `plan_assets`      | Inline image assets stored as base64 (fallback when no upload provider)                                                                                                                 |
 
+```an-schema title="Plan data model" summary="One plan row owns ordered sections plus comments, events, versions, shares, and inline assets."
+{
+  "entities": [
+    { "id": "plans", "name": "plans", "note": "each plan or recap", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "title", "type": "text" },
+      { "name": "brief", "type": "text", "nullable": true },
+      { "name": "kind", "type": "enum", "note": "plan | recap" },
+      { "name": "status", "type": "text" },
+      { "name": "source", "type": "text", "nullable": true },
+      { "name": "hosted_plan_id", "type": "text", "nullable": true, "note": "hosted_plan_url paired" },
+      { "name": "source_url", "type": "text", "nullable": true },
+      { "name": "deleted_at", "type": "timestamp", "nullable": true, "note": "soft delete; deleted_by paired" }
+    ] },
+    { "id": "plan_sections", "name": "plan_sections", "note": "ordered sections within a plan", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "plan_id", "type": "text", "fk": "plans.id" },
+      { "name": "type", "type": "text" },
+      { "name": "title", "type": "text", "nullable": true },
+      { "name": "body", "type": "text", "nullable": true },
+      { "name": "html", "type": "text", "nullable": true },
+      { "name": "sort_order", "type": "integer" },
+      { "name": "created_by", "type": "text", "nullable": true }
+    ] },
+    { "id": "plan_comments", "name": "plan_comments", "note": "threaded comments", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "plan_id", "type": "text", "fk": "plans.id" },
+      { "name": "kind", "type": "text" },
+      { "name": "status", "type": "text" },
+      { "name": "anchor", "type": "json", "nullable": true },
+      { "name": "message", "type": "text" },
+      { "name": "resolution_target", "type": "text", "nullable": true, "note": "agent | human | null" },
+      { "name": "mentions_json", "type": "json", "nullable": true },
+      { "name": "resolved_by", "type": "text", "nullable": true }
+    ] },
+    { "id": "plan_events", "name": "plan_events", "note": "audit log of agent/human events", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "plan_id", "type": "text", "fk": "plans.id" }
+    ] },
+    { "id": "plan_versions", "name": "plan_versions", "note": "point-in-time snapshots", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "plan_id", "type": "text", "fk": "plans.id" }
+    ] },
+    { "id": "plan_shares", "name": "plan_shares", "note": "per-principal grants", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "plan_id", "type": "text", "fk": "plans.id" },
+      { "name": "role", "type": "enum", "note": "viewer | editor | admin" }
+    ] },
+    { "id": "plan_guest_mints", "name": "plan_guest_mints", "note": "rate-limit records for guest session issuance", "fields": [
+      { "name": "id", "type": "text", "pk": true }
+    ] },
+    { "id": "plan_assets", "name": "plan_assets", "note": "inline image assets as base64", "fields": [
+      { "name": "id", "type": "text", "pk": true },
+      { "name": "plan_id", "type": "text", "fk": "plans.id" }
+    ] }
+  ],
+  "relations": [
+    { "from": "plans", "to": "plan_sections", "kind": "1-n", "label": "has sections" },
+    { "from": "plans", "to": "plan_comments", "kind": "1-n", "label": "has comments" },
+    { "from": "plans", "to": "plan_events", "kind": "1-n", "label": "has events" },
+    { "from": "plans", "to": "plan_versions", "kind": "1-n", "label": "has versions" },
+    { "from": "plans", "to": "plan_shares", "kind": "1-n", "label": "has shares" },
+    { "from": "plans", "to": "plan_assets", "kind": "1-n", "label": "has assets" }
+  ]
+}
+```
+
 ### Key actions
 
 Actions in `templates/plan/actions/`:

package/docs/content/template-slides.md

@@ -7,17 +7,21 @@ description: "Generate decks from a prompt, edit visually, and present full-scre
 
 Generate full presentation decks from a prompt, edit slides visually, and present full-screen. Ask the agent for "a 10-slide pitch deck for a coffee subscription service" and watch it stream slide-by-slide into the editor in seconds. An open-source replacement for Google Slides, Pitch, and PowerPoint.
 
-<!-- screenshot:
-  app: slides
-  view: /deck/<id>
-  shows: Deck editor with a "Q3 Board Update" deck open — collapsed left icon rail (Decks / Design Systems / Team), slides thumbnail strip (6 slides — title, agenda, metrics, what we shipped, what we're watching), main slide preview showing the title slide by Maya Chen CEO, speaker notes pane, and the agent chat sidebar with deck-aware suggestions
-  account: screenshot-account (deck authored on this account via the standard create-deck + add-slide flow)
-  capture: 1400x800 viewport, cropped 90px from bottom (final 1400x710); collapse the left rail before capture
--->
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:flex;flex-direction:column;gap:12px;padding:16px;min-height:530px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Q3 Board Update</h1><span class='wf-pill accent'>Title slide</span><div style='flex:1'></div><button>Preview</button><button>Present</button><button class='primary'>Share</button></div><main style='display:grid;grid-template-columns:1fr 220px;gap:12px;flex:1;min-height:0'><section class='wf-card' style='display:flex;align-items:center;justify-content:center;text-align:center;padding:36px'><div><strong style='font-size:28px'>Q3 Board Update</strong><br/><small>Maya Chen · CEO</small><div style='height:46px'></div><span class='wf-pill'>Product momentum</span></div></section><section style='display:flex;flex-direction:column;gap:10px'><div class='wf-card'><strong>Slide outline</strong><div class='wf-box'>1 Title</div><div class='wf-box'>2 Agenda</div><div class='wf-box'>3 Metrics</div><div class='wf-box'>4 Shipped</div></div><div class='wf-card' style='flex:1'><strong>Speaker notes</strong><p class='wf-muted' style='margin:8px 0 0'>Open with launch progress and retention story.</p></div></section></main><div style='display:grid;grid-template-columns:repeat(5,1fr);gap:8px'><div class='wf-box'>1 Title</div><div class='wf-box'>2 Agenda</div><div class='wf-box'>3 Metrics</div><div class='wf-box'>4 Shipped</div><div class='wf-box'>5 Risks</div></div></div>"
+}
+```
 
-![Slides deck editor with a deck open and slide thumbnails on the left](/screenshots/slides.png)
+When you open a deck, the slide canvas, outline, notes, and filmstrip stay in one editor surface while the agent can still create, revise, and navigate slides through actions.
 
-When you open a deck, you get a slide editor in the middle, a sidebar of slides on the left, and the agent on the right.
+```an-diagram title="Prompt to deck" summary="Ask for a deck and the agent streams slides in one at a time through the same actions you could call from the CLI."
+{
+  "html": "<div class=\"diagram-flow\"><div class=\"diagram-node\">Prompt<br><small class=\"diagram-muted\">\"10-slide pitch deck\"</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Agent</span><small class=\"diagram-muted\">picks layouts</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill\">create-deck</div><div class=\"diagram-pill\">add-slide &#215; n</div><small class=\"diagram-muted\">parallel, streaming</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>decks (SQL)</div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-box\">Editor renders live</div></div>",
+  "css": ".diagram-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-flow .diagram-col{display:flex;flex-direction:column;gap:6px;align-items:center}.diagram-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-flow .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
 
 ## What you can do with it
 
@@ -39,7 +43,7 @@ Live demo: [slides.agent-native.com](https://slides.agent-native.com).
 When you open the app:
 
 1. Click **New deck**.
-2. In the agent sidebar, ask: "Generate a 10-slide pitch deck for a coffee subscription service, audience is investors."
+2. Ask the agent: "Generate a 10-slide pitch deck for a coffee subscription service, audience is investors."
 3. Watch slides stream in. Click any slide to edit, or keep asking the agent to refine.
 
 ### Useful prompts
@@ -69,75 +73,17 @@ pnpm install
 pnpm dev
 ```
 
-### Key features (technical) {#key-features}
-
-#### Import and export
-
-The template can pull content in from PPTX (`import-pptx`), DOCX (`import-docx`), Google Docs (`import-google-doc`), arbitrary URLs (`import-from-url`), and GitHub repos (`import-github`). Export paths cover PPTX (`export-pptx`), Google Slides (`export-google-slides`), and HTML (`export-html`). Importing uses the same action surface as the rest of the template — no separate pipeline.
-
-#### Design systems
-
-Reusable brand tokens are stored in the `design_systems` table (colors, typography, spacing, assets, custom instructions, and an `is_default` flag). Sharing is managed via `design_system_shares`. Actions: `create-design-system`, `update-design-system`, `get-design-system`, `list-design-systems`, `set-default-design-system`, `apply-design-system`, and `analyze-brand-assets` (collects brand data before analysis). See the `design-systems` and `image-generation-via-a2a` skills for the full pattern.
-
-#### Deck versions
-
-Every significant deck change is snapshotted in the `deck_versions` table (stores a full copy of title and deck data with an optional `changeLabel`). Actions: `list-deck-versions`, `restore-deck-version`, `get-deck-version`.
-
-#### Prompt-to-deck generation
-
-Ask the agent for a deck and it builds one slide at a time. Slides stream into the editor live as each one is generated — the agent fires parallel `add-slide` calls so you see the deck assemble in seconds.
-
-Under the hood, this is powered by the `add-slide` and `create-deck` actions in `templates/slides/actions/`.
-
-#### Seven slide layouts
-
-Built-in layouts: title, section divider, content with bullets, two-column, statement or quote, metrics or stats, and closing or CTA. Each layout is a pure HTML template with inline styles — the agent picks the right one based on slide purpose. The exact templates live inside `templates/slides/.agents/skills/create-deck/SKILL.md` so the agent can reference them without exploring the codebase.
-
-#### Visual and code editing
-
-- Double-click any text to edit inline.
-- Click a block to open the bubble menu for styles, alignment, and layout.
-- Switch to the code editor (`app/components/editor/CodeEditor.tsx`) to edit raw slide HTML.
-- Use the slash menu (`SlideSlashMenu.tsx`) to insert blocks by typing `/`.
+### Key features {#key-features}
 
-#### AI image generation
+**Prompt-to-deck generation.** Ask for a deck and the agent streams slides into the editor using the same create and edit actions you can run yourself.
 
-Generate images through the Assets app when brand libraries matter; once the managed backend is deployed, that path can use Builder-managed image generation and keep the audit trail with the source library. Direct provider-key generation remains the fallback for standalone decks.
+**Editable slide canvas.** Inline text editing, slash inserts, code editing, drag-and-drop ordering, undo/redo, comments, and presentation mode all live in the deck surface.
 
-Actions: `generate-image`, `edit-image`, `image-search`, `logo-lookup`. UI panels: `ImageGenPanel.tsx`, `ImageSearchPanel.tsx`, `LogoSearchPanel.tsx`.
+**Import and export.** Bring in PPTX, DOCX, Google Docs, PDFs, URLs, and GitHub repos; export to PPTX, Google Slides, HTML, or a share link.
 
-#### Logo and stock image search
+**Design systems and media.** Saved brand systems, image generation, stock search, and logo lookup keep decks closer to the intended visual direction.
 
-- `logo-lookup --domain acme.com` fetches a company logo via Logo.dev or Brandfetch.
-- `image-search --query "mountain landscape"` searches Google Images for stock photos.
-
-#### Comments and threads
-
-Leave comments on specific slides, quote selected text, and reply in threads. Stored in the `slide_comments` table. Actions: `add-slide-comment`, `list-slide-comments`.
-
-#### Drag and drop reordering
-
-Reorder slides in the sidebar, duplicate, or delete with hover controls. The sidebar lives in `app/components/editor/EditorSidebar.tsx`.
-
-#### Presentation mode
-
-Full-screen presentation at `/deck/:id/present` with keyboard navigation (arrow keys, space, escape), auto-hiding controls, and speaker notes. See `app/routes/deck.$id_.present.tsx` and `app/components/presentation/PresentationView.tsx`.
-
-#### Share links
-
-Generate a public read-only URL for a deck so reviewers can view without an account. The share page is `app/routes/share.$token.tsx`. Fine-grained sharing (viewer, editor, admin roles, per-user or org-wide) is also available via the framework's `share-resource` action.
-
-#### Real-time collaboration
-
-Multiple people can edit the same deck simultaneously. Text edits sync through Yjs CRDT so there are no conflicts, and the agent sees and edits the same live document via the `update-slide --find/--replace` action.
-
-#### Undo and redo
-
-Cmd+Z and Cmd+Shift+Z work across the whole deck, with a labeled history panel (`HistoryPanel.tsx`) you can scrub through.
-
-#### Extract from PDF
-
-Turn a PDF into a starter deck. The `extract-pdf` action parses the file and hands the content to the agent for layout.
+**Collaboration and history.** Real-time Yjs editing, threaded comments, share roles, and deck version snapshots are built in.
 
 ### Working with the agent
 
@@ -165,6 +111,81 @@ The agent can embed a live slide preview directly in a chat reply using the fram
 
 All deck data lives in SQL via Drizzle ORM. Schema: `templates/slides/server/db/schema.ts`.
 
+```an-schema title="Slides data model" summary="A deck owns its slides as JSON in decks.data; comments, versions, shares, and design systems hang off it."
+{
+  "entities": [
+    {
+      "id": "decks",
+      "name": "decks",
+      "note": "Slides live as JSON in data; carries ownableColumns",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true, "note": "e.g. deck-1712345-abc" },
+        { "name": "title", "type": "text" },
+        { "name": "data", "type": "text", "note": "JSON: { title, slides: [{ id, content, layout }] }" },
+        { "name": "created_at", "type": "text" },
+        { "name": "updated_at", "type": "text" }
+      ]
+    },
+    {
+      "id": "slide_comments",
+      "name": "slide_comments",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "deck_id", "type": "text", "fk": "decks.id" },
+        { "name": "slide_id", "type": "text", "note": "Slide the comment lives on" },
+        { "name": "thread_id", "type": "text", "note": "Threading" },
+        { "name": "parent_id", "type": "text", "nullable": true },
+        { "name": "content", "type": "text" },
+        { "name": "quoted_text", "type": "text", "nullable": true },
+        { "name": "author_email", "type": "text" },
+        { "name": "author_name", "type": "text" },
+        { "name": "resolved", "type": "boolean" }
+      ]
+    },
+    {
+      "id": "deck_versions",
+      "name": "deck_versions",
+      "note": "Point-in-time snapshots for restore",
+      "fields": [
+        { "name": "deck_id", "type": "text", "fk": "decks.id" },
+        { "name": "title", "type": "text" },
+        { "name": "data", "type": "text", "note": "Full deck JSON" },
+        { "name": "change_label", "type": "text", "nullable": true }
+      ]
+    },
+    {
+      "id": "design_systems",
+      "name": "design_systems",
+      "note": "Reusable brand tokens; ownableColumns",
+      "fields": [
+        { "name": "data", "type": "text", "note": "colors / typography / spacing" },
+        { "name": "assets", "type": "text", "nullable": true },
+        { "name": "custom_instructions", "type": "text", "nullable": true },
+        { "name": "is_default", "type": "boolean" }
+      ]
+    },
+    {
+      "id": "deck_share_links",
+      "name": "deck_share_links",
+      "note": "Persisted public share-link snapshots",
+      "fields": [
+        { "name": "token", "type": "text", "pk": true },
+        { "name": "title", "type": "text" },
+        { "name": "slides", "type": "text", "note": "JSON slides snapshot" },
+        { "name": "aspect_ratio", "type": "text", "nullable": true },
+        { "name": "created_at", "type": "text" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "decks", "to": "slide_comments", "kind": "1-n", "label": "comments" },
+    { "from": "decks", "to": "deck_versions", "kind": "1-n", "label": "snapshots" }
+  ]
+}
+```
+
+Framework shares tables (`deck_shares`, `design_system_shares`) map principals to viewer / editor / admin roles per resource.
+
 #### decks
 
 | Column       | Type | Notes                                                     |

package/docs/content/template-videos.md

@@ -7,18 +7,22 @@ description: "A programmatic video studio for motion graphics, product demos, an
 
 A programmatic video studio for the kind of motion graphics, product demos, and kinetic-text videos that are a pain to keyframe by hand. Ask the agent for "a 6-second logo reveal that fades in at 2 seconds" and it builds the animation. Tune timing, easing, and camera moves on a timeline, then render to MP4 or WebM.
 
-<!-- screenshot:
-  app: video
-  view: /c/<composition-id>
-  shows: Video studio with 4 compositions (Logo reveal, Q3 product demo, Pricing animation, Onboarding walkthrough) in the sidebar; Logo reveal loaded with timeline + Remotion preview + camera tools and the agent chat sidebar
-  account: screenshot-account (compositions authored on this account)
-  capture: 1400x800 viewport, cropped 90px from bottom (final 1400x710)
--->
-
-![Video studio with timeline, composition, and agent sidebar](/screenshots/videos.png)
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:flex;flex-direction:column;gap:12px;padding:16px;min-height:530px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px'><h1 style='margin:0'>Logo reveal</h1><span class='wf-pill accent'>6 seconds</span><div style='flex:1'></div><button>Preview</button><button class='primary'>Render</button></div><div class='wf-card' style='flex:1;display:flex;align-items:center;justify-content:center;min-height:250px'><div style='text-align:center'><strong>Remotion preview</strong><br/><small class='wf-muted'>logo scales in as the title fades</small></div></div><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><div style='display:flex;gap:8px;align-items:center'><span class='wf-pill'>0s</span><span class='wf-pill'>2s</span><span class='wf-pill'>4s</span><span class='wf-pill'>6s</span><div style='flex:1'></div><button>New track</button></div><div class='wf-box'>Title fade · 0-48 frames</div><div class='wf-box'>Logo scale · 48-120 frames</div><div class='wf-box'>Camera push · 72-144 frames</div></div></div>"
+}
+```
 
 When you open the studio, you'll see a list of compositions on the home screen. Click into one and you get a player on top, a timeline at the bottom, and a properties panel on the right. The agent always knows which composition you have open.
 
+```an-diagram title="Animation as data" summary="A composition is a React component; every animation reads from a track so the agent and the timeline edit the same data."
+{
+  "html": "<div class=\"diagram-flow\"><div class=\"diagram-col\"><div class=\"diagram-node\">Timeline<br><small class=\"diagram-muted\">drag, resize, scrub</small></div><div class=\"diagram-node\">Agent<br><small class=\"diagram-muted\">\"fade in at 2s\"</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">AnimationTrack</span><small class=\"diagram-muted\">startFrame / easing / animatedProps</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>React composition<br><small class=\"diagram-muted\">Remotion &lt;Player&gt;</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\">MP4 / WebM</div></div>",
+  "css": ".diagram-flow{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-flow .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-flow .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
 ## What you can do with it
 
 - **Generate animations from a prompt.** "Add a title card that fades in at 2 seconds and holds until 5." The agent edits the composition.
@@ -75,53 +79,15 @@ pnpm dev
 
 Open the studio in your browser, create a composition, and start from blank. Ask the agent something like "add a logo reveal that fades in at 2 seconds" and it will edit the composition for you.
 
-### Key features (technical)
-
-#### React-based compositions
-
-Every video is a React component built on Remotion primitives (`AbsoluteFill`, `useCurrentFrame`, `useVideoConfig`). The template ships one in-code composition — `BlankComposition` in `app/remotion/compositions/BlankComposition.tsx` — and `app/remotion/registry.ts` exports an empty `compositions` array by default. User and example compositions (kinetic text, logo reveals, particle bursts, interactive UI demos, slideshows) live in SQL and load through `app/hooks/use-database-compositions.ts`. You can still add a code composition by dropping a `.tsx` file in `app/remotion/compositions/` and registering it in `app/remotion/registry.ts`.
-
-#### Timeline tracks
-
-Animations are tracks, not hardcoded frame checks. A track has `startFrame`, `endFrame`, `easing`, and a list of `animatedProps` (`opacity`, `translateY`, `scale`, rotation, colors, etc.). Three track shapes:
-
-- **Duration tracks** — bars you can drag and resize in the timeline.
-- **Keyframe tracks** — diamond markers at specific frames for instant state changes (`startFrame === endFrame`).
-- **Expression tracks** — programmatic animations (typing reveals, particle bursts) flagged with `programmatic: true` and shown with a purple `fx` badge.
-
-Helper utilities in `app/remotion/trackAnimation.ts` (`findTrack`, `trackProgress`, `getPropValue`) wire a track's values into a component's render.
-
-#### Easing curves
-
-30+ easing curves ship in `app/types.ts` — linear, power1-4 in/out/inOut, back, bounce, circ, elastic, expo, sine, and Remotion's `spring`. The Properties panel shows a visual preview of the curve shape for each one.
-
-#### Camera controls
+### Key features
 
-Each composition has a dedicated `camera` track with six animatable properties: `translateX`, `translateY`, `scale`, `rotateX`, `rotateY`, `perspective`. The camera toolbar above the player has pan, zoom, and tilt tools — click a tool, drag on the preview, and a keyframe is auto-created at the current frame. `CameraHost` (in `app/remotion/CameraHost.tsx`) applies the chained CSS 3D transform to everything inside.
+**React-based compositions.** Videos are Remotion-backed React components, with SQL-backed user compositions and an optional code registry for local defaults.
 
-#### Multi-keyframe editing
+**Timeline-first animation.** Duration tracks, keyframes, easing curves, camera moves, and programmatic expression tracks all edit the same composition data.
 
-Every animated property supports an optional `keyframes` array. Interpolation is linear between keyframes, with hold-at-first and hold-at-last at the edges. In the timeline you can box-select keyframes, shift-click to add or remove, and drag groups while keeping relative timing.
+**Adjustable motion systems.** Parameters, cursor tracks, interactive hover zones, range navigation, and repeat playback make generated animations tunable without code.
 
-#### Adjustable parameters
-
-Programmatic animations expose internal magic numbers as user-editable `parameters` — character width, drift distance, particle count, stagger delay. Inputs appear in the Properties panel with min/max/step bounds and save to localStorage automatically.
-
-#### Interactive cursor system
-
-The `cursor` track drives a visible cursor that moves across the composition. Hover zones on interactive elements (buttons, tabs, inputs, cards) change the cursor appearance — arrow, pointer, or I-beam. See `app/remotion/hooks/useInteractiveComponent.ts` and `app/remotion/ui-components/InteractiveCard.tsx`.
-
-#### View range and repeat playback
-
-The timeline has a range navigator at the bottom (AE-style triangular handles). Drag to zoom and pan the visible time window. Playback in the player is constrained to that range, with a repeat toggle that loops inside it.
-
-#### Render output
-
-Composition size, fps, and render quality are per-composition in the Properties panel. Render quality is supersampling — 1x, 2x, or 3x internal resolution to keep text and vectors crisp during camera zoom. Final render happens via the Remotion CLI to MP4 or WebM.
-
-#### Composition persistence
-
-User edits (track values, parameter values, prop overrides, composition settings) persist to localStorage per composition. The **Save** button in the top-right of the composition view can write the current state back to `app/remotion/registry.ts` as TypeScript — so new users and sessions pick up the changes. That source-write path runs through `POST /api/save-composition-defaults`, which is gated to local development only; in production it returns a 403, and durable composition state lives in SQL instead.
+**Render and persistence.** Composition settings, quality, fps, track values, and overrides persist per composition and render to MP4 or WebM through Remotion.
 
 ### Working with the agent
 
@@ -133,6 +99,61 @@ Under the hood the agent calls actions like `navigate`, `save-composition`, and
 
 Server-side schema is in `templates/videos/server/db/schema.ts`:
 
+```an-schema title="Video data model" summary="SQL-backed compositions plus design systems and nestable folders, each with a framework shares table."
+{
+  "entities": [
+    {
+      "id": "compositions",
+      "name": "compositions",
+      "note": "User-created compositions and overrides; ownableColumns",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "title", "type": "text" },
+        { "name": "type", "type": "text" },
+        { "name": "data", "type": "text", "note": "Full composition JSON blob" },
+        { "name": "created_at", "type": "text" },
+        { "name": "updated_at", "type": "text" }
+      ]
+    },
+    {
+      "id": "design_systems",
+      "name": "design_systems",
+      "note": "Reusable brand tokens; ownableColumns",
+      "fields": [
+        { "name": "data", "type": "text", "note": "colors / typography / spacing" },
+        { "name": "assets", "type": "text", "nullable": true },
+        { "name": "custom_instructions", "type": "text", "nullable": true },
+        { "name": "is_default", "type": "boolean" }
+      ]
+    },
+    {
+      "id": "folders",
+      "name": "folders",
+      "note": "Nestable folders; ownableColumns",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "name", "type": "text" }
+      ]
+    },
+    {
+      "id": "folder_memberships",
+      "name": "folder_memberships",
+      "note": "Many-to-many join",
+      "fields": [
+        { "name": "folder_id", "type": "text", "fk": "folders.id" },
+        { "name": "composition_id", "type": "text", "fk": "compositions.id" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "folders", "to": "folder_memberships", "kind": "1-n", "label": "members" },
+    { "from": "compositions", "to": "folder_memberships", "kind": "1-n", "label": "in folders" }
+  ]
+}
+```
+
+Each table also has a matching framework shares table (`composition_shares`, `design_system_shares`, `folder_shares`) produced by `createSharesTable()`.
+
 - `compositions` — id, title, type, `data` (full composition JSON blob), ownership columns, timestamps.
 - `composition_shares` — standard share grants produced by `createSharesTable()`.
 - `design_systems` — reusable brand tokens (colors, typography, spacing, assets, custom instructions, `is_default` flag) with `ownableColumns`.