@agent-native/core 0.37.3 → 0.39.0

package/docs/content/visual-plans.md

@@ -0,0 +1,74 @@
+---
+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, answerable Open Questions, 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.
+
+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}
+
+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.3",
+  "version": "0.39.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