Extensions

---
name: extensions
description: >-
  Creating, editing, and managing extensions — sandboxed Alpine.js mini-apps
  that run inside iframes. Use when a user asks for a dashboard, widget,
  calculator, or any interactive mini-app that calls external APIs. Distinct
  from LLM "tools" (function calls) — see note below.
---

# Extensions

> **Terminology note.** This skill is about **extensions** — the framework's
> user-authored mini-app primitive (sandboxed Alpine.js HTML rendered in an
> iframe). It is NOT the same thing as **LLM "tools"**, which are the
> function-calling primitives the AI agent uses (actions, MCP tools, etc.).
> Other skills still talk about "the agent calls actions as tools" — that's
> the LLM concept and stays as-is. When this doc says "tool" without
> qualification, it means LLM tool. When it says "extension", it means the
> sandboxed mini-app.
>
> Historical naming: extensions were previously called "tools". The physical
> SQL table names (`tools`, `tool_data`, `tool_shares`) and a few legacy
> in-iframe globals (`toolFetch`, `toolData`) are kept for back-compat — see
> the relevant sections below.

## CRITICAL: What Extensions Are (and Are Not)

An Extension is a **self-contained Alpine.js HTML snippet** stored in the
SQL `tools` table (table name kept for back-compat; the Drizzle export is
`extensions`). It runs inside a sandboxed iframe with its own Tailwind CSS
and Alpine.js runtime.

**Extensions are NOT:**

- React components
- New source code files
- Database schema changes
- Action files in `actions/`
- Routes

**When a user asks to "make an extension", "create an extension", or "build
a ... extension" (or the older phrasings "make a tool" / "create a tool"):**

1. Write the Alpine.js HTML
2. Call `create-extension` with the HTML as `content`
3. That's it — no files to create, no schema changes, no actions

Extensions have full access to app data via helpers injected into the iframe:

- `appAction(name, params)` — call any app action
- `appFetch(path, options)` — call allowed framework endpoints under
  `/_agent-native/*`
- `dbQuery(sql, args)` — read from SQL
- `dbExec(sql, args)` — write to SQL
- `extensionFetch(url, options)` — call external APIs via proxy. Legacy
  alias: `toolFetch` — kept for back-compat with extension bodies authored
  before the rename; both names refer to the same helper.
- `extensionData.set/list/get/remove(collection, ...)` — persist custom data
  per-extension (supports `{ scope: 'user' | 'org' | 'all' }` option). Legacy
  alias: `toolData` — kept for back-compat; both names refer to the same
  store.

## Data Persistence is Built In

**Every extension has `extensionData` — a per-extension key-value store. NO
source code changes, NO Builder, NO new tables needed.**

When a user asks to "add persistence", "save data", "remember state", or
"store settings" in an extension, use `extensionData`. It handles table
creation, scoping, and upserts automatically. Data is organized into
collections per-extension:

```javascript
// Save a private item (default — only the current user can see it)
await extensionData.set('notes', 'note-1', { title: 'My Note', body: 'Hello' });

// Save an org-shared item (visible to everyone in the org)
await extensionData.set('notes', 'note-1', { title: 'Team Note', body: 'Hello' }, { scope: 'org' });

// List items by scope
const myNotes = await extensionData.list('notes');                        // user-scoped (default)
const orgNotes = await extensionData.list('notes', { scope: 'org' });    // org-scoped only
const allNotes = await extensionData.list('notes', { scope: 'all' });    // both user + org

// Get one item
const note = await extensionData.get('notes', 'note-1');                         // user-scoped
const orgNote = await extensionData.get('notes', 'note-1', { scope: 'org' });   // org-scoped

// Delete an item
await extensionData.remove('notes', 'note-1');                                   // user-scoped
await extensionData.remove('notes', 'note-1', { scope: 'org' });                // org-scoped
```

> The legacy global `toolData` is still injected and points at the same
> store — older extension bodies that reference `toolData.set(...)` continue
> to work without changes. Prefer `extensionData` in new code.

**Prefer `extensionData` over raw `dbExec` for extension-specific
persistence** — it handles everything automatically. Only use
`dbQuery`/`dbExec` when querying the app's existing tables.

## What extensions are

Extensions are mini Alpine.js apps that run inside sandboxed iframes. They
can call external APIs via `extensionFetch()`, which routes through a
server-side proxy that injects secret values. Extensions share the main
app's Tailwind v4 theme automatically.

## Creating an extension

Call the `create-extension` action:

```bash
pnpm action create-extension \
  --name "GitHub PR Dashboard" \
  --description "Shows open PRs for the repo" \
  --content '<div x-data="{ prs: [], loading: true }" x-init="extensionFetch('"'"'https://api.github.com/repos/OWNER/REPO/pulls'"'"', { headers: { '"'"'Authorization'"'"': '"'"'Bearer ${keys.GITHUB_TOKEN}'"'"' }}).then(r => r.json()).then(d => { prs = d; loading = false })"><template x-if="loading"><p>Loading...</p></template><div class="space-y-2"><template x-for="pr in prs" :key="pr.id"><a :href="pr.html_url" target="_blank" class="block rounded-lg border p-3 hover:bg-accent"><p class="font-medium" x-text="pr.title"></p><p class="text-sm text-muted-foreground" x-text="'"'"'#'"'"' + pr.number + '"'"' by '"'"' + pr.user.login"></p></a></template></div></div>'
```

Or via the HTTP API:

```
POST /_agent-native/extensions
{ "name": "GitHub PR Dashboard", "description": "Shows open PRs", "content": "<div ...>...</div>" }
```

The action accepts:

| Field         | Type     | Required | Purpose                       |
| ------------- | -------- | -------- | ----------------------------- |
| `name`        | `string` | yes      | Display name of the extension |
| `description` | `string` | no       | Short summary                 |
| `content`     | `string` | yes      | Alpine.js HTML body           |

## Editing an extension

Use the `update-extension` action. Prefer granular `edits` for surgical
changes instead of regenerating the full HTML. For medium/large extensions,
add stable section comments around major blocks so future agents can target
them without touching unrelated indentation:

```html
<!-- agent-native:section npm-daily-chart -->
<section>...</section>
<!-- /agent-native:section npm-daily-chart -->
```

Then update just that section:

```json
{
  "id": "EXTENSION_ID",
  "edits": "[{\"op\":\"replace-section\",\"section\":\"npm-daily-chart\",\"content\":\"<section>...</section>\"}]",
  "format": true
}
```

Supported `edits` operations:

| Operation         | Use for                                      |
| ----------------- | -------------------------------------------- |
| `replace`         | Literal find/replace; defaults to one match  |
| `insert-before`   | Insert content before an exact marker        |
| `insert-after`    | Insert content after an exact marker         |
| `replace-between` | Replace content between two exact markers    |
| `replace-section` | Replace a named comment section              |
| `wrap-section`    | Add a wrapper around a named section         |
| `remove-section`  | Remove a named section                       |
| `regex-replace`   | Carefully scoped regex replacement           |

Use `expectedMatches` when ambiguity would be dangerous. Missing required
targets fail instead of silently doing nothing. Pass `format: true` to run
Prettier on the final HTML after the patch. Full `content` replacement is
still available for broad rewrites.

Legacy `patches` still work for simple literal replacements:

```
PUT /_agent-native/extensions/:id
{
  "patches": [
    { "find": "old HTML fragment", "replace": "new HTML fragment" }
  ]
}
```

Each patch does a string find-and-replace on the current content. Use this
to change a single element, fix a URL, or update a class without rewriting
everything.

To replace the full content instead:

```
PUT /_agent-native/extensions/:id
{ "content": "full new HTML" }
```

## Alpine.js patterns

Extension HTML uses Alpine.js directives for reactivity. No build step, no
imports.

| Directive       | Purpose                       | Example                                    |
| --------------- | ----------------------------- | ------------------------------------------ |
| `x-data`        | Reactive state object         | `x-data="{ count: 0, items: [] }"`        |
| `x-init`        | Run on mount (fetch data)     | `x-init="fetchData()"`                     |
| `x-show`        | Toggle visibility             | `x-show="isOpen"`                          |
| `x-if`          | Conditional render (template) | `<template x-if="loaded">...</template>`   |
| `x-for`         | Loop                          | `<template x-for="item in items">...</template>` |
| `x-text`        | Set text content              | `x-text="item.name"`                       |
| `x-html`        | Set inner HTML                | `x-html="item.richContent"`                |
| `x-on:click`    | Event handler                 | `x-on:click="count++"`                     |
| `x-model`       | Two-way binding               | `x-model="searchQuery"`                    |
| `x-bind:class`  | Dynamic classes               | `x-bind:class="{ 'font-bold': active }"`   |

Always wrap `x-if` and `x-for` in a `<template>` tag.

## Component shape: inline `x-data` vs. `Alpine.data()`

For trivial components (a couple of state fields, no methods, no string
templating) inline `x-data="{ count: 0, items: [] }"` is fine. **For anything
beyond that — multiple methods, string formatting, classification logic,
async fetches with branching — put the component in a `<script>` block and
register it with `Alpine.data()`.** The inline form is a string inside an
HTML attribute; the longer it gets the more fragile it becomes (one stray
quote, one closing-tag-shaped substring, one template literal and the
attribute terminates early — Alpine then evaluates a half-parsed expression
and throws `ReferenceError: <var> is not defined`).

**Use this pattern for any non-trivial extension:**

```html
<div x-data="customerAnalyzer" class="p-4">
  <button @click="analyze()" class="rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground cursor-pointer">
    Analyze
  </button>
  <template x-if="error"><p class="text-red-500" x-text="error"></p></template>
  <template x-if="results">
    <div class="space-y-2">
      <div class="rounded-lg border p-3">
        <p class="font-medium">Action — Builder Side</p>
        <p class="text-sm text-muted-foreground" x-text="results.builderActions.length + ' items'"></p>
      </div>
      <!-- ...other buckets... -->
    </div>
  </template>
</div>

<script>
  document.addEventListener('alpine:init', () => {
    Alpine.data('customerAnalyzer', () => ({
      loading: false,
      error: '',
      results: null,
      async analyze() {
        this.loading = true;
        this.error = '';
        try {
          const { emails } = await appAction('list-emails', { view: 'inbox', limit: 50 });
          // ...categorize into 3 buckets...
          this.results = {
            builderActions: emails.filter((e) => /* ... */),
            waitingOnCustomer: emails.filter((e) => /* ... */),
            fyi: emails.filter((e) => /* ... */),
          };
        } catch (e) {
          this.error = e?.message || 'Analysis failed';
        } finally {
          this.loading = false;
        }
      },
    }));
  });
</script>
```

**Hard rules for `x-data` / `x-*` attributes:**

- Never put template literals (backticks) inside an HTML attribute. Use
  string concatenation or pre-format in the script block. Backticks can
  trip the HTML parser and the resulting string isn't a JS template literal
  anyway — the attribute is read as plain text.
- Never put a multi-method object literal inline. Move methods into
  `Alpine.data()`.
- In the `<script>` block, write normal JS — template literals, async/await,
  optional chaining all work.
- One source of truth for state: define every variable referenced from any
  `x-text`, `x-show`, `x-if`, `x-for`, `:class`, etc. on the `Alpine.data()`
  object's initial state. If `x-text="results.foo"` references `results`,
  `results` must be a property of the data object — null is a fine initial
  value as long as you guard with `<template x-if="results">`.
- When showing an error, render `error.message`-style text, never a raw
  boolean. `x-text="error"` is correct only when `error` is a string;
  if it's `true` the user sees the literal word "true".

## AI / LLM features in extensions

Extensions can do AI work two ways. Pick deliberately — silent fallbacks
end up rendering nonsense like the literal text `true`.

1. **Delegate to the agent chat.** If the user says "analyze my emails",
   "summarize this", "categorize these tickets" and there is no API key
   already configured for the relevant provider, prefer doing the work in
   the agent chat instead of inside the extension. The extension can have
   a button that calls `parent.postMessage({ type: 'agent-native-send-to-chat', message: '...' })`,
   or you can just answer in chat and skip the extension. Don't ship an
   extension with a stubbed AI step that returns a placeholder — that's
   how you end up rendering `true` in red.
2. **Call an LLM directly via `extensionFetch`.** Requires a real key the
   user has set up. Reference it via `${keys.OPENAI_API_KEY}` /
   `${keys.ANTHROPIC_API_KEY}` and surface a clear error if the proxy
   reports the key isn't configured. Tell the user where to add the key
   (Settings → Secrets) before the extension can work.

If you're not sure a key is configured, ask the user before generating an
extension whose primary value is the AI step.

## Accessing app data

Extensions can call the host app's actions and API endpoints directly. The
iframe shares the session cookie, so authentication is automatic.

### `appAction(name, params)` — Call app actions

Call any action defined in the app's `actions/` directory. Actions are
auto-mounted at `/_agent-native/actions/:name`.

```html
<div x-data="{ emails: [], loading: true }" x-init="
  appAction('list-emails', { view: 'inbox', limit: 10 })
    .then(d => { emails = d.emails || d; loading = false })
    .catch(e => { console.error(e); loading = false })
">
  <h2 class='text-lg font-semibold mb-4'>My Inbox</h2>
  <template x-for='email in emails' :key='email.id'>
    <div class='rounded-lg border p-3 mb-2'>
      <p class='font-medium text-sm' x-text='email.subject'></p>
      <p class='text-xs text-muted-foreground' x-text='email.from?.name || email.from?.email'></p>
    </div>
  </template>
</div>
```

### `appFetch(path, options)` — Call allowed framework endpoints

General-purpose fetch to allowed framework endpoints (for example,
`/_agent-native/application-state/navigation`). Automatically adds credentials
and JSON content type. Template `/api/*` routes are intentionally blocked by
the extension bridge; use `appAction(name, params)` for app data instead.

```javascript
// Read application state
const nav = await appFetch('/_agent-native/application-state/navigation');

// Call a framework route
const nav = await appFetch('/_agent-native/application-state/navigation');
```

### `dbQuery(sql)` — Read from the app's database

Run a read-only SELECT query against the app's SQL database. Results are
auto-scoped to the current user/org.

```html
<div x-data="{ rows: [] }" x-init="
  dbQuery('SELECT id, name FROM tools ORDER BY created_at DESC LIMIT 10')
    .then(d => rows = d.rows || d)
">
  <template x-for="row in rows" :key="row.id">
    <div class="border-b p-2 text-sm" x-text="row.name"></div>
  </template>
</div>
```

> The physical SQL table is still named `tools` (and `tool_data`,
> `tool_shares`) for back-compat. The Drizzle exports are `extensions`,
> `extensionData`, and `extensionShares` — use those when you query via the
> ORM. When writing raw SQL inside an extension (as above), use the
> physical names.

### `dbExec(sql)` — Write to the app's database

Run an INSERT, UPDATE, or DELETE statement. Writes are auto-scoped to the
current user/org, and `owner_email` / `org_id` are auto-injected on INSERT.

```javascript
// Insert a new record
await dbExec("INSERT INTO notes (id, title, body) VALUES ('abc', 'My Note', 'Hello world')");

// Update an existing record
await dbExec("UPDATE notes SET title = 'Updated Title' WHERE id = 'abc'");
```

### All helpers summary

| Helper | Use for | Example |
|--------|---------|---------|
| `appAction(name, params)` | Call app actions (CRUD, queries) | `appAction('list-emails', { view: 'inbox' })` |
| `appFetch(path, options)` | Call allowed framework endpoints | `appFetch('/_agent-native/application-state/navigation')` |
| `dbQuery(sql)` | Read from the app's SQL database | `dbQuery('SELECT * FROM notes LIMIT 10')` |
| `dbExec(sql)` | Write to the app's SQL database | `dbExec("INSERT INTO notes ...")` |
| `extensionFetch(url, options)` | Call external APIs via proxy (alias `toolFetch`) | `extensionFetch('https://api.github.com/user', { headers: { 'Authorization': 'Bearer ${keys.GITHUB_TOKEN}' } })` |
| `extensionData.set(collection, id, data, opts?)` | Save an item to extension storage (alias `toolData.set`) | `extensionData.set('todos', 'todo-1', { title: 'Buy milk' })` |
| `extensionData.list(collection, opts?)` | List items in a collection | `extensionData.list('todos', { scope: 'all' })` |
| `extensionData.get(collection, id, opts?)` | Get a single item by id | `extensionData.get('todos', 'todo-1')` |
| `extensionData.remove(collection, id, opts?)` | Delete an item | `extensionData.remove('todos', 'todo-1')` |

## Persisting Custom Data

Extensions have a built-in key-value store via `extensionData` (legacy alias:
`toolData`). Each extension gets its own isolated storage, organized into
collections. Every method accepts an optional `{ scope }` option:

- `'user'` (default) — private to the current user
- `'org'` — visible to everyone in the user's org
- `'all'` (list/get only) — returns both user and org items

```javascript
// Save a private item (default scope: 'user')
await extensionData.set('todos', 'todo-1', { title: 'Buy milk', done: false });

// Save an org-shared item
await extensionData.set('todos', 'team-todo-1', { title: 'Ship v2', done: false }, { scope: 'org' });

// List user items (default)
const myTodos = await extensionData.list('todos');

// List org items
const orgTodos = await extensionData.list('todos', { scope: 'org' });

// List both user + org items
const allTodos = await extensionData.list('todos', { scope: 'all' });
// Returns: [{ id, toolId, collection, data (JSON string), ownerEmail, scope, orgId, createdAt, updatedAt }]
// (the row column is still named `toolId` for back-compat — it's the extension id)

// Parse the JSON data
const parsed = allTodos.map(t => ({ ...JSON.parse(t.data), id: t.id, scope: t.scope }));

// Get/delete with scope
const item = await extensionData.get('todos', 'team-todo-1', { scope: 'org' });
await extensionData.remove('todos', 'team-todo-1', { scope: 'org' });
```

Data is scoped per-extension. User-scoped items are private per-user;
org-scoped items are shared across the org. Any org member can read,
update, or delete org-scoped items. **Prefer `extensionData` over raw
`dbExec` for extension-specific persistence** — it handles table creation,
scoping, and upserts automatically.

## Using `extensionFetch()` for API calls

`extensionFetch()` (legacy alias `toolFetch()`) is a drop-in replacement for
`fetch()` that proxies requests through the server. The server injects
secret values before the request leaves.

```javascript
// Basic GET
const res = await extensionFetch('https://api.example.com/data');
const data = await res.json();

// With secret injection
const res = await extensionFetch('https://api.openai.com/v1/models', {
  headers: {
    'Authorization': 'Bearer ${keys.OPENAI_API_KEY}'
  }
});

// POST with body
const res = await extensionFetch('https://api.example.com/items', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'New Item' })
});
```

**Important:** Use single quotes around strings containing `${keys.NAME}`
to prevent JavaScript template literal evaluation. The substitution
happens server-side, not in the browser.

## Tailwind classes

Extensions inherit the main app's Tailwind v4 theme. Use the same utility
classes:

- **Colors:** `bg-background`, `text-foreground`, `bg-primary`, `text-primary-foreground`, `text-muted-foreground`, `border-border`, `bg-accent`, `bg-destructive`
- **Layout:** `flex`, `grid`, `space-y-2`, `gap-4`, `p-4`, `m-2`
- **Typography:** `text-sm`, `text-lg`, `font-medium`, `font-bold`
- **Borders:** `border`, `rounded-lg`, `rounded-md`, `rounded-sm`
- **Dark mode:** automatic via `.dark` class on the html element

## Managing secrets

Extensions reference secrets via `${keys.NAME}` inside `extensionFetch()`
calls. Create secrets via:

```
POST /_agent-native/secrets/adhoc
{ "name": "GITHUB_TOKEN", "value": "ghp_xxxx", "description": "GitHub PAT", "urlAllowlist": ["https://api.github.com"] }
```

Or the user can add them in the settings UI. If an extension needs an API
key that isn't configured yet, tell the user what key is needed and where
to get it.

See the `secrets` skill for the full secrets API.

## Sharing

Use the framework sharing actions:

```bash
# Make an extension visible to the org
pnpm action set-resource-visibility --resourceType=tool --resourceId=EXTENSION_ID --visibility=org

# Share with a specific user
pnpm action share-resource --resourceType=tool --resourceId=EXTENSION_ID --principalType=user --principalId=user@example.com --role=editor

# List current shares
pnpm action list-resource-shares --resourceType=tool --resourceId=EXTENSION_ID
```

> The `resourceType` value is still `tool` for back-compat with the
> `tool_shares` table. The variable name `EXTENSION_ID` is the canonical
> name for the value going into the call.

See the `sharing` skill for visibility levels and roles.

## Navigation

```bash
# Navigate to the extensions list
pnpm action navigate --view=extensions

# Navigate to a specific extension
pnpm action navigate --view=extensions --extensionId=EXTENSION_ID

# Or directly:
set-url-path({ "pathname": "/extensions/EXTENSION_ID" })
```

## Example extensions

### API Status Dashboard

Checks the health of multiple endpoints and shows green/red status:

```html
<div class="p-6" x-data="{
  endpoints: [
    { name: 'API', url: 'https://api.example.com/health' },
    { name: 'Auth', url: 'https://auth.example.com/health' },
    { name: 'CDN', url: 'https://cdn.example.com/health' }
  ],
  results: [],
  loading: true
}" x-init="
  Promise.all(endpoints.map(ep =>
    extensionFetch(ep.url).then(r => ({ ...ep, ok: r.ok })).catch(() => ({ ...ep, ok: false }))
  )).then(r => { results = r; loading = false })
">
  <h2 class="text-lg font-bold mb-4">Service Status</h2>
  <template x-if="loading"><p class="text-muted-foreground">Checking...</p></template>
  <div class="space-y-2">
    <template x-for="r in results" :key="r.name">
      <div class="flex items-center justify-between rounded-lg border p-3">
        <span class="font-medium" x-text="r.name"></span>
        <span x-bind:class="r.ok ? 'text-green-600' : 'text-red-600'" x-text="r.ok ? 'Healthy' : 'Down'"></span>
      </div>
    </template>
  </div>
</div>
```

### Weather Widget

Fetches current weather for a city:

```html
<div class="p-6" x-data="{ city: 'San Francisco', weather: null, loading: false }" x-init="
  loading = true;
  extensionFetch('https://api.weatherapi.com/v1/current.json?q=' + encodeURIComponent(city) + '&key=${keys.WEATHER_API_KEY}')
    .then(r => r.json()).then(d => { weather = d; loading = false })
">
  <div class="space-y-4">
    <div class="flex gap-2">
      <input type="text" x-model="city" class="flex-1 rounded-md border bg-background px-3 py-2 text-sm" placeholder="City name" />
      <button x-on:click="loading = true; extensionFetch('https://api.weatherapi.com/v1/current.json?q=' + encodeURIComponent(city) + '&key=${keys.WEATHER_API_KEY}').then(r => r.json()).then(d => { weather = d; loading = false })" class="rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground cursor-pointer">Search</button>
    </div>
    <template x-if="loading"><p class="text-muted-foreground">Loading...</p></template>
    <template x-if="weather && !loading">
      <div class="rounded-lg border p-4">
        <p class="text-2xl font-bold" x-text="weather.current.temp_f + '°F'"></p>
        <p class="text-muted-foreground" x-text="weather.current.condition.text"></p>
        <p class="text-sm text-muted-foreground" x-text="weather.location.name + ', ' + weather.location.region"></p>
      </div>
    </template>
  </div>
</div>
```

### Todo List (using extensionData)

Full CRUD app using the built-in `extensionData` store — no SQL, no schema
files, no actions. Data is automatically scoped per-extension and per-user:

```html
<div class="p-6" x-data="{
  todos: [],
  newTodo: '',
  loading: true,
  async init() {
    const items = await extensionData.list('todos');
    this.todos = items.map(i => ({ id: i.id, ...JSON.parse(i.data) }));
    this.loading = false;
  },
  async addTodo() {
    if (!this.newTodo.trim()) return;
    const id = crypto.randomUUID();
    const data = { title: this.newTodo.trim(), completed: false };
    await extensionData.set('todos', id, data);
    this.todos.unshift({ id, ...data });
    this.newTodo = '';
  },
  async toggle(todo) {
    todo.completed = !todo.completed;
    await extensionData.set('todos', todo.id, { title: todo.title, completed: todo.completed });
  },
  async remove(id) {
    await extensionData.remove('todos', id);
    this.todos = this.todos.filter(t => t.id !== id);
  }
}">
  <h2 class="text-lg font-semibold mb-4">Todo List</h2>
  <div class="flex gap-2 mb-4">
    <input x-model="newTodo" type="text" placeholder="What needs to be done?"
      class="flex-1 rounded-md border border-input bg-background px-3 py-2 text-sm"
      @keydown.enter="addTodo()">
    <button @click="addTodo()"
      class="rounded-md bg-primary px-4 py-2 text-sm text-primary-foreground cursor-pointer hover:bg-primary/90">
      Add
    </button>
  </div>
  <div x-show="loading" class="text-sm text-muted-foreground">Loading...</div>
  <div class="space-y-2">
    <template x-for="todo in todos" :key="todo.id">
      <div class="flex items-center gap-3 rounded-md border p-3">
        <button @click="toggle(todo)" class="cursor-pointer"
          :class="todo.completed ? 'text-green-500' : 'text-muted-foreground'">
          <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
            <template x-if="todo.completed"><path d="M22 11.08V12a10 10 0 1 1-5.93-9.14M22 4 12 14.01l-3-3"/></template>
            <template x-if="!todo.completed"><circle cx="12" cy="12" r="10"/></template>
          </svg>
        </button>
        <span class="flex-1 text-sm" :class="todo.completed && 'line-through text-muted-foreground'" x-text="todo.title"></span>
        <button @click="remove(todo.id)" class="text-muted-foreground hover:text-destructive cursor-pointer text-xs">Remove</button>
      </div>
    </template>
  </div>
  <p x-show="!loading && todos.length === 0" class="text-sm text-muted-foreground text-center py-8">No todos yet. Add one above!</p>
</div>
```

### Quick Notes

Persistent notes using localStorage -- no API key needed:

```html
<div class="p-6" x-data="{
  notes: JSON.parse(localStorage.getItem('quick-notes') || '[]'),
  draft: '',
  save() {
    if (!this.draft.trim()) return;
    this.notes.unshift({ id: Date.now(), text: this.draft, date: new Date().toLocaleDateString() });
    this.draft = '';
    localStorage.setItem('quick-notes', JSON.stringify(this.notes));
  },
  remove(id) {
    this.notes = this.notes.filter(n => n.id !== id);
    localStorage.setItem('quick-notes', JSON.stringify(this.notes));
  }
}">
  <div class="space-y-4">
    <div class="flex gap-2">
      <input type="text" x-model="draft" x-on:keydown.enter="save()" class="flex-1 rounded-md border bg-background px-3 py-2 text-sm" placeholder="Add a note..." />
      <button x-on:click="save()" class="rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground cursor-pointer">Add</button>
    </div>
    <div class="space-y-2">
      <template x-for="note in notes" :key="note.id">
        <div class="flex items-start justify-between rounded-lg border p-3">
          <div>
            <p class="text-sm" x-text="note.text"></p>
            <p class="text-xs text-muted-foreground" x-text="note.date"></p>
          </div>
          <button x-on:click="remove(note.id)" class="text-muted-foreground hover:text-destructive text-sm cursor-pointer">Remove</button>
        </div>
      </template>
      <template x-if="notes.length === 0">
        <p class="text-sm text-muted-foreground">No notes yet.</p>
      </template>
    </div>
  </div>
</div>
```

## Guidelines

- **Rely on the default canvas padding.** The iframe shell adds modest body padding so simple extensions do not hug the edge. Do not add outer `p-4` / `p-6` unless the design needs extra breathing room. For full-bleed extensions such as maps, canvases, or custom editors, put `data-tool-layout="full-bleed"` or `data-tool-padding="none"` on the outermost element. (The `data-tool-*` attribute names are kept for back-compat with the iframe runtime.)
- **Use semantic Tailwind colors for native theming.** Always use `bg-background`, `text-foreground`, `bg-primary`, `text-primary-foreground`, `border-border`, `bg-muted`, `text-muted-foreground`, etc. The extension inherits the parent app's exact theme variables, so it will look fully native in both light and dark modes.
- **Keep extensions focused.** One extension, one job. A "GitHub PR Dashboard" should show PRs, not also manage issues.
- **Handle loading and error states.** Always show a loading indicator during fetch and handle failures gracefully.
- **All functions referenced in Alpine expressions must be defined in `x-data`.** If you use `@click="add()"`, there must be an `add()` method in the component's `x-data` object. Undefined references cause runtime errors.
- **For non-trivial components, use a `<script>` + `Alpine.data('name', () => ({...}))` block and reference it with `x-data="name"`.** Inline `x-data="{ ...big object... }"` is brittle: stuffing many methods, branching logic, or any backtick template literal into an HTML attribute leads to half-parsed expressions and `ReferenceError` failures. See the "Component shape" section above.
- **Don't ship a stubbed AI step.** If the extension's value is "AI analysis" and no LLM key is configured, either route the work to the agent chat or tell the user which key to add — never render a placeholder/boolean as the result.
- **Use the right fetch helper.** `appAction()` for app actions and app data, `appFetch()` for allowed framework `/_agent-native/*` endpoints, and `extensionFetch()` for external APIs. Never call template `/api/*` routes from an extension and never use raw `fetch()` -- secrets won't be injected and CORS will block external APIs.
- **Single quotes around `${keys.*}`** to prevent browser-side template literal evaluation.
- **Prefer patches over full rewrites** when editing existing extensions. Smaller diffs are less error-prone.

## Routes

| Method | Path                                   | Purpose                                       |
| ------ | -------------------------------------- | --------------------------------------------- |
| GET    | `/_agent-native/extensions`            | List extensions (filtered by ownership/share) |
| POST   | `/_agent-native/extensions`            | Create an extension                           |
| GET    | `/_agent-native/extensions/:id`        | Get an 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 HTML for iframe                        |
| POST   | `/_agent-native/extensions/proxy`      | Authenticated proxy with secret injection     |

## Database & API names — back-compat reference

The rename from "tools" to "extensions" is mostly user-facing. Several
under-the-hood names are kept to avoid breaking existing data and code:

| Surface                              | Stays as              | Rationale                                              |
| ------------------------------------ | --------------------- | ------------------------------------------------------ |
| SQL table for extensions             | `tools`               | Renaming a table = drop+create; data must not move     |
| SQL table for per-ext data           | `tool_data`           | Same                                                   |
| SQL table for ext shares             | `tool_shares`         | Same                                                   |
| Drizzle schema export                | `extensions`          | Code-side rename — no data migration needed            |
| Drizzle schema export                | `extensionData`       | Same                                                   |
| Drizzle schema export                | `extensionShares`     | Same                                                   |
| Iframe global (legacy alias)         | `toolFetch`           | Kept so older extension bodies keep working            |
| Iframe global (legacy alias)         | `toolData`            | Same                                                   |
| Iframe global (canonical)            | `extensionFetch`      | Use this in new extensions                             |
| Iframe global (canonical)            | `extensionData`       | Same                                                   |
| `data-tool-layout` HTML attribute    | unchanged             | Runtime contract; not worth churning                   |
| `resourceType` for sharing           | `tool`                | Matches `tool_shares` table                            |
| Slot-system table                    | `tool_slots`          | Drizzle export is `extensionSlots` (see `extension-points`) |
| Slot-installs table                  | `tool_slot_installs`  | Drizzle export is `extensionSlotInstalls`              |

## Related skills

- `extension-points` -- how an extension renders as a widget inside another app via named UI slots.
- `secrets` -- creating and managing API keys for `${keys.NAME}` substitution.
- `sharing` -- visibility and access control for extensions.
- `actions` -- the `create-extension` and `update-extension` actions that back extension CRUD.
- `frontend-design` -- design guidance when styling extension HTML.