@agent-native/core 0.6.1 → 0.7.1

package/docs/content/server.md

@@ -0,0 +1,200 @@
+---
+title: "Server"
+description: "Nitro server layer with file-based routing, server plugins, SSE handlers, and production agent configuration."
+---
+
+# Server
+
+Agent-native apps use [Nitro](https://nitro.build) for the server layer. Nitro is included automatically via the `defineConfig()` Vite plugin — you get file-based API routing, server plugins, and deploy-anywhere presets out of the box.
+
+## File-Based Routing {#file-based-routing}
+
+API routes live in `server/routes/`. Nitro auto-discovers them based on file name and path:
+
+```text
+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
+      [id]/
+        archive.patch.ts  → PATCH /api/items/:id/archive
+```
+
+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;
+});
+```
+
+### Route naming conventions {#route-naming-conventions}
+
+| File name pattern  | HTTP method | Example path               |
+| ------------------ | ----------- | -------------------------- |
+| `index.get.ts`     | GET         | `/api/items`               |
+| `index.post.ts`    | POST        | `/api/items`               |
+| `[id].get.ts`      | GET         | `/api/items/:id`           |
+| `[id].patch.ts`    | PATCH       | `/api/items/:id`           |
+| `[id].delete.ts`   | DELETE      | `/api/items/:id`           |
+| `[...slug].get.ts` | GET         | `/api/items/* (catch-all)` |
+
+### Accessing route parameters {#accessing-route-parameters}
+
+```ts
+import { defineEventHandler, getRouterParam, readBody, getQuery } from "h3";
+
+// GET /api/items/:id
+export default defineEventHandler(async (event) => {
+  const id = getRouterParam(event, "id");
+  const { filter } = getQuery(event);
+  // ...
+});
+```
+
+## Server Plugins {#server-plugins}
+
+Cross-cutting concerns — file watchers, file sync, scheduled jobs, auth — go in `server/plugins/`. Nitro runs these at startup before serving requests:
+
+```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}`);
+  }
+});
+```
+
+## Shared State Between Plugins and Routes {#shared-state}
+
+Use a shared module in `server/lib/` to pass state from plugins to route handlers:
+
+```ts
+// server/lib/watcher.ts
+import { createFileWatcher } from "@agent-native/core";
+import type { SSEHandlerOptions } from "@agent-native/core";
+
+export const watcher = createFileWatcher("./data");
+export const sseExtraEmitters: NonNullable<SSEHandlerOptions["extraEmitters"]> =
+  [];
+
+export let syncResult: any = { status: "disabled" };
+export function setSyncResult(result: any) {
+  syncResult = result;
+  if (result.status === "ready" && result.sseEmitter) {
+    sseExtraEmitters.push(result.sseEmitter);
+  }
+}
+```
+
+The plugin populates the state at startup; route handlers read it at request time.
+
+## createFileWatcher(dir, options?) {#createfilewatcher}
+
+Creates a chokidar file watcher for real-time file change detection:
+
+```ts
+import { createFileWatcher } from "@agent-native/core";
+
+const watcher = createFileWatcher("./data");
+// watcher emits "all" events: (eventName, filePath)
+```
+
+### Options {#filewatcher-options}
+
+| Option        | Type    | Description                                       |
+| ------------- | ------- | ------------------------------------------------- |
+| `ignored`     | any     | Glob patterns or regex to ignore                  |
+| `emitInitial` | boolean | Emit events for initial file scan. Default: false |
+
+## createSSEHandler(watcher, options?) {#createssehandler}
+
+Creates an H3 event handler that streams file changes as Server-Sent Events:
+
+```ts
+// server/routes/_agent-native/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 is JSON: `{ "type": "change", "path": "data/file.json" }`
+
+### Options {#ssehandler-options}
+
+| Option        | Type                        | Description                                       |
+| ------------- | --------------------------- | ------------------------------------------------- |
+| extraEmitters | `Array<{ emitter, event }>` | Additional EventEmitters to stream                |
+| contentRoot   | string                      | Root directory used to relativize paths in events |
+
+## createServer(options?) {#createserver}
+
+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 when file-based routing doesn't fit:
+
+```ts
+import { createServer } from "@agent-native/core";
+import { defineEventHandler } from "h3";
+
+const { app, router } = createServer();
+router.get("/api/items", defineEventHandler(listItems));
+```
+
+## mountAuthMiddleware(app, accessToken) {#mountauthmiddleware}
+
+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 two routes automatically: `POST /api/auth/login` and `POST /api/auth/logout`.
+
+## createProductionAgentHandler(options) {#createproductionagenthandler}
+
+Creates an H3 SSE handler at `POST /_agent-native/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 {#agent-handler-options}
+
+| Option         | Type                          | Description                                       |
+| -------------- | ----------------------------- | ------------------------------------------------- |
+| `scripts`      | `Record<string, ScriptEntry>` | Map of script name → { tool, run } entries        |
+| `systemPrompt` | string                        | System prompt for the embedded agent              |
+| `apiKey`       | string                        | Anthropic API key. Default: ANTHROPIC_API_KEY env |
+| `model`        | string                        | Model to use. Default: claude-sonnet-4-6          |

package/docs/content/skills-guide.md

@@ -0,0 +1,107 @@
+---
+title: "Skills Guide"
+description: "How skills work in agent-native: framework skills, domain skills, and creating custom skills."
+---
+
+# Skills Guide
+
+Skills are Markdown files that give the agent deep knowledge about specific patterns and workflows.
+
+## What are skills {#what-are-skills}
+
+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.
+
+## 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                 |
+
+## Domain skills {#domain-skills}
+
+Templates include skills specific to their domain. These live in the same `.agents/skills/` directory but cover template-specific patterns:
+
+- **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
+
+Domain skills follow the same format as framework skills. They encode patterns specific to the template that the agent needs to follow.
+
+## 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 `learnings.md` 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.
+
+## 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.

package/docs/content/what-is-agent-native.md

@@ -0,0 +1,100 @@
+---
+title: "What Is Agent-Native?"
+description: "What agent-native apps are, what agent-native development means, and why every AI agent needs a management interface."
+---
+
+# What Is Agent-Native?
+
+Agent-native is a way of building software where the AI agent and the UI are equal partners. Everything the agent can do, the UI can do. Everything the UI can do, the agent can do.
+
+## What is an agent-native app? {#what-is-an-agent-native-app}
+
+Think of agent-native apps as a layer on top of AI agents. An agent has skills, instructions, and tools. It can be autonomous and general purpose. The application sits on top of that and gives it structure.
+
+Importantly, agent-native does **not** mean "app that calls an LLM." That's the anti-pattern. A text box that sends a prompt and returns a response gives you no ability to give feedback, no way to understand what the agent is doing, and no way to customize its behavior with instructions and skills.
+
+An agent-native app gives you everything good about traditional applications — databases, dashboards, workflows, persistence, shareability — plus everything good about AI agents. The agent can do anything the UI can do, and the things it does persist to the UI so you can inspect them, visualize them, and share them.
+
+## Not just a chatbot {#not-just-a-chatbot}
+
+A chat interface alone isn't enough. When you're building tools for people to actually use, you need more than a box for them to type a prompt into:
+
+- **Discoverability** — users need to know what the app can do without guessing prompts
+- **Workflows** — structured flows for common tasks like composing emails, creating events, or building forms
+- **Visualization** — charts, calendars, email threads, and slide decks are better as visual interfaces than text
+- **Persistence** — a dashboard to come back to, data that doesn't disappear between sessions
+- **Shareability** — share a form link, a slide deck URL, or a report with your team
+- **Speed** — clicking a button is faster than typing a prompt for routine tasks
+
+Agent-native apps give you all of this while keeping the full power of the AI agent. The agent is always there — you can ask it to do anything. But the UI makes common workflows fast, visual, and accessible to everyone on the team.
+
+## Agent + UI parity {#agent-ui-parity}
+
+This is the defining principle. Any application functionality should be able to be done by the agent _or_ the UI:
+
+> **From the UI** — Click buttons, fill forms, navigate views. The UI writes to the database and the agent can see the results.
+>
+> **From the agent** — Natural language, other agents via A2A, Slack, Telegram. The agent writes to the database and the UI updates automatically.
+
+When the agent creates a draft email, it appears in the UI. When the user clicks "Send," the agent knows it was sent. There's no separate "agent world" and "UI world" — it's one system.
+
+## What makes it different {#what-makes-it-different}
+
+Every agent ultimately needs a management interface. At the minimum, you need to understand what it's doing, inspect the data it's creating, and debug when things go wrong. That's just called an application.
+
+| Approach                               | Description                                                                                                                            |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| **Traditional apps with AI bolted on** | The AI is an afterthought. Limited to autocomplete, summaries, or a chat sidebar that can't actually do anything in the app.           |
+| **Agent-native apps**                  | The agent is a first-class citizen. It shares the same database, the same state, and can do everything the UI can do — and vice versa. |
+| **Pure chat/agent interfaces**         | Powerful but inaccessible. No dashboards, no workflows, no persistence. Non-developers can't use them effectively.                     |
+| **Agent-native apps**                  | Full application UI with discoverability, workflows, and visualization — plus the agent for anything that needs AI.                    |
+
+The argument is simple: make your agents composable, think of them as applications. An analytics application, a slide generation application, a document application. Each one is a complete tool that humans and agents can both use.
+
+## What is agent-native development? {#what-is-agent-native-development}
+
+Agent-native development means building with agents first. You build projects that work great when prompted from AI coding tools like Claude Code, Codex, Cursor, Windsurf, and Builder.io.
+
+The idea is that you build instructions and skills into the project as prerequisites. The agent will tend to do _better_ than a human developer because you can encode rules like "when you add a feature, also add a skill for it" — things that humans will tend to forget or skip reading the docs for.
+
+## Agents as first-class developers {#agents-as-first-class-developers}
+
+In an agent-native project:
+
+- **AGENTS.md** gives every AI coding tool the same instructions — Claude Code, Cursor, Windsurf, and others all read the same file
+- **Skills** teach the agent patterns for specific tasks — adding features, storing data, wiring real-time sync
+- **Agent PR reviewers** can validate that the four-area checklist was followed, that skills were updated, and that the code matches the project's conventions
+- **Auto-maintained docs and tests** — agents can be instructed to keep documentation up to date and tests passing, making it easier for humans to contribute
+
+This is similar to the shift from desktop-first to mobile-first development. Mobile-first didn't mean "no desktop" — it meant designing for mobile constraints first and then scaling up. Agent-native development means designing for agent workflows first and then making sure humans can work effectively too.
+
+## Whole-team development {#whole-team-development}
+
+Agent-native development isn't just for developers. The goal is actual agent-native development as a team:
+
+- **Designers** can update designs directly in the code through the agent
+- **Product managers** can update functionalities and requirements
+- **QA** can test and prompt for fixes
+- **Anyone on the team** can contribute through natural language
+
+The vision is to reduce handoffs and enable one-person-to-full-team productivity using real collaboration between humans and agents.
+
+## Fork and customize {#fork-and-customize}
+
+Agent-native apps follow a fork-and-customize model. You start from a template — mail, calendar, analytics, slides — and make it yours:
+
+1. Pick a template on [agentnative.com](/templates)
+2. Start using it immediately as a hosted app (e.g. mail.agentnative.com)
+3. Fork it when you want to customize — "connect to our Stripe account", "add a cohort chart"
+4. The agent modifies the code to match your needs
+5. Deploy your fork to your own domain
+
+Because it's your app — not shared infrastructure — the agent can safely evolve the code over time. Your app keeps improving as you use it.
+
+## Composable agents {#composable-agents}
+
+Agent-native apps can communicate with each other using the [A2A protocol](/docs/a2a-protocol). From the mail app, you can tag the analytics agent to query data and include results in a draft. An agent discovers what other agents are available, calls them over the protocol, and shows results in the UI.
+
+This is why agent-native is a **framework and not a library**. The architecture — shared database, polling sync, actions, application state — needs to be built in from the ground up. You can migrate existing apps, but the best practice is to build agent-native from the start.
+
+See the [Key Concepts](/docs/key-concepts) doc for the full technical details.

package/docs/content/workspace-management.md

@@ -0,0 +1,224 @@
+---
+title: "Workspace Management"
+description: "Branching strategies, code ownership, PR review, and governance practices for agent-native workspaces."
+---
+
+# Workspace Management
+
+This guide covers the operational side of running an agent-native workspace — how to branch, who reviews what, how to set up code ownership, and how the dispatch control plane fits into your governance model.
+
+For workspace setup, shared auth, and deployment, see [Enterprise Workspace](/docs/enterprise-workspace).
+
+## Branching
+
+### Feature Branches
+
+Use short-lived feature branches for all work:
+
+```
+main                         ← production
+├── feat/mail-filters        ← single-app change
+├── feat/core-oauth-refresh  ← framework change
+├── fix/analytics-chart      ← targeted bug fix
+└── feat/vault-encryption    ← dispatch/infra change
+```
+
+**Naming conventions:**
+
+- **Single-app changes:** `feat/<app>-<description>` or `fix/<app>-<description>` — e.g. `feat/mail-thread-search`, `fix/recruiting-resume-parse`
+- **Framework changes:** `feat/core-<description>` or `fix/core-<description>` — e.g. `feat/core-polling-v2`
+- **Dispatch changes:** `feat/dispatch-<description>` — e.g. `feat/dispatch-vault-policies`
+- **Cross-app changes:** if a framework change requires template updates, do both in one branch so they ship atomically
+
+Keep branches short-lived. Long-lived branches diverge from main and create painful merges — especially in a monorepo where multiple teams push daily.
+
+### Non-Developer Branching
+
+Not everyone who needs to make changes is comfortable with git. For teams with designers, product managers, or content editors who need to make visual changes:
+
+[Builder.io](https://www.builder.io) supports a visual branching model that maps to git branches under the hood:
+
+- Create branches from Builder's dashboard — no terminal needed
+- Edit content, components, layouts, and configuration visually
+- Preview changes in isolation before merging
+- Changes map to git branches, so developer and non-developer work converges
+
+This is useful for content and copy changes, layout adjustments, design iterations, and A/B testing — work that shouldn't require a dev environment. Developer code changes and Builder visual changes can coexist on the same branch.
+
+## Code Ownership
+
+GitHub's CODEOWNERS file auto-assigns reviewers to PRs based on which files changed. In a monorepo with many apps, this is how you make sure the right people review the right code without everyone reviewing everything.
+
+### Example CODEOWNERS
+
+Create `.github/CODEOWNERS` at the repo root:
+
+```
+# Framework core — platform/infra team reviews all changes here
+# because they affect every app in the workspace
+packages/core/                     @your-org/platform-team
+
+# Desktop app shell
+packages/desktop-app/              @your-org/platform-team
+
+# Dispatch control plane — secrets, integrations, workspace resources
+templates/dispatcher/              @your-org/platform-team
+
+# Per-app ownership — each team reviews their own app
+templates/mail/                    @your-org/mail-team
+templates/analytics/               @your-org/analytics-team
+templates/calendar/                @your-org/calendar-team
+templates/content/                 @your-org/content-team
+templates/recruiting/              @your-org/recruiting-team
+templates/forms/                   @your-org/forms-team
+templates/issues/                  @your-org/issues-team
+templates/slides/                  @your-org/slides-team
+templates/videos/                  @your-org/videos-team
+
+# Workspace-level config — broad review since it affects everyone
+.github/                           @your-org/platform-team
+package.json                       @your-org/platform-team
+pnpm-workspace.yaml                @your-org/platform-team
+.env.example                       @your-org/platform-team
+```
+
+### Tips
+
+- **Use GitHub teams, not individuals.** `@org/analytics-team` survives people changing roles. `@jdoe` doesn't.
+- **Framework changes need platform review.** A one-line change in `packages/core/` can break every app. The platform team should always see these.
+- **App teams own their templates.** The people who built and maintain an app understand its domain — they should review changes to it.
+- **Dispatch is infrastructure.** Treat it like core. It manages secrets and resources that affect the whole workspace.
+- **You can narrow with globs.** `templates/mail/**/*.tsx` if you want to assign frontend-specific reviewers for UI-only changes.
+- **Multiple owners are fine.** List both the app team and a senior engineer for critical paths like DB schemas or auth.
+
+### Enabling Required Reviews
+
+1. Create `.github/CODEOWNERS` with the patterns above
+2. In GitHub → Settings → Branches → Branch protection for `main`:
+   - Enable **Require a pull request before merging**
+   - Enable **Require review from Code Owners**
+   - Set minimum required approvals (1 is usually fine, 2 for regulated environments)
+3. Create the GitHub teams referenced in CODEOWNERS
+
+Once enabled, GitHub won't let a PR merge until each CODEOWNERS-matched team has approved. A PR that touches `templates/mail/` and `packages/core/` requires approval from both `@your-org/mail-team` and `@your-org/platform-team`.
+
+## PR Labeling
+
+Auto-labeling PRs by app makes it easy to filter and prioritize reviews. Add `.github/labeler.yml`:
+
+```yaml
+app:mail:
+  - changed-files:
+      - any-glob-to-any-file: templates/mail/**
+
+app:analytics:
+  - changed-files:
+      - any-glob-to-any-file: templates/analytics/**
+
+app:calendar:
+  - changed-files:
+      - any-glob-to-any-file: templates/calendar/**
+
+app:recruiting:
+  - changed-files:
+      - any-glob-to-any-file: templates/recruiting/**
+
+dispatch:
+  - changed-files:
+      - any-glob-to-any-file: templates/dispatcher/**
+
+core:
+  - changed-files:
+      - any-glob-to-any-file: packages/core/**
+```
+
+Then add the [actions/labeler](https://github.com/actions/labeler) GitHub Action to `.github/workflows/labeler.yml`:
+
+```yaml
+name: Label PRs
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/labeler@v5
+```
+
+Labels apply automatically when PRs are opened or updated. Teams can then filter their review queue by label.
+
+## PR Review Guidelines
+
+### By Change Type
+
+| Change type                       | Who reviews                           | What to watch for                                                         |
+| --------------------------------- | ------------------------------------- | ------------------------------------------------------------------------- |
+| **App-only** (`templates/<app>/`) | Owning app team                       | Domain correctness, action schemas                                        |
+| **Framework** (`packages/core/`)  | Platform team + one affected app team | Breaking changes, performance, backwards compat                           |
+| **Schema migrations**             | Platform team + senior engineer       | Data safety, dialect agnosticism (SQLite + Postgres)                      |
+| **Actions**                       | Owning team                           | Actions are both agent tools AND HTTP endpoints — review from both angles |
+| **Cross-app A2A**                 | Both app teams                        | If you change an A2A interface, the callers need to know                  |
+| **Dispatch vault/resources**      | Platform team                         | Secret access, grant scope, who gets what                                 |
+
+### Concurrent Agent Work
+
+Agent-native workspaces often have multiple AI agents working on the same branch simultaneously. This is by design — the agents share a branch and push independently.
+
+When reviewing PRs in this environment:
+
+- **Don't revert changes you didn't make** unless they're clearly broken
+- **Files may be modified by multiple agents** in the same PR — this is normal
+- **Run `pnpm run prep`** (typecheck + test + format) before pushing to catch integration issues between agents' changes
+- **If two agents touch the same file,** the later commit wins. Conflicts surface at review time, not at commit time
+- **Fix bugs in any code in the PR,** regardless of which agent wrote it. The PR is reviewed as a whole.
+
+## Dispatch as Governance
+
+The dispatch app is the workspace's runtime control plane. It complements git-level governance with runtime governance:
+
+| Concern                         | Git / GitHub                  | Dispatch                                   |
+| ------------------------------- | ----------------------------- | ------------------------------------------ |
+| Who can change code             | CODEOWNERS, branch protection | —                                          |
+| Who can access secrets          | —                             | Vault grants + request workflow            |
+| What instructions agents follow | —                             | Workspace resources (skills, instructions) |
+| Which agents are shared         | —                             | Workspace agent profiles                   |
+| Integration inventory           | —                             | Integrations catalog                       |
+| Runtime change approval         | —                             | Dispatch approval flow                     |
+| Audit trail                     | `git log` / `git blame`       | Vault audit + dispatch audit logs          |
+| Messaging & routing             | —                             | Slack / Telegram integration               |
+
+**Git handles code governance. Dispatch handles runtime governance.** Don't try to replicate git workflows inside dispatch or vice versa. They cover different surfaces.
+
+### What Dispatch Manages
+
+- **Vault** — store credentials centrally, grant them to specific apps, sync on demand. Non-admins can request access; admins approve.
+- **Integrations catalog** — see which credentials each app needs, what's configured, what's missing, what's granted from the vault.
+- **Workspace resources** — share skills, behavioral instructions, and reusable agent profiles across apps. Scope to all apps or grant per-app.
+- **Approvals** — require review before runtime changes (destinations, settings) take effect.
+- **Audit** — full history of secret access, grants, syncs, and changes.
+
+## Setup Checklist
+
+For a new workspace, after running `agent-native create`:
+
+**Git & GitHub:**
+
+- [ ] Create `.github/CODEOWNERS` with per-app team ownership
+- [ ] Enable branch protection on `main` with required code owner reviews
+- [ ] Add `.github/labeler.yml` for auto-labeling PRs by app
+- [ ] Create GitHub teams for each app and the platform team
+
+**Dispatch:**
+
+- [ ] Add shared secrets to the vault (API keys, OAuth credentials, etc.)
+- [ ] Grant secrets to the apps that need them
+- [ ] Sync granted secrets to push them to apps
+- [ ] Add workspace-wide skills and instructions via the Resources page
+- [ ] Configure the approval policy and approver emails
+- [ ] Set up SendGrid (`SENDGRID_API_KEY`, `SENDGRID_FROM_EMAIL`) for admin notifications
+- [ ] Connect Slack or Telegram for workspace messaging