@agent-native/core 0.37.2 → 0.38.0

package/docs/content/visual-plans.md

@@ -0,0 +1,72 @@
+---
+title: "Visual Plans"
+description: "Turn your coding agent's plans into interactive, reviewable documents with /visual-plan. Install authenticates once; reviewers you share with edit as a guest, sign in only to save or share."
+---
+
+# Visual Plans
+
+`/visual-plan` is a coding-agent skill that turns the plan your agent would normally write in Markdown into a **structured visual document**: an optional pan/zoom wireframe canvas on top and a Notion-like technical document below, with diagrams, mockups, prototype options, annotations, and comments you can react to before any code changes.
+
+There are two ways into Plans:
+
+- **From your coding agent (CLI)** — one command installs the skill, registers the hosted Plans connector, and authenticates it.
+- **In the browser** — anyone you share with can open the editor and create or edit as a **guest, with no sign-up**. They sign in only when they want to save or share.
+
+## Coding agent setup {#install}
+
+Install with the Agent-Native CLI. The command installs the skill instructions, registers the hosted Plans MCP connector, **and authenticates it in the same step**, so your first tool call does not hit an OAuth wall:
+
+```bash
+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)).
+
+What the auth step does depends on your client:
+
+- **OAuth-capable hosts** (Claude Code) get a URL-only MCP entry plus a prompt to run `/mcp` and choose **Authenticate**.
+- **Codex / Cowork** run a short browser device-code flow: the CLI prints a code, opens the verification page, and writes the connector once you approve.
+- In a **non-interactive shell or CI**, the auth step is skipped and the exact command to run later is printed for you.
+
+Pass `--no-connect` to register the connector without authenticating, then run `agent-native connect https://plan.agent-native.com` whenever you are ready:
+
+```bash
+agent-native skills add visual-plan --no-connect
+```
+
+## Invoking the skill {#invoke}
+
+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.
+- `/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.
+
+## Editing in the browser as a guest {#guest}
+
+People you share a plan with do not need to install anything. They open the Plans editor and **create and edit with no sign-up** — they work as a guest. Signing in is only required when someone wants to **save or share** their own work.
+
+When a guest signs in, the plans they created as a guest are **claimed** into their account, so nothing they built is lost.
+
+Plan prose edits inline: click into any text section, type, format with the rich editor toolbar or slash menu, and Plans autosaves the underlying markdown. Review annotation mode temporarily turns text sections read-only so clicks can pin feedback; leave review mode to keep editing prose.
+
+## Sharing and commenting {#sharing}
+
+Sharing and commenting are the workflows that need an account:
+
+- **Viewing** a public or shared plan works for anyone with the link — no account required.
+- **Commenting** on a shared plan requires an agent-native account.
+- **Sharing** a plan (publishing it to a link, private sharing, reviewer access, cross-device or team review) requires signing in. Google sign-in appears when the standard Google OAuth env vars are configured.
+
+The hosted Plans connector lives at `https://plan.agent-native.com/_agent-native/mcp`. Never put shared secrets in skill files.
+
+## Local mode (advanced, offline) {#local}
+
+For fully offline, no-account use, you can run the Plans app locally and sync your plans to your repo as MDX. This local mode is a separate, advanced path — not the default hosted flow — and is best when you need everything to stay on your machine and in version control.
+
+## Recovering from auth errors {#auth-errors}
+
+If a Plans tool ever returns `needs auth`, `Unauthorized`, or `Session terminated`, do not keep retrying it. Authenticate the connector with `agent-native connect https://plan.agent-native.com` (or re-run `/mcp` → **Authenticate** in an OAuth-capable host), then continue once the connector is available.

package/docs/content/workspace.md

@@ -290,15 +290,15 @@ The resource system also seeds a personal `LEARNINGS.md` for compatibility with
 
 **Where it fits.**
 
-| Surface            | Scope              | Written by                           | Read when                              |
-| ------------------ | ------------------ | ------------------------------------ | -------------------------------------- |
-| `AGENTS.md`        | Shared             | Humans / agent on request            | Every turn                             |
-| `LEARNINGS.md`     | Shared             | Humans / agent on request            | Every turn                             |
-| `memory/MEMORY.md` | Personal           | Agent / humans                       | Every turn                             |
-| `instructions/…`   | Shared             | Humans / agent on request            | Every turn                             |
-| `skills/…`         | Shared             | Humans / agent on request            | On demand (`/slash` command)           |
-| `context/…`        | Shared             | Humans / agent on request            | Indexed every turn, read when relevant |
-| `mcp-servers/…`    | Workspace / shared | Humans via Dispatch or app workspace | MCP config refresh                     |
+| Surface            | Scope              | Written by                           | Read when                                                                                                                                           |
+| ------------------ | ------------------ | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AGENTS.md`        | Shared             | Humans / agent on request            | Every turn                                                                                                                                          |
+| `LEARNINGS.md`     | Shared             | Humans / agent on request            | Every turn (Shared copy only — a personal `LEARNINGS.md` is seeded for back-compat but isn't preloaded; put personal context in `memory/MEMORY.md`) |
+| `memory/MEMORY.md` | Personal           | Agent / humans                       | Every turn                                                                                                                                          |
+| `instructions/…`   | Shared             | Humans / agent on request            | Every turn                                                                                                                                          |
+| `skills/…`         | Shared             | Humans / agent on request            | On demand (`/slash` command)                                                                                                                        |
+| `context/…`        | Shared             | Humans / agent on request            | Indexed every turn, read when relevant                                                                                                              |
+| `mcp-servers/…`    | Workspace / shared | Humans via Dispatch or app workspace | MCP config refresh                                                                                                                                  |
 
 Users can edit these memory files directly in the Workspace tab — they're regular resources. Delete lines the agent got wrong, keep personal preferences in `memory/MEMORY.md`, or promote team-wide rules into `AGENTS.md`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.37.2",
+  "version": "0.38.0",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -41,6 +41,8 @@
     "./db/schema": "./dist/db/schema.js",
     "./db/drizzle-config": "./dist/db/drizzle-config.js",
     "./client": "./dist/client/index.js",
+    "./blocks": "./dist/client/blocks/index.js",
+    "./blocks/server": "./dist/client/blocks/server.js",
     "./client/AgentPanel": "./dist/client/AgentPanel.js",
     "./client/application-state": "./dist/client/application-state.js",
     "./client/api-path": "./dist/client/api-path.js",
@@ -120,7 +122,7 @@
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest --run src",
-    "prepack": "npm run build && cp ../../README.md ./README.md",
+    "prepack": "tsx ../../scripts/sync-workspace-core-skills.ts --check && npm run build && cp ../../README.md ./README.md",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
@@ -151,12 +153,23 @@
     "@tabler/icons-react": "^3",
     "@tailwindcss/typography": "^0.5.19",
     "@tanstack/react-table": "^8.21.3",
-    "@tiptap/core": "^3.22.2",
-    "@tiptap/extension-link": "^3.22.2",
-    "@tiptap/extension-placeholder": "^3.22.2",
-    "@tiptap/pm": "^3.22.2",
-    "@tiptap/react": "^3.22.2",
-    "@tiptap/starter-kit": "^3.22.2",
+    "@tiptap/core": "^3.26.0",
+    "@tiptap/extension-code-block-lowlight": "^3.26.0",
+    "@tiptap/extension-collaboration": "^3.26.0",
+    "@tiptap/extension-collaboration-caret": "^3.26.0",
+    "@tiptap/extension-image": "^3.26.0",
+    "@tiptap/extension-link": "^3.26.0",
+    "@tiptap/extension-placeholder": "^3.26.0",
+    "@tiptap/extension-table": "^3.26.0",
+    "@tiptap/extension-table-cell": "^3.26.0",
+    "@tiptap/extension-table-header": "^3.26.0",
+    "@tiptap/extension-table-row": "^3.26.0",
+    "@tiptap/extension-task-item": "^3.26.0",
+    "@tiptap/extension-task-list": "^3.26.0",
+    "@tiptap/pm": "^3.26.0",
+    "@tiptap/react": "^3.26.0",
+    "@tiptap/starter-kit": "^3.26.0",
+    "@tiptap/y-tiptap": "^3.0.4",
     "@uiw/react-codemirror": "^4.25.10",
     "better-auth": "1.6.0",
     "better-sqlite3": "^12.8.0",
@@ -167,10 +180,12 @@
     "drizzle-orm": "^0.45.2",
     "fzstd": "^0.1.1",
     "h3": "^2.0.1-rc.20",
+    "highlight.js": "^11.11.1",
     "isbot": "^5",
     "jiti": "^2.6.1",
     "jose": "^6.2.2",
     "kiwi-schema": "^0.5.0",
+    "lowlight": "^3.3.0",
     "minimatch": "^10.0.0",
     "nanoid": "^5.1.9",
     "nitro": "3.0.260415-beta",
@@ -186,7 +201,7 @@
     "tiptap-markdown": "^0.9.0",
     "tw-animate-css": "1.4.0",
     "y-protocols": "^1.0.7",
-    "yjs": "^13.6.30",
+    "yjs": "^13.6.31",
     "zod": "^4.3.6"
   },
   "peerDependencies": {
@@ -327,8 +342,8 @@
     "express": "^5.2.1",
     "node-pty": "^1.1.0",
     "playwright": "^1.60.0",
-    "react": "^19.2.5",
-    "react-dom": "19.2.5",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "react-router": "^7.16.0",
     "tailwindcss": "catalog:",
     "typescript": "^6.0.3",

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

@@ -171,6 +171,7 @@ 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);
   // ...
@@ -185,7 +186,9 @@ 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 `loadEnv()`** if the action needs environment variables (API keys, etc.).
+- **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.
 - **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.
 

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

@@ -82,9 +82,16 @@ new Function(userInput);                                   // NEVER
 
 ## Secrets Management
 
+Never hardcode credential values or real private data. Source, docs, tests,
+fixtures, prompts, screenshots, seed data, application state, action responses,
+and generated app/extension content may name credential keys, but must never
+contain API key values, tokens, webhook URLs, signing secrets, private
+Builder/internal data, or customer data.
+
 | Secret type | Where to store | Why |
-|-------------|---------------|-----|
-| API keys (OpenAI, Stripe, etc.) | `.env` file (gitignored) | Never committed, server-side only |
+|-------------|----------------|-----|
+| User/org/workspace API keys, service tokens, webhook secrets | Secrets registry / `app_secrets` vault or `saveCredential` / `resolveCredential` | Encrypted, scoped, never sent to the client |
+| Deploy-only infrastructure secrets | Deployment env vars (`.env` only for local dev) | Server-side runtime configuration |
 | OAuth tokens (Google, GitHub) | `oauth_tokens` store | Per-user, per-provider, server-side |
 | App configuration | `settings` store | OK for non-secret config (themes, preferences) |
 | Session tokens | Framework handles | Automatic via Better Auth |
@@ -94,6 +101,8 @@ new Function(userInput);                                   // NEVER
 - Never return secrets in action responses — they may appear in agent chat or client UI
 - Never log secrets (tokens, keys, passwords)
 - Never commit `.env` files — they're gitignored by default
+- Use env vars only for deploy-level secrets. User/org/workspace credentials
+  must use the encrypted secrets/credential/OAuth stores.
 - Access env vars via `process.env` in actions/server code, never send them to the client
 
 ## Auth Patterns
@@ -193,7 +202,7 @@ A2A_SECRET=your-shared-secret-at-least-32-chars
 ```
 
 **How it works:**
-1. App A signs a JWT with `A2A_SECRET` containing `sub: "steve@builder.io"`
+1. App A signs a JWT with `A2A_SECRET` containing `sub: "user@example.com"`
 2. App B receives the call, verifies the JWT signature
 3. App B sets `AGENT_USER_EMAIL` from the verified `sub` claim
 4. Data scoping applies — App B only shows steve's data
@@ -206,7 +215,7 @@ Without `A2A_SECRET`, A2A calls are unauthenticated (fine for local dev, not pro
 2. **Always use `defineAction` with a Zod `schema:`** for input validation on user-facing actions.
 3. **Never concatenate user input into SQL** — use parameterized queries or Drizzle ORM.
 4. **Never use `dangerouslySetInnerHTML`** or `innerHTML` with user-controlled content.
-5. **Never store secrets outside `.env` or `oauth_tokens`** — no settings, no source code, no responses.
+5. **Never hardcode or expose secrets** — no settings, application state, source code, fixtures, logs, or responses. Use the secrets registry / vault, scoped credentials, OAuth stores, or deploy-level env vars as appropriate.
 6. **Never bypass scoping** — don't raw-query tables without going through `db-query`/`db-exec`.
 7. **Never create unprotected routes that modify data** — use `defineAction` or check `getSession()`.
 8. **Don't hardcode emails** — use `AGENT_USER_EMAIL` environment variable.

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

@@ -16,7 +16,7 @@ There are three storage layers, each for a different kind of data:
 
 ### 1. Settings — app configuration
 
-Key-value store for persistent config that the user or agent can change. Theme, preferences, integration API keys, availability schedules.
+Key-value store for persistent non-secret config that the user or agent can change. Theme, preferences, integration settings, availability schedules.
 
 ```ts
 import { getSetting, putSetting } from "@agent-native/core/settings";
@@ -88,6 +88,15 @@ const tokens = await getOAuthTokens("google", "user@gmail.com");
 const accounts = await listOAuthAccounts("google");
 ```
 
+### 5. Secrets / Credentials — encrypted values
+
+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.
+
 ## Which Layer to Use
 
 | Data | Layer | Why |
@@ -96,6 +105,7 @@ const accounts = await listOAuthAccounts("google");
 | 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 |
 
 ## Environment Variables
@@ -107,10 +117,12 @@ Infrastructure config stays in `.env` — these differ per deployment:
 - `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` — OAuth app credentials
 - `ACCESS_TOKEN` — production auth token
 
-Everything else (user settings, tokens, app state) goes in SQL.
+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.
 
 ## Security Rules
 
-- **Never store API keys or secrets in Settings or Application State** — use `.env` for API keys (gitignored) and the `oauth_tokens` store for OAuth credentials. Settings and application state are readable by the client.
+- **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.

package/src/templates/default/AGENTS.md

@@ -11,6 +11,7 @@ This is an **@agent-native/core** application -- the AI agent and UI share state
 3. **Actions for app operations** -- `pnpm action <name>` dispatches to callable action files in `actions/`; `defineAction` also auto-exposes those operations at `/_agent-native/actions/:name` for the UI. Do not create custom REST routes that re-export actions.
 4. **Live sync keeps the UI current** -- Database writes stream over `/_agent-native/events` first, with `/_agent-native/poll` as the fallback. **When you (the agent) write data, the UI must reflect the change without a manual refresh.** This is non-negotiable. Use `useActionQuery` / `useActionMutation` for action-backed data (preferred). If you use raw `useQuery`, fold `useChangeVersions([<source>, "action"])` into the key for targeted refreshes. See the `real-time-sync` and `adding-a-feature` skills.
 5. **Agent can update code** -- The agent can modify this app's source code directly.
+6. **No hardcoded secrets or private data** -- Never put API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals in source, docs, tests, fixtures, prompts, screenshots, application state, action responses, or generated content. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 
 ### Database Code
 

package/src/templates/default/DEVELOPING.md

@@ -120,6 +120,8 @@ agentChat.submit("Generate something");
 
 Local development defaults to a SQLite file at `data/app.db`. That local file is for development; containers, previews, and serverless deploys can reset their filesystem. For production/cloud deployment, set `DATABASE_URL` to point to a persistent SQL database. Turso is optional, not required; common choices include Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and Builder.io-managed environments when available.
 
+Real credential values belong only in local `.env` files, deployment configuration, or registered secrets/settings UI. Never commit, document, log, return, paste, or include real keys, tokens, webhook URLs, signing secrets, or private data in examples; use empty values or obvious placeholders.
+
 When adding app data, define tables with `@agent-native/core/db/schema` helpers and use Drizzle's query builder for reads/writes. Do not import dialect-specific schema helpers from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core`, and do not write raw SQL in normal actions or handlers when Drizzle can express the query. Raw SQL belongs in additive migrations, health checks, or carefully scoped maintenance.
 
 | Variable              | Required                        | Description                                                                |

package/src/templates/workspace-core/.agents/skills/a2a-protocol/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   How agents call other agents via the A2A (agent-to-agent) JSON-RPC protocol.
   Use when enabling inter-agent communication, exposing agent skills to other
   agents, or calling external agents from scripts.
+metadata:
+  internal: true
 ---
 
 # A2A Protocol (Agent-to-Agent)
@@ -175,10 +177,15 @@ submitted → working → completed
 
 A2A uses bearer token auth. The server reads the token from the environment variable specified by `apiKeyEnv`:
 
-- Set `A2A_API_KEY=my-secret-token` in the server's environment
-- Callers pass it as `Authorization: Bearer my-secret-token`
+- Set `A2A_API_KEY=<A2A_API_KEY_VALUE>` in the server's deployment environment
+- Callers pass it as `Authorization: Bearer <A2A_API_KEY_VALUE>`
 - The agent card endpoint (`/.well-known/agent-card.json`) is public — no auth needed for discovery
 
+Never hardcode the bearer token in source, docs, prompts, app state, action
+descriptions, client bundles, or examples. A2A tokens are deploy-level secrets
+unless a specific app designs a scoped credential flow; read them from secure
+runtime configuration and never log or return them.
+
 ## Message Parts
 
 Messages contain typed parts:
@@ -247,5 +254,5 @@ import type {
 ## Related Skills
 
 - **delegate-to-agent** — For work the local agent handles. Use A2A when the work goes to a different agent.
-- **scripts** — A2A calls typically happen in scripts
+- **actions** — A2A calls typically happen inside actions
 - **storing-data** — Results from A2A calls are stored in SQL like any other data

package/src/templates/workspace-core/.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)
 
@@ -185,9 +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 `loadEnv()`** if the action needs environment variables (API keys, etc.).
+- **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 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
 
@@ -260,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