@agent-native/core 0.4.5 → 0.6.1

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

@@ -1,202 +1,110 @@
-# {{APP_NAME}} — Agent-Native App
+# {{APP_NAME}} — Agent Guide
 
-## Architecture
+This app follows the agent-native core philosophy: the agent and UI are equal partners. Everything the UI can do, the agent can do via actions. The agent always knows what you're looking at via application state. See the root AGENTS.md for full framework documentation.
 
-This is an **@agent-native/core** application — the AI agent and UI share state through a SQL database, with SSE for real-time sync.
+This is an **@agent-native/core** application -- the AI agent and UI share state through a SQL database, with polling for real-time sync.
 
 ### Core Principles
 
-1. **Shared SQL database** — All app state lives in SQL (SQLite locally, cloud DB via `DATABASE_URL` in production). Core stores: `application_state`, `settings`, `oauth_tokens`, `sessions`.
-2. **All AI through agent chat** — No inline LLM calls. UI delegates to the AI via `sendToAgentChat()` / `agentChat.submit()`.
-3. **Scripts for agent operations** — `pnpm script <name>` dispatches to callable script files in `scripts/`.
-4. **SSE for real-time sync** — Database writes emit events that keep the UI in sync automatically.
-5. **Agent can update code** — The agent can modify this app's source code directly.
+1. **Shared SQL database** -- All app state lives in SQL (SQLite locally, cloud DB via `DATABASE_URL` in production). Core stores: `application_state`, `settings`, `oauth_tokens`, `sessions`, `resources`.
+2. **All AI through agent chat** -- No inline LLM calls. UI delegates to the AI via `sendToAgentChat()` / `agentChat.submit()`.
+3. **Actions for agent operations** -- `pnpm action <name>` dispatches to callable action files in `actions/`.
+4. **Polling for real-time sync** -- Database writes trigger version counter increments that the UI polls to stay in sync.
+5. **Agent can update code** -- The agent can modify this app's source code directly.
 
 ### Authentication
 
-Auth is automatic and environment-driven. The `server/plugins/auth.ts` plugin calls `autoMountAuth(app)` at startup.
+Auth is automatic and environment-driven:
 
-- **Dev mode**: Auth is bypassed. `getSession()` returns `{ email: "local@localhost" }`. Zero friction.
-- **Production** (`ACCESS_TOKEN` set): Auth middleware auto-mounts. Login page for unauthenticated visitors.
-- **Production** (no token, no `AUTH_DISABLED=true`): Server refuses to start.
+- **Dev mode**: Auth is bypassed. `getSession()` returns `{ email: "local@localhost" }`.
+- **Production** (`ACCESS_TOKEN` set): Auth middleware auto-mounts.
 
-Use `getSession(event)` server-side and `useSession()` client-side. See [docs/auth.md](docs/auth.md).
+Use `getSession(event)` server-side and `useSession()` client-side.
 
-### Directory Structure
+## Resources
 
-```
-app/                   # React frontend
-  root.tsx             # HTML shell + global providers
-  entry.client.tsx     # Client hydration entry
-  routes.ts            # Route config — flatRoutes()
-  routes/              # File-based page routes (auto-discovered)
-    _index.tsx         # / (home page)
-  components/          # UI components
-  hooks/               # React hooks
-  lib/                 # Utilities (cn, etc)
+Resources are SQL-backed persistent files for notes, learnings, and context.
 
-server/                # Nitro API server
-  routes/
-    api/               # File-based API routes (auto-discovered)
-    [...page].get.ts   # SSR catch-all (delegates to React Router)
-  plugins/             # Server plugins (startup logic)
-  lib/                 # Shared server modules
+**At the start of every conversation, read these resources (both personal and shared scopes):**
 
-shared/                # Isomorphic code (imported by both client & server)
+1. **`AGENTS.md`** -- user-specific context. Read both `--scope personal` and `--scope shared`.
+2. **`LEARNINGS.md`** -- user preferences, corrections, and patterns. Read both scopes.
 
-scripts/               # Agent-callable scripts
-  run.ts               # Script dispatcher
-  *.ts                 # Individual scripts (pnpm script <name>)
+**Update `LEARNINGS.md` when you learn something important.**
 
-data/                  # App data (SQLite DB file)
+| Action            | Args                                                        | Purpose                 |
+| ----------------- | ----------------------------------------------------------- | ----------------------- |
+| `resource-read`   | `--path <path> [--scope personal\|shared]`                  | Read a resource         |
+| `resource-write`  | `--path <path> --content <text> [--scope personal\|shared]` | Write/update a resource |
+| `resource-list`   | `[--prefix <path>] [--scope personal\|shared\|all]`         | List resources          |
+| `resource-delete` | `--path <path> [--scope personal\|shared]`                  | Delete a resource       |
 
-react-router.config.ts # React Router framework config
-.agents/skills/        # Agent skills — detailed guidance for each rule
-```
+## Application State
 
-## Learnings & Preferences
+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`.
 
-**Always read `learnings.md` at the start of every conversation.** This file is the app's memory — it contains user preferences, corrections, important context, and patterns learned from past interactions.
+| State Key    | Purpose                                   | Direction                  |
+| ------------ | ----------------------------------------- | -------------------------- |
+| `navigation` | Current view                              | UI -> Agent (read-only)    |
+| `navigate`   | Navigate command (one-shot, auto-deleted) | Agent -> UI (auto-deleted) |
 
-**Update `learnings.md` when you learn something important:**
+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.
 
-- User corrects your tone, style, or approach
-- User shares personal info relevant to the app (contacts, preferences, habits)
-- You discover a non-obvious pattern or gotcha
-- User gives feedback that should apply to future conversations
+## Agent Operations
 
-Keep entries concise and actionable. Group by category. This file is gitignored so personal data stays local.
+**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.
 
----
-
-Skills in `.agents/skills/` provide detailed guidance for each architectural rule. Read them before making changes.
-
-| Skill                 | When to read                                                   |
-| --------------------- | -------------------------------------------------------------- |
-| `storing-data`        | Before storing or reading any app state                        |
-| `delegate-to-agent`   | Before adding LLM calls or AI delegation                       |
-| `scripts`             | Before creating or modifying scripts                           |
-| `real-time-sync`      | Before wiring up real-time UI sync                             |
-| `self-modifying-code` | Before editing source, components, or styles                   |
-| `frontend-design`     | Before building or restyling any UI component, page, or layout |
-
-The **`frontend-design`** skill (sourced from [Anthropic's skills library](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md)) enforces distinctive, production-grade aesthetics — committing to a clear visual direction and avoiding generic patterns like purple gradients, overused fonts, and cookie-cutter layouts.
-
-### Framework Basics
-
-**SSR-first framework, CSR-by-default content:** This app uses React Router v7 framework mode with `ssr: true`. But virtually every route renders only an SSR shell (loading spinner + meta tags). All real data fetching and rendering happens on the client via React Query hooks. Server-side data fetching is the exception — only used for public pages that need SEO/og tags.
-
-**Adding a page:**
-Create a file in `app/routes/`. The filename determines the URL path:
-
-```
-app/routes/_index.tsx              → /
-app/routes/settings.tsx            → /settings
-app/routes/inbox.tsx               → /inbox
-app/routes/inbox.$threadId.tsx     → /inbox/:threadId
-app/routes/$id.tsx                 → /:id (dynamic param)
-```
-
-Each route file exports a default component, optional `meta()`, and optional `HydrateFallback()`:
+### If you are the built-in agent-chat agent
 
-```tsx
-import MyPage from "@/pages/MyPage";
+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.
 
-export function meta() {
-  return [{ title: "My Page" }];
-}
+### If you are an external CLI agent (Claude Code, Codex, Cursor, etc.)
 
-export function HydrateFallback() {
-  return (
-    <div className="flex items-center justify-center h-screen">
-      <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-foreground" />
-    </div>
-  );
-}
+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.
 
-export default function MyPageRoute() {
-  return <MyPage />;
-}
-```
+### Actions
 
-**Do NOT fetch data server-side** in route loaders unless the page genuinely needs SEO content or og tags based on dynamic data. The standard pattern is: SSR renders a loading spinner, client hydrates, React Query hooks fetch from `/api/*`.
+| 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 |
 
-### Key Patterns
+**Pick the right SQL tool:**
 
-**Adding an API route:**
-Create a file in `server/routes/api/`. The filename determines the URL path and HTTP method:
+- 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.
 
-```
-server/routes/api/items/index.get.ts    → GET  /api/items
-server/routes/api/items/[id].get.ts     → GET  /api/items/:id
-server/routes/api/items/[id].patch.ts   → PATCH /api/items/:id
-```
+## Skills
 
-Each file exports a default `defineEventHandler`.
-
-**Adding a server plugin:**
-Startup logic (auth, SSE, etc.) lives in `server/plugins/`. Use `defineNitroPlugin` from core:
-
-```ts
-import { defineNitroPlugin } from "@agent-native/core";
-
-export default defineNitroPlugin(async (nitroApp) => {
-  // Runs once at server startup
-});
-```
-
-**Key imports from `@agent-native/core`:**
-
-| Import                                       | Purpose                                                                    |
-| -------------------------------------------- | -------------------------------------------------------------------------- |
-| `defineNitroPlugin`                          | Define a server plugin (re-exported from Nitro)                            |
-| `createDefaultSSEHandler`                    | Create SSE endpoint for DB change events (server)                          |
-| `readAppState`, `writeAppState`              | Read/write application state (from `@agent-native/core/application-state`) |
-| `readSetting`, `writeSetting`                | Read/write settings (from `@agent-native/core/settings`)                   |
-| `defineEventHandler`, `readBody`, `getQuery` | H3 route handler utilities (re-exported)                                   |
-| `sendToAgentChat`                            | Send messages to agent from UI (client-side)                               |
-| `agentChat`                                  | Send messages to agent from scripts (server-side)                          |
-
-**Adding a script:**
-Create `scripts/my-script.ts` exporting `default async function(args: string[])`.
-Run with: `pnpm script my-script --arg value`
-
-**Sending to agent chat from UI:**
+Skills in `.agents/skills/` provide detailed guidance for each architectural rule. Read them before making changes.
 
-```ts
-import { sendToAgentChat } from "@agent-native/core";
-sendToAgentChat({
-  message: "Generate something",
-  context: "...",
-  submit: true,
-});
-```
+| Skill                 | When to read                                                   |
+| --------------------- | -------------------------------------------------------------- |
+| `storing-data`        | Before storing or reading any app state                        |
+| `delegate-to-agent`   | Before adding LLM calls or AI delegation                       |
+| `actions`             | Before creating or modifying actions                           |
+| `real-time-sync`      | Before wiring up real-time UI sync                             |
+| `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  |
 
-**Sending to agent chat from scripts:**
+## When Adding Features
 
-```ts
-import { agentChat } from "@agent-native/core";
-agentChat.submit("Generate something");
-```
+As you build out this app, follow this checklist for each new feature:
 
-### Database (Cloud Deployment)
+1. **Add navigation state entries** -- create or extend `app/hooks/use-navigation-state.ts` to track new routes
+2. **Enhance view-screen** -- make the view-screen script return relevant context for the new view
+3. **Create domain actions** -- add scripts for CRUD operations on new data models
+4. **Create domain skills** -- add `.agents/skills/<feature>/SKILL.md` documenting the data model, storage patterns, and agent operations
+5. **Update this AGENTS.md** -- add the new actions, state keys, and common tasks
 
-By default, data is stored in SQLite at `data/app.db`. For production/cloud deployment, set `DATABASE_URL` to point to a remote database (Turso, Neon, Supabase, D1).
+---
 
-**Environment variables:**
-
-| Variable              | Required         | Description                                                |
-| --------------------- | ---------------- | ---------------------------------------------------------- |
-| `DATABASE_URL`        | No (has default) | Database connection string (default: `file:./data/app.db`) |
-| `DATABASE_AUTH_TOKEN` | For remote DBs   | Auth token for Turso or other remote databases             |
-
-### Tech Stack
-
-- **Framework:** @agent-native/core + React Router v7 (framework mode)
-- **Frontend:** React 18, Vite, TailwindCSS, shadcn/ui
-- **Routing:** File-based via `flatRoutes()` — SSR shell + client rendering
-- **Backend:** Nitro (via @agent-native/core) — file-based API routing, server plugins, deploy-anywhere presets
-- **State:** SQL-backed (SSE for real-time updates)
-- **Build:** `pnpm build` (React Router build — client + SSR + Nitro server)
-- **Dev:** `pnpm dev` (Vite dev server with both React Router + Nitro plugins)
-- **Start:** `node .output/server/index.mjs` (production)
+For code editing and development guidance, read `DEVELOPING.md`.

package/src/templates/default/DEVELOPING.md

@@ -0,0 +1,117 @@
+# {{APP_NAME}} — Development Guide
+
+This guide is for development-mode agents editing this app's source code. For app operations and tools, see AGENTS.md.
+
+## Framework Basics
+
+**Client-side-first rendering:** This app uses React Router v7 framework mode with `ssr: true`, but all app content renders **client-side only**. The server renders only the HTML shell (meta tags, styles, scripts) plus a loading spinner. This is enforced by the `ClientOnly` wrapper in `root.tsx` — never remove it. Browser APIs (`window`, `localStorage`, `new Date()`) are safe to use anywhere in app code because components never run on the server.
+
+**Do NOT fetch data server-side** in route loaders. The standard pattern is: server renders a spinner, client hydrates, React Query hooks fetch from `/api/*`.
+
+## Adding a Page
+
+Create a file in `app/routes/`. The filename determines the URL path:
+
+```
+app/routes/_index.tsx              → /
+app/routes/settings.tsx            → /settings
+app/routes/inbox.tsx               → /inbox
+app/routes/inbox.$threadId.tsx     → /inbox/:threadId
+app/routes/$id.tsx                 → /:id (dynamic param)
+```
+
+Each route file exports a default component and optional `meta()`:
+
+```tsx
+import MyPage from "@/pages/MyPage";
+
+export function meta() {
+  return [{ title: "My Page" }];
+}
+
+export default function MyPageRoute() {
+  return <MyPage />;
+}
+```
+
+## Adding an API Route
+
+Create a file in `server/routes/api/`. The filename determines the URL path and HTTP method:
+
+```
+server/routes/api/items/index.get.ts    → GET  /api/items
+server/routes/api/items/[id].get.ts     → GET  /api/items/:id
+server/routes/api/items/[id].patch.ts   → PATCH /api/items/:id
+```
+
+Each file exports a default `defineEventHandler`.
+
+## Server Plugins
+
+Startup logic (auth, SSE, etc.) lives in `server/plugins/`. Use `defineNitroPlugin` from core:
+
+```ts
+import { defineNitroPlugin } from "@agent-native/core";
+
+export default defineNitroPlugin(async (nitroApp) => {
+  // Runs once at server startup
+});
+```
+
+## Key Imports
+
+| Import                                       | Purpose                                                                    |
+| -------------------------------------------- | -------------------------------------------------------------------------- |
+| `defineNitroPlugin`                          | Define a server plugin (re-exported from Nitro)                            |
+| `createDefaultSSEHandler`                    | Create SSE endpoint for DB change events (server)                          |
+| `readAppState`, `writeAppState`              | Read/write application state (from `@agent-native/core/application-state`) |
+| `readSetting`, `writeSetting`                | Read/write settings (from `@agent-native/core/settings`)                   |
+| `readResource`, `writeResource`              | Read/write resources (from `@agent-native/core/resources`)                 |
+| `defineEventHandler`, `readBody`, `getQuery` | H3 route handler utilities (re-exported)                                   |
+| `sendToAgentChat`                            | Send messages to agent from UI (client-side)                               |
+| `agentChat`                                  | Send messages to agent from scripts (server-side)                          |
+
+## Adding a Script
+
+Create `actions/my-script.ts` exporting `default async function(args: string[])`.
+Run with: `pnpm action my-script --arg value`
+
+## Sending to Agent Chat
+
+**From UI:**
+
+```ts
+import { sendToAgentChat } from "@agent-native/core";
+sendToAgentChat({
+  message: "Generate something",
+  context: "...",
+  submit: true,
+});
+```
+
+**From scripts:**
+
+```ts
+import { agentChat } from "@agent-native/core";
+agentChat.submit("Generate something");
+```
+
+## Database
+
+By default, data is stored in SQLite at `data/app.db`. For production/cloud deployment, set `DATABASE_URL` to point to a remote database (Turso, Neon, Supabase, D1).
+
+| Variable              | Required         | Description                                                |
+| --------------------- | ---------------- | ---------------------------------------------------------- |
+| `DATABASE_URL`        | No (has default) | Database connection string (default: `file:./data/app.db`) |
+| `DATABASE_AUTH_TOKEN` | For remote DBs   | Auth token for Turso or other remote databases             |
+
+## Tech Stack
+
+- **Framework:** @agent-native/core + React Router v7 (framework mode)
+- **Frontend:** React 18, Vite, TailwindCSS, shadcn/ui
+- **Routing:** File-based via `flatRoutes()` — SSR shell + client rendering
+- **Backend:** Nitro (via @agent-native/core) — file-based API routing, server plugins, deploy-anywhere presets
+- **State:** SQL-backed (SSE for real-time updates)
+- **Build:** `pnpm build` (React Router build — client + SSR + Nitro server)
+- **Dev:** `pnpm dev` (Vite dev server with both React Router + Nitro plugins)
+- **Start:** `node .output/server/index.mjs` (production)

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

@@ -0,0 +1,20 @@
+/**
+ * Example script — callable via `pnpm action hello`
+ *
+ * Scripts export a default async function that receives CLI args.
+ */
+
+import { parseArgs } from "@agent-native/core";
+import { agentChat } from "@agent-native/core";
+
+export default async function hello(args: string[]) {
+  const parsed = parseArgs(args);
+  const name = parsed.name ?? "world";
+
+  console.log(`Hello, ${name}!`);
+
+  // Example: send a message to agent chat (works in Electron context)
+  if (parsed["send-chat"] === "true") {
+    agentChat.submit(`Hello from the script system! Name: ${name}`);
+  }
+}