@agent-native/core 0.7.82 → 0.8.0

package/docs/content/extensions.md

@@ -0,0 +1,230 @@
+---
+title: "Extensions"
+description: "Lightweight interactive apps — dashboards, widgets, calculators, monitors — that the agent creates for you instantly, without changing your app's code."
+---
+
+# Extensions
+
+Extensions are lightweight interactive apps that live inside your agent-native app. Think dashboards, widgets, calculators, API monitors, data lookups — anything you'd otherwise build by hand.
+
+The key difference from the rest of your app: **extensions don't require code changes.** The agent creates and updates them at runtime, they're stored in the database, and they're ready to use immediately. No deploys, no builds, no pull requests.
+
+## Extensions vs. LLM tools {#extensions-vs-llm-tools}
+
+The word "tools" gets used in two different ways in this codebase, so we use distinct names to keep them clear:
+
+- **Extensions** (this primitive) — sandboxed Alpine.js mini-apps, rendered inside an iframe. They have a UI the user can interact with, persistent storage, and the ability to call your app's actions and external APIs. The rest of this page is about extensions.
+- **LLM tools / agent tools** — the function calls the agent makes during a turn (the things you define with `defineAction`, MCP tools, or that show up in `tools/list` / `tools/call`). These are not user-facing apps; they're the function-call surface area the model sees. When you read `tool: { description, parameters }` on an `ActionEntry`, "agent's tools", or "tool calls" elsewhere in these docs, that's the LLM-tools sense.
+
+Both senses can show up on the same page (extensions can _call_ agent actions, which the agent also sees as tools), so when in doubt: if it has a UI inside an iframe, it's an extension; if it's a function-call name on a model turn, it's an LLM tool.
+
+## Extensions vs. editing the app {#extensions-vs-code}
+
+Your agent-native app has a full codebase — React components, routes, actions, styles. When the agent edits that code, it's changing the app itself. That's powerful, but it requires a build step and a deploy.
+
+Extensions are different:
+
+|                       | App code                                | Extensions                                         |
+| --------------------- | --------------------------------------- | -------------------------------------------------- |
+| **Created by**        | Developer or agent editing source files | Agent or user, instantly from chat                 |
+| **Stored in**         | Git repository                          | Database                                           |
+| **Requires a build**  | Yes                                     | No                                                 |
+| **Requires a deploy** | Yes                                     | No                                                 |
+| **Scope**             | Part of the app for all users           | Private by default, shareable                      |
+| **Best for**          | Core app features                       | Personal dashboards, utilities, quick integrations |
+
+Use app code for features that are core to the product. Use extensions for everything else — one-off utilities, personal dashboards, quick integrations, monitors, and things you want to spin up in seconds.
+
+## When to build an extension vs. a template feature {#when-to-build}
+
+A quick decision rubric:
+
+**Build an extension when:**
+
+- It's for one user or one team, not the whole product.
+- It's a quick utility, dashboard, or widget you want now, not next sprint.
+- No new database schema is needed (or per-extension key-value storage is enough).
+- You want to ship it inside a single chat turn, no deploy.
+
+**Add a template feature when:**
+
+- Every user of the template should get it.
+- It needs new SQL tables, migrations, or shared schema changes.
+- The UI is complex enough to warrant React components, routes, and proper testing.
+- It's part of the product surface — something you'd advertise on a landing page.
+
+When in doubt, start as an extension. Promoting an extension to a template feature later is straightforward; rolling back a half-shipped product feature is not.
+
+## Creating an extension {#creating}
+
+### From the sidebar
+
+Click the **+** button in the Extensions section of the sidebar. Describe what you want in plain language — "a dashboard that shows my open GitHub PRs" — and the agent builds it for you.
+
+### From chat
+
+Just ask: "Create an extension that monitors our API health" or "Make me a calculator for shipping costs." The agent handles the rest.
+
+### Updating an extension
+
+Ask the agent: "Update my PR dashboard to also show draft PRs" or "Add a dark mode toggle to the weather widget." The agent makes surgical edits without regenerating the whole thing.
+
+## What extensions can do {#capabilities}
+
+Extensions are fully capable despite being lightweight. They can:
+
+- **Call external APIs** — GitHub, Stripe, weather services, any REST API. Requests go through a secure server-side proxy that keeps your API keys safe.
+- **Call your app's actions** — anything your agent can do, an extension can trigger.
+- **Query your app's database** — read and write data directly.
+- **Store their own data** — each extension has built-in persistent storage, no setup required. Save notes, preferences, cached results — whatever the extension needs.
+- **Call any endpoint in your app** — hit custom API routes, webhooks, or internal services.
+
+All of this works out of the box. No configuration, no new files, no schema changes.
+
+## Layout defaults {#layout}
+
+Extensions render with modest canvas padding by default so simple widgets and dashboards do not hug the iframe edge. For full-bleed experiences such as maps, canvases, or custom editors, set `data-tool-layout="full-bleed"` or `data-tool-padding="none"` on the outermost element. (The `data-tool-*` attribute names are kept for backward compatibility — `data-extension-layout` / `data-extension-padding` aliases are also accepted.)
+
+## Persistent storage {#persistent-storage}
+
+Every extension has access to a built-in key-value store via the `extensionData` helper (also exposed as `toolData` for backward compatibility). Data is automatically scoped per extension and per user — your data stays yours.
+
+When you ask the agent to "add persistence" or "remember state" in an extension, it uses this built-in storage. No database tables to create, no migrations to run.
+
+### Scopes
+
+All `extensionData` methods accept an optional `{ scope }` option:
+
+- `'user'` (default) — private to the current user.
+- `'org'` — shared across the user's organization.
+- `'all'` — list/get only; returns both user-scoped and org-scoped items.
+
+```html
+<script>
+  // Private to me
+  await extensionData.set('notes', 'note-1', { title: 'My Note' });
+
+  // Shared with my org
+  await extensionData.set('notes', 'team-note', { title: 'Team Note' }, { scope: 'org' });
+
+  // List my notes (default)
+  const mine = await extensionData.list('notes');
+
+  // List both mine and the org's
+  const everything = await extensionData.list('notes', { scope: 'all' });
+</script>
+```
+
+> **Legacy alias.** The original helper was named `toolData`; both `toolData` and `extensionData` resolve to the same store and accept identical arguments. New extensions should use `extensionData`; existing code using `toolData` keeps working.
+
+## API keys and secrets {#secrets}
+
+When an extension needs an API key (for GitHub, OpenAI, a weather service, etc.), the agent will tell you what's needed and where to get it. You add the key through the Settings UI in the agent sidebar.
+
+Keys are encrypted and stored securely. Each key is restricted to specific domains — a GitHub token can only be sent to `api.github.com`, never anywhere else.
+
+### Secrets in extensions {#secrets-in-extensions}
+
+Extensions reference secrets in `extensionFetch()` calls (legacy alias: `toolFetch()`) using the `${keys.NAME}` template pattern. The proxy substitutes the encrypted value server-side; the actual key never reaches the browser.
+
+```html
+<script>
+  const res = await extensionFetch('https://api.github.com/user', {
+    headers: {
+      Authorization: 'Bearer ${keys.GITHUB_TOKEN}',
+    },
+  });
+</script>
+```
+
+When an extension needs a one-off key, the agent can register an ad-hoc secret via `POST /_agent-native/secrets/adhoc` with a `urlAllowlist` that pins which domains the secret may be sent to. A request to any other host is rejected before the proxy fires. Combined with SSRF and private-network protections, this means a leaked extension can't exfiltrate secrets to an attacker-controlled URL.
+
+## Sharing {#sharing}
+
+Extensions are **private by default** — only you can see and use an extension you create.
+
+You can share extensions with your team:
+
+- **Org-visible** — everyone in your organization can use it.
+- **Per-user sharing** — grant access to specific people as viewers, editors, or admins.
+
+Shared extensions have their own URLs, so you can link to them directly.
+
+Under the hood, extensions use the same ownable-resource model as the rest of the framework — `ownableColumns()` on the `extensions` Drizzle export (physical SQL table: `tools`) and a standard `createSharesTable()` for grants (physical table: `tool_shares`, exported as `extensionShares`). That means extensions plug into the same share dialog, access checks, and audit surfaces as documents, decks, dashboards, and any other shareable resource. See [Security](/docs/security) for the full access model.
+
+## Security {#security}
+
+Extensions run in a secure sandbox:
+
+- **Isolated** — extensions can't access your app's cookies, session, or page content.
+- **API keys stay server-side** — secrets are injected by the server, never exposed to the browser.
+- **Domain-restricted secrets** — each API key can only be sent to its approved domains.
+- **Private network protection** — extensions can't reach internal/private network addresses.
+- **Authentication required** — only logged-in users can use extensions.
+
+## Extension API reference {#api-reference}
+
+Every extension runs inside a sandboxed iframe with the following helpers injected on `window`. They are the complete surface area — anything else an extension needs has to go through one of these.
+
+| Helper                                           | Purpose                    | Example                                           |
+| ------------------------------------------------ | -------------------------- | ------------------------------------------------- |
+| `extensionData.set(collection, id, data, opts?)` | Persist data per-extension | `extensionData.set('notes', id, { text: '...' })` |
+| `extensionData.list(collection, opts?)`          | List persisted items       | `extensionData.list('notes', { scope: 'all' })`   |
+| `extensionData.get(collection, id, opts?)`       | Get a single item          | `extensionData.get('notes', 'note-1')`            |
+| `extensionData.remove(collection, id, opts?)`    | Delete persisted item      | `extensionData.remove('notes', 'note-1')`         |
+| `appAction(name, params)`                        | Call any app action        | `appAction('list-emails', { view: 'inbox' })`     |
+| `dbQuery(sql, args)`                             | Read from SQL              | `dbQuery('SELECT * FROM tools')`                  |
+| `dbExec(sql, args)`                              | Write to SQL               | `dbExec('INSERT INTO ...')`                       |
+| `appFetch(path, options)`                        | Call any app endpoint      | `appFetch('/api/settings')`                       |
+| `extensionFetch(url, options)`                   | External API via proxy     | `extensionFetch('https://api.github.com/...')`    |
+
+`appAction` is the preferred way to trigger app behavior — it routes through the same actions the agent and the frontend use, so authorization and access scoping happen automatically. Drop down to `dbQuery`/`dbExec` only when there's no action that fits.
+
+> **Legacy aliases and physical names.** `toolData` and `toolFetch` are kept as aliases for `extensionData` and `extensionFetch`. The physical SQL tables (`tools`, `tool_data`, `tool_shares`) and the `tool_id` foreign-key column also keep their original names — only the public Drizzle/TypeScript exports (`extensions`, `extensionData`, `extensionShares`) and the iframe globals were renamed.
+
+### Routes {#routes}
+
+The framework mounts the following endpoints under `/_agent-native/extensions/`. Extensions themselves rarely call these directly — they're useful when integrating extensions with external scripts or custom UI. The legacy `/_agent-native/tools/*` paths still resolve and are kept for backward compatibility.
+
+| Method | Path                                   | Purpose                                           |
+| ------ | -------------------------------------- | ------------------------------------------------- |
+| GET    | `/_agent-native/extensions`            | List extensions (filtered by ownership + sharing) |
+| POST   | `/_agent-native/extensions`            | Create an extension                               |
+| GET    | `/_agent-native/extensions/:id`        | Get a single extension                            |
+| PUT    | `/_agent-native/extensions/:id`        | Update (supports `patches` for diffing)           |
+| DELETE | `/_agent-native/extensions/:id`        | Delete an extension                               |
+| GET    | `/_agent-native/extensions/:id/render` | Render the iframe HTML                            |
+| POST   | `/_agent-native/extensions/proxy`      | Authenticated proxy with secret injection         |
+
+### Agent actions {#agent-actions}
+
+The agent uses three actions to manage extensions on your behalf:
+
+| Action             | What it does                                                              |
+| ------------------ | ------------------------------------------------------------------------- |
+| `create-extension` | Create a new extension (name, description, Alpine.js HTML content)        |
+| `update-extension` | Update an extension — use `patches` array for find/replace diffs          |
+| `navigate`         | Navigate to `--view=extensions` or `--view=extensions --extensionId=<id>` |
+
+> **Legacy action names.** `create-tool` and `update-tool` continue to work as aliases for `create-extension` and `update-extension`. New code should use the `*-extension` names.
+
+## Examples {#examples}
+
+Here are some things people build as extensions:
+
+- **GitHub PR dashboard** — see open PRs, review status, and CI checks at a glance
+- **API health monitor** — check if your services are up with a single click
+- **Weather widget** — quick weather lookup for any city
+- **Stripe payment lookup** — search recent payments and refunds
+- **Database explorer** — browse and query your app's data
+- **Shipping cost calculator** — compute rates based on weight and destination
+- **Meeting notes summarizer** — paste notes, get action items
+- **Social media scheduler** — draft and schedule posts across platforms
+
+To create any of these, just describe what you want in the agent chat.
+
+## What's next
+
+- [**Actions**](/docs/actions) — the operations that extensions (and the agent) can call
+- [**Workspace**](/docs/workspace) — the broader workspace system extensions live alongside
+- [**Security**](/docs/security) — the framework's data scoping and access control

package/docs/content/key-concepts.md

@@ -270,9 +270,9 @@ Every user gets a personal **workspace** — instructions, skills, memory, custo
 
 **Dispatch** is the workspace control plane: a central inbox for Slack/email/Telegram, a shared secrets vault, scheduled jobs, and an orchestrator agent that delegates domain work to specialist apps over A2A. Run it alongside your domain apps when you have more than one. See [Dispatch](/docs/dispatch).
 
-## Tools {#tools}
+## Extensions {#extensions}
 
-**Tools** are sandboxed mini-apps the agent can create at runtime — Alpine.js HTML rendered inside an iframe, with built-in helpers for persistent storage (`toolData`), calling app actions (`appAction`), and proxied external APIs (`toolFetch`). No source-code changes, no schema migrations. See [Tools](/docs/tools).
+**Extensions** are sandboxed mini-apps the agent can create at runtime — Alpine.js HTML rendered inside an iframe, with built-in helpers for persistent storage (`extensionData`), calling app actions (`appAction`), and proxied external APIs (`extensionFetch`). No source-code changes, no schema migrations. (Distinct from LLM "tools" — the function-call surface area the agent uses, e.g. `defineAction` entries and MCP tools. See [Extensions](/docs/extensions).)
 
 ## A2A {#a2a}
 

package/docs/content/server.md

@@ -116,19 +116,19 @@ Migrations must be additive. Never put destructive SQL in startup plugins.
 
 The framework mounts its own routes under `/_agent-native/`. Treat that namespace as reserved.
 
-| Route prefix                     | Purpose                              |
-| -------------------------------- | ------------------------------------ |
-| `/_agent-native/actions/:name`   | Action HTTP endpoints                |
-| `/_agent-native/agent-chat`      | Agent chat loop                      |
-| `/_agent-native/poll`            | SQL-backed UI sync                   |
-| `/_agent-native/resources/*`     | Workspace resources                  |
-| `/_agent-native/tools/*`         | Runtime tools and tool proxy         |
-| `/_agent-native/integrations/*`  | Messaging/webhook integrations       |
-| `/_agent-native/a2a`             | Agent-to-agent JSON-RPC              |
-| `/_agent-native/mcp`             | MCP endpoint                         |
-| `/_agent-native/onboarding/*`    | Setup checklist                      |
-| `/_agent-native/observability/*` | Traces, feedback, evals, experiments |
-| `/_agent-native/file-upload`     | File upload provider endpoint        |
+| Route prefix                     | Purpose                                                                         |
+| -------------------------------- | ------------------------------------------------------------------------------- |
+| `/_agent-native/actions/:name`   | Action HTTP endpoints                                                           |
+| `/_agent-native/agent-chat`      | Agent chat loop                                                                 |
+| `/_agent-native/poll`            | SQL-backed UI sync                                                              |
+| `/_agent-native/resources/*`     | Workspace resources                                                             |
+| `/_agent-native/extensions/*`    | Runtime extensions and extension proxy (legacy alias: `/_agent-native/tools/*`) |
+| `/_agent-native/integrations/*`  | Messaging/webhook integrations                                                  |
+| `/_agent-native/a2a`             | Agent-to-agent JSON-RPC                                                         |
+| `/_agent-native/mcp`             | MCP endpoint                                                                    |
+| `/_agent-native/onboarding/*`    | Setup checklist                                                                 |
+| `/_agent-native/observability/*` | Traces, feedback, evals, experiments                                            |
+| `/_agent-native/file-upload`     | File upload provider endpoint                                                   |
 
 Custom app routes should use `/api/*`, public app paths, or provider-specific callback paths that do not collide with `/_agent-native/`.
 

package/docs/content/sharing.md

@@ -51,7 +51,7 @@ Every template that stores user-authored work uses this model. Concretely:
 - **Forms** — form definitions
 - **Calendar** — events and booking links
 - **Analytics** — dashboards (rolling out — see the analytics template's `AGENTS.md`)
-- **Tools** — sandboxed mini-apps (see [Tools](/docs/tools#sharing))
+- **Extensions** — sandboxed mini-apps (see [Extensions](/docs/extensions#sharing))
 
 Every one of these uses the same `ownableColumns()` schema helper, the same `share-resource` action, and the same `<ShareButton>` UI. Move from one template to another and the share dialog looks identical.
 
@@ -151,5 +151,5 @@ See [Security & Data Scoping](/docs/security) for the full model and threat surf
 
 - [Security & Data Scoping](/docs/security) — the access-filter and ownership model that sharing rides on.
 - [Authentication](/docs/authentication) — sessions, organizations, and how identity flows into the request context.
-- [Tools](/docs/tools#sharing) — sharing in the sandboxed mini-app surface.
+- [Extensions](/docs/extensions#sharing) — sharing in the sandboxed mini-app surface.
 - [Creating Templates](/docs/creating-templates) — wiring `ownableColumns` into a new template's schema.

package/docs/content/template-analytics.md

@@ -7,6 +7,16 @@ description: "Ask analytics questions in plain English, get charts and dashboard
 
 Ask analytics questions in plain English, get charts and dashboards back. The agent connects to BigQuery, GA4, Amplitude, the built-in first-party event collector, HubSpot, Jira, and a dozen other sources, writes the query for you, validates it, and renders the answer as a chart, table, or saved dashboard panel.
 
+<!-- screenshot:
+  app: analytics
+  view: /adhoc/<dashboard-id>
+  shows: Adhoc dashboard with 3 KPI cards (Weekly active users 24,318 / New signups 1,842 / Revenue MRR $48,210), Weekly active users line chart and Revenue over time area chart side by side, Signups by source bar chart below
+  account: screenshot-account (dashboard authored on this account against a seeded warehouse)
+  capture: 1400x800 viewport, cropped 90px from bottom (final 1400x710)
+-->
+
+![Analytics dashboard with KPIs and charts](/screenshots/analytics.png)
+
 It's an open-source replacement for Amplitude, Mixpanel, and Looker — for teams that want to own the code, the queries, and the data.
 
 ## What you can do with it

package/docs/content/template-calendar.md

@@ -7,6 +7,16 @@ 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)
+-->
+
+![Calendar week view with a populated week and the agent sidebar](/screenshots/calendar.png)
+
 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.
 
 ## What you can do with it

package/docs/content/template-clips.md

@@ -7,6 +7,16 @@ description: "Async screen recording (Loom-style), calendar-synced meeting notes
 
 A capture-everything app: screen recordings (Loom-style), meeting notes from your calendar (Granola-style), and Fn-hold voice dictation (Wisprflow-style). 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)
+
 Think along the lines of Loom + Granola + Wisprflow 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.
 
 ## What you can do with it

package/docs/content/template-content.md

@@ -7,6 +7,16 @@ description: "A Notion-style document editor with an AI agent that can read, wri
 
 A Notion-style document workspace where the agent can read, write, reorganize, and publish pages for you. Open a doc, ask "rewrite this paragraph to be more concise" or "create a page called Q4 Planning with sub-pages for Goals, Metrics, and Risks" — same result whether you do it yourself or ask.
 
+<!-- screenshot:
+  app: content
+  view: /<doc-id>
+  shows: Workspace with sidebar tree (Q3 Roadmap favorited and expanded with Goals/Metrics/Risks, Engineering Wiki with On-call playbook + Architecture overview + Deployment guide, Personal section with Reading list and Ideas, Weekly sync — May 1) and the Q3 Roadmap document open in the editor with the agent sidebar
+  account: screenshot-account (page tree authored on this account; the doc body should NOT begin with the page title — the page chrome already renders it)
+  capture: 1400x800 viewport, cropped 90px from bottom (final 1400x710)
+-->
+
+![Content workspace with the page tree, an open document, and the agent sidebar](/screenshots/content.png)
+
 When you open the app, you'll see a sidebar tree of pages on the left, the editor in the middle, and the agent in the sidebar on the right. The agent always knows which page you're viewing and what text you have selected.
 
 ## What you can do with it

package/docs/content/template-dispatch.md

@@ -9,6 +9,16 @@ description: "Dispatch is the workspace control plane — central inbox, cross-a
 
 Dispatch is the **workspace control plane**. Where other templates are domain apps (Mail, Calendar, Analytics), Dispatch is the app you run _alongside_ them to coordinate everything: a central inbox, a secrets vault, scheduled jobs, Slack/Telegram integration, and an orchestrator agent that delegates domain work to the right specialist app over [A2A](/docs/a2a-protocol).
 
+<!-- screenshot:
+  app: dispatch
+  view: /overview
+  shows: Overview with "What should we do next?" composer, prompt suggestions (Create a lightweight customer onboarding app / Ask Slides to draft a board update from our latest metrics / Schedule a Monday morning analytics digest), and the Workspace apps grid (Mail / Calendar / Slides / Analytics / Forms / Content + Create app placeholder) showing each mounted path + description
+  account: screenshot-account (workspace seeded with the six sibling apps registered as A2A peers)
+  capture: 1400x900 viewport, cropped 90px from bottom (final 1400x810)
+-->
+
+![Dispatch overview with the orchestrator chat and workspace apps grid](/screenshots/dispatch.png)
+
 If you're running an [multi-app workspace](/docs/multi-app-workspace) with many apps, Dispatch is the glue.
 
 ## What it does {#what-it-does}
@@ -65,6 +75,11 @@ Dispatch is usually scaffolded into a workspace alongside the apps it coordinate
 
 Dispatch is a full cloneable SaaS like any other template — see [Cloneable SaaS](/docs/cloneable-saas). Ask the agent to "add a new integration for Datadog" or "route Slack DMs from channel X to the issues agent" and it'll edit the routing config, add the webhook handler, and wire it up.
 
+For workspace-specific management screens, add local React Router pages and
+register them in `app/dispatch-extensions.tsx`. The generated workspace owns
+only the extra tab and route; `@agent-native/dispatch` keeps owning the shell,
+sidebar, built-in pages, and future package updates.
+
 ## What's next
 
 - [**Messaging**](/docs/messaging) — connecting Slack, email, and Telegram so you can talk to your agent from anywhere

package/docs/content/template-forms.md

@@ -7,6 +7,16 @@ description: "Agent-native form builder — create, edit, publish, and route for
 
 Forms is an agent-native form builder. Describe the form you want, refine it in the editor, and publish a public form that stores submissions in your own SQL database.
 
+<!-- screenshot:
+  app: forms
+  view: /forms/<id>
+  shows: Editor for a "Beta signup" form — sidebar with 5 forms (Beta signup selected, Customer feedback Q3, Job application Engineering, Event RSVP, New customer onboarding); editor pane with title, description, and field cards (Full name, Work email, Your role, Team size, What problem are you hoping to solve?); Edit/Results/Settings/Integrations tabs and Share + Unpublish buttons; agent sidebar with form-related suggestions
+  account: screenshot-account (forms authored on this account via the standard build flow, with realistic response counts seeded by submitting through the public URL)
+  capture: 1400x800 viewport, cropped 90px from bottom (final 1400x710)
+-->
+
+![Forms editor with a form open and the agent sidebar](/screenshots/forms.png)
+
 When you open the app, you see your forms, the current editor, and a live preview. The agent can create a form from a prompt, update field labels and options, change validation, and connect submission destinations using the same actions the UI uses.
 
 ## What you can do with it

package/docs/content/template-mail.md

@@ -7,6 +7,16 @@ 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)
+-->
+
+![Mail inbox with the agent sidebar](/screenshots/mail.png)
+
 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.
 
 ## What you can do with it

package/docs/content/template-slides.md

@@ -7,7 +7,17 @@ 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.
 
-When you open the app, you'll see your deck list. Click into a deck and you get a slide editor in the middle, a sidebar of slides on the left, and the agent on the right.
+<!-- 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
+-->
+
+![Slides deck editor with a deck open and slide thumbnails on the left](/screenshots/slides.png)
+
+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.
 
 ## What you can do with it
 

package/docs/content/template-starter.md

@@ -7,6 +7,16 @@ description: "The minimal agent-native scaffold — agent chat, actions, applica
 
 Starter is the minimum viable agent-native app. You get the six-rules architecture, the agent sidebar, the workspace tab, polling sync, auth, and exactly one example action. Nothing else. Build from there.
 
+<!-- screenshot:
+  app: starter
+  view: /
+  shows: Blank-slate app with sidebar (Starter brand, Home / New App / Observability), centered "Blank app" card with Start building prompt button + 3 quick-action tiles (New app / Documentation / Theme), agent chat panel on the right
+  account: screenshot-account (no domain data needed — starter ships with no seed schema)
+  capture: 1400x800 viewport, cropped 90px from bottom (final 1400x710)
+-->
+
+![Starter scaffold with the agent sidebar and a clean blank-slate UI](/screenshots/starter.png)
+
 Pick Starter when you're not sure which domain template fits, or when you want to learn the framework by doing — there's almost nothing to delete.
 
 ## What's in it {#whats-in-it}

package/docs/content/template-video.md

@@ -7,6 +7,16 @@ 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)
+
 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.
 
 ## What you can do with it

package/docs/content/what-is-agent-native.md

@@ -179,5 +179,5 @@ One action, four surfaces: the agent calls it as a tool, the UI calls it as a ty
 - [**Cloneable SaaS**](/docs/cloneable-saas) — templates as complete products you own
 - [**Workspace**](/docs/workspace) — the per-user customization layer (skills, memory, instructions, MCP) backed by SQL, not files
 - [**Dispatch**](/docs/dispatch) — the workspace control plane: secrets vault, Slack/email inbox, cross-app delegation
-- [**Tools**](/docs/tools) — sandboxed mini-apps the agent creates instantly without code changes
+- [**Extensions**](/docs/extensions) — sandboxed mini-apps the agent creates instantly without code changes
 - [**Drop-in Agent**](/docs/drop-in-agent) — mount `<AgentPanel>` into any React app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.7.82",
+  "version": "0.8.0",
   "type": "module",
   "description": "Framework for agent-native application development — where AI agents and UI share state via files",
   "license": "MIT",
@@ -13,6 +13,10 @@
     "url": "https://github.com/BuilderIO/agent-native/issues"
   },
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "bin": {
     "agent-native": "dist/cli/index.js"
   },
@@ -40,8 +44,9 @@
     "./settings": "./dist/settings/index.js",
     "./credentials": "./dist/credentials/index.js",
     "./event-bus": "./dist/event-bus/index.js",
-    "./fetch-tool": "./dist/tools/fetch-tool.js",
-    "./tools/url-safety": "./dist/tools/url-safety.js",
+    "./fetch-tool": "./dist/extensions/fetch-tool.js",
+    "./extensions/url-safety": "./dist/extensions/url-safety.js",
+    "./tools/url-safety": "./dist/extensions/url-safety.js",
     "./file-upload": "./dist/file-upload/index.js",
     "./resources": "./dist/resources/index.js",
     "./resources/store": "./dist/resources/store.js",
@@ -56,7 +61,8 @@
     "./sharing/actions/list-resource-shares": "./dist/sharing/actions/list-resource-shares.js",
     "./sharing/actions/set-resource-visibility": "./dist/sharing/actions/set-resource-visibility.js",
     "./client/sharing": "./dist/client/sharing/index.js",
-    "./client/tools": "./dist/client/tools/index.js",
+    "./client/extensions": "./dist/client/extensions/index.js",
+    "./client/tools": "./dist/client/extensions/index.js",
     "./client/transcription/use-live-transcription": "./dist/client/transcription/use-live-transcription.js",
     "./client/transcription/BuilderTranscriptionCta": "./dist/client/transcription/BuilderTranscriptionCta.js",
     "./transcription/builder": "./dist/transcription/builder-transcription.js",
@@ -67,6 +73,7 @@
     "./mcp": "./dist/mcp/index.js",
     "./mcp-client": "./dist/mcp-client/index.js",
     "./tracking": "./dist/tracking/index.js",
+    "./usage": "./dist/usage/store.js",
     "./notifications": "./dist/notifications/index.js",
     "./client/notifications": "./dist/client/notifications/index.js",
     "./progress": "./dist/progress/index.js",
@@ -85,15 +92,6 @@
     "tsconfig.base.json",
     "src/templates"
   ],
-  "scripts": {
-    "build": "tsc && node scripts/finalize-build.mjs",
-    "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest --run src",
-    "prepack": "cp ../../README.md ./README.md",
-    "prepublishOnly": "npm run build",
-    "release": "npm version patch && npm publish --access public"
-  },
   "dependencies": {
     "@amplitude/analytics-browser": "^2.41.1",
     "@anthropic-ai/sdk": "^0.90.0",
@@ -263,7 +261,7 @@
     "@react-router/fs-routes": "^7.13.1",
     "@supabase/supabase-js": "^2.49.0",
     "@tabler/icons-react": "^3.40.0",
-    "@tailwindcss/vite": "catalog:",
+    "@tailwindcss/vite": "^4.2.4",
     "@tanstack/react-query": "^5.99.2",
     "@types/better-sqlite3": "^7.6.13",
     "@types/diff-match-patch": "^1.0.36",
@@ -283,10 +281,17 @@
     "node-pty": "^1.1.0",
     "react": "^19.2.5",
     "react-router": "^7.13.1",
-    "tailwindcss": "catalog:",
+    "tailwindcss": "^4.2.4",
     "typescript": "^6.0.3",
-    "vite": "catalog:",
+    "vite": "8.0.3",
     "vitest": "^4.1.5",
     "ws": "^8.18.0"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/finalize-build.mjs",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --run src",
+    "release": "npm version patch && npm publish --access public"
   }
-}
+}

package/src/templates/workspace-root/README.md

@@ -39,12 +39,13 @@ the shared package (`@{{APP_NAME}}/shared`).
 pnpm install
 cp .env.example .env   # fill in DATABASE_URL, BETTER_AUTH_SECRET, and an LLM provider key
 pnpm repair:workspace-org -- --name "Example Co" --domain example.com --owner-email owner@example.com
-pnpm dev               # starts the workspace gateway and opens Dispatch
+pnpm dev               # starts the workspace gateway; opens Dispatch when present
 ```
 
-The dev gateway serves Dispatch at `/dispatch` and every app at its own path
-such as `/starter`. It watches `apps/`, so newly-created apps are detected and
-started without restarting `pnpm dev`.
+The dev gateway serves Dispatch at `/dispatch` when you keep the recommended
+Dispatch app selected, and every app at its own path such as `/starter`. It
+watches `apps/`, so newly-created apps are detected and started without
+restarting `pnpm dev`.
 
 ## Workspace org identity