@agent-native/core 0.6.1 → 0.7.1

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

@@ -0,0 +1,185 @@
+---
+title: "Real-Time Collaboration"
+description: "Multi-user collaborative editing with Yjs CRDT, live cursors, and AI agent real-time edits."
+---
+
+# Real-Time Collaboration
+
+Multi-user collaborative editing where the AI agent and human users are equal participants — like Google Docs, but with an AI collaborator.
+
+## Overview {#overview}
+
+The framework provides a Yjs-based collaborative editing system in `@agent-native/core/collab`. Multiple users can edit the same document simultaneously with live cursor positions, and the AI agent can make surgical edits that appear in real-time without disrupting the user's cursor, selection, or undo history.
+
+This is built on three battle-tested technologies: **Yjs** (CRDT for conflict-free merging), **TipTap** (rich text editor), and **polling-based sync** (works in all deployment environments including serverless and edge).
+
+## How it works {#how-it-works}
+
+The collaboration system has three layers:
+
+- **Yjs Y.Doc** — stores the document as a `Y.XmlFragment` (ProseMirror node tree). This is the CRDT that enables conflict-free merging of concurrent edits.
+- **TipTap Collaboration extension** — binds the editor to the Y.XmlFragment via `ySyncPlugin`. Remote changes are applied as minimal ProseMirror transactions that preserve cursor position.
+- **Polling sync** — clients poll `/_agent-native/poll` every 2 seconds for Yjs updates. Awareness state (cursor positions, user info) is synced via a separate `/_agent-native/collab/:docId/awareness` endpoint.
+
+The Yjs state is persisted in a `_collab_docs` SQL table as base64-encoded binary, compatible with both SQLite and Postgres.
+
+## Agent + human collaboration {#agent-human-collab}
+
+The agent and human users are equal participants in collaborative editing. The key insight is that both produce Yjs operations that merge cleanly:
+
+- **Human edits** flow through TipTap → ySyncPlugin → Y.XmlFragment → server via HTTP
+- **Agent edits** flow through the `edit-document` action → server search-replace endpoint → Y.XmlFragment mutation → poll update → all clients
+
+The agent's `edit-document` action uses surgical search-and-replace on Y.XmlText nodes within the Y.XmlFragment tree. This produces the smallest possible Yjs update — only the changed text is modified, not the entire document. The result: the user sees the agent's change appear in their editor without losing their place.
+
+```bash
+# Agent makes a surgical edit — user sees it appear live
+pnpm action edit-document --id doc123 --find "Big Projects" --replace "Proyectos Grandes"
+
+# The action:
+# 1. Updates SQL content column (for search/API compat)
+# 2. Calls POST /_agent-native/collab/doc123/search-replace
+# 3. Server walks Y.XmlFragment, finds text, modifies Y.XmlText node
+# 4. Minimal Yjs update emitted via poll system
+# 5. Client receives update → ySyncPlugin applies targeted PM transaction
+# 6. User's cursor stays in place ✓
+```
+
+## Enabling collaboration {#enabling-collab}
+
+Templates opt into collaboration with five steps:
+
+### 1. Install dependencies
+
+```bash
+pnpm add @tiptap/extension-collaboration @tiptap/extension-collaboration-caret @tiptap/y-tiptap @tiptap/core
+```
+
+### 2. Add Vite optimizeDeps
+
+Prevents Vite from re-bundling TipTap in incompatible ways during dev:
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [reactRouter()],
+  optimizeDeps: {
+    include: [
+      "yjs",
+      "y-protocols/awareness",
+      "@tiptap/core",
+      "@tiptap/extension-collaboration",
+      "@tiptap/extension-collaboration-caret",
+      "@tiptap/y-tiptap",
+    ],
+  },
+});
+```
+
+### 3. Add the collab server plugin
+
+```typescript
+// server/plugins/collab.ts
+import { createCollabPlugin } from "@agent-native/core/server";
+
+export default createCollabPlugin({
+  table: "documents",
+  contentColumn: "content",
+  idColumn: "id",
+  autoSeed: false, // Client-side seeding on first load
+});
+```
+
+### 4. Use the client hook
+
+```typescript
+import { useCollaborativeDoc, generateTabId } from "@agent-native/core/client";
+
+const TAB_ID = generateTabId();
+
+const { ydoc, awareness, isLoading, activeUsers } = useCollaborativeDoc({
+  docId: documentId,
+  requestSource: TAB_ID,
+  user: { name: "Steve", email: "steve@example.com", color: "#60a5fa" },
+});
+```
+
+### 5. Add TipTap extensions
+
+```typescript
+import Collaboration from "@tiptap/extension-collaboration";
+import CollaborationCaret from "@tiptap/extension-collaboration-caret";
+import { Awareness } from "y-protocols/awareness";
+
+// Create awareness for cursor sync
+const awareness = new Awareness(ydoc);
+awareness.setLocalStateField("user", { name, color });
+
+const editor = useEditor({
+  extensions: [
+    StarterKit.configure({ history: false }), // Yjs handles undo
+    Collaboration.configure({ document: ydoc }),
+    CollaborationCaret.configure({
+      provider: { awareness },
+      user: { name, color },
+    }),
+  ],
+  content: initialContent,
+});
+```
+
+## Live cursors & presence {#live-cursors}
+
+The `CollaborationCaret` extension renders colored cursor lines with user name labels for each connected user. The `useCollaborativeDoc` hook provides an `activeUsers` array that can be used to render a presence bar with user avatars.
+
+User identity is derived from the session email. The framework provides `emailToColor()` and `emailToName()` helpers to generate consistent cursor colors and display names from email addresses.
+
+## Comments {#comments}
+
+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`
+- 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()`
+- Agent actions: `list-comments`, `add-comment`
+- Notion comment sync: `sync-notion-comments` action for bidirectional pull/push
+
+## Collab routes {#collab-routes}
+
+All collab routes are auto-mounted under `/_agent-native/collab/` by the collab plugin:
+
+| Route                         | Purpose                                  |
+| ----------------------------- | ---------------------------------------- |
+| `GET /:docId/state`           | Fetch full Y.Doc state (base64)          |
+| `POST /:docId/update`         | Apply client Yjs update                  |
+| `POST /:docId/text`           | Apply full text replacement (diff-based) |
+| `POST /:docId/search-replace` | Surgical find/replace in Y.XmlFragment   |
+| `POST /:docId/awareness`      | Sync cursor/presence state               |
+| `GET /:docId/users`           | List active users on a document          |
+
+## Agent edit action {#edit-document}
+
+The `edit-document` action is the primary way agents make changes to documents in collaborative mode:
+
+```bash
+# Single edit
+pnpm action edit-document --id doc123 --find "old text" --replace "new text"
+
+# Batch edits
+pnpm action edit-document --id doc123 --edits '[{"find":"old","replace":"new"}]'
+
+# Delete text
+pnpm action edit-document --id doc123 --find "delete me" --replace ""
+```
+
+When collab state exists for the document, the action calls the server's `search-replace` endpoint via HTTP (not the collab module directly, since actions run in a separate process). The server walks the Y.XmlFragment tree, finds the text in Y.XmlText nodes, and applies minimal delete/insert operations. The resulting Yjs update is broadcast to all connected clients via the poll system.
+
+## Common pitfalls {#pitfalls}
+
+- **TipTap version mismatch** — All `@tiptap/*` packages must be the same version. The Collaboration extension requires `editor.utils` which was added in v3.22.2. Add `@tiptap/core` as an explicit dependency.
+- **Empty editor on first load** — The Collaboration extension does NOT auto-seed from the `content` prop. Seed manually with `editor.commands.setContent()` when the Y.XmlFragment is empty.
+- **Data loss from empty saves** — Guard against saving empty content in the `onUpdate` handler when the editor is in collab mode but hasn't been seeded yet.
+- **Vite dep optimization** — Always add Yjs-related packages to `optimizeDeps.include` to prevent Vite from re-bundling TipTap in incompatible ways.
+- **Separate process for actions** — Actions run via `pnpm action` in a new Node.js process. Use the server's HTTP endpoints (not the collab module directly) so updates reach the poll system.

package/docs/content/resources.md

@@ -0,0 +1,277 @@
+---
+title: "Workspace Resources"
+description: "SQL-backed workspace files for notes, skills, custom agents, scheduled tasks, and instructions."
+---
+
+# Workspace Resources
+
+The **Workspace** tab is where you and the agent share persistent files — notes, instructions, skills, custom agents, and scheduled jobs. Files live in the database (not the filesystem), so they persist across sessions, work in serverless/edge deploys, and can be edited from both the UI and the agent.
+
+## TL;DR {#tldr}
+
+- Open the **Workspace** tab in the agent sidebar.
+- Create files with the `+` menu. Upload with the upload button. Edit inline (visual or code view).
+- **Personal** is just you. **Shared** is your team/org.
+- The agent can read, write, and rename any of these files as part of a conversation.
+- Special files the agent always reads: `AGENTS.md` (team rules) and `learnings.md` (per-user).
+
+## What goes in here? {#what-goes-in-here}
+
+| File / path               | What it's for                                                                                 |
+| ------------------------- | --------------------------------------------------------------------------------------------- |
+| `AGENTS.md` (Shared)      | Team instructions the agent reads every turn — tone, rules, domain context, skill references. |
+| `learnings.md` (Personal) | Corrections and preferences the agent records per user so it doesn't repeat mistakes.         |
+| `skills/<name>.md`        | Focused domain guidance the agent pulls in on demand (invoked with `/` slash commands).       |
+| `agents/<name>.md`        | Custom sub-agent profiles the agent can delegate to (invoked with `@` mentions).              |
+| `agents/<name>.json`      | A2A manifests for connected remote agents.                                                    |
+| `jobs/<name>.md`          | Scheduled tasks that run on a cron (see the recurring-jobs docs).                             |
+| Anything else             | Notes, prompts, config, dataset snippets — any text file.                                     |
+
+## Overview {#overview}
+
+Every agent-native app has a built-in resource system. Resources are SQL-backed files that persist across sessions and deployments. Unlike code files, resources live in the database — not the filesystem — so they work in serverless environments, edge runtimes, and production deploys without any filesystem dependency.
+
+Resources have two scopes:
+
+- **Personal** — scoped to a single user (their email). Good for preferences, notes, and per-user context.
+- **Shared** — visible to all users. Good for team instructions, skills, and shared config.
+
+## Workspace Panel {#workspace-panel}
+
+The agent panel includes a **Workspace** tab alongside Chat and CLI. This panel lets users browse, create, edit, and delete workspace resources. It displays a tree view of all resources organized by folder path.
+
+Resources can be any text file — Markdown, JSON, YAML, plain text. The panel includes an inline editor for viewing and modifying resource content directly.
+
+The `+` menu in Workspace supports typed creation flows for:
+
+- **Files** — arbitrary resources
+- **Skills** — reusable instruction files under `skills/`
+- **Agents** — custom sub-agent profiles under `agents/*.md`
+- **Scheduled Tasks** — recurring jobs under `jobs/`
+
+Workspace resources come in two scopes:
+
+- **Personal** — visible only to the current user
+- **Shared** — visible across the team/org
+
+Click the `?` icon in the Workspace toolbar to jump back to these docs at any time.
+
+## Getting Started: a 1-minute walkthrough {#getting-started}
+
+Change how the agent behaves, in 60 seconds.
+
+1. Open the **Workspace** tab → **Shared** → `AGENTS.md` (create it with `+` → **File** if missing).
+2. Add one rule, e.g.:
+
+   ```markdown
+   ## Tone
+
+   Be concise. Lead with the answer.
+   ```
+
+3. Save, switch to **Chat**, ask anything — the agent follows the new rule immediately.
+
+**Next steps, when you want them:**
+
+- **Skills** (`+` → **Skill**) — focused how-to files invoked in chat with `/skill-name`.
+- **Agents** (`+` → **Agent**) — reusable sub-agent personas invoked with `@agent-name`.
+- **Scheduled Tasks** (`+` → **Scheduled Task**) — prompts that run on a cron.
+- **learnings.md** — your Personal file the agent auto-updates whenever you correct it.
+
+## How the Agent Uses Resources {#how-the-agent-uses-resources}
+
+The agent has built-in tools for managing resources: `resource-list`, `resource-read`, `resource-write`, and `resource-delete`. These are available in both dev and production modes.
+
+At the start of every conversation, the agent automatically reads:
+
+### AGENTS.md {#agents-md}
+
+A shared resource seeded by default. It contains custom instructions, preferences, and skill references. Edit this to change how the agent behaves for all users — tone, rules, domain context, and which skills to use.
+
+```text
+# Agent Instructions
+
+## Tone
+Be concise. Lead with the answer.
+
+## Code style
+- Use TypeScript, never JavaScript
+- Prefer named exports
+
+## Skills
+| Skill | Path | Description |
+|-------|------|-------------|
+| data-analysis | `skills/data-analysis.md` | BigQuery and data workflows |
+```
+
+### learnings.md {#learnings-md}
+
+A personal resource where the agent records corrections, preferences, and patterns it learns from each user. When the agent makes a mistake and the user corrects it, the agent updates `learnings.md` so it doesn't repeat the error.
+
+## Skills {#skills}
+
+Skills are Markdown resource files that give the agent deep domain knowledge for specific tasks. They live under the `skills/` path prefix in resources (e.g. `skills/data-analysis.md`, `skills/code-review.md`).
+
+When the agent encounters a task that matches a skill, it reads the skill file and follows its guidance. Skills referenced in `AGENTS.md` are discovered automatically.
+
+### Creating Skills {#creating-skills}
+
+There are two ways to add skills:
+
+1. **Via Workspace tab** — Create a new resource with a path like `skills/my-skill.md`. This works in both dev and production.
+2. **Via code (dev only)** — Add a Markdown file to `.agents/skills/` in your project. These are available when the app runs in dev mode.
+
+## Custom Agents {#custom-agents}
+
+Custom agents are reusable local sub-agent profiles stored as Markdown resources under `agents/*.md`.
+
+Use them when you want a focused delegate with its own:
+
+- name
+- description
+- model preference
+- instruction set
+
+Unlike skills, custom agents are not passive guidance. They are operational personas the main agent can invoke through `@` mentions or by selecting them during sub-agent spawning.
+
+### Agent format {#agent-format}
+
+Custom agents use YAML frontmatter plus Markdown instructions:
+
+```markdown
+---
+name: Design
+description: >-
+  Reviews layouts, interaction patterns, and product UX decisions.
+model: inherit
+tools: inherit
+delegate-default: false
+---
+
+# Role
+
+You are a focused design agent.
+
+## Responsibilities
+
+- Review layouts and interaction flows
+- Suggest stronger visual direction
+- Be concise and opinionated
+```
+
+Recommended conventions:
+
+- Store custom agents at `agents/<slug>.md`
+- Use `model: inherit` unless the profile clearly needs a different model
+- Keep `tools: inherit` for now; the field is reserved for future tool policies
+
+### Remote agents vs custom agents {#remote-vs-custom-agents}
+
+There are two agent types in Workspace:
+
+- **Custom agents** — local profiles in `agents/*.md`, executed inside the current app/runtime
+- **Connected agents** — remote A2A peers described by manifests in `agents/*.json`
+
+Use custom agents for delegation within one app. Use connected agents when you need to call another app over A2A.
+
+### Skill Format {#skill-format}
+
+Skills are Markdown files with optional YAML frontmatter for metadata:
+
+````text
+---
+name: data-analysis
+description: BigQuery queries, data transforms, and visualization
+---
+
+# Data Analysis
+
+## When to use
+Use this skill when the user asks about data, queries, or analytics.
+
+## Rules
+- Always validate SQL before executing
+- Prefer CTEs over subqueries
+- Include LIMIT on exploratory queries
+
+## Patterns
+```sql
+-- Standard BigQuery date filter
+WHERE DATE(created_at) BETWEEN @start_date AND @end_date
+````
+
+````
+
+## @ Tagging {#at-tagging}
+
+Type `@` in the chat input to reference workspace items. A dropdown appears at the cursor showing matching agents and files. Use arrow keys to navigate and Enter to select. The selected item appears as an inline chip in the input.
+
+When you send a message:
+
+- **Files/resources** are passed as references the agent can read
+- **Custom agents** run locally with their profile instructions
+- **Connected agents** are called over A2A
+
+What shows up depends on the mode:
+
+- **Dev mode** — Codebase files, workspace resources, custom agents, and connected agents
+- **Production mode** — Workspace resources, custom agents, and connected agents
+
+## / Slash Commands {#slash-commands}
+
+Type `/` at the start of a line to invoke a skill. A dropdown shows available skills with their names and descriptions. Selecting a skill adds it as an inline chip, and its content is included as context when the message is sent.
+
+What shows up depends on the mode:
+
+- **Dev mode** — Skills from `.agents/skills/` (codebase) and skills from resources
+- **Production mode** — Skills from resources only
+
+If no skills are configured, the dropdown shows a hint with a link to these docs.
+
+## Dev vs Production Mode {#dev-vs-prod}
+
+The resource system works identically in both modes. The difference is what additional sources are available for `@` tagging and `/` commands:
+
+| Feature | Dev Mode | Production |
+|---------|----------|------------|
+| @ tagging | Codebase files + workspace resources + custom agents + connected agents | Workspace resources + custom agents + connected agents |
+| / slash commands | .agents/skills/ + resource skills | Resource skills only |
+| Agent file access | Filesystem + resources | Resources only |
+| Workspace panel | Full access | Full access |
+| AGENTS.md / learnings.md | Available | Available |
+
+## Resource API {#resource-api}
+
+Resources can be managed from server code, actions, or the REST API.
+
+### Server API {#server-api}
+
+REST endpoints mounted automatically:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/_agent-native/resources?scope=all` | List resources |
+| `GET` | `/_agent-native/resources/tree?scope=all` | Get folder tree |
+| `POST` | `/_agent-native/resources` | Create a resource |
+| `GET` | `/_agent-native/resources/:id` | Get resource with content |
+| `PUT` | `/_agent-native/resources/:id` | Update a resource |
+| `DELETE` | `/_agent-native/resources/:id` | Delete a resource |
+| `POST` | `/_agent-native/resources/upload` | Upload a file as resource |
+
+### Action API {#script-api}
+
+The agent uses these built-in actions. You can also call them from your own actions:
+
+```bash
+# List all resources
+pnpm action resource-list --scope all
+
+# Read a resource
+pnpm action resource-read --path "skills/my-skill.md"
+
+# Write a resource
+pnpm action resource-write --path "notes/meeting.md" --content "# Meeting Notes..."
+
+# Delete a resource
+pnpm action resource-delete --path "notes/old.md"
+````

package/docs/content/security.md

@@ -0,0 +1,158 @@
+---
+title: "Security"
+description: "Security model for agent-native apps: input validation, SQL injection prevention, XSS, data scoping, secrets management, and auth patterns."
+---
+
+# Security
+
+Agent-native apps are designed to be secure by default. The framework provides automatic protections at multiple layers — you get SQL-level data isolation, parameterized queries, input validation, and authentication out of the box.
+
+## Security by Design {#secure-by-design}
+
+The framework architecture prevents common vulnerabilities when you use the standard patterns:
+
+| Vulnerability   | Framework Protection                                            |
+| --------------- | --------------------------------------------------------------- |
+| SQL injection   | Parameterized queries in `db-query`/`db-exec` and Drizzle ORM   |
+| XSS             | React auto-escapes JSX; TipTap sanitizes rich text              |
+| Data leaks      | SQL-level scoping via temporary views (`owner_email`, `org_id`) |
+| Auth bypass     | Auth guard auto-protects all `defineAction` endpoints           |
+| Input injection | Zod schema validation in `defineAction`                         |
+| CSRF            | `SameSite=lax` + `httpOnly` cookies                             |
+| Secret exposure | `.env` files gitignored; OAuth tokens in dedicated store        |
+
+## Input Validation {#input-validation}
+
+Use `defineAction` with a Zod `schema:` for every action. The framework validates input automatically before your code runs:
+
+```typescript
+import { z } from "zod";
+import { defineAction } from "@agent-native/core";
+
+export default defineAction({
+  description: "Create a note",
+  schema: z.object({
+    title: z.string().min(1).max(200).describe("Note title"),
+    content: z.string().optional().describe("Note body"),
+  }),
+  run: async (args) => {
+    // args is guaranteed valid — invalid input never reaches here
+  },
+});
+```
+
+Invalid input returns clear error messages (400 for HTTP, structured error for agent calls). The legacy `parameters:` format provides no runtime validation.
+
+## SQL Injection Prevention {#sql-injection}
+
+The framework's `db-query` and `db-exec` tools use parameterized queries. User input is passed as arguments, never interpolated into the SQL string:
+
+```typescript
+// SAFE — parameterized query (framework default)
+await exec({ sql: "INSERT INTO notes (title) VALUES (?)", args: [title] });
+
+// SAFE — Drizzle ORM (always generates parameterized queries)
+await db.insert(notes).values({ title, ownerEmail: email });
+
+// DANGEROUS — string concatenation (never do this)
+await exec(`INSERT INTO notes (title) VALUES ('${title}')`);
+```
+
+## XSS Prevention {#xss}
+
+React auto-escapes all JSX expressions. Additional guidelines:
+
+- Never use `dangerouslySetInnerHTML` with user-controlled content
+- Never use `innerHTML`, `eval()`, or `document.write()`
+- For rich text editing, use TipTap (framework dependency) — it sanitizes through its schema
+- For rendering markdown, use `react-markdown` — it converts to React elements safely
+
+## Data Scoping {#data-scoping}
+
+In production, the framework automatically restricts agent SQL queries to the current user's data. This is enforced at the SQL level — agents cannot bypass it.
+
+### Per-User Scoping (`owner_email`)
+
+Every table with user-specific data **must** have an `owner_email` text column:
+
+```typescript
+import { table, text, integer } from "@agent-native/core/db/schema";
+
+export const notes = table("notes", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  content: text("content"),
+  owner_email: text("owner_email").notNull(), // REQUIRED
+});
+```
+
+The framework creates temporary SQL views that filter queries automatically:
+
+```sql
+CREATE TEMPORARY VIEW "notes" AS
+  SELECT * FROM main."notes"
+  WHERE "owner_email" = 'alice@example.com';
+```
+
+INSERT statements get `owner_email` auto-injected when the column isn't already present.
+
+### Per-Org Scoping (`org_id`)
+
+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 = ?`.
+
+### Validation
+
+```bash
+pnpm action db-check-scoping           # Check all tables have owner_email
+pnpm action db-check-scoping --require-org  # Also require org_id
+```
+
+## Secrets Management {#secrets}
+
+| Secret type                     | Where to store                               |
+| ------------------------------- | -------------------------------------------- |
+| API keys (OpenAI, Stripe, etc.) | `.env` file (gitignored, server-side only)   |
+| OAuth tokens (Google, GitHub)   | `oauth_tokens` store via `saveOAuthTokens()` |
+| Session tokens                  | Automatic (Better Auth handles this)         |
+
+Never store secrets in `settings`, `application_state`, source code, or action responses.
+
+## Authentication {#auth}
+
+Auth is automatic. See the [Authentication](/docs/authentication) docs for the full setup.
+
+**Key points for security:**
+
+- `defineAction` endpoints are auto-protected by the auth guard
+- Custom `/api/` routes must call `getSession(event)` and check the result
+- State-changing operations should use POST (the default for actions)
+- `SameSite=lax` + `httpOnly` cookies prevent most CSRF attacks
+
+## A2A Identity Verification {#a2a-identity}
+
+When apps call each other via the A2A protocol, they verify identity using JWT tokens signed with a shared secret:
+
+```bash
+A2A_SECRET=your-shared-secret-at-least-32-chars
+```
+
+1. App A signs a JWT containing `sub: "steve@example.com"`
+2. App B verifies the JWT signature with the same secret
+3. App B sets `AGENT_USER_EMAIL` from the verified `sub` claim
+4. Data scoping applies — App B only shows Steve's data
+
+Without `A2A_SECRET`, A2A calls are unauthenticated (fine for local dev, not production).
+
+## Production Checklist {#production-checklist}
+
+- [ ] Every user-facing table has `owner_email`
+- [ ] Multi-user tables also have `org_id`
+- [ ] All actions use `defineAction` with Zod `schema:`
+- [ ] No `dangerouslySetInnerHTML` with user content
+- [ ] No string-concatenated SQL
+- [ ] API keys are in `.env` only (not in source code or settings)
+- [ ] `BETTER_AUTH_SECRET` is set to a random 32+ character string
+- [ ] `A2A_SECRET` is set on all apps that call each other
+- [ ] `AUTH_MODE` is **not** set to `local`
+- [ ] `pnpm action db-check-scoping` passes
+- [ ] Tested with two user accounts to verify data isolation