Digital Receptionist: build handoff

Four tabs replace nine. Every call becomes a message someone owns. Bella never closes one herself.

Decided by MJ, 2026-09-13: the hybrid home from the kickoff; the receptionist is named Bella (a per-business field, Bella is the default); her open messages roll up into To Do's and the RC Dashboard; Today has two views of the same messages, List (default) and Triage (the pile, one caller at a time), and the Triage cards and the message drawer carry the caller's real documents (estimates, invoices, contracts, drawings, vendor bills) whenever the business already holds them. The prototype is the spec for layout, copy and behavior; this document is the spec for data and code. When they disagree, the prototype wins on words and layout, this document wins on data.

Wave 1 is a frontend regroup plus one table, one writer and one read. Wave 2 is the extraction step, the two loops and rendered PDFs. Wave 3 is audio and voice.

One state per message, derived deterministically, changed only by people (and Bella for three of them)

A message is a call (PhoneCall as normalized in app/features/receptionist/receptionist-logic.ts) plus, from Wave 1, one optional call_followups row. The state is computed in one pure function, deriveMessageState(call, followup, pendingActions, viewerTeamMemberId), unit-tested, used by Today (both views), All calls, To Do's and the Dashboard so they can never disagree.

Derivation for Wave 1 (deterministic, no model call)

state(call, fu, pending, viewer):
  if call.status == "in_progress"                            -> live
  if fu and fu.state == "closed"                             -> done
  if call.is_spam                                            -> spam
  if pending.some(p => p.status == "pending" and linksTo(p, call))   -> approval
  if fu and fu.owner_team_member_id and fu.owner != viewer   -> team
  if fu and fu.state == "open"                               -> needs
  if call.status == "voicemail"                              -> needs   (a listen and a call are owed)
  if unansweredQuestion(call.id)                             -> needs   (knowledge row status unanswered, source_call_id = call.id)
  if call.preferred_callback or call.urgency in ("high","urgent")   -> needs
  if hungUp(call)                                            -> needs   (try once today)
  if appointment(call.id)                                    -> booked
  if call.status == "completed"                              -> handled
  else                                                       -> needs   (failed / unknown: someone should look)

hungUp(call)  = duration_seconds < 15 and the transcript has no caller line (transcript is JSON or newline text, see normalizeTranscript)
kind(call)    = "Vendor" when the vendor skill fired (Wave 1: contact_type; confirm values) ; "Known customer" when contact_id (needs the Wave 1 writer, 5.1) ; "Unknown number" when caller_number is unnamed ; else "New caller"
afterHours    = created_at outside contractors.business_hours (profile), business time zone

Due time rules

Overdue is computed on read (due_at < now) everywhere, never stored, so the four surfaces always agree. Wave 2 adds a scheduled check only for the bounce-back and the optional hold-the-line nudge.

Transitions (who, from what, to what)

Each element, where its data comes from, and which wave it belongs to

Open the prototype next to this. The "Build notes" toggle in its review bar shows the real-vs-sample labels and the "where the old tabs went" map. Column names below are the worker's (src/db/001-consolidated-schema.sql:31-46 for calls); the v3 client normalizes them in normalizePhoneCall.

4.1 Today (#/home in the prototype; /dashboard/receptionist/index.html in v3)

4.2 The message, opened (drawer, ?open=<callId>)

4.3 All calls (#/calls; v3 history.html → calls.html)

4.4 Waiting on your OK (#/approvals; v3 action-log.html → ok.html)

4.5 Settings (#/setup/<section>)

4.6 Rollups: To Do's and the RC Dashboard (#/rollup)

4.7 Triage, the second view of Today (#/triage; index.html?view=triage in v3)

4.8 The document viewer (opens from the drawer and from the Triage card)

Reuse everything that exists, add one table, one writer and one read, widen three projections

5.1 What exists (verified, file:line in ripple-receptionist-worker/src)

5.2 The one new table (Wave 1): call_followups

Migration file src/db/YYYYMMDDHHMMSS-call-followups.sql claimed with pnpm make:migration "call followups" (scripts/make-migration.mjs; numeric prefixes are frozen at 685, INVARIANTS.md:56-58). One CREATE TABLE per table (INVARIANT #2), never edited after apply (INVARIANT #3, migration-immutability-check.yml). contractor_id TEXT NOT NULL REFERENCES contractors(id) as DOCS/architecture/ADDING_A_FEATURE.md:111-113 prescribes. Every mutation goes through appendAuditLog(env, contractorId, 'call_followups', id, row) (services/audit-log.ts).

CREATE TABLE IF NOT EXISTS call_followups (
  id                     TEXT PRIMARY KEY,
  contractor_id          TEXT NOT NULL REFERENCES contractors(id),
  call_id                TEXT NOT NULL UNIQUE REFERENCES calls(id),
  state                  TEXT NOT NULL DEFAULT 'open' CHECK (state IN ('open','closed')),
  owner_team_member_id   TEXT,                       -- team_members.id; NULL = unassigned (shows for the owner)
  due_at                 TEXT,                       -- ISO 8601; NULL = end-of-business-day rule on read
  outcome                TEXT CHECK (outcome IN ('reached','left_message','no_answer','booked','nothing_owed','handed')),
  note                   TEXT,                       -- latest "what happened?" text
  flags                  TEXT,                       -- JSON array of the six slip checkboxes
  handed_by_user_id      TEXT, handed_at TEXT,       -- last hand-off (Clerk user id)
  closed_by_user_id      TEXT, closed_at TEXT,       -- the human stamp; never written by the agent
  reopened_by_user_id    TEXT, reopened_at TEXT,
  attempts               TEXT NOT NULL DEFAULT '[]', -- JSON [{at, by, outcome, note}] so "called 1:15, no answer" survives
  created_at             TEXT NOT NULL,
  updated_at             TEXT NOT NULL
);
CREATE INDEX IF NOT EXISTS idx_call_followups_open ON call_followups (contractor_id, state, owner_team_member_id, due_at);

5.2b The documents read (Wave 1, no new table): GET /calls/:callId/documents

New file src/routes/calls/documents.ts, mounted on the calls router next to the recording route, gate requireFeature('nav.receptionist','view'). One read resolves the caller, then unions what the business holds on them. It stores nothing; it returns rows with an href into the source app and, when a stored file exists, a file the viewer fetches through the existing download route. Rows whose download route the viewer cannot pass are omitted (check docs.vault, execution.tasks, the drawings and finance gates with the same requireFeature matrix, routes/account-roles.ts:220), so the card never shows a document that 403s on click.

-- 1. who called (all within the tenant)
person   = people WHERE id = call.contact_id                       -- after the Wave 1 writer; fallback: phone match on caller_number
company  = companies WHERE id = person.company_id
projects = projects WHERE crm_source_call_id = call.id
        UNION projects WHERE customer_contact_id = person.id OR primary_person_id = person.id
        UNION projects WHERE company_id = company.id                -- only when person.company_id is set

-- 2. what the business holds on them (newest first, deleted_at IS NULL everywhere)
quotes             WHERE contact_id = person.id                     -> kind estimate|quote, file: contract_summaries via contract_summary_id (else null)
invoices           WHERE contact_id = person.id OR company_id = company.id  -> kind invoice, file: null (Wave 2 render)
contract_summaries WHERE project_id IN projects OR quote_id IN (the quotes above)  -> kind contract, file: /api/pm/contracts/:id/source
project_files JOIN project_folders f ON f.id = folder_id WHERE f.project_id IN projects AND f.contractor_id = :tenant
                                                                    -> kind file, file: /api/pm/documents/files/:id/download
drawing_sheets     WHERE project_id IN projects AND is_active = 1   -> kind drawing, file: the sheet image route (drawings.ts:378)
spec_books         WHERE project_id IN projects                     -> kind spec, file: /dashboard/specs/spec-books/:id/pdf
pm_invoices        WHERE vendor_contact_id = person.id              -> kind bill, file: the vendor invoice document (finance-ap)  (confirm the FK target)
pm_change_orders   WHERE project_id IN projects                     -> kind change_order, file: null (no document exists)

-- 3. the shape (amounts in cents; dates ISO; at most 40 rows, the client shows 8)
{ "callId": "...", "contactId": "...", "projectIds": ["..."],
  "documents": [{
    "id": "quote:q_123", "kind": "estimate", "title": "Kitchen remodel", "number": "EST-2041",
    "status": "sent", "amountCents": 1850000, "date": "2026-09-09", "by": "Dan Kowalski",
    "source": "estimates",                                  -- estimates | time_billing | contracts | project | drawings | specs | finance_ap
    "href": "/dashboard/estimates/detail.html?id=q_123",    -- the record page, always present
    "file": null | { "downloadPath": "/api/pm/contracts/cs_9/source", "contentType": "application/pdf",
                     "fileName": "Bath remodel contract.pdf", "sizeBytes": 419840, "pages": 6 }
  }] }

Notes. project_files has no tenant column: always join through project_folders.contractor_id as document-vault.ts:545-550 does. pages exists only on pm_invoices.pages and contract_summaries.page_count / spec_books.page_count; leave it null elsewhere and the client shows the size. The estimates list route has no contactId filter (routes/pm/estimates/index.ts:104-129) and the invoices list has none either (time-billing.ts:733), which is why this read queries D1 directly instead of calling those routes. Cache nothing: the read is cheap (indexed by contact and project) and must reflect a deletion immediately.

CI to expect: add the new route dir entries to regression-map.json and tests/perf/smoke-all-features.js (regression-sync.yml), refresh scripts/schema-baseline-migrations.json, run scripts/preflight-migration-sync.mjs, and rebase right before pushing (the immutability check diffs against main's tip). Update DOCS/business-rules/receptionist.md (the tab strip paragraph is now wrong) and DOCS/architecture/SCHEMA.md.

5.3 Wave 2: extraction, commitments, drafted answers, rendered PDFs, share links

CREATE TABLE IF NOT EXISTS call_commitments (
  id TEXT PRIMARY KEY, contractor_id TEXT NOT NULL REFERENCES contractors(id), call_id TEXT NOT NULL REFERENCES calls(id),
  kind TEXT NOT NULL CHECK (kind IN ('promise','statement')),
  text TEXT NOT NULL,                       -- the sentence as spoken
  due_at TEXT,                              -- parsed deterministically from the due phrase, business time zone; NULL for statements
  state TEXT NOT NULL DEFAULT 'open' CHECK (state IN ('open','kept','kept_late','released','scheduled')),
  kept_by_user_id TEXT, kept_at TEXT,
  source_kind TEXT CHECK (source_kind IN ('knowledge','calendar','rule','improvised')),
  source_ref TEXT,                          -- knowledge_base.id, rule key, or receptionist_appointments.id
  transcript_offset_ms INTEGER,             -- for Hear it
  corrections TEXT NOT NULL DEFAULT '[]',   -- append only: [{at, by, text, action}]
  created_at TEXT NOT NULL
);

CREATE TABLE IF NOT EXISTS document_renders (
  id TEXT PRIMARY KEY, contractor_id TEXT NOT NULL REFERENCES contractors(id),
  entity TEXT NOT NULL CHECK (entity IN ('quote','invoice')), entity_id TEXT NOT NULL,
  content_hash TEXT NOT NULL,               -- of the rendered input; re-render only when it changes
  r2_key TEXT NOT NULL,                     -- QUOTE_PDFS bucket (bound, unused today): {contractorId}/{entity}/{entity_id}/{hash}.pdf
  page_count INTEGER, byte_size INTEGER, rendered_at TEXT NOT NULL,
  UNIQUE (contractor_id, entity, entity_id, content_hash)
);

CREATE TABLE IF NOT EXISTS document_share_tokens (
  token TEXT PRIMARY KEY,                   -- 32 random bytes, base64url; the whole secret is the URL
  contractor_id TEXT NOT NULL REFERENCES contractors(id), call_id TEXT NOT NULL REFERENCES calls(id),
  document_ref TEXT NOT NULL,               -- the 5.2b row id, e.g. contract:cs_9
  sent_to TEXT NOT NULL,                    -- E.164
  created_by_user_id TEXT NOT NULL, created_at TEXT NOT NULL, expires_at TEXT NOT NULL,
  opened_at TEXT, open_count INTEGER NOT NULL DEFAULT 0, revoked_at TEXT
);

• Where the extraction runs: next to the only post-call model call that exists today, analyzeCallSentiment(...) at durable-objects/CallBridge.ts:1225 (defined services/sentiment.ts:125, model resolved by callLLM(env, 'receptionist.sentiment.analyze', ...) at sentiment.ts:134). Add a sibling extractCallOutcome under a new use-case key (for example receptionist.call.extract, swappable on /admin/models) that returns: a one-line "what they wanted", the list of what she did, the next step, and every sentence Bella spoke that commits the business (promise) or states a fact (statement), each with a due phrase and the knowledge article or rule it came from when the agent used one. Write the first three onto calls (new columns wanted, did_json, next_step) and the rest into call_commitments. Deterministic code parses the due phrase and marks improvised when no source was cited.
• Kept is written by the Done flow: closing a message with outcome reached marks its open promises kept (kept_late when due_at has passed). Never by the agent.
• Drafted answers: when saveQuestion writes an unanswered row, also draft a body from the nearest published article (same use-case key) into draft_answer. Publishing (PUT /knowledge-base/:id with status answered) sets published_by / published_at. The gate in elevenlabs.ts:478 increments use_count and sets last_used_call_id for each article it loads, so the next message can say "answered from your approved answer, Sep 15".
• Rendered PDFs for estimates and invoices: reuse renderContractPdf (services/pm/contract-render.ts: markdown to HTML to PDF through @cloudflare/puppeteer on the BROWSER binding, called at routes/pm/contracts.ts:315 and stored at :346). Add renderQuotePdf / renderInvoicePdf templates that produce the same layout the Estimates and Time & Billing detail pages print today, write to QUOTE_PDFS, record in document_renders, and have 5.2b return file for those rows (GET /calls/:callId/documents/:docId/file streams from the bucket with the same headers as the vault). Render on demand on first open, then cache by content hash. This is a judgment-free transform; no model call.
• Text it to the caller: POST /calls/:callId/documents/:docId/share {to} (edit, humanOnly) mints a document_share_tokens row (7 days), sends "{business} sent you {title}: {link}" through the SMS hub within the daily budget, and appends "Texted {title} to {caller}" to the followup attempts so it shows under What she did. GET /share/:token (public, no auth) checks expiry and revocation, streams the bytes with Content-Disposition: inline, increments open_count. Mirror the short-lived Academy media token at routes/dashboard/academy.ts:255 for the pattern. Never for vendor callers (the UI hides the button; the route refuses contact_type = 'vendor').
• Repeat caller: add prior_call_count_30d to the calls list projection (a correlated count on caller_number) or a GET /calls?number= filter.
• Bounce-back and nudge: a scheduled worker reassigns handed messages past due to handed_by, and (optional, gated by send_sms and the budget) texts the caller a hold-the-line message when a promise passes due with nobody assigned.

5.4 Cross-cutting

Regroup the existing pages, add six files, move one, keep every endpoint call

6.1 Routes and nav

6.2 Receptionist feature files (app/features/receptionist/)

6.3 Rollups

Every string, as decided. Plain English, no em dashes, no invented words.

The prototype's day is the seed. The prototype's checks are the acceptance test.

Acceptance checks, Wave 1 (each maps to a prototype step)

Open questions to settle in the first build session