@agent-native/core 0.39.0 → 0.39.2

package/dist/templates/default/.agents/skills/storing-data/SKILL.md

@@ -1,128 +1,161 @@
 ---
 name: storing-data
 description: >-
-  How and where to store application data. Use when adding new data models,
-  deciding between settings vs Drizzle tables, reading/writing app config,
-  or working with application state.
+  How to store application data in agent-native apps. All data lives in SQL.
+  Use when adding data models, deciding where to store data, or reading/writing
+  application data.
+metadata:
+  internal: true
 ---
 
-# Storing Data
+# Storing Data — SQL is the Source of Truth
 
-## Where Data Goes
+## Rule
 
-All data lives in one SQLite database (`data/app.db`). In production, set `DATABASE_URL` to point to Turso, Neon, Supabase, or D1 — same code, no changes needed.
+All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. Do not store durable app data in the filesystem.
 
-There are three storage layers, each for a different kind of data:
+## How It Works
 
-### 1. Settings — app configuration
+Agent-native apps use Drizzle ORM over the configured SQL backend. Local development works out of the box with a SQLite file at `data/app.db`; production and shared preview deploys need a persistent `DATABASE_URL` because container/serverless filesystems can reset. The code should behave the same across backends, but the local SQLite file is not durable once deployed.
 
-Key-value store for persistent non-secret config that the user or agent can change. Theme, preferences, integration settings, availability schedules.
+For app code, use Drizzle's schema/query DSL by default. Raw SQL is an escape hatch for additive migrations, health checks, or one-off maintenance, not the normal way to build features.
 
-```ts
-import { getSetting, putSetting } from "@agent-native/core/settings";
+### Core SQL Stores (auto-created, available in all templates)
 
-// Read (returns null if not set)
-const prefs = await getSetting("user-preferences");
+| Store               | Purpose                                              | Access                                     |
+| ------------------- | ---------------------------------------------------- | ------------------------------------------ |
+| `application_state` | Ephemeral UI state (compose windows, navigation)     | `readAppState()` / `writeAppState()`       |
+| `settings`          | Persistent KV config (preferences, app settings)     | `getSetting()` / `putSetting()`            |
+| `oauth_tokens`      | OAuth credentials                                    | `@agent-native/core/oauth-tokens`          |
+| `sessions`          | Auth sessions                                        | `@agent-native/core/server`               |
 
-// Write (creates or replaces)
-await putSetting("user-preferences", { theme: "dark", density: "comfortable" });
-```
+### Domain Data (per-template)
+
+Define schema with the framework Drizzle helpers in `server/db/schema.ts`. Get a database instance with `const db = getDb()` from `server/db/index.ts`. All queries are async.
 
-From scripts:
 ```ts
-import { readSetting, writeSetting } from "@agent-native/core/settings";
-const prefs = await readSetting("user-preferences");
-```
+import { eq } from "drizzle-orm";
+import { table, text, integer, now } from "@agent-native/core/db/schema";
+
+export const tasks = table("tasks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  completed: integer("completed", { mode: "boolean" })
+    .notNull()
+    .default(false),
+  createdAt: text("created_at").notNull().default(now()),
+});
 
-SSE: writes automatically notify the UI via `{ source: "settings", type: "change", key }`.
+const rows = await db.select().from(tasks).where(eq(tasks.id, taskId));
+```
 
-### 2. Application State — ephemeral UI state
+Never import `sqliteTable` / `pgTable` or column helpers from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates. Use `@agent-native/core/db/schema` so the same schema can run against SQLite, Postgres, libSQL/Turso, D1, and other supported backends.
 
-For state the agent and UI share in real-time: what the user is looking at, compose drafts, navigation commands. Scoped by session — cleared between sessions.
+| Template     | Tables                                        |
+| ------------ | --------------------------------------------- |
+| **Mail**     | emails, labels (+ Gmail API when connected)   |
+| **Calendar** | events, bookings                              |
+| **Forms**    | forms, responses                              |
+| **Content**  | documents                                     |
+| **Slides**   | decks (JSON stored in SQL)                    |
+| **Videos**   | compositions in registry + localStorage       |
 
-```ts
-import { readAppState, writeAppState, deleteAppState, listAppState } from "@agent-native/core/application-state";
+### Agent Access
 
-// Write state (UI updates instantly via SSE)
-await writeAppState("navigate", { view: "inbox", threadId: "t-123" });
+The agent uses app-specific actions to read/write the database. Core DB scripts are for inspection and maintenance, not for implementing normal product behavior:
 
-// Read state
-const nav = await readAppState("navigation");
+- `pnpm action db-schema` — Show all tables, columns, types
+- `pnpm action db-query --sql "SELECT * FROM forms"` — Run SELECT queries
+- `pnpm action db-exec --sql "UPDATE ..."` — Last-resort ad-hoc maintenance for short columns, multi-column writes, or computed updates when no domain action exists. For several related writes, prefer `--statements '[{"sql":"...","args":[...]}]'` so they run sequentially in one transaction. Schema changes are blocked; use reviewed additive migrations/startup code instead.
+- `pnpm action db-patch --table <t> --column <c> --where "<clause>" --find "<old>" --replace "<new>"` — **Surgical search/replace on a large text column.** Sends the diff instead of re-transmitting the whole value, so it's dramatically more token-efficient than `db-exec UPDATE` when editing multi-kilobyte documents, slide HTML, dashboard/form JSON, etc. Targets exactly one row per call — narrow `--where` by primary key. Supports `--edits '[{find,replace},...]'` for batch edits and `--all` to replace every occurrence.
+- App-specific actions for domain operations — **always prefer these over raw SQL when one exists.** They encode business rules, power the client action hooks, and for editor-backed tables (documents, slides) also push live Yjs updates to open collaborative editors. `db-patch` is the generic fallback for tables without a dedicated edit action.
 
-// List by prefix (e.g., all compose drafts)
-const drafts = await listAppState("compose-");
+**For one-off maintenance, how to choose between `db-exec UPDATE` and `db-patch`:**
 
-// Delete (one-shot commands: UI reads, then agent or UI deletes)
-await deleteAppState("navigate");
-```
+| Scenario                                                       | Use          |
+| -------------------------------------------------------------- | ------------ |
+| `SET status = 'published'` on one row                          | `db-exec`    |
+| `SET calories = calories + 50`                                 | `db-exec`    |
+| Updating several columns at once                               | `db-exec`    |
+| Inserting/updating several rows as one logical operation        | `db-exec --statements` |
+| Fixing a typo in a 50KB markdown document's `content` column   | `db-patch`   |
+| Changing a single key in a dashboard's JSON blob               | `db-patch`   |
+| Tweaking one paragraph of slide HTML stored in `decks.data`    | `db-patch`   |
+| Any edit where you'd otherwise re-send thousands of characters | `db-patch`   |
 
-SSE: writes automatically notify the UI via `{ source: "app-state", type: "change", key }`.
+All of these honor the per-user / per-org data scoping — you can't read or write rows outside the current user's data, regardless of which tool you choose.
 
-### 3. Drizzle Tables — structured domain data
+### Frontend Access
 
-For data with schemas, relationships, and queries: forms, bookings, emails, compositions. Define tables in `server/db/schema.ts` using Drizzle ORM.
+The frontend calls actions using React Query hooks from the client API. The framework owns the HTTP transport behind these hooks, so components should not call action routes with raw `fetch`.
 
 ```ts
-import { table, text, integer } from "@agent-native/core/db/schema";
+import { useActionQuery, useActionMutation } from "@agent-native/core/client";
 
-export const bookings = table("bookings", {
-  id: text("id").primaryKey(),
-  name: text("name").notNull(),
-  email: text("email").notNull(),
-  startTime: integer("start_time").notNull(),
-  endTime: integer("end_time").notNull(),
-});
+// Read data
+const { data } = useActionQuery("list-meals", { date: "2025-01-01" });
+
+// Write data
+const { mutate } = useActionMutation("log-meal");
 ```
 
-Query via `getDb()` singleton from `server/db/index.ts`.
+Actions are the **preferred way** for the frontend to access data. You rarely need custom `/api/` routes — only for file uploads, streaming, webhooks, or OAuth callbacks.
 
-### 4. OAuth Tokens — credentials
+### Production / Cloud Deployment
 
-For OAuth tokens acquired at runtime (Google, etc.). Never store these in settings — use the dedicated store.
+Local SQLite works out of the box for development. To deploy to production or any environment where data must survive restarts:
 
-```ts
-import { saveOAuthTokens, getOAuthTokens, listOAuthAccounts } from "@agent-native/core/oauth-tokens";
+1. Set `DATABASE_URL` to a persistent SQL database.
+2. Set `DATABASE_AUTH_TOKEN` only when the provider requires a separate token, such as Turso/libSQL.
+3. No code changes should be needed when the schema and queries stay portable.
 
-await saveOAuthTokens("google", "user@gmail.com", { access_token: "...", refresh_token: "..." });
-const tokens = await getOAuthTokens("google", "user@gmail.com");
-const accounts = await listOAuthAccounts("google");
-```
+Turso is one valid option, not the required option. Common choices include Neon or Supabase Postgres, Turso/libSQL, plain Postgres, durable SQLite, Cloudflare D1 bindings, and managed platform SQL environments when available.
+
+### Real-time Sync
+
+Polling streams database changes to the UI. When the agent writes to the database via scripts, the UI updates automatically via `useDbSync()` which invalidates React Query caches.
+
+## Do
+
+- Use Drizzle ORM for structured domain data (forms, bookings, documents)
+- Use Drizzle query builder methods (`select`, `insert`, `update`, `delete`) and portable operators from `drizzle-orm` (`eq`, `and`, `or`, `inArray`, `desc`, etc.) for app reads/writes
+- Use framework schema helpers from `@agent-native/core/db/schema`, not dialect-specific Drizzle imports
+- Use the `settings` store for app configuration and user preferences
+- Use `application-state` for ephemeral UI state that the agent and UI share
+- Use `oauth-tokens` for OAuth credentials
+- Use core DB scripts (`db-schema`, `db-query`, `db-exec`, `db-patch`) for ad-hoc database operations
+- Use `db-exec --statements` instead of several separate `db-exec` calls for related writes; it is faster and rolls back the whole batch if one statement fails
+- Reach for `db-patch` instead of `db-exec UPDATE` whenever you're making a small change to a large text/JSON column — it's much cheaper on tokens
 
-### 5. Secrets / Credentials — encrypted values
+## Don't
 
-For API keys, service tokens, webhook secrets, and user/org/workspace
-credentials. Register user-facing secrets with the secrets registry and read
-them server-side with `readAppSecret`, or use `saveCredential` /
-`resolveCredential` for scoped credential lookup. Never store these values in
-settings, application state, source code, docs, examples, logs, or action
-responses.
+- Don't store structured app data as JSON files
+- Don't store app state in localStorage, sessionStorage, or cookies (except for UI-only preferences like sidebar width)
+- Don't keep state only in memory (server variables, global stores)
+- Don't use Redis or any external state store for app data
+- Don't implement product features with raw SQL or `getDbExec()` when Drizzle can express the query
+- Don't write SQLite-only or Postgres-only SQL in app code
+- Don't interpolate user input directly into SQL queries — use Drizzle ORM's query builder
 
-## Which Layer to Use
+## Security
 
-| Data | Layer | Why |
-|------|-------|-----|
-| User preferences, theme, config | Settings | Persistent KV, SSE notifications, simple read/write |
-| What the user sees on screen | Application State | Ephemeral, real-time sync, agent ↔ UI bridge |
-| Compose drafts, wizard steps | Application State | Temporary, deleted when done |
-| Domain records (forms, bookings) | Drizzle table | Needs schema, queries, relationships |
-| API keys, service tokens, webhook secrets | Secrets / credentials | Encrypted and scoped; never client-readable |
-| OAuth refresh tokens | OAuth Tokens | Secure, per-provider, per-account |
+- **SQL injection** — Use Drizzle ORM's query builder, never raw string interpolation for SQL queries
+- **Validate before writing** — Check data shape before writing, especially for user-submitted data
 
-## Environment Variables
+## Application State and Context Awareness
 
-Infrastructure config stays in `.env` — these differ per deployment:
+When storing app-state, include **navigation state** — the agent needs to know what the user is looking at. The `application_state` table holds ephemeral UI state that both the agent and UI share. Key patterns:
 
-- `DATABASE_URL` — database connection (default: `file:./data/app.db`)
-- `DATABASE_AUTH_TOKEN` — for remote databases
-- `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` — OAuth app credentials
-- `ACCESS_TOKEN` — production auth token
+- **`navigation` key** — the UI writes current view and selection on every route change. The agent reads this before acting.
+- **`navigate` key** — the agent writes one-shot commands to navigate the UI. The UI processes and deletes them.
+- **Domain-specific keys** (e.g., `compose-{id}`) — bidirectional state for features like email drafts.
 
-Everything else (user settings, app state, domain data) goes in SQL through the
-appropriate store. User/org/workspace credential values go in the encrypted
-secrets/credential stores, not plain settings rows.
+When adding a new data model or feature, also consider what navigation and selection state needs to be exposed via application-state. See the **context-awareness** skill for the full pattern.
 
-## Security Rules
+## Related Skills
 
-- **Never store API keys or secrets in Settings or Application State** — use the secrets registry / vault or `saveCredential` / `resolveCredential` for API keys and service tokens, deploy env vars only for deploy-level secrets, and `oauth_tokens` for OAuth credentials. Settings and application state are readable by the client.
-- **Every Drizzle table with user data must have `owner_email`** — the framework auto-scopes queries in production so users only see their own data. Run `pnpm action db-check-scoping` to verify. See the `security` skill for the full model.
-- **Never return secrets in action responses** — action responses may be visible in the agent chat or sent to the client. Keep credentials server-side only.
+- **context-awareness** — How to expose navigation and selection state via application-state
+- **real-time-sync** — Set up polling so the UI updates when the database changes
+- **actions** — Create actions with `defineAction` to query the database
+- **client-methods** — Keep route details behind named client helpers/hooks
+- **self-modifying-code** — The agent can also modify the app's source code

package/dist/templates/default/DEVELOPING.md

@@ -6,7 +6,7 @@ This guide is for development-mode agents editing this app's source code. For ap
 
 **Client-side-first rendering:** This app uses React Router v7 framework mode with `ssr: true`, but all app content renders **client-side only**. The server renders only the HTML shell (meta tags, styles, scripts) plus a loading spinner. This is enforced by the `ClientOnly` wrapper in `root.tsx` — never remove it. Browser APIs (`window`, `localStorage`, `new Date()`) are safe to use anywhere in app code because components never run on the server.
 
-**Do NOT fetch data server-side** in route loaders. The standard pattern is: server renders a spinner, client hydrates, React Query hooks fetch from `/api/*`.
+**Do NOT fetch data server-side** in route loaders unless the page genuinely needs SEO/OG content. The standard pattern is: SSR renders the shell, client hydrates, and React reads/writes normal app data through actions with `useActionQuery` / `useActionMutation`.
 
 ## Adding a Page
 
@@ -30,7 +30,7 @@ In a workspace, this app can be mounted under `/<app-id>`. React Router already
 | `app/routes/review.tsx` | `/review`          | `/<app-id>/review`  |
 | `app/routes/$id.tsx`    | `/:id`             | `/<app-id>/:id`     |
 
-Use `<Link to="/review">` and `navigate("/review")` inside this app. Do not prefix React Router paths with `/<app-id>` or the URL can double-prefix, e.g. `/<app-id>/<app-id>/review`. Use `appPath()` for raw `href`s/static assets, `appApiPath()` for `/api/*`, and `agentNativePath()` for `/_agent-native/*`.
+Use `<Link to="/review">` and `navigate("/review")` inside this app. Do not prefix React Router paths with `/<app-id>` or the URL can double-prefix, e.g. `/<app-id>/<app-id>/review`. Use `appPath()` for raw `href`s/static assets, `agentNativePath()` for `/_agent-native/*`, and `appApiPath()` only for legitimate route-only `/api/*` endpoints.
 
 Each route file exports a default component and optional `meta()`:
 
@@ -46,17 +46,15 @@ export default function MyPageRoute() {
 }
 ```
 
-## Adding an API Route
+## Adding App Data
 
-Create a file in `server/routes/api/`. The filename determines the URL path and HTTP method:
+Normal app data starts as an action, not a custom route. Add `actions/<verb>-<resource>.ts` with `defineAction`, mark reads with `http: { method: "GET" }`, and call reads/writes from React with `useActionQuery` / `useActionMutation` from `@agent-native/core/client`. This keeps the UI and agent on one contract and lets mutating actions refresh action-backed queries automatically.
 
-```
-server/routes/api/items/index.get.ts    → GET  /api/items
-server/routes/api/items/[id].get.ts     → GET  /api/items/:id
-server/routes/api/items/[id].patch.ts   → PATCH /api/items/:id
-```
+## Adding a Route-Only Endpoint
+
+Use `server/routes/api/` only for protocols that cannot be modeled as JSON actions: multipart uploads, streaming/SSE/WebSocket, webhooks, OAuth callbacks/redirects, public SEO/OG endpoints, or binary/static asset serving. Do not add `/api/*` routes for normal CRUD, data queries, or pass-through wrappers around actions; the action endpoint already exists at `/_agent-native/actions/:name`.
 
-Each file exports a default `defineEventHandler`.
+Each route-only endpoint still exports a default `defineEventHandler`, but keep shared app logic in actions or server libraries so agent and UI behavior do not fork.
 
 ## Server Plugins
 
@@ -84,10 +82,9 @@ export default defineNitroPlugin(async (nitroApp) => {
 | Agent chat context state helpers             | Optional advanced helpers for two-way sync with staged context chips       |
 | `agentChat`                                  | Send messages to agent from scripts (server-side)                          |
 
-## Adding a Script
+## Adding an Action
 
-Create `actions/my-script.ts` exporting `default async function(args: string[])`.
-Run with: `pnpm action my-script --arg value`
+Create `actions/<verb>-<resource>.ts` with `defineAction`. Run with `pnpm action <name> --id value`; React callers should use `useActionQuery` for GET actions and `useActionMutation` for mutating actions, not a matching `/api/*` wrapper.
 
 ## Sending to Agent Chat
 

package/dist/templates/workspace-core/.agents/skills/client-methods/references/legacy-client-fetch-audit-2026-06-03.md

@@ -7,6 +7,11 @@ contracts; some need new actions or helper modules first.
 
 ## Highest Priority
 
+- 2026-06-07 follow-up: the same high-priority route-first clusters are still
+  present. The biggest migrations remain Analytics, Calendar, Mail, Slides, and
+  Content. Do not copy these patterns into new work; when editing the relevant
+  area, add or reuse actions first, then call them with `useActionQuery`,
+  `useActionMutation`, or `callAction`.
 - `templates/analytics/app/pages/analyses/AnalysesList.tsx`,
   `templates/analytics/app/pages/analyses/AnalysisDetail.tsx`,
   `templates/analytics/app/components/layout/Sidebar.tsx`, and
@@ -43,6 +48,10 @@ contracts; some need new actions or helper modules first.
 - Content comments and versions are partially migrated. Add missing actions such
   as `resolve-comment`, `delete-comment`, `list-document-versions`, and
   `restore-document-version`.
+- Plans version history is the model to copy for new history/rollback work:
+  `list-plan-versions`, `get-plan-version`, and `restore-plan-version` are
+  action-native, and the UI calls them through action hooks. Do not copy
+  Content's legacy document-version `/api/*` helpers into new version panels.
 
 ## Acceptable Exceptions
 

package/dist/templates/workspace-core/.agents/skills/writing-agent-instructions/SKILL.md

@@ -74,6 +74,33 @@ Keep one canonical instructions file: `AGENTS.md`. If a client expects
 hand-maintained files drift, and the agent ends up with contradictory rules.
 One source of truth, linked where needed.
 
+## Keep generated guidance in sync
+
+Framework guidance is authored once in this repo and copied outward. Treat
+`.agents/skills/` as the canonical source for shared skills. Generated
+workspace skills in `packages/core/src/templates/workspace-core/.agents/skills/`
+and first-party template copies of shared skills must stay byte-for-byte in
+sync; run `pnpm sync:workspace-skills` after editing a shared skill, and
+`pnpm guard:workspace-skills` before calling the guidance done.
+
+Generated app and workspace instructions must teach the same action-first data
+contract:
+
+- Normal app data goes through `defineAction` files in `actions/`.
+- React calls actions with `useActionQuery`, `useActionMutation`, or
+  `callAction`; route paths are a transport detail hidden behind helpers.
+- Custom `/api/*` routes are only for route-shaped protocols such as uploads,
+  streaming, webhooks, OAuth callbacks, public SEO/OG endpoints, or binary
+  assets.
+- Do not create pass-through routes whose main job is to call, repackage, or
+  re-export an action.
+
+When documenting version history, restore, or audit trails, use actions for
+full restorable snapshots (`list-<resource>-versions`,
+`get-<resource>-version`, `restore-<resource>-version`). Do not copy legacy
+raw-route version panels, such as document-version `/api/*` helpers, into new
+features. The Plans version-history pattern is the preferred model.
+
 ## SKILL.md frontmatter must say what AND when
 
 The `description` is the only thing the agent sees when deciding whether to read

package/docs/content/template-plan.md

@@ -33,7 +33,10 @@ The command installs `/visual-plan` plus the companion commands:
 - `/ui-plan` for UI-first plans with mockups, states, and screen-level review.
 - `/prototype-plan` for clickable prototype-first plans with live comments.
 - `/visual-questions` for visual intake before a plan.
-- `/visualize-plan` for turning an existing text plan into a visual companion.
+
+Use `/visual-plan` for both fresh plans and existing Codex, Claude Code,
+Markdown, or pasted plans; when source plan text already exists, the agent builds
+from that plan instead of starting over.
 
 By default the CLI targets Codex. Add `--client claude-code` or `--client all`
 when you want to configure another host:
@@ -62,7 +65,6 @@ After installation, ask your agent for the command that fits the work:
 - `/prototype-plan` creates a clickable prototype above the plan document, with
   static mocks, comments, and a focused browser popout.
 - `/visual-questions` opens a visual intake questionnaire before planning.
-- `/visualize-plan` imports a plan you already have and makes it reviewable.
 
 The agent should inspect the codebase first, then create the visual plan when a
 wrong direction would be costly. The returned Plans link opens the review UI so
@@ -101,7 +103,7 @@ it to the agent starts a revision turn against the existing plan.
 - "Create a `/ui-plan` for the new onboarding screen with mobile and desktop states."
 - "Create a `/prototype-plan` for the checkout flow so I can click through it."
 - "Use `/visual-questions` to help me choose the dashboard direction first."
-- "Run `/visualize-plan` on the Markdown plan below and make it easier to review."
+- "Use `/visual-plan` on the Markdown plan below and make it easier to review."
 
 ## For developers
 

package/docs/content/visual-plans.md

@@ -20,7 +20,7 @@ Install with the Agent-Native CLI. The command installs the skill instructions,
 agent-native skills add visual-plan
 ```
 
-Authentication is a one-time browser sign-in at setup — this is intended, and it is what lets the agent persist and share the plans it generates. This also installs the companion commands `/ui-plan`, `/visual-questions`, and `/visualize-plan` (see [Invoking the skill](#invoke)).
+Authentication is a one-time browser sign-in at setup — this is intended, and it is what lets the agent persist and share the plans it generates. This also installs the companion commands `/ui-plan`, `/prototype-plan`, `/plan-design`, and `/visual-questions` (see [Invoking the skill](#invoke)).
 
 What the auth step does depends on your client:
 
@@ -40,11 +40,14 @@ Once installed, use the slash command that fits the work:
 
 - `/visual-plan` — the canonical command for any rich plan (architecture, backend, refactors, UI).
 - `/ui-plan` — UI-first work that should start with the screens.
+- `/prototype-plan` — prototype-first work that should start with a clickable flow.
+- `/plan-design` — full-fidelity branded UI direction before implementation.
 - `/visual-questions` — a short visual intake form before planning.
-- `/visualize-plan` — turn an existing Codex, Claude Code, Markdown, or pasted plan into a visual companion.
 
 The agent gates hard: it only builds a polished visual plan when a wrong direction would be costly, and skips it for trivial, unambiguous work. Each command generates a plan and opens the editor.
 
+When a Codex, Claude Code, Markdown, or pasted plan already exists, use `/visual-plan`. The agent should preserve that source plan and build the richer review surface from it instead of starting over.
+
 When a plan has unresolved decisions that are useful to answer after the first pass, the agent can put them in an **Open Questions** form at the bottom of the same plan. You can choose single or multiple options, fill in freeform answers, and send the answers back to the agent to revise the plan.
 
 ## Editing in the browser as a guest {#guest}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.39.0",
+  "version": "0.39.2",
   "type": "module",
   "engines": {
     "node": ">=22"

package/src/templates/default/.agents/skills/actions/SKILL.md

@@ -2,20 +2,45 @@
 name: actions
 description: >-
   How to create and run agent actions. Actions are the single source of truth
-  for app operations — the agent calls them as tools, the frontend calls them
-  as HTTP endpoints. Use when creating a new action, adding an API integration,
-  or wiring up frontend data fetching.
+  for app operations — the agent calls them as tools and frontend code calls
+  them through client hooks. Use when creating a new action, adding an API
+  integration, or wiring up frontend data fetching.
+metadata:
+  internal: true
 ---
 
 # Agent Actions
 
 ## Rule
 
-Actions in `actions/` are the **single source of truth** for app operations. The agent calls them as tools, and the framework auto-exposes them as HTTP endpoints at `/_agent-native/actions/:name`. The frontend calls those endpoints using React Query hooks. No duplicate `/api/` routes needed.
+Actions in `actions/` are the **single source of truth** for app operations. The agent calls them as tools, and the frontend calls them through `useActionQuery` / `useActionMutation`. The framework owns the HTTP transport behind those hooks. No duplicate `/api/` routes needed.
+
+Before creating any custom REST/API route for app data, inspect `actions/` and the action table in `AGENTS.md`. If an action already exists, call it directly from the agent or with `useActionQuery` / `useActionMutation` from the UI. If the capability is missing, create or update a `defineAction`. Do not add `/api/*`, `server/routes/*`, or other pass-through endpoints whose main job is to call, repackage, or re-export an action.
 
 ## Why
 
-Actions give the agent callable tools with structured input/output, AND they give the frontend type-safe HTTP endpoints automatically. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.
+Actions give the agent callable tools with structured input/output, AND they give the frontend a typed client contract through hooks. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.
+
+## Keep the Action Surface Small and Orthogonal
+
+Every agent-exposed action is a tool in the model's context window. There is a real cost to each one: more tools means more for the model to read, disambiguate, and choose between, which degrades tool-selection quality. Treat the action list like an API you have to maintain — add the fewest, most orthogonal actions that cover the capability, not one per UI affordance.
+
+- **Prefer one CRUD-style `update` over N per-field actions.** A single `update-<thing>` that takes a patch of optional fields beats `update-<thing>-name`, `update-<thing>-order`, `update-<thing>-color`, … The agent (and the UI) pass only the fields that change. Same for `create`/`delete` — one orthogonal action per resource, not one per code path.
+- **Reach for a generic query / escape hatch before minting a new read action.** If the agent needs more or different data, do not add `get-<thing>-by-x`, `list-<thing>-filtered-by-y`, etc. For provider data, expose the shared `provider-api-catalog` / `provider-api-docs` / `provider-api-request` trio (see `templates/dispatch/actions/`) so the agent can hit any endpoint or filter without a new action each time. For app data in dev, the `db-query` tool already answers arbitrary read questions.
+- **Hide UI-only or purely programmatic actions from the model with `agentTool: false`.** An action that only the frontend or an HTTP/cron caller needs should not spend a slot in the model's tool list. `agentTool: false` keeps it callable from `useActionMutation` / `callAction` / `/_agent-native/actions/<name>` while removing it from every agent tool surface (in-app assistant, MCP, A2A).
+- **`agentTool: false` is NOT `toolCallable: false`.** They are different switches:
+  - `agentTool: false` → hidden from the **model entirely** (it is no longer a tool the agent can see or call). Still frontend/HTTP-callable.
+  - `toolCallable: false` → only blocks the **sandboxed extension ("tools") iframe bridge** (`appAction(...)`). The action stays fully visible to the model, the UI, the CLI, MCP, and A2A. Use it for high-blast-radius operations (account/org/auth changes), not for trimming the tool list.
+- **Remove or hide stale actions.** When the UI stops using an action, delete it or set `agentTool: false` — do not leave it exposed to the model as dead tool weight. The advisory audit below helps you spot these.
+
+### Audit Script (Advisory)
+
+`pnpm actions:audit [template ...]` (or `node scripts/audit-template-actions.mjs`) statically scans a template's `actions/` and prints two kinds of suggestions:
+
+1. **Likely UI-dead** — HTTP-exposed mutating actions whose name is never referenced under `app/` (candidates to delete or mark `agentTool: false`).
+2. **Likely redundant clusters** — groups like `update-foo-name` / `update-foo-order` that could collapse into one orthogonal `update-foo`.
+
+It is **advisory only**: it always exits 0, never fails CI, and uses conservative heuristics, so expect some false positives (e.g. an action the agent calls but the UI doesn't). Use it as a prompt to review, not a gate.
 
 ## How to Create an Action
 
@@ -45,14 +70,59 @@ export default defineAction({
 
 The `schema` field accepts a Zod schema (or any Standard Schema-compatible library). It provides runtime validation with clear error messages (400 for HTTP, error result for agent), full TypeScript type inference for `run()` args, and auto-generated JSON Schema for the agent's tool definition. `zod` is a dependency of all templates.
 
+When an action reads or writes app data, use Drizzle's query builder and portable operators from `drizzle-orm`. Do not use raw SQL, `getDbExec()`, or dialect-specific schema imports in normal actions unless there is a documented reason Drizzle cannot express the query.
+
+When an action calls an external service, never hardcode API keys, bearer
+tokens, webhook URLs, signing secrets, OAuth refresh tokens, private
+Builder/internal data, or customer data. Read user/org/workspace credentials
+from `readAppSecret`, `resolveCredential`, OAuth token helpers, or the provider
+API credential adapter. Use `process.env` only for explicitly deploy-level
+configuration, and keep examples to obvious placeholders.
+
 Tips:
 - Use `.describe()` for parameter descriptions
 - Use `.optional()` for optional params
-- Use `z.coerce.number()` / `z.coerce.boolean()` for params that arrive as strings from HTTP
+- Use `z.coerce.number()` for numeric params that arrive as strings from HTTP.
+  For booleans, use an explicit string parser/helper instead of
+  `z.coerce.boolean()` because JavaScript treats any non-empty string,
+  including `"false"`, as truthy.
 - Use `z.enum(["draft", "published"])` for constrained values
 
 The legacy `parameters` field (plain JSON Schema object) still works as a fallback but does not provide runtime validation or type inference.
 
+## Decision Order
+
+When you need app data or a mutation:
+
+1. **Use an existing action** if one already performs the operation.
+2. **Create or extend a `defineAction`** when the agent and UI both need a new operation.
+3. **Create a custom route only for route-only concerns** such as uploads, streaming, webhooks, OAuth callbacks, or a non-JSON protocol.
+
+Do not build an umbrella REST API to make actions "easier" to call. Actions are already callable by agents, CLIs, React hooks, HTTP, MCP/A2A exposure, and external hosts through the framework.
+
+## Flexible Provider APIs
+
+For provider integrations used in ad hoc analysis, querying, reporting, or
+cross-source research, do not hardcode every provider endpoint as a separate
+rigid action. Expose the shared provider API action trio instead:
+
+- `provider-api-catalog`: lists provider base URLs, auth style, credential keys,
+  docs/spec URLs, placeholders, and examples without exposing secrets.
+- `provider-api-docs`: fetches registered provider docs/spec URLs when the
+  exact endpoint, filter operator, payload shape, or pagination contract is
+  uncertain.
+- `provider-api-request`: makes a constrained authenticated HTTP request to the
+  provider host, injects configured credentials, blocks private/internal URLs,
+  and redacts secrets.
+
+Use `@agent-native/core/provider-api` as the shared substrate. A template should
+only add a thin credential adapter when it has app-specific credential lookup
+rules. Keep `provider-api-request` `http: false` unless you have a separate UI
+permission model for arbitrary provider writes. Specific actions such as
+`hubspot-deals`, `search-emails`, or `sync-source` are convenience shortcuts,
+not capability limits; agents should fall back to the provider API trio when a
+question requires an endpoint or filter that the shortcut does not model.
+
 ### The `http` Option
 
 Controls how the action is exposed as an HTTP endpoint:
@@ -99,7 +169,7 @@ run: async (args) => {
 
 ## Frontend Hooks
 
-The frontend calls action endpoints using React Query hooks from `@agent-native/core/client`:
+The frontend calls actions using React Query hooks from `@agent-native/core/client`. Components should not hand-write `fetch("/_agent-native/actions/...")`; add or reuse a client hook/helper instead. Use `callAction` from the same package for imperative cases that do not fit a hook, such as debounced search, prefetching, or non-React event handlers.
 
 ### `useActionQuery` — for GET actions
 
@@ -135,6 +205,17 @@ function AddMealButton() {
 
 Mutations automatically invalidate all `["action"]` query keys on success, so GET queries refetch.
 
+### `callAction` — for imperative client code
+
+```ts
+import { callAction } from "@agent-native/core/client";
+
+const people = await callAction("search-people", { query }, { method: "GET" });
+```
+
+Prefer hooks in React data flows. Use `callAction` when a hook would be awkward;
+do not hand-write action route fetches in components.
+
 ## How to Run (Agent)
 
 ```bash
@@ -161,7 +242,7 @@ Most operations should be actions. You only need custom routes in `server/routes
 - **Webhooks** — external services POST to a specific URL
 - **OAuth callbacks** — redirect-based flows that need specific URL patterns
 
-If it's a standard CRUD operation or data query, use an action instead.
+If it's a standard CRUD operation, data query, or a wrapper around an action, use the action instead.
 
 ## Legacy Pattern (bare export)
 
@@ -171,7 +252,6 @@ Older actions use a bare async function export with `parseArgs`:
 import { parseArgs, loadEnv, fail } from "@agent-native/core";
 
 export default async function myAction(args: string[]) {
-  // Only for deploy-level runtime config. User/org credentials use secrets/OAuth.
   loadEnv();
   const parsed = parseArgs(args);
   // ...
@@ -186,11 +266,15 @@ This still works but is not auto-exposed as HTTP. Prefer `defineAction` for all
 - **Return structured data.** Return objects/arrays, not `JSON.stringify()`.
 - **Use `http: { method: "GET" }`** for read-only actions. Default is POST.
 - **Use `http: false`** for agent-only actions (`navigate`, `view-screen`).
+- **Use `agentTool: false`** for UI-only / programmatic actions that should NOT be a tool in the model's context window. It stays frontend/HTTP-callable but is hidden from the agent. Distinct from `toolCallable: false`, which only blocks the sandboxed extension iframe bridge.
+- **Document reusable actions.** If a new action should be called by agents outside one narrow screen, update `AGENTS.md` with when to use it, important args, and which return fields to preserve.
+- **Promote workflow-heavy actions to skills.** If the action is part of a provider-backed, cross-app, MCP/A2A, or multi-step workflow, create or update a skill in `.agents/skills/` and add app-skill visibility (`internal`, `exported`, or `both`) when it should ship through a marketplace.
 - **Use `loadEnv()`** only for deploy-level configuration. User/org/workspace
   credentials belong in the encrypted secrets/credential/OAuth stores, never as
-  hardcoded literals, shared env fallbacks, logs, or action responses.
+  hardcoded literals or shared env fallbacks.
 - **Use `fail()`** for user-friendly error messages (exits with message, no stack trace).
 - **Import from `@agent-native/core`** — Don't redefine `parseArgs()` or other utilities locally.
+- **Do not re-export actions as REST.** The mounted `/_agent-native/actions/:name` endpoint is the REST surface; duplicating it under `/api/*` creates drift and hides the operation from agents.
 
 ## Common Patterns
 
@@ -263,5 +347,6 @@ export default defineAction({
 
 - **storing-data** — Actions read/write data in SQL
 - **delegate-to-agent** — The agent invokes actions via `pnpm action <name>`
-- **real-time-sync** — Database writes from actions trigger poll events to update the UI
+- **real-time-sync** — Database writes from actions trigger change events to update the UI
 - **adding-a-feature** — Actions are area 2 of the four-area checklist
+- **client-methods** — Client code uses named helpers/hooks instead of raw REST calls