# InVision Amyloid CRM — guide for AI agents (Claude)

> Go-to-market CRM for **InVision Precision Cardiac Amyloid** (AI echo-based ATTR-CM
> detection). This file tells an LLM agent how to READ and WRITE the CRM. If you are
> Claude helping the InVision team (e.g. with a Gmail connector for
> andrew@invisionmedtech.com), you can read email and then add or update contacts here.

The live, machine-readable contract is **`GET /api/schema`** on this same origin — fetch it
first; it always reflects the deployed field list, enums, and examples. This file is the
human-and-agent-readable summary.

## What the data is
Contacts are real prescribers, KOLs, and the InVision commercial pipeline across ~130 US
health systems, plus partner/channel/pharma contacts. Provenance is marked with a chip:
`★ Gmail` = David Ouyang's personal contact, `◆ Work email` = surfaced from the InVision work
inbox (andrew@/david@invisionmedtech.com). Everything is real — never fabricate a person,
email, or title.

## API (same origin, JSON)
- `GET  /api/contacts?warm=HOT|WARM|COLD&status=<status>&q=<text>` → `{ contacts: [...] }`
- `POST /api/contacts` → create; body is a contact object, only `contact_name` is required.
- `GET  /api/contacts/:id` → `{ contact }`
- `PATCH /api/contacts/:id` → update writable fields; every change is audited. → `{ contact, changed }`
- `DELETE /api/contacts/:id` → `{ deleted }`
- `GET  /api/systems` → health systems ranked, with aggregate signal + key contacts.
- `PATCH /api/systems/:id` → update a system's `last_contact`, `owner`, `status`, `deal_stage`, `notes` (audited).
- `GET  /api/audit?entity=&actor=&action=&via=&q=&limit=` → the activity log, newest first.
- `GET  /api/schema` → the full machine-readable contract (fields, enums, examples).

## Auth & attribution (required)
The whole API is gated — `/api/schema` and `POST /api/login` are the only open endpoints;
everything else returns `401` without valid auth. Humans sign in through the UI with per-user
accounts (Andrew, David, bryan, milos, davidc), each with their own password (hashed in the
`users` table; new accounts must change the first-time default on first login).
**You (Claude) authenticate on every request with two headers:**
- `x-crm-token: <the shared CRM password, or CRM_WRITE_TOKEN if the deployment sets one>`
- `x-crm-editor: <who you act for> via Claude`  (e.g. `David via Claude Code`)

Your `x-crm-editor` identity is recorded as the actor on every create/update/delete, and those
rows show as `via=claude` in the log. Every change — human or Claude — is appended to `audit_log`
with a UTC timestamp and the field-level old→new diff, readable at `GET /api/audit`, and versioned
into the repo by `npm run pull`.

## Key fields (see /api/schema for all)
- `contact_name` (required to create), `institution`, `metro` ("CITY, ST"), `role_title`, `specialty`, `seniority`
- Role flags (`Y`/`N`): `amyloid_program_director`, `echo_lab_director`, `service_line_lead`, `cardiology_informatics_lead`
- `public_email`, `email_source`, `verification` (`verified`|`reported`|`pattern-inferred`|`not found`)
- `personal_contact_gmail` (provenance chip: `◆ Work email` | `★ Gmail` | `◇ Candidate` | `◈ crm.ivmtc.com` (imported from the external ivmtc CRM) | `? Gmail (confirm)` | "")
- `warm_cold` (`HOT`|`WARM`|`COLD`), `status` (`New`|`Contacted`|`Meeting`|`Pilot`|`Won`|`Lost`|`Do not contact`)
- **`deal_stage`** — the InVision Playbook sales process: `01 - Disco & Qual` → `02 - Demo & Meetings` →
  `03 - Proposal & Value Analysis` → `04 - Scoping & Purchase` → `05 - Contracting` → `Closed Won`/`Closed Lost`/`Hold`.
  Blank for cold prospects. Drives the **Pipeline** board.
- MEDDPICC-lite: `icp_tier` (`Tier 1|2|3|Channel/Pharma`; seeded from the authoritative account tiering),
  `buyer_persona` (Amyloid Treating Cardiologist / Echo Lab Medical Director / CMIO-AI Governance /
  Chair-VP CVSL / IT Sourcing / partner), `champion` (`Y`/`N`), `economic_buyer`,
  `competitor` (`Ultromics` / `Us2.ai` / `MyCardium` / `do nothing`)
- `owner`, `last_contacted`, `next_step`, `crm_notes`, `notes_cautions`

## Playbook for adding/updating from email
1. **Dedupe first.** `GET /api/contacts?q=<last name>` and check the institution before creating.
   If the person exists, `PATCH` their id instead of adding a duplicate.
2. **Mark provenance.** From the work inbox → `personal_contact_gmail: "◆ Work email"`,
   `email_source: "InVision work email (<thread subject>)"`, `prior_contact_with_david: "Y"`.
3. **Verify, don't guess.** `verification: "verified"` only when the email/title came straight
   from a signature or institutional page; otherwise `"reported"`. Never invent an address.
4. **Map the stage.** Cold intro, no reply → `status:"Contacted"`. Met / active thread / formal
   RFI / pricing → `status:"Meeting"`. Eval underway → `"Pilot"`. Declined or chose a competitor →
   `status:"Lost"` (or `"Do not contact"`), `warm_cold:"COLD"`, and note who/why in `notes_cautions`.
5. **Set role flags** from the person's actual role — they drive the Priority-gaps worklist.
6. **Advance `deal_stage`** as an account moves through the Playbook sales process, and fill the
   MEDDPICC-lite fields (`champion`, `economic_buyer`, `competitor`, `buyer_persona`, `icp_tier`)
   whenever the email reveals them. e.g. meeting scheduled → `01 - Disco & Qual`; MEDDPICC captured
   → `02 - Demo & Meetings`; proposal/VA/RFI → `03 - Proposal & Value Analysis`; purchase process
   started → `04 - Scoping & Purchase`; contract out (MSA/OF/BAA) → `05 - Contracting`.

## Example — add a contact from an email thread
```
POST /api/contacts
x-crm-editor: andrew@invisionmedtech.com via Claude
content-type: application/json

{
  "contact_name": "Jane Cardiologist",
  "institution": "Example Health",
  "metro": "AUSTIN, TX",
  "role_title": "Director, Echocardiography Lab",
  "specialty": "Echocardiography",
  "echo_lab_director": "Y",
  "public_email": "jane.cardiologist@examplehealth.org",
  "email_source": "InVision work email (Example Health <> InVision - Echo AI Chat)",
  "verification": "verified",
  "prior_contact_with_david": "Y",
  "personal_contact_gmail": "◆ Work email",
  "warm_cold": "WARM",
  "status": "Meeting",
  "owner": "Andrew Reeve",
  "next_step": "Send pricing + schedule technical eval",
  "crm_notes": "Met at ASE; interested in Syngo integration."
}
```

## Example — advance a deal
```
PATCH /api/contacts/123
x-crm-editor: andrew@invisionmedtech.com via Claude
content-type: application/json

{ "status": "Pilot", "warm_cold": "HOT", "last_contacted": "2026-09-01",
  "next_step": "Kick off 30-day evaluation" }
```