@agent-native/core 0.59.1 → 0.61.0

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

@@ -49,7 +49,7 @@ Use `defineAction` with a Zod schema (required for new actions):
 ```ts
 // actions/list-meals.ts
 import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { getDb } from "../server/db/index.js";
 import { meals } from "../server/db/schema.js";
 
@@ -352,7 +352,7 @@ This still works but is not auto-exposed as HTTP. Prefer `defineAction` for all
   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.
+- **Import action primitives from `@agent-native/core/action`** and CLI helpers such as `parseArgs()` from `@agent-native/core` — do not redefine framework 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
@@ -361,7 +361,7 @@ This still works but is not auto-exposed as HTTP. Prefer `defineAction` for all
 
 ```ts
 import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 
 export default defineAction({
   description: "List calendar events",
@@ -380,7 +380,7 @@ export default defineAction({
 
 ```ts
 import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 
 export default defineAction({
   description: "Log a meal",
@@ -400,7 +400,7 @@ export default defineAction({
 
 ```ts
 import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 
 export default defineAction({
   description: "Navigate the UI to a view",

package/dist/templates/default/.agents/skills/agent-native-docs/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: agent-native-docs
+description: >-
+  How to find version-matched Agent Native framework docs bundled in
+  node_modules. Use before implementing or answering questions about
+  @agent-native/core APIs, generated apps, workspaces, or advanced features.
+metadata:
+  internal: true
+---
+
+# Agent Native Docs Lookup
+
+## Rule
+
+Before implementing or explaining non-trivial Agent Native behavior, read the
+version-matched docs installed with `@agent-native/core`.
+
+## Why
+
+Generated apps and workspaces may be on a different framework version than the
+public docs or model memory. The installed package is the source that matches
+the app in front of you.
+
+## How
+
+From a generated app directory:
+
+```bash
+pnpm action docs-search --query "<feature>"
+pnpm action docs-search --slug <slug>
+pnpm action docs-search --list
+```
+
+The headless `pnpm agent` loop and built-in app agent also expose a read-only
+`docs-search` tool with the same `query`, `slug`, and `list` options.
+
+If the action runner is unavailable, search the package docs directly:
+
+```bash
+rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+```
+
+Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
+under `node_modules/@agent-native/core/docs/content/`.
+
+## Useful Slugs
+
+| Need | Slugs |
+| --- | --- |
+| Actions and typed client calls | `actions`, `client` |
+| SQL, auth, access, sharing | `database`, `authentication`, `security`, `sharing` |
+| UI state visible to the agent | `context-awareness` |
+| Headless and chat-first apps | `pure-agent-apps`, `agent-surfaces`, `using-your-agent` |
+| Automations and schedules | `automations`, `recurring-jobs` |
+| Cross-app and external agents | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions | `skills-guide`, `writing-agent-instructions` |
+
+## Don't
+
+- Do not rely on memory for framework APIs when package docs are present.
+- Do not add custom REST wrappers for app data before reading `actions`.
+- Do not add inline LLM calls before reading `using-your-agent` and
+  `agent-surfaces`.

package/dist/templates/default/AGENTS.md

@@ -1,6 +1,6 @@
 # {{APP_NAME}} — Agent Guide
 
-This app follows the agent-native core philosophy: the agent and UI are equal partners. Everything the UI can do, the agent can do via actions. The agent always knows what you're looking at via application state. See the root AGENTS.md for full framework documentation.
+This app follows the agent-native core philosophy: the agent and UI are equal partners. Everything the UI can do, the agent can do via actions. The agent always knows what you're looking at via application state. Use the framework docs lookup below for version-matched Agent Native documentation.
 
 This is an **@agent-native/core** application -- the AI agent and UI share state through a SQL database, with SSE for in-process live sync and polling as the cross-process/serverless fallback.
 
@@ -13,6 +13,26 @@ This is an **@agent-native/core** application -- the AI agent and UI share state
 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.
 
+## Framework Docs Lookup
+
+Version-matched Agent Native docs ship with `@agent-native/core` in
+`node_modules/@agent-native/core/docs`.
+
+- Use `pnpm action docs-search --query "<topic>"` to search framework docs,
+  bundled `AGENTS.md`, and codebase skills.
+- Use `pnpm action docs-search --slug <slug>` to read a full page. Start with
+  `actions`, `database`, `context-awareness`, `client`, `automations`,
+  `recurring-jobs`, `a2a-protocol`, `external-agents`, `mcp-protocol`,
+  `sharing`, `security`, `pure-agent-apps`, or `agent-surfaces`.
+- Use `pnpm action docs-search --list` to see everything available.
+- If the action runner is unavailable, read
+  `node_modules/@agent-native/core/docs/AGENTS.md` and search
+  `node_modules/@agent-native/core/docs/content/` directly with `rg`.
+
+Read these local package docs before implementing advanced Agent Native
+features. Prefer this app's own `AGENTS.md` and `.agents/skills/` for
+app-specific rules.
+
 ### Database Code
 
 - Define tables with `@agent-native/core/db/schema` helpers (`table`, `text`, `integer`, `real`, `now`, sharing helpers), never `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core`.
@@ -115,6 +135,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 
 | Skill                 | When to read                                                                      |
 | --------------------- | --------------------------------------------------------------------------------- |
+| `agent-native-docs`   | Before using advanced Agent Native framework APIs or generated-app features       |
 | `adding-a-feature`    | **Read first when adding ANY new feature** — the four-area parity checklist       |
 | `real-time-sync`      | Before wiring data fetching for anything the agent can mutate (must auto-refresh) |
 | `storing-data`        | Before storing or reading any app state                                           |

package/dist/templates/default/actions/hello.ts

@@ -1,4 +1,4 @@
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
 export default defineAction({

package/dist/templates/default/actions/navigate.ts

@@ -1,4 +1,4 @@
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { writeAppState } from "@agent-native/core/application-state";
 import { z } from "zod";
 

package/dist/templates/default/actions/view-screen.ts

@@ -1,4 +1,4 @@
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { readAppState } from "@agent-native/core/application-state";
 import { z } from "zod";
 

package/dist/templates/headless/.agents/skills/agent-native-docs/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: agent-native-docs
+description: >-
+  How to find version-matched Agent Native framework docs bundled in
+  node_modules. Use before implementing or answering questions about
+  @agent-native/core APIs, generated apps, workspaces, or advanced features.
+metadata:
+  internal: true
+---
+
+# Agent Native Docs Lookup
+
+## Rule
+
+Before implementing or explaining non-trivial Agent Native behavior, read the
+version-matched docs installed with `@agent-native/core`.
+
+## Why
+
+Generated apps and workspaces may be on a different framework version than the
+public docs or model memory. The installed package is the source that matches
+the app in front of you.
+
+## How
+
+From a generated app directory:
+
+```bash
+pnpm action docs-search --query "<feature>"
+pnpm action docs-search --slug <slug>
+pnpm action docs-search --list
+```
+
+The headless `pnpm agent` loop and built-in app agent also expose a read-only
+`docs-search` tool with the same `query`, `slug`, and `list` options.
+
+If the action runner is unavailable, search the package docs directly:
+
+```bash
+rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+```
+
+Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
+under `node_modules/@agent-native/core/docs/content/`.
+
+## Useful Slugs
+
+| Need | Slugs |
+| --- | --- |
+| Actions and typed client calls | `actions`, `client` |
+| SQL, auth, access, sharing | `database`, `authentication`, `security`, `sharing` |
+| UI state visible to the agent | `context-awareness` |
+| Headless and chat-first apps | `pure-agent-apps`, `agent-surfaces`, `using-your-agent` |
+| Automations and schedules | `automations`, `recurring-jobs` |
+| Cross-app and external agents | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions | `skills-guide`, `writing-agent-instructions` |
+
+## Don't
+
+- Do not rely on memory for framework APIs when package docs are present.
+- Do not add custom REST wrappers for app data before reading `actions`.
+- Do not add inline LLM calls before reading `using-your-agent` and
+  `agent-surfaces`.

package/dist/templates/headless/.env.example

@@ -0,0 +1,4 @@
+# Local development can use the SQLite fallback at data/app.db.
+# Set DATABASE_URL for a persistent hosted database.
+# DATABASE_URL=postgres://user:password@host:5432/database
+

package/dist/templates/headless/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "tabWidth": 2,
+  "useTabs": false,
+  "trailingComma": "all"
+}

package/dist/templates/headless/AGENTS.md

@@ -0,0 +1,58 @@
+# {{APP_NAME}} - Agent Guide
+
+This is a headless Agent Native app. It starts with actions instead of a browser UI, so the first useful primitive is callable from the agent, CLI, and action runtime.
+
+This app is not stateless. The Agent Native runtime uses SQL-backed stores for app state, settings, auth/session data, resources, and other framework capabilities when those surfaces are used. Local development can use SQLite at `data/app.db`; hosted or long-lived deployments should set `DATABASE_URL` to a persistent database.
+
+## Working In This App
+
+- Prefer actions in `actions/` for every app operation. Do not create REST wrappers around actions.
+- Keep action inputs validated with Zod and return structured data, not JSON strings.
+- Do not hardcode API keys, tokens, webhook URLs, private data, or credential-looking literals.
+- There is intentionally no `app/` UI shell in this scaffold. When you need a browser UI, use the Chat template as the UI on-ramp and keep `agent-native add` for integration blueprints.
+
+## Framework Docs Lookup
+
+Version-matched Agent Native docs ship with `@agent-native/core` in
+`node_modules/@agent-native/core/docs`.
+
+- Use `pnpm action docs-search --query "<topic>"` to search framework docs,
+  bundled `AGENTS.md`, and codebase skills.
+- Use `pnpm action docs-search --slug <slug>` to read a full page. Start with
+  `actions`, `pure-agent-apps`, `automations`, `recurring-jobs`,
+  `a2a-protocol`, `external-agents`, `mcp-protocol`, `database`, `sharing`,
+  and `security` for advanced headless workflows.
+- Use `pnpm action docs-search --list` to see everything available.
+- If the action runner is unavailable, read
+  `node_modules/@agent-native/core/docs/AGENTS.md` and search
+  `node_modules/@agent-native/core/docs/content/` directly with `rg`.
+
+Read these local package docs before implementing advanced Agent Native
+features. Prefer this app's own `AGENTS.md` for app-specific rules.
+
+## Actions
+
+| Action      | Args              | Purpose                 |
+| ----------- | ----------------- | ----------------------- |
+| `hello`     | `[--name <name>]` | Return a greeting       |
+| `db-schema` |                   | Show SQL schema         |
+| `db-query`  | `--sql "SELECT"`  | Run a scoped SELECT     |
+| `db-exec`   | `--sql "UPDATE"`  | Last-resort maintenance |
+
+Run actions from this app root:
+
+```bash
+pnpm action hello --name Builder
+```
+
+Run the app-agent loop against those actions:
+
+```bash
+pnpm agent "Call the hello action for Builder and explain the result"
+```
+
+## Skills
+
+Skills in `.agents/skills/` provide detailed guidance. Read
+`.agents/skills/agent-native-docs/SKILL.md` before using advanced Agent Native
+framework APIs, generated-app features, automations, A2A, sharing, or MCP.

package/dist/templates/headless/DEVELOPING.md

@@ -0,0 +1,22 @@
+# Developing {{APP_NAME}}
+
+Install dependencies, then run the hello action:
+
+```bash
+pnpm install
+pnpm action hello --name Builder
+```
+
+Then run the production app-agent loop against this folder:
+
+```bash
+pnpm agent "Call hello for Builder"
+```
+
+Useful checks:
+
+```bash
+pnpm typecheck
+```
+
+This scaffold intentionally has no `app/` directory, React Router config, Vite config, or dev server. Add those only when you are ready for a UI surface; the Chat template is the UI-first scaffold.

package/dist/templates/headless/_gitignore

@@ -0,0 +1,36 @@
+.agent-native/
+
+# Logs
+logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+node_modules
+dist
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Runtime data
+data/*.db
+data/*.db-shm
+data/*.db-wal
+data/uploads/
+data/settings.json
+data/.sessions.json
+

package/dist/templates/headless/actions/hello.ts

@@ -0,0 +1,14 @@
+import { defineAction } from "@agent-native/core/action";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Return a friendly greeting.",
+  schema: z.object({
+    name: z.string().default("world").describe("Name to greet"),
+  }),
+  http: { method: "GET" },
+  readOnly: true,
+  run: async ({ name }) => {
+    return { message: `Hello, ${name}!` };
+  },
+});

package/dist/templates/headless/actions/run.ts

@@ -0,0 +1,3 @@
+import { runScript } from "@agent-native/core/scripts";
+
+runScript();

package/dist/templates/headless/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "{{APP_NAME}}",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "action": "agent-native action",
+    "agent": "agent-native agent",
+    "script": "agent-native script",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@agent-native/core": "latest",
+    "postgres": "^3.4.9",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.2.1",
+    "prettier": "^3.6.2",
+    "tsx": "^4.20.3",
+    "typescript": "^6.0.3"
+  }
+}

package/dist/templates/headless/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "@agent-native/core/tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["node"]
+  },
+  "include": ["actions/**/*", "server/**/*", "shared/**/*"]
+}

package/dist/templates/ui-primitives-sync.spec.ts

@@ -70,8 +70,8 @@ const ALLOW_LIST: Array<[string, string, string]> = [
   // chart.tsx — analytics adds the useChartTooltipFlip hook (which only exists
   // in the analytics template's hooks/ dir) and uses `[_, config]` destructuring.
   // forms/mail have a shared variant without that hook and with `[, config]`.
-  // The canonical 8-template version (calendar/clips/design/macros/plan/slides/
-  // starter/videos) has neither analytics-specific hook nor forms/mail style.
+  // The canonical 8-template version (calendar/chat/clips/design/macros/plan/
+  // slides/videos) has neither analytics-specific hook nor forms/mail style.
   [
     "chart.tsx",
     "analytics",

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

@@ -49,7 +49,7 @@ Use `defineAction` with a Zod schema (required for new actions):
 ```ts
 // actions/list-meals.ts
 import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { getDb } from "../server/db/index.js";
 import { meals } from "../server/db/schema.js";
 
@@ -352,7 +352,7 @@ This still works but is not auto-exposed as HTTP. Prefer `defineAction` for all
   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.
+- **Import action primitives from `@agent-native/core/action`** and CLI helpers such as `parseArgs()` from `@agent-native/core` — do not redefine framework 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
@@ -361,7 +361,7 @@ This still works but is not auto-exposed as HTTP. Prefer `defineAction` for all
 
 ```ts
 import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 
 export default defineAction({
   description: "List calendar events",
@@ -380,7 +380,7 @@ export default defineAction({
 
 ```ts
 import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 
 export default defineAction({
   description: "Log a meal",
@@ -400,7 +400,7 @@ export default defineAction({
 
 ```ts
 import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 
 export default defineAction({
   description: "Navigate the UI to a view",

package/dist/templates/workspace-core/.agents/skills/agent-native-docs/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: agent-native-docs
+description: >-
+  How to find version-matched Agent Native framework docs bundled in
+  node_modules. Use before implementing or answering questions about
+  @agent-native/core APIs, generated apps, workspaces, or advanced features.
+metadata:
+  internal: true
+---
+
+# Agent Native Docs Lookup
+
+## Rule
+
+Before implementing or explaining non-trivial Agent Native behavior, read the
+version-matched docs installed with `@agent-native/core`.
+
+## Why
+
+Generated apps and workspaces may be on a different framework version than the
+public docs or model memory. The installed package is the source that matches
+the app in front of you.
+
+## How
+
+From a generated app directory:
+
+```bash
+pnpm action docs-search --query "<feature>"
+pnpm action docs-search --slug <slug>
+pnpm action docs-search --list
+```
+
+The headless `pnpm agent` loop and built-in app agent also expose a read-only
+`docs-search` tool with the same `query`, `slug`, and `list` options.
+
+If the action runner is unavailable, search the package docs directly:
+
+```bash
+rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+```
+
+Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
+under `node_modules/@agent-native/core/docs/content/`.
+
+## Useful Slugs
+
+| Need | Slugs |
+| --- | --- |
+| Actions and typed client calls | `actions`, `client` |
+| SQL, auth, access, sharing | `database`, `authentication`, `security`, `sharing` |
+| UI state visible to the agent | `context-awareness` |
+| Headless and chat-first apps | `pure-agent-apps`, `agent-surfaces`, `using-your-agent` |
+| Automations and schedules | `automations`, `recurring-jobs` |
+| Cross-app and external agents | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions | `skills-guide`, `writing-agent-instructions` |
+
+## Don't
+
+- Do not rely on memory for framework APIs when package docs are present.
+- Do not add custom REST wrappers for app data before reading `actions`.
+- Do not add inline LLM calls before reading `using-your-agent` and
+  `agent-surfaces`.

package/dist/templates/workspace-core/.agents/skills/composable-mini-apps/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: composable-mini-apps
+description: >-
+  Build many focused workspace apps that compose through agent discovery and
+  A2A. Use when designing headless mini-apps or cross-app workflows.
+---
+
+# Composable Mini-Apps
+
+## Rule
+
+Prefer many one-job apps in a workspace over one oversized app. A headless app
+can own a provider, dataset, workflow, or specialist action surface without a
+full UI; the main agent composes those apps through discovery and A2A.
+
+## Shape
+
+- Give each mini-app one clear job, a concise `package.json` description, and
+  action names that describe the job it owns.
+- Keep provider credentials and upstream API details in the app that owns that
+  provider or workflow. Other apps should delegate to it instead of copying its
+  integration code.
+- Use a tiny status/config screen only when users need to inspect state. A
+  pure headless app is fine when its job is invoked by agents, automations, or
+  sibling apps.
+- If two workflows only share a helper, put the helper in `packages/shared`;
+  keep the workflow actions in separate apps.
+
+## Discovery And Invocation
+
+The main agent should discover available siblings before assuming capability:
+
+- Runtime agents receive an `<available-apps>` block built from
+  `discoverAgents()`. Workspace siblings are layered in by
+  `discoverWorkspaceAgents()`.
+- UI shells, headless surfaces, and scripts can read the same registry through
+  `GET /_agent-native/agents?selfAppId=<app-id>`.
+- Code or CLI callers should use the first-class A2A invocation path
+  (`invokeAgent()` / `agent-native invoke`) when they need to call an app by
+  id, name, or URL.
+- In the agent loop, use `call-agent` with the sibling app id when another app
+  owns the work or data. Never call the current app through `call-agent`; use
+  local actions instead.
+
+Send narrow prompts to siblings: name the exact question, relevant ids, date
+ranges, and expected output shape. Preserve returned ids and URLs verbatim.
+
+## Provider APIs
+
+Provider-specific actions are shortcuts, not limits. When the upstream API can
+answer the question better than a first-class shortcut, call
+`provider-api-catalog` and `provider-api-docs` as needed, then
+`provider-api-request` against the real provider endpoint. For broad joins,
+searches, or absence claims, stage the bounded corpus with `stageAs` and reduce
+it with `query-staged-dataset` or code.
+
+When composing apps, make the provider-owning mini-app do those
+`provider-api-request` calls. The orchestrator should delegate a bounded job;
+it should not reimplement every provider endpoint locally.
+
+## Example
+
+For a sales-intelligence workspace, split the job into small apps:
+
+| App | Owns | Calls |
+| --- | --- | --- |
+| `hubspot-pipeline` | CRM deals, contacts, companies, associations | `provider-api-request` with provider `hubspot` |
+| `gong-evidence` | Calls, transcripts, snippets, speaker evidence | `provider-api-request` with provider `gong` |
+| `knowledge-base` | Internal docs, pricing rules, playbooks | local search/read actions |
+| `deal-brief` | Orchestration and final brief | `invokeAgent()` or `call-agent` to the three apps |
+
+Flow: `deal-brief` asks `hubspot-pipeline` for the target account and open
+deals, asks `gong-evidence` for recent transcript evidence about those deals,
+asks `knowledge-base` for relevant playbook guidance, then synthesizes the
+answer. That is a HubSpot→Gong→knowledge-base chain made of focused apps,
+not a single app that clones every provider integration.
+
+## Don't
+
+- Do not clone Mail, Calendar, Analytics, Brain, Assets, or another first-party
+  app just to reuse its data. Delegate or link to the existing app.
+- Do not hide a multi-provider workflow inside a giant "misc tools" app.
+- Do not add one-off provider endpoints when `provider-api-request` can express
+  the upstream API safely.
+- Do not create wrapper routes that only re-export another app's action or A2A
+  result.
+
+## Related Skills
+
+- **a2a-protocol** - How apps expose and call A2A endpoints.
+- **actions** - How each mini-app exposes its own operation surface.
+- **external-agents** - How external MCP hosts route through workspace apps.
+- **storing-data** - How app-owned data stays SQL-backed and portable.

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

@@ -111,7 +111,7 @@ row is written — status is derived from `hasOAuthTokens("google")`.
 
 ```ts
 import { z } from "zod";
-import { defineAction } from "@agent-native/core";
+import { defineAction } from "@agent-native/core/action";
 import { readAppSecret } from "@agent-native/core/secrets";
 import { getRequestUserEmail } from "@agent-native/core/server";