Riverside Practice Q&A

A document-grounded reception Q&A assistant for The Riverside Practice. Staff ask how to do something in EMIS Web (or what to do at the front desk) and get a step-by-step answer drawn strictly from the practice's own documents, with clickable sources they can open in-browser.

How it works

• Questions go to POST /api/agent, routed through OpenRouter. It is one model call, not a research loop: the model reads the message, chooses the template that fits it and fills that template's variables — and the answer is then the template, rendered in code from the values it returned. Understanding a message is what a model is good at, so it does that; the shape of what comes out is what a model is unreliable at, so code does that. The API key and server-side knowledge never reach the browser.
• The Notebook is a template too. It arrives as a list of page titles and the model returns a title; the page is then rendered from the database exactly as the practice wrote it. So even open-ended questions come back as a variable filled in rather than prose the model composed — the same answer every time, about ten output tokens, and no way for a procedure to be paraphrased on its way to somebody following it.
• The tool-calling loop this replaced is gone, along with its tools, its evidence registry, its compose/validate/repair cycle and the single-shot /api/ask endpoint before it. ANSWER-PIPELINE-REDESIGN.md records how they used to work and why they were replaced; ARCHITECTURE.md §8 describes the turn that runs now.
• A contact question is answered with a contact. The practice directory and the CQC register are matched in code (lib/contacts.fuzzy.mjs, lib/lookup/), and what they hold is shown in the contacts card as structured data — never retyped through the model's prose, where an unverified number is stripped out.
• The turn is streamed to the browser as it happens (newline-delimited JSON), so the field says which step is running instead of showing a silent spinner.
• Every turn is written down. The question, the answer as text, the template that built it and the model that ran are recorded in question_log (lib/questions/log.js) and read back at /stats. There is no answer cache: with the answer assembled in code from a page and a template, there was nothing left worth caching, and its question normaliser now lives in lib/routing/ as the first rung of the router.
• A question it cannot answer becomes a question somebody can. Every turn that comes back without an answer — a card flagged as a pathway the practice has not recorded, a prose answer standing on general knowledge with no Notebook page behind it, or a turn that fell over — is filed on the open questions list at /questions as it is logged (lib/questions/gaps.mjs). Staff can add a question there themselves, which is what the list was asked for; the assistant's own arrive without anybody having to notice them. Same wording twice is one row with a count, so the gap being hit five times a week is visible as the thing to write down next. The switch that turns the question log off at a desk turns this off with it.
• A message that asks for five things gets five things acknowledged. The selection call returns exactly one template, which is why an eConsult listing a knee, a hoarse voice, a repeat prescription, a fit note and a question about somebody's wife came back as a single knee card with the other four gone without trace. That is structural, not a quality problem, so the model is asked for one extra thing on the same call — where each separate ask starts and ends, copied out verbatim — and everything after that is decided in code (lib/safety/):
  • Acuity is a table, never the model's opinion. emergency > twoWeekWait > sameDay > routine > admin, checked top down. The card that renders is the most urgent item the band above it has not already answered — not the first one, and not the longest one.
  • The safety scanners run message-wide on every turn, whatever template was chosen. The red-flag list used to run only inside triage, so a message answered with a Notebook page was never scanned at all. Alongside it now: NICE NG12 suspected-cancer features (hoarseness over three weeks, unintended weight loss, dysphagia, a neck lump, haemoptysis, rectal bleeding, post-menopausal bleeding, a breast lump, visible haematuria), each reported with the words that fired it and sent to the duty doctor today. Naming what was seen is the whole claim — the referral decision is a clinician's.
  • A request about somebody else's record is refused, in code. A hard pattern rule with no model anywhere in its path, so there is nothing for one to be talked out of. It is a refusal, not a routing decision, and the rest of the message is still answered.
  • Names and addresses never leave the browser. A local check runs on the message as it is sent — regex, a forename list and a token scan, no model and no network (lib/safety/identifiers.mjs) — and a name or an address it finds is replaced with [name removed] / [address removed] before the request is built, before the transcript is written and before anything is saved. /api/agent runs the same check on arrival, so the guard belongs to the endpoint and not just to the page. The reader is told what went, as a count and never as a quote. It redacts rather than blocking the send: making somebody retype a sentence in a hurry does not get the name out of the world. Dr, Nurse and Matron introduce a colleague, so those names stay, as do names in the practice directory — "which days is Dr Ahmed in" and "the number for Alison Wade" are the job. It does not run on the Coding mode, in the browser or at the endpoint — see the two paragraphs below.
  • What cannot be redacted still goes. The local check catches the shapes it knows, and it knows them because they can be recognised . An NHS number is ten digits and so is an order number; a date of birth is a date; "reg no 4471982" is a hospital number at one trust and a stock code at another. No word list separates those, so nothing stops them: there was a pre-send model check for them, and it was removed. Staff are told not to type them, and that instruction is the control.
• Answers go through a validation loop: each section must carry a verbatim quote that really appears in the source it names, checked in code against what the tools actually returned. Failures go back to the model once with the specific reason, and anything still unverified is dropped rather than shown.
• Provenance is explicit. Practice-backed sections carry an openable citation; anything from a web page is marked "from the web" with a link and never presented as practice policy; whatever the practice's material does not cover is stated plainly, with who to ask, rather than filled in from model knowledge.
• Which referrals go by email is read from the practice's own page, not from a list in the code. lib/templates/referrals.mjs carries a table of recorded referrals with their e-RS pairings, addresses and forms — and that table is a copy of the practice's list, which had already fallen behind it. "Dietitian" was on the practice's emailed-referrals page and had never been typed into the array, so "how do I do a dietitian referral" answered "not recorded in the practice's notes" about a referral the practice had written down. Worse than a gap, because a gap is visible. Now the model names what is being referred to (referralName — extraction, which it is reliable at) and code reads the Notebook: the page has to actually be a list of emailed referrals, and the name has to actually appear on one of its list lines. A prose mention on an unrelated page is not a listing and does not count. The card quotes the line it found and cites the page. A referral the practice adds to its own page is answerable the moment they save it. A recorded e-RS pairing still wins over list membership, being the more specific fact.
• Which form to open comes from PCIT's NEL Referral Tree, verbatim — in the Referral form mode, and nowhere else. The practice's own material answers how a referral is sent; the tree answers which form. It is the protocol inside EMIS Web holding every referral form in North East London — 533 of them, of which 247 are on a City & Hackney practice's tree — and it has no search beyond Ctrl+F. Ordinary Q&A does not read it: the referral card answers from the practice's own recorded pairings and its emailed-referrals page, and where those have nothing it says "not recorded in the practice's notes" and names the mode that searches the tree. That is a real cost, stated plainly — the tree is what turned four hundred-odd such cards into the name of a form — and it buys one thing: an answer is either from a document the reader chose or from the practice's own writing, never from a document that was merely to hand. In the mode, code looks the form up in lib/referrals/nel-tree.data.json, generated from PCIT's published article by npm run data:nel-tree. The form name is shown exactly as the tree lists it, and offered to copy, because it is a string somebody retypes into Ctrl+F and a name spelled nearly right finds nothing. Several matches are shown as several rather than resolved to one — "dermatology" genuinely is three forms. A form ticked for another borough only is named as another borough's, which beats silence: the alternative is somebody scrolling a menu for a button that was never there. The A form the tree has nothing for gets the honest "no form by that name" card, naming the document searched and the day it was captured. Availability is read by tick column, not by counting ticks — the flattened text of the source PDF gives ticks in order but not which of the five columns each sat in, so "Wider determinants of health questionnaire NEL" is Newham and Waltham Forest and nothing in the text says so.
• Which EMIS template records a contract is answered with the date it was true on — in the Contract template mode, and nowhere else. PCIT name a contract one way and the template that records it another, and there are 42 of them — the NEL Local Contract Specifications (lib/referrals/nel-contracts.data.json, the table lifted out of PCIT's PCCIF mobilisation Sitrep; cards name the specifications, which is what staff would recognise, not the bulletin). So "which template for the ADHD shared pathway" gets the template name verbatim, to copy. The build status beside it is the part that rots — it came off a daily bulletin which says of itself that the position changes through the week — so every card leads with "as at 28 July 2026", a status that is not "For Release" is shown as a warning to check rather than a fact to repeat, and PCIT's own number is on the card so checking is one call. A status presented as current weeks after it was written is worse than none: it is fast, it looks authoritative, and it is wrong.
• A referral the Notebook does not cover still gets a speciality and a clinic type. They are determined from the practice's own e-RS referral-types export (via SNOMED), filled into the e-RS card, and shown with what they were determined from — the concept, the list, the closeness of the match and the other close pairings — under a heading saying they are not recorded in the practice's notes and must be checked against the doctor's task. Only for a referral somebody is actually sending on e-RS: a referral arriving from a hospital, one already sent and being chased, a waiting time or a policy that merely uses the word gets no e-RS card and no referral steps (lib/referrals/scope.mjs).
• Slash commands say which card you want rather than leaving it to be worked out (lib/commands.mjs): /accurx (where the patient goes and the reason line, from one paste), /coding (a filing title), /practice (search the documents, no model at all), /form (a NEL referral form) and /template (the EMIS template that records a NEL contract). There used to be two more — /triage, which said where a patient went, and /appt, which wrote the reason line and the booking notes — and /accurx is both of them on one card, so they were removed rather than kept as half-answers beside it. A described symptom typed without any command still reaches the same triage card: that path never went through /triage.
• The kind of answer is chosen from the search icon, not typed. The magnifying glass at the left of the field carries a disc behind it and is a button (app/_components/ModeSwitch.jsx): pressing it opens the list of modes over the box — Q&A, AccurX, Coding, Referral form, Contract template, Practice documents — each named with the line saying what it does, and the armed one ticked. Nothing was added to the page to make room for it: the glass had always sat there costing 48px of the field and doing nothing when it was pressed, and the disc is what says a thing can be pressed. It is the same size as the ask button opposite, so the field is a box with a control at each end. The disc fills blue with a white glass whenever anything other than Q&A is armed, so a field about to answer out of the referral list cannot look like a field about to answer a question. Arrow keys walk the list, Enter takes a mode, Escape closes it. Two earlier controls are gone: a row of pills under the field, which was four buttons hanging off the dock for a choice left alone almost every time and had to appear and disappear with the cursor to stay out of the way, and before that a segmented track with a sliding thumb. /accurx is offered here, first after Q&A: it is the one the practice reaches for most — a pasted AccurX request answered with the route, the urgency and the reason line on one card — and hiding the command somebody new to the desk would most benefit from finding was the wrong trade for a shorter list. Coding is offered too, and was /document. It was hidden on the argument that the people who file letters do it by habit and a habit needs no advertising, which quietly meant an everyday answer was reachable only by somebody who had already been told it existed. It is a mode now, named for the helper that does the same job at /coding, and the old spelling still resolves: typing /document reaches it, is offered under the Coding row while it is being typed, and is rewritten to /coding in the field, so the habit teaches the new name instead of being broken by it. It is also the one mode nothing checks for patient data — neither the redaction nor the screen — because what is pasted into it is a letter about a patient by definition. See the guards above. The strip above the field carries only the send bar and the "Copied" line, and nothing was added to the header or the footer. Typing "/" still works and still wins over the disc, being the more specific thing the reader just did. The disc wears the armed mode's own icon — a sheet of lines for Form, two sheets for Template, a speech bubble for AccurX, a folder for Coding, a book for Practice, the magnifying glass for Q&A — and the same glyph is drawn beside each name in the list, so which mode is armed is legible at a glance rather than inferred from the disc turning blue. , across a reload as well as across a message (). It used to last exactly one message; three referral forms are three questions, and re-arming the picker between each one was the friction the picker existed to remove. The failure modes are not symmetric — a wrong says honestly that no list has such an entry, while a wrong renders a confident triage card with a destination and an urgency for a question that was never about a patient — so what pays for a mode that stays put is that it cannot be missed and takes one key to drop: the icon on the disc, that mode's own placeholder wording, and . A question asked with a mode carries in the transcript, because typed into the box stays in the reader's own words for ever and choosing the mode with a button would otherwise leave nothing on screen explaining which list the answer came from.
• /form and /template answer from a list, with no model anywhere in the path. The reader has already said which of the two Primary Care IT lists they want, and the rest of the line is the query, so the turn is a ranked string match against a file in this repository: no model call, no tokens, no network. /form suspected skin cancer names the referral form; /template NEL Housebound Winter takes a template's name and answers with the contract specification it sits under, which is the direction staff need — the template name is what is written on the task, and the specification is what the contract is called in every other conversation about it.
• The lists are searched by what was asked for, not by how it was asked. Both lookups raise the bar every word has to clear as more words are typed — which is what stops one weak token dragging back a confident wrong form — and that rule was counting the words doing the ASKING too. "Which template for ADHD" is four words about one, and the three that name nothing put the bar at 200 for the one real answer, worth 108, so the card said no contract had that name. lib/referrals/ask.mjs drops the asking words ("which", "do I use", "please") and the words naming the document itself ("form", "template", "referral") before either list is searched or judged. It never drops anything clinical, and it can only lower the bar, so a query that found its row before still finds it.
• The answer is a template, and a template holds dozens of things. Reception ask in the words of the job — "B12 injection", "dressing change", "ear syringing" — and none of those is written on the specifications, because a template is a page set, not a form: the job is inside one of them. So a miss, and only a miss, runs a web search on how the task is done in North East London and asks a model which of the 37 templates the document names is the one to open (lib/agent/contract-intent.mjs). "B12 injection" comes back as OneTemplate NonPrescriber (Treatment Room page), with what that template records underneath it as the evidence. The model picks a name; it never writes one: the pick is thrown away unless the template is on the document character for character, and the contract, if it named one, is one that template actually records — so a half-remembered "OneTemplate Nurse (B12 page)" yields no template rather than a wrong one, and a right template under a wrong contract loses the contract, not the template. "TBC" and "N/A" are how the document says there is no template, so neither is ever offered as one to open. The card leads with the fact that it was worked out rather than looked up — open it and check the entry is there — and lists the pages that were read. Two more things make it hold up. When the model will not choose, the names the search itself used go back through the document's own matcher, so "Wound care service" off the ICB's page reaches "Simple Wound Care Service" and that row's own template, with no model in the path. And when nothing on the document fits at all, the card names Primary Care IT's own pages about the task.
• What is ON each template, from PCIT's four OneTemplate page specifications (lib/referrals/one-templates.data.json, built by npm run data:one-templates from the documents in rag/sources/). The contract list answers for 42 commissioned specifications and nothing else, which is a small part of a day: a firearms request, an ambulance, a loaned crutch, a sick note, a smear, hay fever — none is a contract, all are pages Primary Care IT publish, and every one of them used to come back "no contract by that name". Contract template now searches the contract list first — where a contract answers, the reader gets the build status and the capture date only that document can give — and the page specifications second, which answer with the page, the template carrying it, the launcher that opens it (the F12 button) and, where PCIT wrote one, the line saying what the page records. The heading comes with it: PCIT nest their lists, so "Injections" is not a page — it is an entry on the Treatment Room page of OneTemplate NonPrescriber — and the card gives the whole route (press this launcher, open that template, then that page) rather than a template name to go scrolling through. The contract card gets the same treatment: the page in its brackets ("OneTemplate NonPrescriber (Treatment Room page)") is resolved against the page lists and the card shows what is on that page, so the reader can see the thing they came to record before they open anything. Naming a template answers with its whole page list. The page card carries no status and no contract area, because a page list says what exists, not whether the work is paid for or how far a build has got — claiming either from the wrong document is exactly the blur this splits apart. 12 templates, 320 pages, and the same date-stamped honesty as the contract card.
• One document each, named in the mode. lib/templates/lookup-command.mjs is the whole scope of both commands and states it once: Referral form reads Primary Care IT's NEL Referral Tree introduction & document list (EMIS Web), and Contract template reads Primary Care IT's NEL Local Contract Specifications. Neither reads the practice's Notebook, neither falls through to the other's document, and neither calls a model. A miss is reported as a miss, on a card that names the document searched and the day it was captured — the one exception being the intent lookup above, which reads the web to pick a row of the SAME document rather than to answer from somewhere else. The modes are named for their documents rather than for the thing being looked for — "Form" and "Template" told a reader nothing about where an answer would come from, and both were quietly reading more than they said: Contract template answered out of the Notebook, Referral form out of the practice's emailed-referrals page. A referral question asked in ordinary words reads the practice's own material and only the practice's own material — that is the router's path, and it is where the Notebook belongs.
• And the scope runs both ways. "One document each" says what the two modes may read; it now also says who may read those two documents — nobody but those two modes. Ordinary Q&A used to have its own way into both: the referral card fell through to the tree when the practice had recorded nothing, and the router could choose a contractTemplate template of its own that searched the specifications. Both are gone — the template is out of the selection schema entirely, so the model cannot ask for a document it is not allowed to read, and the prompt says which mode does hold it. The two lists answer North East London's questions (what forms exist, what the ICB commissions), which are not this practice's questions, and blending the two behind an ordinary question is what made an answer impossible to place.
• /accurx answers both halves of an AccurX request on one card (lib/templates/accurx.mjs): where the patient goes, and the reason line to copy into what gets booked. Reception reads the request once and needs both, so asking for them separately meant pasting the same message twice — and the second paste is the one that does not happen when the phone rings. Neither half is new: the routing is the triage card, run through the practice's own order top to bottom over the destinations in lib/triage/destinations.mjs, and the wording is the reason line and booking notes under the rules in lib/templates/writing.mjs. What the command decides is order. Ordinarily the destination and the reason line sit together at the top, because they are the two things that leave the card. On a card that ends in an emergency — a red flag, cauda equina, an eye going straight to Moorfields — the wording drops its Copy, moves below everything the routing card has to say, and is renamed the handover note: nobody is booking an appointment off "interrupt the duty doctor now". Which of the two it is comes from meansNow in lib/templates/route-card.mjs, next to the destinations it judges, so the two cannot drift apart.
• /accurx also says who to book it with, when the message says somebody has already dealt with it (lib/templates/accurx.mjs, rules in lib/templates/writing.mjs). Patients say this themselves and say it in passing — "I saw Dr Okafor about this in July", "the nurse gave me cream last month", "I was told to come back if it did not settle" — and it was going nowhere: the reason line drops it as narrative and the booking notes are about slots. The same problem twice is one consultation continued, and the appointment that helps is the one with the clinician who saw it last. So the card carries a third panel, laid out exactly like the reason line above it: who dealt with it, when, what came of it, and — where there is an appointment to book and it was somebody here — book it back with them. It never moves the destination, which is why the reading is asked for it after naming one: continuity is who, never where. A follow-up about the same knee still goes to the physio; it goes to the physio who saw the knee. The quote is checked with spanWithin like every other quote on the card, a panel whose words are not in the message keeps the panel and loses the quote, contact somewhere else (a hospital, a walk-in centre, 111) is named as history rather than as a booking, and the note says outright that this is what the message claims — nothing here has read the record. Nothing found renders nothing at all: an empty finding printed as "nothing says this has been dealt with before" is a negative nobody checked, which is the mistake the booking notes already made once.
• /accurx is read as well as matched (lib/templates/accurx-route.mjs). A patient wrote in after a recent miscarriage: severe daily headaches, swelling and pain in both legs, shoulder pain, dizziness, bloods awaited. It came back as a physiotherapy appointment — and nothing was broken. "Leg pain" and "shoulder pain" made it musculoskeletal, "severe" made it disabling, and a disabling musculoskeletal problem is an FCP job. Every rule fired correctly and the answer was wrong, because the words were spread across four complaints and no regex can see that the swelling is in two legs or that "recent miscarriage" changes what all of it means together. That is not a tuning problem; another feature word finds the next gap. So the message is now read — one call, on its own model role (Settings → AccurX routing), which names where it goes and writes the reason line.
• The reading is done against the routing guide, and nothing else. Its prompt is docs/routing.md as data (lib/triage/destinations.mjs): every destination least-senior-first with what it covers and what it refuses, the practice's hard gates — no phlebotomy under 16, HPV to 24 and under, six weeks for travel jabs, health-check bloods before 1 pm — and the nurse-clinic rules. The Notebook is not in front of it. It was, and it was the wrong source for this one question: the Notebook is how the practice does things, the guide is where a task goes, and all the reading ever saw of the Notebook was a list of page titles to match a heading against — which is the failure mode the reading exists to replace. Removing it also took a database round-trip and about 3,000 prompt tokens off the one call the receptionist waits for.
• The reading is the only judgement, so the prompt says so. The pattern cascade came off this path when it told reception to interrupt a doctor over a chest pain the same message said was investigated at A&E last winter and turned out to be reflux. Nothing now catches what the reading misses and nothing retires what it raises, in either direction — so it is given the guide's own front-page rule instead: when you are not sure, route upward. The card shows the patient's own words that decided it, checked against the message first. No model, a timeout, or "unsure" leaves the card exactly as the patterns made it.
  • One call for the whole card. It was ten: one per destination asking whether the message was theirs, plus one writing the reason line. They had to be asked separately because nothing described the destinations in a form a single prompt could be handed — each check was told about its own service by name and nothing else. lib/triage/destinations.mjs describes them now, so the whole ladder goes into one prompt as data and one reader sees what nine saw between them, at a tenth of the calls.
  • What the reader is asked is load-bearing, and it is not "which service does this need". That question broke pt has sore throat: a GP genuinely can see a sore throat, so naming one is true and wrong — it takes the patient off the pharmacy that would have dealt with them. It is asked for the least senior service that can safely deal with the whole message, and every entry on the ladder carries what it refuses as well as what it covers, because refusing is the half that decides it. The GP entry says in its own words that a GP appointment is not the safe default here.
  • An eye emergency is its own destination, and it is a walk-in. The other two emergency cards mean somebody in the building stands up — fetch the duty doctor, call 999. This one means the opposite: nobody here does anything and the patient goes to Moorfields, so the hospital is named, with its address and telephone on the card and the fact that the eye A&E is open 24 hours and takes walk-ins — no referral, no appointment, nothing for reception to arrange first. It ties with 999 on the ladder and is listed above it, so a message that is both goes to the card that names the hospital. The minor eye service sits at the other end of the same list for everything Rose Opticians can actually see; the boundary between the two is on both checks.
  • The practice nurse and the diabetic nurse are on the ladder too, and because they rank below a doctor their answer is a note on the card rather than its destination: where the message goes is untouched, the note says the nurse does what is being asked for and quotes the patient saying so, and whether to book a nurse slot stays reception's call. It is never shown on an emergency card or beside the duty doctor.
• One message box, no modes to pick. The assistant works out for itself whether a message is a how-to question or an incoming patient request to triage (for example an Accurx online consultation) and replies with the matching shape — or the /accurx and /coding commands name it outright. The picker returns the template that fits, and the card is rendered in code from it:
  • answer — the step-by-step how-to described above.
  • triage — grounded action notes: an urgency band, the actions to take, who to route it to, safety-net red flags and an optional draft reply. This is care navigation / routing only — it applies the practice's own triage, duty-doctor and signposting protocols and never diagnoses or gives clinical advice.

Layout

• app/page.js — the chat UI (React). Persists chat + custom guides to localStorage.
• app/api/agent/route.js — the assistant's only answer path: the safety scan, the directory check, the one selection call, the template render, the prose fallback and the NDJSON event stream the chat reads.
• lib/templates/ — the templates: the selection schema and prompt (route.mjs), each card's renderer, the output tags a Notebook folder can carry.
• lib/routing/ — the confidence-scored router in front of the picker: the question normaliser (exact-match rung) and the trigger-phrase index.
• lib/agent/ — practice-answer.mjs (the /practice answer, quote-checked against the passages it cites), contract-intent.mjs, web-search.mjs (OpenRouter's web-search server tool, used by Instant Lookup).
• lib/guides/ — the built-in practice guides, categories and helpers.
• lib/ai/ — the streaming askAgent client (agent-client.js), the OpenRouter wrapper, quote matching, and the document-coding and medication helpers.
• rag/ — the document knowledge base: ingest pipeline, parsers (including vision image reading and PDF page rendering), and the runtime retrieval store. See rag/README.md.
• app/notebook/ + app/api/notebook/ + lib/notebook.js — the in-app Notebook: practice notes/instructions (with sub-notes) stored in Postgres and edited at /notebook. Every non-empty page is read fresh and supplied in full to every Q&A request (no rebuild or retrieval cutoff).
• lib/ai/context.mjs + rag/context/ — optional extra supplementary context (direct URLs, or committed files in rag/context/), reconciled into the same store. See rag/context/README.md.
• lib/contacts.js + lib/contacts.data.json — the deterministic telephone directory (exact numbers shown verbatim, never authored by the AI).
• lib/contacts-store.js + /api/contacts + — the practice's own contacts, as one list that can be added to. Opened with nothing typed, lists every one by category; a search runs over all of them first, with the CQC register below in a box of its own. Contacts are added, changed and removed from the same page (and a register row can be saved as a contact). They are the rows of kind that the bundled sheet is synced into; a save sets , which the sync leaves alone, and an added one carries . The chat's directory card and the identifier redaction's list of names read the same list, so a number added at the desk is answerable at once. Without a database the bundled sheet stands in, read-only.

Knowledge paths

The assistant keeps each source type predictable:

• Documents: found by PostgreSQL full-text (GIN) search, and served by /practice, which shows the passages themselves with no model in the path (lib/templates/practice.mjs). Unedited is not the same as unformatted: the words are exactly the document's, but they are laid out the way every other piece of text in the app is — a heading naming the document, then its own paragraphs and lists. They used to arrive as blockquotes with the whitespace collapsed out of them, which read as machine output and was harder to follow than the policy it came from. The claim that no model touched the answer is one grey line under the title rather than a banner across the card.
• Notebook: every non-empty page is loaded fresh from the live Notebook tables on every request and is never chunked or shortened. The model is given the page TITLES and returns one; the page is then rendered from the database as the practice wrote it, so a long process is never truncated to a snippet and never paraphrased.
• Contacts: a full-text search retrieves matching structured directory entries. Telephone numbers and emails are displayed deterministically rather than copied by the AI.
• Document and Notebook output still requires a server-verified verbatim quote.
• rag:ingest updates portable parsed artefacts; a persisted bundle fingerprint automatically reconciles only changed documents on the next runtime check.
• Source passages are analysed into exact-quote claims once per content hash. Candidate disagreements are reasoned over and only high-confidence, mutually exclusive claims appear as contradictions.
• /knowledge and /api/knowledge/** are deliberately available only from a loopback host in development; they return 404 in deployed production. The public app contains no link to this backend.
• /api/knowledge/sync idempotently reconciles the processed file bundle, Notebook and contacts. A legacy document/contact fallback keeps a fresh deployment available while its first canonical index builds in the background.

Configuration

Set these in .env.local (see .env.local.example):

Variable	Purpose
OPENROUTER_API_KEY	OpenRouter API key (server-side only).
OPENROUTER_AI_MODEL	Gone. The chat/vision model is a practice setting now: change it at /settings, where it is picked from the live OpenRouter catalogue and stored in Postgres (app_settings). Defaults to google/gemini-3.5-flash-lite. Should be vision-capable — the ingester reads images with it whenever the fast model cannot. A routing variant can be pinned to it there too — :nitro (fastest provider), :floor (cheapest), :free, :online, or anything else typed, e.g. openai/gpt-oss-120b:nitro — and a full id can be typed straight into the search box when the catalogue does not list it.
OPENROUTER_ANALYSIS_MODEL	Optional default for the fast role — the reading: the template picker, claim extraction, the medicine-name extractor, the ingester's image transcription. Wants a cheap model that calls tools reliably.
OPENROUTER_WEB_MODEL	Optional default for the web search role — searching the internet and reading a page for a phone number. A search-grounded model such as perplexity/sonar belongs here. Falls back to OPENROUTER_MEDICATION_MODEL, then OPENROUTER_ANALYSIS_MODEL.
DATABASE_URL	Neon Postgres. Powers the staff rota and the Notebook.
SUPPLEMENTARY_CONTEXT_URLS	Optional. Direct text/markdown/JSON URLs to inject as extra supplementary context (the Notebook is the main channel and needs no config).

Model roles

One turn is not one job, and it splits cleanly in two. Reading — searching the practice's material, skimming what comes back, choosing the next file to open, pulling the names out of a pasted list, transcribing a screenshot — is most of the model calls in a turn and none of its output. Deciding is the answer itself and every judgement in it: one call, and the only thing anybody reads.

So /settings picks the model the practice runs on — the reasoning role, which every other role falls back to — and two optional overrides sit beside it: fast, which runs the whole assistant turn (the template picker and the prose fallback) as well as claim extraction, the medicine-name extractor and the ingester's image transcription, and web search, a search-grounded model such as perplexity/sonar for the internet and for reading a page to lift a number off it. Each is stored in app_settings, so changing one needs no redeploy. There is no separate vision role: the ingester reads images with the fast model and falls back to the reasoning model if that one cannot see.

Every role is optional. Unset, it falls back to the environment variable that used to carry it and then to the reasoning model, so an install that has only ever chosen one model is completely unaffected.

The model does not write the answer. The assistant turn is one structured read on the fast role — which template fits, and its variables — and the card is rendered in code from what the practice wrote. So the fast role can be a small, cheap model without the answer getting any worse: the procedure on the card is the Notebook page, not the model's paraphrase of it. Only the prose fallback, taken when no template fits, is the model's own writing, and the card says so.

What a question costs

Each row on /settings shows its model's advertised rate — input and output per 1M tokens, live from the OpenRouter catalogue — and, underneath, the tokens a question really used on that role. A rate is not a cost: what a question costs is the rate multiplied by how many tokens this practice's questions use, and that depends on its Notebook, its documents and how staff word things. Two installs on one model differ by more than two models on one install.

So it is measured, not assumed. Every phase of every turn writes a row to ai_usage — role, model, tokens in, tokens out, no question text — and the page averages the last 30 days per question (not per call, so a repaired answer counts as the one question it was).

Measurements belong to the model that produced them. Tokens measured on one model say nothing about the next: a terser model writes fewer, a hungrier one reads more, and pricing yesterday's counts at today's rate reports a number that was never true of either. So a change of model shows nothing until it has been used — and changing back brings the old model's record back untouched, because nothing is ever reset or deleted. A cost per question, by model table lists every model that has answered anything, marking the ones in use.

A role nobody has run on its current model, or one whose model publishes no price, is excluded from the total and named as excluded. Unpriced models sort last in the table rather than cheapest — unknown is not $0.

Run

npm install
npm run dev        # http://localhost:3000
npm run build && npm run start

Knowledge base

npm run rag:status    # what's indexed / pending
npm run rag:ingest    # process new or changed documents in rag/sources/

See rag/README.md for the data standard, parsers, citations and storage notes.

Notes

• Administrative help for receptionists only — never clinical or medical advice. It refuses clinical questions and escalates possible emergencies (call 999 / alert a clinician).