@agent-native/core 0.9.1 → 0.10.0

package/docs/content/extensions.md

@@ -1,230 +1,265 @@
 ---
 title: "Extensions"
-description: "Lightweight interactive apps — dashboards, widgets, calculators, monitors — that the agent creates for you instantly, without changing your app's code."
+description: "Mini-apps your users build inside your template — a custom KPI tile in Analytics, a meeting-prep checklist in Calendar, a contact CRM widget in Mail. No deploys, no code edits, no schema changes."
 ---
 
 # 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.
+Extensions are **mini-apps your users build inside your template**.
 
-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.
+If you've used QuickBooks Online, you've seen the model: QBO ships a core accounting product, and users layer on small custom widgets — a custom report, a payroll calculator, a tax-rule checker — that live inside the same app and use the same data. Extensions are the agent-native version of that idea, except your users don't write any code. They describe what they want, and the agent builds it.
 
-## Extensions vs. LLM tools {#extensions-vs-llm-tools}
+The framing matters: an extension isn't a generic "do whatever you want" sandbox. It's a **mini-app that extends a specific template** — Mail, Analytics, Calendar, Clips, Design — and uses that template's actions and data. A Mail extension reads emails. An Analytics extension reads a dashboard's metrics. A Calendar extension acts on the open event. They feel like part of the host product because they _are_ part of the host product.
 
-The word "tools" gets used in two different ways in this codebase, so we use distinct names to keep them clear:
+Three things make extensions work:
 
-- **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.
+- **No code, no deploy.** The agent writes them and they're live in seconds. Stored in the database, not the repo.
+- **Full access to the template's data.** Extensions can call the same actions the agent calls — `list-emails` in Mail, `list-decks` in Slides, `list-recordings` in Clips — so they have everything the host app has.
+- **Built-in storage.** Each extension has its own per-user / per-org key-value store, so it can save state without you adding a new SQL table.
 
-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.
+## A quick gallery {#gallery}
 
-## Extensions vs. editing the app {#extensions-vs-code}
+Real extensions people would actually build, grouped by the template they live in. Each one is one focused thing — not a Swiss-army knife.
 
-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.
+### Mail
 
-Extensions are different:
+A user is reading an email from `priya@acme.com`. What kind of widget would help right there?
 
-|                       | 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 |
+- **Contact notes** — a sticky-note pad pinned to whoever the user is emailing. Loads notes for that contact, lets the user jot more.
+- **Recent threads with this person** — a small list of the last five threads with the open contact, separate from the inbox view.
+- **CRM enrichment** — pulls the contact's company size, last meeting date, or open deals from your CRM.
+- **Meeting scheduler shortcut** — turns "find a time next week" into a one-click "send these slots" widget.
 
-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.
+Sketch — Contact notes (saves a note tied to whoever you're emailing):
 
-## When to build an extension vs. a template feature {#when-to-build}
+```html
+<div
+  class="p-4"
+  x-data="{
+    contactEmail: window.slotContext?.contactEmail,
+    note: '',
+    async init() {
+      if (!this.contactEmail) return;
+      const saved = await extensionData.get('notes', this.contactEmail);
+      if (saved) this.note = JSON.parse(saved.data).text;
+    },
+    async save() {
+      await extensionData.set('notes', this.contactEmail, { text: this.note });
+    }
+  }"
+>
+  <p class="text-xs text-muted-foreground mb-2" x-text="contactEmail"></p>
+  <textarea
+    x-model="note"
+    @blur="save()"
+    class="w-full rounded-md border bg-background p-2 text-sm"
+    rows="4"
+    placeholder="Notes about this contact..."
+  ></textarea>
+</div>
+```
 
-A quick decision rubric:
+### Analytics
 
-**Build an extension when:**
+A user is staring at a dashboard. What's the missing tile?
 
-- 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.
+- **Custom KPI box** — a single big number for a metric that isn't a built-in panel. "Trials started this week," "MRR delta vs last month."
+- **Goal tracker** — pulls a metric the user picks and shows progress against a target the user typed in.
+- **Top customers leaderboard** — joins a metric with a customer table, ranks the top 10.
 
-**Add a template feature when:**
+Sketch — Custom KPI box (calls one of the analytics template's `appAction` queries):
+
+```html
+<div
+  class="p-4"
+  x-data="{
+  value: null,
+  async init() {
+    const result = await appAction('query-agent-native-analytics', {
+      metric: 'trials_started',
+      range: '7d'
+    });
+    this.value = result?.total ?? 0;
+  }
+}"
+>
+  <p class="text-xs uppercase tracking-wider text-muted-foreground">
+    Trials this week
+  </p>
+  <p class="text-3xl font-bold mt-1" x-text="value ?? '—'"></p>
+</div>
+```
 
-- 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.
+### Calendar
 
-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.
+The user has an event open. What would help in that moment?
 
-## Creating an extension {#creating}
+- **Meeting prep checklist** — auto-loads agenda items, attendees, and prior thread summaries for the open event.
+- **Travel time** — "you have 35 minutes until your next meeting at the Mission location."
+- **Timezone helper** — shows the meeting time in every attendee's local time at a glance.
 
-### From the sidebar
+### Clips
 
-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.
+A user is reviewing a screen recording. What enhances that view?
 
-### From chat
+- **Action item extractor** — reads the clip transcript (the agent fetches it via `appAction`), lists the to-dos.
+- **Auto-share** — one-click "post this clip's link to my #recordings Slack channel."
+- **Highlight reel** — pulls the chapters the agent generated and turns them into a quick navigation menu.
 
-Just ask: "Create an extension that monitors our API health" or "Make me a calculator for shipping costs." The agent handles the rest.
+### Design
 
-### Updating an extension
+A user has a draft Alpine/Tailwind page open. What would smooth the prototyping loop?
 
-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.
+- **Brand color swatch** — palette pulled from the user's brand config, click to copy a color into the editor.
+- **Asset picker** — lists images the user has uploaded, drops the URL on click.
+- **Spacing inspector** — shows the gap/padding/margin tokens the active page uses, so the user can stay consistent.
 
-## What extensions can do {#capabilities}
+Pattern across all of these: extensions are about **the moment** the user is in inside the host template. The agent already knows which contact, which dashboard, which event, which clip — the extension uses that context.
 
-Extensions are fully capable despite being lightweight. They can:
+## How a user builds one {#building}
 
-- **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.
+The simple path:
 
-All of this works out of the box. No configuration, no new files, no schema changes.
+1. **Click "New Extension"** in the sidebar (or just ask in chat).
+2. **Describe what you want in one sentence.** "A sticky-note pad for the contact I'm emailing." "A KPI box for trials started this week."
+3. **The agent writes it and it appears in your Extensions list, ready to use.**
 
-## Layout defaults {#layout}
+No file to edit, no deploy. The agent picks the right helpers (`appAction`, `extensionData`, `extensionFetch`) and writes the Alpine.js HTML.
 
-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.)
+If the extension needs an API key — a CRM token, a weather API — the agent tells you what to add and where to add it. Keys are stored encrypted and locked to specific domains.
 
-## Persistent storage {#persistent-storage}
+If you want to change something later, just say so: "Add a search box to my contact notes." The agent edits the HTML in place — no regeneration of the whole thing.
 
-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.
+## What an extension can do {#capabilities}
 
-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.
+Inside the iframe sandbox, every extension has these helpers on `window`:
 
-### Scopes
+| Helper                                           | Purpose                                               | Example                                           |
+| ------------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------- |
+| `appAction(name, params)`                        | Call any of the host template's actions               | `appAction('list-emails', { view: 'inbox' })`     |
+| `appFetch(path, options)`                        | Call any app endpoint                                 | `appFetch('/api/settings')`                       |
+| `dbQuery(sql, args)`                             | Read from SQL (auto-scoped to the user)               | `dbQuery('SELECT id, name FROM tools')`           |
+| `dbExec(sql, args)`                              | Write to SQL                                          | `dbExec('INSERT INTO ...')`                       |
+| `extensionFetch(url, options)`                   | Hit external APIs through a secure proxy with secrets | `extensionFetch('https://api.github.com/user')`   |
+| `extensionData.set(collection, id, data, opts?)` | Persist data per-extension (user / org scoping)       | `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 a persisted item                               | `extensionData.remove('notes', 'note-1')`         |
 
-All `extensionData` methods accept an optional `{ scope }` option:
+Two rules of thumb:
 
-- `'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.
+- **Prefer `appAction` over `dbQuery`.** Actions are the template's official surface — they handle access control, scoping, and validation for you. Reach for raw SQL only when no action fits.
+- **Prefer `extensionData` over making new tables.** Each extension gets its own isolated key-value store. No schema, no migration. Set `{ scope: 'org' }` to share with the user's org, `'user'` (default) for private.
 
 ```html
 <script>
   // Private to me
-  await extensionData.set('notes', 'note-1', { title: 'My Note' });
+  await extensionData.set('notes', 'note-1', { title: 'My note' });
 
   // Shared with my org
-  await extensionData.set('notes', 'team-note', { title: 'Team Note' }, { scope: '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' });
+  // List everything visible to me (mine + org)
+  const all = 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.
+External APIs go through `extensionFetch`, which proxies the call server-side and substitutes secrets via the `${keys.NAME}` template:
 
 ```html
 <script>
   const res = await extensionFetch('https://api.github.com/user', {
-    headers: {
-      Authorization: 'Bearer ${keys.GITHUB_TOKEN}',
-    },
+    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.
+The actual key never reaches the browser. Each key is locked to an allowlist of domains, so a leaked extension can't exfiltrate it elsewhere.
 
-## Sharing {#sharing}
+## Slots — putting an extension inside the host UI {#slots}
 
-Extensions are **private by default** — only you can see and use an extension you create.
+The gallery above describes _what_ an extension does. Slots describe _where_ it appears.
 
-You can share extensions with your team:
+By default, an extension lives on its own page in the Extensions list — open it like a small app. That's fine for dashboards, calculators, and standalone widgets.
 
-- **Org-visible** — everyone in your organization can use it.
-- **Per-user sharing** — grant access to specific people as viewers, editors, or admins.
+But the most QBO-shaped use case is different: the user wants their widget pinned _inside_ the template's UI — under the contact info in Mail's sidebar, in the corner of an Analytics dashboard, on the right side of a Calendar event. That's what **slots** are for.
 
-Shared extensions have their own URLs, so you can link to them directly.
+A slot is a named widget area a template ships:
 
-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.
+| Template      | Example slot                   | Where it shows up                            |
+| ------------- | ------------------------------ | -------------------------------------------- |
+| **Mail**      | `mail.contact-sidebar.bottom`  | Below the contact info on every email thread |
+| **Analytics** | `analytics.dashboard.tiles`    | Alongside the dashboard's built-in panels    |
+| **Calendar**  | `calendar.event-detail.bottom` | Below the open event                         |
+| **Clips**     | `clips.right-panel.tabs`       | A new tab in the clip review panel           |
 
-## Security {#security}
+When an extension is **installed into a slot**, the host pushes the relevant context — the contact's email, the dashboard id, the event id — into the iframe. The extension reads `window.slotContext` to know what the user is looking at.
+
+### A concrete example
 
-Extensions run in a secure sandbox:
+Imagine the contact-notes extension from the gallery. On its own, it's a standalone widget. To make it appear inside the Mail contact sidebar:
 
-- **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.
+1. Build the extension once. Use `window.slotContext.contactEmail` so it knows which contact the user is on.
+2. Tell it the slot it can fill: `add-extension-slot-target { extensionId, slotId: "mail.contact-sidebar.bottom" }`.
+3. Install it: `install-extension { extensionId, slotId: "mail.contact-sidebar.bottom" }`.
 
-## Extension API reference {#api-reference}
+The next time you open an email thread, your sticky-note pad is right under the contact info — populated with notes for the person you're emailing. Switch to a different thread, the notes for _that_ contact load. Same extension, different context, no rewrites.
 
-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.
+In practice you don't run those three commands by hand. Just say "pin this widget to my contact sidebar" and the agent handles target + install for you.
 
-| 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/...')`    |
+> **Slots are an _added_ capability, not a prerequisite.** Plenty of useful extensions never get installed into a slot — they live happily on their own page. Reach for slots when the widget needs to be _next to_ what the user is looking at in the host template.
 
-`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.
+For deeper detail on slots — how to declare them in your template, how the context contract works, how installs are scoped — see the `extension-points` skill.
 
-> **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.
+## Sharing {#sharing}
+
+Extensions are private to the user who created them by default. To share:
+
+- **Org-visible** — everyone in the org can see and use it.
+- **Per-user grants** — invite specific people as viewer / editor / admin.
 
-### Routes {#routes}
+Shared extensions have their own URLs and plug into the same share dialog as documents, decks, and dashboards. Slot installs are always personal — sharing an extension means others _can_ install it; it doesn't auto-pin it to their UI.
 
-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.
+## Extensions vs. editing the app code {#vs-app-code}
 
-| 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         |
+The framework lets the agent edit the app's source code directly — components, routes, styles. So when should you reach for an extension instead?
 
-### Agent actions {#agent-actions}
+|                       | Extension                                         | App code edit                        |
+| --------------------- | ------------------------------------------------- | ------------------------------------ |
+| **Created by**        | Agent (or user) at runtime                        | Agent editing source files           |
+| **Stored in**         | The database                                      | The git repository                   |
+| **Requires a build**  | No                                                | Yes                                  |
+| **Requires a deploy** | No                                                | Yes                                  |
+| **Scope**             | One user (or shared with org)                     | The entire product, every user       |
+| **Best for**          | Personal widgets, custom KPIs, per-team utilities | Core features that ship to all users |
 
-The agent uses three actions to manage extensions on your behalf:
+Rule of thumb: **if it's for one user or one team, it's an extension.** If every user of the template should get it, ship it as a real feature.
+
+## Security {#security}
 
-| 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>` |
+Extensions run in a sandboxed iframe:
 
-> **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.
+- **Isolated** from the parent app's cookies, session, and DOM.
+- **Server-side secret injection** via the `${keys.NAME}` template — the actual key value never reaches the browser.
+- **Domain-locked secrets** — each key is bound to a URL allowlist; the proxy refuses requests to other hosts.
+- **Private-network protection** — extensions can't reach internal addresses.
+- **Auth required** — extensions only run for logged-in users, and `dbQuery` / `dbExec` calls are auto-scoped.
 
-## Examples {#examples}
+## A few things to know about naming {#naming-back-compat}
 
-Here are some things people build as extensions:
+If you're poking around the SQL or the source, you'll see a mix of "extension" and "tool" names. Quick decoder:
 
-- **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
+- The user-facing primitive used to be called "Tools." It's now **Extensions**.
+- The physical SQL tables (`tools`, `tool_data`, `tool_shares`, `tool_slots`, `tool_slot_installs`) keep their original names — renaming a table is a destructive migration, and the framework doesn't ship destructive migrations.
+- The Drizzle / TypeScript exports use the new names: `extensions`, `extensionData`, `extensionShares`, `extensionSlots`, `extensionSlotInstalls`.
+- Inside an extension's iframe, the canonical helpers are `extensionFetch` and `extensionData`. The legacy names `toolFetch` and `toolData` still resolve, so older extension HTML keeps working.
 
-To create any of these, just describe what you want in the agent chat.
+You also won't see this in normal use, but the agent has a third related concept called "LLM tools" — the function-call surface area on a model turn (defined via `defineAction`, MCP, etc.). Those are the function-calling primitive, not the user-facing widgets. When this page says "extension," it means the user-facing widget; when other docs say "tool" alongside `defineAction`, that's the LLM concept.
 
 ## 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
+- [**Templates**](/docs/cloneable-saas) — the host apps extensions extend
+- [**Actions**](/docs/actions) — the operations an extension calls via `appAction`
+- [**Sharing & Privacy**](/docs/sharing) — how extension visibility, org sharing, and per-user grants work
+- [**Onboarding & API Keys**](/docs/onboarding) — how secrets surface in the settings UI
+- [**Security**](/docs/security) — the framework's data scoping and access model

package/docs/content/faq.md

@@ -17,7 +17,7 @@ Agent-native is a framework for building apps where the AI agent and the UI are
 
 Anyone who wants to ship an AI-powered product without spending a year building the boring parts. That includes:
 
-- **Founders and PMs** who want to fork a working SaaS and make it their own — see [Cloneable SaaS](/docs/cloneable-saas).
+- **Founders and PMs** who want to fork a working SaaS and make it their own — see [Templates](/docs/cloneable-saas).
 - **Operators** who want a [pure-agent app](/docs/pure-agent-apps) — an agent that does work in the background with a minimal management UI.
 - **Developers** building agent-driven products from scratch and want auth, multi-tenancy, real-time sync, and an architecture that won't break when AI is the primary user.
 
@@ -71,7 +71,7 @@ The framework ships with production-ready templates you can use as daily drivers
 - **[Forms](/templates/forms)** — form builder (like Typeform)
 - **[Dispatch](/templates/dispatch)** — workspace control plane: shared secrets, integrations, jobs
 
-Each template is a complete app with UI, agent actions, database schema, and AI instructions. See [Cloneable SaaS](/docs/cloneable-saas) for the full picture, or all [Templates](/templates).
+Each template is a complete app with UI, agent actions, database schema, and AI instructions. See [Templates](/docs/cloneable-saas) for the full picture, or all [Templates](/templates).
 
 ### Can I customize templates? {#can-i-customize-templates}
 

package/docs/content/getting-started.md

@@ -12,7 +12,7 @@ By the end of this page, you'll have a working app — Mail, Calendar, Forms, or
 There are two ways to use agent-native, depending on how hands-on you want to be:
 
 - **You want to use a hosted version.** Try a template right now at [agent-native.com/templates](/templates). Each template is a live, hosted app — you sign in, start using it, and the agent is already there. No install, no setup. You can stop reading this page and head straight to the [template gallery](/templates).
-- **You want to run locally or customize it.** You'll clone a template, run it on your machine, and shape it however you want — branding, features, integrations. The rest of this page is for you. You'll need [Node.js](https://nodejs.org) and [pnpm](https://pnpm.io) installed.
+- **You want to run locally or customize it.** You'll clone a template, run it on your machine, and shape it however you want — branding, features, integrations. The rest of this page is for you. You'll need [Node.js 24 LTS](https://nodejs.org) and [pnpm](https://pnpm.io) installed.
 
 Not sure which path? If you've never written code, the hosted version is for you. If you have a developer or AI coding tool ready, the local path gives you total control.
 
@@ -26,9 +26,9 @@ cd my-platform
 pnpm install && pnpm dev
 ```
 
-The `create` command shows a multi-select picker — pick one template or several (Mail + Calendar + Forms, for example) and they all scaffold into one workspace sharing auth, brand, and agent config.
+The `create` command defaults to a workspace monorepo. It shows a multi-select picker — pick one template or several (Mail + Calendar + Forms, for example) and they all scaffold into one workspace sharing auth, brand, and agent config. If you want one app directory instead, pass `--standalone`.
 
-Open the URL the dev server prints (usually `http://localhost:3000`).
+Open the URL the dev server prints. Workspace apps use app-specific ports, often `http://localhost:8080` or another 808x port; standalone apps usually use `http://localhost:3000`.
 
 ## What just happened? {#what-just-happened}
 
@@ -40,24 +40,26 @@ You now have a real, full-featured app running on your machine. Open it in the b
 
 That parity between agent and UI is the whole point — see [What Is Agent-Native?](/docs/what-is-agent-native) for the bigger picture.
 
-## What's next {#whats-next}
+## Try one concrete next step {#first-next-step}
 
 From here, use any AI coding tool (Claude Code, Cursor, Windsurf, Builder.io) to customize the app. The agent instructions in `AGENTS.md` are already set up so any tool understands the codebase.
 
-Common next steps:
+Good first moves:
 
-- **Add another app to the same workspace** — run `agent-native add-app` from inside the workspace folder. See [Multi-App Workspace](/docs/multi-app-workspace) for sharing auth, components, and credentials across apps.
+- **Ask the built-in agent what it sees** — open the agent panel and type "what app am I looking at, and what can you do here?" This verifies the app, UI state, and agent loop are all talking to each other.
+- **Make a tiny customization** — ask your coding tool to rename the app, change the first screen copy, or add one field to a form. It will read `AGENTS.md` for the framework conventions.
+- **Add another app to the same workspace** — use `npx @agent-native/core add-app` from inside the workspace folder. The command starts at `npx`.
 - **Single app instead of a monorepo?** Pass `--standalone` when creating: `npx @agent-native/core create my-app --standalone --template mail`.
-- **Build a brand-new template from scratch** — see [Creating Templates](/docs/creating-templates) for the full Vite, Tailwind, and TypeScript setup.
-- **Understand the architecture** — see [Key Concepts](/docs/key-concepts) for how SQL, actions, polling sync, and context awareness fit together.
 
-## What's next {#next-steps}
+## Next docs to read {#next-docs}
 
-Once your app is running, the most common next steps are:
+Once your app is running, the most useful follow-ups are:
 
 - **Connect Slack or email** so you can message your agent from anywhere — see [Messaging](/docs/messaging).
 - **Set up Dispatch as your central inbox** to triage messages and orchestrate across multiple apps — see [Dispatch](/docs/dispatch).
 - **Customize via Workspace** — edit instructions, skills, memory, and connect MCP servers per user — see [Workspace](/docs/workspace).
+- **Troubleshoot common setup questions** — see the [FAQ](/docs/faq).
+- **Understand the architecture** — see [Key Concepts](/docs/key-concepts) for how SQL, actions, polling sync, and context awareness fit together.
 
 ## Templates {#templates}
 
@@ -77,7 +79,7 @@ Each template is a complete app with UI, agent actions, database schema, and AI
 | [Dispatch](/docs/template-dispatch) | Workspace control plane — secrets, routing, jobs |
 | [Starter](/docs/template-starter)   | Minimal scaffold — build from scratch            |
 
-Browse the [template gallery](/templates) for live demos, or see [Cloneable SaaS](/docs/cloneable-saas) for the full list and the clone → customize → deploy flow.
+Browse the [template gallery](/templates) for live demos, or see [Templates](/docs/cloneable-saas) for the full list and the clone → customize → deploy flow.
 
 ## Project structure {#project-structure}
 

package/docs/content/multi-app-workspace.md

@@ -86,13 +86,13 @@ Every app already knows how to log in, share the same database, and load the wor
 From anywhere inside the workspace:
 
 ```bash
-agent-native add-app
+npx @agent-native/core add-app
 ```
 
 The CLI shows the template picker again with apps you've already installed filtered out. Pick one or more and they get scaffolded under `apps/`. Non-interactive variant:
 
 ```bash
-agent-native add-app crm --template content
+npx @agent-native/core add-app crm --template content
 ```
 
 Any first-party template works as a workspace app — the CLI runs a small **workspacify** transform on the template that adds the shared package as a dep and resolves `workspace:*` references. No parallel "workspace-app" scaffold to maintain.

package/docs/content/observability.md

@@ -182,3 +182,50 @@ await putSetting("observability-config", {
 ```
 
 The framework emits `gen_ai.*` semantic convention spans compatible with the OpenTelemetry GenAI spec.
+
+## Error Reporting (Sentry)
+
+Server-side errors that escape Nitro route handlers are reported to Sentry when a DSN is configured. Without it the SDK silently no-ops, so it's safe to leave the env vars unset in dev. Three independent Sentry projects cover the framework:
+
+| Surface            | SDK               | Env var                  | Notes                                                                 |
+| ------------------ | ----------------- | ------------------------ | --------------------------------------------------------------------- |
+| Browser / SPA      | `@sentry/browser` | `VITE_SENTRY_CLIENT_DSN` | Captures unhandled errors and route-change breadcrumbs in the client. |
+| Nitro server       | `@sentry/node`    | `SENTRY_SERVER_DSN`      | Captures 5xx responses and Nitro lifecycle errors. Per-request user.  |
+| `agent-native` CLI | `@sentry/node`    | _hardcoded_              | Crash reports from the published CLI binary; not user-configurable.   |
+
+### Server-side configuration
+
+Set `SENTRY_SERVER_DSN` in the deploy environment (Netlify dashboard, Cloudflare secrets, etc.). The framework auto-mounts a Nitro plugin that:
+
+1. Calls `Sentry.init` once at startup (idempotent — safe to call from multiple plugins).
+2. Resolves the user via `getSession(event)` on every API/framework request and attaches `id` / `email` / `username` plus an `orgId` tag to Sentry's per-request isolation scope. Static-asset paths are skipped to avoid extra DB hits.
+3. Captures every framework-route 5xx with searchable `route`, `method`, and `userAgent` tags.
+
+Optional knobs:
+
+- `SENTRY_SERVER_TRACES_SAMPLE_RATE` (float `0`–`1`) — opt in to performance tracing. Defaults to `0` (errors only). Invalid values clamp to `0`.
+- `AGENT_NATIVE_RELEASE` — overrides the `release` tag. Defaults to `agent-native-server@<core-version>`.
+
+### Templates
+
+Every template inherits this automatically — there's nothing to import. Templates that want custom behavior (extra tags, different DSN per template, hard-disable Sentry) can override by exporting their own plugin from `server/plugins/sentry.ts`:
+
+```ts
+// server/plugins/sentry.ts
+import { createSentryPlugin } from "@agent-native/core/server";
+export default createSentryPlugin();
+```
+
+The CLI's hardcoded DSN is intentional — the published binary needs to phone home crashes regardless of which environment runs it. The server module never hardcodes a DSN because it runs inside customer environments where operators decide whether errors should reach Sentry at all.
+
+### Privacy & PII
+
+Both server and CLI initialize with `sendDefaultPii: false` and a `beforeSend` hook that strips:
+
+- `request.headers.authorization`, `cookie`, `set-cookie`, `proxy-authorization`
+- `request.cookies`
+- `user.ip_address` (auto-collected without consent)
+- `contexts.runtime_env` (process env snapshot)
+- Any event whose top-level exception type is `ValidationError` (treated as expected user-input rejection, not a bug).
+
+Identity fields explicitly set via `setUser({ id, email, username })` are preserved.

package/docs/content/pure-agent-apps.md

@@ -33,7 +33,7 @@ Pick the pure-agent pattern when:
 - **The domain is one-shot.** Research bot, summary generator, report writer. There's no persistent object that needs a list view.
 - **You're prototyping.** Ship the agent now; add a richer UI later if it turns out users actually want one.
 
-If your product is built around persistent objects users browse, pivot, and share — emails, events, documents, charts — pick a [cloneable SaaS](/docs/cloneable-saas) template instead. Those have full UIs _plus_ the agent.
+If your product is built around persistent objects users browse, pivot, and share — emails, events, documents, charts — pick a [template](/docs/cloneable-saas) instead. Those have full UIs _plus_ the agent.
 
 ## What ships in the box {#minimum-ui}