@agent-native/core 0.37.2 → 0.38.0

package/docs/content/real-time-collaboration.md

@@ -139,7 +139,7 @@ User identity is derived from the session email. The framework provides `emailTo
 Templates can add a comments system with threaded discussions on documents. The content template includes a full implementation with:
 
 - `document_comments` SQL table (threads, replies, resolved status)
-- CRUD API routes at `/api/comments`
+- REST routes for update/delete at `/api/comments/:id`; create and list run through the `add-comment` / `list-comments` actions
 - Comments sidebar with threaded view and reply UI
 - Resolve/unresolve threads
 - **Send to AI** button — sends the comment thread context to the agent chat via `sendToAgentChat()`

package/docs/content/recurring-jobs.md

@@ -104,7 +104,7 @@ If the runtime is serverless/edge, trigger the tick from an external cron (Cloud
 ## Debugging a job {#debugging}
 
 - Open `jobs/<name>.md` in the workspace — the frontmatter shows `lastRun`, `lastStatus`, `lastError`, `nextRun`.
-- **Run it now:** ask the agent to "run the `morning-digest` job right now." The agent will invoke the scheduler tool to force-fire it.
+- **Test it without waiting:** there's no force-fire tool. To exercise the same work on demand, either paste the job's prompt into the agent chat and let it run there, or temporarily set the schedule to the next minute so the scheduler picks it up on the next tick (then restore the real cron).
 - **Pause it:** flip `enabled: false`. The file stays put, just stops running.
 
 ## Different from the scheduling package {#vs-scheduling-package}

package/docs/content/security.md

@@ -125,7 +125,7 @@ The `db-query` / `db-exec` tools reject schema-qualified table references (`publ
 
 For multi-user apps where teams share data, add an `org_id` column. When both columns are present, queries are scoped by both: `WHERE owner_email = ? AND org_id = ?`.
 
-The `ownableColumns()` schema helper adds both `owner_email` and `org_id` in one call, so new tenant-aware tables get the full scoping contract by default:
+The `ownableColumns()` schema helper adds `owner_email`, `org_id`, and `visibility` in one call, so new tenant-aware tables get the full scoping contract by default:
 
 ```typescript
 import { table, text, ownableColumns } from "@agent-native/core/db/schema";
@@ -133,7 +133,7 @@ import { table, text, ownableColumns } from "@agent-native/core/db/schema";
 export const projects = table("projects", {
   id: text("id").primaryKey(),
   title: text("title").notNull(),
-  ...ownableColumns(), // adds owner_email + org_id
+  ...ownableColumns(), // adds owner_email + org_id + visibility
 });
 ```
 

package/docs/content/server.md

@@ -63,18 +63,18 @@ Actions mounted by the framework automatically run with request context. Custom
 ```ts
 import { defineEventHandler } from "h3";
 import { getSession, runWithRequestContext } from "@agent-native/core/server";
-import { getDb } from "@agent-native/core/db";
+import { getDb } from "../../db/index.js";
 import { accessFilter } from "@agent-native/core/sharing";
 import * as schema from "../../db/schema";
 
 export default defineEventHandler(async (event) => {
   const session = await getSession(event);
-  if (!session?.user?.email) {
+  if (!session?.email) {
     throw new Response("Unauthorized", { status: 401 });
   }
 
   return runWithRequestContext(
-    { userEmail: session.user.email, orgId: session.orgId },
+    { userEmail: session.email, orgId: session.orgId },
     async () => {
       const db = getDb();
       return db
@@ -86,7 +86,7 @@ export default defineEventHandler(async (event) => {
 });
 ```
 
-Do not run unscoped `db.select().from(ownableTable)` in custom routes.
+`getDb` is created per app via `createGetDb(schema)` in `server/db/index.ts`, so custom routes import it from the template (`../../db/index.js`), not from `@agent-native/core/db`. Do not run unscoped `db.select().from(ownableTable)` in custom routes.
 
 ## Server Plugins {#server-plugins}
 

package/docs/content/skills-guide.md

@@ -182,6 +182,36 @@ The frontmatter `name` and `description` are used by the agent's tool system for
 
 Save the file at `.agents/skills/my-skill/SKILL.md`. The directory name should match the `name` in frontmatter.
 
+## Skill scope: runtime vs dev {#skill-scope}
+
+An optional `scope` frontmatter field controls which agent a skill is for:
+
+| `scope`   | Loaded by the runtime agent? | Use for                                                                         |
+| --------- | ---------------------------- | ------------------------------------------------------------------------------- |
+| `both`    | Yes (default)                | Skills useful to the in-app agent. This is the default when `scope` is omitted. |
+| `runtime` | Yes                          | Skills meant only for the in-app runtime agent.                                 |
+| `dev`     | No                           | Skills meant only for the human's coding agent (e.g. Claude Code).              |
+
+```markdown
+---
+name: release-checklist
+description: >-
+  Steps for cutting a release. Use when preparing or publishing a new version.
+scope: dev
+---
+```
+
+When `scope` is absent (or set to an unrecognized value) it defaults to `both`, so every existing skill keeps loading at runtime — this field is fully backward compatible. A `scope: dev` skill is invisible to the runtime agent everywhere: it is excluded from the skills block injected into the system prompt and from `docs-search` results.
+
+### Exposing a dev-only skill to your coding agent {#dev-only-skills}
+
+The agent-native runtime reads skills from `.agents/skills/`. Claude Code reads skills from `.claude/skills/` independently. To make a skill available to your coding agent but hidden from the runtime agent:
+
+- Mark it `scope: dev` in `.agents/skills/<name>/SKILL.md` so the runtime agent never loads it, and/or
+- Place or mirror the skill under `.claude/skills/<name>/SKILL.md` so Claude Code picks it up.
+
+This replaces the old hack of relying on Claude Code only reading `.claude/skills` — `scope: dev` makes the dev-vs-runtime split a first-class, explicit choice.
+
 > **See also:** [Writing Agent Instructions](/docs/writing-agent-instructions) for how to word skill descriptions, apply progressive disclosure, and keep `AGENTS.md` lean.
 
 ## Skills vs AGENTS.md {#skills-vs-agents-md}

package/docs/content/template-analytics.md

@@ -76,13 +76,13 @@ The rest of this doc is for anyone forking the Analytics template or extending i
 Create a new Analytics app from the CLI:
 
 ```bash
-pnpm dlx @agent-native/core create my-analytics --template analytics --standalone
+npx @agent-native/core create my-analytics --standalone --template analytics
 ```
 
 Local dev:
 
 ```bash
-cd my-analytics-app
+cd my-analytics
 pnpm install
 pnpm dev
 ```

package/docs/content/template-assets.md

@@ -94,9 +94,25 @@ The rest of this doc is for anyone forking the Assets template or extending it.
 ### Scaffolding
 
 ```bash
-pnpm dlx @agent-native/core create my-assets --template assets --standalone
+npx @agent-native/core create my-assets --standalone --template assets
 ```
 
+### Data model
+
+All data lives in SQL via Drizzle ORM (binary media lives in object storage, or the local file-upload fallback during development). Schema: `templates/assets/server/db/schema.ts`. Libraries carry the standard `ownableColumns` and a matching framework shares table, so they slot into the per-user / per-org sharing model. The SQL table names keep the legacy `image_*` prefix from when the app was called Images.
+
+| Table                            | What it holds                                                                                                                                                                            |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `image_libraries`                | A library — the top-level container grouped by brand, campaign, product, or category. Holds `custom_instructions`, `style_brief`, canonical logo and cover asset refs, and archive state |
+| `image_library_shares`           | Framework shares table mapping principals (users or orgs) to roles (viewer, editor, admin) per library                                                                                   |
+| `image_collections`              | Style/category groupings inside a library — `style_brief`, `prompt_template`, default aspect ratio and image size                                                                        |
+| `asset_folders`                  | Nestable folders inside a library (`parent_id` for hierarchy)                                                                                                                            |
+| `image_generation_presets`       | Saved generation recipes — media type, prompt template, aspect ratio, model, and text/reference policy                                                                                   |
+| `image_generation_sessions`      | An iterative generate-and-choose session with a brief, status, active asset, and feedback summary                                                                                        |
+| `image_generation_session_items` | Candidate assets within a session, each with a role and note                                                                                                                             |
+| `image_assets`                   | The asset record — media type, role, status, title/description/alt text, prompt, model, dimensions, MIME type, object/thumbnail keys, and lineage                                        |
+| `image_generation_runs`          | The generation audit log — prompt, compiled prompt, model, references, status, errors, and the `source` (`chat` / `ui` / `a2a`) that triggered it                                        |
+
 ### Customizing it
 
 Assets is a complete, cloneable template. Some practical extension ideas:

package/docs/content/template-brain.md

@@ -80,7 +80,7 @@ exclusion, and honest not-found behavior without connecting a real workspace.
 ### Scaffolding
 
 ```bash
-pnpm dlx @agent-native/core create my-brain --template brain --standalone
+npx @agent-native/core create my-brain --standalone --template brain
 ```
 
 Then open the app, add sources, import a transcript, and ask the agent to
@@ -142,7 +142,7 @@ so Dispatch and sibling apps can ask company-memory questions — the A2A agent
 card is public discovery metadata, while retrieval still happens inside Brain's
 authenticated action surface.
 
-## Data model overview
+## Data model
 
 Brain intentionally uses SQL text search and agentic query expansion. There is
 no vector database requirement, so the template stays portable across SQLite,

package/docs/content/template-calendar.md

@@ -70,7 +70,7 @@ The rest of this doc is for anyone forking the Calendar template or extending it
 Create a new workspace with the Calendar template:
 
 ```bash
-npx @agent-native/core create my-app --template calendar
+npx @agent-native/core create my-app --standalone --template calendar
 cd my-app
 pnpm install
 pnpm dev

package/docs/content/template-clips.md

@@ -17,7 +17,7 @@ A capture-everything app: screen recordings, meeting notes from your calendar, a
 
 ![Clips library with recordings, folders, and spaces](/screenshots/clips.png)
 
-Think along the lines of Loom + Granola + Wisprflow rolled into one app — but the agent is a first-class editor across every surface, and the recordings, meetings, and dictations are yours, not a SaaS vendor's.
+Think along the lines of Loom + Granola + Wispr Flow rolled into one app — but the agent is a first-class editor across every surface, and the recordings, meetings, and dictations are yours, not a SaaS vendor's.
 
 ## What you can do with it
 
@@ -64,7 +64,7 @@ The rest of this doc is for anyone forking the Clips template or extending it.
 ### Scaffolding
 
 ```bash
-pnpm dlx @agent-native/core create my-clips --template clips --standalone
+npx @agent-native/core create my-clips --standalone --template clips
 ```
 
 Clips is a larger template with a native recorder (it ships a desktop companion for local capture). See the template `README.md` for setup specifics around screen-capture permissions and storage configuration.
@@ -109,7 +109,7 @@ Every agent-callable operation is a TypeScript file in `templates/clips/actions/
 - **Search, insights & export** — `search-recordings` (matches titles, descriptions, transcript text, and comments, with timestamps), `get-recording-insights`, `get-organization-insights`, `export-insights-csv`, `export-to-brain`.
 - **Context & navigation** — `view-screen` (current clip, playhead, selected transcript range) and `navigate`; `refresh-list` after mutations.
 
-### Customize it
+### Customizing it
 
 Clips is a complete, cloneable template — fork it and ask the agent to extend it. Some examples:
 

package/docs/content/template-content.md

@@ -52,7 +52,7 @@ The rest of this doc is for anyone forking the Content template or extending it.
 Scaffold a new workspace with the Content template:
 
 ```bash
-npx @agent-native/core create my-workspace --template content
+npx @agent-native/core create my-workspace --standalone --template content
 cd my-workspace
 pnpm install
 pnpm dev
@@ -155,7 +155,7 @@ The four places to look when changing behavior:
 - **`app/components/editor/`** — the Tiptap editor. Add a new node type under `extensions/` and register it in `DocumentEditor.tsx`. The bubble toolbar, slash menu, and hover previews are all component files you can edit.
 - **`.agents/skills/`** — guidance the agent reads before acting. If you add a new capability (say, a CMS publishing pipeline), drop a `SKILL.md` in a new skill folder so the agent uses it correctly. Existing skills: `document-editing`, `notion-integration`, `real-time-sync`, `delegate-to-agent`, `storing-data`, `self-modifying-code`, `security`, `frontend-design`, `create-skill`, `capture-learnings`.
 - **`AGENTS.md`** — the top-level agent guide with the action cheatsheet and common-tasks table. Update it whenever you add a major feature so the agent discovers it without exploring.
-- **`server/db/schema.ts`** — data model. Add a column or table here. For local development, you can sync your database schema using `pnpm db:push`. In hosted production environments, **never** run `db:push` (doing so will attempt to drop core framework tables not defined in the template's schema); instead, apply schema updates via strictly additive migration scripts executed at startup (see [Database](/docs/database#migrations) for guidelines).
+- **`server/db/schema.ts`** — data model. Add a column or table here. The Content template has no `db:push` script; it relies on strictly additive migrations that run on startup. Edit `server/db/schema.ts`, write a matching additive migration, and the change applies the next time the app boots — schema updates must never drop, rename, or destructively alter existing tables or columns (see [Database](/docs/database#migrations) for guidelines).
 - **`shared/notion-markdown.ts`** — markdown-to-Notion-blocks conversion. Extend this if you add new block types that need to round-trip through Notion.
 
 The agent can make all of these changes itself — ask it to "add a tags column to documents and expose it in the sidebar" and it will update the schema, migrate, wire the UI, and write the action.

package/docs/content/template-design.md

@@ -109,7 +109,7 @@ The rest of this doc is for anyone forking the Design template or extending it.
 ### Scaffolding
 
 ```bash
-pnpm dlx @agent-native/core create my-design --template design --standalone
+npx @agent-native/core create my-design --standalone --template design
 ```
 
 ### Data Model
@@ -139,7 +139,7 @@ Every agent-callable operation is a TypeScript file in `templates/design/actions
 - **Export & handoff** — `export-html`, `export-pdf`, `export-svg`, `export-zip`, and `export-coding-handoff` to turn a design into a coding-tool handoff.
 - **Context & navigation** — `view-screen` (current design, open file, view, pending question or variant grid), `get-design-snapshot` (current state for an external agent to continue from), and `navigate`.
 
-### Customize It
+### Customizing It
 
 Design is a complete, cloneable template. Some practical extension ideas:
 

package/docs/content/template-dispatch.md

@@ -74,7 +74,7 @@ _How it works under the hood (for developers)._
 
 - **Orchestrator agent.** The chat is set up as a router: it reads `AGENTS.md`, `LEARNINGS.md`, and routes to specialist sub-agents or remote A2A agents.
 - **Remote agent registry.** A2A agent manifests are workspace-runtime entries (not a checked-in template source folder): in a multi-app workspace, sibling apps under `apps/` are auto-discovered as A2A peers — no manual registration needed. Dispatch calls them using the `call-agent` action.
-- **Vault schema.** Drizzle tables for secrets, grants, requests, approvals, and audit logs. See `server/db/schema.ts` in the template.
+- **Vault schema.** Drizzle tables for secrets, grants, requests, approvals, and audit logs. These live in the `@agent-native/dispatch` package (`packages/dispatch/src/db/schema.ts`) and are re-exported into the template via `templates/dispatch/server/db/index.ts` — there is no template-local `server/db/schema.ts`. Dispatch's runtime ships in the package, not in template source (consistent with the note below that `@agent-native/dispatch` owns the shell, sidebar, and built-in pages).
 - **Slack / Telegram plugins.** Server plugins that register webhooks and forward incoming messages to the orchestrator agent.
 - **Workspace MCP resources.** Add HTTP MCP server definitions under `mcp-servers/*.json` in Resources, then scope them to All apps or selected app grants just like skills and context.
 - **MCP hub mode.** Dispatch can still act as the workspace's [MCP hub](/docs/mcp-clients#hub) so every other app in the workspace pulls the same org-scope MCP server list. Separately, Dispatch's own `/_agent-native/mcp` endpoint is the recommended external MCP connector for Claude, ChatGPT, and other hosts that should reach multiple workspace apps.
@@ -117,7 +117,7 @@ pnpm action create-dream-report --allSources true --sourceTimeoutMs 30000 --limi
 ## Scaffolding {#scaffolding}
 
 ```bash
-pnpm dlx @agent-native/core create my-platform
+npx @agent-native/core create my-platform
 # pick "Dispatch" in the multi-select picker, plus whichever domain apps you want
 ```
 
@@ -140,7 +140,7 @@ You can click through the Dispatch UI after signing in. To use the chat composer
 2. In **LLM**, either connect Builder.io or add your own provider key such as `ANTHROPIC_API_KEY`.
 3. Return to **Overview** and try the composer.
 
-## Customize it {#customize}
+## Customizing it {#customize}
 
 Dispatch is a full template like any other — see [Templates](/docs/cloneable-saas). Ask the agent to "add a new integration for Datadog" or "route Slack DMs from channel X to the analytics agent" and it'll edit the routing config, add the webhook handler, and wire it up.
 

package/docs/content/template-forms.md

@@ -58,17 +58,29 @@ See [What is agent-native?](/docs/what-is-agent-native) for the broader framewor
 ### Scaffolding
 
 ```bash
-pnpm dlx @agent-native/core create my-forms --template forms --standalone
+npx @agent-native/core create my-forms --standalone --template forms
 ```
 
 For a workspace with Forms alongside other apps:
 
 ```bash
-pnpm dlx @agent-native/core create my-platform
+npx @agent-native/core create my-platform
 ```
 
 Pick Forms and any other templates you want during the workspace setup.
 
+### Data model
+
+All data lives in SQL via Drizzle ORM. Schema: `templates/forms/server/db/schema.ts`. Forms carry the standard `ownableColumns` and a matching framework shares table, so they slot into the per-user / per-org sharing model.
+
+| Table         | What it holds                                                                                                                                                                                                  |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `forms`       | A form definition — `title`, `description`, unique `slug`, `fields` (JSON array of `FormField`), `settings` (JSON `FormSettings`), `status` (`draft` / `published` / `closed`), and a soft-delete `deleted_at` |
+| `responses`   | One submission per row — `form_id`, `data` (JSON `{ fieldId: value }`), `submitted_at`, optional `ip` and `submitter_email`                                                                                    |
+| `form_shares` | Framework shares table mapping principals (users or orgs) to roles (viewer, editor, admin) per form                                                                                                            |
+
+The `fields` and `settings` JSON shapes are defined in `templates/forms/shared/types.ts` (`FormField`, `FormSettings`). Owner-private settings such as integration webhook URLs and allowed origins are stripped before any data reaches the public fill page via `toPublicFormSettings`.
+
 ### Customizing it
 
 Ask the agent for shipped behavior first:

package/docs/content/template-mail.md

@@ -34,9 +34,7 @@ When you open the app, you'll see your inbox on the left, the open thread in the
 
 Live demo: [mail.agent-native.com](https://mail.agent-native.com).
 
-> **Hosted demo warning:** The hosted Mail demo uses Agent-Native's shared Google OAuth client. Because Mail asks for Gmail access, Google may show extra consent or warning screens before continuing.
->
-> Self-hosted Mail apps use your own Google OAuth client and avoid this hosted-demo warning. Use the run-local command when you want that path.
+> **Google may show a warning:** The hosted demo uses Agent-Native's shared Google app for Gmail access, so Google may ask you to confirm before continuing. Run locally to use your own Google OAuth client.
 
 When you first open the app:
 

package/docs/content/template-plan.md

@@ -0,0 +1,118 @@
+---
+title: "Plans"
+description: "Install Agent-Native Plans as an app-backed skill for Codex, Claude Code, and other coding agents. Create structured visual plans with diagrams, wireframes, annotations, comments, and share links."
+---
+
+# Plans
+
+Agent-Native Plans is visual plan mode for coding agents. It turns an ordinary
+Codex, Claude Code, Markdown, or pasted implementation plan into a structured
+review surface with rich text, diagrams, wireframes, prototypes, implementation
+maps, annotations, comments, and shareable links.
+
+![Agent-Native Plans review surface](https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fb6f4213ac7cc42eeb10c12e8ccda8936?format=webp&width=1200)
+
+## Install the skill
+
+Use the Agent-Native CLI. This is the recommended setup because it installs the
+Plans skill instructions, registers the hosted Plans MCP connector, and runs the
+client-specific auth/setup flow in one step:
+
+```bash
+npx @agent-native/core@latest skills add visual-plan
+```
+
+If you already have the CLI installed, the shorter command is equivalent:
+
+```bash
+agent-native skills add visual-plan
+```
+
+The command installs `/visual-plan` plus the companion commands:
+
+- `/ui-plan` for UI-first plans with mockups, states, and screen-level review.
+- `/visual-questions` for visual intake before a plan.
+- `/visualize-plan` for turning an existing text plan into a visual companion.
+
+By default the CLI targets Codex. Add `--client claude-code` or `--client all`
+when you want to configure another host:
+
+```bash
+npx @agent-native/core@latest skills add visual-plan --client all
+```
+
+If you only want the portable instruction file through the open Skills CLI, use:
+
+```bash
+npx skills add BuilderIO/agent-native --skill visual-plan
+```
+
+That installs the skill instructions only. It does not register the hosted MCP
+connector, so use the Agent-Native CLI path when you want the one-command setup.
+
+## Use it from your coding agent
+
+After installation, ask your agent for the command that fits the work:
+
+- `/visual-plan` creates a structured plan for architecture, backend, refactor,
+  or mixed product work.
+- `/ui-plan` creates a UI-first plan with wireframes, mockups, states, and
+  implementation notes.
+- `/visual-questions` opens a visual intake questionnaire before planning.
+- `/visualize-plan` imports a plan you already have and makes it reviewable.
+
+The agent should inspect the codebase first, then create the visual plan when a
+wrong direction would be costly. The returned Plans link opens the review UI so
+you can annotate, correct, choose options, and ask for updates before code
+changes begin.
+
+## What you can do with it
+
+- **Review before implementation.** React to diagrams, wireframes, option tabs,
+  risk notes, file maps, and code previews before the agent edits files.
+- **Comment directly on the plan.** Pin feedback, request changes, and resolve
+  comments as the plan evolves.
+- **Share with reviewers.** Hosted Plans can create private review links and
+  account-backed sharing. Viewing shared plans works from the browser; saving
+  and sharing require sign-in.
+- **Export the result.** Keep an HTML, Markdown, or JSON receipt of the plan
+  when you need a source-control-friendly handoff.
+- **Run locally when needed.** The template can be self-hosted for development
+  or offline workflows, while the hosted skill is the easiest path for normal
+  coding-agent use.
+
+## Useful prompts
+
+- "Use `/visual-plan` before changing the auth flow."
+- "Create a `/ui-plan` for the new onboarding screen with mobile and desktop states."
+- "Use `/visual-questions` to help me choose the dashboard direction first."
+- "Run `/visualize-plan` on the Markdown plan below and make it easier to review."
+
+## For developers
+
+The rest of this doc is for anyone forking or self-hosting the Plans template.
+Most users should install the skill with the CLI instead of scaffolding the app.
+
+### Scaffold the template
+
+```bash
+npx @agent-native/core create my-plans --standalone --template plan
+cd my-plans
+pnpm install
+pnpm dev
+```
+
+The hosted app-backed skill uses:
+
+- App: `https://plan.agent-native.com`
+- MCP: `https://plan.agent-native.com/_agent-native/mcp`
+
+The local template is useful when you are developing Plans itself, testing local
+persistence, or running a fully self-hosted review surface.
+
+## What's next
+
+- [**Visual Plans**](/docs/visual-plans) — the full skill flow and auth details
+- [**Skills**](/docs/skills-guide) — how Agent-Native installs skills
+- [**MCP Clients**](/docs/mcp-clients) — configuring hosted MCP connectors
+- [**Templates**](/docs/cloneable-saas) — the clone-and-own model

package/docs/content/template-slides.md

@@ -60,8 +60,9 @@ The rest of this doc is for anyone forking the Slides template or extending it.
 Create a new Slides app from the CLI:
 
 ```bash
-npx @agent-native/core create my-slides --template slides
+npx @agent-native/core create my-slides --standalone --template slides
 cd my-slides
+pnpm install
 pnpm dev
 ```
 
@@ -73,9 +74,9 @@ Ask the agent for a deck and it builds one slide at a time. Slides stream into t
 
 Under the hood, this is powered by the `add-slide` and `create-deck` actions in `templates/slides/actions/`.
 
-### Eight slide layouts
+### Seven slide layouts
 
-Built-in layouts: title, section divider, content with bullets, two-column, image, statement or quote, full-bleed, and blank. Each layout is a pure HTML template with inline styles — the agent picks the right one based on slide purpose. Templates live inside `templates/slides/AGENTS.md` so the agent can reference them without exploring the codebase.
+Built-in layouts: title, section divider, content with bullets, two-column, statement or quote, metrics or stats, and closing or CTA. Each layout is a pure HTML template with inline styles — the agent picks the right one based on slide purpose. The exact templates live inside `templates/slides/.agents/skills/create-deck/SKILL.md` so the agent can reference them without exploring the codebase.
 
 ### Visual and code editing
 
@@ -233,7 +234,7 @@ Agent skills that explain patterns when the agent needs to modify code:
 
 ### AGENTS.md
 
-`templates/slides/AGENTS.md` is the single source of truth the agent reads on every conversation. It contains the full action list, every slide HTML template, the navigation state contract, and rules for delegating to sub-agents. Update this file whenever you add an action or a new slide layout pattern.
+`templates/slides/AGENTS.md` is the short router the agent reads on every conversation. It points at the skills under `.agents/skills/` and lays out the core rules, application-state contract, and skill index. The exact slide HTML templates for every layout live in `.agents/skills/create-deck/SKILL.md` — update that skill whenever you add or change a slide layout pattern.
 
 ### API routes
 

package/docs/content/template-starter.md

@@ -25,10 +25,10 @@ Pick Starter when you're not sure which domain template fits, or when you want t
 - **Agent chat plugin** pre-configured so the chat actually talks to Claude (once `ANTHROPIC_API_KEY` is set).
 - **Auth** via Better Auth — login, signup, sessions, organizations. The same flow runs locally and in production; in development email verification is skipped so signup is just an email + password.
 - **Actions directory** with one example (`actions/hello.ts`) and the `view-screen` / `navigate` standard actions wired up.
-- **Drizzle schema** with the framework's core tables (application_state, settings, oauth_tokens, sessions, resources).
+- **The framework's core tables** (application_state, settings, oauth_tokens, sessions, resources) provided by `@agent-native/core` at runtime — there's no template-local schema file to maintain. Add your own Drizzle schema when you define domain tables.
 - **Live sync** (`useDbSync`) already wired so UI auto-refreshes when the agent writes to the database.
 - **AGENTS.md** with the framework-wide rules the agent reads on every turn.
-- **One route** at `/` that says hi and renders the sidebar toggle. That's it.
+- **One example domain route** at `/` that says hi and renders the sidebar toggle, plus the framework-shared admin routes (Database, Team, Observability, Extensions).
 
 ## What's _not_ in it {#not-in-it}
 
@@ -51,13 +51,13 @@ Pick a domain template ([Mail](/docs/template-mail), [Calendar](/docs/template-c
 ## Scaffolding {#scaffolding}
 
 ```bash
-pnpm dlx @agent-native/core create my-app --template starter --standalone
+npx @agent-native/core create my-app --standalone --template starter
 ```
 
 Or, in a workspace:
 
 ```bash
-pnpm dlx @agent-native/core create my-platform  # pick "Starter" (pre-selected by default) plus any others
+npx @agent-native/core create my-platform  # pick "Starter" (pre-selected by default) plus any others
 ```
 
 ## First edits {#first-edits}

package/docs/content/template-videos.md

@@ -24,7 +24,7 @@ When you open the studio, you'll see a list of compositions on the home screen.
 - **Generate animations from a prompt.** "Add a title card that fades in at 2 seconds and holds until 5." The agent edits the composition.
 - **Tune timing on a timeline.** Drag and resize animation tracks, scrub through frames, set easing curves visually.
 - **Animate the camera.** Pan, zoom, and tilt with on-screen tools. Click the tool, drag in the preview, and a keyframe is auto-created.
-- **Built-in compositions to start from.** Twelve examples ship: kinetic text, logo reveals, particle bursts, interactive UI demos, slideshows.
+- **Start from a blank composition or an example.** The template ships one in-code composition (`BlankComposition`) to start from; example compositions — kinetic text, logo reveals, particle bursts, interactive UI demos, slideshows — load from the database, and you can add your own.
 - **Edit easing curves visually.** 30+ curves shipped — power, back, bounce, circ, elastic, expo, sine, plus spring physics.
 - **Render to MP4 or WebM** at 1x, 2x, or 3x supersampling for crisp text and vectors during camera zoom.
 
@@ -64,21 +64,16 @@ The studio runs on Remotion's `<Player>` for preview and the Remotion CLI for fi
 
 ### Quick start
 
-Create a workspace with the Video app scaffolded:
-
-```bash
-npx @agent-native/core create my-video-app
-```
-
-During the picker, select **Video**. Then:
+Scaffold a new Video app from the CLI:
 
 ```bash
+npx @agent-native/core create my-video-app --standalone --template videos
 cd my-video-app
 pnpm install
 pnpm dev
 ```
 
-Open the studio in your browser and pick a composition from the home screen. Ask the agent something like "add a logo reveal that fades in at 2 seconds" and it will edit the registry and the composition for you.
+Open the studio in your browser, create a composition, and start from blank. Ask the agent something like "add a logo reveal that fades in at 2 seconds" and it will edit the composition for you.
 
 Live demo: [videos.agent-native.com](https://videos.agent-native.com).
 
@@ -86,7 +81,7 @@ Live demo: [videos.agent-native.com](https://videos.agent-native.com).
 
 ### React-based compositions
 
-Every video is a React component built on Remotion primitives (`AbsoluteFill`, `useCurrentFrame`, `useVideoConfig`). Twelve example compositions ship by default — kinetic text, logo reveals, particle bursts, interactive UI demos, slideshows. Add new ones by dropping a `.tsx` file in `app/remotion/compositions/` and registering it in `app/remotion/registry.ts`.
+Every video is a React component built on Remotion primitives (`AbsoluteFill`, `useCurrentFrame`, `useVideoConfig`). The template ships one in-code composition — `BlankComposition` in `app/remotion/compositions/BlankComposition.tsx` — and `app/remotion/registry.ts` exports an empty `compositions` array by default. User and example compositions (kinetic text, logo reveals, particle bursts, interactive UI demos, slideshows) live in SQL and load through `app/hooks/use-database-compositions.ts`. You can still add a code composition by dropping a `.tsx` file in `app/remotion/compositions/` and registering it in `app/remotion/registry.ts`.
 
 ### Timeline tracks
 
@@ -128,7 +123,7 @@ Composition size, fps, and render quality are per-composition in the Properties
 
 ### Composition persistence
 
-User edits (track values, parameter values, prop overrides, composition settings) persist to localStorage per composition. The **Save** button in the top-right of the composition view writes the current state back to `app/remotion/registry.ts` as TypeScript — so new users and sessions pick up the changes.
+User edits (track values, parameter values, prop overrides, composition settings) persist to localStorage per composition. The **Save** button in the top-right of the composition view can write the current state back to `app/remotion/registry.ts` as TypeScript — so new users and sessions pick up the changes. That source-write path runs through `POST /api/save-composition-defaults`, which is gated to local development only; in production it returns a 403, and durable composition state lives in SQL instead.
 
 ### Working with the agent
 

package/docs/content/tracking.md

@@ -5,7 +5,7 @@ description: "Server-side analytics with pluggable providers — PostHog, Mixpan
 
 # Analytics Tracking
 
-One function, multiple destinations. Call `track()` from any server-side code — actions, plugins, server routes — and the event fans out to every registered analytics provider. No SDK dependencies, no client-side scripts, no blocking.
+One function, multiple destinations. Call `track()` from any server-side code — actions, plugins, server routes — and the event fans out to every registered analytics provider. No SDK dependencies, no client-side scripts, no blocking. The same `track()` is also available in [browser/app code](#client) and routes to the same providers.
 
 ```ts
 import { track } from "@agent-native/core/tracking";
@@ -173,6 +173,26 @@ export default defineAction({
 
 Track calls are fire-and-forget — they return immediately and never block the action response.
 
+## Client-side tracking {#client}
+
+`track()` also works from browser/app code. Import the client twin from `@agent-native/core/client` and call it the same way — it POSTs the event to the framework route at `POST /_agent-native/track`, which forwards it to the **same** registered server-side providers (PostHog, Mixpanel, Amplitude, webhook). No analytics SDK ships to the browser and no provider keys are exposed client-side.
+
+```ts
+import { track } from "@agent-native/core/client";
+
+// e.g. inside a click handler or effect
+track("checkout.completed", { total: 49.99, items: 3 });
+```
+
+Key differences from the [server `track()`](#track):
+
+- **No identity argument.** The event is attributed server-side to the signed-in user (and the active org, as `org_id` in `properties`). Browser code never passes a `userId`.
+- **`source: "client"`** is added to every event's properties so you can tell client-originated events apart from server ones.
+- **Fire-and-forget.** It never blocks the UI, never throws, and swallows network errors.
+- **Authenticated, first-party only.** The route requires a session and a same-origin/CSRF marker (set automatically by the helper), so it can't be used as an open analytics relay. `name` is capped at 200 characters and `properties` at ~16KB; oversized or malformed payloads are rejected.
+
+This is distinct from the framework's internal browser telemetry (`trackEvent()` / automatic pageviews — see [Browser defaults](#browser-defaults)), which powers Agent Native's own product analytics. Use `track()` for your app's own analytics events that should reach your configured providers.
+
 ## What's next
 
 - [**Actions**](/docs/actions) — where most tracking calls originate