@agent-native/core 0.6.1 → 0.7.1

package/docs/content/client.md

@@ -0,0 +1,175 @@
+---
+title: "Client"
+description: "React hooks and utilities for agent-native apps: sendToAgentChat, useDbSync, useAgentChatGenerating, and cn."
+---
+
+# Client
+
+`@agent-native/core` provides React hooks and utilities for the browser-side of agent-native apps.
+
+## File-Based Routing {#file-based-routing}
+
+Agent-native apps use **React Router v7** with file-based routing. Every file in `app/routes/` becomes a URL.
+
+### File → URL mapping
+
+| File                             | URL                                   |
+| -------------------------------- | ------------------------------------- |
+| `app/routes/_index.tsx`          | `/`                                   |
+| `app/routes/settings.tsx`        | `/settings`                           |
+| `app/routes/inbox/index.tsx`     | `/inbox`                              |
+| `app/routes/inbox/$threadId.tsx` | `/inbox/:threadId`                    |
+| `app/routes/inbox.$threadId.tsx` | `/inbox/:threadId` (flat alternative) |
+
+Prefix a segment with `$` for dynamic params. Prefix with `_` to make it a pathless layout route (doesn't add a URL segment). `_index.tsx` is the index route for its folder.
+
+### Adding a new page
+
+Create the file and export a default component:
+
+```tsx
+// app/routes/settings.tsx
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+That's it — React Router picks it up automatically, no registration needed.
+
+### Dynamic params
+
+```tsx
+// app/routes/inbox/$threadId.tsx
+import { useParams } from "react-router";
+
+export default function ThreadPage() {
+  const { threadId } = useParams();
+  return <div>Thread: {threadId}</div>;
+}
+```
+
+### Navigation
+
+Use `<Link>` for client-side navigation and `useNavigate()` for programmatic navigation:
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/settings">Settings</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/inbox/${threadId}`);
+```
+
+---
+
+## sendToAgentChat(opts) {#sendtoagentchat}
+
+Send a message to the agent chat via postMessage. Used to delegate AI tasks from UI interactions.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core";
+
+// Auto-submit a prompt with hidden context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+### AgentChatMessage {#agentchatmessage}
+
+| Option                | Type        | Description                                    |
+| --------------------- | ----------- | ---------------------------------------------- |
+| `message`             | `string`    | The visible prompt sent to the chat            |
+| `context`             | `string?`   | Hidden context appended (not shown in chat UI) |
+| `submit`              | `boolean?`  | true = auto-submit, false = prefill only       |
+| `projectSlug`         | `string?`   | Optional project slug for structured context   |
+| `preset`              | `string?`   | Optional preset name for downstream consumers  |
+| `referenceImagePaths` | `string[]?` | Optional reference image paths                 |
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+React hook that wraps sendToAgentChat with loading state tracking:
+
+```ts
+import { useAgentChatGenerating } from "@agent-native/core";
+
+function GenerateButton() {
+  const [isGenerating, send] = useAgentChatGenerating();
+
+  return (
+    <button
+      disabled={isGenerating}
+      onClick={() => send({
+        message: "Generate a summary",
+        context: documentContent,
+        submit: true,
+      })}
+    >
+      {isGenerating ? "Generating..." : "Generate"}
+    </button>
+  );
+}
+```
+
+`isGenerating` turns true when you call `send()` and automatically resets to false when the agent finishes generating.
+
+## useDbSync(options?) {#usedbsync}
+
+React hook (formerly `useFileWatcher`) that polls for database changes and invalidates react-query caches:
+
+```ts
+import { useDbSync } from "@agent-native/core";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    queryKeys: ["files", "projects", "versionHistory"],
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+### Options {#usedbsync-options}
+
+| Option        | Type             | Description                                                       |
+| ------------- | ---------------- | ----------------------------------------------------------------- |
+| `queryClient` | `QueryClient?`   | React-query client for cache invalidation                         |
+| `queryKeys`   | `string[]?`      | Query key prefixes to invalidate. Default: `["file", "fileTree"]` |
+| `pollUrl`     | `string?`        | Poll endpoint URL. Default: `"/_agent-native/poll"`               |
+| `onEvent`     | `(data) => void` | Optional callback for each SSE event                              |
+
+## cn(...inputs) {#cn}
+
+Utility for merging class names (clsx + tailwind-merge):
+
+```ts
+import { cn } from "@agent-native/core";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```

package/docs/content/context-awareness.md

@@ -0,0 +1,168 @@
+---
+title: "Context Awareness"
+description: "How the agent knows what the user is looking at: navigation state, view-screen, navigate commands, and jitter prevention."
+---
+
+# Context Awareness
+
+How the agent knows what the user is looking at — and how the agent can control what the user sees.
+
+## Overview {#overview}
+
+Without context awareness, the agent is blind. It asks "which email?" when the user is staring at one. It cannot act on the current selection, cannot provide relevant suggestions, and cannot modify what the user sees.
+
+Three patterns solve this:
+
+1. **Navigation state** — the UI writes a `navigation` key to application-state on every route change
+2. **`view-screen`** — an action that reads navigation state, fetches contextual data, and returns a snapshot of what the user sees
+3. **`navigate`** — a one-shot command from the agent that tells the UI where to go
+
+## Navigation state {#navigation-state}
+
+The UI writes a `navigation` key to application-state on every route change. This tells the agent what view the user is on and what item is selected.
+
+```json
+{
+  "view": "inbox",
+  "threadId": "thread-123",
+  "focusedEmailId": "msg-456",
+  "search": "budget",
+  "label": "important"
+}
+```
+
+What to include in navigation state:
+
+- `view` — the current page/section (e.g., "inbox", "form-builder", "dashboard")
+- Item IDs — the selected/open item (e.g., `threadId`, `formId`)
+- Filter state — active search, label, or category filters
+- Any selection — focused item, selected text range, active tab
+
+The agent reads this before acting:
+
+```ts
+import { readAppState } from "@agent-native/core/application-state";
+
+const navigation = await readAppState("navigation");
+// { view: "inbox", threadId: "thread-123", label: "important" }
+```
+
+## The view-screen action {#view-screen-action}
+
+Every template should have a `view-screen` action. It reads navigation state, fetches the relevant data, and returns a snapshot of what the user sees. This is the agent's eyes.
+
+```ts
+// actions/view-screen.ts
+import { readAppState } from "@agent-native/core/application-state";
+
+export default async function main() {
+  const navigation = await readAppState("navigation");
+  const screen: Record<string, unknown> = { navigation };
+
+  // Fetch data based on what the user is viewing
+  if (navigation?.view === "inbox") {
+    const res = await fetch(
+      "http://localhost:3000/api/emails?label=" + navigation.label,
+    );
+    screen.emailList = await res.json();
+  }
+  if (navigation?.threadId) {
+    const res = await fetch(
+      "http://localhost:3000/api/threads/" + navigation.threadId,
+    );
+    screen.thread = await res.json();
+  }
+
+  console.log(JSON.stringify(screen, null, 2));
+}
+```
+
+The agent should always call `pnpm action view-screen` before acting. This is a hard convention across all templates. When adding new features, update `view-screen` to return data for the new view.
+
+## The navigate action {#navigate-action}
+
+The agent writes a one-shot `navigate` command to application-state. The UI reads it, performs the navigation, and deletes the entry.
+
+```ts
+// Agent side — write a navigate command
+import { writeAppState } from "@agent-native/core/application-state";
+
+await writeAppState("navigate", { view: "inbox", threadId: "thread-123" });
+```
+
+The UI polls for this command and navigates when it appears:
+
+```ts
+// UI side — poll for navigate commands
+const { data: navCommand } = useQuery({
+  queryKey: ["navigate-command"],
+  queryFn: async () => {
+    const res = await fetch("/_agent-native/application-state/navigate");
+    if (!res.ok) return null;
+    const data = await res.json();
+    if (data) {
+      // Delete the one-shot command after reading
+      fetch("/_agent-native/application-state/navigate", { method: "DELETE" });
+      return data;
+    }
+    return null;
+  },
+  staleTime: 2_000,
+});
+
+useEffect(() => {
+  if (navCommand) {
+    router.navigate(buildPath(navCommand));
+  }
+}, [navCommand]);
+```
+
+The `navigation` key belongs to the UI — the agent should never write to it directly. Instead, the agent writes to `navigate`, and the UI performs the actual navigation (which then updates `navigation`).
+
+## useNavigationState hook {#use-navigation-state}
+
+The `use-navigation-state.ts` hook syncs routes to application-state on every navigation:
+
+```ts
+// app/hooks/use-navigation-state.ts
+import { useEffect } from "react";
+import { useLocation } from "react-router";
+
+export function useNavigationState() {
+  const location = useLocation();
+
+  useEffect(() => {
+    const state = deriveNavigationState(location.pathname);
+    fetch("/_agent-native/application-state/navigation", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(state),
+    }).catch(() => {});
+  }, [location.pathname]);
+}
+```
+
+The `deriveNavigationState()` function is template-specific — it parses the URL path and extracts the view, item IDs, and filters relevant to your app.
+
+## Jitter prevention {#jitter-prevention}
+
+When the agent writes to application-state, the polling system might cause the UI to refetch data it just wrote. This creates jitter. The solution is source tagging:
+
+```ts
+// app/root.tsx
+import { TAB_ID } from "@/lib/tab-id";
+
+useDbSync({
+  queryClient,
+  queryKeys: ["app-state", "settings"],
+  ignoreSource: TAB_ID, // ignore events from this tab's own writes
+});
+```
+
+How it works:
+
+- Agent writes are tagged with `requestSource: "agent"` (the action helpers do this automatically)
+- UI writes include the tab's unique ID via `X-Request-Source` header
+- The server stores the source on each event
+- When polling, the UI filters out events matching its own `ignoreSource` value — so it doesn't refetch data it just wrote
+- Events from agents, other tabs, and actions still come through normally

package/docs/content/creating-templates.md

@@ -0,0 +1,311 @@
+---
+title: "Creating Templates"
+description: "How to create and publish your own agent-native app templates."
+---
+
+# Creating Templates
+
+How to build and publish your own agent-native app template.
+
+## Overview {#overview}
+
+Templates are complete, forkable agent-native apps that solve a specific use case. The analytics, content, slides, and video templates that ship with Agent-Native are all built this way. Anyone can create a template and share it with the community.
+
+A good template:
+
+- Solves a real workflow end-to-end (not a toy demo)
+- Works out of the box with example data
+- Has a comprehensive `AGENTS.md` so the AI agent understands the architecture
+- Includes actions for key operations the agent can call
+- Follows the core rules: data in SQL, all AI through agent chat, actions for operations, real-time sync, agent can modify code
+
+## Start from the starter {#start-from-starter}
+
+The fastest way to start is with the built-in starter template:
+
+```bash
+npx @agent-native/core create my-template
+```
+
+This scaffolds a minimal agent-native app with the standard directory structure, a working dev server, file watching, SSE, and an example action. Build your template on top of this.
+
+## Project structure {#project-structure}
+
+Every template follows the same convention:
+
+```text
+my-template/
+  app/                # React frontend
+    routes/           # File-based page routes (auto-discovered)
+      _index.tsx      # / (home page)
+      settings.tsx    # /settings
+    root.tsx          # App shell — <html>, <head>, <body>, providers
+    entry.client.tsx  # Client hydration entry
+    routes.ts         # Route config — flatRoutes()
+    components/       # UI components
+    components/ui/    # Reusable primitives (shadcn/ui)
+    hooks/            # React hooks
+    lib/utils.ts      # cn() utility
+
+  server/             # Nitro API server
+    routes/           # File-based API routes (auto-discovered by Nitro)
+      [...page].get.ts # SSR catch-all (delegates to React Router)
+    plugins/          # Server plugins (startup logic)
+    lib/              # Shared server modules
+
+  shared/             # Isomorphic types (imported by client & server)
+    api.ts            # Shared interfaces
+
+  actions/            # Agent-callable actions
+    run.ts            # Action dispatcher (don't modify)
+    *.ts              # Your actions — one per operation
+
+  data/               # File-based state (watched by SSE)
+    .gitkeep          # Or seed data for the template
+
+  .agents/skills/     # Agent skills — detailed guidance per topic
+
+  AGENTS.md           # Master agent instructions
+  react-router.config.ts # React Router config (ssr, appDirectory)
+  package.json        # Scripts: dev, build, start, action, typecheck
+  vite.config.ts      # Vite config (React Router + Nitro)
+  tsconfig.json       # TypeScript config
+```
+
+## Build your client {#build-your-client}
+
+The client uses React Router v7 framework mode with file-based routing. Pages go in `app/routes/`, global providers live in `app/root.tsx`, and React Query handles data fetching.
+
+```ts
+// app/root.tsx — App shell with providers
+import { Links, Meta, Outlet, Scripts, ScrollRestoration } from "react-router";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useDbSync } from "@agent-native/core";
+
+const queryClient = new QueryClient();
+
+export function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        {children}
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}
+
+export default function Root() {
+  useDbSync({ queryClient, queryKeys: ["items", "projects"] });
+  return (
+    <QueryClientProvider client={queryClient}>
+      <Outlet />
+    </QueryClientProvider>
+  );
+}
+```
+
+Routes are auto-discovered from `app/routes/` via `flatRoutes()`. Create a file to add a page:
+
+```ts
+// app/routes/_index.tsx → /
+export default function Dashboard() {
+  return <div>Home page</div>;
+}
+
+// app/routes/settings.tsx → /settings
+export default function Settings() {
+  return <div>Settings page</div>;
+}
+```
+
+The `useDbSync` hook (formerly `useFileWatcher`) polls `/_agent-native/poll` and invalidates react-query caches when data changes. This is how the UI stays in sync when the agent modifies data.
+
+## Add API routes {#add-api-routes}
+
+API routes serve data from files and handle mutations. They go in `server/routes/` as file-based routes:
+
+```ts
+// server/routes/api/items/index.get.ts
+import { defineEventHandler } from "h3";
+import { readdir, readFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+
+export default defineEventHandler(async () => {
+  const dir = "./data/items";
+  await mkdir(dir, { recursive: true });
+  const files = await readdir(dir);
+  return Promise.all(
+    files
+      .filter((f) => f.endsWith(".json"))
+      .map(async (f) => {
+        const content = await readFile(path.join(dir, f), "utf-8");
+        return JSON.parse(content);
+      }),
+  );
+});
+```
+
+Each route file exports a default `defineEventHandler`. Both the UI and the agent can create items — the UI via `POST /api/items`, the agent by writing directly to `data/items/`. The SSE watcher ensures both paths trigger UI updates.
+
+## Add actions {#add-actions}
+
+Actions are the agent's toolbox. Each action handles one operation — fetching data from an API, generating content, processing files, etc:
+
+```typescript
+// actions/import-data.ts
+import { parseArgs } from "@agent-native/core";
+import { writeFile, mkdir } from "node:fs/promises";
+
+export default async function importData(args: string[]) {
+  const { url, name } = parseArgs(args);
+  if (!url) {
+    console.error("--url is required");
+    process.exit(1);
+  }
+
+  const res = await fetch(url);
+  const data = await res.json();
+
+  const slug = name ?? "imported";
+  await mkdir("./data/imports", { recursive: true });
+  await writeFile(`./data/imports/${slug}.json`, JSON.stringify(data, null, 2));
+  console.log(
+    `Imported ${Array.isArray(data) ? data.length + " records" : "data"} to data/imports/${slug}.json`,
+  );
+}
+```
+
+```bash
+# The agent can run this
+pnpm action import-data --url https://api.example.com/data --name users
+```
+
+Scripts should write their output to `data/` — the SSE watcher will notify the UI. Use `console.log` for output the agent can see. Use `console.error` and `process.exit(1)` for errors.
+
+## Add data models {#add-data-models}
+
+Seed your template with example data so it works immediately. Put JSON files in `data/` matching the structure your API routes expect:
+
+```text
+data/
+  items/
+    example-1.json     # {"id": "example-1", "title": "...", "status": "active"}
+    example-2.json
+  config.json          # App-level config
+  sync-config.json     # (optional) Firestore sync glob patterns
+```
+
+Keep your data models simple — flat JSON files, one per entity. The agent can grep, read, and modify them. Deeply nested structures or binary formats make it harder for the agent to work with the data.
+
+## Write AGENTS.md {#write-agents-md}
+
+This is the most important file in your template. `AGENTS.md` tells the AI agent how your app works, what it can and can't do, and how to make changes:
+
+````markdown
+# My Template — Agent-Native App
+
+## Architecture
+
+This is an **@agent-native/core** application.
+
+### Core Principles
+
+1. **Data lives in SQL** — All state in SQL via Drizzle ORM.
+2. **All AI through agent chat** — No inline LLM calls.
+3. **Actions for operations** — `pnpm action <name>` for complex work.
+4. **Real-time sync** — Polling keeps UI in sync with agent changes.
+5. **Agent can update code** — Edit components, routes, actions.
+
+### Directory Structure
+
+```
+app/             # React frontend (file-based routing in app/routes/)
+server/          # Nitro API server
+actions/         # Agent-callable actions
+data/            # File-based state
+```
+
+### Available Actions
+
+- `pnpm action import-data --url <url>` — Import data from API
+- `pnpm action generate-report --id <id>` — Generate a report
+
+### Data Model
+
+Items are stored as `data/items/<id>.json`:
+
+```json
+{ "id": "...", "title": "...", "status": "active" }
+```
+
+### Key Patterns
+
+- API routes in `server/routes/` serve files from `data/`
+- UI delegates AI work via `sendToAgentChat()`
+- Actions write results to `data/` — SSE updates the UI
+````
+
+Be specific about your data models, available actions, and key patterns. The better your `AGENTS.md`, the better the agent will work with your template.
+
+## Add skills {#add-skills}
+
+For complex topics that don't fit in `AGENTS.md`, create skills in `.agents/skills/`. Each skill is a Markdown file with detailed guidance for a specific topic:
+
+```markdown
+# .agents/skills/bigquery/SKILL.md
+
+## BigQuery Integration
+
+### Column Reference
+
+- `event_name` — The event type (string)
+- `event_timestamp` — Microsecond timestamp (int64)
+- `user_pseudo_id` — Anonymous user ID (string)
+
+### Common Queries
+
+...
+
+### Gotchas
+
+- Always use `event_date` partition filter to avoid full table scans
+- Timestamps are in microseconds, not milliseconds
+```
+
+Skills let you give the agent deep domain knowledge for specific integrations or patterns without bloating your main `AGENTS.md`.
+
+## Onboarding & API keys {#onboarding}
+
+If your template needs API keys or external service configuration, document them in a `.env.example` file:
+
+```bash
+# .env.example
+BIGQUERY_PROJECT_ID=your-project-id
+STRIPE_SECRET_KEY=sk_live_...
+OPENAI_API_KEY=sk-...
+```
+
+When users fork your template, they copy `.env.example` to `.env` and fill in their own values. Keep the number of required keys minimal — the template should work with example data before any keys are configured.
+
+## Publishing {#publishing}
+
+To share your template:
+
+1. Push your template to a public GitHub repo
+2. Make sure it works with `pnpm install && pnpm dev`
+3. Include seed data in `data/` so it works without API keys
+4. Write a clear README explaining what the template does and how to configure it
+
+Community templates can be shared via GitHub. The agent-native CLI supports creating from any git repo:
+
+```bash
+npx @agent-native/core create my-app --template github:user/repo
+```