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

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

@@ -0,0 +1,213 @@
+---
+name: security
+description: >-
+  Secure coding guide for agent-native apps. Covers input validation, SQL
+  injection prevention, XSS, secrets management, auth patterns, data scoping,
+  and A2A security. Read this when generating any code that handles user data.
+---
+
+# Security
+
+The framework provides strong security primitives. Use them — don't reinvent security.
+
+## Input Validation
+
+**Always use `defineAction` with a Zod `schema:`** for every action that accepts user input. The framework validates automatically and returns clear error messages.
+
+```ts
+// SECURE — framework validates before run() is called
+export default defineAction({
+  description: "Create a note",
+  schema: z.object({
+    title: z.string().min(1).max(200),
+    content: z.string().optional(),
+  }),
+  run: async (args) => {
+    // args is guaranteed valid — { title: string; content?: string }
+  },
+});
+```
+
+The legacy `parameters:` format (plain JSON Schema) has **no runtime validation** — the agent receives whatever the caller sends. Do not use it for new code.
+
+Actions without a `schema:` are unvalidated. This is acceptable for internal/dev scripts but never for user-facing operations.
+
+## SQL Injection Prevention
+
+The framework's `db-query` and `db-exec` tools use **parameterized queries** (`?` placeholders). The database driver handles escaping — user input never touches the SQL string.
+
+```ts
+// WRONG — SQL injection vulnerability
+await exec(`INSERT INTO notes (title) VALUES ('${title}')`)
+await exec(`SELECT * FROM notes WHERE title LIKE '%${search}%'`)
+
+// RIGHT — parameterized queries (framework default)
+await exec({ sql: "INSERT INTO notes (title) VALUES (?)", args: [title] })
+await exec({ sql: "SELECT * FROM notes WHERE title LIKE ?", args: [`%${search}%`] })
+```
+
+**Drizzle ORM is always safe** — it generates parameterized queries automatically:
+
+```ts
+const notes = await db.select().from(notesTable).where(eq(notesTable.title, title));
+```
+
+**When is SQL injection a risk?**
+- Only when writing raw SQL with string concatenation in server routes or actions
+- Never when using `db-query`/`db-exec` with `args` arrays
+- Never when using Drizzle ORM
+
+## XSS Prevention
+
+React auto-escapes all JSX expressions by default. Trust it.
+
+```tsx
+// SAFE — React escapes the output
+<p>{userInput}</p>
+<span>{comment.text}</span>
+
+// DANGEROUS — bypasses React's escaping
+<div dangerouslySetInnerHTML={{ __html: userInput }} />  // NEVER with user content
+element.innerHTML = userInput;                             // NEVER
+eval(userInput);                                           // NEVER
+document.write(userInput);                                 // NEVER
+new Function(userInput);                                   // NEVER
+```
+
+**For rich text:** Use TipTap (framework dependency) with the Collaboration extension. TipTap sanitizes content through its schema — only allowed node types render.
+
+**For markdown:** Use `react-markdown` (already used in the framework). It parses markdown to React elements without `dangerouslySetInnerHTML`.
+
+**For HTML from external sources:** If you absolutely must render external HTML, use a sanitization library like `dompurify`. But prefer structured data (markdown, TipTap JSON) over raw HTML.
+
+## Secrets Management
+
+| Secret type | Where to store | Why |
+|-------------|---------------|-----|
+| API keys (OpenAI, Stripe, etc.) | `.env` file (gitignored) | Never committed, server-side only |
+| OAuth tokens (Google, GitHub) | `oauth_tokens` store | Per-user, per-provider, server-side |
+| App configuration | `settings` store | OK for non-secret config (themes, preferences) |
+| Session tokens | Framework handles | Automatic via Better Auth |
+
+**Rules:**
+- Never store secrets in `settings`, `application_state`, or source code
+- Never return secrets in action responses — they may appear in agent chat or client UI
+- Never log secrets (tokens, keys, passwords)
+- Never commit `.env` files — they're gitignored by default
+- Access env vars via `process.env` in actions/server code, never send them to the client
+
+## Auth Patterns
+
+### Use `defineAction` (recommended)
+
+Actions defined with `defineAction` are automatically protected by the auth guard. Unauthenticated requests get a 401 response. This is the safest pattern.
+
+```ts
+// Auto-protected — auth guard runs before this code
+export default defineAction({
+  description: "Delete a note",
+  schema: z.object({ id: z.string() }),
+  run: async (args) => {
+    // Only authenticated users reach here
+  },
+});
+```
+
+### Custom `/api/` routes (use sparingly)
+
+If you must create custom routes (file uploads, streaming, webhooks), always check auth:
+
+```ts
+// server/routes/api/upload.ts
+import { getSession } from "@agent-native/core/server";
+
+export default defineEventHandler(async (event) => {
+  const session = await getSession(event);
+  if (!session?.email) {
+    setResponseStatus(event, 401);
+    return { error: "Unauthorized" };
+  }
+  // ... handle upload with session.email
+});
+```
+
+### CSRF Protection
+
+The framework uses `SameSite=lax` cookies with `httpOnly` flag. This prevents most CSRF attacks. Additional rules:
+- State-changing actions should use POST (the default for `defineAction`)
+- GET actions (`http: { method: "GET" }`) should be read-only
+- Never perform writes in response to GET requests
+
+## Data Scoping
+
+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(),
+  org_id: text("org_id").notNull(),
+});
+```
+
+When both columns are present, queries are scoped by **both**: `WHERE owner_email = ? AND org_id = ?`.
+
+### Validation
+
+Run `pnpm action db-check-scoping` to verify all tables have proper ownership columns. Use `--require-org` for multi-org apps.
+
+## 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
+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. **Always use `defineAction` with a Zod `schema:`** for input validation on user-facing actions.
+3. **Never concatenate user input into SQL** — use parameterized queries or Drizzle ORM.
+4. **Never use `dangerouslySetInnerHTML`** or `innerHTML` with user-controlled content.
+5. **Never store secrets outside `.env` or `oauth_tokens`** — no settings, no source code, no responses.
+6. **Never bypass scoping** — don't raw-query tables without going through `db-query`/`db-exec`.
+7. **Never create unprotected routes that modify data** — use `defineAction` or check `getSession()`.
+8. **Don't hardcode emails** — use `AGENT_USER_EMAIL` environment variable.
+9. **Don't expose user data in application state** — it's per-session, not per-user. Use SQL tables with `owner_email`.

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

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

package/{src/templates/default/.agents/skills/files-as-database → dist/templates/default/.agents/skills/storing-data}/SKILL.md

@@ -78,7 +78,7 @@ 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.
+For OAuth tokens acquired at runtime (Google, etc.). Never store these in settings — use the dedicated store.
 
 ```ts
 import { saveOAuthTokens, getOAuthTokens, listOAuthAccounts } from "@agent-native/core/oauth-tokens";
@@ -108,3 +108,9 @@ Infrastructure config stays in `.env` — these differ per deployment:
 - `ACCESS_TOKEN` — production auth token
 
 Everything else (user settings, tokens, app state) goes in SQL.
+
+## Security Rules
+
+- **Never store API keys or secrets in Settings or Application State** — use `.env` for API keys (gitignored) and the `oauth_tokens` store for OAuth credentials. Settings and application state are readable by the client.
+- **Every Drizzle table with user data must have `owner_email`** — the framework auto-scopes queries in production so users only see their own data. Run `pnpm action db-check-scoping` to verify. See the `security` skill for the full model.
+- **Never return secrets in action responses** — action responses may be visible in the agent chat or sent to the client. Keep credentials server-side only.

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

@@ -0,0 +1,100 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pnpm action view-screen 2>/dev/null || echo '{\"view\": \"unknown\"}'",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "NotebookEdit",
+      "WebFetch",
+      "WebSearch",
+      "Bash(ls *)",
+      "Bash(pwd)",
+      "Bash(echo *)",
+      "Bash(cat *)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(find *)",
+      "Bash(wc *)",
+      "Bash(sort *)",
+      "Bash(uniq *)",
+      "Bash(diff *)",
+      "Bash(which *)",
+      "Bash(env)",
+      "Bash(mkdir *)",
+      "Bash(cp *)",
+      "Bash(mv *)",
+      "Bash(touch *)",
+      "Bash(chmod *)",
+      "Bash(cd *)",
+      "Bash(node *)",
+      "Bash(npx *)",
+      "Bash(npm *)",
+      "Bash(pnpm *)",
+      "Bash(yarn *)",
+      "Bash(tsx *)",
+      "Bash(tsc *)",
+      "Bash(vitest *)",
+      "Bash(jest *)",
+      "Bash(eslint *)",
+      "Bash(prettier *)",
+      "Bash(git status*)",
+      "Bash(git log *)",
+      "Bash(git diff *)",
+      "Bash(git show *)",
+      "Bash(git branch*)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git checkout *)",
+      "Bash(git switch *)",
+      "Bash(git stash *)",
+      "Bash(git merge *)",
+      "Bash(git rebase *)",
+      "Bash(git pull *)",
+      "Bash(git blame *)",
+      "Bash(git rev-parse *)",
+      "Bash(git worktree *)",
+      "Bash(git remote -v)",
+      "Bash(gh *)",
+      "Bash(curl *)",
+      "Bash(grep *)",
+      "Bash(rg *)",
+      "Bash(sed *)",
+      "Bash(awk *)",
+      "Bash(jq *)",
+      "Bash(rm *)"
+    ],
+    "deny": [
+      "Bash(rm -rf /)",
+      "Bash(rm -rf /*)",
+      "Bash(rm -rf ~)",
+      "Bash(rm -rf ~/*)",
+      "Bash(sudo *)",
+      "Bash(git push --force *)",
+      "Bash(git push -f *)",
+      "Bash(git reset --hard *)",
+      "Bash(git clean -f *)",
+      "Bash(dd *)",
+      "Bash(mkfs *)",
+      "Bash(kill -9 *)",
+      "Bash(killall *)",
+      "Bash(pkill *)",
+      "Bash(shutdown *)",
+      "Bash(reboot *)"
+    ]
+  }
+}

package/dist/templates/default/.env.example

@@ -0,0 +1,5 @@
+# Server port (production)
+PORT=3000
+
+# Custom health check message
+PING_MESSAGE=pong

package/dist/templates/default/.prettierrc

@@ -0,0 +1,5 @@
+{
+  "tabWidth": 2,
+  "useTabs": false,
+  "trailingComma": "all"
+}

package/dist/templates/default/AGENTS.md

@@ -0,0 +1,110 @@
+# {{APP_NAME}} — Agent Guide
+
+This app follows the agent-native core philosophy: the agent and UI are equal partners. Everything the UI can do, the agent can do via actions. The agent always knows what you're looking at via application state. 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 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`, `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:
+
+- **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.
+
+## Resources
+
+Resources are SQL-backed persistent files for notes, learnings, and context.
+
+**At the start of every conversation, read these resources (both personal and shared scopes):**
+
+1. **`AGENTS.md`** -- user-specific context. Read both `--scope personal` and `--scope shared`.
+2. **`LEARNINGS.md`** -- user preferences, corrections, and patterns. Read both scopes.
+
+**Update `LEARNINGS.md` when you learn something important.**
+
+| 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       |
+
+## Application State
+
+Ephemeral UI state is stored in the SQL `application_state` table, accessed via `readAppState(key)` and `writeAppState(key, value)` from `@agent-native/core/application-state`.
+
+| State Key    | Purpose                                   | Direction                  |
+| ------------ | ----------------------------------------- | -------------------------- |
+| `navigation` | Current view                              | UI -> Agent (read-only)    |
+| `navigate`   | Navigate command (one-shot, auto-deleted) | Agent -> UI (auto-deleted) |
+
+The `navigation` key is written by the UI whenever the route changes. The `navigate` key is a one-shot command: the agent writes it, the UI reads and executes the navigation, then deletes it.
+
+## Agent Operations
+
+**Always know what the user is currently viewing before you edit anything.** The user's view can change mid-conversation. Stale IDs lead to editing the wrong record.
+
+### If you are the built-in agent-chat agent
+
+A `<current-screen>` block is auto-injected into every user message with the current view, IDs, and selected item. You can trust it for the first action of a turn without calling `view-screen`. If the user says "this" or "now do X" after several tool calls, the user may have navigated — call `view-screen` again for a fresh snapshot.
+
+### If you are an external CLI agent (Claude Code, Codex, Cursor, etc.)
+
+You do NOT get auto-injected screen state. **Call `pnpm action view-screen` at the start of every task and before any edit** so you're acting on the IDs the user currently sees, not what was open earlier. Do not rely on cached context from previous turns.
+
+### Actions
+
+| 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
+
+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                       |
+| `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  |
+
+## When Adding Features
+
+As you build out this app, follow this checklist for each new feature:
+
+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
+
+---
+
+For code editing and development guidance, read `DEVELOPING.md`.

package/dist/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)