@agent-native/core 0.46.0 → 0.48.1

package/docs/content/recurring-jobs.md

@@ -7,6 +7,8 @@ description: "Cron-scheduled prompts the agent runs on its own — daily digests
 
 A **recurring job** is a prompt that runs on a cron schedule. It's how the agent does things on its own: "every morning at 7 summarize my overnight emails," "every Monday post last week's signup numbers to Slack," "every hour sweep for stale drafts and delete them."
 
+Recurring jobs fire on a clock. To react to _events_ (a booking created, an email received) — same `jobs/` file format plus conditions — see [Automations](/docs/automations).
+
 Jobs live in the [workspace](/docs/workspace) at `jobs/<name>.md` — just a Markdown file with YAML frontmatter. No registration, no wiring. Drop the file in and the framework picks it up.
 
 ## A job file {#job-file}
@@ -99,7 +101,7 @@ The scheduler is a framework plugin (the internal `processRecurringJobs()` routi
 4. The agent runs its loop — calling actions, writing to SQL, sending A2A messages, emailing, whatever the prompt asks for.
 5. On completion, writes `lastRun`, `lastStatus`, `lastError`, and recomputes `nextRun` from the cron.
 
-If the runtime is serverless/edge, trigger the tick from an external cron (Cloudflare Cron Triggers, Vercel Cron, GitHub Actions on a schedule, etc.) by hitting the framework's scheduler endpoint. If you're on Node, the scheduler can run in-process on a `setInterval`.
+The scheduler runs in-process: a `setInterval` fires every 60 seconds (with a 10-second startup delay) inside the agent chat plugin, wherever the server is running. On scale-to-zero serverless hosts, jobs only fire while an instance is warm — if reliable scheduling matters, keep an instance warm with keep-alive pings or use an always-on host (Fly, Render, a VPS).
 
 ## Debugging a job {#debugging}
 
@@ -107,6 +109,19 @@ If the runtime is serverless/edge, trigger the tick from an external cron (Cloud
 - **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.
 
+## Agent tool {#agent-tool}
+
+A single `manage-jobs` tool is registered in every template. The `action` parameter selects the operation:
+
+| Action   | Parameters                                                        | Purpose                                                      |
+| -------- | ----------------------------------------------------------------- | ------------------------------------------------------------ |
+| `create` | `name`, `schedule`, `instructions` (required); `scope`, `runAs`   | Create a new recurring job                                   |
+| `list`   | `scope` (`personal`, `shared`, or all)                            | List all jobs with status (schedule, enabled, last/next run) |
+| `update` | `name` (required); `schedule`, `instructions`, `enabled`, `runAs` | Edit an existing job                                         |
+| `delete` | `name` (required)                                                 | Delete a job — always confirm with the user first            |
+
+**Personal vs shared scope.** Each job lives in either personal scope (runs as and is visible only to the creator) or shared/org scope (runs on behalf of the creator but is visible to org members). The `scope` and `runAs` parameters control this at create time. Org admins can update or delete any shared job; non-admin members can only manage their own.
+
 ## Different from the scheduling package {#vs-scheduling-package}
 
 Don't confuse recurring jobs with `@agent-native/scheduling`:
@@ -118,6 +133,7 @@ Recurring jobs are "how do I make the agent act on its own?" The scheduling pack
 
 ## What's next
 
+- [**Automations**](/docs/automations) — add event triggers and conditions to the same `jobs/` format
 - [**Workspace**](/docs/workspace) — where jobs live alongside skills, memory, and custom agents
 - [**Actions**](/docs/actions) — the tools a job calls
 - [**Agent Teams**](/docs/agent-teams) — jobs often spawn sub-agents to do parallel work

package/docs/content/security.md

@@ -96,16 +96,30 @@ The signed-in session carries `email` and (when an org is active) `orgId`. The f
 
 ### Per-User Scoping (`owner_email`)
 
-Every table with user-specific data **must** have an `owner_email` text column:
+Every table with user-specific data **must** have an `owner_email` text column. Use the camelCase Drizzle property name — `accessFilter` reads `resourceTable.ownerEmail`:
 
 ```typescript
-import { table, text, integer } from "@agent-native/core/db/schema";
+import {
+  table,
+  text,
+  integer,
+  ownableColumns,
+} from "@agent-native/core/db/schema";
+
+// Minimal: just the owner column
+export const notes = table("notes", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  content: text("content"),
+  ownerEmail: text("owner_email").notNull(), // REQUIRED — camelCase property
+});
 
+// Or use ownableColumns() to add owner_email + org_id + visibility in one call
 export const notes = table("notes", {
   id: text("id").primaryKey(),
   title: text("title").notNull(),
   content: text("content"),
-  owner_email: text("owner_email").notNull(), // REQUIRED
+  ...ownableColumns(),
 });
 ```
 

package/docs/content/server.md

@@ -56,12 +56,48 @@ If the UI and agent both need to do something, define an action instead of a cus
 
 Use custom `/api/*` routes only when you need a route-shaped protocol or binary/streaming behavior. See [Actions](/docs/actions).
 
+## One-Shot Text Completion {#complete-text}
+
+Most AI work should go through the agent chat so users can see, steer, and audit
+what happened. For narrow server-side transforms that intentionally do not need
+tools, chat history, or run state, use `completeText()` as an explicit escape
+hatch.
+
+```ts
+// actions/classify-message.ts
+import { defineAction } from "@agent-native/core";
+import { completeText } from "@agent-native/core/server";
+import { z } from "zod";
+
+export default defineAction({
+  description: "Classify a short message",
+  schema: z.object({ body: z.string() }),
+  run: async ({ body }) => {
+    const result = await completeText({
+      systemPrompt:
+        "Return exactly one label: urgent, follow-up, waiting, or archive.",
+      input: body,
+      maxOutputTokens: 16,
+      temperature: 0,
+    });
+
+    return { label: result.text.trim() };
+  },
+});
+```
+
+`completeText()` runs through the same configured engine layer as the agent
+chat, including Builder, Anthropic, AI SDK providers, user/app model defaults,
+request-scoped secrets, and engine-normalized errors. It is server-only; do not
+call model providers from client code. If the operation is user-facing, wrap it
+in an action so the UI and agent share the same capability.
+
 ## Request Context And Access {#request-context}
 
 Actions mounted by the framework automatically run with request context. Custom routes do not. If a custom route reads or writes ownable resources, load the session and wrap the work:
 
 ```ts
-import { defineEventHandler } from "h3";
+import { defineEventHandler, createError } from "h3";
 import { getSession, runWithRequestContext } from "@agent-native/core/server";
 import { getDb } from "../../db/index.js";
 import { accessFilter } from "@agent-native/core/sharing";
@@ -70,7 +106,7 @@ import * as schema from "../../db/schema";
 export default defineEventHandler(async (event) => {
   const session = await getSession(event);
   if (!session?.email) {
-    throw new Response("Unauthorized", { status: 401 });
+    throw createError({ statusCode: 401, statusMessage: "Unauthorized" });
   }
 
   return runWithRequestContext(
@@ -86,7 +122,7 @@ export default defineEventHandler(async (event) => {
 });
 ```
 
-`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.
+`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`; see [Database — Where the DB Client Lives](/docs/database#db-client). Do not run unscoped `db.select().from(ownableTable)` in custom routes.
 
 ## Server Plugins {#server-plugins}
 

package/docs/content/sharing.md

@@ -136,7 +136,26 @@ registerShareableResource({
 });
 ```
 
-After that, list/read queries pass through `accessFilter()` and write actions use `assertAccess()` to enforce roles. `getResourcePath` gives notification emails a direct fallback link when a share is created by the agent or another non-UI caller. The full pattern (including create-action ownership stamping and the migration recipe for existing tables) lives in the `sharing` agent skill — the agent reads it on demand when building a sharing-aware feature.
+After that, list/read queries pass through `accessFilter()` and write actions use `assertAccess()` to enforce roles.
+
+### Optional hardening flags {#hardening-flags}
+
+`registerShareableResource` accepts two security flags for resources that execute code or carry elevated trust:
+
+```ts
+registerShareableResource({
+  type: "extension",
+  resourceTable: schema.extensions,
+  sharesTable: schema.extensionShares,
+  // ...
+  allowPublic: false, // Reject set-resource-visibility → "public"
+  requireOrgMemberForUserShares: true, // Reject user grants to non-org emails
+});
+```
+
+`allowPublic: false` prevents any caller — agent or UI — from setting the resource's visibility to `public`. `requireOrgMemberForUserShares: true` rejects individual user grants to email addresses outside the resource owner's org. Extensions set both: an extension's HTML runs inside an iframe that calls actions and DB as the _viewer_, so public access would be arbitrary code with the viewer's credentials.
+
+`getResourcePath` gives notification emails a direct fallback link when a share is created by the agent or another non-UI caller. The full pattern (including create-action ownership stamping and the migration recipe for existing tables) lives in the `sharing` agent skill — the agent reads it on demand when building a sharing-aware feature.
 
 ## Security guarantees {#security}
 

package/docs/content/skills-guide.md

@@ -11,39 +11,169 @@ Skills are Markdown files that give the agent deep knowledge about specific patt
 
 Skills live at `.agents/skills/<name>/SKILL.md` and contain detailed guidance for the agent. Each skill focuses on one concern — how to store data, how to sync state, how to delegate work to the agent chat.
 
-The agent reads skills when it needs to follow a specific pattern. Skills are referenced in `AGENTS.md` and triggered by the agent's tool system when relevant.
+Every skill's frontmatter `name` and `description` are always injected into the system prompt's skills block so the agent knows what skills exist. The full skill body is loaded on demand when the agent decides a skill is relevant to the task (it is also surfaced via `docs-search`). This is why keeping descriptions short and trigger-specific matters: the description is the only thing the agent reads before deciding whether to load the rest.
 
 ## Framework skills {#framework-skills}
 
-These skills ship with the framework and apply to all agent-native apps:
-
-| Skill                 | When to use                                            |
-| --------------------- | ------------------------------------------------------ |
-| `storing-data`        | Adding data models, reading/writing config or state    |
-| `real-time-sync`      | Wiring polling sync, debugging UI not updating         |
-| `delegate-to-agent`   | Delegating AI work from UI or actions to the agent     |
-| `actions`             | Creating or running agent actions                      |
-| `self-modifying-code` | Editing app source, components, or styles              |
-| `create-skill`        | Adding new skills for the agent                        |
-| `capture-learnings`   | Recording corrections and patterns                     |
-| `frontend-design`     | Building or styling any web UI, components, or pages   |
-| `adding-a-feature`    | The four-area checklist: UI, script, skills, app-state |
-| `context-awareness`   | Exposing UI state to the agent, view-screen, navigate  |
-| `a2a-protocol`        | Inter-agent communication via JSON-RPC                 |
+These skills ship with the default template and are available in every new agent-native app:
+
+| Skill                 | When to use                                             |
+| --------------------- | ------------------------------------------------------- |
+| `storing-data`        | Adding data models, reading/writing config or state     |
+| `real-time-sync`      | Wiring polling sync, debugging UI not updating          |
+| `delegate-to-agent`   | Delegating AI work from UI or actions to the agent      |
+| `actions`             | Creating or running agent actions                       |
+| `self-modifying-code` | Editing app source, components, or styles               |
+| `create-skill`        | Adding new skills for the agent                         |
+| `capture-learnings`   | Recording corrections and patterns                      |
+| `frontend-design`     | Building or styling any web UI, components, or pages    |
+| `adding-a-feature`    | The four-area checklist: UI, actions, skills, app-state |
+| `shadcn-ui`           | Using shadcn/ui primitives and components               |
+| `security`            | Auth, access control, and secret handling               |
+| `real-time-collab`    | Multi-user collaborative editing                        |
+| `agent-engines`       | Swapping or configuring the underlying agent engine     |
+| `notifications`       | In-app and push notification patterns                   |
+| `progress`            | Tracking and surfacing background task progress         |
+| `inline-embeds`       | Embedding apps or iframes inside the agent chat         |
+
+`context-awareness` and `a2a-protocol` are framework-level skills available in the `.agents/skills/` directory at the repo root — see each template's own `.agents/skills/` for what it inherits.
 
 ## Domain skills {#domain-skills}
 
-Templates include skills specific to their domain. These live in the same `.agents/skills/` directory but cover template-specific patterns:
+Templates include skills specific to their domain. These live in the same `.agents/skills/` directory but cover template-specific patterns. See each template's `.agents/skills/` directory for the full list; a representative sample:
 
-- **Mail template** — email-drafts, thread-management, label-system
-- **Forms template** — form-building, field-types, submission-handling
-- **Analytics template** — chart-types, data-connectors, query-patterns
-- **Slides template** — deck-management, slide-layouts, theme-system
+- **Mail template** — `email-drafts`, `draft-queue`
+- **Forms template** — `form-building`, `form-publishing`, `form-responses`
+- **Analytics template** — `adhoc-analysis`, `bigquery`, `cross-source-analysis`, `dashboard-management`, `data-querying`, `provider-api`, `gong`, `hubspot`, `prometheus`
+- **Slides template** — `create-deck`, `deck-management`, `design-systems`, `slide-editing`, `slide-images`
 
 Domain skills follow the same format as framework skills. They encode patterns specific to the template that the agent needs to follow.
 
 ## App-backed skills {#app-backed-skills}
 
+App-backed skills package an agent-native app as a skill marketplace artifact. The bundle can include agent instructions, exported skills, MCP connector metadata, hosted/local launch instructions, and UI surfaces such as MCP Apps.
+
+> **Full details below:** the mechanics of app-backed skills (manifest format, CLI commands, marketplace adapters, auto-update hashing) are covered in [App-backed skills — full details](#app-backed-skills-full).
+
+## Creating custom skills {#creating-skills}
+
+Create a skill when:
+
+- There's a pattern the agent should follow repeatedly
+- A workflow needs step-by-step guidance
+- You want to scaffold files from a template
+
+Don't create a skill when:
+
+- The guidance already exists in another skill — extend it instead
+- The guidance is a one-off — put it in `AGENTS.md` or workspace memory instead
+
+## Skill format {#skill-format}
+
+Each skill is a Markdown file with YAML frontmatter:
+
+```markdown
+---
+name: project-imports
+description: >-
+  How to import projects from the legacy CSV export. Use when the user uploads
+  a project CSV or asks to migrate projects from the old system.
+---
+
+# Project Imports
+
+## Rule
+
+Always validate the CSV header row before writing any rows. Reject unknown
+columns rather than silently dropping them.
+
+## Why
+
+The legacy export has three known formats. Silently skipping columns causes data
+loss that is hard to notice until the migration is audited.
+
+## How
+
+1. Call `get-import-schema` to fetch the expected columns for the target project type.
+2. Parse the first CSV row and diff against the schema.
+3. If any required columns are missing, return an error listing them — do not proceed.
+4. Stream remaining rows through `create-project-item` in batches of 50.
+5. Return a summary: rows processed, rows skipped, and any errors.
+
+## Do
+
+- Run `view-screen` before importing so you know the user's current project context.
+- Use the `sharing` skill after import if the project should be shared with collaborators.
+
+## Don't
+
+- Don't hold all rows in memory — stream them.
+- Don't create duplicate projects; check for an existing project with the same name first.
+
+## Related Skills
+
+- **storing-data** — SQL schema and write patterns for new project rows
+- **sharing** — Exposing a project to other users after import
+```
+
+The frontmatter `name` and `description` are used by the agent's tool system for skill discovery. The description should state when the skill triggers — be specific about the situations.
+
+Save the file at `.agents/skills/my-skill/SKILL.md`. The directory name should match the `name` in frontmatter.
+
+> **See also:** [Writing Agent Instructions](/docs/writing-agent-instructions) for how to word skill descriptions, apply progressive disclosure, and keep `AGENTS.md` lean. Both pages use the `project-imports` skill as a running example.
+
+## 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}
+
+> **AGENTS.md** — The overview. Lists all scripts, describes the data model, explains the app architecture. The agent reads this first to understand the app.
+>
+> **Skills** — Deep dives. Each skill focuses on one pattern with detailed rules, code examples, and do/don't lists. The agent reads these when it needs to follow a specific pattern.
+
+`AGENTS.md` tells the agent _what_ the app does. Skills tell the agent _how_ to do specific things correctly. Both are needed — `AGENTS.md` for orientation, skills for execution.
+
+## Skills vs memory {#skills-vs-memory}
+
+> **Skills** — Authored, reusable how-to guides. Apply to every user, invoked on demand when the task matches.
+>
+> **Memory (`LEARNINGS.md` / `memory/MEMORY.md`)** — Shared project learnings and personal structured memory loaded every turn.
+
+If the knowledge applies to _everyone_ working in the app ("always prefer CTEs over subqueries"), it's a skill or shared `LEARNINGS.md`. If it's about _this particular user_ ("Steve likes concise answers"), it belongs in `memory/MEMORY.md`. See [Workspace Memory](/docs/workspace#memory) for the full treatment.
+
+---
+
+## App-backed skills — full details {#app-backed-skills-full}
+
 App-backed skills package an agent-native app as a skill marketplace artifact.
 The bundle can include agent instructions, exported skills, MCP connector
 metadata, hosted/local launch instructions, and UI surfaces such as MCP Apps.
@@ -144,107 +274,3 @@ npx @agent-native/core@latest skills update visual-plan
 the copied folder hash to the latest bundled skill, and rewrites stale folders in
 place. Newly copied Agent Native skills include an `agent-native-skill.json`
 marker so future status output can identify the source and hash.
-
-## Creating custom skills {#creating-skills}
-
-Create a skill when:
-
-- There's a pattern the agent should follow repeatedly
-- A workflow needs step-by-step guidance
-- You want to scaffold files from a template
-
-Don't create a skill when:
-
-- The guidance already exists in another skill — extend it instead
-- The guidance is a one-off — put it in `AGENTS.md` or workspace memory instead
-
-## Skill format {#skill-format}
-
-Each skill is a Markdown file with YAML frontmatter:
-
-```markdown
----
-name: my-skill
-description: >-
-  One-line description of what this skill covers and when
-  the agent should use it.
----
-
-# Skill Title
-
-## Rule
-
-The core invariant — what must always be true.
-
-## Why
-
-Why this rule exists. Motivates the agent to follow it.
-
-## How
-
-Step-by-step instructions with code examples.
-
-## Do
-
-- Concrete actions the agent should take
-
-## Don't
-
-- Anti-patterns to avoid
-
-## Related Skills
-
-- **other-skill** — How it relates
-```
-
-The frontmatter `name` and `description` are used by the agent's tool system for skill discovery. The description should state when the skill triggers — be specific about the situations.
-
-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}
-
-> **AGENTS.md** — The overview. Lists all scripts, describes the data model, explains the app architecture. The agent reads this first to understand the app.
->
-> **Skills** — Deep dives. Each skill focuses on one pattern with detailed rules, code examples, and do/don't lists. The agent reads these when it needs to follow a specific pattern.
-
-`AGENTS.md` tells the agent _what_ the app does. Skills tell the agent _how_ to do specific things correctly. Both are needed — `AGENTS.md` for orientation, skills for execution.
-
-## Skills vs memory {#skills-vs-memory}
-
-> **Skills** — Authored, reusable how-to guides. Apply to every user, invoked on demand when the task matches.
->
-> **Memory (`LEARNINGS.md` / `memory/MEMORY.md`)** — Shared project learnings and personal structured memory loaded every turn.
-
-If the knowledge applies to _everyone_ working in the app ("always prefer CTEs over subqueries"), it's a skill or shared `LEARNINGS.md`. If it's about _this particular user_ ("Steve likes concise answers"), it belongs in `memory/MEMORY.md`. See [Workspace Memory](/docs/workspace#memory) for the full treatment.

package/docs/content/template-analytics.md

@@ -67,6 +67,14 @@ The app has three primary surfaces you'll spend time in:
 
 The dictionary is seeded by asking the agent: "import our dbt definitions" or "pull the metrics from our Notion handbook" and it does the work.
 
+## Why it's interesting
+
+Three things make Analytics a good showcase of the framework:
+
+1. **The data dictionary keeps SQL grounded.** The agent consults the dictionary before writing any query, so it uses real warehouse column names and honors documented caveats. The dictionary is itself an agent-native resource — seeded and edited through the same chat interface that runs the queries.
+2. **Multi-source, single action surface.** BigQuery, GA4, Mixpanel, Amplitude, HubSpot, Jira, and a dozen other sources are each a single action file. Adding a new connector is adding a file; the agent picks it up automatically with no registration step.
+3. **Reusable workspace integrations.** When a workspace already has a provider connected (e.g. HubSpot), Analytics requests a grant instead of requiring a second copy of the same credentials. The Data Sources page shows workspace-level readiness alongside local-credential status.
+
 ## For developers
 
 The rest of this doc is for anyone forking the Analytics template or extending it.

package/docs/content/template-assets.md

@@ -13,6 +13,8 @@ Use it when your team needs reusable visual direction and searchable source asse
 
 ## Getting started
 
+Live demo: [assets.agent-native.com](https://assets.agent-native.com).
+
 1. **Create a library.** Add the brand, campaign, product, or content stream you
    want to manage.
 2. **Upload references.** Add approved logos, product shots, style examples, or

package/docs/content/template-brain.md

@@ -61,6 +61,8 @@ or issue.
 
 ## Getting started
 
+Live demo: [brain.agent-native.com](https://brain.agent-native.com).
+
 1. **Try the demo.** Open Ask and choose **Start demo**. Brain seeds a small
    product-decision corpus, runs the trust checks, and asks a cited question so
    you can see answers, citations, review, and not-found behavior before adding
@@ -77,14 +79,68 @@ For a public demo, the seeded corpus demonstrates product-decision recall,
 citation links, supersede behavior, review gating, redaction, personal-content
 exclusion, and honest not-found behavior without connecting a real workspace.
 
-### Scaffolding
+## Why it's interesting
+
+Three things make Brain a good showcase of the framework:
+
+1. **No vector database required.** Brain uses SQL text search with agentic query expansion, so it stays portable across SQLite, Postgres, Neon, D1, and Turso without an additional service dependency. This demonstrates that semantic-enough retrieval can be built without embedding infrastructure.
+2. **Human-in-the-loop distillation.** Raw captures don't become company knowledge automatically. High-confidence entries can auto-publish; sensitive or low-confidence ones queue as proposals for human review. The Review surface is a first-class part of the product, not a settings screen.
+3. **Shared workspace integrations.** Brain sources resolve credentials from workspace grants first, not duplicated env vars. It's a live example of the grant pattern — one Slack token at workspace level, per-app access requests.
+
+## For developers
+
+The rest of this section is for anyone forking or extending the Brain template.
+
+### Quick start
 
 ```bash
 npx @agent-native/core create my-brain --standalone --template brain
+cd my-brain
+pnpm install
+pnpm dev
 ```
 
-Then open the app, add sources, import a transcript, and ask the agent to
-distill cited memories from the raw capture.
+Open the app and choose **Start demo** to see cited memory without connecting a real workspace.
+
+### Data model
+
+Brain's schema lives in `templates/brain/server/db/schema.ts`. Eight tables:
+
+| Table                    | What it holds                                                                                                                                  |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `brain_sources`          | Connector config — provider, allow-listed channels/repos, sync cursors, review posture, `ingest_token_hash`, `status`, `last_synced_at`        |
+| `brain_source_shares`    | Per-source share grants (viewer / editor / admin)                                                                                              |
+| `brain_raw_captures`     | Transcripts, channel exports, notes, and webhook imports with `external_id` dedupe key, `content_hash`, kind, and distillation status          |
+| `brain_knowledge`        | Distilled atomic entries — kind (decision / fact / process / …), topic, entities, evidence quotes, confidence, `publish_tier`, supersede links |
+| `brain_knowledge_shares` | Per-knowledge share grants                                                                                                                     |
+| `brain_proposals`        | Pending review items — proposed create/update/archive with evidence and reviewer notes                                                         |
+| `brain_proposal_shares`  | Per-proposal share grants                                                                                                                      |
+| `brain_sync_runs`        | Sync audit log — provider, status, stats JSON, error, start/end timestamps                                                                     |
+| `brain_ingest_queue`     | Background distillation queue — operation, status, priority, retry count, `run_after`                                                          |
+
+### Key actions
+
+Grouped by area (`templates/brain/actions/`):
+
+- **Source management** — `create-source`, `update-source`, `delete-source`, `get-source`, `list-sources`, `sync-source`, `sync-due-sources`, `run-slack-pilot`, `test-slack-connection`
+- **Capture ingestion** — `import-capture`, `import-transcript`, `list-captures`, `get-capture`, `mark-capture-distilled`, `resanitize-captures`
+- **Distillation** — `enqueue-distillation`, `enqueue-captures-distillation`, `claim-distillation`, `retry-distillation`, `list-distillation-queue`
+- **Knowledge & review** — `write-knowledge`, `get-knowledge`, `list-knowledge`, `set-knowledge-canonical`, `preview-canonical-resource`, `list-proposals`, `review-proposal`, `approve-proposal`, `reject-proposal`, `update-proposal`
+- **Search & retrieval** — `ask-brain`, `search-knowledge`, `search-everything`
+- **Settings** — `get-brain-settings`, `update-brain-settings`, `set-settings`, `get-settings`
+- **Evaluation & demo** — `seed-demo-data`, `run-demo-eval`, `run-retrieval-eval`
+- **Context & navigation** — `view-screen`, `navigate`
+- **Provider APIs** — `provider-api-catalog`, `provider-api-docs`, `provider-api-request`
+
+### Customizing it
+
+Key places to look when extending Brain:
+
+- `templates/brain/actions/` — every agent-callable operation. Add a new file with `defineAction` to expose a new capability.
+- `templates/brain/app/routes/` — the UI surface: Ask, Sources, Review, Knowledge, Settings, and Team routes.
+- `templates/brain/.agents/skills/` — Brain-specific guidance for distillation and retrieval.
+- `templates/brain/AGENTS.md` — top-level agent guide. Update when you add major features.
+- `templates/brain/server/db/schema.ts` — data model. Additive migrations only.
 
 ## Connecting sources
 

package/docs/content/template-calendar.md

@@ -61,6 +61,14 @@ Or just ask the agent: "Create a 15-minute intro booking link with a name field.
 
 The agent will query Google Calendar live for any schedule question — it never guesses.
 
+## Why it's interesting
+
+Three things make Calendar a good showcase of the framework:
+
+1. **Live API queries, no local sync.** Events live in Google Calendar; the app queries the API on demand rather than maintaining a local mirror. This avoids stale data and webhook infrastructure while still giving the agent full read/write access through actions.
+2. **Booking links as a Calendly replacement.** The public booking page (`/book/{slug}`) is stateless to visitors — it queries availability live and creates a booking on submit. The `booking_link_shares` table wires into the framework sharing primitive so teammates can manage links collaboratively.
+3. **Multi-account overlay.** Connecting a second Google account is an action call; the UI overlays events from all connected calendars in the same view. This pattern — one row per account in `oauth_tokens`, list action that fans out — is reusable for any multi-account integration.
+
 ## For developers
 
 The rest of this doc is for anyone forking the Calendar template or extending it.

package/docs/content/template-clips.md

@@ -30,7 +30,9 @@ Think along the lines of Loom + Granola + Wispr Flow rolled into one app — but
 - **Smart library views.** Group by project, filter by speaker, auto-tag based on content.
 - **Edit the transcript through chat.** "Fix the mis-transcribed word at 1:42." "Pull three quotes for a blog post." The agent edits the transcript and the UI updates live.
 
-## Start Here
+## Getting started
+
+Live demo: [clips.agent-native.com](https://clips.agent-native.com).
 
 1. **Open Library.** Browse screen recordings, meeting recordings, dictations,
    folders, and spaces from one place.
@@ -65,9 +67,16 @@ The rest of this doc is for anyone forking the Clips template or extending it.
 
 ```bash
 npx @agent-native/core create my-clips --standalone --template clips
+cd my-clips
+pnpm install
+pnpm dev
 ```
 
-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.
+Clips is a larger template with a native recorder (it ships a desktop companion for local capture). Three setup steps are needed before recordings can upload:
+
+1. **Video storage (required).** Connect a storage backend through the onboarding wizard. The easiest path is Builder.io (free during beta, one-click). For self-hosted storage, set `S3_ENDPOINT`, `S3_BUCKET`, `S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, and optionally `S3_REGION` and `S3_PUBLIC_BASE_URL`. Cloudflare R2 and DigitalOcean Spaces use the same env vars with the `R2_*` prefix.
+2. **Google Calendar (optional).** To sync upcoming meetings, connect a Google Calendar account from Settings. The OAuth callback URL in dev is `http://localhost:8094/_agent-native/google/callback`. Set up a Google OAuth client in [Google Cloud Console](https://console.cloud.google.com/) with the Gmail and Google Calendar APIs enabled.
+3. **Screen-capture permissions.** On macOS, grant Screen Recording permission to the browser (or the desktop companion app) in System Settings → Privacy & Security → Screen Recording.
 
 ### Data model