@agent-native/core 0.14.8 → 0.15.1

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

@@ -0,0 +1,41 @@
+---
+name: recurring-jobs
+description: >-
+  Scheduled tasks the agent runs on a cron schedule. Use when a user asks for
+  something recurring ("every morning", "daily", "weekly"), when creating or
+  updating jobs, or when debugging the job scheduler.
+---
+
+# Recurring Jobs
+
+## Rule
+
+Recurring jobs are scheduled tasks the agent executes automatically on a cron schedule. Jobs live as resource files under `jobs/` with YAML frontmatter for scheduling metadata.
+
+## How It Works
+
+1. User asks for something recurring via the agent chat
+2. Agent uses `manage-jobs` tool (action: "create") to write a job file at `jobs/<name>.md`
+3. A scheduler polls every 60 seconds, finds due jobs, and executes them via `runAgentLoop`
+4. Job results are saved as chat threads
+
+## Job Tool (built in)
+
+| Tool          | Action     | Purpose                                                    |
+| ------------- | ---------- | ---------------------------------------------------------- |
+| `manage-jobs` | `create`   | Create a recurring job (name, cron schedule, instructions) |
+| `manage-jobs` | `list`     | List all jobs and their status                             |
+| `manage-jobs` | `update`   | Update schedule, instructions, or toggle enabled           |
+
+## Key Files
+
+| File                                  | Purpose                                                  |
+| ------------------------------------- | -------------------------------------------------------- |
+| `packages/core/src/jobs/cron.ts`      | Cron parsing (`nextOccurrence`, `isValidCron`, `describeCron`) |
+| `packages/core/src/jobs/scheduler.ts` | Job execution engine (`processRecurringJobs`)            |
+| `packages/core/src/jobs/tools.ts`     | Agent tool (`manage-jobs` with create/list/update actions) |
+
+## Related Skills
+
+- `actions` — How tools and actions work
+- `delegate-to-agent` — How jobs invoke the agent loop

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

@@ -0,0 +1,239 @@
+---
+name: secrets
+description: >-
+  Declaratively register API keys and service credentials a template needs so
+  they appear in the agent sidebar settings UI and the onboarding checklist.
+  Use for any third-party API key (OpenAI, Stripe, Twilio, etc.) and for
+  surfacing OAuth connections in the unified settings UI.
+---
+
+# Secrets Registry
+
+## When to use
+
+Use this for any external credential your template needs: API keys, service
+tokens, webhook secrets. It gives you:
+
+- A sidebar UI entry for each credential (masked input, rotate, test, delete).
+- Automatic onboarding-checklist items for `required: true` secrets.
+- A stable server-side read API (`readAppSecret`) that decrypts values on
+  demand.
+- Validator hooks for health-checking keys before save and from a Test button.
+
+## When NOT to use
+
+- OAuth flows that need to run the full authorization code exchange — use
+  `@agent-native/core/oauth-tokens` directly to save/refresh tokens. The
+  registry can still surface the OAuth connection in the sidebar by
+  registering a secret with `kind: "oauth"` — that just delegates status
+  lookup to oauth-tokens and renders a Connect button, no `app_secrets` row
+  is written.
+- Purely process-level env vars that are never user-facing (e.g. `NODE_ENV`,
+  deployment flags). Those belong in the onboarding `form` method or the
+  `envKeys` list in `core-routes-plugin`.
+
+## Registering a secret
+
+```ts
+// server/plugins/register-secrets.ts
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { registerRequiredSecret } from "@agent-native/core/secrets";
+
+export default defineNitroPlugin(() => {
+  registerRequiredSecret({
+    key: "OPENAI_API_KEY",
+    label: "OpenAI API Key",
+    description: "Used for Whisper transcription of your recordings.",
+    docsUrl: "https://platform.openai.com/api-keys",
+    scope: "user",
+    kind: "api-key",
+    required: true,
+    validator: async (value) => {
+      const res = await fetch("https://api.openai.com/v1/models", {
+        headers: { Authorization: `Bearer ${value}` },
+      });
+      return res.ok
+        ? { ok: true }
+        : { ok: false, error: `OpenAI rejected the key (HTTP ${res.status})` };
+    },
+  });
+});
+```
+
+### OAuth in the unified UI
+
+```ts
+registerRequiredSecret({
+  key: "GOOGLE_CONNECTED",
+  label: "Google account",
+  description: "Grants access to Gmail / Calendar APIs.",
+  scope: "user",
+  kind: "oauth",
+  required: true,
+  oauthProvider: "google", // must match the provider id in oauth-tokens
+  oauthConnectUrl: "/_agent-native/google/auth-url",
+});
+```
+
+The sidebar shows a Connect button instead of a text input; no `app_secrets`
+row is written — status is derived from `hasOAuthTokens("google")`.
+
+## Registered options
+
+| Field              | Type                                    | Purpose                                                                  |
+| ------------------ | --------------------------------------- | ------------------------------------------------------------------------ |
+| `key`              | `string`                                | Env-var style name (`OPENAI_API_KEY`). Also the storage key.             |
+| `label`            | `string`                                | Human-readable title in the sidebar.                                     |
+| `description`      | `string?`                               | Subtitle under the label.                                                |
+| `docsUrl`          | `string?`                               | "Get key" link rendered on the card.                                     |
+| `scope`            | `"user" \| "workspace"`                 | Per-user or shared across the active org.                                |
+| `kind`             | `"api-key" \| "oauth"`                  | Drives UI and storage behavior.                                          |
+| `required`         | `boolean?`                              | When true, an onboarding step is auto-injected.                          |
+| `validator`        | `(v) => Promise<boolean \| {ok,error}>` | Runs on save and from the Test button. Never log `v`.                    |
+| `oauthProvider`    | `string?` (oauth-kind only)             | Provider id in `oauth-tokens` that backs this entry.                     |
+| `oauthConnectUrl`  | `string?` (oauth-kind only)             | URL the Connect button points at.                                        |
+
+## Reading a secret from an action
+
+```ts
+import { defineAction } from "@agent-native/core";
+import { readAppSecret } from "@agent-native/core/secrets";
+import { getSession } from "@agent-native/core/server";
+
+export default defineAction({
+  name: "transcribe-audio",
+  description: "Transcribe an audio file with Whisper",
+  input: { fileUrl: "string" },
+  handler: async ({ fileUrl }, ctx) => {
+    const session = await getSession(ctx.event);
+    if (!session?.email) throw new Error("Not signed in");
+
+    const stored = await readAppSecret({
+      key: "OPENAI_API_KEY",
+      scope: "user",
+      scopeId: session.email,
+    });
+    // Env var wins if set (useful for hosted deployments).
+    const apiKey = process.env.OPENAI_API_KEY ?? stored?.value;
+    if (!apiKey) {
+      throw new Error(
+        "OPENAI_API_KEY is not set. Configure it in the sidebar settings.",
+      );
+    }
+
+    // …call OpenAI. NEVER log the key or include it in error messages.
+  },
+});
+```
+
+Rules:
+
+- **Never log the value.** The read layer enforces this server-side; your
+  code must do the same.
+- **Check `process.env[key]` first.** Env vars win so ops teams can set keys
+  via deploy configuration without the user ever visiting the sidebar.
+- **Scope matches the registration.** `scope: "user"` → pass the user email.
+  `scope: "workspace"` → pass the active `orgId` from
+  `getOrgContext(event).orgId`.
+
+## HTTP routes
+
+Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
+
+- `GET /_agent-native/secrets` — list registered secrets with status (`set`
+  / `unset` / `invalid`), metadata, and — for set api-keys — the last 4
+  characters. Values are never returned.
+- `POST /_agent-native/secrets/:key` — body `{ value, scope?, scopeId? }`.
+  Runs the registered validator; returns 400 with the error on failure.
+- `DELETE /_agent-native/secrets/:key` — remove the stored value.
+- `POST /_agent-native/secrets/:key/test` — re-run the validator against the
+  currently stored value.
+
+## Storage & encryption
+
+- Values are stored in `app_secrets` (created on-demand; no migration
+  needed).
+- Encrypted at rest with AES-256-GCM. Key material is derived from
+  `SECRETS_ENCRYPTION_KEY` (preferred) or `BETTER_AUTH_SECRET` (fallback).
+  If neither is set, the framework uses a machine-local fallback and logs a
+  one-time warning — set `SECRETS_ENCRYPTION_KEY` in production.
+
+## Ad-hoc Keys
+
+Ad-hoc keys are user-created secrets that are not declared by the template.
+Users create them through the settings UI or the agent chat to use with
+automations and the `web-request` tool. They support `${keys.NAME}`
+substitution in outbound HTTP requests.
+
+### Ad-hoc API
+
+Core routes plugin mounts these under `/_agent-native/secrets/adhoc`:
+
+- `GET /_agent-native/secrets/adhoc` — list all ad-hoc keys (name, last 4
+  chars, URL allowlist). Values are never returned.
+- `POST /_agent-native/secrets/adhoc` — body `{ name, value, urlAllowlist? }`.
+  Creates or updates an ad-hoc key.
+- `DELETE /_agent-native/secrets/adhoc/:name` — remove an ad-hoc key.
+
+### URL Allowlists
+
+Each ad-hoc key can have a URL allowlist — an array of origin URLs that
+restrict where the key's value can be sent. The check is origin-level
+(scheme + host + port). If no allowlist is configured, the key can be used
+with any URL.
+
+```ts
+// Creating a key with an allowlist
+POST /_agent-native/secrets/adhoc
+{
+  "name": "SLACK_WEBHOOK",
+  "value": "https://hooks.slack.com/services/T00/B00/xxxx",
+  "urlAllowlist": ["https://hooks.slack.com"]
+}
+```
+
+### `${keys.NAME}` Substitution
+
+The `web-request` tool supports `${keys.NAME}` placeholders in the URL,
+headers, and body. Substitution happens server-side after the agent emits
+the tool call — the raw secret value never enters the agent's context.
+
+```ts
+import {
+  resolveKeyReferences,
+  validateUrlAllowlist,
+} from "@agent-native/core/secrets/substitution";
+
+// Resolve all ${keys.NAME} references in a string
+const { resolved, usedKeys } = await resolveKeyReferences(
+  "Bearer ${keys.API_TOKEN}",
+  "user",
+  "owner@example.com",
+);
+
+// Validate a URL against a key's allowlist
+const allowed = validateUrlAllowlist(
+  "https://hooks.slack.com/services/T00/B00/xxxx",
+  ["https://hooks.slack.com"],
+);
+```
+
+Key resolution falls back from user scope to workspace scope, so users can
+override shared keys without breaking automations that reference workspace
+defaults.
+
+### Key Files (ad-hoc)
+
+| File                                           | Purpose                                     |
+| ---------------------------------------------- | ------------------------------------------- |
+| `packages/core/src/secrets/substitution.ts`    | `resolveKeyReferences()`, `validateUrlAllowlist()` |
+| `packages/core/src/tools/fetch-tool.ts`        | `web-request` tool consuming key references |
+
+## Related skills
+
+- `onboarding` — the setup checklist that required secrets show up in.
+- `actions` — where you'll read secrets when calling third-party APIs.
+- `authentication` — session scoping; `scope: "user"` uses the session
+  email.
+- `security` — input validation and never logging secrets.
+- `automations` — ad-hoc keys power `${keys.NAME}` in automation web requests.

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

@@ -0,0 +1,191 @@
+---
+name: security
+description: >-
+  Secure coding practices for agent-native apps: input validation, SQL
+  injection, XSS, secrets, data scoping, and auth. Use when writing any action,
+  route, or component that touches user data or external input.
+---
+
+# Security
+
+## Rule
+
+Use the framework's security primitives everywhere. Never bypass them.
+
+## Input Validation
+
+Use `defineAction` with a Zod `schema:` for every action. The framework validates input automatically and returns clear 400 errors for HTTP callers and structured error results for agent tool calls.
+
+```ts
+export default defineAction({
+  schema: z.object({
+    email: z.string().email(),
+    role: z.enum(["admin", "member"]),
+    limit: z.coerce.number().int().min(1).max(100).default(25),
+  }),
+  run: async (args) => { /* args is fully typed and validated */ },
+});
+```
+
+The legacy `parameters:` field (plain JSON Schema) has no runtime validation — do not use it for new code.
+
+## SQL Injection
+
+Never concatenate user input into SQL strings. Use Drizzle ORM's query builder (always safe) or parameterized queries:
+
+```ts
+// Safe — Drizzle ORM
+await db.select().from(users).where(eq(users.email, args.email));
+
+// Safe — parameterized raw SQL
+await client.execute({ sql: "SELECT * FROM users WHERE id = ?", args: [id] });
+
+// NEVER do this
+await client.execute(`SELECT * FROM users WHERE id = '${id}'`);
+```
+
+## XSS
+
+- React auto-escapes JSX content — trust it.
+- Never use `dangerouslySetInnerHTML`, `innerHTML`, `eval()`, or `document.write()` with user-controlled content.
+- For rich text editing, use TipTap (framework dependency).
+- For rendering markdown, use `react-markdown`.
+
+## Secrets
+
+- OAuth tokens go in the `oauth_tokens` store via `saveOAuthTokens()`.
+- Never store secrets in `settings`, `application_state`, source code, or action responses sent to the client.
+
+## User Credentials Are Per-User Data — Never `process.env`
+
+User credentials (API keys, third-party tokens) are per-user (or per-org) data. They MUST live in SQL, scoped per-user (`u:<email>:credential:KEY`) or per-org (`o:<orgId>:credential:KEY`). Always read with the request context:
+
+```ts
+import { resolveCredential } from "@agent-native/core/credentials";
+const apiKey = await resolveCredential("OPENAI_API_KEY", { userEmail, orgId });
+```
+
+On 2026-04-29 the previous one-arg `resolveCredential(key)` form fell back to `process.env[key]` and an unscoped global `settings` row, so every signed-in user inherited the deployment's credentials. Two guards now block this in CI (`pnpm prep`):
+
+- `scripts/guard-no-env-credentials.mjs` — bans `process.env.<KEY>` reads in `packages/core/src/credentials/`, `secrets/`, `vault/`, and `templates/*/server/{lib,routes/api}/credential*` paths, except for an explicit allowlist of deploy-level vars (`DATABASE_URL`, `BETTER_AUTH_SECRET`, `NETLIFY_*`, etc.). Per-line opt-out: `// guard:allow-env-credential — <reason>`.
+- `scripts/guard-no-unscoped-credentials.mjs` — bans one-arg calls to `resolveCredential` / `hasCredential` / `saveCredential` / `deleteCredential`. Per-line opt-out: `// guard:allow-unscoped-credential — <reason>`.
+
+If a deploy-level value genuinely needs an env var (CI-set token, host secret), it's not a user credential — keep it out of the credentials/ secrets/ vault/ paths and the env-credentials guard won't see it.
+
+## Guards
+
+Two more CI guards (also wired into `pnpm prep`) target the 2026-04 cross-tenant leak class — request-state escaping into shared process state, and dev-mode sentinel identities used as production fallbacks.
+
+- `scripts/guard-no-env-mutation.mjs` — bans `process.env.<KEY> = …` (and bracket / compound forms) anywhere in production code. On serverless, every warm container handles many concurrent requests in one Node process, so `process.env` mutation leaks across in-flight requests (the "restore" line at the end of a handler races and never helps — most recently the Zoom webhook). Use `runWithRequestContext({ userEmail, orgId, timezone }, fn)` from `@agent-native/core/server` instead — it's AsyncLocalStorage-backed and per-request safe. Allowlisted paths: `scripts/`, `*.spec.ts` / `*.test.ts`, `packages/core/src/dev**`, `templates/*/test/`, anything under `/cli/` or `/scaffold/`. Per-line opt-out: `process.env.X = y // guard:allow-env-mutation — <reason>`.
+- `scripts/guard-no-localhost-fallback.mjs` — bans the literal `"local@localhost"` / `'local@localhost'` / `` `local@localhost` `` in production code. The bug class: `getRequestUserEmail() ?? "local@localhost"` silently pools every unauthenticated request into a single shared tenant, leaking credentials, tools, and `application_state` rows between accounts. The right behavior is to throw / 401 when there's no session. Allowlisted paths: the dev-mode auth shim (`packages/core/src/server/auth.ts`), `packages/core/src/dev**`, tests, `scripts/`, `seed/` / `seeds/`, plus a few framework helpers that intentionally inspect or migrate the dev identity. SQL DDL `DEFAULT 'local@localhost'` and the Drizzle helper `.default('local@localhost')` are skipped per-line — schema column defaults are intentional dev fixtures, not the dangerous fallback pattern. Per-line opt-out: `email ?? "local@localhost" // guard:allow-localhost-fallback — <reason>`.
+
+## Auth
+
+- All actions are protected by the auth guard automatically.
+- If you must create custom `/api/` routes, always call `getSession(event)` and reject requests without a session:
+
+```ts
+import { getSession } from "@agent-native/core/server";
+
+export default defineEventHandler(async (event) => {
+  const session = await getSession(event);
+  if (!session) throw createError({ statusCode: 401 });
+  // ...
+});
+```
+
+- Never create unprotected routes that modify data.
+
+## Custom HTTP Routes Must Apply Access Control Themselves
+
+This is the single most-failed rule in the codebase. Auto-mounted action routes (`/_agent-native/actions/...`) get a request context wired up automatically. **Hand-written `/api/*` Nitro routes do not.** If your handler queries an ownable resource (any table with `...ownableColumns()`), you MUST:
+
+1. Read the session: `const session = await getSession(event).catch(() => null)`.
+2. Run the work inside `runWithRequestContext({ userEmail: session?.email, orgId: session?.orgId }, fn)` from `@agent-native/core/server`.
+3. Inside `fn`, query through one of:
+   - `accessFilter(table, sharesTable)` in the WHERE clause for list/read-many.
+   - `resolveAccess("<type>", id)` for read-by-id (returns null if no access — return 404, not 403, so existence isn't leaked).
+   - `assertAccess("<type>", id, "viewer"|"editor"|"admin")` for write/delete-by-id.
+
+```ts
+// Bad — Brent's signup leaked every other user's decks because of this exact shape.
+export default defineEventHandler(async () => {
+  const db = getDb();
+  return db.select().from(schema.decks); // no access filter!
+});
+
+// Good
+import { getSession, runWithRequestContext } from "@agent-native/core/server";
+import { accessFilter } from "@agent-native/core/sharing";
+export default defineEventHandler(async (event) => {
+  const session = await getSession(event).catch(() => null);
+  return runWithRequestContext(
+    { userEmail: session?.email, orgId: session?.orgId },
+    async () => {
+      const db = getDb();
+      return db
+        .select()
+        .from(schema.decks)
+        .where(accessFilter(schema.decks, schema.deckShares));
+    },
+  );
+});
+```
+
+`scripts/guard-no-unscoped-queries.mjs` runs in `pnpm prep` and fails the build if any file in `templates/*/server/`, `templates/*/actions/`, or `packages/*/src/` queries an ownable table without one of the access helpers. Last-resort opt-out is the marker comment `// guard:allow-unscoped — <reason>` — only use it for cases like the sharing primitives themselves or share-token-public viewer endpoints, and always include a reviewer-readable reason.
+
+## Data Scoping
+
+In production, the framework automatically restricts all agent SQL queries to the current user's data using temporary views. This is enforced at the SQL level — the agent cannot bypass it.
+
+### Per-User Scoping (`owner_email`)
+
+Every template table with user data **must** have an `owner_email` text column:
+
+1. Framework detects `owner_email` via schema introspection
+2. Creates temp views `WHERE owner_email = <current user>` before each query
+3. Auto-injects `owner_email` into INSERT statements
+
+The current user is resolved from `AGENT_USER_EMAIL` (set automatically from the session).
+
+### Per-Org Scoping (`org_id`)
+
+For multi-org apps, tables also need `org_id`:
+
+1. `WHERE org_id = <current org>` is added (in addition to `owner_email` if present)
+2. `org_id` is auto-injected into INSERT statements
+
+Enable org scoping in the agent-chat plugin:
+
+```ts
+createAgentChatPlugin({
+  resolveOrgId: async (event) => {
+    const ctx = await getOrgContext(event);
+    return ctx.orgId;
+  },
+});
+```
+
+### Column Conventions
+
+| Column        | Purpose                 | Required                        |
+| ------------- | ----------------------- | ------------------------------- |
+| `owner_email` | Per-user data isolation | Yes, for all user-facing tables |
+| `org_id`      | Per-org data isolation  | Yes, for multi-org apps         |
+
+Run `pnpm action db-check-scoping` to verify. Use `--require-org` for multi-org apps.
+
+## Checklist
+
+- [ ] New action uses `defineAction` with a Zod `schema:`
+- [ ] No SQL string concatenation with user input
+- [ ] No `dangerouslySetInnerHTML` with user content
+- [ ] New env vars in `.env` only, not committed
+- [ ] New user-data tables have `owner_email` column
+- [ ] Custom routes call `getSession` and reject unauthenticated requests
+
+## Related Skills
+
+- `storing-data` — SQL patterns and the agent's db tools
+- `actions` — `defineAction` with Zod schema validation
+- `authentication` — Auth modes, sessions, and org context

package/dist/templates/workspace-core/.agents/skills/self-modifying-code/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: self-modifying-code
+description: >-
+  How the agent can modify the app's own source code. Use when the agent needs
+  to edit components, routes, styles, or scripts, when designing UI for agent
+  editability, or when deciding what the agent should and shouldn't modify.
+---
+
+# Self-Modifying Code
+
+## Rule
+
+The agent can edit the app's own source code — components, routes, styles, scripts. This is a feature, not a bug. Design your app expecting this.
+
+## Why
+
+An agent-native app isn't just an app the agent can _use_ — it's an app the agent can _change_. The agent can fix bugs, add features, adjust styles, and restructure code. This makes the agent a true collaborator, not just an operator.
+
+## Modification Taxonomy
+
+Not all modifications are equal. Use this to decide what level of care is needed:
+
+| Tier          | What                  | Examples                                         | After modifying                   |
+| ------------- | --------------------- | ------------------------------------------------ | --------------------------------- |
+| 1: Data       | Files in `data/`      | JSON state, generated content, markdown          | Nothing — these are routine       |
+| 2: Source     | App code              | Components, routes, styles, scripts              | Run `pnpm typecheck && pnpm lint` |
+| 3: Config     | Project config        | `package.json`, `tsconfig.json`, `vite.config.*` | Ask for explicit approval first   |
+| 4: Off limits | Secrets and framework | `.env`, `@agent-native/core` internals           | Never modify these                |
+
+## Git Checkpoint Pattern
+
+Before modifying source code (Tier 2+), create a rollback point:
+
+1. Commit or stash current state
+2. Make the edit
+3. Run `pnpm typecheck && pnpm lint`
+4. If verification fails → revert with `git checkout -- <file>`
+5. If verification passes → continue
+
+This ensures the agent can experiment without breaking the app.
+
+## Designing for Agent Editability
+
+Make your app easy for the agent to understand and modify:
+
+**Expose UI state via `data-*` attributes** so the agent knows what's selected:
+
+```ts
+const el = document.documentElement;
+el.dataset.currentView = view;
+el.dataset.selectedId = selectedItem?.id || "";
+```
+
+**Expose richer context via `window.__appState`** for complex state:
+
+```ts
+(window as any).__appState = {
+  selectedId: id,
+  currentLayout: layout,
+  itemCount: items.length,
+};
+```
+
+**Use configuration-driven rendering** — Extract visual decisions (colors, layouts, sizes) into JSON config files in `data/`. The agent can modify the config (Tier 1) instead of the component source (Tier 2).
+
+## Don't
+
+- Don't modify `.env` files or files containing secrets
+- Don't modify `@agent-native/core` package internals
+- Don't modify `.agents/skills/` or `AGENTS.md` unless explicitly requested
+- Don't skip the typecheck/lint step after editing source code
+- Don't make source changes without a git checkpoint to roll back to
+
+## Related Skills
+
+- **storing-data** — Tier 1 modifications (data files) are the safest and most common
+- **scripts** — The agent can create or modify scripts to add new capabilities
+- **delegate-to-agent** — Self-modification requests come through the agent chat
+- **real-time-sync** — Database writes trigger poll events to update the UI

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

@@ -0,0 +1,73 @@
+---
+name: server-plugins
+description: >-
+  Framework server plugins and the `/_agent-native/` route namespace. Use when
+  adding a custom server plugin, deciding whether to create an `/api/` route vs
+  an action, or debugging auto-mounted framework routes.
+---
+
+# Server Plugins & Framework Routes
+
+## Default Plugins (auto-mount)
+
+Five default plugins auto-mount when your app doesn't have a custom version in `server/plugins/`:
+
+| Plugin        | Default behavior                                  | Customize when                              |
+| ------------- | ------------------------------------------------- | ------------------------------------------- |
+| `agent-chat`  | Agent chat endpoints                              | Custom `mentionProviders` or `systemPrompt` |
+| `auth`        | Auth middleware                                   | Custom `publicPaths` or Google OAuth config |
+| `core-routes` | `/_agent-native/poll`, `/_agent-native/ping`, etc | Custom `envKeys` or `sseRoute`              |
+| `resources`   | Resource CRUD                                     | Rarely                                      |
+| `terminal`    | Terminal emulator                                 | Rarely                                      |
+
+**Only create plugin files for plugins you need to customize.** Let defaults auto-mount.
+
+## Framework Route Namespace: `/_agent-native/`
+
+All framework-level routes live under `/_agent-native/` to avoid collisions with template-specific `/api/*` routes.
+
+### Hard rule
+
+- **ALL framework routes go under `/_agent-native/`.**
+- Templates own `/api/*` for their domain routes.
+- Never put framework routes under `/api/`.
+- Never put template routes under `/_agent-native/` — that namespace is reserved.
+
+### Auto-mounted framework routes
+
+| Route                                                         | Purpose                                  |
+| ------------------------------------------------------------- | ---------------------------------------- |
+| `GET /_agent-native/poll`                                     | Polling endpoint for DB change detection |
+| `GET /_agent-native/events`                                   | SSE endpoint for real-time sync          |
+| `GET /_agent-native/ping`                                     | Health check                             |
+| `GET/PUT/DELETE /_agent-native/application-state/:key`        | Application state CRUD                   |
+| `GET/PUT/DELETE /_agent-native/application-state/compose/:id` | Compose draft CRUD                       |
+| `POST /_agent-native/agent-chat`                              | Agent chat SSE endpoint                  |
+| `GET /_agent-native/agent-chat/mentions`                      | Mention search for @-tagging             |
+| `GET /_agent-native/env-status`                               | Env key configuration status             |
+| `POST /_agent-native/env-vars`                                | Save env vars                            |
+| `/_agent-native/auth/*`                                       | Authentication (login, session, logout)  |
+| `/_agent-native/google/*`                                     | Google OAuth (callback, auth-url, etc.)  |
+| `/_agent-native/resources/*`                                  | Resource CRUD                            |
+| `/_agent-native/actions/:name`                                | Auto-mounted action endpoints            |
+| `/_agent-native/available-clis`                               | Available CLI tools                      |
+| `/_agent-native/agent-terminal-info`                          | Terminal connection info                 |
+| `/_agent-native/collab/*`                                     | Real-time collaboration (see `real-time-collab`) |
+| `/_agent-native/a2a`                                          | A2A JSON-RPC endpoint (see `a2a-protocol`) |
+
+## Actions-First Approach
+
+For standard CRUD and data operations, use `defineAction` in `actions/` — the framework auto-mounts them as HTTP endpoints at `/_agent-native/actions/:name`. Only create custom `/api/*` routes for things actions can't do:
+
+- File uploads with multipart form data
+- Streaming responses
+- Webhooks from external services
+- OAuth callbacks
+
+The Nitro Vite plugin handles both `/api/` and `/_agent-native/` prefixes via file-based routing in `server/routes/`.
+
+## Related Skills
+
+- `actions` — Prefer actions over custom `/api/` routes
+- `authentication` — Auth middleware and session handling
+- `portability` — Use H3 (not Express) for all routes