@agent-native/core 0.123.0 → 0.123.2

package/corpus/templates/crm/.agents/skills/storing-data/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: storing-data
+description: >-
+  How to store application data in agent-native apps. All data lives in SQL.
+  Use when adding data models, deciding where to store data, or reading/writing
+  application data.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Storing Data — SQL is the Source of Truth
+
+## Rule
+
+All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. SQL stores structured records, metadata, references, and searchable text — not large raw file payloads. Do not store durable app data in the filesystem unless the app is explicitly running a Local File Mode artifact flow described below.
+
+Large binary or file-like payloads (images, video/audio, PDFs, ZIPs, screenshots, session replay chunks, thumbnails, generated assets, `data:` URLs, and base64 file bodies) must go through configured file/blob storage such as `uploadFile()` or `putPrivateBlob()`. Persist only the returned URL, asset id, or opaque blob handle in SQL. If storage is unavailable in hosted or persistent-database mode, fail closed with setup guidance instead of falling back to base64 in `application_state`, `settings`, `resources`, or app tables. Local SQLite-only dev fallbacks may exist for tiny assets, but they must be capped, documented as dev-only, and kept off hot list/read paths.
+
+**Local File Mode exception:** some artifact apps (Content, Plans, Slides, Dashboards, Designs, etc.) can intentionally use repo files as the source of truth for the artifact itself. This must be explicit via `agent-native.json`, `AGENT_NATIVE_MODE=local-files`, or an app-owned local-file action helper. In that mode, the UI and agent still go through app actions, but those actions read/write scoped files through `@agent-native/core/local-artifacts` instead of SQL rows. App state, auth, settings, credentials, collaboration metadata, and hosted database mode remain SQL. File-to-database or file-to-provider synchronization is an explicit sync step, not an implicit side effect of editing.
+
+When you add a data model, a list, or a read path, also follow the `performance` skill: project only the columns a list renders, index the columns hot queries filter/sort on, and avoid query waterfalls — so apps stay fast as data grows.
+
+## How It Works
+
+Agent-native apps use Drizzle ORM over the configured SQL backend. Local development works out of the box with a SQLite file at `data/app.db`; production and shared preview deploys need a persistent `DATABASE_URL` because container/serverless filesystems can reset. The code should behave the same across backends, but the local SQLite file is not durable once deployed.
+
+For app code, use Drizzle's schema/query DSL by default. Raw SQL is an escape hatch for additive migrations, health checks, or one-off maintenance, not the normal way to build features.
+
+### Naming migrations
+
+When you add an entry to a `runMigrations([...])` list (`@agent-native/core/db`), always give it a unique `name:` slug (e.g. `name: "analytics-alert-rules-table"`) alongside its `version`. Never renumber or reuse version numbers on existing entries.
+
+Why: version numbers alone are not a safe identity. Two branches that each independently extend the same migration list can ship different DDL under the same version numbers — whichever branch deploys first "claims" those version numbers in the bookkeeping table, and the other branch's DDL is silently treated as already applied even though it never ran. This exact collision took down analytics: parallel branches both extended their migration list through v75-v83 with different DDL, so `analytics_alert_rules`, `analytics_alert_incidents`, and `session_recordings.network_error_count` never made it to production despite the bookkeeping table showing every version as applied. A `name:` slug is tracked independently of version numbers, so it applies exactly once per database regardless of what any other branch already recorded.
+
+Existing unnamed migrations don't need to be renamed retroactively (the two gating strategies coexist), but any new entry should always carry a name.
+
+### Core SQL Stores (auto-created, available in all templates)
+
+| Store               | Purpose                                              | Access                                     |
+| ------------------- | ---------------------------------------------------- | ------------------------------------------ |
+| `application_state` | Ephemeral UI state (compose windows, navigation)     | `readAppState()` / `writeAppState()`       |
+| `settings`          | Persistent KV config (preferences, app settings)     | `getSetting()` / `putSetting()`            |
+| `oauth_tokens`      | OAuth credentials                                    | `@agent-native/core/oauth-tokens`          |
+| `sessions`          | Auth sessions                                        | `@agent-native/core/server`               |
+
+### Domain Data (per-template)
+
+Define schema with the framework Drizzle helpers in `server/db/schema.ts`. Get a database instance with `const db = getDb()` from `server/db/index.ts`. All queries are async.
+
+```ts
+import { eq } from "drizzle-orm";
+import { table, text, integer, now } from "@agent-native/core/db/schema";
+
+export const tasks = table("tasks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  completed: integer("completed", { mode: "boolean" })
+    .notNull()
+    .default(false),
+  createdAt: text("created_at").notNull().default(now()),
+});
+
+const rows = await db.select().from(tasks).where(eq(tasks.id, taskId));
+```
+
+Never import `sqliteTable` / `pgTable` or column helpers from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates. Use `@agent-native/core/db/schema` so the same schema can run against SQLite, Postgres, libSQL/Turso, D1, and other supported backends.
+
+| Template     | Tables                                        |
+| ------------ | --------------------------------------------- |
+| **Mail**     | emails, labels (+ Gmail API when connected)   |
+| **Calendar** | events, bookings                              |
+| **Forms**    | forms, responses                              |
+| **Content**  | documents                                     |
+| **Slides**   | decks (JSON stored in SQL)                    |
+| **Videos**   | compositions in registry + localStorage       |
+
+### Agent Access
+
+The agent uses app-specific actions to read/write the database. Core DB scripts are for inspection and maintenance, not for implementing normal product behavior:
+
+- `pnpm action db-schema` — Show all tables, columns, types
+- `pnpm action db-query --sql "SELECT * FROM forms"` — Run SELECT queries
+- `pnpm action db-exec --sql "UPDATE ..."` — Last-resort ad-hoc maintenance for short columns, multi-column writes, or computed updates when no domain action exists. For several related writes, prefer `--statements '[{"sql":"...","args":[...]}]'` so they run sequentially in one transaction. Schema changes are blocked; use reviewed additive migrations/startup code instead.
+- `pnpm action db-patch --table <t> --column <c> --where "<clause>" --find "<old>" --replace "<new>"` — **Surgical search/replace on a large text column.** Sends the diff instead of re-transmitting the whole value, so it's dramatically more token-efficient than `db-exec UPDATE` when editing multi-kilobyte documents, slide HTML, dashboard/form JSON, etc. Targets exactly one row per call — narrow `--where` by primary key. Supports `--edits '[{find,replace},...]'` for batch edits and `--all` to replace every occurrence.
+- App-specific actions for domain operations — **always prefer these over raw SQL when one exists.** They encode business rules, power the client action hooks, and for editor-backed tables (documents, slides) also push live Yjs updates to open collaborative editors. `db-patch` is the generic fallback for tables without a dedicated edit action.
+
+**For one-off maintenance, how to choose between `db-exec UPDATE` and `db-patch`:**
+
+| Scenario                                                       | Use          |
+| -------------------------------------------------------------- | ------------ |
+| `SET status = 'published'` on one row                          | `db-exec`    |
+| `SET calories = calories + 50`                                 | `db-exec`    |
+| Updating several columns at once                               | `db-exec`    |
+| Inserting/updating several rows as one logical operation        | `db-exec --statements` |
+| Fixing a typo in a 50KB markdown document's `content` column   | `db-patch`   |
+| Changing a single key in a dashboard's JSON blob               | `db-patch`   |
+| Tweaking one paragraph of slide HTML stored in `decks.data`    | `db-patch`   |
+| Any edit where you'd otherwise re-send thousands of characters | `db-patch`   |
+
+All of these honor the per-user / per-org data scoping — you can't read or write rows outside the current user's data, regardless of which tool you choose.
+
+### Frontend Access
+
+The frontend calls actions using React Query hooks from the client API. The framework owns the HTTP transport behind these hooks, so components should not call action routes with raw `fetch`.
+
+```ts
+import { useActionQuery, useActionMutation } from "@agent-native/core/client/hooks";
+
+// Read data
+const { data } = useActionQuery("list-meals", { date: "2025-01-01" });
+
+// Write data
+const { mutate } = useActionMutation("log-meal");
+```
+
+Actions are the **preferred way** for the frontend to access data. You rarely need custom `/api/` routes — only for file uploads, streaming, webhooks, or OAuth callbacks.
+
+### Production / Cloud Deployment
+
+Local SQLite works out of the box for development. To deploy to production or any environment where data must survive restarts:
+
+1. Set `DATABASE_URL` to a persistent SQL database.
+2. Set `DATABASE_AUTH_TOKEN` only when the provider requires a separate token, such as Turso/libSQL.
+3. No code changes should be needed when the schema and queries stay portable.
+
+Turso is one valid option, not the required option. Common choices include Neon or Supabase Postgres, Turso/libSQL, plain Postgres, durable SQLite, Cloudflare D1 bindings, and managed platform SQL environments when available.
+
+### Real-time Sync
+
+Polling streams database changes to the UI. When the agent writes to the database via scripts, the UI updates automatically via `useDbSync()` which invalidates React Query caches.
+
+## Do
+
+- Use Drizzle ORM for structured domain data (forms, bookings, documents)
+- Use Drizzle query builder methods (`select`, `insert`, `update`, `delete`) and portable operators from `drizzle-orm` (`eq`, `and`, `or`, `inArray`, `desc`, etc.) for app reads/writes
+- Use framework schema helpers from `@agent-native/core/db/schema`, not dialect-specific Drizzle imports
+- Use the `settings` store for app configuration and user preferences
+- Use `application-state` for ephemeral UI state that the agent and UI share
+- Use `oauth-tokens` for OAuth credentials
+- Use `uploadFile()` or `putPrivateBlob()` for large files/blob data and store only URLs, ids, or handles in SQL
+- Use core DB scripts (`db-schema`, `db-query`, `db-exec`, `db-patch`) for ad-hoc database operations
+- Use `db-exec --statements` instead of several separate `db-exec` calls for related writes; it is faster and rolls back the whole batch if one statement fails
+- Reach for `db-patch` instead of `db-exec UPDATE` whenever you're making a small change to a large text/JSON column — it's much cheaper on tokens
+
+## Don't
+
+- Don't store structured app data as JSON files
+- Don't store app state in localStorage, sessionStorage, or cookies (except for UI-only preferences like sidebar width)
+- Don't keep state only in memory (server variables, global stores)
+- Don't use Redis or any external state store for app data
+- Don't store large files, base64 blobs, `data:` URLs, screenshots, videos, audio, PDFs, ZIPs, or session replay chunks directly in SQL rows, `application_state`, `settings`, or `resources`
+- Don't implement product features with raw SQL or `getDbExec()` when Drizzle can express the query
+- Don't write SQLite-only or Postgres-only SQL in app code
+- Don't interpolate user input directly into SQL queries — use Drizzle ORM's query builder
+
+## Security
+
+- **SQL injection** — Use Drizzle ORM's query builder, never raw string interpolation for SQL queries
+- **Validate before writing** — Check data shape before writing, especially for user-submitted data
+
+## Application State and Context Awareness
+
+When storing app-state, include **navigation state** — the agent needs to know what the user is looking at. The `application_state` table holds ephemeral UI state that both the agent and UI share. Key patterns:
+
+- **`navigation` key** — the UI writes current view and selection on every route change. The agent reads this before acting.
+- **`navigate` key** — the agent writes one-shot commands to navigate the UI. The UI processes and deletes them.
+- **Domain-specific keys** (e.g., `compose-{id}`) — bidirectional state for features like email drafts.
+
+When adding a new data model or feature, also consider what navigation and selection state needs to be exposed via application-state. See the **context-awareness** skill for the full pattern.
+
+## Related Skills
+
+- **context-awareness** — How to expose navigation and selection state via application-state
+- **real-time-sync** — Set up polling so the UI updates when the database changes
+- **actions** — Create actions with `defineAction` to query the database
+- **client-methods** — Keep route details behind named client helpers/hooks
+- **self-modifying-code** — The agent can also modify the app's source code

package/corpus/templates/crm/.agents/skills/upgrade-agent-native/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: upgrade-agent-native
+description: >-
+  Bring an older Agent Native app or workspace current. Use when updating
+  @agent-native/core, fixing a broken upgrade, or when tempted to patch or
+  override core/dispatch packages to make an old branch run.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Upgrade Agent Native
+
+## Rule
+
+When an older Agent Native app/branch needs to run on current packages, use
+`agent-native upgrade`. Never "fix" upgrade breakage with
+`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
+edits under `node_modules/@agent-native/*` — especially not against
+`@agent-native/core` or `@agent-native/dispatch`.
+
+## Why
+
+Agents often respond to a failed core bump by inventing framework patches and
+dispatch behavior overrides. That hides the real app-level break, drifts from
+upstream, and makes the next upgrade worse. The supported path is bump →
+install → refresh scaffold skills → verify, then fix **app** code only.
+
+## How
+
+1. **Preview migration codemods first**
+
+   ```bash
+   npx @agent-native/core@latest upgrade --codemods
+   ```
+
+   Codemods are preview-by-default: read the diff before applying it. Do not
+   manually edit imports before running this command; the migration manifest is
+   the source of truth for renamed specifiers and symbols.
+
+2. **Apply the reviewed codemods, then run the upgrade**
+
+   ```bash
+   npx @agent-native/core@latest upgrade --codemods --yes
+   npx @agent-native/core@latest upgrade
+   ```
+
+   Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
+   `agent-native upgrade`.
+
+   What it does:
+
+   - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
+   - Rewrites non-local `@agent-native/*` dependency pins to `latest`
+   - Runs the package manager install
+   - Runs `skills update scaffold --project`
+   - Runs `typecheck` when the project has that script
+
+3. **Pull upstream template changes (optional, separate from the bump)**
+
+   `agent-native upgrade` moves package versions. It never touches files that
+   were copied out of a template at scaffold time, so template fixes and
+   improvements do not arrive with a bump.
+
+   ```bash
+   agent-native template status        # recorded ref vs latest, drift counts
+   agent-native template diff          # what upstream changed, read-only
+   agent-native template sync          # 3-way merge it into the app
+   ```
+
+   `sync` defaults to the ref matching the installed `@agent-native/core`, so
+   run it after `upgrade`. It merges per file against a pristine baseline
+   stored in `refs/agent-native/template-baseline/<app-path>`; files upstream
+   did not touch are left alone, and real collisions get conflict markers.
+   After resolving markers, run `agent-native template accept` — the baseline
+   deliberately does not advance past an unresolved merge.
+
+   Apps scaffolded before provenance existed have no baseline. Create one
+   with `agent-native template baseline` before the first sync.
+
+4. **If upgrade or typecheck fails**
+
+   - Read the concrete error
+   - Fix **app** source, actions, config, or env — not framework packages
+   - Re-run `agent-native upgrade` or `pnpm typecheck`
+   - Stop and ask the user if you cannot fix the app-level error
+
+   Intentional app-level UI customization is a separate workflow. Read
+   `customizing-agent-native` when the product needs to own a selectively
+   copied component; do not use that path to reproduce framework runtime
+   behavior or hide version skew.
+
+5. **Dry-run / partial runs**
+
+   ```bash
+   agent-native upgrade --dry-run
+   agent-native upgrade --skip-verify
+   agent-native upgrade --skip-install   # package.json bumps only
+   agent-native doctor --only migration-manifest
+   ```
+
+   `migration-manifest` has no opt-out. Run it in CI before upgrading to find
+   imports that will break, then use `npx @agent-native/core@latest upgrade --codemods`
+   to preview the supported rewrite.
+
+## Don't
+
+- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
+  `patchedDependencies` for any `@agent-native/*` package
+- Don't edit `node_modules/@agent-native/core` or
+  `node_modules/@agent-native/dispatch`
+- Don't invent local "dispatch behavior" shims to paper over version skew
+- Don't keep iterating with more framework patches after a failed install
+- Don't skip `skills update scaffold --project` after a core bump (the
+  upgrade command does this for you)
+
+## Related Skills
+
+- **self-modifying-code** — Tier 4: framework packages are off limits
+- **agent-native-docs** — version-matched docs after the bump
+- **customizing-agent-native** — intentional app-owned UI copies, not upgrade patches
+- **portability** — keep app code provider-agnostic across upgrades

package/corpus/templates/crm/.env.example

@@ -0,0 +1,5 @@
+# Persistent SQL is required outside local development.
+DATABASE_URL=file:./data/app.db
+
+# Local development or preview only.
+# AUTH_DISABLED=true

package/corpus/templates/crm/AGENTS.md

@@ -0,0 +1,82 @@
+# CRM — Agent Guide
+
+A typed, bitemporal CRM whose grid is the product. It is Native SQL or a scoped
+HubSpot/Salesforce lens; UI and agent share actions.
+
+## Skills
+
+- `crm` — read before CRM work: provider/credential boundaries, lists,
+  enrichment, signals, dashboards, and Clips evidence.
+- Before building common workspace or agent UI, read `agent-native-toolkit`;
+  read `customizing-agent-native` when extending shared framework capabilities.
+
+Source of truth: `shared/crm-contract.ts` (vocabulary, field and write policy),
+`shared/crm-attributes.ts` (types), `server/lib/record-fields.ts` (the only
+sanctioned field-value write).
+
+## Core model
+
+- **Typed attributes**, 17 types: text, number, checkbox, currency, date,
+  timestamp, rating, status, select, record-reference, actor-reference,
+  location, domain, email-address, phone-number, plus system-only interaction
+  and personal-name. Call `list-crm-attributes` first; never guess a slug or
+  type.
+- **Managed options.** A status/select value must already exist as an option;
+  writing an unknown one is a 422, never a silent auto-create.
+- **Values are bitemporal.** A change closes the current row and opens a new
+  one, so stage history *is* the value history. An equal write stores nothing;
+  `historyTracked=false` means in-place updates, not "never changed".
+- **Objects vs lists.** A list is a workflow overlay over one object type, with
+  its own entry attributes. Lists and their entries are local-authoritative on
+  *every* backend, HubSpot and Salesforce included — a pipeline never needs a
+  provider write.
+- **Saved views** hold filter, sort, columns, audience, and a table or board
+  presentation; `"@currentUser"` in a filter resolves to the caller.
+- **Enrichment spends in two phases**: free `verify`, then paid `spend` whose
+  input set is *built from* approved record ids.
+
+## Hard boundaries
+
+- Workspace Connections own provider credentials. Never request, store, log, or
+  return a provider token.
+- The mirror is thin: unknown fields are remote-only, sensitive ones redacted,
+  only allow-listed fields mirrored. Raw payloads, transcripts, media, and
+  base64 never enter SQL — evidence is a URL/id plus a bounded quote.
+- **A provider write is a handoff, not a write.** A provider-owned edit becomes a
+  proposal; `apply-crm-proposals` returns the exact diff and a deep link to
+  finish it upstream. CRM never completes an upstream write and never reports
+  one as applied.
+- Ownership, amount, stage, deletion, bulk scope, and external side effects need
+  an exact preview and approval.
+- Never merge identities from email or domain alone — that is a duplicate
+  *signal*; merging is an explicit reviewed action.
+
+## Actions
+
+|Action|Purpose|
+|---|---|
+|`get-crm-workspace` / `get-crm-overview`|Start here: identity, book of business, tasks, proposals, signals, health.|
+|`view-screen` / `navigate`|Read the visible screen and selection; move the UI.|
+|`configure-native-crm` / `configure-crm-connection` / `list-crm-connections` / `list-workspace-connections` / `sync-crm`|Set up Native SQL or a granted connection; refresh a cohort.|
+|`list-crm-attributes` / `create-crm-attribute` / `update-crm-attribute` / `archive-crm-attribute` / `manage-crm-attribute-option`|Read and author the typed schema and its managed options.|
+|`list-crm-records` / `list-crm-record-values` / `get-crm-record` / `get-crm-record-page` / `create-crm-record` / `update-crm-record`|Grid rows, grid cells, one record, the record page, create, edit.|
+|`list-crm-record-field-history`|How one value changed: value, the window it was current, actor.|
+|`list-crm-lists` / `create-crm-list` / `update-crm-list` / `list-crm-list-entries` / `add-crm-record-to-list` / `update-crm-list-entry` / `remove-crm-list-entry`|Lists and pipelines; a stage move is `update-crm-list-entry`.|
+|`list-crm-saved-views` / `save-crm-saved-view` / `delete-crm-saved-view` / `run-crm-saved-view-program`|Saved table/board views and a view's data program.|
+|`list-crm-proposals` / `apply-crm-proposals`|Review a pending provider change and record the handoff.|
+|`find-crm-duplicates` / `merge-crm-records`|Scored duplicate candidates with reasons; merge into a survivor.|
+|`list-crm-enrichment-slots` / `estimate-crm-enrichment` / `run-crm-enrichment`|Slot credential state; cost estimate; the gated verify/spend run.|
+|`run-crm-attribute-fill`|Manual fill: get the brief, reason, call again with values.|
+|`list-crm-tasks` / `manage-crm-task`|Read and manage follow-up tasks.|
+|`attach-call-evidence` / `create-crm-signal-tracker` / `list-crm-signal-trackers` / `manage-crm-signal-tracker` / `run-crm-signal-trackers` / `list-crm-signal-hits` / `record-crm-smart-signal` / `record-crm-call-insight` / `review-crm-signal` / `get-crm-automation-recipe`|Call evidence and reviewable signals; smart detection goes through agent chat, cited to stored evidence.|
+|`install-crm-pipeline-dashboard` / `get-crm-pipeline-data` / `get-crm-dashboard` / `get-crm-dashboard-panel` / `list-crm-dashboards` / `save-crm-dashboard` / `list-crm-dashboard-revisions` / `restore-crm-dashboard-revision`|Install, read, revision-write, restore the Pipeline dashboard.|
+|`provider-api-catalog` / `provider-api-docs` / `provider-api-request` / `list-staged-datasets` / `query-staged-dataset` / `delete-staged-dataset`|Read-only escape hatch for an exact provider request no action expresses; stage and reduce large results.|
+
+## Agent behavior
+
+- Call `view-screen` when the request names the visible record, selection, or
+  view. `navigate` to a view rather than describing it.
+- Never flatten a failure into a normal-looking value: an unreadable owner,
+  slot, or scope is reported as itself, never as empty. Read a value back before
+  reporting it done.
+- Recover from a recoverable error rather than abandoning the task.

package/corpus/templates/crm/CHANGELOG.md

@@ -0,0 +1,25 @@
+# CRM changelog
+
+## 2026-07-26
+
+### Added
+
+- CRM connects to HubSpot for scoped account intelligence, saved views, follow-up tasks, evidence, and approval-gated write proposals.
+- CRM can prepare a record-scoped, default-off Clips review recipe while keeping media and transcripts in Clips.
+- CRM can now find and review evidence-grounded call signals without storing transcripts or media.
+- Approved sales automations can now update routine local CRM fields while provider changes remain reviewable proposals.
+- CRM can now run as a standalone Native SQL system for accounts, people, opportunities, views, tasks, and cadence without an external provider.
+- Pipeline now gives each CRM user a live, permission-aware view of opportunity value by stage.
+- CRM can now connect to Salesforce alongside HubSpot for scoped account intelligence and follow-up work.
+
+### Improved
+
+- CRM can now manage keyword and smart call-signal trackers from Intelligence settings.
+
+### Fixed
+
+- Pipeline dashboards now install correctly from the CRM action CLI.
+- CRM field validation now explains which fields cannot be edited instead of showing a generic error.
+- Fixed HubSpot contact syncs missing records updated after the sync cursor.
+- Fixed Pipeline dashboard panels so their opportunity data loads reliably.
+- Full-page chat keeps the active conversation when moving to and from the sidebar.

package/corpus/templates/crm/DEVELOPING.md

@@ -0,0 +1,66 @@
+# CRM — Development Guide
+
+CRM is a React Router + Nitro Agent Native template. The UI and agent share the
+same `actions/` contract; normal client reads and writes use action hooks, not
+custom CRUD routes.
+
+## Commands
+
+- `pnpm dev` — run the local app
+- `pnpm typecheck` — run the framework typecheck
+- `pnpm test` — run unit tests
+- `pnpm build` — build the React Router and Nitro app
+
+## Architecture boundaries
+
+- `shared/crm-contract.ts` is the canonical CRM vocabulary and provider-neutral
+  contract.
+- `actions/` contains UI/agent operations. Read actions are GET; mutations use
+  the shared action surface and must preserve access checks and audit behavior.
+- `server/` owns provider adapters, scoped mirror lifecycle, and startup
+  plugins. Use a route only for protocols actions cannot model.
+- `app/` owns the persistent workspace shell and domain views. Keep normal
+  data fetching client-side through `useActionQuery` and `useActionMutation`.
+
+## Data and provider rules
+
+CRM SQL is a thin projection, not a raw HubSpot backup. Only allow-listed
+fields are mirrored; remote-only values are fetched ephemerally and redacted
+values are never fetched or exposed. Store evidence as bounded references and
+quotes only. Raw provider responses, transcripts, media, screenshots, and file
+bodies belong in their source system or approved blob storage, never SQL.
+
+Use workspace Connections for credentials. Never add provider tokens to source,
+fixtures, docs, logs, or `.env.example`. Provider API actions are the escape
+hatch for legitimate unmodeled HubSpot or Salesforce requests; stage large
+results and reduce them via data programs instead of loading an unbounded
+payload into chat.
+
+## Dashboards
+
+CRM owns its dashboard schema, revision history, access policy, data programs,
+and panel resolvers. It composes `@agent-native/toolkit/dashboard` for cards,
+tables, layout, and chart rendering only; never add fetching, provider tokens,
+or direct SQL access to Toolkit components. The Pipeline dashboard is installed
+idempotently through `install-crm-pipeline-dashboard` and reads its bounded
+opportunity data through `get-crm-pipeline-data`.
+
+`@agent-native/core/dashboard-storage` is instantiated per app. Keep CRM's
+dashboard rows and revisions scoped through its store, and use the `program`
+panel source for CRM-owned data programs. Add a provider panel source only when
+the CRM adapter can enforce the workspace connection, field policy, and access
+scope.
+
+## Signals and provider writes
+
+Call evidence is a Clips-owned artifact reference. CRM may store only bounded
+quotes, timestamps, evidence references, confidence, detector/model metadata,
+and review state; it must never store a transcript body, media, or provider
+payload. Keyword trackers run locally. Smart trackers and call summaries must
+delegate to the agent chat, then validate evidence before persisting a signal.
+
+Keep provider mutations proposal-first. `update-crm-record` records a
+revision-aware, idempotent proposal for provider-authoritative fields;
+`apply-crm-proposals` is the only path that can invoke an adapter after
+approval. Delegated policy is narrow, access-scoped, and never bypasses the
+field firewall or destructive/bulk gates.

package/corpus/templates/crm/README.md

@@ -0,0 +1,122 @@
+# CRM
+
+An agent-native CRM built around a typed, bitemporal record grid. It runs as its
+own system of record on plain SQL, or as a scoped, field-policy-aware companion
+to a connected HubSpot or Salesforce workspace — without making you pick one up
+front, and without the connected mode limiting what you can model locally.
+
+Everything the UI does, the agent does, through the same actions and the same
+SQL. `AGENTS.md` is the single source of truth for how the app behaves; the
+`crm` skill is the workflow depth behind it. This README describes the product.
+
+## What it is
+
+- **A spreadsheet grid over typed attributes.** Seventeen attribute types —
+  text, number, checkbox, currency, date, timestamp, rating, status, select,
+  record and actor references, location, domain, email, phone, and two
+  system-owned ones. Filtering, multi-key sorting, and pagination all run in
+  SQL, so a filtered page is the real result set rather than one page narrowed
+  after the fact. Keyboard navigation and TSV copy/paste work the way a
+  spreadsheet does.
+- **Every value keeps its history.** A field write closes the old row and opens
+  a new one with the actor and the time, so a record's stage history _is_ its
+  value history — no separate audit table, no "who changed this?" dead end. A
+  write that changes nothing stores nothing, so a sync does not inflate history.
+- **Lists and pipelines that are always yours.** A list is a workflow overlay
+  over one object type with its own entry attributes. Lists, entries, and entry
+  values are local-authoritative on every backend, HubSpot and Salesforce
+  included — so you can run a pipeline over connected records without needing a
+  single provider write. Time-in-stage falls out of the entry's own history.
+- **Saved views, as tables or boards.** Filter, sort, columns, and audience are
+  saved together; a board view groups by any status attribute. `@currentUser` in
+  a filter resolves per viewer, so one shared view is everyone's own pipeline.
+- **A record page, not a form.** Typed attribute panel with per-value
+  provenance, every list the record belongs to with that entry's own values, its
+  interactions and evidence, and a change history for any single value.
+- **Duplicates you can see the reason for.** Detection scores candidates on
+  email, company domain, shared root domain, and normalized name, and says which
+  one matched. Merge is explicit: you choose the survivor, values the survivor
+  lacks are promoted, both sides' entries/tasks/evidence/relationships move
+  over, and the loser is tombstoned and linked rather than deleted.
+- **Enrichment behind a two-phase spend gate.** A free verify pass gathers
+  evidence; the paid pass runs only over records a human approved, and its input
+  set is built from those approvals rather than filtered down to them. Costs are
+  estimated per line item and quoted before anything is spent, and a failed
+  provider slot is reported as a failure, never as an empty answer.
+- **Call evidence and reviewable signals.** Attach a bounded quote and source
+  reference from a Clips recording; run keyword detectors locally and delegate
+  smart moments and summaries through the agent chat. Every stored signal cites
+  an exact evidence row and waits for a human to confirm or dismiss it.
+- **Command menu and shortcuts.** ⌘K ranks records, lists, and commands
+  together, so getting anywhere is one search away rather than a click path.
+- **Admin in the app.** Settings has Connection, Fields, Lists, Intelligence,
+  and Advanced tabs — the attribute schema and its managed options are edited
+  where the data lives, not in a config file.
+
+## Modes
+
+- **Native SQL** — CRM is the system of record for accounts, people,
+  opportunities, relationships, lists, views, tasks, cadence, and every local
+  field. No provider, no sync job, no token. Portable across SQLite, Postgres,
+  and D1.
+- **Connected (HubSpot / Salesforce)** — the source CRM stays authoritative for
+  its own fields. CRM is a scoped companion for record work, lists, views,
+  tasks, evidence, and analysis. HubSpot maps companies/contacts/deals;
+  Salesforce maps Account/Contact/Opportunity.
+
+Either way, local attributes, lists, and entry values are yours. The `hybrid`
+mode is deprecated: per-attribute authority expresses everything it promised.
+
+### Provider writes are a handoff, and say so
+
+CRM prepares a provider change as a reviewable proposal, shows the exact
+before/after diff, and opens the record in HubSpot or Salesforce to finish it.
+It does not complete upstream writes and never reports one as applied. That is
+the intended flow, not an error — a proposal awaiting completion is presented as
+the next step, not as a failure.
+
+## Guardrails
+
+Provider credentials live only in workspace Connections; CRM never accepts,
+stores, or returns a token. The mirror holds configured cohorts and allow-listed
+fields — unknown fields are remote-only, sensitive fields default to redacted.
+Raw provider payloads, transcripts, media, and base64 bodies never enter SQL;
+evidence is a URL or id plus a bounded quote. Ownership, amount, stage,
+deletion, bulk scope, and external side effects always require an exact preview
+and approval. Email and domain are matching signals, never identity keys.
+
+Full detail: [`AGENTS.md`](AGENTS.md) for the operating rules, the
+[`crm` skill](.agents/skills/crm/SKILL.md) for workflows, and
+[the CRM contract](docs/architecture/crm-contract.md) for identity, field
+policy, access scope, and the write-policy matrix.
+
+## Set up
+
+1. Open **Set up CRM** and choose **Start with Native SQL** to use CRM with no
+   external service.
+2. To connect a provider, authorize HubSpot or Salesforce in shared **Settings →
+   Connections** and grant it to CRM. OAuth and refresh tokens stay in workspace
+   Connections. Salesforce production is the default; for a sandbox use
+   **Authorize the sandbox directly** on Set up CRM, and the chosen login
+   environment is retained for token refresh.
+3. Pick the granted connection and a recent history window. HubSpot may be
+   narrowed to deal pipeline IDs; Salesforce starts with recently updated
+   Accounts, Contacts, and Opportunities.
+4. CRM mirrors that cohort and its allow-listed fields only. Confirm the
+   connection actor's access before relying on a mirrored record.
+
+## Local development
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Set `DATABASE_URL` for persistent deployment storage. Native SQL needs no
+external credentials. Connect providers from the workspace Connections surface;
+never put provider secrets in `.env`.
+
+For live testing, use an already-authorized shared Connection, choose a small
+recent cohort, verify the resulting records and access scope, then exercise a
+proposal without completing the provider change. Record only connection labels,
+counts, and non-sensitive results.

package/corpus/templates/crm/_gitignore

@@ -0,0 +1,12 @@
+node_modules
+dist
+build
+.output
+.netlify
+.react-router
+.generated
+data/*.db
+data/*.db-shm
+data/*.db-wal
+.env
+.env.local