@agent-native/core 0.114.16 → 0.115.1

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

@@ -0,0 +1,145 @@
+---
+name: customizing-agent-native
+description: >-
+  How to configure, compose, or eject Agent Native features into app-owned
+  code. Use when overriding shared components or integrations, customizing a
+  template, adding UI to chat or headless apps, or inspecting package source.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Customizing Agent Native
+
+## Rule
+
+Start with the public component and its props, slots, callbacks, and stable
+class names. If those seams are not enough, use the eject CLI to transfer the
+smallest supported feature into the app and make that copy app-owned. Never
+edit `node_modules`, deep-import a private source file at runtime, or patch an
+`@agent-native/*` package.
+
+Use this order:
+
+1. Configure the public component.
+2. Compose public primitives behind a local app component.
+3. Eject the smallest feature into app-owned source.
+4. Propose a new Toolkit seam when the same override is useful in two apps.
+
+Ejection is for intentional product customization, not for hiding an upgrade
+failure or replacing Core runtime behavior.
+
+## Eject A Feature
+
+Discover and inspect the ejection units published by installed first-party
+packages before changing source:
+
+```bash
+agent-native eject --list
+agent-native eject inspect <unit>
+agent-native eject <unit> --app <app>
+agent-native eject <unit> --app <app> --apply
+```
+
+The command is dry-run by default. It prints the file closure, consumer import
+rewrites, protected package contracts, and verification commands before
+writing. `--apply` copies the package-version-matched source into the app and
+rewrites only imports covered by the unit manifest.
+
+Every first-party public ejection unit must have a complete manifest. If one is
+missing, treat that as a framework coverage bug instead of inventing a copy
+recipe. For an unknown third-party package, use the emitted add-style blueprint
+as a starting point. Protected runtime behavior is never copied; follow the
+reported configuration, adapter, or extension seam instead.
+
+Applied ejections are recorded in the committed
+`agent-native.ejections.json`, including package version, manifest digest,
+target hashes, and import rewrites. Use the recorded state to review drift or
+undo an unchanged ejection:
+
+```bash
+agent-native eject diff <unit> --app <app>
+agent-native eject restore <unit> --app <app>
+agent-native eject restore <unit> --app <app> --apply
+```
+
+Restore is hash-gated. It refuses to remove locally edited files or reverse
+changed imports and prints their diff instead. Keep an edited ejection as
+app-owned code, or reconcile those edits before restoring it.
+
+## Find The Installed Implementation
+
+Use the source that matches the installed package version:
+
+```bash
+pnpm action docs-search --query "<component or feature>"
+pnpm action source-search --query "<component or symbol>"
+rg -n "<component or symbol>" node_modules/@agent-native/toolkit/src
+rg -n "<component or symbol>" node_modules/@agent-native/core/corpus
+```
+
+- Toolkit publishes readable TypeScript under
+  `node_modules/@agent-native/toolkit/src/` for selective UI adoption.
+- Core and first-party template source lives under
+  `node_modules/@agent-native/core/corpus/core/` and
+  `node_modules/@agent-native/core/corpus/templates/`.
+- Treat those trees as read-only references. Prefer `agent-native eject` so the
+  package manifest selects the complete source closure and rewrites imports.
+  Manual inspection is still useful for deciding whether to configure,
+  compose, eject, or propose a shared seam.
+
+Do not manually guess at sibling dependencies. The ejection manifest owns the
+required file closure and keeps protected contracts on public package imports.
+
+## Preserve The Agent-Native Contract
+
+UI ownership may change; product contracts should not:
+
+- Keep app operations in `defineAction` actions and call them through
+  `useActionQuery`, `useActionMutation`, or another named client helper.
+- Keep navigation, selection, and focused-object state visible through the
+  existing application-state keys.
+- Keep AI work in the shared agent chat instead of adding direct LLM calls.
+- Keep auth, access checks, persistence, chat transport, and agent execution in
+  Core. Do not copy those runtimes into the app.
+- Keep local adapters narrow so package upgrades still improve every surface
+  the app has not intentionally taken ownership of.
+
+## App Shapes
+
+- **Template app:** begin with its existing local adapters and domain UI. Use
+  Toolkit for repeated workspace UI; eject only the unit being customized.
+- **Chat app:** keep `AgentChatSurface`, thread state, and chat transport in
+  Core. Compose or eject Toolkit presentation such as chat-history UI around it.
+- **Headless app:** stay action-first while no UI is needed. When adding a UI,
+  use the Chat template as the on-ramp or add Toolkit components without
+  replacing the existing actions.
+- **Workspace:** put one-app overrides in that app. Promote a local component
+  to `packages/shared` only when multiple workspace apps use it.
+
+## After Ejecting
+
+- Commit `agent-native.ejections.json` with the app-owned files and rewrites.
+- Remove unused dependencies and imports from the ejected files.
+- Keep visible text in the app's localization catalogs.
+- Run the manifest verification commands plus the app's formatter, typecheck,
+  and focused tests.
+- Re-check the installed source during future package upgrades; the app-owned
+  ejection does not receive upstream fixes automatically. Use `eject diff` to
+  distinguish recorded output from subsequent local edits.
+
+## Don't
+
+- Don't edit or import from `node_modules/@agent-native/*/src` at runtime.
+- Don't add `pnpm.overrides`, patches, or resolutions for Agent Native packages.
+- Don't copy Core auth, DB, action, agent-loop, or transport internals.
+- Don't manually copy a first-party unit with a missing recipe; fix its manifest.
+- Don't eject a full package when a prop, slot, wrapper, or smaller unit works.
+
+## Related Skills
+
+- `agent-native-docs` — version-matched docs and source lookup
+- `agent-native-toolkit` — shared-vs-app-owned architecture boundary
+- `self-modifying-code` — safe app source edits
+- `upgrade-agent-native` — supported package upgrade path
+- `adding-a-feature` — UI/action/instructions/application-state parity

package/corpus/templates/crm/.agents/skills/feature-flags/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: feature-flags
+description: >-
+  Declare, evaluate, manage, and remove framework feature flags. Use when
+  shipping a capability gradually, targeting users or organizations, or
+  replacing a compile-time rollout switch with a production-safe runtime flag.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Feature Flags
+
+A feature flag is a boolean declared in app code, evaluated locally by Core,
+and managed from the Analytics fleet control plane. Code owns whether a flag
+exists. Runtime settings own only its rollout state.
+
+Flags let an app deploy dormant code and turn it on in the real environment
+without another deployment. They are not experiments: do not add variants,
+hypotheses, conversion metrics, exposure tracking, or lifecycle states.
+
+## When to use one
+
+Use a flag for a reversible rollout of a user-facing capability whose dormant
+code is safe to deploy. Flags are useful for production dogfooding, exact-user
+or organization pilots, and deterministic percentage rollouts.
+
+Do not use a flag for authentication, authorization, secrets, audit enablement,
+SSR cache behavior, or another security boundary. Client hiding is presentation
+only; every guarded server action must evaluate the same registered flag.
+
+## Agent workflow
+
+### 1. Declare
+
+Keep definitions in a shared TypeScript module so server and client code use the
+same stable key. Flags are boolean and default-off.
+
+```ts
+import { defineFeatureFlag } from "@agent-native/core/feature-flags/registry";
+
+export const FULL_APP_BUILDING = defineFeatureFlag({
+  key: "full-app-building",
+  displayName: "Full app building",
+  description: "Create and edit Fusion-backed applications.",
+});
+```
+
+Keys are immutable, never reused, and contain only letters, numbers, dots,
+underscores, or hyphens. Prefer a concise app-owned name. Do not create flag
+definitions or rollout rows from Analytics.
+
+### 2. Register
+
+Register app definitions from a Nitro plugin before actions are discovered.
+Do not add app-specific flags to a Core registry.
+
+```ts
+import { createFeatureFlagsPlugin } from "@agent-native/core/server";
+
+import { FULL_APP_BUILDING } from "../../shared/feature-flags.js";
+
+export default createFeatureFlagsPlugin({ flags: [FULL_APP_BUILDING] });
+```
+
+### 3. Guard server and client
+
+The server action is the enforcement boundary:
+
+```ts
+import { isFeatureFlagEnabled } from "@agent-native/core/feature-flags";
+
+run: async (args, ctx) => {
+  if (!(await isFeatureFlagEnabled(FULL_APP_BUILDING, ctx))) {
+    throw new Error("Full app building is not enabled for this account.");
+  }
+  // guarded operation
+}
+```
+
+Use the client hook only to hide or reveal hydrated UI:
+
+```tsx
+import { useFeatureFlag } from "@agent-native/core/client/feature-flags";
+
+const enabled = useFeatureFlag(FULL_APP_BUILDING.key);
+return enabled ? <FullAppOption /> : null;
+```
+
+The client hook intentionally returns false while loading or for an unknown
+flag. Never replace that fail-closed behavior with app-local bucketing or a
+compile-time fallback. Never evaluate personalized flags in the public SSR
+shell; it is shared and cached for every visitor.
+
+### 4. Verify and roll out
+
+1. Verify the off path before changing rollout state.
+2. Confirm the registered flag appears in **Analytics → Feature flags** for the
+   app and is Off by default.
+3. Use **Enable for me** for initial production dogfood.
+4. Expand to exact emails, organization IDs, or a percentage only from
+   Analytics.
+5. Confirm the client presentation and authoritative server action agree.
+
+## Management contract
+
+Core mounts three actions in registered apps:
+
+| Action | Purpose |
+| --- | --- |
+| `get-feature-flags` | Return the current caller's evaluated boolean values. |
+| `list-feature-flags` | Return definitions and rollout metadata to an authorized operator. |
+| `set-feature-flag` | Atomically turn a flag off, enable it for the operator, or replace targeting rules. |
+
+Analytics calls the app-local operator actions through narrowly scoped A2A
+delegation. Tokens require an exact audience, organization, scope, operator
+role, and audit correlation id. Management is permission-checked and audited
+by the target app. Never manage flags through generic settings routes, raw SQL,
+or per-app toggle UIs.
+
+## Rollout semantics
+
+The operator modes are **Off**, **Targeted**, and **Everyone**. Core stores them
+as `off`, `rules`, and `on`.
+
+Targeted rules combine exact normalized emails, exact organization IDs, and a
+percentage with OR semantics. Exact matches are checked first. Percentage
+buckets use Core's stable hash of the flag key and authenticated user identity;
+anonymous callers fail closed. Raising a percentage preserves the users already
+included at a lower percentage. Do not implement bucketing in app code.
+
+Unknown definitions, missing state, malformed state, storage errors, and
+evaluation errors all return the code default (`false` in v1). Explicit Off
+wins over every target; Everyone enables every authenticated caller.
+
+## Remove a flag
+
+After a rollout is permanent:
+
+1. Replace guarded branches with the chosen behavior.
+2. Delete the server and client gates.
+3. Delete the definition and registration entry.
+4. Verify the flag disappears from the Analytics fleet.
+5. Remove stale tests and rollout instructions.
+
+A permanent flag is just an if statement with a pension plan.
+
+## Verification checklist
+
+- Unknown and unregistered keys evaluate false.
+- UI hiding and server enforcement use the same registered key.
+- Exact-user, organization, deterministic percentage, Everyone, and Off paths
+  have focused tests.
+- Increasing a percentage is monotonic; anonymous percentage evaluation is off.
+- Unauthorized callers cannot list targeting details or mutate flags.
+- Mutations are atomic, read back stored state, emit refresh, and appear in the
+  audit log with the flag key.
+- Analytics represents ready, no-definition, unsupported, forbidden, legacy,
+  and unreachable directory apps honestly.
+- Future agents can find this skill from root `AGENTS.md`, and
+  `pnpm guard:workspace-skills` passes after syncing generated copies.
+
+## Related skills
+
+- **adding-a-feature** — preserve UI/action/instruction/application-state parity
+- **actions** — define and call guarded app operations
+- **audit-log** — inspect automatic action mutation history
+- **reliable-mutations** — make rollout changes atomic and provable
+- **security** — keep security controls out of feature flags

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

@@ -0,0 +1,100 @@
+---
+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. **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.
+
+4. **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,120 @@
+# CRM — Agent Guide
+
+CRM is a standalone Native SQL CRM and a HubSpot/Salesforce Connected/Hybrid
+companion. Actions are the shared contract for UI, agent chat, HTTP, MCP, A2A,
+and CLI. Read `shared/crm-contract.ts` before changing CRM semantics; it is the
+source of truth for vocabulary, field policies, provenance, provider identity,
+and write policy.
+
+## Hard boundaries
+
+- Native SQL, HubSpot, and Salesforce are the initial modes. Native SQL is
+  local-authoritative, requires no external connection, and stays portable
+  across SQLite, Postgres, and D1.
+- Workspace Connections own provider credentials. Never ask for, store, log,
+  or expose provider tokens.
+- The local mirror is scoped and thin. Unknown fields are remote-only;
+  sensitive fields default to redacted; only allow-listed fields are mirrored.
+- Never store raw provider payloads, transcripts, audio, video, screenshots,
+  base64, or file bodies in SQL. Evidence is a URL/id plus bounded quote,
+  timestamp, speaker, and source metadata.
+- Do not merge identities from email/domain matches. Preserve the provider
+  identity tuple and directional relationships.
+
+## Actions
+
+| Action                                                                                 | Purpose                                                                                                 |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `get-crm-overview`                                                                     | Read the scoped CRM summary and connection/mirror health.                                               |
+| `configure-native-crm`                                                                 | Start a local-authoritative Native SQL CRM without a provider connection.                               |
+| `configure-crm-connection`                                                             | Register an authorized HubSpot or Salesforce workspace Connection for the companion mirror.             |
+| `list-crm-records`                                                                     | List a bounded set of CRM records using declared filters.                                               |
+| `get-crm-record`                                                                       | Read one record and its permitted scoped detail.                                                        |
+| `sync-crm`                                                                             | Refresh a declared mirror cohort; never treat it as an export-all operation.                            |
+| `list-crm-saved-views` / `save-crm-saved-view`                                         | List or save scoped CRM views.                                                                          |
+| `install-crm-pipeline-dashboard`                                                       | Idempotently verify and install the CRM-owned Pipeline dashboard and data program.                      |
+| `get-crm-pipeline-data`                                                                | Read bounded, access-scoped opportunity totals by stage for the dashboard program.                      |
+| `get-crm-dashboard` / `list-crm-dashboards` / `save-crm-dashboard`                     | Read, list, or revision-write access-scoped Pipeline dashboards.                                        |
+| `list-crm-dashboard-revisions` / `restore-crm-dashboard-revision`                      | Inspect and restore a dashboard's bounded revision history.                                             |
+| `list-crm-tasks` / `manage-crm-task`                                                   | Read and manage CRM follow-up tasks.                                                                    |
+| `update-crm-record`                                                                    | Submit a typed, access-checked, revision-aware record mutation.                                         |
+| `list-crm-proposals` / `apply-crm-proposals`                                           | Review provider proposals and record the upstream handoff.                                              |
+| `attach-call-evidence`                                                                 | Attach a bounded call evidence reference; never attach a transcript or media.                           |
+| `get-crm-automation-recipe`                                                            | Return the default-off, record-selected Clips call-evidence review recipe.                              |
+| `create-crm-signal-tracker` / `list-crm-signal-trackers` / `manage-crm-signal-tracker` | Create, inspect, enable, disable, or delete access-scoped keyword and delegated-agent moment detectors. |
+| `run-crm-signal-trackers` / `list-crm-signal-hits`                                     | Find deterministic hits and prepare bounded smart/summary agent work.                                   |
+| `record-crm-smart-signal` / `record-crm-call-insight`                                  | Persist only evidence-grounded delegated results as reviewable signals.                                 |
+| `review-crm-signal`                                                                    | Confirm or dismiss one grounded CRM signal.                                                             |
+| `view-screen`                                                                          | Read current navigation, selection, and visible CRM context.                                            |
+| `navigate`                                                                             | Move the UI to overview, records, tasks, proposals, or settings.                                        |
+| `provider-api-catalog` / `provider-api-docs` / `provider-api-request`                  | Discover and make authorized, read-only exact provider API requests.                                    |
+| `query-staged-dataset`                                                                 | Reduce staged, paginated provider results for broad analyses.                                           |
+| data program, automation, extension surfaces                                           | Use shared framework capabilities under their scoped access and data limits.                            |
+
+## Agent behavior
+
+- Call `view-screen` before acting on “this record,” “these accounts,” the
+  selected row, or a visible saved view. For standalone read requests, call the
+  focused CRM action directly.
+- Navigate before presenting a requested CRM view. Keep visible context aligned
+  with the action result.
+- For a standalone CRM, use `configure-native-crm`; then create and update
+  local-authoritative records through the normal CRM actions. Do not call
+  `sync-crm`, provider API actions, or require a workspace Connection for
+  Native SQL.
+- Use first-class actions for ordinary workflows. For an exact HubSpot or Salesforce API
+  request that actions cannot express, discover it with provider API actions,
+  fetch it with explicit pagination, then stage/reduce large results. Report
+  source, scope, filters, counts, pagination, and uncertainty.
+- Agent provider changes are normally proposals. Changes involving ownership,
+  amounts, stage, deletion, bulk scope, or external side effects require an
+  exact preview and approval. This release does not complete provider writes:
+  review the proposal, direct the user to make the change in HubSpot or
+  Salesforce, and never claim the upstream change succeeded.
+- A stored automation may execute only the `crm-sales-routine-local-v1` pack:
+  one routine, compensatable local update to one record. The trigger dispatcher,
+  not action input, supplies that policy context. Provider updates remain
+  proposals; ownership, amount, stage, deletion, bulk, and external effects
+  stay approval-gated or denied.
+- Use `run-crm-signal-trackers` for attached Clips evidence. Keyword detectors
+  run locally; smart detectors and call summaries are delegated through agent
+  chat. Record only exact, bounded evidence citations through the signal record
+  actions. Never pass or reconstruct a transcript.
+- Manage a tracker only with editor access. Enabling, disabling, and deleting a
+  tracker are local CRM configuration changes: they never invoke a model or
+  mutate a connected provider. Use `navigate` with
+  `{ view: "settings", settingsSection: "intelligence" }` to open its settings tab.
+- The Clips review recipe is default-off and always scoped to one explicit CRM
+  record. It may subscribe to `clip.created` only after the user explicitly
+  approves the exact A2A activation call. The trigger belongs to Clips, where
+  `clip.created` is registered. It must ignore the event URL, call
+  `prepare-crm-call-evidence` with the event clip ID, and send only that bounded
+  durable HTTPS `/r/<id>` reference back to `attach-call-evidence` for the
+  selected record. It rejects media, tokens, transcripts, inferred records,
+  tasks, field/provider writes, and broader scopes. Use
+  `get-crm-automation-recipe` before configuring this flow.
+- Use `install-crm-pipeline-dashboard` to set up the Pipeline view. It owns one
+  per-user data program that calls `get-crm-pipeline-data`; do not replace it
+  with a provider-specific action or embed raw rows in dashboard config. Use
+  `save-crm-dashboard` with `expectedUpdatedAt` for dashboard edits, and
+  `restore-crm-dashboard-revision` to roll back a saved revision.
+
+## Four-area change guide
+
+When changing a provider workflow, keep UI, actions, agent instructions, and
+application state aligned. The setup route records the selected native mode or
+connection; `configure-native-crm`, `configure-crm-connection`, and `sync-crm`
+are the shared UI/agent operations; signal selection stores record/evidence IDs
+only; `view-screen` and `navigate` expose the selected CRM context. Do not introduce provider-specific API routes, browser
+credential inputs, or unscoped state.
+
+## Implementation
+
+Before building common workspace or agent UI, read `agent-native-toolkit`; use
+`customizing-agent-native` when composing or ejecting shared surfaces.
+
+Use `defineAction` and action hooks rather than duplicate `/api` CRUD routes.
+Use shared Toolkit surfaces for connections, settings, navigation, sharing,
+automations, and extensions before adding app-local equivalents. Keep SQL
+schema changes additive and preserve access-scope checks independently from
+provider permissions.

package/corpus/templates/crm/CHANGELOG.md

@@ -0,0 +1 @@
+# CRM changelog

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.