@agent-native/core 0.63.2 → 0.63.4

package/docs/content/template-brain.md

@@ -19,7 +19,19 @@ The product surface stays simple on purpose: **Ask** is the primary chat
 experience, while **Sources**, **Review**, and **Knowledge** are admin/support
 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)
+```an-diagram title="From source to cited answer" summary="Brain ingests approved sources into raw captures, distills durable memory, gates it through review, and only then answers with citations."
+{
+  "html": "<div class=\"diagram-flow\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Sources</span><small class=\"diagram-muted\">Slack · Granola · GitHub · Clips · webhooks</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Raw captures<br><small class=\"diagram-muted\">deduped, redacted</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>Distill<br><small class=\"diagram-muted\">facts · decisions · processes</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card\"><span class=\"diagram-pill warn\">Review</span><small class=\"diagram-muted\">sensitive / low-confidence queue</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough><span class=\"diagram-pill ok\">Knowledge</span><small class=\"diagram-muted\">approved, atomic</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-panel center\"><span class=\"diagram-pill accent\">Ask</span><small class=\"diagram-muted\">cited answer</small></div></div>",
+  "css": ".diagram-flow{display:flex;align-items:center;gap:10px;flex-wrap:wrap}.diagram-flow .diagram-card{display:flex;flex-direction:column;gap:4px;padding:10px 12px}.diagram-flow .diagram-box{display:flex;flex-direction:column;gap:4px}.diagram-flow .diagram-arrow{font-size:20px;line-height:1}.diagram-flow .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
+```an-wireframe
+{
+  "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'>Ask company memory</h1><span class='wf-pill accent'>42 approved memories</span><span class='wf-pill'>3 sources</span><div style='flex:1'></div><button>Sources</button><button>Review</button></div><div class='wf-card' style='display:flex;align-items:center;gap:10px'><span data-icon='search' aria-label='Search'></span><strong style='flex:1'>Why did we choose usage pricing?</strong><button class='primary'>Ask</button></div><div class='wf-card' style='display:flex;flex-direction:column;gap:10px'><strong>Answer</strong><p style='margin:0'>The team chose usage pricing after pilots showed seat counts undercounted automation value.</p><div style='display:flex;gap:8px;flex-wrap:wrap'><span class='wf-pill accent'>Pricing RFC</span><span class='wf-pill'>Launch retro</span><span class='wf-pill'>Sales notes</span></div></div><div class='wf-card' style='flex:1;display:flex;flex-direction:column;gap:8px'><strong>Source timeline</strong><div class='wf-box'>May 3 · Decision captured</div><div class='wf-box'>May 8 · Customer evidence added</div><div class='wf-box'>May 12 · Legal note approved</div></div></div>"
+}
+```
 
 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
@@ -140,6 +152,65 @@ Brain's schema lives in `templates/brain/server/db/schema.ts`. Eight tables:
 | `brain_sync_runs`        | Sync audit log — provider, status, stats JSON, error, start/end timestamps                                                                     |
 | `brain_ingest_queue`     | Background distillation queue — operation, status, priority, retry count, `run_after`                                                          |
 
+```an-schema title="Brain data model" summary="Connectors produce raw captures; distillation turns captures into reviewable knowledge; proposals gate sensitive entries. Sync runs and the ingest queue track background work."
+{
+  "entities": [
+    { "id": "sources", "name": "brain_sources", "note": "Connector config", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "provider", "type": "text", "note": "slack / granola / github / clips / webhook" },
+      { "name": "ingest_token_hash", "type": "text" },
+      { "name": "status", "type": "text" },
+      { "name": "last_synced_at", "type": "timestamp", "nullable": true }
+    ] },
+    { "id": "source_shares", "name": "brain_source_shares", "note": "viewer / editor / admin", "fields": [
+      { "name": "source_id", "type": "id", "fk": "brain_sources.id" }
+    ] },
+    { "id": "captures", "name": "brain_raw_captures", "note": "Ingested raw payloads", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "source_id", "type": "id", "fk": "brain_sources.id" },
+      { "name": "external_id", "type": "text", "note": "dedupe key" },
+      { "name": "content_hash", "type": "text" },
+      { "name": "kind", "type": "text" }
+    ] },
+    { "id": "knowledge", "name": "brain_knowledge", "note": "Distilled atomic entries", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "kind", "type": "text", "note": "decision / fact / process" },
+      { "name": "topic", "type": "text" },
+      { "name": "entities", "type": "json" },
+      { "name": "confidence", "type": "real" },
+      { "name": "publish_tier", "type": "text" }
+    ] },
+    { "id": "knowledge_shares", "name": "brain_knowledge_shares", "fields": [
+      { "name": "knowledge_id", "type": "id", "fk": "brain_knowledge.id" }
+    ] },
+    { "id": "proposals", "name": "brain_proposals", "note": "Pending review items", "fields": [
+      { "name": "id", "type": "id", "pk": true },
+      { "name": "op", "type": "text", "note": "create / update / archive" }
+    ] },
+    { "id": "proposal_shares", "name": "brain_proposal_shares", "fields": [
+      { "name": "proposal_id", "type": "id", "fk": "brain_proposals.id" }
+    ] },
+    { "id": "sync_runs", "name": "brain_sync_runs", "note": "Sync audit log", "fields": [
+      { "name": "source_id", "type": "id", "fk": "brain_sources.id" },
+      { "name": "status", "type": "text" },
+      { "name": "stats", "type": "json" }
+    ] },
+    { "id": "ingest_queue", "name": "brain_ingest_queue", "note": "Background distillation queue", "fields": [
+      { "name": "operation", "type": "text" },
+      { "name": "status", "type": "text" },
+      { "name": "priority", "type": "int" },
+      { "name": "run_after", "type": "timestamp", "nullable": true }
+    ] }
+  ],
+  "relations": [
+    { "from": "sources", "to": "captures", "kind": "1-n", "label": "ingested into" },
+    { "from": "knowledge", "to": "captures", "kind": "n-n", "label": "evidence" },
+    { "from": "knowledge", "to": "proposals", "kind": "1-n", "label": "gated by" },
+    { "from": "sources", "to": "sync_runs", "kind": "1-n", "label": "audited by" }
+  ]
+}
+```
+
 ### Key actions
 
 Grouped by area (`templates/brain/actions/`):
@@ -188,6 +259,23 @@ a source with a `sourceKey` to receive a bearer token, then send a
 use the same payload shape for call transcripts, customer research, imported
 notes, or any other source that can produce a bounded capture.
 
+```an-api title="Signed ingest webhook" summary="Clips and generic transcript/capture imports post a RawCapturePayload with a per-source bearer token."
+{
+  "method": "POST",
+  "path": "/api/_agent-native/brain/ingest",
+  "summary": "Import a raw capture from Clips or a generic source",
+  "auth": "Bearer <ingestToken> issued per source via its sourceKey",
+  "request": {
+    "contentType": "application/json",
+    "example": "RawCapturePayload — bounded transcript / capture body"
+  },
+  "responses": [
+    { "status": "200", "description": "Capture accepted and queued for distillation" },
+    { "status": "401", "description": "Missing or invalid ingest bearer token" }
+  ]
+}
+```
+
 Slack, Granola, and GitHub sources can opt into background `autoSync` with a
 poll cadence once review quality is proven.
 

package/docs/content/template-calendar.md

@@ -7,17 +7,21 @@ description: "An agent-powered calendar with Google Calendar sync and Calendly-s
 
 An agent-powered calendar app. Connect your Google Calendar and the agent can read your schedule, find free slots, create events, and manage Calendly-style booking links — all in plain English. It replaces the Google Calendar + Calendly combo with one app you own.
 
-<!-- screenshot:
-  app: calendar
-  view: / (week)
-  shows: Calendar week view (May 3-9) with ~17 events scattered across the week (All-hands kickoff, Q3 launch sync, Design review, 1:1 with Marcus, Coffee w/ Hannah, Eng standup, Lunch block, Customer call - Acme, Design crit, Focus block, Roadmap planning, Skip-level w/ Priya, Friday demo, All-hands) — events render in the default blue tone — and the agent sidebar with calendar-aware suggestions
-  account: screenshot-account (Google Calendar connected and a representative week populated via create-event)
-  capture: 1400x800 viewport, cropped 90px from bottom (final 1400x710)
--->
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='display:flex;flex-direction:column;min-height:530px;box-sizing:border-box'><div style='display:flex;align-items:center;gap:10px;padding:14px 18px;border-bottom:1.4px solid var(--wf-line)'><button>Week</button><button>Today</button><button>‹</button><button>›</button><div style='flex:1'></div><strong>May 3-9, 2026</strong><div style='flex:1'></div><button class='primary'>New Event</button></div><div style='display:grid;grid-template-columns:56px repeat(7,minmax(0,1fr));grid-template-rows:36px repeat(5,72px);gap:7px;padding:14px;flex:1'><div></div><strong>Sun 3</strong><strong>Mon 4</strong><strong>Tue 5</strong><strong>Wed 6</strong><strong>Thu 7</strong><strong>Fri 8</strong><strong>Sat 9</strong><small class='wf-muted'>7 AM</small><div class='wf-box' style='opacity:.45'></div><div></div><div></div><div></div><div></div><div></div><div></div><small class='wf-muted'>9 AM</small><div class='wf-box'>All-hands</div><div class='wf-box'>Eng standup</div><div class='wf-box'>Eng standup</div><div class='wf-box'>Eng standup</div><div></div><div class='wf-box'>Planning</div><div></div><small class='wf-muted'>11 AM</small><div class='wf-box'>Design review</div><div></div><div class='wf-box'>Design crit</div><div class='wf-box'>Roadmap</div><div class='wf-box'>Friday demo</div><div></div><div></div><small class='wf-muted'>1 PM</small><div></div><div class='wf-box'>1:1</div><div class='wf-box'>Focus block</div><div></div><div></div><div class='wf-box'>All-hands</div><div></div><small class='wf-muted'>3 PM</small><div></div><div></div><div></div><div class='wf-box'>Skip-level</div><div></div><div></div><div></div></div></div>"
+}
+```
 
-![Calendar week view with a populated week and the agent sidebar](/screenshots/calendar.png)
+When you open the app, the active calendar view is the primary surface. The agent still knows which day, week, or event you're looking at, so you can say "schedule a 30-minute call with Alex on this day" without spelling everything out.
 
-When you open the app, you'll see your calendar in the middle and the agent in the sidebar. The agent always knows which day, week, or event you're looking at, so you can say "schedule a 30-minute call with Alex on this day" without spelling everything out.
+```an-diagram title="How a scheduling request flows" summary="Whether you click in the calendar or ask the agent, the same actions read live from Google Calendar and write back to the same view."
+{
+  "html": "<div class=\"diagram-flow\"><div class=\"diagram-col\"><div class=\"diagram-node\">You click<br><small class=\"diagram-muted\">drag, toolbar, shortcuts</small></div><div class=\"diagram-node\">You ask the agent<br><small class=\"diagram-muted\">\"find a 1-hour slot next week\"</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-events · check-availability · create-event</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-box\">Google Calendar<br><small class=\"diagram-muted\">live, multi-account</small></div><div class=\"diagram-box\">SQL<br><small class=\"diagram-muted\">bookings · availability</small></div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&#8635;</div><div class=\"diagram-box\">Calendar view updates 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
 
@@ -80,60 +84,17 @@ Open `http://localhost:8082` (the default Calendar dev port).
 
 To connect Google Calendar in dev, open the Settings view, paste a `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` from [Google Cloud Console](https://console.cloud.google.com/), and click "Connect Google Calendar". The OAuth redirect URI is `http://localhost:8082/_agent-native/google/callback` in dev. Tokens are stored in the `oauth_tokens` SQL table and refresh automatically.
 
-### Key features (technical)
+### Key features
 
-**Calendar views.** The main view at `/` (route `app/routes/_app._index.tsx`) renders the calendar in day, week, or month mode. Switch views from the toolbar, or ask the agent to switch for you. Events are fetched live from Google Calendar — no local sync step is required to see the latest state.
+**Live calendar views.** Day, week, and month views read directly from connected Google accounts, with optional read-only ICS feeds layered into the same schedule.
 
-**Multi-account Google Calendar sync.** Connect as many Google accounts as you like. Each connection appears in Settings, and events from every connected calendar overlay in the main view. Sync is pull-based, so no webhooks or background workers are required. The `sync-google-calendar` action refetches a date range on demand. Supporting actions: `list-events`, `search-events`, `get-event`, `create-event`, `sync-google-calendar`.
-
-**External calendars (ICS subscriptions).** Subscribe to read-only ICS or `webcal://` feeds — useful for HR time off, conference schedules, or shared team calendars. Feeds are added in Settings and stored per user. Relevant actions: `add-external-calendar`, `list-external-calendars`, `remove-external-calendar`, `update-external-calendars`.
-
-**Availability rules.** Availability is a weekly schedule of time windows per day, plus a timezone. It is stored in the settings table under the key `calendar-availability`:
-
-```json
-{
-  "timezone": "America/Los_Angeles",
-  "schedule": {
-    "monday": [{ "start": "09:00", "end": "17:00" }],
-    "tuesday": [{ "start": "09:00", "end": "17:00" }],
-    "wednesday": [
-      { "start": "09:00", "end": "12:00" },
-      { "start": "13:00", "end": "17:00" }
-    ],
-    "thursday": [{ "start": "09:00", "end": "17:00" }],
-    "friday": [{ "start": "09:00", "end": "16:00" }],
-    "saturday": [],
-    "sunday": []
-  }
-}
-```
+**Availability and free-slot search.** Weekly availability rules, timezone support, and existing events all feed the same availability action the UI and agent use.
 
-Edit it at `/availability` (`app/routes/_app.availability.tsx`) or via the `update-availability` action. The `check-availability` action reads this schedule, subtracts your existing Google Calendar events, and returns free slots of the requested duration.
+**Booking links.** Public `/book/{slug}` pages collect name, email, custom fields, conferencing preferences, and cancellation/reschedule tokens.
 
-**Public booking pages.** Booking links are the Calendly replacement. Create one in the UI at `/booking-links` (`app/routes/_app.booking-links._index.tsx`), configure it in the editor at `/booking-links/{id}`, and share the public URL.
+**Shareable management.** Booking links are private by default, but can be shared with teammates through the framework sharing actions.
 
-Every link has:
-
-- A URL slug, so the public page lives at `/book/{slug}`.
-- A primary duration plus an optional list of alternative durations (for example 15, 30, or 60 minutes).
-- Optional custom fields collected at booking time.
-- A conferencing option (Google Meet, Zoom, or a custom meeting link).
-- An `isActive` toggle to pause bookings without deleting the link.
-
-Visitors land on the public page, pick a date and time from the available slots, fill in name, email, and any custom fields, and receive a confirmation. Bookings are stored in the `bookings` table with a `cancelToken`, which powers the public cancel/reschedule page at `/booking/manage/{token}`.
-
-There is also a per-user public URL at `/meet/{username}/{slug}` for clean personal sharing.
-
-**Sharing booking links with teammates.** Booking links are private by default — only the creator can edit or delete them. To let a teammate manage a link, either change the link's visibility or grant explicit access. The framework ships these actions, auto-mounted for any `booking-link` resource:
-
-- `share-resource` — grant a user or org `viewer`, `editor`, or `admin` access.
-- `unshare-resource` — revoke a grant.
-- `list-resource-shares` — show current visibility plus all grants.
-- `set-resource-visibility` — change the coarse visibility (`private`, `org`, or `public`).
-
-Sharing only controls who can manage the link. The public booking URL always accepts bookings from unauthenticated visitors as long as `isActive` is true.
-
-**Inline event previews in chat.** The `/event` route (`app/routes/event.tsx`) renders a compact, chromeless event card that the agent can embed in chat when you ask about a specific event. Title, time, location, attendees, and a description snippet are shown with a button to jump into the main calendar.
+**Inline event previews.** The agent can embed compact event cards in chat with title, time, location, attendees, and a jump-back button.
 
 ### Working with the agent
 
@@ -150,6 +111,73 @@ Defined in `templates/calendar/server/db/schema.ts`. Only non-event data is stor
 - `booking_slug_redirects` — remembers old slugs when a link is renamed so existing public URLs keep working.
 - `booking_link_shares` — share grants for booking links.
 
+```an-schema title="Calendar data model" summary="Only non-event data is stored locally — events live in Google Calendar. Booking links use ownableColumns so the sharing system applies."
+{
+  "entities": [
+    {
+      "id": "booking_links",
+      "name": "booking_links",
+      "note": "Calendly-style link definitions (ownable)",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "slug", "type": "string", "note": "public page at /book/{slug}" },
+        { "name": "title", "type": "string" },
+        { "name": "description", "type": "string", "nullable": true },
+        { "name": "duration", "type": "int", "note": "primary duration in minutes" },
+        { "name": "durations", "type": "json", "nullable": true, "note": "alternative durations" },
+        { "name": "customFields", "type": "json", "nullable": true },
+        { "name": "conferencing", "type": "string", "note": "Google Meet / Zoom / custom" },
+        { "name": "color", "type": "string", "nullable": true },
+        { "name": "isActive", "type": "bool", "note": "pause without deleting" }
+      ]
+    },
+    {
+      "id": "bookings",
+      "name": "bookings",
+      "note": "Confirmed appointments from public booking pages",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "slug", "type": "string", "fk": "booking_links.slug" },
+        { "name": "name", "type": "string" },
+        { "name": "email", "type": "string" },
+        { "name": "start", "type": "datetime" },
+        { "name": "end", "type": "datetime" },
+        { "name": "notes", "type": "string", "nullable": true },
+        { "name": "customFields", "type": "json", "nullable": true, "note": "custom field responses" },
+        { "name": "meetingLink", "type": "string", "nullable": true },
+        { "name": "cancelToken", "type": "string", "note": "powers /booking/manage/{token}" },
+        { "name": "status", "type": "enum", "note": "confirmed | cancelled" }
+      ]
+    },
+    {
+      "id": "booking_slug_redirects",
+      "name": "booking_slug_redirects",
+      "note": "Keeps old public URLs working after a link is renamed",
+      "fields": [
+        { "name": "oldSlug", "type": "string", "pk": true },
+        { "name": "linkId", "type": "id", "fk": "booking_links.id" }
+      ]
+    },
+    {
+      "id": "booking_link_shares",
+      "name": "booking_link_shares",
+      "note": "Share grants for booking links",
+      "fields": [
+        { "name": "id", "type": "id", "pk": true },
+        { "name": "linkId", "type": "id", "fk": "booking_links.id" },
+        { "name": "principal", "type": "string", "note": "user or org" },
+        { "name": "role", "type": "enum", "note": "viewer | editor | admin" }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "booking_links", "to": "bookings", "kind": "1-n", "label": "has bookings" },
+    { "from": "booking_links", "to": "booking_slug_redirects", "kind": "1-n", "label": "has old slugs" },
+    { "from": "booking_links", "to": "booking_link_shares", "kind": "1-n", "label": "has share grants" }
+  ]
+}
+```
+
 Availability rules and per-user configuration live in the settings table, keyed by `calendar-availability`. Google OAuth tokens live in the framework `oauth_tokens` table. Ephemeral UI state (current view, date, selected event) lives in `application_state` under the `navigation` key.
 
 ### Customizing it

package/docs/content/template-chat.md

@@ -9,15 +9,12 @@ Chat is the basic agent-native app starting point. It gives you a clean ChatGPT-
 
 If you want the smallest action-only runtime with no browser UI, start with [Pure-Agent Apps](/docs/pure-agent-apps). If you want a finished domain product shape, start from [Calendar](/docs/template-calendar), [Mail](/docs/template-mail), [Content](/docs/template-content), [Forms](/docs/template-forms), [Analytics](/docs/template-analytics), or another domain template.
 
-<!-- screenshot:
-  app: chat
-  view: /
-  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: 2434x1440 app screenshot
--->
-
-![Chat template with a centered agent composer and app navigation sidebar](/screenshots/chat.png)
+```an-wireframe
+{
+  "surface": "desktop",
+  "html": "<div style='min-height:560px;box-sizing:border-box;display:flex;align-items:center;justify-content:center;padding:56px 40px'><div style='display:flex;flex-direction:column;align-items:center;justify-content:center;gap:28px;width:min(700px,92%);min-height:430px'><div style='height:34px'></div><div style='text-align:center'><h1 style='margin:0'>How can I help?</h1><p class='wf-muted' style='margin:10px 0 0'>Chat about anything. Add actions, components, pages, jobs, or your own backend.</p></div><div class='wf-card' style='width:100%;min-height:150px;display:flex;flex-direction:column;gap:18px'><span class='wf-muted'>Message the agent...</span><div style='flex:1'></div><div style='display:flex;align-items:center;gap:10px'><span data-icon='plus' aria-label='Attach'></span><div style='flex:1'></div><span class='wf-pill'>Sonnet 4.6 · Auto</span><span class='wf-pill'>Act</span><button class='primary'>↑</button></div></div><div style='height:34px'></div></div></div>"
+}
+```
 
 ## What's in it {#whats-in-it}
 
@@ -38,6 +35,13 @@ If you want the smallest action-only runtime with no browser UI, start with [Pur
 
 That's the point. Chat is a thin, useful default shell for your own agent, not a domain product pretending to be generic.
 
+```an-diagram title="What ships in the Chat shell" summary="A thin chat surface over the framework's standard runtime — actions, durable threads, live sync, and auth — with room to add your own UI."
+{
+  "html": "<div class=\"diagram-chat\"><div class=\"diagram-col left\"><div class=\"diagram-node\">Thread list<br><small class=\"diagram-muted\">create · reopen · pin · archive</small></div><div class=\"diagram-node\">Full-page chat<br><small class=\"diagram-muted\">framework chat surface on /</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\">hello.ts · view-screen · navigate</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col right\"><div class=\"diagram-box\">Core SQL tables<br><small class=\"diagram-muted\">threads · application_state · settings · sessions · runs</small></div><div class=\"diagram-pill ok\">Live sync &#8635;</div><div class=\"diagram-box\">Better Auth<br><small class=\"diagram-muted\">login · orgs · sessions</small></div></div></div>",
+  "css": ".diagram-chat{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-chat .diagram-col{display:flex;flex-direction:column;gap:10px}.diagram-chat .diagram-arrow{font-size:22px;line-height:1}.diagram-chat .center{display:flex;flex-direction:column;align-items:center;gap:4px}"
+}
+```
+
 ## When to pick it {#when-to-pick}
 
 - **You want a basic app users can talk to immediately** and then extend with actions and UI.
@@ -70,6 +74,18 @@ From there, copy the Chat template's `/` route and sidebar thread list into your
   suggestions, empty state, composer, or surrounding layout here.
 - `AGENTS.md` tells the built-in agent how to work inside this app.
 
+```an-file-tree title="Chat template layout"
+{
+  "entries": [
+    { "path": "actions/hello.ts", "note": "the one example action; replace or add actions beside it" },
+    { "path": "actions/view-screen.ts", "note": "standard context action the agent reads" },
+    { "path": "actions/navigate.ts", "note": "standard navigation action" },
+    { "path": "app/routes/_index.tsx", "note": "renders the full-page chat surface; edit suggestions, empty state, composer" },
+    { "path": "AGENTS.md", "note": "chat-first guidance the built-in agent reads" }
+  ]
+}
+```
+
 The chat page is intentionally thin:
 
 ```tsx

package/docs/content/template-clips.md

@@ -7,18 +7,22 @@ description: "Async screen recording, calendar-synced meeting notes, and push-to
 
 A capture-everything app: screen recordings, meeting notes from your calendar, and Fn-hold voice dictation. The agent transcribes, titles, summarizes, and indexes all of it — then lets you ask "find the clip where we discussed the rollout plan" and searches across every transcript you've ever made.
 
-<!-- screenshot:
-  app: clips
-  view: /library
-  shows: Library with Acme Co. organization, folders (Onboarding videos / Customer calls / Bug repros) and spaces (Engineering / Design / Sales) in the sidebar, six recordings in a 3-column grid (Q3 OKRs review meeting, Walkthrough of new onboarding flow, Eng standup May 4, Dictation - Ideas for landing page copy, Customer call - Acme Corp pricing review, Bug repro - drag-and-drop in Safari)
-  account: screenshot-account (recordings imported into this org via the standard upload + meetings flow)
-  capture: 1400x800 viewport, cropped 90px from bottom (final 1400x710)
--->
-
-![Clips library with recordings, folders, and spaces](/screenshots/clips.png)
+```an-wireframe
+{
+  "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'>Engineering clips</h1><span class='wf-pill accent'>Library</span><span class='wf-pill'>Meetings</span><span class='wf-pill'>Dictation</span><div style='flex:1'></div><button>Import</button><button class='primary'>Record</button></div><div style='display:grid;grid-template-columns:repeat(3,1fr);gap:12px'><div class='wf-card' style='height:120px;display:flex;flex-direction:column;justify-content:end'><strong>OKRs review</strong><small>35 min</small></div><div class='wf-card' style='height:120px;display:flex;flex-direction:column;justify-content:end'><strong>Onboarding flow</strong><small>12 min</small></div><div class='wf-card' style='height:120px;display:flex;flex-direction:column;justify-content:end'><strong>Bug repro</strong><small>4 min</small></div></div><div class='wf-card' style='display:flex;gap:10px;align-items:center'><span class='wf-pill accent'>Agent-readable</span><span>Transcript + frames ready for share links</span><div style='flex:1'></div><button>Share</button></div><div class='wf-card' style='flex:1;display:flex;flex-direction:column;gap:8px'><strong>Transcript search</strong><div class='wf-box'>Matched chapter 03:12 · rollout risks and owner handoff</div><div class='wf-box'>Meeting summary and action items</div></div></div>"
+}
+```
 
 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.
 
+```an-diagram title="Capture, transcribe, reuse" summary="Three capture types land in one library; the agent transcribes, titles, and summarizes, then every transcript is searchable and shareable."
+{
+  "html": "<div class=\"diagram-clips\"><div class=\"diagram-col\"><div class=\"diagram-node\">Screen recording</div><div class=\"diagram-node\">Calendar meeting</div><div class=\"diagram-node\">Fn-hold dictation</div></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box\" data-rough>One library<br><small class=\"diagram-muted\">recordings + transcripts (SQL)</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\">title · summary · chapters</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-col\"><div class=\"diagram-pill\">Search</div><div class=\"diagram-pill\">Share</div><div class=\"diagram-pill\">Agent-readable links</div></div></div>",
+  "css": ".diagram-clips{display:flex;align-items:center;gap:12px;flex-wrap:wrap}.diagram-clips .diagram-col{display:flex;flex-direction:column;gap:8px}.diagram-clips .center{display:flex;flex-direction:column;align-items:center;gap:4px}.diagram-clips .diagram-arrow{font-size:22px;line-height:1}"
+}
+```
+
 ## What you can do with it
 
 - **Record your screen** with a built-in recorder, webcam overlay, audio capture, and pause/trim.
@@ -49,6 +53,51 @@ Password-protected clips require the password once; successful responses return
 short-lived tokenized links so downstream agents do not need the plaintext
 password.
 
+```an-api title="Agent context entry point"
+{
+  "method": "GET",
+  "path": "/api/agent-context.json",
+  "summary": "Compact, agent-readable description of a shared clip",
+  "description": "Returns clip metadata, transcript status, chapters, CTAs, recommended frames, and links to the transcript and frame APIs. Advertised by the public share page so a text- or image-only agent can understand a recording without ingesting raw video.",
+  "auth": "Same public / password / expiry rules as the share page",
+  "params": [
+    { "name": "id", "in": "query", "type": "string", "required": true, "description": "Recording id" }
+  ],
+  "responses": [
+    { "status": "200", "description": "Clip metadata plus transcript and frame API links" }
+  ]
+}
+```
+
+```an-api title="Timestamped transcript"
+{
+  "method": "GET",
+  "path": "/api/agent-transcript.json",
+  "summary": "Timestamped transcript segments for a shared clip",
+  "params": [
+    { "name": "id", "in": "query", "type": "string", "required": true, "description": "Recording id" }
+  ],
+  "responses": [
+    { "status": "200", "description": "Segments with startMs, endMs, readable timestamps, text, and optional source labels" }
+  ]
+}
+```
+
+```an-api title="Frame at a timestamp"
+{
+  "method": "GET",
+  "path": "/api/agent-frame.jpg",
+  "summary": "A JPEG frame extracted from the video at an original-video timestamp",
+  "params": [
+    { "name": "id", "in": "query", "type": "string", "required": true, "description": "Recording id" },
+    { "name": "atMs", "in": "query", "type": "integer", "required": true, "description": "Original-video timestamp in milliseconds" }
+  ],
+  "responses": [
+    { "status": "200", "description": "image/jpeg frame" }
+  ]
+}
+```
+
 ## Getting started
 
 Live demo: [clips.agent-native.com](https://clips.agent-native.com).
@@ -89,22 +138,81 @@ 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)
+### Key features
 
-**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.
+**One library, three capture types.** Screen recordings, calendar meetings, and push-to-talk dictations share one searchable library.
 
-**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.
+**Transcript and AI pipeline.** Recordings get timestamped transcript segments, generated titles, summaries, and chapter markers.
 
-**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.
+**Non-destructive editing.** Trim, split, filler-word removal, silence removal, and stitching stay in `edits_json` so original media remains 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.
+**Agent-readable share links.** Public share links expose transcript and frame APIs so agents can understand recordings without ingesting raw video.
 
 ### 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.
 
+```an-schema title="Clips core data model" summary="recordings is the source of truth for media; transcripts, meetings, and dictations compose with it rather than duplicating video. (Engagement and org tables omitted for clarity — see the full table below.)"
+{
+  "entities": [
+    {
+      "id": "recordings",
+      "name": "recordings",
+      "note": "Core resource; source of truth for media. ownableColumns",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "title", "type": "text" },
+        { "name": "video_url", "type": "text", "note": "plus format / size / duration / thumbnails" },
+        { "name": "status", "type": "text" },
+        { "name": "edits_json", "type": "text", "note": "Non-destructive edits" },
+        { "name": "chapters_json", "type": "text", "nullable": true },
+        { "name": "password", "type": "text", "nullable": true, "note": "Privacy: password / expiry" }
+      ]
+    },
+    {
+      "id": "recording_transcripts",
+      "name": "recording_transcripts",
+      "note": "Split out so the library and transcript views render fast",
+      "fields": [
+        { "name": "recording_id", "type": "text", "fk": "recordings.id" },
+        { "name": "segments_json", "type": "text", "note": "{ startMs, endMs, text }" },
+        { "name": "full_text", "type": "text" },
+        { "name": "language", "type": "text" },
+        { "name": "status", "type": "text" }
+      ]
+    },
+    {
+      "id": "clips_meetings",
+      "name": "clips_meetings",
+      "note": "Calendar-sourced or ad-hoc; owns a recording",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "recording_id", "type": "text", "fk": "recordings.id", "nullable": true },
+        { "name": "summary_md", "type": "text", "nullable": true },
+        { "name": "bullets_json", "type": "text", "nullable": true },
+        { "name": "action_items_json", "type": "text", "nullable": true }
+      ]
+    },
+    {
+      "id": "clips_dictations",
+      "name": "clips_dictations",
+      "note": "Push-to-talk dictation history; ownableColumns",
+      "fields": [
+        { "name": "id", "type": "text", "pk": true },
+        { "name": "full_text", "type": "text", "note": "Raw" },
+        { "name": "cleaned_text", "type": "text", "nullable": true },
+        { "name": "source", "type": "text", "note": "fn-hold, etc." },
+        { "name": "target_app", "type": "text", "nullable": true }
+      ]
+    }
+  ],
+  "relations": [
+    { "from": "recordings", "to": "recording_transcripts", "kind": "1-1", "label": "transcript" },
+    { "from": "recordings", "to": "clips_meetings", "kind": "1-1", "label": "captured by" }
+  ]
+}
+```
+
 | Table                                           | What it holds                                                                                                                                                                 |
 | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `recordings`                                    | The core resource — title, video URL/format/size, duration, thumbnails, status, non-destructive `edits_json`, `chapters_json`, privacy (password, expiry), and player toggles |