@agent-native/core 0.37.3 → 0.38.0

package/dist/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

package/dist/templates/workspace-core/.agents/skills/adding-a-feature/SKILL.md

@@ -3,6 +3,8 @@ name: adding-a-feature
 description: >-
   The four-area checklist every new feature must complete. Use when adding any
   feature, integration, or capability to ensure the agent and UI stay in parity.
+metadata:
+  internal: true
 ---
 
 # Adding a Feature — The Four-Area Checklist
@@ -21,7 +23,7 @@ When you add a new feature, work through these four areas in order:
 
 ### 1. UI Component
 
-Build the user-facing interface — a page, component, dialog, or route. Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` to call actions for data fetching and mutations — you rarely need custom `/api/` routes.
+Build the user-facing interface — a page, component, dialog, or route. Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` to call actions for data fetching and mutations. Do not create a custom REST endpoint just so React can call action-backed data; the action endpoint already exists.
 
 **Auto-refresh on agent writes is non-negotiable** — when the agent mutates data, the UI must reflect the change without a manual refresh. There are two paths, and you must pick the right one:
 
@@ -44,12 +46,45 @@ Build the user-facing interface — a page, component, dialog, or route. Use `us
 
 ### 2. Action
 
-Create an action in `actions/` using `defineAction`. This serves double duty: the agent calls it as a tool, and the framework auto-exposes it as an HTTP endpoint at `/_agent-native/actions/:name` for the UI to call. Set `http: { method: "GET" }` for read actions, leave default for writes, or set `http: false` for agent-only actions like `navigate` and `view-screen`.
+Create an action in `actions/` using `defineAction`. This serves double duty: the agent calls it as a tool, and the UI calls it through `useActionQuery` / `useActionMutation` while the framework owns the HTTP transport. Set `http: { method: "GET" }` for read actions, leave default for writes, or set `http: false` for agent-only actions like `navigate` and `view-screen`.
+
+Before adding a new route or endpoint, inspect the existing actions. Reuse an
+action if it already covers the business operation, extend it if the shared
+contract is incomplete, or create a new `defineAction` if the agent and UI both
+need the capability. Do not add pass-through `/api/*` routes that re-export
+actions. If client code needs a new framework/app route, expose a named helper
+or hook first and use that helper from components and docs.
+
+For provider-backed analysis/query/reporting integrations, do not turn every
+provider endpoint or filter into a rigid action. Prefer the shared
+`provider-api-catalog` / `provider-api-docs` / `provider-api-request` pattern
+from `@agent-native/core/provider-api`, then add narrow convenience actions only
+for workflows that truly deserve a first-class shortcut.
+
+If the feature needs credentials, design the credential path in the same change.
+Never hardcode API keys, tokens, webhook URLs, signing secrets, private
+Builder/internal data, or customer data in the action, UI, seed data, fixtures,
+docs, prompts, or generated extension/app content. Register required secrets,
+use OAuth helpers, or read scoped values from the vault/credential store.
+
+**If the action produces or lists a navigable resource**, add a `link` builder that returns `{ url: buildDeepLink({ app, view, params }), label }`. External coding agents and MCP hosts (Claude / ChatGPT / Claude Code / Cowork / Codex, over MCP/A2A) then surface an "Open in … →" deep link that drops the user back into the running UI focused on the record — for free. If a compatible MCP host should render an inline review/edit surface, also add `mcpApp` with `embedApp()` so the action embeds the real React app route instead of a one-off HTML UI. The `link` builder and `mcpApp` metadata must be pure and synchronous (no I/O). Any external-agent read/ingest action must be `http: { method: "GET" }` + `readOnly: true` + `publicAgent: { expose: true, readOnly: true, requiresAuth: true }`. See the `external-agents` skill.
 
 ### 3. Skills / Instructions
 
 Update `AGENTS.md` and/or create a skill in `.agents/skills/` if the feature introduces patterns the agent needs to know. At minimum, add the new actions to the action table in the template's `AGENTS.md`.
 
+Reusable actions are part of the app contract, not just implementation detail. When an action is useful outside one screen, update agent instructions in the same change so app agents know when to call it, which arguments matter, and what output to preserve. If the capability is workflow-heavy, cross-app, provider-backed, or has a non-obvious sequence of actions, add or update a skill instead of burying the behavior in one long `AGENTS.md` paragraph.
+
+Instruction examples may name secret keys like `SLACK_WEBHOOK`, but must use
+placeholders such as `${keys.SLACK_WEBHOOK}` or `<SLACK_WEBHOOK>`. Do not paste
+real keys, internal data, or customer data into instructions as examples.
+
+For app-backed skills, declare skill visibility in the app-skill manifest:
+
+- `internal` — only the app's own agents should use it.
+- `exported` — marketplace installs receive it, but the app does not need it loaded internally.
+- `both` — shared between the app's internal agents and exported marketplace bundles.
+
 ### 4. Application State Sync
 
 Expose navigation and selection state so the agent knows what the user is looking at. Write to the `navigation` app-state key on route changes. Update the `view-screen` action to fetch relevant data for the new feature. Add a `navigate` command if the agent needs to open the new view.
@@ -100,7 +135,10 @@ See the "Client-Side Routing" section in the root `CLAUDE.md` for full details.
 - **Per-route `<AppLayout>` wrappers** — Every route file wraps its content in `<AppLayout>` or `<Layout>`. React sees a different component at the outlet on each nav and unmounts the whole shell, causing the agent sidebar to reload on every click. Mount the shell once above `<Outlet />` (root.tsx or `_app.tsx` pathless layout).
 - **UI without actions** — The user can create forms but the agent cannot. The agent says "I don't have access to that" when it should be able to do it.
 - **Actions without AGENTS.md** — The actions exist but the agent doesn't know about them because they're not documented. The agent reinvents solutions instead of using the actions.
-- **Duplicate API routes** — Creating `/api/` routes for operations that actions already handle. Actions are auto-exposed as HTTP endpoints — use `useActionQuery`/`useActionMutation` instead.
+- **Duplicate API routes** — Creating `/api/` routes for operations that actions already handle, including pass-through routes that just call or repackage an action. Use `useActionQuery`/`useActionMutation` instead.
+- **Raw client route calls** — Teaching or adding `fetch("/_agent-native/...")`,
+  `fetch(agentNativePath(...))`, or template `/api/*` calls in components for
+  normal app work. Add a named client helper/hook and call that instead.
 - **Features without app-state** — The agent cannot see that the user is looking at a specific form, email, or chart. It asks "which one?" instead of acting on the current selection.
 - **Actions without UI** — The agent can do something the user cannot. This is less common but still breaks parity.
 
@@ -113,6 +151,9 @@ After completing all four areas, verify:
 3. Does `pnpm action view-screen` show the relevant state when the user is using the feature?
 4. Can the agent navigate to the feature view via the `navigate` action?
 5. Is the feature documented in AGENTS.md with action names and args?
+6. Are credentials and sensitive data supplied only through approved runtime
+   channels, with no hardcoded real keys, tokens, webhook URLs, Builder/internal
+   data, or customer data?
 
 ## One more area — sharing
 
@@ -125,6 +166,7 @@ TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSh
 - **sharing** — How to make a new resource ownable (private by default, share with users/orgs/public)
 - **context-awareness** — How to expose UI state to the agent (area 4 in detail)
 - **actions** — How to create actions with `defineAction` and the `http` option (area 2 in detail)
+- **external-agents** — Add a `link` builder so external agents (MCP/A2A) get an "Open in … →" deep link
 - **create-skill** — How to create skills for new patterns (area 3 in detail)
 - **storing-data** — Where to store the feature's data
 - **real-time-sync** — How the UI stays in sync when the agent writes data

package/dist/templates/workspace-core/.agents/skills/address-feedback/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   Triage feedback docs or pasted feedback into bugs to fix, UX suggestions to
   propose, unclear questions, and skipped noise; verify bugs, check Sentry when
   relevant, and keep UI changes minimal.
+metadata:
+  internal: true
 ---
 
 # Address Feedback

package/dist/templates/workspace-core/.agents/skills/authentication/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   How auth works in agent-native apps. Use when wiring login/signup,
   configuring auth modes, setting up organizations, protecting routes, or
   debugging session issues.
+metadata:
+  internal: true
 ---
 
 # Authentication
@@ -20,7 +22,7 @@ Auth is powered by **Better Auth** with account-first design. Every new user cre
 | **Production (default)**  | Better Auth with email/password + social providers (Google, GitHub). Organizations built in.                                             |
 | **`AUTH_MODE=local`**     | **Not** a browser auth bypass, and never returns `local@localhost`. It only affects CLI/agent identity: it lets `pnpm action` / the local agent loop auto-bind to the single real signed-in dev user from the `sessions` table (see `scripts/dev-session.ts`). Browser login is unchanged. |
 | **`AUTH_SKIP_EMAIL_VERIFICATION=1`** | QA/preview escape hatch for real email/password accounts. Signup skips email verification and does not send the signup verification email. Local dev/test skips verification by default; set `AUTH_SKIP_EMAIL_VERIFICATION=0` only when testing verification itself. Use `+qa` emails for test accounts. |
-| **`ACCESS_TOKEN` / `ACCESS_TOKENS`** | Simple token-based auth for production deployments.                                                                           |
+| **`ACCESS_TOKEN` / `ACCESS_TOKENS`** | Static bearer fallback for MCP/connect clients that cannot use OAuth. Not browser auth and never a token login page.         |
 | **`AUTH_DISABLED=true`**  | Skip auth entirely (for apps behind infrastructure-level auth like Cloudflare Access).                                                   |
 | **Custom**                | Pass your own `getSession` to `autoMountAuth(app, { getSession })`.                                                                     |
 
@@ -31,6 +33,22 @@ Auth is powered by **Better Auth** with account-first design. Every new user cre
 > When there is no session, **throw or return 401** — never substitute a
 > sentinel. Enforced by `scripts/guard-no-localhost-fallback.mjs`.
 
+## Remote MCP OAuth
+
+Every app's `/_agent-native/mcp` endpoint is also a standard protected MCP
+resource. OAuth-capable hosts connect with the remote MCP URL only, receive a
+`WWW-Authenticate` challenge, discover `/.well-known/oauth-protected-resource`
+and `/.well-known/oauth-authorization-server`, dynamically register a public
+client, and complete authorization-code + PKCE at
+`/_agent-native/mcp/oauth/authorize` / `/_agent-native/mcp/oauth/token`.
+Access tokens are audience-bound to the exact MCP URL and carry user/org
+identity plus `mcp:read`, `mcp:write`, and/or `mcp:apps`; refresh tokens are
+stored hashed and rotate. Keep `ACCESS_TOKEN` and `agent-native connect` for
+local stdio proxying and fallback clients. The CLI
+uses the OAuth-native URL-only entry for Claude Code/Claude Code CLI by
+default; use the Connect page or `agent-native connect --token <token>` when a
+client needs explicit bearer headers.
+
 ## Local → Real Account Migration
 
 Upgrading from `local@localhost` to a real account preserves SQL-backed workspace data. The built-in migration moves `application_state`, user-scoped `settings`, `oauth_tokens`, and any template table that uses `owner_email`.
@@ -39,9 +57,9 @@ Templates with legacy global settings can provide `POST /api/local-migration` fo
 
 ## Organizations
 
-Better Auth's organization plugin is built in. Every app supports creating orgs, inviting members, and role-based access (owner/admin/member).
+Organizations are **framework-managed**, not handled by Better Auth's organization plugin (which is intentionally NOT registered). Org data lives in the framework's own `organizations`, `org_members`, and `org_invitations` tables. Every app supports creating orgs, inviting members, and role-based access (owner/admin/member).
 
-The active org flows automatically: `session.orgId` → `AGENT_ORG_ID` → SQL scoping (see `security` skill).
+The active org flows automatically: `session.orgId` — resolved by `getOrgContext` from `org_members` plus the user's `active-org-id` setting (_not_ from a Better Auth session field) — → `AGENT_ORG_ID` → SQL scoping (see `security` skill).
 
 **If your template requires an org to function** (data is scoped by `organization_id`, core features can't run without one), set `AUTO_CREATE_DEFAULT_ORG=1` in your `.env`. The framework will auto-create a default org (named after the user) on first login when no memberships exist. This happens inside `getOrgContext` — no template integration needed.
 
@@ -55,13 +73,27 @@ Set `A2A_SECRET` (same value) on all apps that must verify each other's identity
 - Inbound calls are verified cryptographically
 - Without `A2A_SECRET`, A2A calls are unauthenticated (fine for local dev)
 
+## Cross-App SSO (Dispatch identity hub)
+
+Each hosted `*.agent-native.com` app has its **own user store**, so "sign in once" is identity federation, not a shared cookie. **Dispatch is the identity authority.**
+
+- **Opt-in per app via one env var:** set `AGENT_NATIVE_IDENTITY_HUB_URL=https://dispatch.agent-native.com` and the app shows a "Sign in with Agent-Native" option. **Unset = zero behavior change** — the whole path is dormant. Reversible at any time.
+- **Flow:** app → `GET <hub>/_agent-native/identity/authorize?app=&redirect_uri=&state=` → user logs in at Dispatch → 302 back with a short-lived (`≤5min`) `A2A_SECRET`-signed identity JWT (`sub`/`email`/`name`/`org_domain`/`scope:"identity"`). Strict `redirect_uri` allowlist (`*.agent-native.com` + localhost). App verifies the token, **JIT-links strictly by verified email** (existing same-email user → reused unchanged; new email → created), then mints a normal local session.
+- **Invariant (do not break):** identity rows are only ever **added** — never modified, renamed, or deleted. Enabling SSO logs users out, but they always log back into the **same email-matched account with data intact**. Email is the only thing that crosses the trust boundary; the app never trusts a user id, role, or org from the wire.
+- **Canary rollout:** deploy with the env unset everywhere (no-op) → set it on **one** app (mail) only → verify (logout → SSO → Dispatch → back to the same pre-existing account, data intact, direct logins still work) → expand app-by-app → rollback = unset the env on that app's deploy (instant, no data change).
+
+Full runbook + flow detail: [Cross-App SSO doc](/docs/cross-app-sso).
+
 ## Builder Browser Access
 
 Apps can connect to Builder via the `cli-auth` flow and persist shared browser credentials in `.env`. Agents then use the built-in `get-browser-connection` tool to provision a real browser session via AI Services.
 
 ## Protecting Custom Routes
 
-Actions are auto-protected. For custom `/api/` routes:
+Actions are auto-protected. Do not create custom `/api/` routes for normal
+CRUD, data queries, or action-backed operations; use `defineAction` and the
+auto-mounted action endpoint instead. If a route-only concern forces a custom
+route:
 
 ```ts
 import { getSession } from "@agent-native/core/server";
@@ -93,3 +125,4 @@ Bookmarked private paths already work without any plumbing — the framework's l
 
 - `security` — Data scoping, SQL injection, secrets
 - `actions` — Auto-protected by the auth guard
+- [Cross-App SSO doc](/docs/cross-app-sso) — Dispatch identity hub, federation flow, canary runbook

package/dist/templates/workspace-core/.agents/skills/automations/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   Event-triggered and schedule-triggered automations with natural-language
   conditions. Use when creating automations, wiring events, or understanding
   how triggers fire.
+metadata:
+  internal: true
 ---
 
 # Automations
@@ -42,7 +44,7 @@ event: calendar.booking.created
 condition: "attendee email ends with @example.com"
 mode: agentic
 domain: calendar
-createdBy: owner@example.com
+createdBy: user@example.com
 runAs: creator
 ---
 
@@ -109,7 +111,7 @@ emit("calendar.booking.created", {
   bookingId: "abc",
   attendeeEmail: "jane@co.com",
   startTime: "2025-01-15T10:00:00Z",
-}, { owner: "owner@example.com" });
+}, { owner: "user@example.com" });
 ```
 
 ### Built-in Events
@@ -134,7 +136,7 @@ emit("calendar.booking.created", {
 
 ## Condition Evaluator
 
-When an automation has a `condition`, the dispatcher calls Haiku (claude-haiku-4-5) to classify whether the event payload satisfies the condition. This is a yes/no classification, not a generation task.
+When an automation has a `condition`, the dispatcher calls the configured fast/classification model to classify whether the event payload satisfies the condition. This is a yes/no classification, not a generation task. The exact model ID lives in `condition-evaluator.ts`.
 
 - Empty or missing condition = unconditional (always fires).
 - Results are memoized (SHA-256 of condition + payload) with a 5-minute TTL and 500-entry LRU cache.
@@ -149,6 +151,9 @@ Automations use the `web-request` tool for outbound HTTP. It supports `${keys.NA
 - Each key can have a URL allowlist that restricts which origins the key can be sent to.
 - `resolveKeyReferences()` resolves placeholders, falling back from user scope to workspace scope.
 - `validateUrlAllowlist()` checks the resolved URL against per-key allowlists (origin-level matching).
+- Automation definitions, examples, event payloads, and prompts must not
+  hardcode real API keys, webhook URLs, tokens, private Builder/internal data, or
+  customer data. Use `${keys.NAME}` and synthetic `example.com` identities.
 
 ## UI
 
@@ -163,7 +168,7 @@ Agent flow:
 1. Calls `manage-automations` with `action=list-events` to find `calendar.booking.created`.
 2. Confirms the plan with the user.
 3. Calls `manage-automations` with `action=define`:
-   - `name`: `slack-on-builder-booking`
+   - `name`: `slack-on-example-booking`
    - `trigger_type`: `event`
    - `event`: `calendar.booking.created`
    - `condition`: `attendee email ends with @example.com`

package/dist/templates/workspace-core/.agents/skills/capture-learnings/SKILL.md

@@ -5,6 +5,8 @@ description: >-
   user gives feedback, shares preferences, corrects a mistake, or when you
   discover something worth remembering for future conversations.
 user-invocable: false
+metadata:
+  internal: true
 ---
 
 # Capture Learnings

package/dist/templates/workspace-core/.agents/skills/client-methods/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: client-methods
+description: >-
+  Client method surface rules. Use when wiring browser/client code to actions,
+  application state, framework routes, app APIs, uploads, auth, or settings.
+metadata:
+  internal: true
+---
+
+# Client Methods
+
+## Rule
+
+Browser/client code imports named methods, hooks, or client modules instead of
+hand-writing REST calls to framework or app routes.
+
+## Why
+
+Route shapes are transport details. If components and docs call
+`fetch("/_agent-native/...")` or template `/api/*` routes directly, every caller
+has to rediscover auth, base paths, request-source headers, JSON parsing, error
+handling, optimistic updates, sync invalidation, and route quirks. A named client
+method gives the UI, docs, and future agents one stable contract.
+
+## How
+
+1. Look for an existing client API first.
+
+   | Need | Use |
+   | --- | --- |
+   | App action reads/writes | `useActionQuery` / `useActionMutation` from `@agent-native/core/client` |
+   | Imperative action calls | `callAction` from `@agent-native/core/client` |
+   | Browser application state | `readClientAppState`, `writeClientAppState`, `setClientAppState`, `deleteClientAppState` |
+   | Navigation/app-state sync | `useAgentRouteState` / `useSemanticNavigationState` from `@agent-native/core/client` |
+   | Agent chat context | Agent chat client helpers from `@agent-native/core/client` |
+   | Ask the user a multiple-choice question from app code | `askUserQuestion` from `@agent-native/core/client` (renders inline in the agent panel; answer goes to the agent — do not build a custom modal) |
+   | Live sync | `useDbSync`, `useChangeVersion`, `useChangeVersions` |
+   | Extension iframe calls | `appAction`, `appFetch`, `extensionFetch` from the extension runtime |
+
+2. If no client API exists, add the narrowest helper at the boundary.
+
+   - Put shared framework helpers in `packages/core/src/client/*`.
+   - Put template-local helpers in `templates/<app>/app/hooks/*`,
+     `templates/<app>/app/lib/*`, or an existing local client module.
+   - Export reusable core helpers from `@agent-native/core/client`; add a leaf
+     export when callers may need to avoid the broad barrel.
+   - Keep raw `fetch`, `agentNativePath`, and route paths inside that helper,
+     not scattered through components or docs.
+   - Add focused tests for URL construction, headers, response parsing, error
+     shape, and any sync invalidation.
+
+3. Teach the helper, not the route.
+
+   Docs, skills, examples, and generated code should show:
+
+   ```ts
+   await setClientAppState("selection", selection, { keepalive: true });
+   ```
+
+   not:
+
+   ```ts
+   await fetch("/_agent-native/application-state/selection", {
+     method: "PUT",
+     body: JSON.stringify(selection),
+   });
+   ```
+
+## Exceptions
+
+Raw route calls are acceptable only inside low-level client helpers or for
+route-shaped protocols that cannot be hidden cleanly:
+
+- multipart uploads
+- streaming/SSE/WebSocket transports
+- OAuth redirects and callback URL construction
+- webhooks and external provider callbacks
+- extension sandbox `appFetch` / `extensionFetch`, which are themselves exposed
+  client methods
+- tests that assert route construction
+
+Even for exceptions, prefer a named helper as soon as more than one caller needs
+the behavior.
+
+## Don't
+
+- Don't put `fetch("/_agent-native/...")`, `fetch(agentNativePath(...))`, or
+  template `/api/*` calls directly in React components for normal app data,
+  actions, settings, or application state.
+- Don't document route calls as the way client code should do work.
+- Don't add pass-through `/api/*` routes just to make client fetches look
+  simpler; expose an action and call it with action hooks.
+- Don't duplicate auth/session/base-path/request-source/error parsing logic in
+  every component.
+
+## Related Skills
+
+- `actions` — app operations shared by UI and agent.
+- `context-awareness` — application-state navigation and selection helpers.
+- `real-time-sync` — keeping helper-backed UI reads fresh.
+- `server-plugins` — when a new route is actually warranted.
+
+## References
+
+- `references/legacy-client-fetch-audit-2026-06-03.md` — known legacy cleanup
+  targets found when this rule was added.

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

@@ -0,0 +1,53 @@
+# Legacy Client Fetch Audit (2026-06-03)
+
+These are known legacy client-side route calls found while adding the
+`client-methods` rule. Treat them as cleanup targets when editing the relevant
+area. Do not migrate them mechanically without reading the local action/data
+contracts; some need new actions or helper modules first.
+
+## Highest Priority
+
+- `templates/analytics/app/pages/analyses/AnalysesList.tsx`,
+  `templates/analytics/app/pages/analyses/AnalysisDetail.tsx`,
+  `templates/analytics/app/components/layout/Sidebar.tsx`, and
+  `templates/analytics/app/components/layout/CommandPalette.tsx` use `/api/*`
+  for normal app data. `list-analyses` and `get-analysis` already exist; add
+  action-backed hooks/helpers for dashboard, explorer, theme, and user-pref
+  routes.
+- `templates/slides/app/context/DeckContext.tsx` and
+  `templates/slides/app/pages/Presentation.tsx` use `/api/decks` for deck CRUD.
+  `list-decks` and `get-deck` already exist; add or expose UI-safe actions for
+  upsert/delete flows before migrating.
+- `templates/mail/app/hooks/use-emails.ts`,
+  `templates/mail/app/hooks/use-scheduled-jobs.ts`,
+  `templates/mail/app/hooks/use-automations.ts`, and
+  `templates/mail/app/pages/SettingsPage.tsx` still use `/api/*` for normal
+  email/settings/automation work. Reuse existing actions where possible and add
+  missing structured actions for aliases, scheduled jobs, and automation
+  settings.
+- `templates/calendar/app/hooks/use-events.ts` bypasses existing private event
+  actions for event CRUD. Prefer `get-event`, `update-event`, `delete-event`,
+  and `rsvp-event` through action hooks or `callAction`.
+
+## Medium Priority
+
+- Raw action endpoint calls remain in several client flows, including Gmail
+  filters, calendar people search, slides import, videos composition generation,
+  and design variant flow. Prefer hooks or `callAction`.
+- Template navigation hooks duplicate application-state fetch logic. Prefer
+  `setClientAppState`, `readClientAppState`, `deleteClientAppState`, or a shared
+  navigation-state helper.
+- Mail integration credentials are written through application state in
+  `templates/mail/app/hooks/use-integrations.ts` and `use-apollo.ts`; move
+  credential values to secrets/actions instead of browser-readable app-state.
+- Content comments and versions are partially migrated. Add missing actions such
+  as `resolve-comment`, `delete-comment`, `list-document-versions`, and
+  `restore-document-version`.
+
+## Acceptable Exceptions
+
+Uploads/file transfer, exports, public/anonymous pages, OAuth/auth redirects,
+webhooks/tracking endpoints, media/blob routes, collab text endpoints,
+framework setup/status routes, low-level core helper implementations, and the
+extension bridge `appFetch` / `extensionFetch` can be route-shaped protocols.
+Prefer named helpers when more than one caller needs the behavior.

package/dist/templates/workspace-core/.agents/skills/client-side-routing/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   How to add routes without remounting the app shell. Use when adding a new
   route, fixing agent sidebar reloads on navigation, or choosing between
   `root.tsx` layout and pathless `_app.tsx` layout patterns.
+metadata:
+  internal: true
 ---
 
 # Client-Side Routing