@agent-native/core 0.5.0-dev.b51eaae → 0.6.1

package/src/templates/default/.agents/skills/agent-engines/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: agent-engines
+description: >-
+  How to inspect and configure the AI engine (model provider) powering the
+  agent. Use when the user asks to switch models, check which engine is active,
+  test a new provider, or register a custom engine.
+---
+
+# Agent Engines
+
+## Overview
+
+The framework supports pluggable AI engines beneath the agent loop. The **Anthropic engine** is the default and best-in-class path (Claude models). Additional engines can be added via the Vercel AI SDK (OpenAI, Google Gemini, Groq, Mistral, Cohere, Ollama).
+
+## Available Tools
+
+| Tool | Purpose |
+|---|---|
+| `list-agent-engines` | List all registered engines, their capabilities, and the current selection |
+| `set-agent-engine` | Set the active engine and model (persisted in settings) |
+| `test-agent-engine` | Send a trivial prompt to verify the engine works (connectivity + API key) |
+
+## Checking the Current Engine
+
+```
+list-agent-engines
+```
+
+Returns the registry of all engines (name, label, capabilities, supported models) plus the currently active engine and model.
+
+## Switching Engines
+
+```
+set-agent-engine --engine "ai-sdk:openai" --model "gpt-4o"
+```
+
+Changes take effect on the next conversation. The setting is persisted via the settings store (`agent-engine` key).
+
+Resolution order (highest priority first):
+1. Explicit `engine` option passed to `createAgentChatPlugin()` in the server plugin
+2. Settings store (`agent-engine` key)
+3. `AGENT_ENGINE` environment variable
+4. Default: `"anthropic"` (requires `ANTHROPIC_API_KEY`)
+
+## Testing a New Engine
+
+Before switching, verify the engine is working:
+
+```
+test-agent-engine --engine "ai-sdk:openai" --model "gpt-4o"
+```
+
+Returns `{ ok, latencyMs, response, capabilities }`. If `ok: false`, the error message explains what's wrong (missing API key, package not installed, etc.).
+
+## Built-in Engines
+
+| Engine Name | Provider | Requires |
+|---|---|---|
+| `anthropic` | Anthropic Claude SDK | `ANTHROPIC_API_KEY` |
+| `ai-sdk:anthropic` | Claude via Vercel AI SDK | `ANTHROPIC_API_KEY` |
+| `ai-sdk:openai` | OpenAI via Vercel AI SDK | `OPENAI_API_KEY` |
+| `ai-sdk:google` | Google Gemini via Vercel AI SDK | `GOOGLE_GENERATIVE_AI_API_KEY` |
+| `ai-sdk:groq` | Groq LPU via Vercel AI SDK | `GROQ_API_KEY` |
+| `ai-sdk:mistral` | Mistral via Vercel AI SDK | `MISTRAL_API_KEY` |
+| `ai-sdk:cohere` | Cohere via Vercel AI SDK | `COHERE_API_KEY` |
+| `ai-sdk:ollama` | Local Ollama via Vercel AI SDK | None (local) |
+
+## Engine Capabilities
+
+Each engine advertises its capabilities:
+
+| Capability | Anthropic | AI SDK: Anthropic | AI SDK: OpenAI | AI SDK: Google |
+|---|---|---|---|---|
+| `thinking` | ✓ | ✓ | ✗ | ✓ |
+| `promptCaching` | ✓ | ✓ | ✗ | ✗ |
+| `vision` | ✓ | ✓ | ✓ | ✓ |
+| `computerUse` | ✓ | ✗ | ✗ | ✗ |
+| `parallelToolCalls` | ✓ | ✓ | ✓ | ✓ |
+
+## Anthropic-Exclusive Features
+
+When using the `anthropic` engine (or `ai-sdk:anthropic`):
+
+- **Prompt caching** is applied automatically to the system prompt — cutting latency and cost on repeated turns.
+- **Extended thinking** can be enabled via `providerOptions.anthropic.thinking` — the agent reasons longer before responding.
+
+These features are silently ignored when a non-Anthropic engine is active (capability-gated, no breakage).
+
+## Registering a Custom Engine
+
+Register custom engines in a server plugin at startup:
+
+```ts
+// server/plugins/my-engine.ts
+import { registerAgentEngine } from "@agent-native/core/server";
+
+registerAgentEngine({
+  name: "my-engine",
+  label: "My Custom Engine",
+  description: "...",
+  capabilities: {
+    thinking: false,
+    promptCaching: false,
+    vision: false,
+    computerUse: false,
+    parallelToolCalls: true,
+  },
+  defaultModel: "my-model-v1",
+  supportedModels: ["my-model-v1", "my-model-v2"],
+  requiredEnvVars: ["MY_ENGINE_API_KEY"],
+  create: (config) => new MyEngine(config),
+});
+```
+
+After registering, the engine appears in `list-agent-engines` output and can be selected via `set-agent-engine`.
+
+## Env Vars Reference
+
+| Variable | Purpose |
+|---|---|
+| `ANTHROPIC_API_KEY` | Required for `anthropic` and `ai-sdk:anthropic` engines |
+| `OPENAI_API_KEY` | Required for `ai-sdk:openai` |
+| `GOOGLE_GENERATIVE_AI_API_KEY` | Required for `ai-sdk:google` |
+| `GROQ_API_KEY` | Required for `ai-sdk:groq` |
+| `MISTRAL_API_KEY` | Required for `ai-sdk:mistral` |
+| `COHERE_API_KEY` | Required for `ai-sdk:cohere` |
+| `AGENT_ENGINE` | Default engine name (overridden by settings store) |

package/src/templates/default/.agents/skills/real-time-collab/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: real-time-collab
+description: >-
+  How to enable multi-user collaborative editing with Yjs CRDT, TipTap
+  Collaboration extension, live cursors, and agent-driven edits.
+---
+
+# Real-Time Collaboration
+
+The framework provides a Yjs-based collaborative editing system in `@agent-native/core/collab`. Multiple users can edit the same document simultaneously with live cursor positions, and the AI agent can make surgical edits that appear in real-time.
+
+## Architecture
+
+```
+User A (TipTap + Collaboration ext)  ←→  Y.XmlFragment  ←→  Server (_collab_docs table)
+User B (TipTap + Collaboration ext)  ←→  Y.XmlFragment  ←→       ↑
+Agent (edit-document action)         ←→  search-replace endpoint ─┘
+```
+
+- **Yjs Y.Doc** stores the document as a `Y.XmlFragment` (ProseMirror node tree)
+- **TipTap's Collaboration extension** binds the editor to the Y.XmlFragment via `ySyncPlugin`
+- **CollaborationCaret extension** renders remote users' cursors with names and colors
+- **Polling** (every 2s) syncs Y.Doc updates and awareness state between clients and server
+- **SQL `_collab_docs` table** persists Yjs state (base64-encoded binary)
+
+## Enabling Collaboration in a Template
+
+### 1. Install dependencies
+
+```bash
+pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap --filter your-template
+```
+
+### 2. Add Vite optimizeDeps
+
+In `vite.config.ts`:
+```ts
+export default defineConfig({
+  plugins: [reactRouter()],
+  optimizeDeps: {
+    include: [
+      "yjs",
+      "y-protocols/awareness",
+      "@tiptap/extension-collaboration",
+      "@tiptap/extension-collaboration-caret",
+      "@tiptap/y-tiptap",
+    ],
+  },
+});
+```
+
+This prevents Vite from re-bundling TipTap in incompatible ways during dev.
+
+### 3. Add the collab server plugin
+
+Create `server/plugins/collab.ts`:
+```ts
+import { createCollabPlugin } from "@agent-native/core/server";
+export default createCollabPlugin({
+  table: "your_table",
+  contentColumn: "content",
+  idColumn: "id",
+  autoSeed: false, // Client-side seeding on first load
+});
+```
+
+This mounts routes under `/_agent-native/collab/`:
+- `GET /:docId/state` — fetch Y.Doc state
+- `POST /:docId/update` — apply client update
+- `POST /:docId/text` — apply full text (diff-based)
+- `POST /:docId/search-replace` — surgical text find/replace in Y.XmlFragment
+- `POST /:docId/awareness` — sync cursor/presence state
+
+### 4. Use the `useCollaborativeDoc` hook
+
+```ts
+import { useCollaborativeDoc, generateTabId } from "@agent-native/core/client";
+
+const TAB_ID = generateTabId();
+
+const { ydoc, awareness, isLoading, activeUsers } = useCollaborativeDoc({
+  docId: documentId,
+  requestSource: TAB_ID,
+  user: { name: "Steve", email: "steve@example.com", color: "#60a5fa" },
+});
+```
+
+The hook:
+- Creates a stable `Y.Doc` per docId (never changes identity)
+- Fetches server state and applies it
+- Sends local updates to server
+- Polls for remote updates (every 2s)
+- Tracks active users via awareness
+
+### 5. Add Collaboration extension to TipTap
+
+```ts
+import Collaboration from "@tiptap/extension-collaboration";
+import CollaborationCaret from "@tiptap/extension-collaboration-caret";
+import { Awareness } from "y-protocols/awareness";
+
+// Create awareness locally (must use same y-protocols as the caret extension)
+const awareness = new Awareness(ydoc);
+awareness.setLocalStateField("user", { name, color });
+
+const editor = useEditor({
+  extensions: [
+    StarterKit.configure({ history: false }), // Disable history — Yjs handles undo
+    Collaboration.configure({ document: ydoc }),
+    CollaborationCaret.configure({
+      provider: { awareness },
+      user: { name, color },
+    }),
+    // ... other extensions
+  ],
+  content: initialContent, // Seeds Y.XmlFragment on first load
+});
+```
+
+**Important:** Disable `history` in StarterKit when using Collaboration — Yjs handles undo/redo.
+
+### 6. Seed the Y.XmlFragment
+
+The Collaboration extension does NOT auto-seed from the `content` prop. You must seed manually:
+
+```ts
+useEffect(() => {
+  if (!editor || !ydoc || !content) return;
+  const fragment = ydoc.getXmlFragment("default");
+  if (fragment.length === 0) {
+    editor.commands.setContent(parseContent(content));
+  }
+}, [editor, ydoc, content]);
+```
+
+**Critical:** Guard against saving empty content back to SQL when the editor is in collab mode but hasn't been seeded yet:
+
+```ts
+onUpdate: ({ editor }) => {
+  const md = editor.storage.markdown.getMarkdown();
+  if (!md.trim() && ydoc) return; // Don't save empty during seeding
+  onChange(md);
+}
+```
+
+## Agent Edits via `edit-document`
+
+The `edit-document` action uses search-and-replace:
+```bash
+pnpm action edit-document --id <docId> --find "old text" --replace "new text"
+```
+
+When collab state exists, the action calls the server's `search-replace` endpoint which:
+1. Walks the Y.XmlFragment tree
+2. Finds the text in Y.XmlText nodes
+3. Applies minimal delete/insert operations
+4. Emits a Yjs update via the poll system
+5. Client receives the update → ySyncPlugin applies a targeted ProseMirror transaction → cursor preserved
+
+**Important:** Actions run in a separate process, so they must use the HTTP endpoint (not the collab module directly) to emit updates to the server's poll system.
+
+## Key Modules
+
+| Module | Path | Purpose |
+|--------|------|---------|
+| `@agent-native/core/collab` | `packages/core/src/collab/` | Server-side Yjs management |
+| `useCollaborativeDoc` | `packages/core/src/collab/client.ts` | Client hook |
+| `createCollabPlugin` | `packages/core/src/server/collab-plugin.ts` | Route mounting |
+| `searchAndReplace` | `packages/core/src/collab/ydoc-manager.ts` | Y.XmlFragment text mutation |
+
+## Common Pitfalls
+
+1. **TipTap version mismatch** — All `@tiptap/*` packages must be the same version. The Collaboration extension requires `editor.utils` which was added in v3.22.2.
+
+2. **Empty editor on first load** — The Collaboration extension uses Y.XmlFragment as the source of truth. If the fragment is empty, the editor shows empty. Seed manually (see above).
+
+3. **Data loss from empty saves** — The `onUpdate` handler fires when the editor initializes with an empty Y.XmlFragment. If this empty content is saved to SQL, it overwrites the real content. Always guard against saving empty content in collab mode.
+
+4. **Stale content on document switch** — Use `key={documentId}` on the editor component to force a full remount when switching documents. This ensures the Y.Doc, seeding, and editor state are all fresh.
+
+5. **Separate process for actions** — Actions run via `pnpm action` in a new Node.js process. The in-memory EventEmitter in the action process doesn't reach the dev server's poll system. Use HTTP endpoints for collab operations from actions.
+
+6. **Vite dep optimization** — Adding Yjs-related packages to a template changes Vite's dependency bundling, which can break TipTap's React integration. Always add them to `optimizeDeps.include`.

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

@@ -0,0 +1,108 @@
+---
+name: security
+description: >-
+  Data security model, user/org scoping, and auth patterns. Use when adding
+  tables with user data, implementing multi-user features, setting up A2A
+  cross-app calls, or reviewing data access patterns.
+---
+
+# Security & Data Scoping
+
+## How Data Isolation Works
+
+In production, the framework enforces data isolation at the SQL level. Agents and users can only see and modify data they own. This is automatic — you don't write WHERE clauses yourself.
+
+### Per-User Scoping (`owner_email`)
+
+Every table with user-specific data **must** have an `owner_email` text column.
+
+```ts
+import { table, text, integer } from "@agent-native/core/db/schema";
+
+export const notes = table("notes", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  content: text("content"),
+  owner_email: text("owner_email").notNull(), // REQUIRED for user data
+});
+```
+
+**What happens automatically:**
+- `db-query` creates temporary views with `WHERE owner_email = <current user>`
+- `db-exec` INSERT statements get `owner_email` auto-injected
+- `db-exec` UPDATE/DELETE statements are scoped to the current user's rows
+- The current user comes from `AGENT_USER_EMAIL` (set from the auth session)
+
+### Per-Org Scoping (`org_id`)
+
+For multi-user apps where teams share data, add an `org_id` column:
+
+```ts
+export const projects = table("projects", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  owner_email: text("owner_email").notNull(), // who created it
+  org_id: text("org_id").notNull(),           // which org it belongs to
+});
+```
+
+When both columns are present, queries are scoped by **both**: `WHERE owner_email = ? AND org_id = ?`.
+
+The `org_id` comes from `AGENT_ORG_ID` which is automatically set from the user's active organization in Better Auth.
+
+### Validation
+
+Run `pnpm action db-check-scoping` to verify all tables have proper ownership columns. Use `--require-org` for multi-org apps.
+
+## Auth Model
+
+### Better Auth (Default)
+
+The framework uses Better Auth for authentication. It's always on by default — users create an account on first visit.
+
+**Environment variables:**
+- `BETTER_AUTH_SECRET` — signing key (auto-generated if not set)
+- `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` — enable Google OAuth
+- `GITHUB_CLIENT_ID` + `GITHUB_CLIENT_SECRET` — enable GitHub OAuth
+- `AUTH_MODE=local` — disable auth for solo local dev (escape hatch)
+
+### Organizations
+
+Better Auth's organization plugin is built-in. Every app supports:
+- Creating organizations
+- Inviting members (owner/admin/member roles)
+- Switching active organization
+- Per-org data scoping via `org_id`
+
+The active organization ID flows from `session.orgId` → `AGENT_ORG_ID` → SQL scoping automatically.
+
+### ACCESS_TOKEN (Legacy)
+
+For simple deployments, set `ACCESS_TOKEN` or `ACCESS_TOKENS` (comma-separated) as environment variables. This provides a shared token for all users — no per-user identity.
+
+## A2A Security
+
+### Cross-App Identity
+
+When apps call each other via A2A, they need to verify identity. Set the same `A2A_SECRET` on all apps that need to trust each other:
+
+```bash
+# On both apps
+A2A_SECRET=your-shared-secret-at-least-32-chars
+```
+
+**How it works:**
+1. App A signs a JWT with `A2A_SECRET` containing `sub: "steve@builder.io"`
+2. App B receives the call, verifies the JWT signature
+3. App B sets `AGENT_USER_EMAIL` from the verified `sub` claim
+4. Data scoping applies — App B only shows steve's data
+
+Without `A2A_SECRET`, A2A calls are unauthenticated (fine for local dev, not production).
+
+## Rules for Agents
+
+1. **Every new table with user data must have `owner_email`.** No exceptions.
+2. **Never bypass scoping** — don't raw-query tables without going through `db-query`/`db-exec`.
+3. **Don't expose user data in application state** — application state is per-session, not per-user. Use SQL tables with `owner_email` for persistent user data.
+4. **Don't hardcode emails** — use `AGENT_USER_EMAIL` environment variable.
+5. **Test with multiple users** — create two accounts and verify data isolation.

package/src/templates/default/.agents/skills/storing-data/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: storing-data
+description: >-
+  How and where to store application data. Use when adding new data models,
+  deciding between settings vs Drizzle tables, reading/writing app config,
+  or working with application state.
+---
+
+# Storing Data
+
+## Where Data Goes
+
+All data lives in one SQLite database (`data/app.db`). In production, set `DATABASE_URL` to point to Turso, Neon, Supabase, or D1 — same code, no changes needed.
+
+There are three storage layers, each for a different kind of data:
+
+### 1. Settings — app configuration
+
+Key-value store for persistent config that the user or agent can change. Theme, preferences, integration API keys, availability schedules.
+
+```ts
+import { getSetting, putSetting } from "@agent-native/core/settings";
+
+// Read (returns null if not set)
+const prefs = await getSetting("user-preferences");
+
+// Write (creates or replaces)
+await putSetting("user-preferences", { theme: "dark", density: "comfortable" });
+```
+
+From scripts:
+```ts
+import { readSetting, writeSetting } from "@agent-native/core/settings";
+const prefs = await readSetting("user-preferences");
+```
+
+SSE: writes automatically notify the UI via `{ source: "settings", type: "change", key }`.
+
+### 2. Application State — ephemeral UI state
+
+For state the agent and UI share in real-time: what the user is looking at, compose drafts, navigation commands. Scoped by session — cleared between sessions.
+
+```ts
+import { readAppState, writeAppState, deleteAppState, listAppState } from "@agent-native/core/application-state";
+
+// Write state (UI updates instantly via SSE)
+await writeAppState("navigate", { view: "inbox", threadId: "t-123" });
+
+// Read state
+const nav = await readAppState("navigation");
+
+// List by prefix (e.g., all compose drafts)
+const drafts = await listAppState("compose-");
+
+// Delete (one-shot commands: UI reads, then agent or UI deletes)
+await deleteAppState("navigate");
+```
+
+SSE: writes automatically notify the UI via `{ source: "app-state", type: "change", key }`.
+
+### 3. Drizzle Tables — structured domain data
+
+For data with schemas, relationships, and queries: forms, bookings, emails, compositions. Define tables in `server/db/schema.ts` using Drizzle ORM.
+
+```ts
+import { table, text, integer } from "@agent-native/core/db/schema";
+
+export const bookings = table("bookings", {
+  id: text("id").primaryKey(),
+  name: text("name").notNull(),
+  email: text("email").notNull(),
+  startTime: integer("start_time").notNull(),
+  endTime: integer("end_time").notNull(),
+});
+```
+
+Query via `getDb()` singleton from `server/db/index.ts`.
+
+### 4. OAuth Tokens — credentials
+
+For OAuth tokens acquired at runtime (Google, etc.). Never store these in settings — use the dedicated encrypted store.
+
+```ts
+import { saveOAuthTokens, getOAuthTokens, listOAuthAccounts } from "@agent-native/core/oauth-tokens";
+
+await saveOAuthTokens("google", "user@gmail.com", { access_token: "...", refresh_token: "..." });
+const tokens = await getOAuthTokens("google", "user@gmail.com");
+const accounts = await listOAuthAccounts("google");
+```
+
+## Which Layer to Use
+
+| Data | Layer | Why |
+|------|-------|-----|
+| User preferences, theme, config | Settings | Persistent KV, SSE notifications, simple read/write |
+| What the user sees on screen | Application State | Ephemeral, real-time sync, agent ↔ UI bridge |
+| Compose drafts, wizard steps | Application State | Temporary, deleted when done |
+| Domain records (forms, bookings) | Drizzle table | Needs schema, queries, relationships |
+| OAuth refresh tokens | OAuth Tokens | Secure, per-provider, per-account |
+
+## Environment Variables
+
+Infrastructure config stays in `.env` — these differ per deployment:
+
+- `DATABASE_URL` — database connection (default: `file:./data/app.db`)
+- `DATABASE_AUTH_TOKEN` — for remote databases
+- `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` — OAuth app credentials
+- `ACCESS_TOKEN` — production auth token
+
+Everything else (user settings, tokens, app state) goes in SQL.

package/src/templates/default/.claude/settings.json

@@ -1,4 +1,17 @@
 {
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pnpm action view-screen 2>/dev/null || echo '{\"view\": \"unknown\"}'",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  },
   "permissions": {
     "allow": [
       "Read",

package/src/templates/default/AGENTS.md

@@ -52,18 +52,33 @@ The `navigation` key is written by the UI whenever the route changes. The `navig
 
 ## Agent Operations
 
-**Always run `pnpm action view-screen` first** before taking any action. This tells you what the user is looking at.
+**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
 
-| 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              |
-| `db-exec`     | `--sql "INSERT ..."`              | Run INSERT/UPDATE/DELETE        |
+| 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                                                                      |
+| `db-exec`     | `--sql "INSERT ..."`                                                           | Run INSERT/UPDATE/DELETE (use for short/multi-column writes)                            |
+| `db-patch`    | `--table <t> --column <c> --where "<clause>" --find "<old>" --replace "<new>"` | Surgical search/replace on a large text column — sends a diff instead of the full value |
+
+**Pick the right SQL tool:**
+
+- Use `db-exec UPDATE` for short columns, multi-column writes, or computed updates.
+- Use `db-patch` when you only need to tweak a small slice of a **large** text/JSON column (documents, slide HTML, dashboard/form JSON). It saves tokens by sending `{find, replace}` instead of re-transmitting the whole column. Targets exactly one row per call — narrow `--where` by primary key. Supports `--edits '[{find,replace},...]'` for batch edits and `--all` for replace-every-occurrence.
+- If a template-specific action exists (e.g. `edit-document`, `update-slide`), prefer it — those also push live updates to any open collaborative editor.
 
 ## Skills
 
@@ -78,6 +93,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 | `self-modifying-code` | Before editing source, components, or styles                   |
 | `capture-learnings`   | Before recording user preferences or corrections               |
 | `frontend-design`     | Before building or restyling any UI component, page, or layout |
+| `agent-engines`       | Before switching LLM providers or registering a custom engine  |
 
 ## When Adding Features
 

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

@@ -13,7 +13,7 @@ import type { ScriptTool } from "@agent-native/core";
 
 export const tool: ScriptTool = {
   description:
-    "See what the user is currently looking at on screen. Returns the current navigation state. Always call this first before taking any action.",
+    "See what the user is currently looking at on screen. Returns the current navigation state. Note: basic screen context is auto-included with each message — use this tool only when you need a detailed or refreshed snapshot.",
   parameters: {
     type: "object",
     properties: {},

package/src/templates/default/package.json

@@ -11,11 +11,11 @@
     "script": "agent-native script"
   },
   "dependencies": {
-    "@agent-native/core": "^0.4.1",
+    "@agent-native/core": "^0.6.0",
     "@assistant-ui/react": "^0.12.19",
     "@assistant-ui/react-markdown": "^0.12.6",
     "@tabler/icons-react": "^3.40.0",
-    "h3": "^1.13.0",
+    "h3": "^2.0.1-rc.20",
     "isbot": "^5"
   },
   "devDependencies": {

package/src/templates/default/server/middleware/auth.ts

@@ -0,0 +1,15 @@
+/**
+ * Global auth middleware — runs for ALL requests (page routes, API routes,
+ * framework routes). The auth plugin configures the guard; this middleware
+ * enforces it on every request.
+ *
+ * Without this, auth only runs for /_agent-native/* routes because the
+ * framework handler's middleware registry is scoped to that catch-all.
+ * Page routes (/, /settings) and API routes (/api/*) would bypass auth.
+ */
+import { defineEventHandler } from "h3";
+import { runAuthGuard } from "@agent-native/core/server";
+
+export default defineEventHandler(async (event) => {
+  return runAuthGuard(event);
+});

package/src/templates/default/server/routes/[...page].get.ts

@@ -1,12 +1,5 @@
-import { createRequestHandler } from "react-router";
-import { defineEventHandler, toWebRequest } from "h3";
+import { createH3SSRHandler } from "@agent-native/core/server/ssr-handler";
 
-const handler = createRequestHandler(
-  // virtual module provided by React Router Vite plugin
+export default createH3SSRHandler(
   () => import("virtual:react-router/server-build"),
 );
-
-export default defineEventHandler(async (event) => {
-  const webReq = toWebRequest(event);
-  return handler(webReq);
-});

package/src/templates/default/ssr-entry.ts

@@ -0,0 +1,20 @@
+/**
+ * SSR entry point for Nitro.
+ *
+ * This wraps React Router's request handler so Nitro can use it as an
+ * SSR service. The file must be a real file (not a virtual module) so
+ * Nitro can resolve it during build.
+ *
+ * Similar to how TanStack Start provides a server.ts entry for Nitro.
+ */
+import { createRequestHandler } from "react-router";
+
+const handler = createRequestHandler(
+  () => import("virtual:react-router/server-build"),
+);
+
+export default {
+  async fetch(request: Request) {
+    return handler(request);
+  },
+};