@agent-native/core 0.123.0 → 0.123.2

package/corpus/templates/content/changelog/2026-07-26-collaborative-documents-no-longer-flash-duplicated-recent-bl.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-26
+---
+
+Collaborative documents no longer flash duplicated recent blocks when reopened

package/corpus/templates/content/changelog/2026-07-26-corrected-builder-updates-are-now-reviewed-separately-from-f.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-26
+---
+
+Corrected Builder updates are now reviewed separately from failed earlier attempts, slow hosted writes get a full provider response window, and uncertain outcomes still require reconciliation before retry.

package/corpus/templates/content/changelog/2026-07-26-documents-now-remain-read-only-until-their-live-collaborativ.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-26
+---
+
+Documents now remain read-only until their live collaborative content finishes initial sync.

package/corpus/templates/content/changelog/2026-07-26-slash-command-menus-now-stay-reachable-when-editing-near-the.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-26
+---
+
+Slash command menus now stay reachable when editing near the bottom of the screen.

package/corpus/templates/content/changelog/2026-07-26-the-slash-menu-now-shows-one-clear-callout-choice-instead-of.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-07-26
+---
+
+The slash menu now shows one clear Callout choice instead of duplicate actions

package/corpus/templates/content/shared/api.ts

@@ -957,6 +957,7 @@ export interface RefreshContentDatabaseSourceRequest {
   documentId?: string;
   sourceId?: string;
   fullRefresh?: boolean;
+  expectedBuilderContinuationOffset?: number;
 }
 
 export interface DisconnectContentDatabaseSourceRequest {

package/corpus/templates/content/shared/builder-mdx.ts

@@ -1872,19 +1872,75 @@ function freshTextHtmlBlock(text: string, stableSource: string): unknown {
   };
 }
 
-function assertSafeFreshCalloutNode(node: MdxNode) {
-  for (const child of node.children ?? []) {
-    if (
-      child.type === "mdxFlowExpression" ||
-      child.type === "mdxTextExpression" ||
-      child.type === "mdxjsEsm" ||
-      child.type === "mdxJsxFlowElement" ||
-      child.type === "mdxJsxTextElement"
-    ) {
-      throw new Error("Unsupported dynamic syntax inside Builder callout.");
+function assertSafeFreshCalloutNode(node: MdxNode, raw: string) {
+  const rootStart = node.position?.start?.offset;
+  const visit = (candidate: MdxNode) => {
+    for (const child of candidate.children ?? []) {
+      const childStart = child.position?.start?.offset;
+      const childEnd = child.position?.end?.offset;
+      const childRaw =
+        typeof rootStart === "number" &&
+        typeof childStart === "number" &&
+        typeof childEnd === "number"
+          ? raw.slice(childStart - rootStart, childEnd - rootStart).trim()
+          : "";
+      const emptyBlockNode =
+        (child.type === "mdxJsxFlowElement" ||
+          child.type === "mdxJsxTextElement") &&
+        child.name === "empty-block";
+      if (emptyBlockNode) {
+        if (isEmptyEditorBlockSentinel(child, childRaw)) continue;
+        throw new Error(
+          "Unsupported Builder callout empty-block syntax. Only an attribute-free, self-closing Content editor sentinel can be omitted.",
+        );
+      }
+      if (
+        child.type === "mdxFlowExpression" ||
+        child.type === "mdxTextExpression" ||
+        child.type === "mdxjsEsm" ||
+        child.type === "mdxJsxFlowElement" ||
+        child.type === "mdxJsxTextElement"
+      ) {
+        throw new Error("Unsupported dynamic syntax inside Builder callout.");
+      }
+      visit(child);
     }
-    assertSafeFreshCalloutNode(child);
-  }
+  };
+  visit(node);
+}
+
+function removeSafeCalloutEmptyBlockSentinels(node: MdxNode, raw: string) {
+  const rootStart = node.position?.start?.offset;
+  if (typeof rootStart !== "number") return raw;
+  const ranges: Array<{ start: number; end: number }> = [];
+
+  const visit = (candidate: MdxNode) => {
+    for (const child of candidate.children ?? []) {
+      const start = child.position?.start?.offset;
+      const end = child.position?.end?.offset;
+      if (typeof start !== "number" || typeof end !== "number") {
+        visit(child);
+        continue;
+      }
+      const relativeStart = start - rootStart;
+      const relativeEnd = end - rootStart;
+      const childRaw = raw.slice(relativeStart, relativeEnd).trim();
+      if (isEmptyEditorBlockSentinel(child, childRaw)) {
+        ranges.push({ start: relativeStart, end: relativeEnd });
+        continue;
+      }
+      visit(child);
+    }
+  };
+  visit(node);
+
+  return ranges
+    .sort((left, right) => right.start - left.start)
+    .reduce(
+      (current, range) =>
+        `${current.slice(0, range.start)}${current.slice(range.end)}`,
+      raw,
+    );
 }
 
 function findMdxOpeningTagEnd(raw: string) {
@@ -1936,14 +1992,15 @@ function freshCalloutBlock(
       `Unsupported Builder callout attribute: ${attribute.name}.`,
     );
   }
-  assertSafeFreshCalloutNode(node);
+  assertSafeFreshCalloutNode(node, raw);
 
-  const openingEnd = findMdxOpeningTagEnd(raw);
-  const closingStart = raw.lastIndexOf("</callout>");
+  const contentRaw = removeSafeCalloutEmptyBlockSentinels(node, raw);
+  const openingEnd = findMdxOpeningTagEnd(contentRaw);
+  const closingStart = contentRaw.lastIndexOf("</callout>");
   if (openingEnd < 0 || closingStart < openingEnd) {
     throw new Error("Builder callout must have an explicit closing tag.");
   }
-  const markdown = raw
+  const markdown = contentRaw
     .slice(openingEnd + 1, closingStart)
     .split(/\r?\n/)
     .map((line) => line.replace(/^(?:\t| {2})/, ""))

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

@@ -0,0 +1,115 @@
+---
+name: agent-native-docs
+description: >-
+  How to find version-matched Agent Native framework docs and source bundled in
+  node_modules. Use before implementing or answering questions about
+  @agent-native/core APIs, generated apps, workspaces, templates, or advanced
+  features.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Agent Native Docs Lookup
+
+## Rule
+
+Before implementing or explaining non-trivial Agent Native behavior, read the
+version-matched docs installed with `@agent-native/core`. When examples,
+imports, or implementation details matter, inspect the packaged source corpus
+too.
+
+## Why
+
+Generated apps and workspaces may be on a different framework version than the
+public docs or model memory. The installed package is the source that matches
+the app in front of you. It also includes a source-only corpus of core and
+first-party templates so agents can replicate current best-practice patterns
+without needing the framework monorepo checkout.
+
+## How
+
+From a generated app directory:
+
+```bash
+pnpm action docs-search --query "<feature>"
+pnpm action docs-search --slug <slug>
+pnpm action docs-search --list
+pnpm action source-search --query "<pattern>"
+pnpm action source-search --path templates/plan/AGENTS.md
+pnpm action source-search --path toolkit/src/index.ts
+pnpm action source-search --list
+```
+
+The headless `pnpm agent` loop and built-in app agent also expose a read-only
+`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
+read-only `source-search` tool with `query`, `path`, and `list`.
+
+If the action runner is unavailable, search the package directly:
+
+```bash
+rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
+```
+
+Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
+under `node_modules/@agent-native/core/docs/content/`. For source examples,
+read files under `node_modules/@agent-native/core/corpus/core/` or
+`node_modules/@agent-native/core/corpus/templates/`.
+
+Toolkit source is searchable at `toolkit/` in the Core corpus and also ships as
+readable TypeScript under `node_modules/@agent-native/toolkit/src/`. Read
+`customizing-agent-native` before taking ownership of a shared component: inspect package
+source as a read-only reference, then configure, compose, or eject the smallest
+supported unit into app-owned source. Preserve public actions, application
+state, auth, and agent-chat runtime contracts. Never edit `node_modules` or
+deep-import its private source. Manual copying is only the fallback described by
+an unknown third-party package's add-style blueprint.
+
+## Reuse Proven Patterns (rg + cp)
+
+Version-matched installed source outranks web docs or memory: it is the exact
+code shipping with this app. `node_modules/@agent-native/core/corpus/templates/`
+holds source for every first-party template, not just the one this app started
+from, so a pattern from the mail template is fair game for a tasks app. Grep
+across it, then copy a whole file as a starting point instead of writing the
+pattern from scratch:
+
+```bash
+# Find how other templates solved a similar problem
+rg -n "drag.*drop|reorder" node_modules/@agent-native/core/corpus/templates
+
+# Grab a proven action file as a starting point, then adapt names/schema
+cp node_modules/@agent-native/core/corpus/templates/mail/actions/archive-email.ts \
+   actions/archive-item.ts
+
+# Read the full framework source behind an API, not just the corpus copy
+rg -n "defineAction" node_modules/@agent-native/core/src/action.ts
+```
+
+Copying template-level app code (actions, components, skill files) is the
+expected reuse path — templates exist to be forked. This is different from
+copying `core`/`toolkit` **runtime internals**: for those, follow
+`customizing-agent-native`'s configure/compose/eject ladder instead of
+hand-duplicating framework logic.
+
+## Useful Slugs
+
+| Need                           | Slugs                                                         |
+| ------------------------------ | ------------------------------------------------------------- |
+| Actions and typed client calls | `actions`, `client`                                           |
+| SQL, auth, access, sharing     | `database`, `authentication`, `security`, `sharing`           |
+| UI state visible to the agent  | `context-awareness`                                           |
+| Headless and chat-first apps   | `pure-agent-apps`, `agent-surfaces`, `using-your-agent`       |
+| Automations and schedules      | `automations`, `recurring-jobs`                               |
+| Cross-app and external agents  | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions        | `skills-guide`, `writing-agent-instructions`                  |
+
+## Don't
+
+- Do not rely on memory for framework APIs when package docs are present.
+- Do not add custom REST wrappers for app data before reading `actions`.
+- Do not add inline LLM calls before reading `using-your-agent` and
+  `agent-surfaces`.
+- Do not copy framework runtime internals when a public API or narrow UI copy
+  will do; read `customizing-agent-native` for the supported override ladder.

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

@@ -0,0 +1,177 @@
+---
+name: agent-native-toolkit
+description: >-
+  Inventory and ownership rules for shared Agent Native workspace UI. Use
+  before building app chrome, settings, navigation, sharing, collaboration,
+  setup, history, comments, chat rails, agent UX, or repeated workspace behavior.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Agent-Native Toolkit
+
+Use this skill when deciding whether app chrome, settings, collaboration,
+sharing, navigation, organization, setup, history, comments, or agent UX should
+be built app-locally or moved into reusable framework/toolkit pieces.
+
+## Core Rule
+
+Apps own domain models, domain actions, and product-specific workflows. The
+framework and `@agent-native/toolkit` own repeated workspace behavior users
+expect to work the same everywhere.
+
+Move behavior into shared toolkit primitives when it is:
+
+- workspace-wide, such as settings, nav, search, org membership, or setup
+- agent-visible, such as context, actions, run progress, or proof-of-done
+- governed, such as secrets, permissions, sharing, audit, or billing
+- repeated by two or more apps
+- not tied to one domain model
+
+Keep behavior app-local when the abstraction would hide important domain
+language or make a simple app-specific workflow harder to understand.
+
+## Discover Before Building
+
+Before creating an app-local version of repeated workspace or agent UI:
+
+1. Check the reusable kits below and the installed package documentation.
+2. Search installed public components and source with `docs-search` and
+   `source-search`.
+3. Run `agent-native eject --list` to see the version-matched units published
+   by the packages installed in this app.
+4. Read `customizing-agent-native` and configure, compose, or eject the
+   smallest unit instead of recreating shared behavior from memory.
+
+Use public package exports at runtime. Published source and ejection manifests
+are discovery and ownership-transfer mechanisms, not private runtime APIs.
+
+## Design-System Boundary
+
+Every app keeps an explicit design-system seam in `app/design-system.ts` using
+`defineDesignSystem` from `@agent-native/toolkit/design-system`, and supplies it
+to `ToolkitProvider`. The semantic contract contains:
+
+- nine leaf components: `ActionButton`, `IconButton`, `TextField`, `TextArea`,
+  `Spinner`, `Skeleton`, `Status`, `Surface`, and `Avatar`
+- eight behavior components: `Tooltip`, `Menu`, `Popover`, `Dialog`, `Picker`,
+  `Checkbox`, `Switch`, and `Tabs`
+
+These are semantic contracts, not styling contracts. An adapter may use
+Tailwind/shadcn, MUI-style theme providers, React Aria, CSS modules, CSS-in-JS,
+or another React design system. Do not assume CVA, utility classes, or even a
+`className`; behavior adapters may supply their overlay and focus
+implementation wholesale while honoring portal, focus-restoration, keyboard,
+dismissal, ARIA, and z-index interoperability.
+
+Pages, routes, and domain components import ordinary controls through the app's
+local adapter layer, usually `@/components/ui/*`. They must not import
+`@agent-native/toolkit/ui/*` directly. Toolkit feature exports are still the
+right home for shared workspace behavior; their presentation flows through the
+registered semantic components, feature controller, and product-level slots.
+
+Customer adapter packages are normal npm packages imported explicitly by the
+app. Never auto-detect them or load React components from JSON. Run the adapter
+against `@agent-native/toolkit/conformance` in customer CI before adopting it.
+
+## Settings Direction
+
+Durable settings belong in the Settings app or a registered settings route. The
+agent sidebar should not become a second settings app. It can show contextual
+quick controls and deep links such as:
+
+- `/settings/ai`
+- `/settings/connections`
+- `/settings/secrets`
+- `/settings/usage`
+- `/settings/apps/:appId`
+
+The shared Account section is the canonical profile surface at
+`/settings#account`. It owns the editable display name and existing avatar
+control through the authenticated `get-user-profile` and `update-user-profile`
+actions. Shared workspace chrome such as `OrgSwitcher` should link to this
+surface rather than creating an app-local profile page.
+
+When adding a new API key, OAuth grant, provider connection, model selector, app
+preference, notification preference, or usage/billing surface, register it as a
+settings tab or app settings panel first. Only add sidebar UI when it is needed
+in the moment of agent use.
+
+## Reusable Kits
+
+- **Settings kit**: a searchable settings page with account, workspace, AI
+  models, LLM keys, connections, secrets, usage, notifications, changelog, and
+  app-specific panels. Search is on by default; register a `SettingsSearchEntry`
+  per control so users find settings by name across tabs.
+- **Collaboration kit**: Yjs docs, presence, agent presence, live cursors,
+  remote selections, recent edit highlights, real-time sync indicators, and
+  undo/redo grouping.
+- **Sharing kit**: private/workspace/org/public-link access, invites, roles,
+  expirations, agent-readable links, and resource registration.
+- **Navigation and command kit**: app shell, side nav, breadcrumbs, app switcher,
+  command palette entries, recent resources, pinned resources, and global search.
+- **Organization kit**: folders, tags, favorites, archive, trash, ownership,
+  membership, and common resource metadata.
+- **Setup and connections kit**: declarative setup requirements, model readiness,
+  missing-secret states, OAuth grants, and provider connection health.
+- **Agent UX kit**: sidebar, composer, staged context, mentions, voice, human
+  approval, generative UI, progress, and screen-state exposure.
+- **Chat history kit**: presentational chat lists and recent-chat rails belong
+  in Toolkit; Core keeps thread persistence, agent execution, transport, and
+  page-to-sidebar handoff. Use Toolkit's `ChatHistoryRail` for the standard
+  five-item sidebar preview and a footer row with New chat followed by an
+  ellipsis disclosure up to fifteen. Apps inject routing, labels, and domain
+  actions.
+- **Agent page kit**: the full-page `/agent` surface (`AgentTabsPage` from
+  `@agent-native/core/client`) with Context, Files, Connections, Jobs, and
+  Access tabs plus a Personal/Organization scope toggle. The canonical home
+  for context transparency, MCP servers, A2A remote agents, recurring
+  jobs/automations, and external-client connect flows. See the `agent-page`
+  skill.
+- **History and recovery kit**: audit log, activity feed, version history,
+  checkpoints, undo, redo, restore, and proof-of-done.
+- **Comments and review kit**: anchored comments, pins, mentions, review
+  requests, resolved threads, agent follow-up tasks, and notifications.
+- **Workflow and observability kit**: notifications, approvals, scheduled work,
+  background runs, recurring jobs, traces, evals, feedback, and run timelines.
+
+## Implementation Checklist
+
+When adding or refactoring one of these areas:
+
+1. Search existing framework and template code for duplicated UI or actions.
+2. Decide the shared contract: data shape, action API, feature-level headless
+   controller, default view, semantic components, and product-level render
+   slots.
+3. Keep shared data provider-agnostic and scoped by auth/sharing rules.
+4. Expose the same capability to the UI and agent through actions or documented
+   client helpers.
+5. Register app-specific labels, routes, resource adapters, and settings panels
+   instead of hardcoding app names in core UI.
+6. Update docs and relevant skills so future apps discover the shared path.
+7. Keep the component easy to adopt piecemeal: expose props/slots first and
+   ship readable source plus a complete ejection unit so apps can take ownership
+   of the smallest feature when needed. See `customizing-agent-native` for the
+   configure → compose → eject → propose seam ladder.
+8. Keep one controller as the source of truth for the default and custom render
+   paths. A custom design must not fork actions, analytics, async state, or
+   accessibility behavior.
+9. Verify the default adapter and at least one non-Tailwind adapter with the
+   conformance kit, including focus and portal stacking across mixed overlay
+   implementations.
+
+## Related Skills
+
+Read these alongside this skill when the work touches the specific area:
+
+- `sharing`
+- `real-time-collab`
+- `real-time-sync`
+- `client-side-routing`
+- `context-awareness`
+- `onboarding`
+- `secrets`
+- `audit-log`
+- `observability`
+- `frontend-design`

package/corpus/templates/crm/.agents/skills/crm/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: crm
+description: How to run typed CRM work — attributes and options, lists and pipelines, saved and board views, provider proposals, duplicates and merge, gated enrichment, and evidence-grounded call signals. Use for any CRM read, write, setup, or provider question.
+---
+
+# CRM
+
+`AGENTS.md` owns the invariants (attribute typing, bitemporal values, list
+authority, the provider handoff, credential and evidence boundaries). This skill
+is the how: which action, in what order, and the traps in between. Do not
+restate a rule here that `AGENTS.md` already states — fix it there instead.
+
+Model source of truth: `shared/crm-contract.ts`. Type registry:
+`shared/crm-attributes.ts`. Every field-value write goes through
+`server/lib/record-fields.ts`.
+
+## Pick the starting action
+
+- `get-crm-workspace` — "what should I work on", who the caller is, whether
+  their provider owner identity resolved. Read `ownerStatus` before trusting an
+  empty book: `unmapped`, `ambiguous`, and `unreadable` are different failures,
+  and none of them mean "no records".
+- `view-screen` — only when the request depends on the visible record,
+  selection, list, or view. `navigate` to show a view rather than describing it.
+- `list-crm-records` / `get-crm-record` / `get-crm-record-page` — ordinary reads.
+- `sync-crm` — one declared, bounded provider cohort. It is not an export-all,
+  and Native SQL never needs it.
+
+## Setup and modes
+
+- `configure-native-crm` starts a local-authoritative CRM with no provider,
+  portable across SQLite, Postgres, and D1. Then use the normal record, list,
+  task, view, and evidence actions. Never require a connection for Native SQL.
+- After HubSpot or Salesforce is authorized in workspace Connections, register
+  it with `configure-crm-connection`. Never pass a token. HubSpot starts with
+  companies/contacts/deals; Salesforce with Account/Contact/Opportunity.
+- `list-crm-connections` shows which object types a connection carries — read it
+  before authoring attributes on an object type.
+- Salesforce reads are revalidated against the current connection actor and
+  field permissions. Never infer a user's access from a service-account mirror
+  or a previously visible local row; fail closed when access is ambiguous.
+
+## Typed attributes and options
+
+- `list-crm-attributes` before any read, write, filter, or grouping. It returns
+  the type, cardinality (`multi`), authority, and managed options.
+- `create-crm-attribute` derives an immutable snake_case `apiSlug` from the
+  title. `update-crm-attribute` can change presentation, `required`,
+  `historyTracked`, config, `archived`, and `fillMode` — never the slug or the
+  type, because every stored value row is keyed and typed by them.
+- `manage-crm-attribute-option` adds an option *before* a value that uses it is
+  written. Archiving an option removes it from pickers only; records already
+  holding it keep the value.
+- `archive-crm-attribute` is a soft archive. Values and history stay. Restore
+  with `update-crm-attribute` and `archived: false`.
+- Status options may carry `targetDays` (a stage SLA the grid shows as overrun)
+  and `celebrate`.
+
+## Reading the grid
+
+- `list-crm-records` returns row summaries; `list-crm-record-values` returns the
+  cells for those rows with provenance. Filter, sort, and pagination all run in
+  SQL, so a filtered page is the real result set, not one page narrowed
+  afterwards. Pass `viewId` to apply a saved view's stored filter.
+- A filter naming an unknown or archived attribute fails rather than quietly
+  returning unfiltered rows. Do not "fix" that by dropping the filter.
+- `get-crm-record-page` is the whole record surface in one call: attribute
+  definitions, current values with actor and time, every list the record is in
+  with that entry's values, and the provider deep link.
+
+## Lists and pipelines
+
+- A list is a workflow overlay over one object type; entry attributes belong to
+  the list, not the record. `create-crm-list` seeds a Stage attribute unless you
+  pass `seedStageAttribute: false`.
+- `add-crm-record-to-list` never de-duplicates — it returns `existingEntryIds`
+  and lets you decide. Two open deals for one company are two entries.
+- **Moving a stage is `update-crm-list-entry`.** It closes the previous value's
+  row and opens a new one, so time-in-stage is derivable from the entry's own
+  history without a separate audit table.
+- Every `status` write goes through `server/lib/lifecycle.ts`. The enterable set
+  is the attribute's own options, so a move into an undeclared or archived stage
+  is refused with a sentence naming the values you may pick (`unknown-status`,
+  `archived-status`), and the move is claimed against the value it was decided
+  from, so a stage somebody else moved in between comes back as
+  `concurrent-transition` instead of being clobbered. Leaving any stage —
+  including a retired one — is always allowed. On a record, `update-crm-record`
+  applies the same gate to local targets; a provider target is still a proposal,
+  not a blocked transition.
+- `remove-crm-list-entry` deletes membership and that entry's values only. It is
+  not a way to delete a record.
+- `list-crm-record-field-history` reads either side: pass `entryId` for a stage
+  history, `recordId` for a record attribute.
+
+## Views and boards
+
+`save-crm-saved-view` stores filter, ordered sort, columns, `table`/`board`
+presentation, and personal/shared audience. A board view needs a
+`groupByAttributeId` pointing at a status attribute. Pass `expectedUpdatedAt` so
+a concurrent edit is rejected instead of silently overwritten. A view stores
+presentation, never provider rows. `run-crm-saved-view-program` runs the data
+program linked to one view.
+
+## Writes and the provider handoff
+
+- `update-crm-record` for a scoped typed edit. Provider-owned fields become
+  revision-aware, access-checked, idempotent, audited proposals.
+- `list-crm-proposals` then `apply-crm-proposals`: the second returns the exact
+  before/after diff and a deep link, and records the handoff. A proposal with
+  status `approved` and no `appliedAt` was prepared and handed off — present
+  that as the next step for the user, never as a failure and never as applied.
+- The only stored delegation pack is `crm-sales-routine-local-v1`: one routine,
+  compensatable local update to one record, supplied by a trusted automation
+  trigger, never by action input.
+
+## Duplicates and merge
+
+`find-crm-duplicates` is read-only and never merges. It matches on exact email,
+company domain, shared email root domain, and normalized name plus location, and
+returns a reason and confidence per candidate. A shared company domain is a
+signal between accounts only — colleagues are a relationship, not a duplicate.
+
+`merge-crm-records` needs an explicit survivor. It promotes only the values the
+survivor lacks, moves list entries, tasks, interactions, evidence, signals, and
+relationships from both sides, and tombstones the loser with a `merged-into`
+link instead of deleting it. It is idempotent and approval-gated for non-human
+callers. Show the candidate reasons and let a human pick the survivor.
+
+## Enrichment (money changes hands)
+
+1. `list-crm-enrichment-slots` — which capability slots are usable. A slot's
+   `credential.status` of `unknown` means the lookup itself failed and is *not*
+   the same as `missing`.
+2. `estimate-crm-enrichment` — line-item cost and period-to-date spend. Quote it
+   to the user. `spendToDate.actorUnits` is theirs and is what the cap applies
+   to; `workspaceUnits` is everyone's and is context only.
+3. `run-crm-enrichment` with `phase: "verify"` — free evidence pass, never
+   touches contact data. A human reviews its per-record evidence.
+4. `run-crm-enrichment` with `phase: "spend"` — requires `sourceRunId` and the
+   explicit `approvedRecordIds` from that review. The paid input set is built
+   from those approvals, so an unapproved record is never visible to the paid
+   job. Both phases refuse a duplicate in-flight run for the same scope.
+
+A slot outcome is one of `unconfigured`, `skipped`, `ok`, `empty`, or `error` —
+report the one you got. "We could not find out" is not "there is none".
+
+## Agent attribute fill
+
+`run-crm-attribute-fill` is manual only. Call it with no `values` to get the
+brief (attribute, managed options, each record's current value and context),
+reason over that yourself, then call again with `values`. Never call a model
+inline. Writes merge: a human edit or a purchased value is kept and reported as
+`kept-existing`, an equal value is not rewritten. Classifying against a
+status/select attribute must produce one of its managed options; an unknown one
+rejects the whole call and writes nothing.
+
+## Evidence and signals
+
+- `attach-call-evidence` stores only a source URL/id, bounded quote, timestamp,
+  speaker, and metadata. For Clips use a durable `/share/<id>` or `/r/<id>` page
+  URL with no access token or transcript fragment — never a `clip.created` event
+  URL.
+- `run-crm-signal-trackers` runs only over evidence already attached to the
+  record. Keyword hits are deterministic; smart detectors and summaries are
+  delegated through agent chat, never a direct model call, and persisted with
+  `record-crm-smart-signal` or one atomic `record-crm-call-insight` batch whose
+  every quote and timestamp cites an exact stored evidence row.
+- `create-crm-signal-tracker` / `manage-crm-signal-tracker` need editor access.
+  Enabling, disabling, and deleting a tracker are local configuration only:
+  never a model call, never a provider mutation. Their settings tab is
+  `navigate({ view: "settings", settingsSection: "intelligence" })`.
+- `review-crm-signal` is the human confirm/dismiss step.
+- `get-crm-automation-recipe` returns the default-off Clips review recipe for
+  one explicitly selected record. The recipe is a configuration aid, not
+  permission to activate it: show the exact Clips-owned `clip.created` trigger,
+  the selected record, and its one bounded local evidence write, then get a fresh
+  approval. The trigger must call `prepare-crm-call-evidence` with the clip id
+  and hand back only the durable `/r/<id>` reference. It cannot create tasks,
+  field updates, proposals, or provider mutations.
+
+## Dashboards
+
+`install-crm-pipeline-dashboard` is idempotent and owns one per-user data
+program that calls the bounded `get-crm-pipeline-data` through `appAction`. Do
+not reimplement that aggregate with a provider request or put CRM rows in
+dashboard config. Edit with `save-crm-dashboard` plus `expectedUpdatedAt`;
+inspect and roll back with `list-crm-dashboard-revisions` /
+`restore-crm-dashboard-revision`.
+
+## Provider API escape hatch
+
+CRM actions are convenience workflows, not a capability ceiling. For an
+endpoint, object, filter, pagination mode, or schema no action expresses, use
+`provider-api-catalog`, then `provider-api-docs`, then the read-only
+`provider-api-request`. Declare a cohort, selected fields, and a page/row budget
+first; stage only that result and reduce it with `query-staged-dataset` or a
+data program. Report provider, scope, filters, page/row counts, truncation, and
+gaps. Always pass the selected workspace `connectionId` for Salesforce so its
+actor-bound token and instance URL cannot be separated.
+
+## Out of scope
+
+No provider migration, no page builder, no raw provider payload or media in CRM
+SQL. Native SQL supports the canonical CRM objects plus generic custom records; a
+separate object-authoring engine is not part of this template.