@agent-native/core 0.117.2 → 0.118.1

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

@@ -1,169 +0,0 @@
----
-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

@@ -1,100 +0,0 @@
----
-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

@@ -1,5 +0,0 @@
-# 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

@@ -1,120 +0,0 @@
-# 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

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

package/corpus/templates/crm/DEVELOPING.md

@@ -1,66 +0,0 @@
-# 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

@@ -1,106 +0,0 @@
-# CRM
-
-CRM is an agent-native CRM that runs either as a standalone Native SQL system
-or as a scoped companion for connected HubSpot and Salesforce workspaces. It
-provides fast record work, saved views, tasks, cadence, evidence, reviewable
-call signals, and agent workflows without forcing a provider choice.
-
-Native SQL is local-authoritative and portable across SQLite, Postgres, and D1.
-The connected modes support scoped Connected and Hybrid behavior: HubSpot maps
-companies, contacts, and deals; Salesforce maps Accounts, Contacts, and
-Opportunities.
-
-## Guardrails
-
-- Native SQL requires no external connection or provider credential.
-- Provider credentials are workspace Connections only.
-- The mirror contains configured cohorts and allow-listed fields, not raw
-  provider exports.
-- Sensitive fields default to redacted and unknown fields are remote-only.
-- Evidence stores a bounded quote and source reference, never transcripts or
-  media.
-- Signal detectors produce timestamped evidence citations. Keyword matching is
-  local; smart moments and summaries are delegated through agent chat and saved
-  only after grounding validation.
-- Provider mutations are revision-aware, audited, and proposed when agent risk
-  requires approval.
-
-## Start or connect CRM
-
-1. Open **Set up CRM** and select **Start with Native SQL** to use CRM without
-   HubSpot or Salesforce. Native records and fields are local-authoritative.
-2. To use CRM as a companion, in shared **Settings → Connections**, authorize
-   HubSpot or Salesforce and
-   grant the connection to CRM. OAuth and refresh tokens stay in workspace
-   Connections; CRM never accepts a token or key. Salesforce production is the
-   default. For a sandbox, use **Authorize the sandbox directly** on Set up CRM;
-   the selected login environment is retained for token refresh.
-3. Choose the granted connection and select a recent
-   history window. HubSpot may be narrowed to deal pipeline IDs; Salesforce
-   starts with recently updated Accounts, Contacts, and Opportunities.
-4. CRM mirrors the selected cohort and allow-listed fields only. Confirm the
-   connection actor's access before relying on a record in the local mirror.
-
-## Operating model
-
-- **Connected**: the source CRM is authoritative. CRM is a scoped companion
-  for record work, saved views, tasks, call evidence, and analysis.
-- **Hybrid**: the source CRM remains authoritative for remote fields; CRM may
-  own explicitly configured derived-local and local-authoritative fields.
-- **Native SQL**: CRM is the system of record for its accounts, people,
-  opportunities, relationships, saved views, tasks, cadence, and local fields.
-  It has no upstream provider, sync job, or provider token.
-- **Signals**: attach one Clips call-evidence artifact to one or more CRM
-  records, run the default Pricing, Competitors, Objections, Next steps,
-  Budget, and Timing detectors, then confirm or dismiss the grounded results.
-  Clips remains the owner of recording, transcript, consent, and media access.
-- **Clips review recipe**: from a chosen CRM record, prepare a default-off
-  `clip.created` recipe. After explicit activation, its Clips-owned trigger
-  ignores the event media URL, resolves the clip through an access-checked
-  read action, and attaches only its opaque ID, durable HTTPS `/r/<id>` page,
-  and capture time to that exact CRM record. It never copies media or a
-  transcript, infers another record, or authorizes a provider write.
-- **Pipeline dashboard**: install the CRM-owned Pipeline dashboard to get
-  action-backed stage, amount, and close-date panels. Its data program and
-  dashboard revisions are access-scoped CRM records; the reusable chart and
-  table presentation comes from the Toolkit dashboard kit.
-- **Read and write safety**: provider reads use the connection's effective
-  permissions. Upstream changes are revision-aware, access-checked proposals
-  in this release; finish the approved change in HubSpot or Salesforce and do
-  not claim a provider write completed from CRM.
-
-## Review and delegation policy
-
-CRM records the actor, expected remote revision, idempotency key, field-level
-provenance, and an audit event for each mutation request. Local, reversible
-routine work can execute in CRM. Agent-initiated provider changes become
-reviewable proposals; destructive, bulk, and named-risk changes remain gated.
-Delegated authority is narrow and stored as policy—it never expands record or
-field access, bypasses the write firewall, or turns a provider result into an
-unverified success.
-
-Salesforce reads are validated against the current connection actor and field
-permissions before mirrored data is returned. A service-account mirror never
-proves a user's access; ambiguous or changed access fails closed until refresh.
-
-## Live testing
-
-Use a shared, already-authorized workspace Connection—never copy its secret
-into an environment file. Choose a small recent cohort, verify the resulting
-records and access scope in CRM, then test a proposal without applying a
-provider change. Record only connection labels, counts, and non-sensitive
-results in test evidence.
-
-See [the CRM contract](docs/architecture/crm-contract.md) for field policies,
-identity, access scope, and write decisions.
-
-## Local development
-
-```bash
-pnpm install
-pnpm dev
-```
-
-Set `DATABASE_URL` for persistent deployment storage. Native SQL works without
-external credentials. Connect HubSpot or Salesforce from the workspace
-Connections surface; do not add provider secrets to `.env`.

package/corpus/templates/crm/_gitignore

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

package/corpus/templates/crm/actions/_crm-action-utils.ts

@@ -1,87 +0,0 @@
-import type { ActionRunContext } from "@agent-native/core/action";
-import {
-  getRequestOrgId,
-  getRequestUserEmail,
-} from "@agent-native/core/server";
-
-export {
-  isBoundedCrmValue,
-  isSafeCrmMutationFieldName,
-  isSafeCrmMutationFields,
-} from "../server/crm/crm-field-firewall.js";
-
-export const MAX_CRM_FIELDS_PER_MUTATION = 20;
-
-export function requireCrmScope(ctx?: ActionRunContext) {
-  const ownerEmail = ctx?.userEmail ?? getRequestUserEmail();
-  if (!ownerEmail) throw new Error("Sign in is required to manage CRM data.");
-  const orgId = ctx?.orgId ?? getRequestOrgId() ?? null;
-  return {
-    ownerEmail,
-    orgId,
-    visibility: orgId ? ("org" as const) : ("private" as const),
-  };
-}
-
-export function crmInitiatedBy(ctx?: ActionRunContext) {
-  if (ctx?.caller === "automation") return "automation" as const;
-  return ctx?.caller === "tool" ||
-    ctx?.caller === "mcp" ||
-    ctx?.caller === "a2a"
-    ? ("agent" as const)
-    : ("human" as const);
-}
-
-export function crmWriteRisk(fieldNames: string[]) {
-  const names = fieldNames.map((field) => field.toLowerCase());
-  if (names.some((field) => field.includes("owner")))
-    return "ownership" as const;
-  if (names.some((field) => field === "amount" || field.includes("amount"))) {
-    return "amount" as const;
-  }
-  if (
-    names.some((field) => field.includes("stage") || field.includes("pipeline"))
-  ) {
-    return "stage" as const;
-  }
-  return "routine" as const;
-}
-
-export async function scopedCrmIdempotencyKey(input: {
-  ownerEmail: string;
-  orgId: string | null;
-  recordId: string;
-  key: string;
-}): Promise<string> {
-  const value = [
-    "crm-mutation-v1",
-    input.ownerEmail.toLowerCase(),
-    input.orgId ?? "",
-    input.recordId,
-    input.key,
-  ].join("\u0000");
-  const bytes = new TextEncoder().encode(value);
-  const digest = await crypto.subtle.digest("SHA-256", bytes);
-  return `crm:v1:${Array.from(new Uint8Array(digest), (byte) =>
-    byte.toString(16).padStart(2, "0"),
-  ).join("")}`;
-}
-
-export function toJson(value: unknown, maxChars: number) {
-  const encoded = JSON.stringify(value);
-  if (encoded.length > maxChars) {
-    throw new Error(`CRM payload exceeds the ${maxChars}-character limit.`);
-  }
-  return encoded;
-}
-
-export function parseJsonRecord(value: string): Record<string, unknown> {
-  try {
-    const parsed = JSON.parse(value) as unknown;
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
-      ? (parsed as Record<string, unknown>)
-      : {};
-  } catch {
-    return {};
-  }
-}