@agent-native/core 0.122.3 → 0.123.0

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

@@ -14,6 +14,8 @@ metadata:
 
 Every new feature MUST update all four areas. Skipping any one breaks the agent-native contract — the agent and UI must always be equal partners.
 
+Scope check first: this is the checklist for a feature that adds app data or a new capability. A restyle, a copy change, or a screen with no new data model and no new agent-visible operation only needs the areas it actually touches — do not manufacture actions, state keys, or a skill for it.
+
 ## 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 scripts is invisible to the user. A feature without app-state sync means the agent is blind to what the user is doing.

package/src/templates/default/.agents/skills/frontend-design/SKILL.md

@@ -1,14 +1,17 @@
 ---
 name: frontend-design
 description: >-
-  Create distinctive, production-grade frontend interfaces with high design
-  quality. Use when building web components, pages, artifacts, posters, or
-  applications (websites, landing pages, dashboards, React components,
-  HTML/CSS layouts, or when styling/beautifying any web UI). Generates
-  creative, polished UI that avoids generic AI aesthetics.
+  Sets the visual direction for a new or redesigned surface, with production
+  quality that avoids generic AI aesthetics. Use when building a new page,
+  app, or marketing surface, defining visual identity, or doing a design pass
+  ("make this look good"). Do not load it for routine UI edits: adding a field
+  to an existing form, fixing spacing, wiring a button, or changing copy.
 scope: dev
 license: Complete terms in LICENSE.txt
 source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
+local-changes: >-
+  Description narrowed and Verification rescoped deliberately; an upstream sync
+  must not restore the broad auto-load triggers or screenshot-everything step.
 metadata:
   internal: true
 ---
@@ -141,11 +144,22 @@ Avoid:
 
 ## Verification
 
+Match verification effort to the size of the change. For one component, one
+form, one page, or a restyle, run the app's existing checks — formatter,
+`pnpm typecheck`, existing tests — and stop there.
+
+Escalate to browser verification only when the user asks for it, or when the
+change is a multi-step user-visible flow that cannot be confirmed any other
+way. Never author a new Playwright/Puppeteer script, add a browser-automation
+dependency, or stand up an e2e harness to check work the user did not ask you
+to test that way; use an available browser tool, or say what you could not
+verify.
+
 For substantial frontend work:
 
 1. Run the relevant formatter/checks.
 2. Start the dev server when the app needs one.
-3. Verify with browser screenshots at desktop and mobile widths.
+3. Verify with the available browser tooling at desktop and mobile widths.
 4. Check interactive states: hover, focus, loading, empty, error, and destructive confirmations.
 5. When registering or changing a company adapter, run
    `@agent-native/toolkit/conformance`, including mixed-overlay focus,

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

@@ -127,6 +127,8 @@ Two more CI guards (also wired into `pnpm prep`) target the 2026-04 cross-tenant
 - `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>`.
 
+  The same guard also bans the **ambient process identity** as a request-scoped fallback: `?? process.env.AGENT_USER_EMAIL`, `|| process.env.WORKSPACE_OWNER_EMAIL`, and `?? getAmbientUserEmail()`. Those name the identity of the *deployment*, not the caller, so a handler reading one authorizes whoever the deploy env names rather than whoever signed in — it fails open toward more privilege. Exempt paths are the ones with no request by construction: `scripts/` (including `templates/*/scripts/`), `src/cli/`, `src/scripts/`, `script-helpers.ts` / `script-entries.ts`, tests, and seeds. It deliberately matches only the `??` / `||` fallback position, so reading the same env var to build an admin allowlist (`envEmails("WORKSPACE_OWNER_EMAIL").includes(email)`) is untouched. Known gaps, both requiring dataflow analysis the guard does not do: an env read aliased through a local (`const fallback = process.env.AGENT_USER_EMAIL; … ?? fallback`) and a destructured `const { AGENT_USER_EMAIL } = process.env`.
+
 ## Auth
 
 - All actions are protected by the auth guard automatically.

package/src/templates/default/.agents/skills/self-modifying-code/SKILL.md

@@ -1,9 +1,10 @@
 ---
 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.
+  Tiers, checkpoints, and off-limits paths for an agent editing the app's own
+  source. Use when designing UI for agent editability, deciding whether a file
+  is safe for the agent to change, or when tempted to patch config, `.env`, or
+  an `@agent-native/*` package. Do not load it for ordinary source edits.
 scope: dev
 metadata:
   internal: true

package/src/templates/default/.agents/skills/shadcn-ui/SKILL.md

@@ -1,11 +1,15 @@
 ---
 name: shadcn-ui
 description: >-
-  Use when adding, updating, debugging, styling, or composing shadcn/ui
-  components, forms, dialogs, menus, charts, sidebars, themes, registries, or
-  any project with a components.json file.
+  The shadcn CLI, component composition, theming, and registry workflow. Use
+  when adding, replacing, upgrading, or debugging a shadcn/ui primitive itself,
+  or when changing a theme or registry. Do not load it for ordinary edits to a
+  file that happens to import a shadcn component.
 scope: dev
 source: https://ui.shadcn.com/docs/skills
+local-changes: >-
+  Description narrowed deliberately; an upstream sync must not restore the
+  "any project with a components.json file" trigger.
 metadata:
   internal: true
 ---

package/src/templates/default/AGENTS.md

@@ -1,200 +1,73 @@
 # {{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. 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.
-
-### Core Principles
-
-1. **Shared SQL database** -- All app state lives in SQL. SQL stores structured records, metadata, references, and searchable text; large files/blob payloads must use file/blob storage and persist only URLs, ids, or handles. Never store large base64, `data:` URLs, images, videos, audio, PDFs, ZIPs, screenshots, thumbnails, or session replay chunks in SQL, `application_state`, `settings`, or `resources`. Local SQLite at `data/app.db` is the zero-setup dev fallback; local PGlite is available as a Postgres-dialect opt-in with `DATABASE_URL=pglite:./data/pglite` after installing `@electric-sql/pglite`. Deployed apps need a persistent `DATABASE_URL` so data survives container/serverless restarts. Turso is optional, not required: Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and Builder.io-managed environments are all valid when supported by the deploy. Core stores: `application_state`, `settings`, `oauth_tokens`, `sessions`, `resources`.
-2. **AI through the right framework surface** -- Product workflows delegate to the agent via `sendToAgentChat()` / `agentChat.submit()`. Use `sendToAgentChat({ message, context, submit })` for simple UI handoffs and prefill/review flows; add `newTab: true, background: true, openSidebar: false` when the agent should work silently without focusing the sidebar. Only use the agent-chat context state helpers (`useAgentChatContext`, `setAgentChatContextItem`, `listAgentChatContext`, `removeAgentChatContextItem`, `clearAgentChatContext`) when the UI needs two-way sync with staged context chips. For rare server-side text transforms that intentionally need no tools, chat history, or run state, use `completeText()` from `@agent-native/core/server` inside an action instead of importing provider SDKs directly.
-3. **Actions for app operations** -- `pnpm action <name>` dispatches to callable action files in `actions/`; `defineAction` also auto-exposes those operations at `/_agent-native/actions/:name` for the UI. Do not create custom REST routes that re-export actions.
-4. **Live sync keeps the UI current** -- Database writes stream over `/_agent-native/events` first, with `/_agent-native/poll` as the fallback. **When you (the agent) write data, the UI must reflect the change without a manual refresh.** This is non-negotiable. Use `useActionQuery` / `useActionMutation` for action-backed data (preferred). If you use raw `useQuery`, fold `useChangeVersions([<source>, "action"])` into the key for targeted refreshes. See the `real-time-sync` and `adding-a-feature` skills.
-5. **Agent can update code** -- The agent can modify this app's source code directly.
-6. **No hardcoded secrets or private data** -- Never put API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals in source, docs, tests, fixtures, prompts, screenshots, application state, action responses, or generated content. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
-
-## Framework Docs Lookup
-
-Version-matched Agent Native docs ship with `@agent-native/core` in
-`node_modules/@agent-native/core/docs`. A source-only corpus of core and
-first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
-
-- 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.
-- Use `pnpm action source-search --query "<pattern>"` when you need current
-  implementation examples or template best practices, and
-  `pnpm action source-search --path <path>` to read a specific corpus file.
-- 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`. Search
-  `node_modules/@agent-native/core/corpus/` for source examples.
-
-Before building common workspace or agent UI, read `agent-native-toolkit` to
-inventory existing public kits and installed package seams. When intentionally
-customizing shared UI, read `customizing-agent-native`.
-Use the supported ladder: configure → compose → eject the smallest unit →
-propose a shared seam. Preview `agent-native eject <unit>` before `--apply`,
-commit `agent-native.ejections.json`, and never edit `node_modules`, deep-import
-private source, or eject protected runtime auth, data, action, or agent-chat
-internals.
-
-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, then use the corpus for reusable framework/template
-patterns.
-To bring an older app current, run `pnpm upgrade:agent-native` or
-`npx @agent-native/core@latest upgrade` from the app root. That bumps
-`@agent-native/*` deps, installs, refreshes scaffold skills, and typechecks.
-Do **not** add `pnpm.overrides` / patches against `@agent-native/*` or edit
-`node_modules/@agent-native/*` when an upgrade fails — fix app code or ask.
-See the `upgrade-agent-native` and `self-modifying-code` skills.
-After a manual core bump only, `pnpm skills:update` (or
-`npx @agent-native/core@latest skills update scaffold --project`) still
-refreshes framework-provided `.agents/skills` and repairs `CLAUDE.md` /
-`.claude/skills` compatibility links.
-
-### 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`.
-- Use Drizzle's query builder (`db.select`, `db.insert`, `db.update`, `db.delete`) plus portable operators from `drizzle-orm` (`eq`, `and`, `or`, `inArray`, `desc`, etc.) for app reads and writes.
-- Keep raw SQL out of normal actions, handlers, and stores. Use it only for additive migrations, health checks, or last-resort maintenance, and keep it parameterized and dialect-agnostic.
-- Do not write SQLite-only or Postgres-only syntax in product code. The same app should run on SQLite, Postgres, libSQL/Turso, D1, and other supported Drizzle backends.
-
-### Authentication
-
-Auth is real Better Auth in every environment — there is **no dev bypass**:
-
-- **Development**: the same Better Auth flow as production. On first run the framework auto-creates a throwaway dev account and signs you in (so you are not stuck at a login wall). `getSession()` returns the signed-in user or `null` — it never returns a `local@localhost` sentinel.
-- **Production**: Better Auth with email/password + social providers; organizations built in.
-
-Use `getSession(event)` server-side and `useSession()` client-side. When there is no session, **throw or return 401** — never fall back to `local@localhost` (that pools every unauthenticated request into one shared tenant).
-
-## Resources
-
-Resources are persistent files for notes, learnings, and context. Text resources
-live in SQL; binary resource uploads require configured file storage and store
-only the hosted URL/reference in SQL.
-
-**At the start of every conversation, read these resources (workspace, shared, and personal scopes as relevant):**
-
-1. **`AGENTS.md`** -- inherited workspace defaults, app/team instructions, and user-specific context.
-2. **`LEARNINGS.md`** -- user preferences, corrections, and patterns. Read personal and shared scopes.
-
-**Update the shared `LEARNINGS.md` when you learn something important for the
-team.** Canonical destinations, request fields, metric definitions, routing
-conventions, and corrections learned in Slack belong there with concise source
-links. Shared scope resolves to the active organization. Personal preferences
-and user-specific context go through `save-memory` into `memory/MEMORY.md`.
-Built-in app chat agents use the `resources` tool with the `action` argument.
-External CLI agents can use the equivalent `pnpm action resource-*` commands.
-
-| Built-in agent tool call                                                | CLI equivalent                                                                         | Purpose                 |
-| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------- |
-| `resources` with `action: "read"`, `path`, optional `scope`             | `pnpm action resource-read --path <path> [--scope personal\|shared]`                   | Read a resource         |
-| `resources` with `action: "write"`, `path`, `content`, optional `scope` | `pnpm action resource-write --path <path> --content <text> [--scope personal\|shared]` | Write/update a resource |
-| `resources` with `action: "list"`, optional `prefix`/`scope`            | `pnpm action resource-list [--prefix <path>] [--scope personal\|shared\|all]`          | List resources          |
-| `resources` with `action: "delete"`, `path`, optional `scope`           | `pnpm action resource-delete --path <path> [--scope personal\|shared]`                 | Delete a resource       |
-
-## Application State
-
-Ephemeral UI state is stored in the SQL `application_state` table, accessed via `readAppState(key)` and `writeAppState(key, value)` from `@agent-native/core/application-state`.
-
-| State Key    | Purpose                                   | Direction                  |
-| ------------ | ----------------------------------------- | -------------------------- |
-| `navigation` | Current view                              | UI -> Agent (read-only)    |
-| `navigate`   | Navigate command (one-shot, auto-deleted) | Agent -> UI (auto-deleted) |
-
-The `navigation` key is written by the UI whenever the route changes. The `navigate` key is a one-shot command: the agent writes it, the UI reads and executes the navigation, then deletes it.
-
-UI code should use `useAgentRouteState` / `useSemanticNavigationState` from
-`@agent-native/core/client` for navigation sync instead of hand-written
-`fetch("/_agent-native/application-state/...")` calls. Keep shareable filters
-in URL query params; the framework exposes them as `<current-url>` and the
-built-in agent can update them with `set-search-params`.
-
-## Mounted Workspace Routing
-
-This app may be mounted under `/<app-id>` in a workspace. Inside app source, React Router paths are app-local: use `<Link to="/review">` and `navigate("/review")`, not `/<app-id>/review`. The workspace gateway and `APP_BASE_PATH` add the mounted prefix in the browser; hardcoding it inside React Router links causes doubled URLs such as `/<app-id>/<app-id>/review`.
-
-For raw paths outside React Router, use the core helpers: `appPath()` for static assets or normal hrefs, `appApiPath()` for legitimate route-only `/api/*` endpoints, and `agentNativePath()` for `/_agent-native/*`. Do not use `appApiPath()` to build action-backed CRUD wrappers.
-
-## Agent Operations
-
-**Always know what the user is currently viewing before you edit anything.** The user's view can change mid-conversation. Stale IDs lead to editing the wrong record.
-
-### If you are the built-in agent-chat agent
-
-A `<current-screen>` block is auto-injected into every user message with the current view, IDs, and selected item. You can trust it for the first action of a turn without calling `view-screen`. If the user says "this" or "now do X" after several tool calls, the user may have navigated — call `view-screen` again for a fresh snapshot.
-
-### If you are an external CLI agent (Claude Code, Codex, Cursor, etc.)
-
-You do NOT get auto-injected screen state. **Call `pnpm action view-screen` at the start of every task and before any edit** so you're acting on the IDs the user currently sees, not what was open earlier. Do not rely on cached context from previous turns.
-
-### Actions
-
-Use existing domain actions before reaching for SQL or custom routes. If a
-capability is missing, add or extend a `defineAction` so both the agent and UI
-share the same operation. Do not create `/api/*` routes that only call,
-repackage, or proxy an action.
-
-| Action           | Args                                                   | Purpose                                                   |
-| ---------------- | ------------------------------------------------------ | --------------------------------------------------------- |
-| `view-screen`    |                                                        | See current UI state                                      |
-| `navigate`       | `--view <name>` or `--path <url>`                      | Navigate the UI                                           |
-| `hello`          | `[--name <name>]`                                      | Example script                                            |
-| `db-schema`      |                                                        | Show all tables, columns, types                           |
-| `db-query`       | `--sql "SELECT ..."`                                   | Run a SELECT query                                        |
-| `list-mcp-tools` | `--serverId <id>`                                      | List connected MCP tools visible to the authenticated app |
-| `call-mcp-tool`  | `--serverId <id> --toolName <name> --arguments <json>` | Call a connected MCP tool through the scoped app API      |
-
-**For data changes, pick the right surface:**
-
-- Use domain actions first. They validate input, enforce access, and refresh the UI.
-- Use `db-query` / `db-schema` for read-only inspection.
-- Raw write SQL (`db-exec` / `db-patch`) is not part of the default agent surface. If this app explicitly opts into `databaseTools: "write"`, use those tools only for deliberate maintenance when no domain action exists.
-- **Database admin (dev only):** in development, `db-admin-query` / `db-admin-mutate` / `db-admin-rows` / `db-admin-tables` / `db-admin-schema` give **unscoped, full-database** access to ANY table — including framework tables and tables without `owner_email`/`org_id`. Prefer these over `db-exec`/`db-query` for database-admin work and for any non-owner-scoped table: `db-exec`/`db-query` auto-scope to the current user and return **0 rows** on unscoped tables. These mirror the in-app Database admin UI, so prompts and the UI do the same thing.
+This is an agent-native app: the UI and agent share SQL state and the same
+action surface. Use the app's existing patterns before adding new ones.
 
 ## Skills
 
-Skills in `.agents/skills/` provide detailed guidance for each architectural rule. Read them before making changes.
-
-| Skill                      | When to read                                                                      |
-| -------------------------- | --------------------------------------------------------------------------------- |
-| `agent-native-docs`        | Before using advanced Agent Native framework APIs or generated-app features       |
-| `agent-native-toolkit`     | Before building common workspace, chat, settings, navigation, or collaboration UI |
-| `customizing-agent-native` | Before configuring, composing, or ejecting shared Agent Native features           |
-| `adding-a-feature`         | **Read first when adding ANY new feature** — the four-area parity checklist       |
-| `feature-flags`            | Before shipping a staged production rollout or replacing a compile-time switch    |
-| `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                                           |
-| `internationalization`     | Before adding or editing visible UI copy, prompts, toasts, labels, or formatting  |
-| `delegate-to-agent`        | Before adding LLM calls or AI delegation                                          |
-| `actions`                  | Before creating or modifying actions                                              |
-| `self-modifying-code`      | Before editing source, components, or styles                                      |
-| `upgrade-agent-native`     | Before updating an older app/branch or when tempted to patch `@agent-native/*`    |
-| `capture-learnings`        | Before recording user preferences or corrections                                  |
-| `frontend-design`          | Before building or restyling any UI component, page, or layout                    |
-| `shadcn-ui`                | Before adding, updating, or debugging shadcn/ui components                        |
-| `agent-engines`            | Before switching LLM providers or registering a custom engine                     |
-| `notifications`            | Before surfacing alerts/progress to the user or adding channels                   |
-| `progress`                 | Before running any task that takes more than a few seconds                        |
-
-## When Adding Features
-
-**Read the `adding-a-feature` skill first** — it has the full four-area checklist (UI / Action / Skills / App-State). Quick summary:
-
-1. **Add navigation state entries** — extend `app/hooks/use-navigation-state.ts` to track new routes with `useAgentRouteState`
-2. **Enhance view-screen** — make the view-screen script return relevant context for the new view
-3. **Create domain actions** — add actions in `actions/` for CRUD operations on new data models; do not create REST wrappers around those actions
-4. **Wire UI for auto-refresh** — use `useActionQuery` / `useActionMutation` for normal CRUD. If a raw `useQuery` is unavoidable, fold `useChangeVersions([<source>, "action"])` into its key with `placeholderData`. When the agent mutates this data, the UI must reflect the change without a manual refresh. See `real-time-sync` skill.
-5. **Create domain skills** — add `.agents/skills/<feature>/SKILL.md` documenting the data model, storage patterns, and agent operations
-6. **Update this AGENTS.md** — add the new actions, state keys, and common tasks
-
----
-
-For code editing and development guidance, read `DEVELOPING.md`.
+Read the matching skill before implementation. Before building common workspace or agent UI, read `agent-native-toolkit` and `customizing-agent-native` for the
+configure → compose → eject ladder. Start with `actions` for app operations,
+`storing-data` for persistence, `real-time-sync` for live updates, and
+`security` for auth, access, and secrets. Use `adding-a-feature` for new
+cross-cutting work and `self-modifying-code` when changing app source.
+
+## Core rules
+
+- Store structured state in SQL through Drizzle; store large files in configured
+  file/blob storage and persist only URLs, ids, or opaque handles.
+- Normal app data must flow through actions.
+- Do not create `/api/*` routes that only call, repackage, or proxy an action.
+- Define app operations with `defineAction` in `actions/`. The agent and UI
+  call the same action surface; do not duplicate an action with a JSON route.
+- If you are about to add `server/routes/api/`, stop and write an action
+  instead, except for uploads, streaming, webhooks, OAuth callbacks, public
+  unauthenticated URLs, or non-JSON responses.
+- Keep database code provider-agnostic and migrations additive. Do not use
+  adapter-only database methods or production schema push commands.
+- All AI work goes through the agent chat. UIs do not call model providers.
+- Keep application state in SQL so the agent can read navigation, selection,
+  and focused-object context.
+- Never hardcode keys, tokens, webhook URLs, private data, or credential-like
+  literals. Use secrets, OAuth, or obvious placeholders.
+- A missing or unreadable value must stay distinguishable from success. Throw or
+  return an explicit error instead of silently falling back to an empty value.
+
+## Application state
+
+Use the existing `application_state` helpers for navigation and selection. Keep
+the shape small and explicit; include the current route/view and the selected
+object id when the UI has one.
+
+## Actions
+
+Actions in `actions/` are callable from the agent, UI hooks, HTTP, MCP, A2A,
+and CLI where enabled. Validate inputs with Zod, return structured data, and
+scope reads and writes to the signed-in user or organization. Prefer
+`useActionQuery` and `useActionMutation` in browser code.
+
+## Authentication and access
+
+Auth is real Better Auth in development and production. Use `getSession()` or
+the shared request context and fail closed when there is no session. Never use a
+sentinel identity such as `local@localhost`. Tables with ownable columns need
+scoped reads and writes through the framework access helpers.
+
+## UI and sync
+
+Use the shared toolkit and shadcn primitives for standard controls. Keep UI
+optimistic where safe, roll back failed mutations, and use `useDbSync()` or
+action query invalidation to reflect agent writes without a manual refresh.
+
+## Documentation lookup
+
+Version-matched docs and source examples ship with `@agent-native/core`. Use
+`pnpm action docs-search --query "<topic>"` and
+`pnpm action source-search --query "<pattern>"`; read the relevant local skill
+before relying on a framework API. Do not edit `node_modules` or deep-import
+private package internals.
+
+## Verification
+
+Match checks to the change: run the existing focused tests, typecheck, and
+formatter. For a user-facing template change, record a changelog entry from
+the app with `agent-native changelog add` when appropriate.

package/src/templates/default/app/entry.client.tsx

@@ -2,9 +2,12 @@
 // This keeps the ~650-700 KB gzip chat stack off the static import closure
 // of the client entry point so it can't block the first page parse.
 import { appBasePath } from "@agent-native/core/client/api-path";
+import { installRouteChunkRecovery } from "@agent-native/core/client/route-chunk-recovery";
 import { hydrateRoot } from "react-dom/client";
 import { HydratedRouter } from "react-router/dom";
 
+installRouteChunkRecovery();
+
 const basePath = appBasePath();
 const pathname = window.location.pathname;
 const routerBasePath =

package/src/templates/default/app/i18n/ar-SA.ts

@@ -472,6 +472,14 @@ const messages = {
     remove: "إزالة",
     save: "حفظ",
     loading: "جار التحميل...",
+    dangerZone: "منطقة الخطر",
+    deleteOrg: "حذف المنظمة",
+    deleteOrgDescription:
+      "يؤدي هذا إلى حذف هذه المنظمة وأعضائها ودعواتها المعلقة نهائيًا. ستصبح البيانات المملوكة للمنظمة غير قابلة للوصول. لا يمكن التراجع عن هذا الإجراء.",
+    deleteOrgConfirmPrompt: "اكتب {{name}} للتأكيد.",
+    deleteOrgConfirmPlaceholder: "اسم المنظمة",
+    deleteOrgConfirmCta: "حذف المنظمة",
+    deleteOrgPending: "جارٍ الحذف...",
   },
   integrations: {
     webhookUrl: "ويب هوك URL",

package/src/templates/default/app/i18n/de-DE.ts

@@ -455,6 +455,14 @@ const messages = {
     remove: "Entfernen",
     save: "Speichern",
     loading: "Wird geladen...",
+    dangerZone: "Gefahrenzone",
+    deleteOrg: "Organisation löschen",
+    deleteOrgDescription:
+      "Löscht diese Organisation, ihre Mitglieder und ausstehenden Einladungen dauerhaft. Daten der Organisation werden unzugänglich. Dies kann nicht rückgängig gemacht werden.",
+    deleteOrgConfirmPrompt: "Geben Sie {{name}} ein, um zu bestätigen.",
+    deleteOrgConfirmPlaceholder: "Name der Organisation",
+    deleteOrgConfirmCta: "Organisation löschen",
+    deleteOrgPending: "Wird gelöscht...",
   },
   integrations: {
     webhookUrl: "Webhook-URL",

package/src/templates/default/app/i18n/en-US.ts

@@ -446,6 +446,14 @@ const messages = {
     remove: "Remove",
     save: "Save",
     loading: "Loading...",
+    dangerZone: "Danger zone",
+    deleteOrg: "Delete organization",
+    deleteOrgDescription:
+      "Permanently deletes this organization, its members, and its pending invitations. Data owned by the organization becomes inaccessible. This cannot be undone.",
+    deleteOrgConfirmPrompt: "Type {{name}} to confirm.",
+    deleteOrgConfirmPlaceholder: "Organization name",
+    deleteOrgConfirmCta: "Delete organization",
+    deleteOrgPending: "Deleting…",
   },
   integrations: {
     webhookUrl: "Webhook URL",

package/src/templates/default/app/i18n/es-ES.ts

@@ -462,6 +462,14 @@ const messages = {
     remove: "Eliminar",
     save: "Guardar",
     loading: "Cargando...",
+    dangerZone: "Zona de peligro",
+    deleteOrg: "Eliminar organización",
+    deleteOrgDescription:
+      "Elimina permanentemente esta organización, sus miembros y sus invitaciones pendientes. Los datos de la organización dejarán de ser accesibles. Esta acción no se puede deshacer.",
+    deleteOrgConfirmPrompt: "Escribe {{name}} para confirmar.",
+    deleteOrgConfirmPlaceholder: "Nombre de la organización",
+    deleteOrgConfirmCta: "Eliminar organización",
+    deleteOrgPending: "Eliminando...",
   },
   integrations: {
     webhookUrl: "Gancho web URL",

package/src/templates/default/app/i18n/fr-FR.ts

@@ -461,6 +461,14 @@ const messages = {
     remove: "Retirer",
     save: "Enregistrer",
     loading: "Chargement...",
+    dangerZone: "Zone de danger",
+    deleteOrg: "Supprimer l'organisation",
+    deleteOrgDescription:
+      "Supprime définitivement cette organisation, ses membres et ses invitations en attente. Les données appartenant à l'organisation deviennent inaccessibles. Cette action est irréversible.",
+    deleteOrgConfirmPrompt: "Saisissez {{name}} pour confirmer.",
+    deleteOrgConfirmPlaceholder: "Nom de l'organisation",
+    deleteOrgConfirmCta: "Supprimer l'organisation",
+    deleteOrgPending: "Suppression...",
   },
   integrations: {
     webhookUrl: "URL du webhook",

package/src/templates/default/app/i18n/hi-IN.ts

@@ -441,6 +441,14 @@ const messages = {
     remove: "हटाएं",
     save: "सहेजें",
     loading: "लोड हो रहा है...",
+    dangerZone: "खतरे का क्षेत्र",
+    deleteOrg: "संगठन हटाएं",
+    deleteOrgDescription:
+      "यह इस संगठन, इसके सदस्यों और इसके लंबित निमंत्रणों को स्थायी रूप से हटा देता है। संगठन के स्वामित्व वाला डेटा दुर्गम हो जाएगा। इसे पूर्ववत नहीं किया जा सकता।",
+    deleteOrgConfirmPrompt: "पुष्टि के लिए {{name}} टाइप करें।",
+    deleteOrgConfirmPlaceholder: "संगठन का नाम",
+    deleteOrgConfirmCta: "संगठन हटाएं",
+    deleteOrgPending: "हटाया जा रहा है...",
   },
   integrations: {
     webhookUrl: "वेबहुक URL",

package/src/templates/default/app/i18n/ja-JP.ts

@@ -446,6 +446,14 @@ const messages = {
     remove: "削除",
     save: "保存",
     loading: "読み込み中...",
+    dangerZone: "危険区域",
+    deleteOrg: "組織を削除",
+    deleteOrgDescription:
+      "この組織、そのメンバー、および保留中の招待状を完全に削除します。組織が所有するデータにはアクセスできなくなります。この操作は元に戻せません。",
+    deleteOrgConfirmPrompt: "確認するには {{name}} と入力してください。",
+    deleteOrgConfirmPlaceholder: "組織名",
+    deleteOrgConfirmCta: "組織を削除",
+    deleteOrgPending: "削除中...",
   },
   integrations: {
     webhookUrl: "Webhook の URL",

package/src/templates/default/app/i18n/ko-KR.ts

@@ -438,6 +438,14 @@ const messages = {
     remove: "제거",
     save: "저장",
     loading: "로드 중...",
+    dangerZone: "위험 구역",
+    deleteOrg: "조직 삭제",
+    deleteOrgDescription:
+      "이 조직과 구성원, 대기 중인 초대를 영구적으로 삭제합니다. 조직이 소유한 데이터에 더 이상 액세스할 수 없습니다. 이 작업은 되돌릴 수 없습니다.",
+    deleteOrgConfirmPrompt: "확인하려면 {{name}}을(를) 입력하세요.",
+    deleteOrgConfirmPlaceholder: "조직 이름",
+    deleteOrgConfirmCta: "조직 삭제",
+    deleteOrgPending: "삭제 중...",
   },
   integrations: {
     webhookUrl: "웹훅 URL",

package/src/templates/default/app/i18n/pt-BR.ts

@@ -459,6 +459,14 @@ const messages = {
     remove: "Remover",
     save: "Salvar",
     loading: "Carregando...",
+    dangerZone: "Zona de perigo",
+    deleteOrg: "Excluir organização",
+    deleteOrgDescription:
+      "Exclui permanentemente esta organização, seus membros e seus convites pendentes. Os dados pertencentes à organização ficarão inacessíveis. Essa ação não pode ser desfeita.",
+    deleteOrgConfirmPrompt: "Digite {{name}} para confirmar.",
+    deleteOrgConfirmPlaceholder: "Nome da organização",
+    deleteOrgConfirmCta: "Excluir organização",
+    deleteOrgPending: "Excluindo...",
   },
   integrations: {
     webhookUrl: "URL do webhook",

package/src/templates/default/app/i18n/zh-CN.ts

@@ -426,6 +426,14 @@ const messages = {
     remove: "移除",
     save: "保存",
     loading: "正在加载...",
+    dangerZone: "危险区域",
+    deleteOrg: "删除组织",
+    deleteOrgDescription:
+      "永久删除此组织及其成员和待处理的邀请。组织拥有的数据将变得无法访问。此操作无法撤销。",
+    deleteOrgConfirmPrompt: "输入 {{name}} 以确认。",
+    deleteOrgConfirmPlaceholder: "组织名称",
+    deleteOrgConfirmCta: "删除组织",
+    deleteOrgPending: "正在删除...",
   },
   integrations: {
     webhookUrl: "查看：Webhook URL",

package/src/templates/default/app/i18n/zh-TW.ts

@@ -424,6 +424,14 @@ const messages = {
     remove: "移除",
     save: "儲存",
     loading: "正在載入...",
+    dangerZone: "危險區域",
+    deleteOrg: "刪除組織",
+    deleteOrgDescription:
+      "永久刪除此組織及其成員和待處理的邀請。組織擁有的資料將變得無法存取。此操作無法復原。",
+    deleteOrgConfirmPrompt: "輸入 {{name}} 以確認。",
+    deleteOrgConfirmPlaceholder: "組織名稱",
+    deleteOrgConfirmCta: "刪除組織",
+    deleteOrgPending: "正在刪除...",
   },
   integrations: {
     webhookUrl: "檢視：Webhook URL",

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

@@ -18,6 +18,8 @@ Actions in `actions/` are the **single source of truth** for app operations. The
 
 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.
 
+**Stop trigger:** the moment you are about to create a file under `server/routes/api/` — or add server middleware to guard one — stop and check it against the exception list in *When You Still Need Custom `/api/` Routes* below. If it is not on that list, write a `defineAction` instead. This applies even when you already started the route; abandoning a half-written action to hand-roll routes is the exact failure this rule exists to prevent.
+
 ## Why
 
 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.
@@ -390,12 +392,28 @@ This is the canonical approach for new apps. Action names must be lowercase with
 
 ## When You Still Need Custom `/api/` Routes
 
-Most operations should be actions. You only need custom routes in `server/routes/api/` for:
+This is the complete exception list. A route in `server/routes/api/` is only
+justified when the caller is not your own UI or agent, or when the payload is
+not JSON:
 
 - **File uploads** — actions receive JSON params, not multipart form data
 - **Streaming responses** — SSE or chunked responses that need direct H3 control
 - **Webhooks** — external services POST to a specific URL
 - **OAuth callbacks** — redirect-based flows that need specific URL patterns
+- **Public unauthenticated endpoints** — SEO/OG images, share links, and other
+  URLs opened directly by a browser or crawler
+- **Binary or non-JSON responses** — media, exports, generated assets
+
+Everything else is an action: CRUD, settings, search, list/detail reads, auth
+state, and anything the UI fetches as JSON. If a route needs new middleware to
+scope it to the current user, that is a signal it should be an action — actions
+already run inside request context with access checks.
+
+Existing first-party templates still contain a shrinking, explicitly
+grandfathered set of older `/api/*` CRUD routes for app data. The repository's
+`guard:no-action-twin-routes` CI check ratchets that baseline down across the
+first-party template route trees (with the separately owned Plan template
+fenced out); it is not a substitute for keeping generated apps action-first.
 
 When the agent needs a durable image or file URL, call the core `upload-image`
 action or use `uploadFile()` in server code. Do not write base64 into SQL,