@agent-native/core 0.39.1 → 0.40.0

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

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

package/src/templates/default/.agents/skills/adding-a-feature/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: adding-a-feature
 description: >-
-  The four-area checklist every new feature in this app must complete. Use
-  when adding any feature, integration, or capability to keep the agent and
-  UI in parity.
+  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
@@ -14,59 +15,158 @@ Every new feature MUST update all four areas. Skipping any one breaks the agent-
 
 ## Why
 
-Agent-native apps are defined by parity: everything the UI can do, the agent can do, and vice versa. A feature that only has UI is invisible to the agent. A feature that only has actions is invisible to the user. A feature without app-state sync means the agent is blind to what the user is doing. And **a feature without auto-refresh wiring means the agent's writes are silently invisible until the user manually reloads** — that breaks the framework's #1 promise.
+Agent-native apps are defined by parity: everything the UI can do, the agent can do, and vice versa. A feature that only has UI is invisible to the agent. A feature that only has scripts is invisible to the user. A feature without app-state sync means the agent is blind to what the user is doing.
 
 ## The Checklist
 
-### 1. UI Component
+When you add a new feature, work through these four areas in order:
 
-Build the user-facing interface — a page, component, dialog, or route. Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for data fetching and mutations. You rarely need custom `/api/` routes.
+### 1. UI Component
 
-**Auto-refresh on agent writes is non-negotiable** — when the agent mutates the data this UI shows, the UI must reflect the change without a manual refresh. Two paths, pick the right one:
+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.
 
-- **`useActionQuery` (preferred)** — automatically covered. The framework's `useDbSync` invalidates `["action"]` on every change event, so every `useActionQuery` hook refetches when the agent runs an action. No extra wiring required.
+**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:
 
-- **Raw `useQuery` with a custom key** — needs explicit wiring. Fold `useChangeVersions([<source>, "action"])` from `@agent-native/core/client` into the `queryKey` and set `placeholderData: (prev) => prev`. The `"action"` source is the reliable signal — the agent runner emits it after every successful tool call. The resource-specific source (e.g. `"settings"`, `"app-state"`) is bonus. Without this wiring, agent writes will be invisible until manual refresh.
+- **`useActionQuery` / `useActionMutation`** — covered automatically. The framework's `useDbSync` invalidates `["action"]` on every change event, so every `useActionQuery` hook refetches on agent activity. No extra wiring required. **Prefer this path.**
+- **Raw `useQuery` with custom keys** — needs explicit wiring. Fold `useChangeVersions([<source>, "action"])` from `@agent-native/core/client` into the `queryKey` and set `placeholderData: (prev) => prev`. The `action` source is the reliable signal (the agent runner emits it after every successful tool call); the resource-specific source (`"dashboards"`, `"analyses"`, `"settings"`, etc.) is bonus when emitted. Without this wiring, agent writes will be invisible until manual refresh — that breaks the framework's #1 promise.
 
   ```tsx
   import { useChangeVersions } from "@agent-native/core/client";
   import { useQuery } from "@tanstack/react-query";
 
-  function useItem(id: string) {
-    const v = useChangeVersions(["items", "action"]);
-    return useQuery({
-      queryKey: ["item", id, v],
-      queryFn: () => fetchItem(id),
-      placeholderData: (prev) => prev, // no flicker on refetch
-    });
-  }
+  const v = useChangeVersions(["dashboards", "action"]);
+  useQuery({
+    queryKey: ["dashboard", id, v],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev, // no flicker on refetch
+  });
   ```
 
   See the `real-time-sync` skill for the full pattern and source catalog.
 
 ### 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` (the per-app guide) 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`.
+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.
 
+## Examples
+
+### Adding "compose email" to a mail app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | Compose panel with tabs, to/cc/bcc fields, body editor. Use `useActionQuery`/`useActionMutation` for data. |
+| Action          | `manage-draft` action (create/update/delete drafts), `send-email` action                 |
+| Skills/AGENTS   | Document compose state shape, draft lifecycle, action args in AGENTS.md                  |
+| App-state sync  | `compose-{id}` keys for each draft tab, `navigation` includes compose state              |
+
+### Adding "create form" to a forms app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | Form builder page with drag-and-drop fields, preview, settings. Use `useActionQuery` for lists. |
+| Action          | `create-form` action, `update-form` action, `list-forms` action (GET)                    |
+| Skills/AGENTS   | Document form schema shape, field types, validation rules in AGENTS.md                   |
+| App-state sync  | `navigation` includes `{ view: "form-builder", formId: "..." }`, `view-screen` fetches form data |
+
+### Adding "chart type" to an analytics app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | New chart component, chart type selector in dashboard                                    |
+| Action          | `create-chart` or `update-dashboard` action that sets chart type and config              |
+| Skills/AGENTS   | Document supported chart types, config options, data requirements                        |
+| App-state sync  | `navigation` includes selected chart/dashboard, `view-screen` returns chart config       |
+
+## Adding a new route
+
+Templates are single-page apps with client-side routing. The app shell (AgentSidebar + top-level nav) MUST persist across navigation — it is mounted once, either in `root.tsx` around `<Outlet />` or via a pathless `_app.tsx` layout route that all authed routes nest under.
+
+**Never wrap each new route in its own `<AppLayout>` / `<Layout>`.** That causes React to unmount the entire app shell on every navigation, reloading the agent sidebar and destroying in-progress work.
+
+- If the template has `<AppLayout>` in `root.tsx` — just render page content in your new route file, nothing else.
+- If the template has `app/routes/_app.tsx` (pathless layout) — name your new route `_app.<segment>.tsx` to inherit the shell, or bare `<segment>.tsx` for public routes that should NOT have the shell.
+- If a page needs per-route data (e.g. highlighting the active item in the sidebar), read it in the layout from `useParams()` / `useLocation()`. Don't pass it as a prop through every route file.
+
+See the "Client-Side Routing" section in the root `CLAUDE.md` for full details.
+
 ## Anti-Patterns
 
-- **UI without actions** — The user can create things but the agent cannot. Breaks parity.
-- **Actions without UI** — The agent can do something the user cannot. Less common but still breaks parity.
-- **Mutations without auto-refresh wiring** — The agent says "done!" but the screen doesn't change until the user hits reload. This is the most common silent regression. If you used `useActionQuery` you're covered; if you used raw `useQuery`, fold `useChangeVersions` into the key. Always test by asking the agent to mutate the data and watching the UI without refreshing.
+- **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, 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.
 
 ## Verification
 
-For every new feature, manually verify:
+After completing all four areas, verify:
 
 1. Can the user perform the operation from the UI?
-2. Can the agent perform the operation via an action (`pnpm action <name>`)?
-3. When the agent runs the action, **does the UI update within a second or two without a manual refresh**? If not, your query is missing `useActionQuery` or `useChangeVersions` wiring — go back to step 1.
-4. Does `view-screen` return the new feature's state when the user is on that page?
+2. Can the agent perform the same operation via actions?
+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
+
+If the feature stores **user-authored resources** (documents, dashboards, forms, decks, etc.), make them ownable so they get private-by-default semantics and a share dialog for free. See the `sharing` skill.
+
+TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSharesTable(...)`, call `registerShareableResource(...)`, wrap list/read queries with `accessFilter`, guard writes with `assertAccess`, and drop `<ShareButton>` in the resource header. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted framework-wide.
+
+## Related Skills
+
+- **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/src/templates/default/.agents/skills/capture-learnings/SKILL.md

@@ -1,50 +1,76 @@
 ---
 name: capture-learnings
 description: >-
-  Capture and apply accumulated knowledge in learnings.md. Use when the user
-  corrects a mistake, when debugging reveals unexpected behavior, or when an
-  architectural decision should be recorded for future reference.
+  Capture and apply accumulated knowledge via structured memory. Use when the
+  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
 
-This is background knowledge, not a slash command. Read `learnings.md` before starting significant work. Update it when you discover something worth remembering.
+This is background knowledge, not a slash command. **Your memory index is loaded at the start of every conversation.** Use `save-memory` proactively when you learn something worth remembering.
 
-## When to Capture
+## How to Read & Write Memories
 
-Use judgment, not rules. Capture when:
+Memories are stored as **resources** in the SQL database (personal scope), not as files on disk.
 
-- **Surprising behavior** — Something didn't work as expected and you figured out why
-- **Repeated friction** — You hit the same issue twice; write it down so there's no third time
-- **Architectural decisions** — Why something is done a certain way (the "why" isn't in the code)
-- **API/library quirks** — Undocumented behavior, version-specific gotchas
-- **Performance insights** — What's slow and what fixed it
+- **Save a memory:** `save-memory --name <name> --type <type> --description "..." --content "..."`
+- **Read a memory:** `resource-read --path memory/<name>.md`
+- **Delete a memory:** `delete-memory --name <name>`
+- **List all memories:** `resource-list --prefix memory/`
 
-Don't capture:
+## Memory Types
 
-- Things that are obvious from reading the code
-- Standard language/framework behavior
-- Temporary debugging notes
+| Type | Use for |
+|------|---------|
+| `user` | Preferences, role, personal context, contacts |
+| `feedback` | Corrections, confirmed approaches, things to avoid or repeat |
+| `project` | Ongoing work context, decisions, deadlines, status |
+| `reference` | Pointers to external systems, URLs, API details |
 
-## Format
+## When to Capture
 
-Add entries to `learnings.md` at the project root. Match the existing format — typically a heading per topic with a brief explanation:
+### User Preferences & Memory (`user`)
+- **Tone and style** — "I prefer casual tone", "don't use emojis", "keep replies short"
+- **Personal context** — contacts, relationships, habits ("my wife's email is...", "I'm in PST timezone")
+- **Workflow preferences** — "always CC my assistant", "I like to review before sending"
+- **Role and expertise** — "I'm a data scientist", "new to React"
+
+### Feedback & Corrections (`feedback`)
+- **Corrections** — user says "no, do it this way" → capture the right way
+- **Confirmed approaches** — user validates a non-obvious choice ("yes, that's perfect")
+- **Repeated friction** — you hit the same issue twice; save it
+
+### Project Context (`project`)
+- **Ongoing work** — who is doing what, why, by when
+- **Decisions** — why something is done a certain way
+- **Status** — current state of initiatives
+
+### References (`reference`)
+- **External systems** — "bugs are tracked in Linear project INGEST"
+- **URLs** — dashboards, documentation, tools
+- **API quirks** — undocumented behavior, version-specific gotchas
+
+### Don't Capture
+- Things obvious from reading the code
+- Standard language/framework behavior
+- Temporary debugging notes
+- Anything already in AGENTS.md or skills
+- Ephemeral task details (use tasks/plans instead)
 
-```markdown
-## [Topic]
+## Key Rules
 
-[What you learned and why it matters. Keep it to 2-3 sentences.]
-```
+1. **Save proactively — don't ask permission.** When you learn something, save it immediately.
+2. **One memory per topic** — e.g. `coding-style`, `project-alpha`, not one giant dump
+3. **Read before updating** — if a memory exists, read it first and merge, don't overwrite
+4. **Keep descriptions concise** — the index is loaded every conversation
+5. **Memories are SQL-backed** — safe for personal info, persist across sessions, not in git
 
 ## Graduation
 
-When a learning is referenced repeatedly, it's outgrowing `learnings.md`. Propose adding it to the relevant skill or creating a new skill via `create-skill`.
-
-- Updating `learnings.md` is a Tier 1 modification (data — auto-apply)
-- Updating a SKILL.md based on learnings is Tier 2 (source — verify after)
-
-## Related Skills
-
-- **self-modifying-code** — Learnings.md updates are Tier 1; skill updates are Tier 2
-- **create-skill** — When a learning graduates, create a skill from it
+When a memory is referenced repeatedly, it may belong in AGENTS.md or a skill:
+- Saving a memory is lightweight (auto-apply, personal scope)
+- Updating AGENTS.md or a skill is heavier (affects all users/agents)

package/src/templates/default/.agents/skills/create-skill/SKILL.md

@@ -4,6 +4,8 @@ description: >-
   How to create new skills for an agent-native app. Use when adding a new
   skill, documenting a pattern the agent should follow, or creating reusable
   guidance for the agent.
+metadata:
+  internal: true
 ---
 
 # Create a Skill
@@ -148,6 +150,32 @@ description: >-
 - Workflow/generator skills: verb-noun (`create-skill`, `capture-learnings`).
 - The directory name must match the `name` in frontmatter.
 
+## Skill Scope (runtime vs dev)
+
+An optional `scope` frontmatter field controls which agent loads the skill:
+
+- `both` (default when omitted) — loaded by the in-app runtime agent. Use for
+  any skill the runtime agent should follow.
+- `runtime` — loaded only by the in-app runtime agent.
+- `dev` — meant for the human's coding agent (e.g. Claude Code) only. **Excluded
+  from the runtime agent everywhere**: not in the system-prompt skills block and
+  not in `docs-search` results.
+
+```markdown
+---
+name: release-checklist
+description: >-
+  Steps for cutting a release. Use when preparing or publishing a new version.
+scope: dev
+---
+```
+
+Leave `scope` off for normal skills — the default (`both`) keeps them loading at
+runtime, so this is fully backward compatible. To make a dev-only skill visible
+to your coding agent but hidden from the runtime agent, mark it `scope: dev` and
+optionally mirror it under `.claude/skills/<name>/SKILL.md` (Claude Code reads
+`.claude/skills/` independently of the runtime's `.agents/skills/`).
+
 ## Tips
 
 - **Keep descriptions under 40 words** — they load into context on every