crm

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.