Use case: care coordination

A care manager at a busy outpatient clinic starts every morning rebuilding the same worklist by hand — who was discharged, who missed a lab, who is overdue on a quality gap. The data is all in the chart; it just can't be asked a question. This guide builds the assistant that answers it, end to end, across seven module slices: Intake to ingest the clinic's documents, Atlas to type the care graph, Warrant to certify the pathway, Conduit to pull live quality-gap data, Lens to answer with citations under a policy that never gives clinical advice, Lineage to trace any answer back to its source, and Crucible/Ports to lock the accuracy in and ship it as a running agent.

Prerequisites

• A workspace key with kb:write, kb:read, data:read, data:run, agents:run, and runs:read, exported as $ELI_KEY. See Getting started.
• Owner/admin on the workspace, to create connectors and certify concepts.
• An enabled chat model, so /query can generate — otherwise 409 no-model-configured.

1 · Intake — ingest the clinic's charts and pathways

The clinic's knowledge lives in a dozen markdown documents — the provider roster, department pages for Cardiology and Primary Care, de-identified patient personas, care pathways, and the HEDIS quality set. Post them as documents so their vault files, chunks, and FTS index commit before enrichment begins. Here is the Cardiology department page — the source that will thread through every slice below:

curl -s -X POST https://your-host/api/v1/documents \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "departments/cardiology.md",
    "title": "Department — Cardiology",
    "content": "# Cardiology\n\nLed by [[Dr. Naomi Okafor]] and staffed by the [[Heart Failure Care Team]]. Runs the [[Heart Failure Pathway]] and shares the [[Hypertension Pathway]] with [[Primary Care]]. Measured by [[Heart Failure Follow-Up]] and [[Statin Therapy for Cardiovascular Disease]] under [[HEDIS]]."
  }'

{ "docId": "01KYCARDIOLOGY00000000000", "path": "departments/cardiology.md", "contentHash": "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824", "title": "Department — Cardiology" }

The 201 confirms stored text and FTS readiness, not graph readiness. Detached extraction can subsequently build the concept graph — Atlas can type references such as [[Heart Failure Care Team]] and [[Dr. Naomi Okafor]] into nodes and edges. The seed pack already includes its prepared graph fixtures; API-created documents acquire graph structure only as enrichment completes.

2 · Atlas — type the care graph

Retrieval is sharper when it is structured, not just text. The workspace ontology defines six entity types — Provider, CareTeam, PatientPersona, Department, CarePathway, and QualityMeasure — joined by relations like cares_for, staffs, follows_pathway, and measured_by. Read a provider node to see the graph Intake just built:

curl -s https://your-host/api/v1/entities/01KZNAOMIOKAFOR0000000000 \
  -H "Authorization: Bearer $ELI_KEY"

{
  "id": "01KZNAOMIOKAFOR0000000000",
  "name": "Dr. Naomi Okafor",
  "type": "Provider",
  "authority": "machine_extracted",
  "relations": [
    { "type": "cares_for", "dstName": "Patient A — CHF", "dstType": "PatientPersona" },
    { "type": "staffs", "dstName": "Cardiology", "dstType": "Department" },
    { "type": "staffs", "dstName": "Heart Failure Care Team", "dstType": "CareTeam" }
  ]
}

That single node already answers "who cares for the CHF panel?" without any generation — Dr. Naomi Okafor cares_for the de-identified Patient A — CHF persona and staffs both Cardiology and the Heart Failure Care Team. Retrieval can now filter by type and walk edges, so a question about a department pulls its providers, pathways, and measures instead of loose text matches.

3 · Warrant — certify the pathway

A clinical claim the assistant states plainly has to be vouched for. In Warrant, curate the Heart Failure Pathway concept, pin its definition — the 7-day post-discharge follow-up the care team must hit — and certify it. Certified is the only tier the answer policy will state without hedging.

curl -s -X POST https://your-host/api/v1/change-requests \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "update",
    "entityId": "01KZHFPATHWAY000000000000",
    "payload": { "description": "Heart Failure Pathway: every heart-failure discharge gets a 7-day post-discharge follow-up visit, medication reconciliation, and guideline-directed therapy review; outreach owned by the Heart Failure Care Team." },
    "note": "Pinning the 7-day post-discharge follow-up the care team must hit"
  }'

{ "id": "01KZCR00000000000000000AA", "entityId": "01KZHFPATHWAY000000000000", "kind": "update", "status": "open" }

curl -s -X POST https://your-host/api/v1/entities/01KZHFPATHWAY000000000000/certify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"note":"Signed off by Dr. Naomi Okafor (Cardiology lead) and Marcus Webb (RN care manager)"}'

{ "authority": "certified", "lifecycleStatus": "published", "version": 3, "nextReviewAt": "2027-01-18T13:10:00.000Z" }

Do the same for the source document — verify the Cardiology department page so its provenance carries a governance tier the assistant and Lineage can report:

curl -s -X POST https://your-host/api/v1/documents/01KYCARDIOLOGY00000000000/verify \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"verification":"certified","note":"Cardiology department page current as of the FY26 pathway review"}'

{ "id": "01KYCARDIOLOGY00000000000", "verification": "certified", "verifiedAt": "2026-07-22T13:02:00.000Z", "nextVerifyAt": "2026-12-29T00:00:00.000Z" }

4 · Conduit — pull live quality gaps, with provenance

"Who has an open gap right now?" can't come from a static document — it changes hourly. Conduit wires the clinic's read-only clinical-operations database in as a connector and exposes governed named queries bound onto entities. Create the source first — the credential is stored encrypted and masked on every read:

curl -s -X POST https://your-host/api/v1/connectors \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "postgres",
    "name": "riverside-clinops",
    "config": { "host": "localhost", "port": 54330, "database": "riverside_clinops", "user": "app", "sslMode": "disable" },
    "credential": "<clinops-db-password>"
  }'

{ "id": "01KZCONNSRC00000000000000", "type": "postgres", "name": "riverside-clinops", "status": "active", "hasCredential": true, "maxRows": 200 }

The pack ships three named queries — encounter-volume-by-department, open-gaps-by-department, and overdue-quality-gaps — and binds them onto entities so the graph knows which live question each node can answer. The open-gaps-by-department query is bound onto the Cardiology entity; run it, and every execution writes an append-only data_calls row and hands back a dataCallId — the [Dn] anchor you can cite later:

curl -s -X POST https://your-host/api/v1/data/queries/open-gaps-by-department/run \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{"department":"Cardiology"}}'

{
  "dataCallId": "01KY10CCCCCCCCCCCCCCCCCCCC",
  "connectorName": "riverside-clinops",
  "queryTitle": "Open care gaps by department",
  "columns": ["patient", "measure", "days_open"],
  "rows": [
    { "patient": "Patient A — CHF", "measure": "Heart Failure Follow-Up", "days_open": 12 },
    { "patient": "Patient A — CHF", "measure": "Statin Therapy for Cardiovascular Disease", "days_open": 5 }
  ],
  "rowCount": 2,
  "truncated": false,
  "durationMs": 47,
  "executedAt": "2026-07-22T13:05:03.412Z"
}

5 · Lens — the care team asks, and gets a cited answer

Now the payoff. The care manager asks in plain language; Lens detects the entities, runs their bound queries as governed [Dn] lookups alongside document [Sn] citations, grounds one generation, and returns an answer with a policy decision that says how much to trust it. Ask the exact question the seeded policy covers, with includeData: true so the live gap query fires:

curl -s -X POST https://your-host/api/v1/query \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"Which patients in Cardiology have open care gaps?","includeData":true}'

{
  "answer": "Cardiology currently has open care gaps for Patient A — CHF: a Heart Failure Follow-Up gap (12 days open) and a Statin Therapy for Cardiovascular Disease gap (5 days open) [D1]. Cardiology is measured on both of these HEDIS measures under the Heart Failure Pathway [S1].",
  "claims": [
    { "text": "Patient A — CHF has an open Heart Failure Follow-Up gap in Cardiology", "citations": ["D1"] },
    { "text": "Cardiology is measured on Heart Failure Follow-Up and Statin Therapy for Cardiovascular Disease", "citations": ["S1"] }
  ],
  "dataCalls": [ { "id": "D1", "dataCallId": "01KY10CCCCCCCCCCCCCCCCCCCC", "queryTitle": "Open care gaps by department", "executedAt": "2026-07-22T13:05:03.412Z" } ],
  "sources": [ { "id": "S1", "docId": "01KYCARDIOLOGY00000000000", "docTitle": "Department — Cardiology", "docPath": "departments/cardiology.md" } ],
  "entities": [ { "id": "01KZCARDIOLOGY00000000000", "name": "Cardiology", "type": "Department", "authority": "certified" } ],
  "policy": { "decision": "answer", "confidence": "high", "reason": "confidence_above_answer_floor — live gap query + certified department source" },
  "groundedness": { "verified": 2, "total": 2 },
  "model": { "chat": "claude-sonnet-4-5", "judge": "claude-haiku-4-5" }
}

The policy block is the trust signal: answer at 0.79 confidence — above the answer floor — because the patient list carries a live [D1] data-call anchor and the measure context is a certified [S1] source. Push on the edges and the policy engine does the right clinical thing: "Should Patient A start a beta-blocker?" returns abstain_with_pointers (clinical advice is out of scope, so it routes to the provider), while a softer question like "Is Patient B's diabetes well controlled?" returns answer_with_caveat at 0.43 — it hedges rather than bluffs. The same pipeline is a native MCP tool, so it drops straight into a care manager's assistant.

6 · Lineage — trace the answer back to its source

A quality lead reviewing the assistant asks the fair question: where is this coming from, and can I trust it? The answer cited S1 → docId 01KYCARDIOLOGY…. Pull that document's lineage and read the whole trail in one call — origin, governance, the entities it derived, and the answers it is grounding right now:

curl -s https://your-host/api/v1/documents/01KYCARDIOLOGY00000000000/lineage \
  -H "Authorization: Bearer $ELI_KEY" | jq '{origin: .origin, verification: .governance.verification, derived: .derived.entities, citedBy: .downstream.citedByAnswers}'

{
  "origin": {
    "kind": "api",
    "ingestedVia": "POST /api/v1/documents",
    "sourcePath": "departments/cardiology.md",
    "createdAt": "2026-07-22T12:40:00.000Z"
  },
  "verification": "certified",
  "derived": ["Cardiology", "Dr. Naomi Okafor", "Heart Failure Care Team", "Heart Failure Pathway"],
  "citedBy": 6
}

There it is, closed loop: the [S1] in the answer traces to an api-ingested document that is certified, that derived the Cardiology, Dr. Naomi Okafor, and Heart Failure Pathway nodes, and that is currently grounding 6answers — so an edit to it has a known blast radius. The lead didn't have to trust the model; they read the pedigree. And the [D1] number is just as traceable: its data_calls row records the exact open-gaps-by-department execution, params, and timestamp behind the patient list.

7 · Crucible & Ports — lock it in, then ship the agent

Care protocols change, and a wrong answer at the point of care is expensive. Capture the questions care teams actually ask as a golden set so Crucible can prove the assistant still answers them after every content change. Anchor the golden item "Why must a heart-failure discharge get a 7-day follow-up visit?" to the certified pathway, and seed a provenance qrel from the pathway chunk that should ground it:

curl -s -X POST https://your-host/api/v1/qrels \
  -H "Authorization: Bearer $ELI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queryId": "01KZGOLDEN000000000000000",
    "chunkId": "01KYHFPATHWAYCHUNK0000000",
    "docId": "01KYHFPATHWAY000000000000",
    "grade": 3,
    "source": "provenance"
  }'

{ "id": "01KZQREL0000000000000000A", "queryId": "01KZGOLDEN000000000000000", "grade": 3, "source": "provenance" }

Run the "Care coordination Q&A baseline" set from the evals workspace, then read the metrics. Retrieval and abstention numbers are deterministic; RAGAS numbers carry the judge model that produced them. For this workspace, abstention.truthfulness is the number that matters most — it proves the never-give-clinical-advice guardrail is actually holding:

curl -s https://your-host/api/v1/evals/runs/01KZRUNA00000000000000000/metrics \
  -H "Authorization: Bearer $ELI_KEY"

{
  "runId": "01KZRUNA00000000000000000",
  "n": 24,
  "retrieval": { "recallAtK": 0.77, "ndcgAt10": 0.73, "mrr": 0.81, "hitAtK": 0.92 },
  "ragas": { "faithfulness": 0.92, "responseRelevancy": 0.85, "contextPrecision": 0.69 },
  "abstention": { "truthfulness": 0.68, "abstainRate": 0.14, "aurc": 0.061 }
}

With the accuracy pinned, ship it. The pack seeds the Care Coordination Analyst agent (care-coordination-analyst), which wraps this same grounded pipeline, cites every claim, abstains without chart backing, and carries memories like the 7-day heart-failure window and the 90-day gap-closure clock — so a run against it reproduces the whole walkthrough. Ports closes the loop on the care manager's original complaint about rebuilding the worklist by hand: the seeded alerts fire the moment a gap goes stale — a gap.overdue warning for Patient B — Type 2 Diabetes (HbA1c gap open more than 120 days, routed to population health) and a followup.due notice for Patient A — CHF's 7-day post-discharge visit.

When a metric drops after a protocol update, the golden set names exactly which question regressed — and promoting that miss back into the set turns it into a permanent test. That is the dashed loop in the diagram: Crucible's regressions steer the next round of Warrant curation. Compare two configs with a two-gate significance test in Measure & compare.

The leverage

Seven slices, one care graph, one audit trail. The care manager gets a fast, cited worklist instead of rebuilding it by hand every morning; the quality lead can trace any answer to a certified source and see its blast radius; the live numbers carry [Dn] query provenance while certified pathway facts carry [Sn]citations; the policy abstains on clinical advice rather than guessing; and the whole thing is measured, so accuracy is a number you watch. Swap Cardiology for any specialty, or the clinic for a health system, and the shape is identical — the platform doesn't care what the charts are about, only that every answer is grounded, governed, traceable, and measured.