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

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

@@ -0,0 +1,136 @@
+---
+name: actions
+description: >-
+  How to create and run agent-callable actions in actions/. Use when creating
+  a new action, adding an API integration, implementing a complex agent
+  operation, or running pnpm action commands.
+---
+
+# Agent Actions
+
+## Rule
+
+Complex operations the agent needs to perform are implemented as actions in `actions/`. The agent runs them via `pnpm action <name>`.
+
+## Why
+
+Actions give the agent callable tools with structured input/output. They keep the agent's chat context clean (no massive code blocks), they're reusable, and they can be tested independently.
+
+## How to Create an Action
+
+Create `actions/my-action.ts`:
+
+```ts
+import fs from "fs";
+import { parseArgs, loadEnv, fail, agentChat } from "@agent-native/core";
+
+export default async function myAction(args: string[]) {
+  loadEnv();
+
+  const parsed = parseArgs(args);
+  const input = parsed.input;
+  if (!input) fail("--input is required");
+
+  const outputPath = parsed.output ?? "data/result.json";
+  const raw = fs.readFileSync(input, "utf-8");
+  const data = JSON.parse(raw) as unknown;
+
+  fs.writeFileSync(outputPath, JSON.stringify(data, null, 2));
+  agentChat.submit(`Processed ${input}, result saved to ${outputPath}`);
+}
+```
+
+### Using `defineAction` (recommended for new actions)
+
+```ts
+import { defineAction } from "@agent-native/core";
+
+export default defineAction({
+  description: "Process some data",
+  parameters: {
+    input: { type: "string", description: "Input file path" },
+    output: { type: "string", description: "Output file path" },
+  },
+  run: async (args) => {
+    // do work
+    return "Done";
+  },
+});
+```
+
+## How to Run
+
+```bash
+pnpm action my-action --input data/source.json --output data/result.json
+```
+
+## Action Dispatcher
+
+The default template uses core's `runScript()` in `actions/run.ts`:
+
+```ts
+import { runScript } from "@agent-native/core";
+runScript();
+```
+
+This is the canonical approach for new apps. Action names must be lowercase with hyphens only (e.g., `my-action`).
+
+## Guidelines
+
+- **One action, one job.** Keep actions focused on a single operation. The agent composes multiple action calls for complex operations.
+- **Use `parseArgs()`** for structured argument parsing. It converts `--key value` pairs to a `Record<string, string>`.
+- **Use `loadEnv()`** if the action needs environment variables (API keys, etc.).
+- **Use `fail()`** for user-friendly error messages (exits with message, no stack trace).
+- **Write results to the database.** The agent and UI will pick them up via db sync polling.
+- **Use `agentChat.submit()`** to report results or errors back to the agent chat.
+- **Import from `@agent-native/core`** -- Don't redefine `parseArgs()` or other utilities locally.
+
+## Common Patterns
+
+**API integration action** (e.g., image generation):
+
+```ts
+import fs from "fs";
+import { parseArgs, loadEnv, fail } from "@agent-native/core";
+
+export default async function generateImage(args: string[]) {
+  loadEnv();
+  const parsed = parseArgs(args);
+  const prompt = parsed.prompt;
+  if (!prompt) fail("--prompt is required");
+
+  const outputPath = parsed.output ?? "data/generated-image.png";
+  const imageUrl = await callImageAPI(prompt);
+  const buffer = await fetch(imageUrl).then((r) => r.arrayBuffer());
+  fs.writeFileSync(outputPath, Buffer.from(buffer));
+}
+```
+
+**Data processing action:**
+
+```ts
+import fs from "fs";
+import { parseArgs, fail } from "@agent-native/core";
+
+export default async function transform(args: string[]) {
+  const parsed = parseArgs(args);
+  const source = parsed.source;
+  if (!source) fail("--source is required");
+
+  const data = JSON.parse(fs.readFileSync(source, "utf-8")) as unknown[];
+  const result = data.map(transformItem);
+  fs.writeFileSync(source, JSON.stringify(result, null, 2));
+}
+```
+
+## Troubleshooting
+
+- **Action not found** -- Check that the filename matches the command name exactly. `pnpm action foo-bar` looks for `actions/foo-bar.ts`.
+- **Args not parsing** -- Ensure args use `--key value` or `--key=value` format. Boolean flags use `--flag` (sets value to `"true"`).
+- **Action runs but UI doesn't update** -- Make sure results are written to the database so db sync polling picks them up.
+
+## Related Skills
+
+- **files-as-database** -- Actions read/write data files in `data/`
+- **delegate-to-agent** -- The agent invokes actions via `pnpm action <name>`
+- **real-time-sync** -- Database writes from actions trigger poll events to update the UI

package/src/templates/default/.agents/skills/create-skill/SKILL.md

@@ -148,7 +148,7 @@ description: >-
 
 - **Inline LLM calls** — Skills must not call LLMs directly (violates Rule 2)
 - **Database patterns** — Skills must not introduce databases (violates Rule 1)
-- **Ignoring SSE** — If a skill creates data files, mention wiring up `useFileWatcher`
+- **Ignoring db sync** — If a skill creates data, mention wiring up `useDbSync`
 - **Vague descriptions** — "Helps with development" won't trigger. Be specific about _when_.
 - **Pure documentation** — Skills should guide action, not just explain concepts
 

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

@@ -84,7 +84,7 @@ Scripts may call external APIs (image generation, search, etc.) — but the AI r
 
 ## Related Skills
 
-- **scripts** — The agent invokes scripts via `pnpm script <name>` to perform complex operations
+- **scripts** — The agent invokes scripts via `pnpm action <name>` to perform complex operations
 - **self-modifying-code** — The agent operates through the chat bridge to make code changes
 - **storing-data** — The agent writes results to the database after processing requests
 - **real-time-sync** — The UI updates automatically when the agent writes to the database

package/src/templates/default/.agents/skills/files-as-database/SKILL.md

@@ -63,9 +63,9 @@ SSE: writes automatically notify the UI via `{ source: "app-state", type: "chang
 For data with schemas, relationships, and queries: forms, bookings, emails, compositions. Define tables in `server/db/schema.ts` using Drizzle ORM.
 
 ```ts
-import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { table, text, integer } from "@agent-native/core/db/schema";
 
-export const bookings = sqliteTable("bookings", {
+export const bookings = table("bookings", {
   id: text("id").primaryKey(),
   name: text("name").notNull(),
   email: text("email").notNull(),

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

@@ -0,0 +1,112 @@
+---
+name: real-time-sync
+description: >-
+  How to keep the UI in sync with agent changes via polling. Use when wiring
+  query invalidation for new data models, debugging UI not updating, or
+  understanding jitter prevention.
+---
+
+# Real-Time Sync (Polling)
+
+## Rule
+
+The UI stays in sync with agent/script changes through database polling. When the agent writes to the database, the UI detects the change and updates automatically — no manual refresh needed.
+
+## Why
+
+The agent modifies data in SQL, but the UI runs in the browser. Polling bridges this gap: every database write increments a version counter, the `useDbSync()` hook polls for version changes, and React Query invalidates the relevant caches. This is what makes database writes feel real-time.
+
+## How It Works
+
+1. **Server** increments a version counter on every database write. The `/_agent-native/poll` endpoint returns the current version and any events since the last poll.
+
+2. **Client** polls for changes and invalidates React Query caches:
+
+   ```ts
+   import { useDbSync } from "@agent-native/core";
+   useDbSync({ queryClient, queryKeys: ["items", "settings"] });
+   ```
+
+3. When the agent writes to the database, the version increments, polling detects it, and React Query refetches the affected queries.
+
+## Don't
+
+- Don't create manual polling loops — `useDbSync()` handles it (polls every 2 seconds by default)
+- Don't create your own fetch-based polling alongside `useDbSync` — use the `onEvent` callback for custom handling
+
+## Query Key Mapping
+
+By default, `useDbSync` invalidates all listed query keys on every change. For apps with multiple data models, this causes unnecessary refetches. Use event-based filtering via the `onEvent` callback:
+
+```ts
+useDbSync({
+  queryClient,
+  queryKeys: [], // don't auto-invalidate everything
+  onEvent: (data) => {
+    if (data.source === "settings") {
+      queryClient.invalidateQueries({ queryKey: ["settings"] });
+    } else if (data.source === "app-state") {
+      queryClient.invalidateQueries({ queryKey: ["navigate-command"] });
+    } else {
+      queryClient.invalidateQueries({ queryKey: ["items"] });
+    }
+  },
+});
+```
+
+To prevent cache thrashing during rapid agent writes, set `staleTime` on your queries:
+
+```ts
+useQuery({
+  queryKey: ["items"],
+  queryFn: fetchItems,
+  staleTime: 2000, // don't refetch within 2 seconds
+});
+```
+
+## Troubleshooting
+
+| Symptom                            | Check                                                                                                          |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| UI not updating after agent writes | Is `useDbSync` called with the correct `queryClient`? Are the `queryKeys` matching your `useQuery` keys?       |
+| Poll endpoint not responding       | Is `/_agent-native/poll` accessible? Is the server running?                                                    |
+| High CPU / event storms            | The agent is writing rapidly. Add `staleTime` to queries and use event-based filtering.                        |
+
+## Jitter Prevention
+
+When the agent writes to application-state via script helpers (`writeAppState`, `deleteAppState`), the write is automatically tagged with `requestSource: "agent"`. This prevents the UI from overwriting active user edits when it receives the change event.
+
+### How it works
+
+1. **Agent writes** are tagged: the script helpers in `@agent-native/core/application-state` pass `{ requestSource: "agent" }` to the store.
+2. **UI writes** are tagged: templates send a per-tab ID via the `X-Request-Source` header on PUT/DELETE requests to application-state endpoints.
+3. **Polling filters**: `useDbSync()` accepts an `ignoreSource` option. The UI passes its own tab ID so it ignores events from its own writes — but still picks up events from agents, other tabs, and scripts.
+
+### Template setup
+
+```ts
+// app/lib/tab-id.ts
+export const TAB_ID = `tab-${Math.random().toString(36).slice(2, 8)}`;
+
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  queryKeys: ["app-state", "settings"],
+  ignoreSource: TAB_ID,
+});
+```
+
+The `use-navigation-state.ts` hook sends the same `TAB_ID` in the `X-Request-Source` header when writing navigation state, so the tab that wrote the state does not refetch it.
+
+### Why this matters
+
+Without jitter prevention, a cycle occurs: the UI writes state, polling detects the change, the UI refetches and re-renders, potentially overwriting what the user is actively editing. With `ignoreSource`, the UI only reacts to changes from other sources (agent scripts, other browser tabs, other users).
+
+## Related Skills
+
+- **storing-data** — Application-state and settings are the data stores that sync via polling
+- **context-awareness** — Navigation state writes use jitter prevention to avoid overwriting active edits
+- **scripts** — Script outputs written to the database trigger poll events
+- **self-modifying-code** — Agent code edits trigger poll events; rapid edits can cause event storms

package/src/templates/default/AGENTS.md

@@ -1,73 +1,71 @@
-# {{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 run `pnpm action view-screen` first** before taking any action. This tells you what the user is looking at.
 
----
+### 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        |
+
+## Skills
 
 Skills in `.agents/skills/` provide detailed guidance for each architectural rule. Read them before making changes.
 
@@ -75,128 +73,22 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 | --------------------- | -------------------------------------------------------------- |
 | `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                           |
+| `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 |
 
-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()`:
-
-```tsx
-import MyPage from "@/pages/MyPage";
-
-export function meta() {
-  return [{ title: "My Page" }];
-}
-
-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>
-  );
-}
-
-export default function MyPageRoute() {
-  return <MyPage />;
-}
-```
-
-**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/*`.
-
-### Key Patterns
+## When Adding Features
 
-**Adding an API route:**
-Create a file in `server/routes/api/`. The filename determines the URL path and HTTP method:
+As you build out this app, follow this checklist for each new feature:
 
-```
-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
-```
+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
 
-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:**
-
-```ts
-import { sendToAgentChat } from "@agent-native/core";
-sendToAgentChat({
-  message: "Generate something",
-  context: "...",
-  submit: true,
-});
-```
-
-**Sending to agent chat from scripts:**
-
-```ts
-import { agentChat } from "@agent-native/core";
-agentChat.submit("Generate something");
-```
-
-### Database (Cloud Deployment)
-
-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/{scripts → actions}/hello.ts

@@ -1,5 +1,5 @@
 /**
- * Example script — callable via `pnpm script hello`
+ * Example script — callable via `pnpm action hello`
  *
  * Scripts export a default async function that receives CLI args.
  */