ROADMAP.md — docforum-web

Update this file on every contribution that starts/completes/blocks an item below — same rule as the rest of the org, see AGENTS.md.

Status: Phase W1 built and connected to a live backend. The deployed Pages preview (https://docforum.github.io/docforum-web/) points at docforum-core's Render deployment; signup/login work end-to-end. One gap remains — see ARCHITECTURE_ESSENTIALS.md "Known gaps against the real API" (no refresh-on-reload flow).

Phase W1 — Shell & auth

• [x] Vite app wired up — real main.tsx/App.tsx, React Router, React Query, Zustand. npm run dev/build/test all work (verified).
• [x] API client service layer pointing at docforum-core (src/services/api-client.ts, auth-service.ts) — contract is a documented assumption, not confirmed, since docforum-core has no implemented routes yet. See ARCHITECTURE_ESSENTIALS.md "Known assumptions."
• [x] Signup/login screens, corrected to patient/doctor only for self-serve signup — facility accounts are admin-invited (PRD OQ-2), so there is deliberately no facility option in the signup UI. Login works for all three roles (facility users just don't self-register). 14 tests passing (npm test), including one that asserts facility is never offered at signup.
• [ ] Restore session on reload via POST /auth/refresh (single-flight refresh, one retry on 401, RequireAuth waits for boot refresh). Tracked as issue #9 (Medium, 150 pts).
• [ ] Not done: any integration test against a real docforum-core instance. Tracked as issue #12 (High, 200 pts) — an end-to-end smoke test against a throwaway docforum-core backend.
• [ ] ESLint + lint step in CI. Tracked as issue #11 (Trivial, 100 pts).
• [x] Deployed as a UI preview to GitHub Pages on every push to main (.github/workflows/deploy-pages.yml) — see ARCHITECTURE_ESSENTIALS.md "Deployment". Not a production deploy decision for the org; scoped to this repo's static frontend only.

Phase W2 — Patient core flow

Fully scoped into issues #1–#5, #18–#21, #26–#29.

• [ ] Doctor search (specialty + availability filter). Tracked as issue #1 (Medium, 150 pts) — built against a documented assumed API shape, since docforum-core has no doctor-list endpoint yet.
• [ ] Booking + intake form. Tracked as issue #2 (High, 200 pts) — must handle the 409 slot-taken response from docforum-core's real booking-concurrency guarantee explicitly, not as a generic error.
• [ ] My appointments list. Tracked as issue #3 (Trivial, 100 pts) — calls docforum-core's real, already-implemented GET /appointments/mine, no assumption involved.
• [ ] Referral accept/decline screen. Tracked as issue #4 (Medium, 150 pts) — assumed contract against docforum-core issues #5–#8, not yet merged there.
• [ ] Orders list + facility-selection screen. Tracked as issue #5 (Medium, 150 pts) — assumed contract against docforum-core issues #9–#16, not yet merged there.
• [x] Health profile editor: allergies, conditions and current medications. Tracked as issue #18 (High, 200 pts) — assumed contract against docforum-core issue #59.
• [x] Dependents management for guardians. Tracked as issue #19 (High, 200 pts) — assumed contract against docforum-core issue #42.
• [x] Acting-for profile switcher: book and view records on behalf of a dependent. Tracked as issue #20 (High, 200 pts) — client-only UI state (Zustand), threads patientProfileId through API calls and query keys.
• [x] Guardian consent and age-of-majority handover screens. Tracked as issue #21 (High, 200 pts) — assumed contract against docforum-core issue #42.
• [x] Download my data: request, track and fetch a data export. Tracked as issue #26 (High, 200 pts) — assumed contract against docforum-core issue #40.
• [x] Account deletion flow with clear retention explanation. Tracked as issue #27 (High, 200 pts) — assumed contract against docforum-core issue #41.
• [x] Care thread timeline: one view from booking to results. Tracked as issue #28 (High, 200 pts).
• [x] Facility finder with a map and distance-sorted results. Tracked as issue #29 (High, 200 pts) — assumed contract against docforum-core issue #74.

Phase W3 — Doctor core flow

Fully scoped into issues #6–#7, with #45–#49 added as doctor core-flow features.

• [x] Today's appointments / intake view. Tracked as issue #6 (Medium, 150 pts) — foundation laid via the doctor dashboard's live queue (src/features/queue/).
• [x] Consultation screen (notes, outcome, referral/order issuance). Tracked as issue #7 (High, 200 pts) — sign-off & addenda UI built (src/features/consultation/).
• [x] Doctor live queue: start and complete visits, running delay with manual override and undo window. Tracked as issue #49 (High, 200 pts) — src/features/queue/, QueuePanel, optimistic start/complete with a 4s undo toast.
• [x] Doctor messages inbox across all patient threads. Tracked as issue #47 (High, 200 pts) — src/features/messaging/, DoctorInbox, UnreadBadge, unread counts, truncated PHI previews, oldest-unanswered-first sorting, filters, pagination.
• [x] Doctor command palette and keyboard shortcuts. Tracked as issue #46 (High, 200 pts) — src/components/CommandPalette.tsx, src/hooks/useKeyboardShortcuts.ts, shortcuts help dialog, input suppression.
• [x] Doctor practice insights: utilisation, no-shows and turnaround. Tracked as issue #50 (High, 200 pts) — src/features/insights/, DoctorPracticeInsightsPage, slot utilisation by week, no-show/late-cancel rates, referral turnaround, message response time; charts with accessible table alternatives; date range selector; small-sample caveats; doctor-only data (no peer comparisons).

Phase W4 — Facility core flow

Fully scoped into issues #8, #51, #52, and #53.

• [x] Facility staff accounts: invite, list and remove. Tracked as issue #51 (High, 200 pts) — src/features/facility-team/, FacilityTeamPage, owner staff invite by email with fixed roles, pending invites with resend/revoke, member removal with backend session revocation and last-owner protection, read-only staff view, and fulfillment queue action attribution (PRD §7).
• [x] Scan-to-verify orders with the device camera. Tracked as issue #52 (High, 200 pts) — src/features/order-verify/, OrderVerifyPage (/facility/verify), camera QR scanning via BarcodeDetector API with JS fallback, verified order states (valid, superseded, expired, fulfilled, not_eligible), instant jump into fulfillment queue, manual token entry fallback, camera permission and stream teardown, and 429 rate limit error handling.
• [x] Facility payout ledger with per-order escrow status and terms. Tracked as issue #53 (High, 200 pts) — src/features/payments/, FacilityPaymentsPage (/facility/payments), cursor-paginated ledger, escrow totals cards (held, released, refunded), BigInt-safe amount formatting for Stellar stroops across assets (XLM vs USDC), plain-language escrow terms with releasers and refund countdowns, approaching deadline warnings (< 48h), and Stellar Expert testnet transaction explorer links.
• [ ] Fulfillment queue. Tracked as issue #8 (Medium, 150 pts).
• [ ] Mark fulfilled/rejected, attach lab result. Folded into issue #8 above.

Phase W5 — Payments UI

Built — docforum-core Phase 5.5 shipped for real (custodial v1, its docs/adr/0004), so the two-layer blocker (escrow-escrow SDK → docforum-core → here) cleared. Every call from this repo goes through docforum-core's real API — hard rule 1 (no direct Stellar calls here) held throughout.

• [x] Wallet link screen (calls docforum-core API only, per ARCHITECTURE_ESSENTIALS.md hard rule 1 — no direct Stellar calls here). src/features/payments/components/WalletLinkForm.tsx, wired into FacilityDashboardPage — a facility links the Stellar address docforum-core pays out to.
• [x] Payment/escrow status display — not literally "on orders" (Phase 4's Prescription/LabOrder don't exist yet, same reason docforum-core's PaymentIntent.orderId stays opaque), but a real, functioning admin console instead: AdminDashboardPage at /admin (new route, admin-role-gated) lets an admin create a PaymentIntent and drive it through fund → release/refund, showing live status, on-chain escrow id, and transaction hash — every click a real API call to docforum-core, which makes a real Stellar testnet transaction underneath. Admin accounts are seeded/invited, not self-serve (PRD OQ-2, same as facility) — this page is real once such a session exists, same caveat as the facility dashboard already had.
• [ ] Link transaction hashes/escrows to the Stellar testnet explorer. Tracked as issue #10 (Trivial, 100 pts).

Phase W6 — Admin console

Admin-only screens beyond payments. Everything goes through docforum-core's admin API; admin accounts stay seeded/invited (PRD OQ-2).

• [x] Audit and access log viewer. Tracked as issue #71 (High, 200 pts) — src/features/admin-audit/, AdminAuditPage at /admin/audit. Two tabs: state-change events against docforum-core's real GET /admin/audit-events (docforum-core#43), and PHI access logs against an assumed GET /admin/access-logs (docforum-core#45, still open — the tab says so on a 404). Entity type/id, actor, action and date-range filters plus the page cursor all live in the URL; one 50-row page per request; entity links where an admin view exists (payment intents → /admin?intent=); client-side CSV export of the page on screen. The action filter is client-side within the loaded page, because the backend rejects an action parameter — a docforum-core API gap, see ARCHITECTURE_ESSENTIALS.md "Known assumptions — Phase W6".
• [x] Stuck referrals console: reassign or cancel with a reason. Tracked as issue #72 (High, 200 pts): src/features/admin-referrals/, AdminReferralsPage at /admin/referrals. Pending referrals past a 1/2/3/7-day threshold are listed oldest first with age, target specialty and stuck reason (no doctor, doctor inactive, loop flagged); loop-flagged referrals show their chain with the returning hop marked. Reassign offers only verified doctors in the target specialty (re-checked client-side, excluding the current and referring doctor) with 7-day availability; cancel tells the admin docforum-core notifies the patient. Both require a reason and send expectedUpdatedAt, so concurrent actions come back as conflicts and the queue refreshes. Built against assumed shapes: docforum-core#68 (admin referral operations) and #65 (loop chain) haven't landed. See ARCHITECTURE_ESSENTIALS.md "Known assumptions — Phase W6".
• [x] System health page: readiness, background jobs and recent failures. Tracked as issue #73 (High, 200 pts): src/features/admin-system/, AdminSystemPage at /admin/system. Overview tiles answer "is it broken?" at a glance (API readiness, background jobs, outbox dead letters), backed by a readiness-check list (required vs optional, so a Stellar RPC outage shows as degraded, not down), one card per job with last success, last failure, next run and an overdue flag for stalled jobs, and a recent-failures list with error messages. "Run now" asks for confirmation (Cancel focused) and shows docforum-core's result in the dialog: finished with item count, failed with the error, still running, already running elsewhere (409), or unconfirmed after a network failure. Everything refreshes every 30 s while the tab is visible and catches up when it's shown again; each source fails on its own, a failed poll never leaves a stale "Ready" on screen, and slow readiness answers are flagged as likely cold starts. Built against assumed shapes: docforum-core#104 (readiness), #100 (job runner) and #94 (outbox) haven't landed. See ARCHITECTURE_ESSENTIALS.md "Known assumptions — Phase W6".
• [x] Feature flags console. Tracked as issue #74 (High, 200 pts): src/features/admin-flags/, AdminFlagsPage at /admin/flags. Lists every flag with its state (on, rolling out, off), type, rollout percentage, role targeting and allowlist size, a plain-language "who it reaches" line, and who changed it last and when, taken from the audit trail. Search (key and description), state and type filters live in the URL. The switch and the edit dialog both go through a review step that shows each changed field before and after, the audience before and after, and the last change; turning a flag off is called out. Percentages must be whole numbers from 0 to 100, and allowlist entries must be user ids. Saves are optimistic. A failed save rolls back only that flag, never another save in flight, and the list refetches. expectedUpdatedAt turns concurrent edits into conflicts, and the dialog notices when the flag changes under it. Built against assumed shapes: docforum-core#132 hasn't landed. See ARCHITECTURE_ESSENTIALS.md "Known assumptions — Phase W6".

Phase W7 — Platform quality: reliability, accessibility, performance, testing

• [x] Mock API for local development (MSW). Tracked as issue #95 (High, 200 pts) — npm run dev:mock serves every endpoint the app uses through the normal service layer via src/mocks/: seeded obviously-fake fixtures, a dev-panel role switcher (patient/doctor/facility/admin), scenario toggles (empty states, forced errors), a latency slider, and a fixture reset. 26 handler tests drive the real src/services/ layer against MSW; CI fails if mock code ever enters a production bundle (npm run check:dist). Documented in CONTRIBUTING.md.
• [ ] Generate MSW handlers and fixtures from the backend OpenAPI spec. Tracked as issue #96 (High, 200 pts) — blocked: depends on docforum-core#112 (OpenAPI 3.1 spec generated from the Zod schemas), which is still open — there is no authoritative openapi.json to generate from yet. Do not fabricate one; see that issue.
• [ ] Storybook component library with interaction and accessibility tests. Tracked as issue #97 (High, 200 pts).
• [ ] Performance budget: route-level code splitting, lazy GSAP, and Lighthouse CI. Tracked as issue #99 (High, 200 pts).

Changelog

• 2026-09-09 — Roadmap created, carved out of docforum-core Phase 7 as part of the 3-repo org split.

• 2026-09-14 — Phase W1 implemented: Vite/React Router/React Query/Zustand wired up for real, auth service layer + login/signup screens + role-based route guards, 14 tests passing, npm run build verified. Corrected signup to patient/doctor only (facility is admin-invited per PRD OQ-2) — see ARCHITECTURE_ESSENTIALS.md "Known assumptions" for the provisional API contract this is built against.

• 2026-09-14 — Deployed as a UI preview to GitHub Pages (https://docforum.github.io/docforum-web/), auto-deploying on every push to main. Switched BrowserRouter → HashRouter for this (no server-side rewrite on Pages). Preview only — login/signup will fail since docforum-core has no live API.

• 2026-09-14 — Connected to docforum-core's new Render preview deployment: deploy-pages.yml now builds with VITE_API_BASE_URL pointed at it, and api-client.ts sends credentials: 'include' (required for the cross-site refresh cookie). Signup/login verified working end-to-end against the live Pages URL.

• 2026-09-14 — Visual design refactor (no functional/phase change): full design-token rewrite in global.css (typography, color, spacing, radius, shadow scales), Space Grotesk/Inter, a hexagon-plus-pulse-line logo mark, and matching CSS Module updates across Button/TextField/ FormError/RoleSelect/Layout. HomePage rewritten as a real landing page. Not visually verified in a browser this session — no browser tool was available (see chat). Typecheck/tests/build all pass; confirm the rendered result at the live Pages URL.

• 2026-09-14 — Installed Anthropic's real official frontend-design skill (~/.claude/skills/frontend-design/, verified byte-identical against both github.com/anthropics/claude-code and github.com/anthropics/claude-plugins-official — an unofficial third-party site the user also linked pointed at a frontend-design-2 skill name that doesn't actually exist in either repo, disregarded). Read its critique checklist and found the design pass above hit several of its named "generic AI-design" tells almost exactly: an ALL-CAPS eyebrow label, gradient-highlighted single words in the headline, a monospace face used decoratively on small badges, and a 3-card grid for content that's actually a sequence. Revised: dropped the eyebrow and the headline word-highlighting, replaced the feature-card grid with a connected "thread" diagram (book → refer → order → settle — the product's own core flow, genuinely sequential), dropped the unused IBM Plex Mono webfont. Saved the checklist to memory (frontend_design_tells.md) for future design work.

• 2026-09-14 — Properly installed frontend-design@claude-plugins-official via claude plugin install (the real plugin mechanism — supersedes the manual ~/.claude/skills/frontend-design/ copy above, which was removed). Also manually installed Leonxlnx/taste-skill's taste-skill skill at ~/.claude/skills/design-taste-frontend/ (npx/bunx skills add both fail in this environment — Node 20.10.0 lacks util.styleText, added in Node 20.12+ — so fetched the file directly instead; verified the repo/script/content first, same as the frontend-design checks).

  Applied that skill's process (brief inference → dials → solid palette → typography → layout) to a full redesign, per explicit direction: no gradients, solid colors, web3 × hospitality (not medical this time — read as warmth/welcome, not clinical). New palette is solid pine green (--color-accent, trust/value) + warm brass (--color-accent-2, hospitality metal + web3 store-of-value) over warm porcelain/espresso neutrals — replaces the teal/violet gradient pair entirely, in every component (Button, nav CTA, hero CTA, the logo mark, the thread diagram's connecting line — all were gradient-filled, none are now). Typography swapped from Space Grotesk/Inter to Fraunces (warm serif — the hospitality half) + IBM Plex Sans (precise grotesk — the web3 half), a more deliberate pairing than the previous tech-startup default. Hero layout switched from centered to left-aligned/editorial — taste- skill and the official skill both flag centered-hero-with-accent as the generic default treatment. Logo mark redrawn: was a filled hexagon with a literal medical pulse-line (too on-the-nose for "medical," and gradient-filled); now an outlined hexagon (hospitality threshold / web3 node) around a three-point connected path, matching the thread metaphor, ending in a solid brass point where the redesign puts "this is where value settles." Not visually verified in a browser this session (still no browser tool available) — typecheck/tests/build all pass; confirm the rendered result at the live Pages URL.

• 2026-09-14 — Applied gsap-core and svg-animations (installed earlier) to two places, deliberately not "everywhere" — motion stays restrained (trust-first territory) and tied to what the marks already represent, per both design skills' "spend boldness in one place" guidance:

  • Logo (Layout header, mounts once): the three-point path now draws itself in via stroke-dasharray/stroke-dashoffset (the svg-animations path-drawing technique), dots popping in as the line reaches them, GSAP-driven and timed.
  • HomePage thread diagram: connector lines are now real SVG <line> elements (were CSS-colored <div>s) that draw themselves left to right as the section scrolls into view — the diagram extends the same way the thread it represents does. Triggered by a plain IntersectionObserver (no ScrollTrigger plugin — not installed, core GSAP only), plays once. Hero headline/subhead/CTA also get one staggered fade-up entrance on mount — a single reveal, not scattered per-section effects.

  Both wrapped in gsap.matchMedia('(prefers-reduced-motion: no-preference)') — reduced-motion users get the finished state immediately, no animation, per the official skill's accessibility floor. Added gsap as a real dependency (+~29KB gzip to the bundle — 97KB → 126KB). Typecheck, all 14 tests, and build all pass. Not visually verified in a browser this session (still no browser tool available) — the animation-specific risk here is real (SVG geometry APIs, timing, matchMedia behavior are all much harder to fully trust from code review alone than static CSS was) — please actually look at this one before trusting it.

• 2026-09-14 — Thread diagram now loops continuously (explicit user request — overrides the "single reveal, not scattered/repeated effects" default both design skills recommend, which is fine per those same skills: "where the brief pins down a direction, follow it exactly"). The one-shot IntersectionObserver trigger became a gsap.timeline({repeat: -1, yoyo: true, repeatDelay: 1}): draws in (~1.7s) → holds fully drawn (~1.4s) → undraws in reverse (~1.7s) → pauses (~1s) → repeats. Still gated by prefers-reduced-motion (no animation at all, not just non-looping, for those users) and still only runs while the section is actually on screen — the IntersectionObserver now play()/pause()s the loop instead of firing once, so it doesn't spend cycles off-screen.

• 2026-09-14 — Loading UX pass, three gaps addressed:

  • Pre-hydration shell: index.html had nothing but <div id="root"> — blank white page for however long the JS bundle (~126KB gzip, now including GSAP) takes to download/parse/run. Added a static HTML/CSS-only loading shell (brand mark + "Loading DocForum…", pulse animation) inside #root, using var(--color-*, fallback) so it's styled correctly independent of the app's own stylesheet load order. React's createRoot().render() replaces it automatically — no cleanup script needed.
  • Cold-start-aware auth loading: docforum-core's Render deployment (free tier, docs/adr/0003-render-preview-deployment.md) spins down after 15 minutes idle — first request after that can take up to ~a minute. Added useSlowRequestHint(isPending, delayMs=4000) (src/hooks/, finally has real content — placeholder README removed): past 4s of a pending login/signup, shows "the server may be waking up... this can take up to a minute" instead of leaving a spinner with no explanation indistinguishable from "broken."
  • Button gained a proper loading prop (spinner + aria-busy, implicitly disabled) — new Spinner component (src/components/, functional motion exempted from the restrained-motion default since it communicates real state, but still slows under prefers-reduced-motion rather than freezing). Replaces manual disabled={mutation.isPending} text-only toggling on login/signup/logout buttons.

  New tests: Button.test.tsx (loading/disabled states), useSlowRequestHint.test.ts (timing behavior — real timers + small delays, not vi.useFakeTimers(), which hangs Testing Library's auto-cleanup in this environment). 21/21 tests, typecheck, and build all pass.

• 2026-09-14 — Added .github/ISSUE_TEMPLATE/bug_report.md (identical copy across all three org repos — see docforum-core's changelog for the sourcing note: a user-supplied bug-report structure plus drips.network's "Creating Meaningful Issues" guide).

• 2026-09-14 — Scoped the start of Phase W2 into three real GitHub issues (#1–#3): doctor search, booking + intake form, my appointments list. Two of the three (search, booking) are explicitly built against a documented assumed API contract — docforum-core's Phase 2 doesn't exist yet — flagged plainly in each issue rather than implied as already-working; the third (appointments list) calls a real, already-implemented docforum-core endpoint with no assumption involved. Booking's issue specifically calls out handling the 409 slot-taken response as a first-class case, not a generic error path — that response is docforum-core's actual double-booking-prevention guarantee (Phase 1) surfacing at the UI layer for the first time. Referral and orders screens intentionally left unscoped — not enough of a real contract to assume against yet (docforum-core Phase 3/4 don't exist). Phase W2 checklist above updated to link each item to its issue.

• 2026-09-14 — Scoped the rest of the frontend roadmap that has a real (even if assumed) backend contract to build against: five more issues (#4–#8) covering the rest of W2 (referral accept/decline, orders + facility-selection — now buildable since docforum-core opened issues #5–#16 for the referral/order/facility work they assume against), all of W3 (doctor's today view, and a deliberately large consultation screen issue that explicitly permits splitting into multiple PRs given it touches three separate assumed contracts at once), and all of W4 (facility fulfillment queue + status + lab-result attachment, folded into one issue since both bullets are one cohesive feature). Every one of these issues documents its assumed API shape in ARCHITECTURE_ESSENTIALS.md "Known assumptions" as part of its DoD — not yet done in this commit, tracked as part of each issue's own work, not this roadmap update's.

  W5 (Payments UI) deliberately left unscoped: it depends on docforum-core Phase 5.5, which is itself unscoped pending docforum-escrow publishing its SDK — two layers of "no real contract to build against yet," so no issue was opened for it. All checklist items above updated to link to their issues.

• 2026-09-14 — Replaced the placeholder .github/workflows/ci.yml (pull_request-only, echo "TODO", never once run — this repo's existing deploy-pages.yml was the only workflow that ever actually ran) with a real one: typecheck → test → build, on push to main and on PRs. Verified locally first (21/21 tests, typecheck, and build all pass) and confirmed green in Actions. Companion fix applied identically in docforum-core (issue #21) and, separately, already done in docforum-escrow — all three org repos now run their real checks in CI instead of a stub, done ahead of the docforum-escrow Drips Wave application so any repo a reviewer or contributor lands on looks actively maintained. No lint script exists in this repo's package.json yet, so this doesn't include one.

• 2026-09-15 — General workspace-audit fixes (applied identically across all three org repos, see docforum-core's changelog for the full rationale): added CONTRIBUTING.md (human onboarding — AGENTS.md is agent-facing); enabled branch protection on main (real CI check + 1 approval required to merge, force-push/deletion disabled, enforce_admins left false so the maintainer isn't blocked); added GitHub topics for discoverability.

• 2026-09-15 — Built Phase W5 (Payments UI) for real, now that docforum-core's Phase 5.5 shipped: added WalletLink/PaymentIntent types to src/types/models.ts (real, mirroring docforum-core's actual schema — not "assumed" like most of this repo's other types still are), src/services/payments-service.ts, and src/features/payments/ (hooks + WalletLinkForm, CreatePaymentIntentForm, PaymentIntentPanel). Wired WalletLinkForm into FacilityDashboardPage; added a new AdminDashboardPage at /admin (new admin-role-gated route) driving the full create → fund → release/refund lifecycle. Every call goes through docforum-core's API only — confirmed no Stellar/@docforum/escrow-sdk dependency was added here, holding hard rule 1. 6 new component tests (mocking payments-service, following this repo's existing SignupForm.test.tsx pattern) — 27/27 tests, typecheck, and build all pass. Not visually verified in a browser this session (still no browser tool available) — same disclosed gap as every other UI change in this repo's history; the actual end-to-end payment mechanics (fund/release/refund really moving testnet funds) are proven by docforum-core's own live-testnet integration test, which this UI calls through unmodified endpoints.

• 2026-09-26 — Opened issue #9 for the one remaining W1 gap (no refresh-on-reload), and fixed the stale auth-store.ts comment that said docforum-core hadn't picked a refresh-token transport (it's an httpOnly cookie). Linked issue #1 to its new backend counterpart, docforum-core issue #23.

• 2026-10-07 — Opened issues #10 (explorer links in the payments console), #11 (ESLint in CI) and #12 (end-to-end smoke test against a real docforum-core, the unchecked Phase W1 item).

• 2026-10-16 — Built Phase W2 patient features: dependents management (#19), acting-for profile switcher (#20), health profile editor (#18), and guardian consent/age-of-majority handover screens (#21). All four built against documented assumed API shapes (recorded in ARCHITECTURE_ESSENTIALS.md "Known assumptions"). New types in models.ts (Dependent, HealthEntry, ActingProfile), services (dependents-service.ts, health-profile-service.ts), Zustand profile store (profile-store.ts), feature folders (src/features/dependents/, src/features/health-profile/), pages (DependentsPage, HealthProfilePage, ClaimAccountPage), and routes (/patient/dependents, /patient/health, /claim-account). Profile switcher in header, acting-for banner on patient pages. Tests for every new component.

• 2026-10-16 — Built Phase W2 patient core flows: download my data (#26), account deletion with clinical retention explanation (#27), care thread timeline (#28), and facility finder with map and distance-sorted results (#29). Built against documented assumed API shapes in ARCHITECTURE_ESSENTIALS.md. New types in models.ts (DataExport, DeleteAccountResponse, CareThread, CareThreadStep, FacilityWithDistance), services (account-service.ts, care-thread-service.ts, facility-service.ts), features (src/features/account/, src/features/care-thread/, src/features/orders/), components (DataExportSection, DeleteAccountSection, CareTimeline, FacilityFinder, FacilityMap, FacilityCard), pages (AccountSettingsPage, AccountDeletedPage, CareThreadPage, FacilityFinderPage), and routes (/patient/settings, /account-deleted, /care, /care/:threadId, /patient/facilities). Strict privacy enforcement: transient in-memory location only (never persisted to storage or URLs). 15 test files and 62/62 tests passing.

• 2026-10-17 — Built Phase W3 doctor core flow (#45–#49): live queue with start/complete visits, running delay + manual override and 4s undo window (#49); doctor messages inbox with unread badge, truncated PHI previews, oldest-unanswered-first sorting, filters and pagination (#47); command palette + configurable keyboard shortcuts with input suppression and help dialog (#46); consultation note sign-off with append-only addenda (#45). New types/services/features for queue, messaging and consultation; wired into DoctorDashboardPage, Layout (unread badge) and routes (/doctor/consultation/:id, /doctor/messages). Updated ARCHITECTURE_ESSENTIALS.md "Known assumptions" with the Phase W3 assumed API shapes. Typecheck, build, and all non-pre-existing tests pass.

• 2026-10-18 — Built Phase W3 Doctor practice insights (#50) and Phase W4 Facility staff accounts with fulfillment attribution (#51):

  • #50 Doctor practice insights: private insights page (/doctor/insights) with weekly slot utilisation, no-show and late-cancellation rates, referral acceptance turnaround, and messages response time. Includes SVG charts paired with accessible semantic <table> alternatives, date range selector (presets + custom), clearly labelled small-sample caveats, and strict peer-comparison suppression (doctor's own confidential data only). Wired into DoctorDashboardPage, command palette (⌘K), and navigation.
  • #51 Facility staff accounts & fulfillment attribution: dedicated team management page (/facility/team) with member list, role assignment (owner vs staff), email invitations, resend/revoke pending invites, member removal with backend session revocation warning, and last-owner deletion protection. Enforced read-only view and action suppression for staff members. In the fulfillment queue (/facility), added action attribution display showing which staff member dispensed/fulfilled each order for PRD §7 audit trail.
  • Updated ARCHITECTURE_ESSENTIALS.md "Known assumptions" and ROADMAP.md. 24 test files and 112/112 tests passing; typecheck and build green.

• 2026-10-18 — Built Phase W6 (new section) audit and access log viewer (#71): /admin/audit with state-change and record-access tabs, URL-synced filters (entity type/id, actor, action, date range) and keyset cursor pagination (newer-page trail kept in history state so browser back/forward agrees with the pager), entity record links, entity-history/actor pivots, and formula-safe client-side CSV export of the current page. Audit events use docforum-core's real contract (#43); access logs are an assumed shape pending docforum-core#45. Admin nav gained Payments/Audit trail links; /admin?intent=<id> now opens a payment intent directly. Viewer never logs to the console (tested). 27 test files and 153/153 tests passing; typecheck and build green.

• 2026-10-18 — Built Phase W6 stuck referrals console (#72): /admin/referrals queue of referrals pending past an age threshold (URL-synced threshold and reason filter, oldest first, cursor "Load more"), loop-chain context for loop-flagged referrals, reassign dialog with a doctor picker limited to verified doctors in the target specialty (with availability, chain-member warning, ineligible rows hidden and counted), and cancel dialog with patient-notification notice. Both actions need a 10–500 character reason, send expectedUpdatedAt for conflict detection, handle 409/404 (someone else acted) by closing and refreshing, and link to the referral's audit trail afterwards. Admin nav and dashboard link to it. API shapes are assumed pending docforum-core#68/#65. 30 test files and 207/207 tests passing; typecheck and build green.

• 2026-10-18 — Built Phase W6 system health page (#73): /admin/system with readiness, background-job and outbox overview tiles, per-check readiness list (required/optional, duration, detail, cold-start hint), job cards (healthy, last run failed, overdue, running, never run; last success, last failure, next run), recent failures from the last 24 hours, and a confirmed "Run now" that shows the run's result in place (finished, failed, still running, 409 already running, unconfirmed). Polls every 30 s only while the tab is visible. 404s show as "not served yet"/"not exposed" rather than errors. Admin nav and dashboard link to it. API shapes are assumed pending docforum-core#104/#100/#94. 33 test files and 267/267 tests passing; typecheck and build green.

• 2026-10-18 — Built Phase W6 feature flags console (#74): /admin/flags lists flags with state, type, rollout bar, targeting, a "who it reaches" summary and last change (actor and time from GET /admin/audit-events?entityType=FeatureFlag, one request for all flags). Search, state and type filters are synced to the URL. The edit and quick-toggle dialogs share a review-then-confirm step (field diff, audience before and after, last change). Validation covers a whole-number 0–100 percentage and a UUID allowlist (max 500). Optimistic saves roll back per flag on failure, re-read the server's state afterwards, and handle 409/404 conflicts and mid-edit staleness. Admin nav and dashboard link to it. API shape assumed pending docforum-core#132. 37 test files and 335/335 tests passing; typecheck and build green.

• 2026-10-18 — Built Phase W4 Scan-to-verify orders (#52) and Facility payout ledger with escrow terms (#53):

  • #52 Scan-to-verify orders with device camera: dedicated verification page (/facility/verify) enabling facility staff to scan order QR codes via device camera or enter tokens manually. Uses native BarcodeDetector API with fallback; guarantees complete media stream track teardown on screen unmount/exit. Dispatches to POST /facilities/me/verify-order and cleanly displays all 5 result states (valid, superseded, expired, fulfilled, not_eligible) alongside minimal clinical order summaries. Valid results feature an immediate CTA to jump into fulfillment (/facility?orderId=...). Surfaces HTTP 429 rate-limit protection against enumeration.
  • #53 Facility payout ledger with escrow terms: dedicated payments page (/facility/payments) displaying held, released, and refunded totals for both XLM and USDC. Uses BigInt-safe math (formatStroops) for Stellar 7-decimal stroop precision. Renders cursor-paginated escrow ledger with plain-language terms (releaser rules and refund deadline countdowns) adhering to threat model T8. Prominently flags approaching refund deadlines (< 48h) on unfulfilled orders. Integrates direct deep links to Stellar Expert testnet explorer for funding, release, and refund transactions.
  • Updated ARCHITECTURE_ESSENTIALS.md "Known assumptions" and ROADMAP.md. 26 test files and 124/124 tests passing; typecheck and build green. Captured desktop and mobile screenshots into screenshots/.