From 42e6851d6b4e8168afe11f417b57e40817b68d4e Mon Sep 17 00:00:00 2001 From: "Builder.io" Date: Wed, 25 Mar 2026 02:16:54 +0000 Subject: [PATCH] docs: update LLMs.txt with current Builder CLI naming and Nitro backend --- packages/docs/public/llms-full.txt | 860 +++++++++++++++++++---------- packages/docs/public/llms.txt | 104 ++-- 2 files changed, 635 insertions(+), 329 deletions(-) diff --git a/packages/docs/public/llms-full.txt b/packages/docs/public/llms-full.txt index af740581..14a41223 100644 --- a/packages/docs/public/llms-full.txt +++ b/packages/docs/public/llms-full.txt @@ -1,279 +1,581 @@ -# Agent-Native — Complete Documentation - -> Framework for building AI-native applications where agents and UI share state through files. - -Agent-Native is an open source framework for building full-featured applications powered by AI agents. Apps are React frontends with Express backends. All state lives in files — the agent and UI read/write the same source of truth. - ---- - -# Getting Started - -## Installation - -```bash -npx @agent-native/core create my-app -``` - -## Project Structure - -``` -my-app/ - client/ # React frontend (Vite SPA) - App.tsx # Entry point - components/ # UI components - lib/utils.ts # cn() utility - server/ # Express backend - index.ts # createAppServer() - node-build.ts # Production entry point - shared/ # Isomorphic code (client & server) - scripts/ # Agent-callable scripts - run.ts # Script dispatcher - data/ # App data files (watched by SSE) -``` - -## Vite Configuration - -```ts -// vite.config.ts -import { defineConfig } from "@agent-native/core/vite"; -export default defineConfig(); -``` - -```ts -// vite.config.server.ts -import { defineServerConfig } from "@agent-native/core/vite"; -export default defineServerConfig(); -``` - -## TypeScript & Tailwind - -```json -// tsconfig.json -{ "extends": "@agent-native/core/tsconfig.base.json" } -``` - -```ts -// tailwind.config.ts -import type { Config } from "tailwindcss"; -import preset from "@agent-native/core/tailwind"; - -export default { - presets: [preset], - content: ["./client/**/*.{ts,tsx}"], -} satisfies Config; -``` - -## Subpath Exports - -| Import | Exports | -|--------|---------| -| `@agent-native/core` | createServer, createFileWatcher, createSSEHandler, createProductionServer, runScript, parseArgs, loadEnv, fail, agentChat, sendToAgentChat, useAgentChatGenerating, useFileWatcher, cn | -| `@agent-native/core/vite` | defineConfig(), defineServerConfig() | -| `@agent-native/core/tailwind` | Tailwind preset (HSL colors, shadcn/ui tokens, animations) | -| `@agent-native/core/adapters/firestore` | FileSync, threeWayMerge, loadSyncConfig | - -## Architecture Principles - -1. **Files as database** — All app state lives in files. Both UI and agent read/write the same files. -2. **All AI through agent chat** — No inline LLM calls. UI delegates to the AI via `sendToAgentChat()`. -3. **Scripts for agent ops** — `pnpm script ` dispatches to callable script files. -4. **Bidirectional SSE events** — File watcher keeps UI in sync with agent changes in real-time. -5. **Agent can update code** — The agent modifies the app itself. - ---- - -# Server API - -## createServer(options?) - -Creates a pre-configured Express app with standard middleware (cors, json, urlencoded, /api/ping). - -```ts -import { createServer } from "@agent-native/core"; -const app = createServer(); -``` - -Options: `cors` (CorsOptions | false), `jsonLimit` (string, default "50mb"), `pingMessage` (string), `disablePing` (boolean). - -## createFileWatcher(dir, options?) - -Creates a chokidar file watcher for real-time file change detection. - -```ts -import { createFileWatcher } from "@agent-native/core"; -const watcher = createFileWatcher("./data"); -``` - -Options: `ignored` (glob/regex), `emitInitial` (boolean, default false). - -## createSSEHandler(watcher, options?) - -Creates an Express route handler that streams file changes as Server-Sent Events. - -```ts -app.get("/api/events", createSSEHandler(watcher)); -``` - -Each SSE message: `{ "type": "change", "path": "data/file.json" }` - -Options: `extraEmitters` (Array<{ emitter, event }>). - -## createProductionServer(app, options?) - -Starts a production server with SPA fallback and graceful shutdown. - -```ts -import { createProductionServer } from "@agent-native/core"; -createProductionServer(createAppServer()); -``` - -Options: `port` (number/string, default 3000), `spaDir` (string, default "dist/spa"), `appName` (string). - ---- - -# Client Hooks & Utilities - -## sendToAgentChat(opts) - -Send a message to the agent chat via postMessage. - -```ts -import { sendToAgentChat } from "@agent-native/core"; - -sendToAgentChat({ - message: "Generate alt text for this image", - context: "Image path: /api/projects/hero.jpg", - submit: true, -}); -``` - -AgentChatMessage fields: `message` (string), `context` (string?), `submit` (boolean?), `projectSlug` (string?), `preset` (string?), `referenceImagePaths` (string[]?). - -## useAgentChatGenerating() - -React hook with loading state tracking. - -```tsx -const [isGenerating, send] = useAgentChatGenerating(); -``` - -## useFileWatcher(options?) - -React hook that connects to SSE endpoint and invalidates react-query caches on file changes. - -```tsx -useFileWatcher({ - queryClient, - queryKeys: ["files", "projects"], - eventsUrl: "/api/events", - onEvent: (data) => console.log("File changed:", data), -}); -``` - -## cn(...inputs) - -Utility for merging class names (clsx + tailwind-merge). - ---- - -# Scripts - -## Script Dispatcher - -```ts -// scripts/run.ts -import { runScript } from "@agent-native/core"; -runScript(); -``` - -```ts -// scripts/hello.ts -import { parseArgs } from "@agent-native/core"; - -export default async function hello(args: string[]) { - const { name } = parseArgs(args); - console.log(`Hello, ${name ?? "world"}!`); -} -``` - -```bash -pnpm script hello --name Steve -``` - -## parseArgs(args) - -Parse `--key value` or `--key=value` format arguments. - -## Shared Agent Chat - -Isomorphic chat bridge for browser and Node.js: - -```ts -import { agentChat } from "@agent-native/core"; -agentChat.submit("Generate a report for Q4"); -agentChat.prefill("Draft an email to...", contextData); -``` - -## Utility Functions - -- `loadEnv(path?)` — Load .env file -- `camelCaseArgs(args)` — Convert kebab-case keys to camelCase -- `isValidPath(p)` — Validate relative path -- `isValidProjectPath(p)` — Validate project slug -- `ensureDir(dir)` — mkdir -p helper -- `fail(message)` — Print error and exit(1) - -## Firestore Adapter - -Bidirectional file sync with three-way merge: - -```ts -import { FileSync } from "@agent-native/core/adapters/firestore"; -const sync = new FileSync({ appId, ownerId, contentRoot, getFileCollection }); -await sync.initFileSync(); -``` - ---- - -# Harnesses - -Apps run inside a **harness** — a host that provides the AI agent alongside your app UI. - -## CLI Harness (Local, Open Source) - -- xterm.js terminal + app iframe -- Supports Claude Code, Codex, Gemini CLI, OpenCode — switchable from settings -- Auto-installs missing CLIs, per-CLI launch flags -- Best for: solo development, testing - -## Builder Harness (Cloud) - -- Real-time collaboration -- Visual editing + AI agent -- Parallel agent execution -- Best for: teams, production - -## Protocol - -1. **Agent chat** — use `sendToAgentChat()` to send messages to the agent -2. **Generation state** — use `useAgentChatGenerating()` to track when the agent is running -3. **File watching** — SSE keeps UI in sync -4. **Script system** — `pnpm script ` dispatches to scripts - -App code is identical regardless of harness or CLI. - ---- - -# Templates - -## Analytics -BI platform with 20+ data connectors (BigQuery, HubSpot, Stripe, Jira, Sentry, GitHub, Slack, Grafana, Google Cloud, etc.), SQL query explorer, reusable dashboards, 550+ metric data dictionary, 50+ pre-built scripts, and natural language chart generation. - -## Content -Content workspace with project/document organization, rich text editor, brand-aware AI writing, media management, CMS publishing (WordPress, Contentful, Builder), real-time sync via SSE, and script automation for batch operations. - -## Slides -AI presentation builder with 8 slide layouts (title, section, content, two-column, image, statement, full-bleed, blank), Gemini image generation with style references, logo/image search, drag-drop reordering, presentation mode with speaker notes, sharing, and undo/redo. - -## Video -Video composition studio built on Remotion with track-based animation (duration, keyframe, expression tracks), 30+ easing curves, multi-keyframe editing, interactive cursor system (arrow, pointer, I-beam), 6D camera controls (pan, zoom, 3D tilt), and 12 example compositions. Renders to MP4/WebM at 1920x1080, 30fps. +# Agent-Native — Complete Documentation + +> Framework for building AI-native applications where agents and UI share state through files. + +Agent-Native is an open source framework for building full-featured applications powered by AI agents. Apps are React frontends with Nitro backends. All state lives in files — the agent and UI read/write the same source of truth. + +--- + +# Getting Started + +## Installation + +Create a new project: + + +npx @agent-native/core create my-app +``` + +Or fork a specific template: + +```bash +npx @agent-native/core create my-app --template mail +``` + +## Project Structure + +Every agent-native app follows the same convention: + +``` +my-app/ + 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) + settings.tsx # /settings + components/ # UI components + lib/utils.ts # cn() utility + 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 + shared/ # Isomorphic code (client & server) + scripts/ # Agent-callable scripts + run.ts # Script dispatcher + data/ # App data files (watched by SSE) + react-router.config.ts # React Router framework config +``` + +## Vite Configuration + +A single config file handles both client and server build: + +```ts +// vite.config.ts +import { defineConfig } from "@agent-native/core/vite"; + +export default defineConfig({ + reactRouter: true, +}); +``` + +`defineConfig()` sets up React Router framework mode (SSR + file-based routing), path aliases (`@/` → `app/`, `@shared/` → `shared/`), and the Nitro server plugin (file-based API routing, server plugins, deploy-anywhere presets). + +### Nitro options + +```ts +export default defineConfig({ + reactRouter: true, + nitro: { + preset: "vercel", // Deploy target (default: "node") + }, +}); +``` + +## TypeScript & Tailwind + +```json +// tsconfig.json +{ "extends": "@agent-native/core/tsconfig.base.json" } +``` + +```ts +// tailwind.config.ts +import type { Config } from "tailwindcss"; +import preset from "@agent-native/core/tailwind"; + +export default { + presets: [preset], + content: ["./app/**/*.{ts,tsx}"], +} satisfies Config; +``` + +## Subpath Exports + +| Import | Exports | +|--------|---------| +| `@agent-native/core` | Server: `createServer`, `createFileWatcher`, `createSSEHandler`, `mountAuthMiddleware`, `createProductionAgentHandler` · Client: `sendToAgentChat`, `useAgentChatGenerating`, `useFileWatcher`, `useProductionAgent`, `ProductionAgentPanel`, `cn` · Scripts: `runScript`, `parseArgs`, `loadEnv`, `fail`, `agentChat` | +| `@agent-native/core/router` | React Router re-exports: `Link`, `NavLink`, `Outlet`, `useNavigate`, `useParams`, `useLoaderData`, `redirect`, `Form`, `Links`, `Meta`, `Scripts`, `ScrollRestoration` | +| `@agent-native/core/vite` | `defineConfig()` | +| `@agent-native/core/tailwind` | Tailwind preset (HSL colors, shadcn/ui tokens, animations) | +| `@agent-native/core/db` | `getDb()` — Drizzle ORM factory (SQLite via @libsql/client, local or cloud via `DATABASE_URL`) | +| `@agent-native/core/adapters/sync` | `createFileSync`, `FileSync`, `FileSyncAdapter` interface, `FileRecord`, `FileChange` types | +| `@agent-native/core/adapters/firestore` | `FirestoreFileSyncAdapter`, `threeWayMerge`, `loadSyncConfig` | +| `@agent-native/core/adapters/supabase` | `SupabaseFileSyncAdapter`, `threeWayMerge`, `loadSyncConfig` | +| `@agent-native/core/adapters/convex` | `ConvexFileSyncAdapter`, `threeWayMerge`, `loadSyncConfig` | + +## Architecture Principles + +1. **Files as database** — All app state lives in files. Both UI and agent read/write the same files. +2. **All AI through agent chat** — No inline LLM calls. UI delegates to the AI via `sendToAgentChat()`. +3. **Scripts for agent ops** — `pnpm script ` dispatches to callable script files. +4. **Bidirectional SSE events** — File watcher keeps UI in sync with agent changes in real-time. +5. **Agent can update code** — The agent modifies the app itself. +6. **Application state as files** — Ephemeral UI state lives in `application-state/` as JSON. Both agent and UI can read and write these files; the SSE watcher covers this directory too. +7. **Deploy anywhere** — Nitro presets let you deploy to Node.js, Vercel, Netlify, Cloudflare, AWS Lambda, Deno, and more with a single config change. + +--- + +# Routing + +Agent-native apps use **React Router v7 framework mode** with file-based routing. Pages are auto-discovered from `app/routes/` via `flatRoutes()`. + +## Architecture: SSR Shell + Client Rendering + +Even though SSR is enabled, virtually every route renders only an SSR shell (loading spinner, optional meta tags). All real data fetching and rendering happens on the client via React Query hooks. + +## Adding a Page + +Create a file in `app/routes/`. The filename determines the URL path: + +``` +app/routes/ + _index.tsx → / + about.tsx → /about + settings.tsx → /settings + inbox.$threadId.tsx → /inbox/:threadId +``` + +## Default Route Pattern (95% of routes) + +```tsx +// app/routes/settings.tsx +import Settings from "@/pages/Settings"; + +export function meta() { + return [{ title: "Settings — My App" }]; +} + +export function HydrateFallback() { + return
+
+
; +} + +export default function SettingsRoute() { + return ; +} +``` + +## Build Commands + +```bash +pnpm dev # Vite dev server +pnpm build # react-router build (client + SSR + Nitro) +pnpm start # node .output/server/index.mjs +pnpm typecheck # react-router typegen && tsc --noEmit +``` + +--- + +# Server API + +Agent-native apps use [Nitro](https://nitro.build) for the server layer, included automatically via `defineConfig()`. + +## File-Based Routing + +API routes live in `server/routes/`. Nitro auto-discovers them based on file name: + +``` +server/routes/ + api/ + hello.get.ts → GET /api/hello + items/ + index.get.ts → GET /api/items + index.post.ts → POST /api/items + [id].get.ts → GET /api/items/:id + [id].delete.ts → DELETE /api/items/:id +``` + +Each route file exports a default `defineEventHandler`: + +```ts +// server/routes/api/items/index.get.ts +import { defineEventHandler } from "h3"; +import fs from "fs/promises"; + +export default defineEventHandler(async () => { + const files = await fs.readdir("./data/items"); + const items = await Promise.all( + files + .filter((f) => f.endsWith(".json")) + .map(async (f) => + JSON.parse(await fs.readFile(`./data/items/${f}`, "utf-8")), + ), + ); + return items; +}); +``` + +## createFileWatcher(dir, options?) + +Creates a chokidar file watcher for real-time file change detection: + +```ts +import { createFileWatcher } from "@agent-native/core"; + +const watcher = createFileWatcher("./data"); +``` + +Options: `ignored` (glob/regex), `emitInitial` (boolean, default false). + +## createSSEHandler(watcher, options?) + +Creates an H3 event handler that streams file changes as Server-Sent Events: + +```ts +// server/routes/api/events.get.ts +import { createSSEHandler } from "@agent-native/core"; +import { watcher, sseExtraEmitters } from "../../lib/watcher.js"; + +export default createSSEHandler(watcher, { + extraEmitters: sseExtraEmitters, + contentRoot: "./data", +}); +``` + +Each SSE message: `{ "type": "change", "path": "data/file.json" }` + +Options: `extraEmitters` (Array<{ emitter, event }>), `contentRoot` (string — root used to relativize paths in events). + +## createServer(options?) + +Optional helper that creates a pre-configured H3 app with CORS middleware and a health-check route. Returns `{ app, router }`. Useful for programmatic route registration in server plugins: + +```ts +import { createServer } from "@agent-native/core"; + +const { app, router } = createServer(); +``` + +Options: `cors` (Record | false), `pingMessage` (string), `disablePing` (boolean), `envKeys` (EnvKeyConfig[] — enables `/api/env-status` and `/api/env-vars` routes). + +## mountAuthMiddleware(app, accessToken) + +Mounts session-cookie authentication onto an H3 app. Serves a login page for unauthenticated browser requests and returns 401 for unauthenticated API requests. + +```ts +import { mountAuthMiddleware } from "@agent-native/core"; + +mountAuthMiddleware(app, process.env.ACCESS_TOKEN!); +``` + +Adds `POST /api/auth/login` and `POST /api/auth/logout` routes automatically. + +## createProductionAgentHandler(options) + +Creates an H3 SSE handler at `POST /api/agent-chat` that runs an agentic tool loop using Claude. Each script's `run()` function is registered as a tool the agent can invoke. + +```ts +import { createProductionAgentHandler } from "@agent-native/core"; +import { scripts } from "./scripts/registry.js"; +import { readFileSync } from "fs"; + +const agent = createProductionAgentHandler({ + scripts, + systemPrompt: readFileSync("agents/system-prompt.md", "utf-8"), +}); +``` + +Options: `scripts` (Record), `systemPrompt` (string), `apiKey` (string, default: `ANTHROPIC_API_KEY`), `model` (string, default: `claude-sonnet-4-6`). + +## Server Plugins + +Cross-cutting concerns go in `server/plugins/`. Nitro runs these at startup: + +```ts +// server/plugins/file-sync.ts +import { defineNitroPlugin } from "@agent-native/core"; +import { createFileSync } from "@agent-native/core/adapters/sync"; + +export default defineNitroPlugin(async () => { + const result = await createFileSync({ contentRoot: "./data" }); + if (result.status === "error") { + console.warn(`[app] File sync failed: ${result.reason}`); + } +}); +``` + +--- + +# Client Hooks & Utilities + +## sendToAgentChat(opts) + +Send a message to the agent chat via postMessage. + +```ts +import { sendToAgentChat } from "@agent-native/core"; + +sendToAgentChat({ + message: "Generate alt text for this image", + context: "Image path: /api/projects/hero.jpg", + submit: true, +}); +``` + +AgentChatMessage fields: `message` (string), `context` (string?), `submit` (boolean?), `projectSlug` (string?), `preset` (string?), `referenceImagePaths` (string[]?). + +## useAgentChatGenerating() + +React hook with loading state tracking: + +```tsx +const [isGenerating, send] = useAgentChatGenerating(); +``` + +`isGenerating` turns true when you call `send()` and automatically resets to false when the agent finishes. + +## useFileWatcher(options?) + +React hook that connects to the SSE endpoint and invalidates react-query caches on file changes: + +```tsx +useFileWatcher({ + queryClient, + queryKeys: ["files", "projects"], + eventsUrl: "/api/events", + onEvent: (data) => console.log("File changed:", data), +}); +``` + +Options: `queryClient` (QueryClient?), `queryKeys` (string[]?), `eventsUrl` (string?, default: "/api/events"), `onEvent` ((data) => void). + +## cn(...inputs) + +Utility for merging class names (clsx + tailwind-merge). + +--- + +# Scripts + +## Script Dispatcher + +```ts +// scripts/run.ts +import { runScript } from "@agent-native/core"; +runScript(); +``` + +```ts +// scripts/hello.ts +import { parseArgs } from "@agent-native/core"; + +export default async function hello(args: string[]) { + const { name } = parseArgs(args); + console.log(`Hello, ${name ?? "world"}!`); +} +``` + +```bash +pnpm script hello --name Steve +``` + +## parseArgs(args) + +Parse `--key value` or `--key=value` format arguments. + +## Shared Agent Chat + +Isomorphic chat bridge for browser and Node.js: + +```ts +import { agentChat } from "@agent-native/core"; + +agentChat.submit("Generate a report for Q4"); +agentChat.prefill("Draft an email to...", contextData); +``` + +In the browser, messages are sent via `window.postMessage()`. In Node.js (scripts), they use the `BUILDER_PARENT_MESSAGE:` stdout format. + +## Utility Functions + +- `loadEnv(path?)` — Load .env file +- `camelCaseArgs(args)` — Convert kebab-case keys to camelCase +- `isValidPath(p)` — Validate relative path +- `isValidProjectPath(p)` — Validate project slug +- `ensureDir(dir)` — mkdir -p helper +- `fail(message)` — Print error and exit(1) + +## Production Scripts (run() export) + +Scripts used by the embedded production agent must export a `tool` definition and a `run()` function: + +```ts +import type { ScriptTool } from "@agent-native/core"; + +export const tool: ScriptTool = { + description: "Archive an email by ID", + parameters: { + type: "object", + properties: { + id: { type: "string", description: "Email ID to archive" }, + }, + required: ["id"], + }, +}; + +export async function run(args: Record): Promise { + const result = await archiveEmail(args.id); + return `Archived email ${args.id}`; +} + +export default async function main(args: string[]) { + const { id } = parseArgs(args); + await archiveEmail(id); +} +``` + +Register all production scripts in a registry: + +```ts +// scripts/registry.ts +import type { ScriptEntry } from "@agent-native/core"; +import * as archiveEmail from "./archive-email.js"; + +export const scripts: Record = { + "archive-email": { tool: archiveEmail.tool, run: archiveEmail.run }, +}; +``` + +## File Sync + +For multi-user collaboration, agent-native provides a `createFileSync()` factory and adapters for **Firestore**, **Supabase**, and **Convex**. File sync is opt-in (`FILE_SYNC_ENABLED=true`). + +| Variable | Required | Description | +|----------|----------|-------------| +| `FILE_SYNC_ENABLED` | No | Set to `"true"` to enable sync | +| `FILE_SYNC_BACKEND` | When enabled | `"firestore"`, `"supabase"`, or `"convex"` | +| `SUPABASE_URL` | For Supabase | Project URL | +| `SUPABASE_PUBLISHABLE_KEY` | For Supabase | Publishable (anon) key | +| `GOOGLE_APPLICATION_CREDENTIALS` | For Firestore | Path to service account JSON | +| `CONVEX_URL` | For Convex | Deployment URL | + +--- + +# Deployment + +## Database + +By default, apps use local SQLite (`file:./data/app.db`). For production, set `DATABASE_URL`: + +| Provider | `DATABASE_URL` format | +|----------|-----------------------| +| SQLite (local) | `file:./data/app.db` (default) | +| Turso | `libsql://your-db.turso.io` | +| Neon | `libsql://...` | +| Cloudflare D1 | No URL needed — uses `DB` binding automatically | + +For Turso/Neon, also set `DATABASE_AUTH_TOKEN`. + +## Node.js (Default) + +```bash +pnpm build +pnpm start # or: node build/server/index.js +``` + +## Cloudflare Workers + +```bash +NITRO_PRESET=cloudflare_pages pnpm build +npx wrangler deploy +``` + +## Environment Variables + +| Variable | Description | +|----------|-------------| +| `PORT` | Server port (Node.js only) | +| `DATABASE_URL` | Database connection URL | +| `DATABASE_AUTH_TOKEN` | Auth token (Turso/Neon) | +| `NITRO_PRESET` | Edge target (build time only) | +| `ANTHROPIC_API_KEY` | API key for production agent | + +--- + +# Harnesses + +Apps run inside a **harness** — a host that provides the AI agent alongside your app UI. + +## CLI Harness (Local, Open Source) + +- Open source, ships with `@agent-native/harness-cli` +- Runs locally — xterm.js terminal + app iframe +- Supports multiple AI coding CLIs — switch between them from the settings panel + +| CLI | Command | +|-----|---------| +| Claude Code | `claude` | +| Codex | `codex` | +| Gemini CLI | `gemini` | +| OpenCode | `opencode` | +| Builder.io | `fusion` | + +- Auto-installs missing CLIs on first use +- Best for: solo development, testing + +## Builder.io Cloud Harness + +- Real-time collaboration — multiple users can watch/interact simultaneously +- Visual editing, roles and permissions +- Parallel agent execution +- Best for: teams, production + +## Protocol + +1. **Agent chat** — use `sendToAgentChat()` to send messages to the agent +2. **Generation state** — use `useAgentChatGenerating()` to track when the agent is running +3. **File watching** — SSE keeps UI in sync +4. **Script system** — `pnpm script ` dispatches to scripts + +App code is identical regardless of harness or CLI. + +--- + +# Templates + +## Mail +Superhuman-style email client with keyboard shortcuts, AI triage, smart search, and a fully customizable interface. Own your inbox workflow. + +```bash +npx @agent-native/core create my-app --template mail +``` + +## Calendar +Calendar app with Google Calendar sync (OAuth 2.0), Calendly-style public booking page, configurable availability, and natural language scheduling. + +```bash +npx @agent-native/core create my-app --template calendar +``` + +## Analytics +BI platform with 20+ data connectors (BigQuery, HubSpot, Stripe, Jira, Sentry, GitHub, Slack, Grafana, etc.), SQL query explorer, reusable dashboards, 550+ metric data dictionary, 50+ pre-built scripts, and natural language chart generation. + +```bash +npx @agent-native/core create my-app --template analytics +``` + +## Content +Content workspace with project/document organization, rich text editor, brand-aware AI writing, media management, CMS publishing (WordPress, Contentful, Builder), real-time sync via SSE, and script automation for batch operations. + +```bash +npx @agent-native/core create my-app --template content +``` + +## Slides +AI presentation builder with 8 slide layouts (title, section, content, two-column, image, statement, full-bleed, blank), image generation with style references, logo/image search, drag-drop reordering, presentation mode with speaker notes, sharing, and undo/redo. + +```bash +npx @agent-native/core create my-app --template slides +``` + +## Video +Video composition studio built on Remotion with track-based animation (duration, keyframe, expression tracks), 30+ easing curves, multi-keyframe editing, interactive cursor system, 6D camera controls, and 12 example compositions. Renders to MP4/WebM at 1920x1080, 30fps. + +```bash +npx @agent-native/core create my-app --template video diff --git a/packages/docs/public/llms.txt b/packages/docs/public/llms.txt index 4b9401ca..368267ca 100644 --- a/packages/docs/public/llms.txt +++ b/packages/docs/public/llms.txt @@ -1,50 +1,54 @@ -# Agent-Native - -> Framework for building AI-native applications where agents and UI share state through files. - -Agent-Native is an open source framework for building full-featured applications powered by AI agents. Apps are React frontends with Express backends. All state lives in files — the agent and UI read/write the same source of truth. No traditional database needed. - -## Key Concepts - -- **Files as Database**: All app state lives in JSON/markdown files. Agent and UI share the same source of truth. -- **AI Through the Agent**: No inline LLM calls. The UI delegates to the agent via a chat bridge (`sendToAgentChat()`). -- **Agent Updates Code**: The agent can modify the app itself. Your tools get better over time. -- **Real-time Sync**: File watcher streams changes via SSE. When the agent writes a file, the UI updates instantly. -- **Scripts System**: Agent-callable scripts via `pnpm script ` for complex operations. -- **Harnesses**: Apps run inside a harness (CLI harness supporting Claude Code, Codex, Gemini, OpenCode — or Builder.io Cloud) that provides the AI agent alongside your UI. - -## Quick Start - -```bash -npx @agent-native/core create my-app --template analytics -cd my-app -pnpm install -pnpm dev -``` - -## Templates - -- **Analytics**: BI platform with 20+ data connectors, SQL query explorer, dashboards, data dictionary -- **Content**: Content workspace with brand-aware AI writing, CMS publishing, media management -- **Slides**: AI presentation builder with 8 layouts, image generation, visual editing -- **Video**: Video composition studio built on Remotion with track-based animation - -## Documentation (Markdown) - -All documentation pages are available as raw markdown by appending `.md` to any docs URL: - -- [Getting Started](https://agent-native.com/docs/getting-started.md) -- [Server API](https://agent-native.com/docs/server.md) -- [Client Hooks](https://agent-native.com/docs/client.md) -- [Scripts](https://agent-native.com/docs/scripts.md) -- [Harnesses](https://agent-native.com/docs/harnesses.md) - -## Full Documentation - -For the complete documentation in a single file, see: [llms-full.txt](https://agent-native.com/llms-full.txt) - -## Links - -- Website: https://agent-native.com -- GitHub: https://github.com/BuilderIO/agent-native -- npm: https://www.npmjs.com/package/@agent-native/core +# Agent-Native + +> Framework for building AI-native applications where agents and UI share state through files. + +Agent-Native is an open source framework for building full-featured applications powered by AI agents. Apps are React frontends with Nitro backends. All state lives in files — the agent and UI read/write the same source of truth. No traditional database needed. + +## Key Concepts + +- **Files as Database**: All app state lives in JSON/markdown files. Agent and UI share the same source of truth. +- **AI Through the Agent**: No inline LLM calls. The UI delegates to the agent via a chat bridge (`sendToAgentChat()`). +- **Agent Updates Code**: The agent can modify the app itself. Your tools get better over time. +- **Real-time Sync**: File watcher streams changes via SSE. When the agent writes a file, the UI updates instantly. +- **Scripts System**: Agent-callable scripts via `pnpm script ` for complex operations. +- **Harnesses**: Apps run inside a harness (CLI harness supporting Claude Code, Codex, Gemini CLI, OpenCode, Builder.io — or Builder.io Cloud) that provides the AI agent alongside your UI. + +## Quick Start + + +npx @agent-native/core create my-app +cd my-app +pnpm install +pnpm dev +``` + +## Templates + +- **Mail**: Superhuman-style email client with keyboard shortcuts, AI triage, and smart search +- **Calendar**: Calendar app with Google Calendar sync, public booking page, and natural language scheduling +- **Analytics**: BI platform with 20+ data connectors, SQL query explorer, dashboards, data dictionary +- **Content**: Content workspace with brand-aware AI writing, CMS publishing, media management +- **Slides**: AI presentation builder with 8 layouts, image generation, visual editing +- **Video**: Video composition studio built on Remotion with track-based animation + +## Documentation (Markdown) + +All documentation pages are available as raw markdown by appending `.md` to any docs URL: + +- [Getting Started](https://agent-native.com/docs/getting-started.md) +- [Server API](https://agent-native.com/docs/server.md) +- [Client Hooks](https://agent-native.com/docs/client.md) +- [Scripts](https://agent-native.com/docs/scripts.md) +- [Routing](https://agent-native.com/docs/routing.md) +- [Deployment](https://agent-native.com/docs/deployment.md) +- [Harnesses](https://agent-native.com/docs/harnesses) + +## Full Documentation + +For the complete documentation in a single file, see: [llms-full.txt](https://agent-native.com/llms-full.txt) + +## Links + +- Website: https://agent-native.com +- GitHub: https://github.com/BuilderIO/agent-native +- npm: https://www.npmjs.com/package/@agent-native/core