Source: ddx-documentation/features.md
Functional view of the workspace: pages and capabilities per audience, each row citing the route file it lives in. Technical view: [shell-tree.md](/en/docs/shell-tree), [patterns.md](/en/docs/patterns), `api/openapi.json`. Every route below is a file today; a page that is not listed here has no route. Path prefix for the **File** column: `ddx-web/src/app/[locale]/`. `<P>` = `(app)/portal/[orgSlug]/[role]`. Every page is locale-prefixed (`en`, `de`, `fr`, `es`; strings in `ddx-web/messages/<locale>/`). ## 1. Roles The portal URL is `/{locale}/portal/{slug}/{role}` (ADR 0003). `slug` is the org slug. `role` is a portal role, not an org role: | Portal role | Who lands here | Source | |---|---|---| | `staff` | org members with role `staff` | `packages/ddx-contracts/src/read-models.ts` (`PORTAL_ROLES`), re-exported by `ddx-web/src/lib/auth/roles.ts` | | `member` | org members with role `member` | same | | `client` | org members with role `client` | same | | `partner` | reserved role slug, own nav (home + settings) | same | | `public` | the default: every member whose org role has no portal role — `org-admin` lands here | `normalizePortalRoles()` in `roles.ts`; comment in `portal-registry.ts` | A role that the session does not hold renders `forbidden()`. The role is gated once, in `PortalPage` (`allowedRoles: rolesFor('<nav item>')`); ddx-api still decides data access per request (org roles `super-admin` · `org-admin` · `staff` · `member` · `client`; `super-admin` is a platform role that acts as org-admin of the target org, ADR 0013). ## 2. Public site (no sign-in) | Capability | Route | File | |---|---|---| | Landing page in SiteShell | `/{locale}` | `(marketing)/page.tsx` | | Component gallery: browse every inventory entry, design-system page | `/{locale}/gallery`, `/gallery/[entryId]`, `/gallery/design-system` | `(app)/gallery/page.tsx`, `(app)/gallery/[entryId]/page.tsx`, `(app)/gallery/design-system/page.tsx` | | R&D docs rendered from `ddx-documentation/` | `/{locale}/docs/<path>` | `(app)/docs/[[...slug]]/page.tsx` | | Locale switch, theme (light/dark), density (compact · cosy · large) | header of every page | `ddx-web/src/components/site/SiteHeader.tsx` | | Platform branding: the header, tab title, auth panel and loader show the platform display name (per locale), logo, palette, font and illustration; anonymous read of `GET /platform/branding`. The `/auth` tab title uses the platform name too | every site and auth page | `ddx-web/src/components/site/SiteHeader.tsx`, `SiteAuthFrame.tsx`, `(auth)/auth/layout.tsx`, `ddx-web/src/components/providers/BrandingProvider.tsx` | | Home as one scroll story: a film-sequence hero (4 clips in turn: hero, consult, treatment, team) with the illustrative report, a count band (engine stages read `SITE_ENGINE_STEPS`, 5), two screen tours (see the motion row), chapter bands (facts, how it works, knowledge, capabilities, specialties, privacy, FAQ) and a close film band; no in-page anchor bar. The FAQ is visible text and feeds the FAQPage structured data. Phones play the clips too (muted, inline); reduced motion, Save-Data and a 2g/3g connection keep the poster, and a missing clip keeps the poster (`data-media="missing"`) | `/{locale}` | `ddx-web/src/components/site/home/{SiteHomeSections,SiteHomeMotionBands}.tsx`, `components/site/motion/film/{SiteFilmHero,SiteCloseFilm}.tsx`; `(marketing)/page.tsx` | | Marketing pages, 8 routes x 4 locales (en, fr, de, es) = 32 URLs: `/{locale}/engine`, `/knowledge`, `/reports`, `/specialties`, `/specialties/{dermatology,gastroenterology,cardiology}`, `/trust`, plus the home. Each page has one h1 on a film hero (its own clip, poster first), chapters, a FAQ where it applies, and a closing band. Engine, Knowledge and Reports use `SiteSegmentedTabs` (tab panels with an autoplay progress bar) and typed lines (`SiteTypewriter`); Knowledge and Reports also carry a screen tour. Every outputs page states that a qualified doctor reviews and decides; no outcome or accuracy number, no certification claim | `/{locale}/<route>` | `ddx-web/src/app/[locale]/(marketing)/{engine,knowledge,reports,specialties,trust}/page.tsx`, `specialties/[specialty]/page.tsx` | | Page families and diagrams: pages compose the `SitePage` wrapper (`image` and `closing` props) and the `SitePage*` families `Pipeline`, `MediaBand`, `Faq`, `SpecialtyGrid`, `ReportPreview`, with the flat block diagrams `SiteEngineFlowDiagram`, `SiteCardAnatomyDiagram`, `SiteCurationLoopDiagram`, `SiteTopologyDiagram` (shared `SiteBlockDiagram`, labels from `site-diagram-labels.ts`; engine-true per `findings/osprey-diagnosis-parity/`, planned parts in a dashed strip) and the `SiteReveal` scroll-in island (CSS, transform and opacity only, reduced motion shows the end state). Entries are listed in `inventory.md`. | marketing pages | `ddx-web/src/components/families/{pipeline,media,faq,specialty,report}/`, `ddx-web/src/components/site/diagrams/`, `ddx-web/src/components/site/motion/SiteReveal.tsx` | | Site motion parts: film (`SiteFilmHero`, `SiteCloseFilm`, `SiteVideoBackdrop`, sequence and gate hooks), screen tour (`SiteScreenTour`, `SiteScreenFrame`: camera, spot, ring, ripple over a real screen capture), `SiteCountUp`, `SiteTypewriter`, `SiteSegmentedTabs`. Styling is Tailwind 4 utilities and semantic tokens in the TSX plus three small anchored blocks `site-film`, `site-motion`, `site-tour` in `ddx-web/src/styles/component-utilities.css` (the one `@utility` home; no `site-neo` scope). Timing lives in `lib/site-motion/site-motion-timing.ts`. Reduced motion shows the final state: counts at final values, typed line complete, poster instead of video. Brief: `plans/osprey-public-site-neo/CSS-COMPLIANCE-BRIEF.md` | marketing pages | `ddx-web/src/components/site/motion/{film,tour,hooks}/`, `ddx-web/src/lib/site-motion/`, `ddx-web/src/styles/component-utilities.css` | | Imagery: 11 film clips at `ddx-web/public/site/film/` (each as boomerang `-loop.mp4`, `-loop.webm` and `-poster.jpg`; 16 MB in total, each file under 2 MB; poster-first, the video loads after the poster). They are the HMS Neo realistic clips copied unchanged; the clip-to-HMS table is in `ddx-web/public/site/film/README.md`. Scene stills in `public/site/img/` are the matching HMS posters (AVIF and WebP at 800 and 1600 px). Screen tours use 5 real Osprey screen captures (synthetic cases, no patient data) in `public/site/screens/<cockpit,report,studio,pdf,assistant>-{light,dark}.webp`; the assistant screen shows the assistant drafting a case and asking questions, and the doctor starts the run. Earlier prompts and estimate: `ddx-web/site-assets/film/{prompts,ESTIMATE}.md` and `ddx-web/site-assets/prompts/README.md`. Check: `tsx scripts/site-clips-check.mts --strict` in `ddx-web`, plus the `site-film` row of `deploy/scripts/preflight.sh` (fails on a missing or over-budget clip) | marketing pages | `ddx-web/public/site/{film,img,screens}/`, `ddx-web/site-assets/film/`, `ddx-web/scripts/site-clips-check.mts` | | Search and sharing metadata: `sitemap.xml` (the 8 marketing routes x 4 locales with hreflang; the gallery is not listed), `robots.txt` (allows `/`, blocks `/api/`, portal, platform and auth), a 1200x630 Open Graph image per page group (home, engine, knowledge, reports, specialties, trust) and locale, canonical and hreflang (en, de, fr, es, x-default), JSON-LD (Organization, WebSite, SoftwareApplication, FAQPage, and BreadcrumbList on every inner page). Base URL key `DDX_WEB_SITE_URL`; Search Console key `DDX_WEB_GOOGLE_SITE_VERIFICATION` | every site page | `ddx-web/src/app/sitemap.ts`, `robots.ts`, `(marketing)/opengraph-image.tsx`, `ddx-web/src/components/site/SiteJsonLd.tsx` | | Google Analytics 4 behind Consent Mode v2: all four consent signals start `denied`; the gtag script loads only after the visitor grants consent in the one cookie banner; a later decline sends `denied`. Active only when `NEXT_PUBLIC_GA4_MEASUREMENT_ID` is set | site pages | `ddx-web/src/components/consent/GoogleAnalytics.tsx`, `CookieConsent.tsx` | | Legal and trust pages, 7 routes x 4 locales: `/{locale}/about`, `/imprint`, `/privacy`, `/terms`, `/cookies`, `/accessibility`, `/ai-transparency`. One `SiteLegalDocument` renders each; text lives in the `legal` message namespace (all four locales); company facts come from `ddx-web/src/lib/legal/company.ts` (copied from HMS, unknown facts show the "to be confirmed" marker) | `/{locale}/<route>` | `ddx-web/src/app/[locale]/(marketing)/{about,imprint,privacy,terms,cookies,accessibility,ai-transparency}/page.tsx`, `ddx-web/src/components/site/SiteLegalDocument.tsx`, `ddx-web/messages/*/legal.json` | | Site header and 4-column footer: the footer renders `SITE_FOOTER_GROUPS` plus the legal links from `SITE_LEGAL_PAGES` (kebab route id mapped to a camelCase message key by `SITE_LEGAL_MESSAGE_KEY`); the cookie-settings control sits in the footer. The header (ported from HMS Neo) adds a shadow on scroll, an active underline, a compact locale and theme cluster and a mobile sheet; the footer sheet reads scoped `--token-*`. The site container `--site-max` is 90vw clamped between 1280 and 1920 px (`globals.css`). The About page has a Dudoxx AI HMS product-line section with an external link to https://www.dudoxx.com (4 locales). Open Graph is complete for 9 pages x 4 locales | every site page | `ddx-web/src/lib/navigation/site-registry.ts`, `ddx-web/src/components/site/SiteFooter.tsx`, `SiteHeader.tsx` | | Contact form protected by Cloudflare Turnstile (`SiteTurnstile` widget). `POST /public/contact` verifies the token in ddx-api and answers `403 TURNSTILE_REJECTED` on a failed check; verify fails closed. Env: web `NEXT_PUBLIC_TURNSTILE_SITEKEY`, api `DDX_API_TURNSTILE_SECRET_KEY` (set both or neither). ddx-api refuses a production boot without the secret; in development with no secret the check is skipped with one warning. The CSP allows `challenges.cloudflare.com` | `/{locale}/contact` | `ddx-web/src/components/site/{SiteContactForm,SiteTurnstile}.tsx`, `ddx-api/src/communication/contact/` | | Hero art: 8 new HMS-grammar illustration renders. Provenance: `ddx-web/public/site/illustrations/README.md`. Plan: `plans/osprey-public-site/_index.md` phase 2 | marketing pages | `ddx-web/public/site/illustrations/README.md` | | Unknown URL | any | `[...rest]/page.tsx`, `ddx-web/src/app/global-not-found.tsx` | ## 3. Sign-in and org selection | Capability | Route | File | |---|---|---| | Sign in (email + password, better-auth via the BFF) | `/{locale}/auth/login` | `(auth)/auth/login/page.tsx` | | Sign out | `/{locale}/auth/logout` | `(auth)/auth/logout/page.tsx` | | Pick an org when the session has none active | `/{locale}/auth/select-org` | `(auth)/auth/select-org/page.tsx` | | Pick an org when the user has several; a user with exactly one org starts in it (the session is created with that org active) | `/{locale}/auth/select-org` | `(auth)/auth/select-org/page.tsx`; `ddx-api/src/auth/auth.instance.ts` | | Create organization: a user with no org sees the create form (no dead end); a user with orgs can create another from a dialog. The creator becomes `org-admin` and lands on the branding wizard (`?onboarding=1`) | `/{locale}/auth/select-org` | `(auth)/auth/select-org/create-org-client.tsx`; `POST /orgs` | | Entry after sign-in: resolves org + member role, redirects to the role home | `/{locale}/portal` | `(app)/portal/page.tsx` | | Register, OTP, magic link, forgot / reset password, verify e-mail: pages exist; their BFF endpoints answer `501 unsupported` until a real backend exists | `/{locale}/auth/<name>` | `(auth)/auth/{register,otp,magic-link,forgot-password,reset-password,verify-email}/page.tsx`; `ddx-web/src/app/api/auth/*/route.ts` | | Unknown `/auth/*` URL | `/{locale}/auth/...` | `(auth)/auth/[...rest]/page.tsx` | ## 4. Portal — pages per role Nav items come from `ddx-web/src/lib/navigation/portal-registry.ts` (17 items). Columns show which portal role sees each item. All routes live under `<P>/`. | Capability | Route segment | staff | member | client | partner / public | File | |---|---|---|---|---|---|---| | Role home (dashboard) | `` | yes | yes | yes | yes | `<P>/page.tsx` | | Projects: list, search, filter, page; view modes table · cards · list (rows) · timeline · kanban (drag moves status along the lifecycle) · calendar (by period) · export via `?view=`; action bar with create, search, facets, group-by and density; bulk bar on selection (export selected, delete); sticky header and pager. A client sees only projects granted to them | `projects` | yes | yes (read) | grants only | yes (org-admin) | `<P>/projects/page.tsx` | | Project detail with tabs: Overview, Tasks, Attachments, Audit (chain verified pill), Access (grants to users and roles). Audit shows to org-admin and the project owner; Access to holders of `share` (org-admin, owner) | `projects/[id]` | yes | yes (read) | grant only | yes (org-admin) | `<P>/projects/[id]/page.tsx` | | Project print | `projects/[id]/print` | yes | yes (read) | grant only | yes | `<P>/projects/[id]/print/page.tsx` | | Own profile: view, edit (display name, pseudonym, motto), avatar and signature upload, print | `profile`, `profile/print` | yes | yes | yes | yes | `<P>/profile/page.tsx`, `<P>/profile/print/page.tsx` | | Organization: view, edit, logo upload, print. org-admin sees the `admin` projection (tax id, brand preset); other roles see `detail`; status is editable by super-admin only | `organization`, `organization/print` | yes (read) | yes (read) | yes (read) | yes (edit for org-admin) | `<P>/organization/page.tsx`, `<P>/organization/print/page.tsx` | | Members: roster (name, image, title, role; e-mail for org-admin only), member print | `members`, `members/[memberId]/print` | yes | yes | yes | yes | `<P>/members/page.tsx`, `<P>/members/[memberId]/print/page.tsx` | | Task detail (tasks live under a project) | `projects/[id]/tasks/[taskId]` | yes | yes (read) | — | — | `<P>/projects/[id]/tasks/[taskId]/page.tsx` | | Create project, wizard, edit | `projects/new`, `projects/new/wizard`, `projects/[id]/edit` | yes (write) | — | — | — | `<P>/projects/new/page.tsx`, `<P>/projects/new/wizard/page.tsx`, `<P>/projects/[id]/edit/page.tsx` | | Settings (section 5) | `settings` | yes | yes | yes | yes | `<P>/settings/page.tsx` | | Branding wizard: 5 steps (name per locale, palette, font, illustration, logo) plus a review, live preview of the draft, per-step skip, finish saves the changed keys at org tier. Opens after create-org; no nav row | `settings/branding` | — | — | — | yes (org-admin only; staff gets access denied) | `<P>/settings/branding/page.tsx` | | Workspace with resizable panels (P-workspace) | `workspace` | yes | yes | — | — | `<P>/workspace/page.tsx` | | Data table demo (fill mode, filters) | `data` | yes | yes | — | — | `<P>/data/page.tsx` | | Forms demo (creates tasks) | `forms` | yes | — | — | — | `<P>/forms/page.tsx` | | Realtime events view (Centrifugo hints and connection state) | `realtime` | yes | — | — | — | `<P>/realtime/page.tsx` | | Streaming AI text. Status: the ddx-api demo-stream route it posts to was removed in plan osprey-engine task 017, so the page fails loudly (404). NEEDS_REVIEW by the owner: retire or re-point it | `stream` | yes | — | — | — | `<P>/stream/page.tsx` | | Assistant (section 5d): chat workspace with model and effort pickers, projects, personae, attachments and voice. Nav id `assistant` (staff, member) | `assistant`, `assistant/projects/[projectId]` | yes | yes | — | — | `<P>/assistant/page.tsx`, `<P>/assistant/projects/[projectId]/page.tsx` | | Customize the assistant: Skills, Connectors (MCP), Plugins, Agents tabs; org scope switch for org-admin | `assistant/customize` | yes | yes | — | — | `<P>/assistant/customize/page.tsx` | | Assistant settings: Personal and Organization tabs for the 24 `assistant.*` keys (section 5) | `settings/assistant` (no nav row) | yes | yes | yes | yes | `<P>/settings/assistant/page.tsx` | | Old playground URL: redirects to `assistant` and keeps `?session=` | `osprey` | yes | yes | — | — | `<P>/osprey/page.tsx` | | Chat (threads, messages) | `chat` | yes | — | yes | — | `<P>/chat/page.tsx` | | Voice assistant | `voice` | yes | — | — | — | `<P>/voice/page.tsx` | | Media: library, detail, upload | `media`, `media/[id]`, `media/upload` | yes | — | yes | — | `<P>/media/page.tsx`, `<P>/media/[id]/page.tsx`, `<P>/media/upload/page.tsx` | | Call room | `room` (nav item `call`) | yes | yes | yes | — | `<P>/room/page.tsx` | | Schedule (calendar) | `schedule` | yes | yes | — | — | `<P>/schedule/page.tsx` | | Audio recorder | `recorder` (no nav item) | yes | — | — | — | `<P>/recorder/page.tsx` | | Document viewer, print layout | `documents/[id]`, `documents/[id]/print` (no nav item) | yes | — | — | — | `<P>/documents/[id]/page.tsx`, `<P>/documents/[id]/print/page.tsx` | Reading the table: `—` = the nav hides the item and the page renders `forbidden()` for that role. Staff sees every pattern demo; the access sets are `PORTAL_NAV` in `portal-registry.ts` and `PROJECT_WRITE_ROLES` in `<P>/projects/_islands/model.ts`. Portal chrome shared by every page above (the header and side nav show the tenant name and logo, see section 5b): header (org switcher with role badge, location crumb, ⌘K command palette, notification bell with unread badge, language menu, appearance menu for theme and density, help link, user menu), side nav (`expanded` · `collapsed` · `auto`), status line, footer status bar, mobile menu — [shell-tree.md](/en/docs/shell-tree). ## 5. Settings (unified, ADR 0014) One page, `<P>/settings/page.tsx`, one read: `GET /orgs/:orgSlug/settings/effective` through the BFF. The page renders what ddx-api returns; it never merges tiers. - **Tiers**: platform (stored in `PlatformSetting`, edited only by platform `super-admin`) → org (stored, edited by `org-admin`) → user (stored, edited by the user for their own value). Registry: `packages/ddx-contracts/src/settings.ts`. Guide: [settings.md](/en/docs/settings). - **Keys today** (`<scope>.<group>.<key>`): `portal.locale.default` (org + user) · `portal.locale.enabled` (org) · `portal.features.ai` (org; each org chooses; staff roles read) · `portal.notifications.digest` (org + user) · `portal.display.timeZone` (org + user) · `portal.display.themeMode` light · dark · system · `portal.display.density` compact · cosy · large · `portal.display.motion` full · reduced · `portal.display.textSize` sm · md · lg (type only, never row height; all org + user) · `module.demo-entities.viewMode` table · cards (per-module preference, org + user) · the five `portal.branding.*` keys (section 5b; org only, no user tier). The 24 `assistant.*` keys (model, effort, voice providers, voice id, turn detection, fallback order, default persona, default agent, custom instructions, tone, memory switch, file limits and kinds) are listed with tiers in [settings.md](/en/docs/settings) §Assistant keys. The STT provider, TTS provider and fallback order are org-tier only (org-admin edits; review 050 M1). - **Platform settings page**: `/{locale}/platform/settings` lists the platform tier and edits one key at a time (`GET /platform/settings`, `PATCH /platform/settings/:key`, `version` required, 409 on a stale version). Only platform `super-admin` may call it. A write fans out `settings.changed` (key + version, never the value) to every org. - **Appearance**: theme, density and motion read through `UnifiedSettingsProvider` and `useUnifiedSetting(key)`; the header menus write the user tier. - **What a member sees**: only the keys their org role may read, each with value, source tier and an `editable` flag. `client` sees 4 keys (no `portal.features.ai`). - **Open item**: `public`-persona access for org-admin is `NEEDS_REVIEW` (ADR 0014). ## 5b. Branding (tenant branding, ADR 0019) Five keys, `portal.branding.{displayName,palette,font,illustration,logo}`: platform default, org override, no user tier. Key table: [settings.md](/en/docs/settings) §Branding keys. | Audience | Capability | Where | |---|---|---| | Platform `super-admin` | Sets the platform branding default: display name per locale (en, fr, de, es), palette (`dudoxx`, `neutral`, `solace-grid`, `verdant-loop`), font pair, illustration, logo default. One key at a time, `version` required | `/{locale}/platform/settings`; `ddx-web/src/components/platform/templates/PlatformPageSettings.tsx` | | `org-admin` | Sets the tenant branding in the org settings page (branding section with live preview), or in the onboarding wizard right after create-org. Logo: platform, generated monogram or wordmark, or an uploaded image (PNG, JPEG, WebP) | `<P>/settings/_islands/BrandingSettingsSection.tsx`, `<P>/settings/branding/_islands/BrandingWizard.tsx` | | Every portal member | Sees the org name, logo, palette, font and illustration in the portal. An org that set no name or logo shows its own org name and uploaded logo, else a mark generated from the org name; never the platform name or logo. Other orgs and `/auth/select-org` keep the platform branding | `ddx-web/src/components/providers/BrandingProvider.tsx` (`PortalBrandingScope`) | | Anyone (no sign-in) | The site and `/auth` show the platform branding, read anonymously | `GET /platform/branding`; `ddx-web/src/lib/branding/platform-branding.server.ts` | Known gaps (ADR 0019): the home hero title (`home.title`) and `site.brand.home` label are fixed text; the first hard load after a palette change can paint the previous palette once; orphaned logo objects are not cleaned up. ## 5a. Debug overlay (dev aid) A Bug button in the header and `Alt+Shift+D` open a debug panel. It exists only when `NEXT_PUBLIC_UI_DEBUG` is on in `ddx-web/.env.local`. Detail: [debug-overlay.md](/en/docs/debug-overlay). ## 5c. Osprey playground (plans osprey-engine, osprey-playground-v2; now the Assistant, section 5d) Page `/{locale}/portal/{orgSlug}/{role}/osprey` now redirects to the assistant route (plan ai-assistant-platform task 020); the workspace described here is the assistant workspace (`<P>/assistant/_islands/AssistantWorkspace.tsx`). Roles with the nav item: `staff` and `member`. A `client` and the org-admin persona (`public`) have no nav row and get `forbidden()`. The engine and the router behind it: [osprey-engine.md](/en/docs/osprey-engine). Live transport: [realtime.md](/en/docs/realtime). | Capability | Behaviour | Where | |---|---|---| | Workspace layout (v2) | One full-height frame: session rail on the left, the thread in the centre, a resizable panel on the right. The document never scrolls; the thread has its own scroller. The panel can expand to 60 vw | `ddx-web/src/components/osprey/OspreyWorkspace.tsx`, `OspreyThread.tsx` | | Sessions and rail | New chat, debounced search, Pinned and Recents sections, a row menu (inline rename, pin, delete behind a confirm) and arrow-key navigation (one Tab stop). Delete is soft: the session leaves every list. A session belongs to one user in one org; open one with `?session=` | `OspreySessionRail.tsx`, `hooks/use-osprey-sessions.ts`, `ddx-api/src/osprey/` | | Titled sessions | Turn 1 gets a first-turn title at once; a one-line model summary refines it after the turn. A title the user typed is never overwritten | `ddx-osprey-engine/src/sessions/title.ts` | | Streaming answer | Answer text and reasoning stream token by token as parts with stable ids; text before and after a tool call are separate parts. An assistant footer offers copy, retry, time and a token usage badge | `OspreyAssistantText.tsx`, `OspreyReasoning.tsx`, `OspreyTurnActions.tsx` | | Work trace | One collapsed line per turn (live label while running, "Worked for Ns" after) that expands to the step timeline: LLM steps, tool inputs, tool results | `OspreyWorkTrace.tsx` | | Composer and Stop | Enter sends (IME-safe); while a run streams the send button becomes Stop and cancels the active run. A follow-up cannot be queued while a run streams | `OspreyComposer.tsx` | | Plan state | Plan nodes with live status, attempts, a version badge, progress, and the diff when the plan is mutated | `OspreyPlanCard.tsx`, `OspreyPlanPanel.tsx` | | Run graph | The panel's Run tab draws the run as a node graph: plan lanes show plan nodes and their `dependsOn` / container edges, react lanes show one LLM-step node per step with a leaf per tool call. Nodes carry an icon and a text status label (drafting, pending, running, suspended, succeeded, failed, denied, rewired, invalidated, skipped); a node opens its detail inline (inputs, output ref, bound tool, timings, attempts, approval binding) and Esc closes it. A Graph / List switch shows the same nodes as text rows. One collapsed "+N calls" node replaces the leaves of a finished step above the render budget | `OspreyRunGraph.tsx`, `-Node.tsx`, `-Detail.tsx`, `ddx-web/src/lib/osprey/run-graph.ts`, `run-graph-layout.ts` | | Plan build strip | Above the graph the build strip shows Drafting → Bound → Running → vN: each newly complete node appears while the planner drafts, the bind result marks each node `bound`, `unbound`, `approval gate` or `pinned`, and a rejected attempt marks its issue node with the reason before the retry. A version stepper shows each plan version with added, removed (dashed ghost), rewired and changed nodes | `OspreyRunGraphBuild.tsx`, `plan.bound` / `plan.rejected` / `plan.drafted.phase` | | Open the graph from a turn | Every work-trace row and every plan-card row carries an "Open run graph" button that opens the Run tab on that turn, and a step row click opens it on that step's node | `OspreyOpenGraphButton.tsx`, `OspreyWorkTrace.tsx`, `OspreyPlanCard.tsx` | | Cards and artifacts | Result blocks of 9 kinds (`kv-grid`, table, chart, timeline, form, calendar, markdown, code, mermaid); mermaid and code show as source text because no renderer package is approved. A large result shows as a chip and opens in the side panel with view, code and plan tabs; an unknown kind shows a visible fallback chip | `OspreyBlockRenderer.tsx`, `OspreyArtifactChip.tsx`, `OspreyArtifactPanel.tsx` | | Human approval (HITL), inline | The card sits at the suspension point of the turn. States: open, responded, denied, invalidated, expired. An approval is bound to one tool call and its argument fingerprint: if the call changes, the old approval is void and the page asks again. A form or clarify step shows a form built from the step's JSON Schema. The run resumes only on that explicit answer | `OspreyHitlCard.tsx`, `OspreyHitlForm.tsx` | | Failure card | A run that ends on a guard tripwire, provider error, timeout or other failure shows an inline card with the failure kind | `OspreyErrorCard.tsx` | | Long sessions | The page loads the newest 100 turns and offers "load earlier" at the top; the snapshot is compacted so a 500-turn session stays under 4000 rows and 2.5 MB | `OspreyThread.tsx`, `ddx-web/src/lib/osprey/reducer.ts` | | Client actions | The engine can ask the page to set the theme, open or close a dialog (`help`, `session`, `plan`, `artefact`), dock or undock a panel, open an artefact, navigate or show a notice. Only allow-listed types run; `client` cannot navigate; each action is acknowledged once per `actionId`, from every lane including plan. Toasts become an inline notice banner | `ddx-web/src/lib/osprey/client-actions.ts`, `packages/ddx-contracts/src/osprey-client-actions.ts` | | Dock and undock | Panels dock to the left, right or bottom rail, or float as windows | `OspreyDockPanel.tsx` | | Reconnect and reboot | After a dropped connection or an engine reboot the page resnapshots from Postgres and continues; evidence in `findings/osprey-engine/judge/` | `ddx-web/src/lib/realtime/reconciler.ts` | Components `OspreyChat` and `OspreySessionList` no longer exist (removed in plan osprey-playground-v2 task 018). Deferred in v2 (no task; source `plans/osprey-playground-v2/00-protocol-alignment.md`): AG-UI adapter endpoint (`POST RunAgentInput` to SSE) · AI SDK `useChat`-compatible BFF route · MCP Apps sandbox lane · follow-up / steer queue while a run streams (v2: composer is Stop only) · "always allow this category" approvals (needs owner and security review) · supervisor hook guards · observational memory · per-run thinking-level and model pickers (the v2 meta row is read-only) · error-diff lesson collector · memory compaction · `server.drainTimeout` · JSON-repair wrapper in `define-tool.ts` · RRF fusion and multi-vector Tool-RAG (future plan `osprey-tool-rag-v2`). Also open: a cancel of a suspended react approval leaves the Mastra durable snapshot suspended while the log says `run.cancelled`. Run graph — measured state (`findings/osprey-run-graph/judge/verdict.md`, 2026-11-16, not a clean sweep): the plan-lane rows pass (nodes grow while drafting, `data-node-status` equals the SQL status per node, keyboard and detail rows pass, the build sequence and the reject-with-feedback diff pass) and `ui-binding` passes. Three rows failed or are unproven and stay open: the react lane showed no data tool in the judge runs, so no `llm-step` or tool leaf reached the DOM (AC2 FAIL — a lane/catalogue exposure question, the fold is not implicated); the engine `plan-build-events` case `bind-failure` is model-dependent and flaked 2 of 3 runs (AC13, AC15 FAIL — the fixture's refusal depends on the draw); and no vitest spec was authored for the fold or the layout budgets (AC4, AC8), while the live/replay and long-session browser rows could not open a canvas (AC5, AC9) — all NOT PROVEN, tests are opt-in. Engine capabilities the playground exposes (as shipped, measured on a held-out set; see [osprey-engine.md](/en/docs/osprey-engine) §Measured results): - Turn routing to chat, react (tool loop), plan, clarify or resume lanes, in about 300 to 400 ms p95. - Plans compiled to durable workflows with approvals, retry, rewire and re-plan, and recovery after a reboot. - Tool use limited to 7 tools per model call, with permissions derived from the org role. **Below target.** Router accuracy on the held-out set is 0.778 against a 0.90 target (AC4 FAIL; the plan lane is 0.361). Tool recall@4 is 0.817 against 0.90 (AC8 FAIL). Both stay open for an owner decision. Open quality gap: a plan step can bind the wrong tool (a "create a follow-up task" step bound to `list_tasks` in one browser run), and a mutated plan can end a run without reaching the goal. The org-role permission map needs owner review. ## 5d. Assistant (plan ai-assistant-platform) Page `/{locale}/portal/{orgSlug}/{role}/assistant`. Roles with the nav item: `staff` and `member`. Engine and API detail: [osprey-engine.md](/en/docs/osprey-engine) §Assistant platform. Voice transport: [realtime.md](/en/docs/realtime) §Voice audio transport. | Capability | Behaviour | Where | |---|---|---| | Chat area | The section 5c workspace as a product page. The composer carries a model picker (the engine registry) and an effort picker (off · low · medium · high · max); both default to the effective settings. Thinking stays off unless raised | `<P>/assistant/_islands/AssistantWorkspace.tsx`, `ddx-web/src/components/osprey/OspreyComposerModelPicker.tsx` | | Turn actions | Edit a user turn, regenerate an answer, branch from a turn. Each opens a new session branch; the source session never changes | `OspreyTurnActions.tsx`; `POST /osprey/sessions/:id/fork`, `.../turns/:turnId/regenerate`, `.../edit` | | Session organisation | Folders (session groups), archive view, temporary sessions, share (same-org read-only snapshot), search over titles and message text | session rail; `/osprey/session-groups`, `PATCH /osprey/sessions/:id` | | Projects | A project holds instructions and linked files; its sessions use both. Page per project | `<P>/assistant/projects/[projectId]/page.tsx`; `/osprey/projects` | | Personae and custom instructions | Org personae (org-admin writes) and personal ones; a default persona setting; free-text "about me" and "how to answer" plus a tone. A memory switch turns saved memory off. Saved memories can be listed, added (one line, at most `assistant.memory.maxLines` lines of `assistant.memory.maxLineChars` characters; patient data is refused) and deleted | `/osprey/personas`, `POST /osprey/memories`, `/osprey/memories`; settings keys in section 5 | | Customize | Skills, MCP connectors (header secrets are write-only and shown as names only), plugin bundles and user agents, each at org or personal scope. The composer can run a turn on a chosen agent. Role `client` has no access | `<P>/assistant/customize/page.tsx`; `/osprey/mcp-servers`, `/skills`, `/agents`, `/plugins` | | Files | Attach images and documents to a turn, or link them to a project. Documents are indexed for retrieval (PDF, text, markdown, csv; at most the `assistant.files.maxBytes` limit, default 20 MiB); images go to a vision-capable model for that turn only. The uploader must be the caller; the org may restrict kinds | `POST /osprey/files`, turn attachments; engine file-RAG | | Live tools | Web search, news, deep research (Exa then Brave fallback), weather (Open-Meteo) and image generation (stored in the engine, shown from `/api/v1/osprey/blobs/:id`). A missing provider key fails with a readable error and invents nothing. Query text reaches the chosen search or image vendor | engine `src/tools/catalogue/` | | Voice | Voice mode in the composer: speak, see live captions, hear the reply, interrupt it (barge-in). STT and TTS vendors and their fallback order are set by the org admin; a member cannot change which vendor receives audio. First audio after end of speech measured p50 2.9 to 3.4 s, above the 0.8 s stretch and 1.2 s job targets (`findings/assistant-job/voice-latency.md`) | `ddx-web/src/lib/osprey/voice-socket.ts`, `ddx-web/src/components/osprey/hooks/use-osprey-voice.ts`; `/osprey/sessions/:id/voice-ticket`, `/osprey/voice/:streamId` | | Voice dock and screen (live validation) | While voice is live and the dialog is hidden, a strip replaces attach, input and Send: orb with level, a visible state label, one caption line, and Mute (aria-pressed), Full screen and End as one ghost / secondary button family. Full screen is one centred `max-w-prose` column (orb and state, captions, transcript with a speaker label per entry; Interrupt, Mute, End). The reply that was cut shows "Interrupted". The readable card shows only when the turn has cards, a plan or an approval. Below md the agent, persona, mode and model pickers sit behind one Options chip. Opening a panel is closed when compact voice starts | `OspreyVoiceMode.tsx`, `OspreyComposer.tsx`, `OspreyWorkspace.tsx`, `use-osprey-voice.ts` | | Answer rendering (live validation) | The answer well is flat and tonal in every status; lists hang-indent, blocks use one gap, links use the link ink. The stats chip reports output tokens over (duration minus first-token time). A suspended turn shows "Waiting for you" with no spinner or clock. An approval card shows a calendar event as "date time · label" and, when the engine sends `labels` on the approval binding, a human label per argument. A weather block can carry `focusDate` for the asked day. The current date is in the engine core context | `OspreyTurn.tsx`, `OspreyAssistantText.tsx`, `OspreyTurnStats.tsx`, `OspreyHitlCard.tsx`, `ddx-osprey-engine/src/context/assembler.ts` | | Deep-content document (live validation) | The document view offers "Download Word document" (DOCX only; PDF has no server renderer). The deep-content block opens its panel at 60vw | `OspreyDeepContentDocument.tsx`, `OspreyArtifactPanel.tsx`; `GET /osprey/deep-runs/:runId/document/export?format=docx` | Open findings (`plans/ai-assistant-platform/ac-sweep.md`): the UI never shows the `interrupted` state (F3); voice latency targets not met; unset boolean and number keys show Off or empty on the Voice tab instead of the inherited default (UI1); the crumb on the Customize page reads "Assistant › Assistant" (UI2). ## 5e. Assistant upgrade (plan osprey-assistant-v3) Additions to section 5d. Engine and API detail: [osprey-engine.md](/en/docs/osprey-engine). | Capability | Behaviour | Where | |---|---|---| | Tool labels | Tool cards, the run inspector, plan cards and approval cards show a translated label, an icon and a short argument summary instead of the raw tool id. Raw arguments sit behind a "details" toggle. MCP tools get a generic MCP label | `ddx-web/src/lib/osprey/tool-labels.ts`; `OspreyWorkTrace.tsx` | | Image generation and viewer | The model creates images through the router alias `OSPREY_IMAGE_MODEL` (live alias `dudoxx-image`). The viewer offers zoom and download. A block header no longer shows the block id. A video block with an invalid id shows a text fallback with a link to open it on YouTube | `generate_image`; `OspreyMediaBlocks.tsx`, `OspreyBlockRenderer.tsx` | | Image and document requests | Short requests such as "generate an image of ..." or "make me a Word document ..." (en, de, fr, es) route straight to the tool lane without an LLM routing call | `ddx-osprey-engine/src/router/rules.ts` | | MCP and skills in chat and plan | The chat lane can use the owner's approval-free (allow-listed) MCP tools; approval-gated tools stay on the react lane. The plan lane uses the owner's skills in the planner prompt; plans carry no MCP tools | `runToolMap`, `pickTurnSkills` | | Word documents | `generate_docx` builds a Word file in the shared Dudoxx document preset and shows a download card (title, size). PDF output reads the same preset | `OspreyDocxCard.tsx`, `PdfDocument.tsx`; blobs served at `/api/v1/osprey/blobs/:id` | | Event timeline | The artefact panel's Run tab shows an AG-UI event timeline (tool, status, offset and duration from engine timestamps) above the run inspector; the Code tab shows the block source | `OspreyEventTimeline.tsx`, `projector.ts` | | Voice captions and language | Voice mode sends the UI language to pin STT and reply language, shows a live transcript with word-timed reply captions, and highlights the side that is speaking | `OspreyVoiceMode.tsx`, `use-osprey-voice.ts` | | File explorer | One explorer lists files in the session Files tab and in a project: upload, drop zone, preview, download, delete. Deleting a document removes its search index entries; unlinking the last project link of a file, or deleting a project, purges files nothing else uses. Generated Word files can be downloaded, not deleted. A session-scope upload is not available | `OspreyFileExplorer.tsx`; `DELETE /osprey/sessions/:id/files/:mediaId` | | Consumption dashboard | Page `<P>/consumption` (nav item in every role's Account section): window picker (day, week, month, quarter), cost per currency, calls, input/output/reasoning tokens, a chart split by model or call kind. Members see their own usage; org-admins can switch to the organisation and see a per-user table; the platform super-admin sees a per-org table. An unpriced call shows "no price", never 0 | `consumption/page.tsx`; `GET /usage/summary|series|users|orgs` | | Price list | Page `<P>/consumption/prices`: per-alias rates, source, version and revision history. Only the platform super-admin edits (version lock, 409 on conflict). `dudoxx-image` has no price row yet, so its calls are unpriced | `consumption/prices/page.tsx`; `GET /usage/prices`, `PATCH /usage/prices/:alias` | ## 5f. Assistant UX overhaul (plan osprey-ux-overhaul) Additions to sections 5d and 5e. Setting detail: [settings.md](/en/docs/settings) §Default agent. | Capability | Behaviour | Where | |---|---|---| | Default persona and agent | A new chat starts on the effective `assistant.persona.defaultId` and `assistant.agent.defaultId` (user over org over platform). The pick is remembered with its session; a pick made on a new chat carries to the session that send creates; switching session re-seeds from the settings. The seeder sets both org defaults on a fresh org | `<P>/assistant/_islands/use-assistant-turn-actions.ts`, `use-assistant-turn-body.ts`; Settings page field "Default agent" | | Tool-call cards | Each tool call shows as a card with icon, label, one-line argument summary, state and duration; raw input sits behind a disclosure. Collapsed, calls show as compact chips. `ui_control` rows appear only when the turn fired a UI action | `OspreyToolCallCard.tsx`, `OspreyWorkTrace.tsx` | | Run details chip | The turn footer rests as Copy plus one time and token chip. The chip opens a popover with time, model, tokens in and out, first-token time, latency, tokens per second and cost, and a button to open the full inspector. Retry, edit, regenerate, fork and summarize sit in an overflow menu that appears on hover or focus (always visible on touch) | `OspreyTurnActions.tsx`, `OspreyTurnStats.tsx` | | Tool-derived suggestion chips | The empty state shows up to four suggestions, built from the tools of the selected agent (web search, document search, PDF, weather, image, date and time). Each row leads with its tool icon | `ddx-web/src/lib/osprey/suggestions.ts`, `OspreyEmptyState.tsx` | | Voice on a new chat | The composer voice and dictation buttons work before the first message: the composer asks the host for a session, then starts voice on it | `OspreyComposer.tsx`, `use-assistant-turn-body.ts` | | Header and rail | Header icons (copy, paste, Customize, Settings) carry tooltips; the compact rail buttons carry tooltips. The sidenav top shows the Dudoxx platform mark | `AssistantHeaderActions.tsx`, `PortalSideNav.tsx` | ## 5g. Diagnosis (plan diagnosis-engine) A per-specialty, self-hosted diagnosis assistant for doctors and their assistants. Decision record: [ADR 0021](/en/docs/adr/0021-diagnosis-engine); engine design: [osprey-engine.md](/en/docs/osprey-engine) §Diagnosis engine. Nav item `diagnosis` shows for staff (doctors), member (read only) and org-admin; a client sees none. | Capability | Behaviour | Where | |---|---|---| | Specialties | Dermatology, gastroenterology and cardiology ship as seed packs (12 disease cards each, evidence cited) | `ddx-osprey-engine/datasets/diagnosis/` | | Cases | A case is one patient (`single`) or a set of patients (`cohort`); lifecycle draft, active, disposed, archived; list with search, filters, views; the record link opens the case workspace | `<P>/diagnosis`, `<P>/diagnosis/new`, `<P>/diagnosis/[caseId]` | | Intake | Pseudonymous: findings with present / absent / unknown, age band, sex, free text. No name, birth date or record id | `DiagnosisIntakeForm`, `DiagnosisCohortIntake` | | Live run | Scoring is deterministic and replayable. The engine retrieves over the cards, ranks a differential and shows progress live | `DiagnosisRunPanel` | | Questions | When questions remain, the run pauses and shows the most informative questions; the doctor answers and it resumes, bounded by `maxRounds`. A cohort run does not pause | `DiagnosisRunPanel` | | Outputs | Report, standard guidance, checklist, orientation and scorecard (cohort: a cohort summary), each with citations and the doctor-review disclaimer; PDF download | `DiagnosisOutputs` | | Safety | A red flag pins must-not-miss diagnoses and raises urgency. When a safety check blocks or cannot run, guidance is withheld and a blocking banner shows | `DiagnosisSafetyBanner` | | Feedback | The doctor records agreement with the differential (top1 / top3 / top10 / missed); feedback is the only disposition | run outputs | | Card library | Browse cards and revisions per specialty | `<P>/diagnosis/cards` | | Curation | Platform super-admin only: review pending proposals (from doctor feedback or from the unattended curator), approve or reject. Approval publishes a new card revision only when the gold-set gate passes; a change that lowers must-not-miss recall is `gate_failed`. A folder proposal from the card author has no diff: the queue shows the authored card in a preview, and approval publishes the folder through the card-folder install seam (the reviewer act, no gold-set gate; reviewer differs from proposer) | `<P>/diagnosis/curation` | | Card author page | A doctor writes a card from a brief or upgrades an installed card, watches sources, parts and the partial card, resumes a failed run, previews the result and submits it as a proposal (`?run=<id>` reopens a run). Roles org-admin, staff, member | `<P>/diagnosis/author`, `DiagnosisCardAuthor` | | Unattended curator | A scheduled tick researches stale cards from card text only (no patient data) and files cited proposals; it never publishes. Off by default (`module.diagnosis.curatorEnabled`) | `ddx-api` curator scheduler, engine curator | | Ported specialties | Dermatology and cardiology come from imported IBIS packs (DERM 87 cards, CARD 74 cards; the 12-card seeds are superseded) via `osprey dx pack import-ibis`; decision record [ADR 0022](/en/docs/adr/0022-ibis-pack-reuse) | `ddx-osprey-engine/src/diagnosis/ibis-pack-*.ts` | | Treatments | Guidance lists treatment options with regimens per card; estimate values show an "estimate, not clinical evidence" banner | `DiagnosisOutputs` | | Drug safety plane | ATC-based checks; `blocked` or unknown context withholds dose, frequency and duration (fail closed); drug search `GET /osprey/diagnosis/drugs` | engine safety, `osprey-diagnosis-drugs` contracts | | Patient context | Conditions and context feed scoring and safety; missing context is unknown, never assumed | intake | | Overlays (CLI) | Per-tenant overlays: `osprey dx overlay list\|set\|off --tenant`; a disabled must-not-miss card stays | `ddx-osprey-engine/src/diagnosis/overlay-store.ts` | | Dx chat assistant | Doctors describe a case in chat; the assistant drafts the case, runs the core, answers what-if, explain and compare. The model writes no number: a grounding guard replaces any number the core did not return. Decision record [ADR 0023](/en/docs/adr/0023-dx-assistant) | `ddx-osprey-engine/src/diagnosis/`, persona "Dudoxx Dx" | | Knowledge map | Qdrant v2 (dense and sparse, entities); 3D proximity map per run and per specialty with exact cosine (layout approximate). Run map: radial proximity layout by default (distance from the case = the chosen metric; PCA and classical MDS are switches). Math views: 5 normalizations (raw, l2, centred, kind-centred default, whitened) remove the kind islands that raw embeddings show; 7 metrics (cosine default, dot, euclidean, angular, mahalanobis, knn-rank, snn); PCA component triples PC1-3 to PC8-10; case variants (combined, findings, context, per patient) with per-point component decomposition; seriated distance matrix (10-60 points); scree chart. Global map: normalization and PCA/MDS only, no metric. Measured: cold 2.2 s, warm 0.27 s. Not t-SNE or UMAP (stochastic, no global distance meaning). Settings `mapMetric`, `mapNormalization`, `mapProjection`, `mapMatrixSize`, `mapWhitenComponents`, labelled points (case, top hypotheses, a settable count of others; a point with no doctor-readable label is not shown), labels drawn in one overlay beside each ball. Detail panel for the selected point (type, cosine, probability, open card). Develop a card or finding to load its neighbours; collapse folds them again with no request. The table below the map mirrors it as a tree with the same develop and collapse. Settings `module.diagnosis.mapNeighboursPerKind` and `mapLabelCount`. The map page is a full-height layout from md; from lg it has a controls rail, the 3D stage and a details rail, and both rails collapse (a chevron stacked below lg). The 3D polar grid draws in the `--token-viz-guide` colour | `GET /diagnosis/runs/:runId/vector-map`, `GET /diagnosis/runs/:runId/vector-map/neighbourhood`, `GET /diagnosis/map` | | Card folders (CARD) | Cards `DDC-CARD-0023` and `DDC-CARD-0057` are installed at version 2.0.0 from reviewable card folders (`osprey-dx-card/1`); clinical review is pending. A card author writes a folder from cited web sources: a new card from a free-text brief, or an upgrade of an installed card (`dx cards author --queue` or `--card <CODE>`, or the author page). A run shows its sources, finished parts and partial card while it works, a failed run resumes from its checkpoint, and the end result is a PENDING folder proposal that a different reviewer approves; the author never installs or publishes. Settings `module.diagnosis.cardAuthorModel`, `cardAuthorSourcesPerCard`, `cardAuthorConcurrency` | `osprey dx cards install --card <CODE>`, `ddx-osprey-engine/src/diagnosis/card-folder-install.ts`, `ddx-osprey-engine/src/diagnosis/card-author/`, `POST /osprey/diagnosis/card-author/runs` | | Case dossier | Long cited document from run results; search queries are de-identified; a numbers judge checks every figure | `POST /diagnosis/runs/:id/dossier` | | Dx MCP server | `dx_knowledge_search`, `dx_card_get`, `dx_score_case`, `dx_drug_check` for other DDX products | `/osprey/mcp/dx` | | Self-curation | Producers (gap, estimate, calibration, pattern, doctor) file PENDING proposals only; reviewer differs from proposer; scheduled jobs are claimed once per window | `/diagnosis/proposals`, `/diagnosis/curator/miners` | | Cockpit v2 (plan osprey-dx-cockpit-ui) | Direction "Split Workbench", the only diagnosis UI (the legacy screens and the `module.diagnosis.cockpitUi` switch are removed). Screens: case list, new case, case cockpit, card library, card detail, card author, patterns, map, curation, quality. At 1440 px: command column, run strip, then two benches across one seam (doctor side: intake and questions; Osprey side: board and report). At 390 px: command block, doctor side, seam, Osprey side in one scroll. Design record: `ddx-web/DESIGN.md` "Diagnosis cockpit v2" | `diagnosis/_islands/v2/CaseCockpitV2.tsx`, `components/diagnosis-cockpit/` | | Command region | Red flags, must-not-miss pins, withheld guidance and the review disclaimer sit in one fixed column (1440 px) or one fixed, open 2 x 2 block on top (390 px). Never in a tab, drawer, popover or collapsed pane. The red-flag card is the only destructive tint of the screen; a blocked run shows in the run strip with a warning tone | `CockpitCommandRegion.tsx`, `cockpit-command-region.ts` | | Seven pane states | Every pane shows one of `loading`, `live`, `suspended`, `safetyBlocked`, `resync` (overlay), `failed`, `empty`, through one shared frame. Priority: failed, loading, safetyBlocked, suspended, empty, live | `CockpitPaneFrame.tsx`, `cockpit-pane-state.ts` | | Seam | A finding on the doctor side lights up the hypotheses and red flags it drove on the Osprey side. The seam line is 2 px at rest and full primary while linked | `SeamDrives.tsx`, `seam-link.ts` | | Mixed intake and fill-into-draft | The intake pane merges typed fields and the free-text story into one view. Typed values win; a differing extracted value shows as a conflict the doctor picks. A story read in the background fills INTO the open draft and never wipes it. A failed fill shows its reason and a retry. A same-text request on a live draft is a no-op. Route `POST /osprey/diagnosis/drafts/:draftId/fill` (202, body `{ text, context? }`); the draft record carries `intake` (origin and conflicts per field) | `IntakeMergeView.tsx`, `IntakePane.tsx`, engine `draft-fill.ts`, ddx-api `OspreyDiagnosisController`, BFF row `/osprey/diagnosis/drafts/:draftId/fill` | | Held items and Analyse | Items mapped by vector similarity stay held. The held list shows under the run frame before the first run; Analyse confirms the ready draft through the one draft board of the cockpit, so the ticks the doctor set enter the run | `RunPane.tsx`, `BoardActs.tsx`, `use-case-draft-board.ts` | | Board acts file mapping proposals | A concept switch, tick or untick on the board counts as a board signal. At the support floor (`module.diagnosis.boardSignalMinSupport`) it files one PENDING proposal of kind `mapping` (concept ids and counts only, proposer `system:board-signals`). Approval closes it as `approved` with no card revision and no publish; reject uses the normal path. Table `dx_proposal` gains the kind and `override_reason` (migration `sql/037`) | engine `curation/board-signals.ts`, `curation/proposals.ts`, `CurationV2.tsx` | | Curation gate result and override | The curation pane shows the gate result with readable diff lines. Approving a change whose gate failed needs a reason: without it ddx-api answers 422 `override_required` (keyed on the engine status and code, not on message text); with it the reason is stored as `overrideReason` on the proposal | `curation-v2.ts`, ddx-api `OspreyDiagnosisCurationController`, engine `DxUnprocessableError` | | Case assistant in v2 | The case chat stays. At 2xl (96 rem) and above the assistant is a resizable side pane; below 2xl a docked bar opens it as a bottom drawer. The header shows an act to open it while it is closed. A chat-made draft shows in the board pane (one draft board) | `CaseAssistantV2.tsx`, `case-assistant-v2.ts` | | Case header | One quiet row: `<case number> · <title>`, the specialty, the run status word. Below lg it scrolls away above the sticky command block | `CaseCockpitV2.tsx` | | Outputs screen (live validation) | The hypothesis table shows the top 10 plus rows at 1 % or more; the rest sits behind "N more below 1 %"; value, interval and bar sit on separate lines. Feedback lists 10 checkboxes plus confirmed picks, with a search box and a "shown of total" status. A safety banner names the red flags that fired (`redFlags` on the run status; runs made before this change show the banner as before) | `DiagnosisOutputs.tsx`, `DiagnosisSafetyBanner.tsx` | | Case list screen (live validation) | The list no longer shows a "Latest analysis" column (`latestRunId` is out of the `summary` projection; the `detail` and `admin` projections keep it) | `packages/ddx-contracts/src/descriptors/diagnosis-case.ts` | | Card library and card page (live validation) | The list is not windowed (it showed in a 384 px box), shows `Updated` as a formatted date and the specialty as a readable name. The card page uses the card title as h1 and last crumb, one h3 per body section (19 known keys, others humanised), `max-w-prose` sections, red flags as the rule label for the locale (raw key muted), and readable evidence links. The "Knowledge cards" eyebrow is removed. The per-specialty card count can read higher than the list for cards with no current revision (D-046; engine `gateway-knowledge.ts` counts a LEFT JOIN) | `DiagnosisCardLibrary.tsx`, `DiagnosisCardDetail.tsx` | | Map screen (live validation) | Point labels rank selection, then case, then posterior, hide on collision and flip left at the right edge; the polar grid faces the camera. The top list is titled "Most probable diagnoses". The table name cell wraps; the PCA scree sits in the side column. One "Distance settings" popover holds metric, normalization, hints, axes and variant. With no case the legend reads global (no "cosine to the case"). The global map draws every disease and pattern card point; the matrix lists the case and top hypotheses first. Global-map label and metric controls need `GlobalMapQuerySchema` changes (D-056, blocked) | `DiagnosisVectorMap*.tsx`, `ddx-osprey-engine/src/diagnosis/vector-map*.ts` | | Intake mapping (live validation) | Intake maps a lay phrase to a card concept through retrieval candidates and a two-way word match; the safety reason of a red flag is returned to the doctor. Open: a near-synonym finding can still be re-asked (D-040), and the must-not-miss rule has no catch-all marker (D-043) | `ddx-osprey-engine/src/diagnosis/knowledge-store.ts`, `retrieval.ts` | Not built: FHIR or EHR integration, paid external medical APIs, MDR certification, CSV cohort import, an overlay UI. The public site may stop labelling treatments "planned" (separate lane). ## 5h. Case Studio (plan osprey-case-studio) The diagnosis case workspace after the Case Studio plan. Same roles and nav item as section 5g. Engine side: [osprey-engine.md](/en/docs/osprey-engine) §Diagnosis engine, paragraph Case Studio. Names and numbers: [naming-constitution.md](/en/docs/naming-constitution) §6.5. | Capability | Behaviour | Where | |---|---|---| | Case number | Every case has a number `DX-<year>-<5 digits>` per organisation. Screens show `<case number> · <title>`; the list has a "Case number" column (search and sort). Technical ids are never shown to a doctor | `diagnosisCase` kernel field `caseNumber`, `diagnosis-case-title.ts` | | Patient context at create | The create form records medications (by ATC code), allergy classes, conditions, kidney and liver bands, pregnancy and breastfeeding. The title is prefilled with `<specialty> · <patient label>`, required, up to 120 characters. A readiness panel names the context fields still missing | `v2/CaseCreateV2.tsx`, `use-case-title-prefill.ts` | | Allergy class picker | Search the allergy classes and pick chips; the intake stores the class id | `GET /osprey/diagnosis/allergen-classes` | | Cohort context | A cohort keeps its own context per patient. The cohort read view shows each patient's context. The new-case form starts a cohort with one patient; more patients are added after the first save (Edit intake, Add patient) | `DiagnosisCaseSummary.tsx` | | Cohort cap | The cap is the effective setting `module.diagnosis.cohortMaxPatients`. A start over the cap is refused (400) and the banner reads "Too many patients. The limit is N." | `DiagnosisCohortIntake.tsx` | | Specialty on the run | The command bar shows the specialty and the run button reads "Analyse as <specialty>". A later run in another specialty asks for a confirm first | `DiagnosisCommandBar.tsx` | | Questions | Nothing is pre-selected; the counter reads "N of M answered"; submit stays off until one question is answered. Each answer can carry a note. The overview lists every round with each answer and note. A question shows its source: "From the analysis" or "From the assistant" | `DiagnosisRunPanel`, `GET /osprey/diagnosis/runs/:runId/questions` | | More questions | "Ask more" opens one more round. An approved assistant pick always keeps the last slot of the round. Not available for a cohort | engine `askMore` | | Assistant tools | `dx_case_facts` (the case as stored), `dx_question_candidates` (finding ids it may propose), `dx_question_propose`, `dx_ask_more`, `dx_case_patch`. The last three show an approval card with names, never ids. A case patch shows as a card: Apply, then a banner "Results are out of date" with "Run again" | `ddx-osprey-engine/src/tools/catalogue/diagnosis-case.ts`, `DiagnosisCasePatchCard` | | Odds scorecard | Per diagnosis: probability, odds, "1 in N", likelihood ratio and 95 % interval. A row with no stored interval shows a dash, never a computed one. Source chips show one chip per title | `DiagnosisOddsScorecard.tsx` | | Treatment detail | Interacting drugs show per-check reasons, a monitoring note and "Why this is blocked". A drug with no safety profile reads "Not checked" and withholds dose (fail closed). Term help sits under the table | `DiagnosisOutputBodies.tsx` | | Case report | "Generate report" makes one report of a single case or a cohort, as PDF and Markdown, with the same values in both. Sections follow `module.diagnosis.caseReportSections`; the format setting picks the main button. A numbers judge checks every figure against the stored run and shows "Every number matches the stored run." A cohort report has one block per patient with only that patient's values. Header `Case report <run number>`; file `<run number>-report-<YYYYMMDD>.pdf\|md`. A report too large for the PDF returns Markdown plus a clear PDF error, never a cut PDF | `DiagnosisCaseReport.tsx`, `GET /osprey/diagnosis/runs/:runId/case-report`, `POST …/case-report/files?format=` | | Inline PDF viewer | The PDF draws inside the panel with the app PDF viewer (no iframe, no forced download). A "Scroll \| Pages" control: Scroll (default) shows all pages in one scroll, Pages shows one page and a horizontal swipe or drag changes it. Downloads are small links | `DiagnosisCaseReportPdf.tsx`, `PdfViewer`, `use-page-swipe.ts` | | Report export | The export route stores the file for the user (media id) and writes one audit row. Markdown is always an attachment | `OspreySessionFilesService`, kernel audit | Open quality items from the walks (not part of the plan acceptance): the case pane read view prints ATC codes and allergy class ids; the assistant has no lookup tool for a new drug code; drug safety is "Not checked" where the pack has no profile; red-flag names fall back to keys while a round waits. Since plan osprey-case-cockpit (section 5o): the case page is a tabbed cockpit with a stage header, so the "Questions" and "Case report" rows above now appear as the Questions and Report tabs. The report pane reads the report by case (`GET /osprey/diagnosis/cases/:caseId/runs/:runId/case-report`), so a reader who did not start the run sees it; PDF and Markdown export stay on the owner route (`…/runs/:runId/case-report/files`), and the export buttons are hidden for that reader. ## 5i. Case draft accuracy (plan osprey-dx-accuracy) The case draft board of section 5g/5h after the accuracy plan. Same roles and nav item. Engine side: [osprey-engine.md](/en/docs/osprey-engine) §Diagnosis engine, paragraph Case drafts. Keys: [settings.md](/en/docs/settings) §Draft and mapping keys. | Capability | Behaviour | Where | |---|---|---| | Async draft | The draft request answers at once. The board shows "Preparing the draft. The page updates by itself." and hides the items. When the fill ends, one live hint (`entity.changed` on the user channel) makes the board reload by itself; a failed fill shows its reason, a stale or interrupted fill tells the doctor to ask again in the chat. "Confirm" stays off, with the reason "You can confirm when the draft is ready.", until the draft is ready | `use-case-draft-board.ts`, `use-dx-draft-live.ts`, ddx-api `OspreyDraftWatchService` | | Same text, one fill | A repeat request with the same text and files returns the draft already running or ready; a failed or stale draft is retried on the same draft | engine `draft-fill.ts` | | Vector items stay held | An item mapped by vector similarity is never ticked for the doctor, whatever its score; the doctor ticks it | engine `case-extract.ts` | | Alternatives | Each item can list other concepts that may fit the phrase (label and match score). "Use this concept" switches the item; the engine pick stays available as the way back; the switched item shows "Changed by you". A switch is saved with the confirm, and the tick stays the doctor's | `DiagnosisDraftItemAlternatives.tsx`, `module.diagnosis.draftAlternatives` | | Better mapping | Concept-match reads the scrubbed case note around each phrase and judges a wider offer of candidates; the three sizes are org settings | `module.diagnosis.conceptMatch*` | | Vitals and labs | A measure without value and unit is kept as a text-only sign instead of failing the draft | engine `case-extract.ts` | | Settings page | Six new Diagnosis fields (org admin edits, staff reads) in the platform settings form | [settings.md](/en/docs/settings) | Usage harness (not a product screen): `./ddx-manage.sh usage ... --patient` answers questions from the case text only, and each case writes a stage report (mapping, coverage, rank); see `ddx-osprey-usage/CLAUDE.md`. --- Last reconciled: 2026-11-16 · plan osprey-dx-accuracy task 023 ## 5j. Mastra spine, case library and learning loop (plan osprey-mastra-native) The diagnosis of section 5g on a second, Mastra-native run engine, plus the case library and the learning loop. Same roles and nav item; no new page. Engine side: [osprey-engine.md](/en/docs/osprey-engine) §Diagnosis engine, paragraphs Mastra spine, Learning loop, Assistant tools. Keys: [settings.md](/en/docs/settings) §Mastra spine keys. **State.** The spine is built and switchable per org with `module.diagnosis.engine` (`legacy` | `mastra`). The seed is `legacy`: every org runs today's pipeline until an org admin switches. The parity, accuracy, time and token runs have not run yet; no measured number is claimed here. | Capability | Behaviour | Where | |---|---|---| | Engine switch | An org admin sets the run engine in the platform settings form; a run keeps the engine it started with | `module.diagnosis.engine` | | Spine progress | A spine run emits one progress row per step (load, intake, match, retrieve, score, rank, questions, safety, differential, deep reasoning, report, outputs, case library); questions suspend and resume as before | engine `spine/workflow.ts` | | Same scores | Score, rank and questions use the unchanged diagnosis core, so a spine round has the same `resultHash` as the legacy round | engine `spine/steps-score.ts` | | Run budget | A finished spine run carries its token and time spend per step and an over-budget flag | `module.diagnosis.runInputTokenBudget` | | Case library | Every completed spine run with a case number is stored scrubbed (no identifiers) for the same doctor in the same org | engine `case-library/ingest.ts` | | Similar cases | The case chat can list similar past cases of the same doctor and org, labelled "similar past case <case number>"; they are hints, never case facts and never scoring evidence | assistant `dx_similar_cases` | | Cross-case recall | A case-scoped chat turn may recall items from the doctor's past cases, labelled and scrubbed; an item without a case number is dropped | `module.diagnosis.crossCaseRecall*` | | Feedback notes | The doctor can store a note or a confirmed diagnosis on an owned run (approval card first) | assistant `dx_feedback_note` | | Card CRUD as proposals | The case chat can read cards (`dx_card_get`, `dx_card_search`; WITHHELD on a safety-blocked run) and propose a new card, a card update or one attribute change; a write needs `diagnosis:propose` and files a PENDING proposal, never a published change | assistant `dx_card_*` | | Submit case | In the case chat the doctor says "submit this case" (any language): the router picks the workflow `diagnosis-start`, and with a ready draft the assistant asks for approval, then starts the run and answers at once. It never starts a draft or run of another case, and repeating the request attaches to the existing run | assistant `dx_run_start`, engine `lanes/react/dx-first-tool.ts` | | Analyze case | The case chat can start or attach to a run with `dx_analyze_case`: each step appears as it runs and the answer ends with one sentence for voice | assistant `dx_analyze_case` | | Learning loop | Board acts (alternative switch, tick, untick, confirmed final diagnosis), notes and case outcomes become id-and-count signals; at the support floor they file PENDING proposals. Patient text never enters a signal | engine `curation/board-signals.ts`, `feedback-signals.ts` | | Gate before review | Each proposal shows its promotion-gate result (tune split) before review; the reviewer approves over a failed top-5 gate only with an override reason; a must-not-miss drop can never be overridden | curation proposals, `overrideReason` | | Closed loop | After a publish, `osprey dx learn check` compares the gold-card ranks before and after; a regression files a PENDING rollback proposal | engine CLI, `module.diagnosis.closedLoopRankTolerance` | | Mixed intake | Text plus form: a form value wins over the text fill, and each field records where its value came from | engine `draft-fill.ts` | | Settings page | Eighteen new Diagnosis fields (org admin edits, staff reads) in the platform settings form | [settings.md](/en/docs/settings) | Usage harness (not a product screen): `osprey-usage parity` compares a legacy run with a mastra run per case, `osprey-usage signals <runDir>` exports stage misses as count-only signals, and suite `flow-intake3` drives the mixed intake end to end; see `ddx-osprey-usage/CLAUDE.md`. --- Last reconciled: 2026-11-17 · plan osprey-mastra-native task 064 ## 5k. Assistant diagnosis artifacts (plan assistant-diagnosis-agentic) The case chat and the main Assistant answer a diagnosis question with artifact cards, not only text. Engine side: [osprey-engine.md](/en/docs/osprey-engine) §Diagnosis engine, paragraph Artifact tools. | Capability | Behaviour | Where | |---|---|---| | Artifact cards in chat | A diagnosis answer can carry cards in the thread: odds scorecard, questions, what-if, outputs of a run and the case report. Each card links to the cockpit run | assistant tools `dx_analyze_case`, `dx_question_propose`, `dx_ask_more`, `dx_what_if`, `dx_run_outputs`, `dx_case_report`; `ddx-web/src/components/diagnosis/DxArtifact*.tsx` | | Case binding in the main Assistant | `?case=<id>` binds the Assistant to one case. A chip names the case (by number and title, never an id) and an unbind button clears it. A bound turn is sent with the case marker and runs on the react lane | `use-assistant-case-binding.ts`, `AssistantWorkspace.tsx` | | Cockpit Results pane | The case cockpit has a Results pane with a switcher over the result views (differential, treatment, safety and others). It shows only a completed run. `?run=<id>` opens a given run | `ddx-web/src/components/diagnosis-cockpit/case/ResultsPane.tsx` | | Discuss in the assistant | A cockpit action opens the Assistant bound to the case and the run | `diagnosis.json` key `openAssistant` | | Case number on chat runs | A run started from chat is stamped with the kernel case number, so the report and the case library name it | `POST /diagnosis/runs/:runId/case-number` | Open items: the vector-map card link opens the global map and ignores `?run=`; a `?run=` link to an older run of a case does not replace the latest run in the cockpit. The manuals `ddx-manuals/osprey-assistant` and `ddx-manuals/osprey-diagnosis` show the old chat and need a re-render. ## 5l. Case groups (plan osprey-case-groups) Cases can be grouped by a subject code or a cohort code, an outcome can be recorded per subject, and the assistant can list the doctor's cases. Same roles and nav item as section 5g. Names and code rules: [naming-constitution.md](/en/docs/naming-constitution) §6.5b. Engine side: [osprey-engine.md](/en/docs/osprey-engine) §Diagnosis engine, paragraph Case groups, outcome and case directory. Kernel side: [entity-kernel.md](/en/docs/entity-kernel). | Capability | Behaviour | Where | |---|---|---| | Group list | `diagnosis/groups` lists case groups (code, kind, cases and open cases), with search, a kind filter and a Create button. The create form takes a kind and a code; the code is upper-cased on save. A code that reads as a date, has the wrong shape or is already in use is refused, and the message names the rule, not the value | `<P>/diagnosis/groups/page.tsx`, `GroupListV2.tsx`, `group-counts.ts` | | Group detail | `diagnosis/groups/<id>` shows the kind and code, the count of cases and open cases, and only the cases the caller can read. Each case row shows its outcome and its report files (PDF and Markdown). A file from the latest run of the case reads "Current"; an older export reads "Older" | `<P>/diagnosis/groups/[groupId]/page.tsx`, `GroupDetailV2.tsx`, `group-header.ts` | | Group on a case | The create form and the cockpit let a staff, org-admin or super-admin pick a subject group and a cohort group for a case. A cohort case has no subject group. A kind mismatch is refused (400) | `CaseCreateV2.tsx`, `DiagnosisCaseSummary.tsx`, `DiagnosisCaseGroups` in the cockpit beside the outcome block | | Case list columns | Case number, title, subject, cohort, status, outcome, last activity. Filters by subject group and cohort group, search `?q=`, and a link to the group list. There is no run column | `CaseListV2.tsx`, `case-list-v2.ts` | | Outcome | The cockpit shows the current outcome per subject (labels only), when it was recorded, and a history link. "Record outcome" opens a disclosure with the form; a cohort asks for the subject first. The save sends the outcome time the doctor saw; if another save changed it, the form shows a conflict and a reload button and writes nothing. Outcome labels come from the engine, never from typed text | `DiagnosisCaseOutcome.tsx`, `DiagnosisOutputActions.tsx` (FeedbackForm), route `POST /osprey/diagnosis/runs/:runId/feedback` | | Report files | Every case report export (PDF or Markdown) is indexed in `diagnosis_case_report_file`, so the group page can list files per case. Exports made before this plan are not indexed | `GET /osprey/diagnosis/cases/report-files?caseIds=…`, `OspreyCaseReportFilesService` | | Assistant case list | The assistant answers "which of my cases are open, grouped by subject" with a `dx_case_list` card: groups with a code heading, rows `<case number> · <title>` linking to the case. The model sees counts, case numbers, status, outcome and codes, never titles | engine `dx_case_list`, `DxArtifactCaseList.tsx`, setting `module.diagnosis.assistantCaseDirectoryMax` | | Fixture tools off | The named-patient fixture tool groups are not in the live assistant catalogue unless `OSPREY_FIXTURE_TOOLS=true`; the assistant no longer offers "Patient search" | engine `OSPREY_FIXTURE_TOOLS` | Accepted limits: (1) the outcome check runs before the write, so two saves at the same moment can both reach the engine and leave two `dx_feedback` rows; the second case write answers 409 (the full fix is an engine idempotency key, a later plan). (2) The `dx_case_list` card stores its rows, titles included, in `osprey.event`. (3) The report-files list cuts at `LIST_QUERY_LIMIT_MAX` rows with no `truncated` flag. (4) The per-entry outcome history list was not walked live; the history link shows after a record. Open items from the walk: the create-group dialog shows a duplicate error twice; the assistant card header repeats "Case list"; the outcome form has two buttons named "Record outcome" and "Current outcome" shows twice when open. ## 5m. Assistant case offer, learning loop and projects with groups (plan osprey-assistant-engine) The assistant offers a case, binds voice to a case and learns from recorded outcomes. Wiring map of the four turns: [assistant-diagnosis-wiring.md](/en/docs/assistant-diagnosis-wiring). | Capability | Behaviour | Where | |---|---|---| | Case offer | A diagnosis question with no case open gets a case card (`dx_case_create`, approval-gated), never a memory answer. The doctor applies it; the web creates the case through the BFF and binds the chat. The code must be a pseudonymous subject or cohort code; a name or date is refused | engine `tools/catalogue/diagnosis-case-create.ts`; web `DiagnosisCaseCreateCard` | | Case finder | A turn that names a case number (`DX-YYYY-NNNNN`, spoken forms too) finds that case first (`dx_case_find`) and opens it through the navigate handler | engine `tools/catalogue/diagnosis-directory.ts` | | Case-bound voice | A voice stream can be bound to a readable case. The case rides the ticket binding and a first loopback scope frame, never a browser frame | `ddx-api/src/osprey/osprey-voice-ticket.service.ts`; engine `voice/turn-body.ts` | | Outcome loop | Recorded outcomes feed card accuracy (`GET /diagnosis/card-accuracy`). An opt-in job (`module.diagnosis.outcomeLoopEnabled`) writes a PENDING card proposal with origin `outcome` into the review queue; a reviewer other than the proposer decides, and each draft writes an audit row | engine `diagnosis/curation/outcome-loop.ts`, `accuracy-routes.ts` | | Projects with groups | A case group can link to a project (optional). A project grant never opens a group | [entity-kernel.md](/en/docs/entity-kernel) | Accepted limit: voice number resolution depends on the spoken-form pattern; an unmatched form reaches the model as text. ## 5n. Assistant casework (plan osprey-assistant-casework) The Assistant can run a whole case study by chat: open or create a case, answer the question form, see the safety result, get the report as a PDF, record the outcome, look at projects and groups, and propose card changes. Wiring map: [assistant-diagnosis-wiring.md](/en/docs/assistant-diagnosis-wiring). Keys: [settings.md](/en/docs/settings) §Diagnosis keys. | Capability | Behaviour | Where | |---|---|---| | Chat cards | Ten block kinds show a run, the safety result, a card, a case, a project, the report PDF, a case status change, a group change, an entity change (section 5p) and a proposal review. Each block holds ids only; the card reads the stored record. Texts come from the `diagnosis-casework` namespace in all four locales | `ddx-web/src/components/diagnosis/DxArtifact*`, `DxCaseStatusCard`, `DxGroupChangeCard`, `DxEntityChangeCard`, `DxProposalReviewCard` | | Answer form | The question form carries its round. A second tab or a repeat submit gets a clear refusal (409) and the form must reload | engine `run-service.ts`; ddx-api `…/runs/:runId/answers` | | Safety block | A blocked run withholds guidance. The card lists the fired red flags and the acknowledge form | `DxArtifactSafety`; `isGuidanceWithheld` | | Safety override | A doctor clicks the safety form, ticks every fired red flag and writes a reason of at least `module.diagnosis.safetyOverrideReasonMin` characters. Roles: org-admin and staff. The override releases the held guidance for display only; the verdict and scores do not change. It covers the run only while the round and verdict match and every fired red flag is acknowledged; a re-scored run needs a new acknowledgement. Each acknowledgement is one append-only history row. No model tool and no voice phrase can make an override. The report prints it and a banner shows it | engine `safety-override*.ts`; ddx-api `OspreyDiagnosisSafetyController` | | Case work | Read, list, create, archive and reopen a case from chat. Archive and reopen need a doctor click on the card. Rename, dispose and delete are proposals too (section 5p); a delete is a kernel soft delete behind a click and one confirm | tools `dx_case_open`, `dx_case_status`; `DxCaseStatusCard` | | Report PDF | The report of a completed run opens as a PDF block; a blocked run withholds it | tool `dx_report_pdf`; `DxArtifactReportPdf` | | Projects and groups | The Assistant lists projects, reads one, assigns a group to a project and creates a group. The turn carries a project directory (with groups that sit in no project). Assign and create need approval and `diagnosis:write` | tools `dx_project_list`, `dx_project_read`, `dx_group_assign`, `dx_group_create`; ddx-api `buildProjects` | | Card work | Read and search cards, propose a card change or a retire, list and review proposals. A retired card stays on stored runs and reports, but feeds no new run. The review tools show only to a platform super-admin (exposure `diagnosis:review`, set per turn from the platform role, never from a client value); an org-admin has the Assistant page but not these tools; the decision itself stays in the web review | tools `dx_card_retire`, `dx_proposal_list`, `dx_proposal_review`; `DxProposalReviewCard` | | State gate | The engine hides a dx tool the case state cannot use (rows G1-G8; G4 is retired, the management tools also run with no bound case). A proposal tool runs once per turn and never when a turn resumes after approval | engine `lanes/react/dx-tool-gate.ts` | | Case directory | The per-turn case directory keeps a tenth of its cap for the newest closed cases | ddx-api `OspreyCaseDirectoryService` | Known limits (open, from the headed walk of plan task 043; none is fixed): - Card work (AC-9): a retire request can pick `dx_card_propose` instead of `dx_card_retire`. The reviewer (platform super-admin) reaches the Assistant page since 2026-11-18 (section 5o); the review chat cards are not walked there yet. - Voice (AC-12): a voice turn is heard and bound to the case but gave no spoken answer. Answering a question and opening the report by voice are not walked. - Projects (AC-14): the project block and the group assign work. "List projects" gave no answer. Creating a group in a project and listing cases by project are not walked. - Permissions: the nine older write tools carry no permission, so every role sees them. This is an owner decision, not a fix. - Case chat: a turn that carries a case marker needs the case `update` op. A member who can only read a case gets 403 on every turn of that chat, also for a pure question (section 5o, open points). - Review refusal: the engine answers a reviewer who is the proposer with a plain 400 that has no code. The web matches the message text. - The card page (`DiagnosisCardDetail`) shows nothing about a retired card; only the chat card does. ## 5o. Case cockpit, case stage and projects with cases (plan osprey-case-cockpit) One stage per case, a tabbed case page, runs that every reader of the case can see, and projects that hold cases. Same roles and nav item as section 5g. Wiring of the Assistant gate: [assistant-diagnosis-wiring.md](/en/docs/assistant-diagnosis-wiring). Keys: [settings.md](/en/docs/settings) §Diagnosis keys. | Capability | Behaviour | Where | |---|---|---| | Case stage | Every screen shows one derived stage, never the raw case or run status: Draft · Ready to analyse · Analysing · Needs answers · Results ready · Outcome recorded · Archived · Failed · Cancelled. First match wins: archived → Archived; disposed → Outcome recorded; a case with a run takes the stage of its latest run (queued, running → Analysing; awaiting answer → Needs answers; completed → Results ready; failed; cancelled); draft with no run → Draft; active with no run → Ready to analyse. A draft case that already has a run shows the run stage | `deriveCaseStage` in `packages/ddx-contracts/src/osprey-diagnosis-case-stage.ts`; labels in `diagnosis-cockpit` `stage.*` | | Next action | One main action per stage: Complete intake · Analyse · Watch the run · Answer questions · Record outcome · Reopen case · Restore case · Run again (Failed, Cancelled). Results ready also offers Run again as a lower action. A closed case (Outcome recorded, Archived) offers only Reopen or Restore; start, intake edit, patch apply, outcome record are off and the Questions tab is inert. A reader who did not start the run sees "Run again as me" where the owner would answer | `DX_CASE_STAGE_ACTIONS`, `isCaseReadOnly`; `case-work-tabs.ts` `caseActionsOf` | | Tabbed cockpit | The case page `diagnosis/[caseId]` has a header (`<case number> · <title>`, specialty, project, stage badge, next action), the fixed command region (red flags, must-not-miss pins, withheld guidance, disclaimer; never in a tab) and seven tabs by `?tab=`: Overview (stage stepper, run, outcome, groups, intake) · Differential · Evidence · Map · Report · Questions · History. A tab with nothing to show is disabled: Differential needs a run in progress or done, Evidence, Map and Report need a completed run, Questions any run, History at least one run. Older `?tab=reasoning\|treatment\|prognosis\|dossier` open Evidence. Overview and Questions stay mounted, so typed input survives a tab change. The doctor/Osprey split of section 5g is gone | `ddx-web/src/app/[locale]/(app)/portal/[orgSlug]/[role]/diagnosis/_islands/v2/CaseCockpitV2.tsx`, `components/diagnosis-cockpit/case/case-work-tabs.ts` | | History tab | Lists the runs of the case (stage of each run, who started it, own run marked, no run id shown) up to `module.diagnosis.caseRunHistoryLimit`; a click opens that run (`?run=<id>&tab=history`) | `HistoryTab`; `GET /osprey/diagnosis/cases/:caseId/runs` | | Run visibility | Any user of the tenant who may read the case sees its runs, outputs, insight, evidence, map, questions, report and safety result, whoever started the run (org-admin sees the staff run). The kernel read of the case comes first (404 when unreadable); only then the engine answers under a read grant. Writes stay owner-scoped: start, answers, safety acknowledgement, outcome. A failed run read is an error state with Retry, never "No run yet" | ddx-api `OspreyDiagnosisCaseRunsController`, `OspreyCaseRunsService`; engine `gateway-case-reads.ts` (12 GET routes) | | Run link | The server links a run to its case: the case keeps the latest run id and run status (`latestRunId`, `latestRunStatus`), and a draft case becomes active. A run started outside the web (harness, Assistant) shows after the engine's `dx.run.changed` hint (section 5p) or a throttled sync (`POST /osprey/diagnosis/cases/sync`; a throttled call answers 200 and skips). A one-time backfill linked the existing runs | ddx-api `OspreyCaseRunsService.repairCase`, `syncTenant`; `module.diagnosis.caseSyncMinIntervalMs`, `caseSyncBatchLimit` | | Case list | The list shows the stage per case and a "Continue" link that opens the next action of the stage. Filter `?stage=` (exact, run on the server, including "no run" through the `empty` filter op). The list runs the throttled sync before it reads. The role home shows case counts by stage (dashboard `caseStages`) | `diagnosis/page.tsx`, `CaseListV2.tsx`; `GET /orgs/:orgSlug/dashboard` | | Questions | A question can carry up to three answer options (state + label); the form groups questions by modality (History, Examination) and answers read Reported, Denied, Unknown; ids are never shown | `DxQuestion.options`; `QuestionsPane` | | Projects that hold cases | A project (kernel entity, section 6 "Projects and tasks") holds clinical cases; tasks are its steps. A case belongs to at most one project (`projectId`, set null if the project goes). The project page has a Cases tab for roles with the diagnosis area: case number, title, stage badge, outcome label, link to the cockpit, progress "N of M cases have an outcome" and a count per stage. New case from the project (`diagnosis/new?project=<id>` presets and locks the project picker; the picker is optional); Move out and Move in change only the case project relation. The projects list has a Cases column. The kernel projections `owner` and `admin` carry `cases` and `caseCount`; a client with a grant sees no case through a project | `projects/[id]/page.tsx`, `ProjectCasesPanel.tsx`; `descriptors/project.ts`; `diagnosis-case` `projectId` | | Assistant for org-admins | The Assistant page and nav item are open to org-admin (owner decision 2026-11-18). Discuss in the assistant opens `/public/assistant?case=<id>` with the case chip. The review tools stay platform super-admin only. A case chat turn needs the case `update` op | `portal-registry.ts`; ddx-api `osprey.service.ts` | | Case assistant pane | From 1280 px (`xl`) a closable chat pane sits right of the tabs; below it a docked bar opens the chat in a drawer. The empty chat shows a title, one sentence and three starters. The case page asks the side nav for the icon rail while it is open | `CaseAssistantV2.tsx`, `usePortalSideNavFocus` | | Settings | `module.diagnosis.caseRunHistoryLimit` (50), `caseSyncMinIntervalMs` (15000), `caseSyncBatchLimit` (2000); org tier, staff read, org-admin edit | [settings.md](/en/docs/settings) | Open points of the headed walk (plan task 018; not fixed): - A PDF download for a reader who did not start the run: the button was hidden; the by-case report files route of section 5p closes this. - A read-only member cannot chat about a case at all (403 on every turn with a case marker); a finer rule needs an engine capability flag. - "Record outcome" is offered to a reader who did not start the run; the write stays owner-scoped and was not clicked. - The draft cockpit shows three "Analyse" buttons (header, next step, run pane) and four "No run yet" rail cards; the one next-action card is only partly reached. - A stale answer shows "already answered" by code path only (two-tab test not run). - The old demo project rows ("Website refresh" and four more) still exist; they are removed only after an owner yes. - Production must require `x-real-ip` for the web trusted client-IP key (`deploy/scripts/check-env.sh`); the dev BFF sends no node token (a debug line per request). ## 5p. Run control, lifecycle and Assistant management (plan osprey-cockpit-hardening) The diagnosis screens act as one product, runs and cases have no dead end, and the Assistant can do what the UI can do, by proposal card. Same roles and nav item as section 5g. Wiring of the tools: [assistant-diagnosis-wiring.md](/en/docs/assistant-diagnosis-wiring). Push hints: [realtime.md](/en/docs/realtime) "System hints". Keys: [settings.md](/en/docs/settings). | Capability | Behaviour | Where | |---|---|---| | One live run per case | A start on a case that has a queued, running or waiting run answers 409 `DX_RUN_ACTIVE` with a fixed text and no id. Ask-more takes the same check. The UI shows "A run is in progress" with "Open it" and "Cancel it". Two starts at once: the engine lets one win | ddx-api `OspreyCaseRunsService.assertNoLiveRun`; engine `insertRunRowIfCaseIdle`, `moveCompletedRunToRunning` | | Run cancel | The cockpit shows "Cancel run" (outline) while the shown run is live, behind one confirm. Any user with the case `update` op may cancel, whoever started the run. The first terminal status stays: a run that already ended answers 200 `cancelled: false` | `POST /osprey/diagnosis/cases/:caseId/runs/:runId/cancel`; engine grant `diagnosis:case-manage` | | Run expiry and lost runs | A run that waits for answers longer than `module.diagnosis.runAwaitingExpiryHours` (72, 0 = never) becomes `cancelled` (reason `unanswered-expired`). A queued run past `runQueuedGraceSeconds` (120) with no worker is started, or becomes `failed` if the start fails. Both values are stored with the run at start | engine `boot/recovery.ts` sweeps | | Outcome by case | A user with the case `update` op records the outcome from any completed run of the case, whoever started it. The outcome and the status `disposed` are one write. Reopening a case clears the current outcome marker; the engine feedback rows stay as history | `POST …/cases/:caseId/runs/:runId/outcome`; `OspreyDiagnosisOutcomeService.recordForCase` | | Report files | The report PDF and Markdown of a completed run are stored once with the case. Every reader of the case downloads them; only a user with `update` stores one. The PDF bytes come from the Next server, never from a browser | `POST …/case-report/files?format=`; `app/api/osprey/pdf/route.ts` mode `{ caseId, runId }`; media owner type `diagnosis-case` | | Archive and delete | Archiving a case with a live run cancels the run first; a delete does the same and also needs the case `update` op. If the engine is down the archive or delete is refused (502 / 503), nothing is half done. Deleting a project clears the project link of its cases in the same transaction | ddx-api `OspreyCaseLifecycleService`; kernel `EntityWriteHooks` | | No polling between services | The engine pushes a hint when a run, a draft fill or the usage ledger changes; ddx-api repairs the case link, tells the watcher and syncs usage from that hint. The case sync timer, the usage ledger interval and the draft watch loops are removed, and so are the settings `caseSyncIntervalMs` and `caseRunLinkWaitMs`. A subscription that comes up without recovery runs one catch-up pass | channel `system:osprey`; ddx-api `EngineHintSubscriberService`, `OspreyEngineHintsService`; engine `events/system-hints.ts` | | Assistant management | By chat the Assistant proposes: case rename, specialty, dispose, delete, move to a project, group assign (`dx_case_change`); project create, update, delete (`dx_project_change`); task create, update, delete (`dx_task_change`); run cancel (`dx_run_cancel`). Each shows one `dx_entity_change` card; nothing changes before the doctor clicks Approve, and a delete asks one more confirm. Reads: `dx_run_history`, `dx_task_list`, `dx_case_list` by stage and project. The case argument defaults to the open case. The old fixture task tools are removed | engine `tools/catalogue/diagnosis-entity-change.ts`; web `DxEntityChangeCard` | | Runs of a colleague in chat | ddx-api adds the bound-case pack `dxBoundCase` to the turn of a case the caller may update. The Assistant reads that case's runs under a read grant and can run again with no draft | engine `diagnosis/bound-case.ts`; gate rows G2, G3 | | Cockpit screens | One filled button per view; pane status lines are sentences; the Intake pane shows no run state; evidence groups and views are one-row rails; History is a table; questions read as sentences; the Report tab uses the cockpit type scale and shows the differential once; rounds print as `shownRound`; each resource is read once and a status move re-reads only the case version | `ddx-web/DESIGN.md` "Diagnosis cockpit v2" | | Settings | New: `runAwaitingExpiryHours`, `runQueuedGraceSeconds`, `assistantRunHistoryMax`, `assistantTaskDirectoryMax` (org tier, staff read, org-admin edit). Removed: `caseSyncIntervalMs`, `caseRunLinkWaitMs`. `draftWatchPollSeconds` now only paces the engine relay | [settings.md](/en/docs/settings) | Deploy order (open item for the release): run `pnpm osprey db migrate` in the engine before the new engine code (`sql/045`); add `DDX_API_CENTRIFUGO_CLIENT_URL` to the server `ddx-api.env`; restart Centrifugo for the new namespace `system`; run `pnpm install` (ddx-api gains the `centrifuge` client). Open points (from the plan walk, not fixed): - A stale draft fill is a read-time state in the engine and sends no hint; a watcher learns of it by the draft read. - Kernel delete has no version of its own: the card re-reads and compares before a delete, which is not a true compare-and-set. - Chat tools `dx_ask_more` and `dx_question_propose` show a live-run refusal with the generic failure text, not the fixed `DX_RUN_ACTIVE` wording. - Not driven live: a real expiry cancel, a real orphan-queued start, recovery after a Centrifugo restart with hints in flight, node 2, and the chat cards for case update, dispose, delete, project and task changes. ## 6. Cross-cutting capabilities | Capability | Behaviour | Where | |---|---|---| | Realtime | One Centrifugo connection per tab, SSE first with a WebSocket fallback. Open tabs refresh through delivery-only hints on the `user:` and `org:` channels that invalidate TanStack Query keys; the browser never trusts a hint as state. Presence, outbound webhooks, inbound webhooks, the `/events` stream and the SSE inspector no longer exist. Osprey session events arrive on `session:` and `run:` channels and are ordered by Postgres revision. Technical detail: [realtime.md](/en/docs/realtime) | `ddx-web/src/lib/realtime/`, `ddx-web/src/components/providers/RealtimeProvider.tsx`, `ddx-api/src/realtime/` | | Media | Upload, list, detail, streamed content with Range → 206; browser never sees MinIO or a presigned URL (ADR 0011) | `ddx-api/src/media/media.controller.ts`; BFF `ddx-web/src/app/api/v1/[[...path]]/route.ts` | | Chat and notifications | Threads with messages, per-user notifications, mark read | `ddx-api/src/communication/threads.controller.ts`, `notifications.controller.ts` | | Projects and tasks | CRUD with org isolation, served by the entity kernel ([entity-kernel.md](/en/docs/entity-kernel)); `staff` holds read, list, create, update, delete, attach; `org-admin` holds every op; `member` reads; a `client` reads only through a grant. Task assignee and project change by org-admin and staff only, and the assignee must be an active member | `packages/ddx-contracts/src/descriptors/{project,task}.ts`, `ddx-api/src/kernel/` | | Access grants (ACL) | A project or task owner or org-admin grants `read`, `update` or `attach` to a user or a role; a task inherits its project's grants. One call replaces the whole list; a user must be an active member and a role one of the org roles. An unreadable record answers 404 | `GET\|PUT /orgs/{orgSlug}/projects/{id}/acl`; `ddx-web/src/components/entity/EntityAccessPanel.tsx` | | Audit chain | Every kernel mutation writes a hash-chained audit row (grants shown before and after on an ACL change). Anyone holding `audit` can verify the chain | `GET /orgs/{orgSlug}/projects/{id}/audit`, `…/audit/verify`; `EntityAuditPanel.tsx` | | Attachments | Files on a record: cover image on a project, documents on a task, avatar, signature, logo. Upload and download go through ddx-api and the BFF | `…/{id}/attachments`; `EntityAttachmentsPanel.tsx` | | Members | Org member roster with projections: `summary` for everyone (no e-mail), `admin` for org-admin; title edit by org-admin | `ddx-api/src/members/members.controller.ts`; `ddx-api/src/identity/` | | API keys | Create, list, delete a user key | `ddx-api` `/api-keys` (`ddx-api/src/auth/api-keys/`) | | Audit (platform) | Settings writes and non-member platform writes are audited | `ddx-api/src/audit/audit.service.ts` | | Multi-tenancy | Every record belongs to one org; the org comes from the signed token claim, never a client header | `ddx-api/src/tenancy/` | | i18n | `en`, `de`, `fr`, `es` in lockstep | `ddx-web/messages/` | | List stack | Every list page (projects, members, project tasks, data, media, workspace) shares one stack: action bar (create, view switch, density, search `?q=`, facets, group-by `?group=`), bulk bar on selection (count, clear, delete with confirm, CSV export of the selection), views table · cards · compact list · timeline · board · calendar · export, sticky header and pager with shimmer while loading. Facets in the toolbar are single-select; ddx-api already serves multi-value (`in`), range, relation-option (`GET …/facets/:field`) and bulk-delete (`POST …/bulk-delete`, ≤ 100 ids) through the one list-query contract, and the web parser is shared (`lib/kernel/entity-service.ts`, `query-keys.ts`) — toolbar UI for them is not built | [patterns.md](/en/docs/patterns) §List stack; `ddx-web/src/components/data/` | | Org list and permission source | The org switcher and `/auth/select-org` read the caller's orgs from `GET /me/orgs`; the portal layout reads org, role and the permission map (`can`) from `GET /orgs/:orgSlug/overview`; `requirePermission` reads `can`. No page reads the better-auth organization plugin (only `set-active` is a write). Role change: `PATCH /orgs/:orgSlug/members/:memberId/role` | `ddx-web/src/lib/dal/organization.ts`; `ddx-api/src/read-models/`; [ADR 0017](/en/docs/adr/0017-bff-layered) | | Portal header controls | Org switcher (searchable), location crumb, ⌘K / Ctrl K palette trigger, notification bell and popover, 4-language menu (endonyms), theme light · dark · system and density, help, user menu (profile, settings, organization, sign-out) | `ddx-web/src/components/portal/shell/PortalHeader*.tsx`, `PortalOrgSwitcher.tsx`, `PortalUserMenu.tsx` | | Profile locale and time zone | Language is a 4-endonym select; time zone is a searchable combobox grouped by IANA region with the UTC offset | `<P>/profile/_islands/ProfileForm.tsx`; `ddx-web/src/lib/format/time-zones.ts` | | Cookie settings | The consent banner reopens from the site footer, the portal status bar and the portal user menu | `ddx-web/src/components/consent/` | | Full-width frames | Portal and site page frames use the full viewport width with the shell gutter; entity forms and detail grids add columns with width. Prose, auth cards, call cards and print previews stay capped | `ddx-web/src/components/portal/page/types.ts`, `ddx-web/src/components/site/types.ts` | | Portal loading | A hard load of any portal route shows a static shell skeleton (header, side nav, status bar) before data | `ddx-web/src/components/portal/shell/` (`PortalShellSkeleton`), `<P>/../loading.tsx` | | Print of a record | Print routes: documents, projects, profile, organization, member. `?view=print` redirects to `/print` | `<P>/{documents/[id],projects/[id],profile,organization,members/[memberId]}/print/page.tsx` | | Operator deploy | Operator role only, never a portal role. `./ddx-manage.sh remote deploy\|rollback\|route\|logs\|status\|pull-logs --target <id>` or `/ddx-deploy`: release deploy with canary check, rollback to the previous release, publish of the public route, remote logs, status with boot check, log pull. Runs on operator request from the main session; never on push or a timer. Production: `https://osprey.dudoxx.com` (forge) | `deploy/`, `ddx-manage.sh`; runbook [deploy/README.md](/en/docs/deploy/README), quick path [deploy/CHECKLIST.md](/en/docs/deploy/CHECKLIST); targets `context/DEPLOY_TARGETS.md` | --- Last reconciled: 2026-11-18 · plan osprey-cockpit-hardening task 021 (sections 5n, 5o, 5p)
Functional view of the workspace: pages and capabilities per audience, each row citing the
route file it lives in. Technical view: ,
, api/openapi.json. Every route below is a file today; a page
that is not listed here has no route.
Path prefix for the File column: ddx-web/src/app/[locale]/. <P> = (app)/portal/[orgSlug]/[role].
Every page is locale-prefixed (en, de, fr, es; strings in ddx-web/messages/<locale>/).
The portal URL is /{locale}/portal/{slug}/{role} (ADR 0003). slug is the org slug.
role is a portal role, not an org role:
A role that the session does not hold renders forbidden(). The role is gated once, in
PortalPage (allowedRoles: rolesFor('<nav item>')); ddx-api still decides data access per
request (org roles super-admin · org-admin · staff · member · client; super-admin is a platform role that acts as org-admin of the target org, ADR 0013).
Nav items come from ddx-web/src/lib/navigation/portal-registry.ts (17 items). Columns show
which portal role sees each item. All routes live under <P>/.
Reading the table: — = the nav hides the item and the page renders forbidden() for that
role. Staff sees every pattern demo; the access sets are PORTAL_NAV in portal-registry.ts
and PROJECT_WRITE_ROLES in <P>/projects/_islands/model.ts.
Portal chrome shared by every page above (the header and side nav show the tenant name and logo, see section 5b): header (org switcher with role badge, location crumb, ⌘K command palette, notification bell with unread badge, language menu, appearance menu for theme and density, help link, user menu), side nav (expanded · collapsed · auto), status line, footer
status bar, mobile menu — .
One page, <P>/settings/page.tsx, one read: GET /orgs/:orgSlug/settings/effective through
the BFF. The page renders what ddx-api returns; it never merges tiers.
PlatformSetting, edited only by platform super-admin) →
org (stored, edited by org-admin) → user (stored, edited by the user for their own value).
Registry: packages/ddx-contracts/src/settings.ts. Guide: .<scope>.<group>.<key>): portal.locale.default (org + user) ·
portal.locale.enabled (org) · portal.features.ai (org; each org chooses; staff roles read) ·
portal.notifications.digest (org + user) · portal.display.timeZone (org + user) ·
portal.display.themeMode light · dark · system · portal.display.density compact · cosy · large ·
portal.display.motion full · reduced · portal.display.textSize sm · md · lg (type only, never row height; all org + user) · module.demo-entities.viewMode
table · cards (per-module preference, org + user) · the five portal.branding.* keys (section 5b; org only, no user tier).
The 24 assistant.* keys (model, effort, voice providers, voice id, turn detection, fallback order, default persona, default agent,
custom instructions, tone, memory switch, file limits and kinds) are listed with tiers in
§Assistant keys. The STT provider, TTS provider and fallback order are org-tier only (org-admin edits; review 050 M1)./{locale}/platform/settings lists the platform tier and edits one
key at a time (GET /platform/settings, PATCH /platform/settings/:key, version required,
409 on a stale version). Only platform super-admin may call it. A write fans out
settings.changed (key + version, never the value) to every org.UnifiedSettingsProvider and
useUnifiedSetting(key); the header menus write the user tier.editable flag. client sees 4 keys (no portal.features.ai).public-persona access for org-admin is NEEDS_REVIEW (ADR 0014).Five keys, portal.branding.{displayName,palette,font,illustration,logo}: platform default, org
override, no user tier. Key table: §Branding keys.
Known gaps (ADR 0019): the home hero title (home.title) and site.brand.home label are fixed
text; the first hard load after a palette change can paint the previous palette once; orphaned logo
objects are not cleaned up.
A Bug button in the header and Alt+Shift+D open a debug panel. It exists only when
NEXT_PUBLIC_UI_DEBUG is on in ddx-web/.env.local. Detail: .
Page /{locale}/portal/{orgSlug}/{role}/osprey now redirects to the assistant route (plan ai-assistant-platform task 020); the workspace described here is the assistant workspace (<P>/assistant/_islands/AssistantWorkspace.tsx).
Roles with the nav item: staff and member. A client and the org-admin persona (public) have no
nav row and get forbidden(). The engine and the router behind it: .
Live transport: .
Components OspreyChat and OspreySessionList no longer exist (removed in plan osprey-playground-v2 task 018).
Deferred in v2 (no task; source plans/osprey-playground-v2/00-protocol-alignment.md): AG-UI adapter endpoint
(POST RunAgentInput to SSE) · AI SDK useChat-compatible BFF route · MCP Apps sandbox lane · follow-up / steer
queue while a run streams (v2: composer is Stop only) · "always allow this category" approvals (needs owner and
security review) · supervisor hook guards · observational memory · per-run thinking-level and model pickers (the v2
meta row is read-only) · error-diff lesson collector · memory compaction · server.drainTimeout · JSON-repair wrapper in
define-tool.ts · RRF fusion and multi-vector Tool-RAG (future plan osprey-tool-rag-v2). Also open: a cancel of
a suspended react approval leaves the Mastra durable snapshot suspended while the log says run.cancelled.
Run graph — measured state (findings/osprey-run-graph/judge/verdict.md, 2026-11-16, not a clean sweep):
the plan-lane rows pass (nodes grow while drafting, data-node-status equals the SQL status per node, keyboard and
detail rows pass, the build sequence and the reject-with-feedback diff pass) and ui-binding passes. Three rows
failed or are unproven and stay open: the react lane showed no data tool in the judge runs, so no llm-step or tool
leaf reached the DOM (AC2 FAIL — a lane/catalogue exposure question, the fold is not implicated); the engine
plan-build-events case bind-failure is model-dependent and flaked 2 of 3 runs (AC13, AC15 FAIL — the fixture's
refusal depends on the draw); and no vitest spec was authored for the fold or the layout budgets (AC4, AC8), while
the live/replay and long-session browser rows could not open a canvas (AC5, AC9) — all NOT PROVEN, tests are opt-in.
Engine capabilities the playground exposes (as shipped, measured on a held-out set; see §Measured results):
Below target. Router accuracy on the held-out set is 0.778 against a 0.90 target (AC4 FAIL; the plan
lane is 0.361). Tool recall@4 is 0.817 against 0.90 (AC8 FAIL). Both stay open for an owner decision. Open
quality gap: a plan step can bind the wrong tool (a "create a follow-up task" step bound to list_tasks in
one browser run), and a mutated plan can end a run without reaching the goal. The org-role permission map
needs owner review.
Page /{locale}/portal/{orgSlug}/{role}/assistant. Roles with the nav item: staff and member. Engine and API detail:
§Assistant platform. Voice transport: §Voice audio transport.
Open findings (plans/ai-assistant-platform/ac-sweep.md): the UI never shows the interrupted state (F3); voice latency
targets not met; unset boolean and number keys show Off or empty on the Voice tab instead of the inherited default (UI1); the
crumb on the Customize page reads "Assistant › Assistant" (UI2).
Additions to section 5d. Engine and API detail: .
Additions to sections 5d and 5e. Setting detail: §Default agent.
A per-specialty, self-hosted diagnosis assistant for doctors and their assistants. Decision record:
; engine design: §Diagnosis engine.
Nav item diagnosis shows for staff (doctors), member (read only) and org-admin; a client sees none.
| Ported specialties | Dermatology and cardiology come from imported IBIS packs (DERM 87 cards, CARD 74 cards; the 12-card seeds are superseded) via osprey dx pack import-ibis; decision record | ddx-osprey-engine/src/diagnosis/ibis-pack-*.ts |
| Treatments | Guidance lists treatment options with regimens per card; estimate values show an "estimate, not clinical evidence" banner | DiagnosisOutputs |
| Drug safety plane | ATC-based checks; blocked or unknown context withholds dose, frequency and duration (fail closed); drug search GET /osprey/diagnosis/drugs | engine safety, osprey-diagnosis-drugs contracts |
| Patient context | Conditions and context feed scoring and safety; missing context is unknown, never assumed | intake |
| Overlays (CLI) | Per-tenant overlays: osprey dx overlay list\|set\|off --tenant; a disabled must-not-miss card stays | ddx-osprey-engine/src/diagnosis/overlay-store.ts |
| Dx chat assistant | Doctors describe a case in chat; the assistant drafts the case, runs the core, answers what-if, explain and compare. The model writes no number: a grounding guard replaces any number the core did not return. Decision record | ddx-osprey-engine/src/diagnosis/, persona "Dudoxx Dx" |
| Knowledge map | Qdrant v2 (dense and sparse, entities); 3D proximity map per run and per specialty with exact cosine (layout approximate). Run map: radial proximity layout by default (distance from the case = the chosen metric; PCA and classical MDS are switches). Math views: 5 normalizations (raw, l2, centred, kind-centred default, whitened) remove the kind islands that raw embeddings show; 7 metrics (cosine default, dot, euclidean, angular, mahalanobis, knn-rank, snn); PCA component triples PC1-3 to PC8-10; case variants (combined, findings, context, per patient) with per-point component decomposition; seriated distance matrix (10-60 points); scree chart. Global map: normalization and PCA/MDS only, no metric. Measured: cold 2.2 s, warm 0.27 s. Not t-SNE or UMAP (stochastic, no global distance meaning). Settings mapMetric, mapNormalization, mapProjection, mapMatrixSize, mapWhitenComponents, labelled points (case, top hypotheses, a settable count of others; a point with no doctor-readable label is not shown), labels drawn in one overlay beside each ball. Detail panel for the selected point (type, cosine, probability, open card). Develop a card or finding to load its neighbours; collapse folds them again with no request. The table below the map mirrors it as a tree with the same develop and collapse. Settings module.diagnosis.mapNeighboursPerKind and mapLabelCount. The map page is a full-height layout from md; from lg it has a controls rail, the 3D stage and a details rail, and both rails collapse (a chevron stacked below lg). The 3D polar grid draws in the --token-viz-guide colour | GET /diagnosis/runs/:runId/vector-map, GET /diagnosis/runs/:runId/vector-map/neighbourhood, GET /diagnosis/map |
| Card folders (CARD) | Cards DDC-CARD-0023 and DDC-CARD-0057 are installed at version 2.0.0 from reviewable card folders (osprey-dx-card/1); clinical review is pending. A card author writes a folder from cited web sources: a new card from a free-text brief, or an upgrade of an installed card (dx cards author --queue or --card <CODE>, or the author page). A run shows its sources, finished parts and partial card while it works, a failed run resumes from its checkpoint, and the end result is a PENDING folder proposal that a different reviewer approves; the author never installs or publishes. Settings module.diagnosis.cardAuthorModel, cardAuthorSourcesPerCard, cardAuthorConcurrency | osprey dx cards install --card <CODE>, ddx-osprey-engine/src/diagnosis/card-folder-install.ts, ddx-osprey-engine/src/diagnosis/card-author/, POST /osprey/diagnosis/card-author/runs |
| Case dossier | Long cited document from run results; search queries are de-identified; a numbers judge checks every figure | POST /diagnosis/runs/:id/dossier |
| Dx MCP server | dx_knowledge_search, dx_card_get, dx_score_case, dx_drug_check for other DDX products | /osprey/mcp/dx |
| Self-curation | Producers (gap, estimate, calibration, pattern, doctor) file PENDING proposals only; reviewer differs from proposer; scheduled jobs are claimed once per window | /diagnosis/proposals, /diagnosis/curator/miners |
| Cockpit v2 (plan osprey-dx-cockpit-ui) | Direction "Split Workbench", the only diagnosis UI (the legacy screens and the module.diagnosis.cockpitUi switch are removed). Screens: case list, new case, case cockpit, card library, card detail, card author, patterns, map, curation, quality. At 1440 px: command column, run strip, then two benches across one seam (doctor side: intake and questions; Osprey side: board and report). At 390 px: command block, doctor side, seam, Osprey side in one scroll. Design record: ddx-web/DESIGN.md "Diagnosis cockpit v2" | diagnosis/_islands/v2/CaseCockpitV2.tsx, components/diagnosis-cockpit/ |
| Command region | Red flags, must-not-miss pins, withheld guidance and the review disclaimer sit in one fixed column (1440 px) or one fixed, open 2 x 2 block on top (390 px). Never in a tab, drawer, popover or collapsed pane. The red-flag card is the only destructive tint of the screen; a blocked run shows in the run strip with a warning tone | CockpitCommandRegion.tsx, cockpit-command-region.ts |
| Seven pane states | Every pane shows one of loading, live, suspended, safetyBlocked, resync (overlay), failed, empty, through one shared frame. Priority: failed, loading, safetyBlocked, suspended, empty, live | CockpitPaneFrame.tsx, cockpit-pane-state.ts |
| Seam | A finding on the doctor side lights up the hypotheses and red flags it drove on the Osprey side. The seam line is 2 px at rest and full primary while linked | SeamDrives.tsx, seam-link.ts |
| Mixed intake and fill-into-draft | The intake pane merges typed fields and the free-text story into one view. Typed values win; a differing extracted value shows as a conflict the doctor picks. A story read in the background fills INTO the open draft and never wipes it. A failed fill shows its reason and a retry. A same-text request on a live draft is a no-op. Route POST /osprey/diagnosis/drafts/:draftId/fill (202, body { text, context? }); the draft record carries intake (origin and conflicts per field) | IntakeMergeView.tsx, IntakePane.tsx, engine draft-fill.ts, ddx-api OspreyDiagnosisController, BFF row /osprey/diagnosis/drafts/:draftId/fill |
| Held items and Analyse | Items mapped by vector similarity stay held. The held list shows under the run frame before the first run; Analyse confirms the ready draft through the one draft board of the cockpit, so the ticks the doctor set enter the run | RunPane.tsx, BoardActs.tsx, use-case-draft-board.ts |
| Board acts file mapping proposals | A concept switch, tick or untick on the board counts as a board signal. At the support floor (module.diagnosis.boardSignalMinSupport) it files one PENDING proposal of kind mapping (concept ids and counts only, proposer system:board-signals). Approval closes it as approved with no card revision and no publish; reject uses the normal path. Table dx_proposal gains the kind and override_reason (migration sql/037) | engine curation/board-signals.ts, curation/proposals.ts, CurationV2.tsx |
| Curation gate result and override | The curation pane shows the gate result with readable diff lines. Approving a change whose gate failed needs a reason: without it ddx-api answers 422 override_required (keyed on the engine status and code, not on message text); with it the reason is stored as overrideReason on the proposal | curation-v2.ts, ddx-api OspreyDiagnosisCurationController, engine DxUnprocessableError |
| Case assistant in v2 | The case chat stays. At 2xl (96 rem) and above the assistant is a resizable side pane; below 2xl a docked bar opens it as a bottom drawer. The header shows an act to open it while it is closed. A chat-made draft shows in the board pane (one draft board) | CaseAssistantV2.tsx, case-assistant-v2.ts |
| Case header | One quiet row: <case number> · <title>, the specialty, the run status word. Below lg it scrolls away above the sticky command block | CaseCockpitV2.tsx |
| Outputs screen (live validation) | The hypothesis table shows the top 10 plus rows at 1 % or more; the rest sits behind "N more below 1 %"; value, interval and bar sit on separate lines. Feedback lists 10 checkboxes plus confirmed picks, with a search box and a "shown of total" status. A safety banner names the red flags that fired (redFlags on the run status; runs made before this change show the banner as before) | DiagnosisOutputs.tsx, DiagnosisSafetyBanner.tsx |
| Case list screen (live validation) | The list no longer shows a "Latest analysis" column (latestRunId is out of the summary projection; the detail and admin projections keep it) | packages/ddx-contracts/src/descriptors/diagnosis-case.ts |
| Card library and card page (live validation) | The list is not windowed (it showed in a 384 px box), shows Updated as a formatted date and the specialty as a readable name. The card page uses the card title as h1 and last crumb, one h3 per body section (19 known keys, others humanised), max-w-prose sections, red flags as the rule label for the locale (raw key muted), and readable evidence links. The "Knowledge cards" eyebrow is removed. The per-specialty card count can read higher than the list for cards with no current revision (D-046; engine gateway-knowledge.ts counts a LEFT JOIN) | DiagnosisCardLibrary.tsx, DiagnosisCardDetail.tsx |
| Map screen (live validation) | Point labels rank selection, then case, then posterior, hide on collision and flip left at the right edge; the polar grid faces the camera. The top list is titled "Most probable diagnoses". The table name cell wraps; the PCA scree sits in the side column. One "Distance settings" popover holds metric, normalization, hints, axes and variant. With no case the legend reads global (no "cosine to the case"). The global map draws every disease and pattern card point; the matrix lists the case and top hypotheses first. Global-map label and metric controls need GlobalMapQuerySchema changes (D-056, blocked) | DiagnosisVectorMap*.tsx, ddx-osprey-engine/src/diagnosis/vector-map*.ts |
| Intake mapping (live validation) | Intake maps a lay phrase to a card concept through retrieval candidates and a two-way word match; the safety reason of a red flag is returned to the doctor. Open: a near-synonym finding can still be re-asked (D-040), and the must-not-miss rule has no catch-all marker (D-043) | ddx-osprey-engine/src/diagnosis/knowledge-store.ts, retrieval.ts |
Not built: FHIR or EHR integration, paid external medical APIs, MDR certification, CSV cohort import, an overlay UI. The public site may stop labelling treatments "planned" (separate lane).
The diagnosis case workspace after the Case Studio plan. Same roles and nav item as section 5g. Engine side: §Diagnosis engine, paragraph Case Studio. Names and numbers: §6.5.
Open quality items from the walks (not part of the plan acceptance): the case pane read view prints ATC codes and allergy class ids; the assistant has no lookup tool for a new drug code; drug safety is "Not checked" where the pack has no profile; red-flag names fall back to keys while a round waits.
Since plan osprey-case-cockpit (section 5o): the case page is a tabbed cockpit with a stage header, so the "Questions" and "Case report" rows above now appear as the Questions and Report tabs. The report pane reads the report by case (GET /osprey/diagnosis/cases/:caseId/runs/:runId/case-report), so a reader who did not start the run sees it; PDF and Markdown export stay on the owner route (…/runs/:runId/case-report/files), and the export buttons are hidden for that reader.
The case draft board of section 5g/5h after the accuracy plan. Same roles and nav item. Engine side: §Diagnosis engine, paragraph Case drafts. Keys: §Draft and mapping keys.
Usage harness (not a product screen): ./ddx-manage.sh usage ... --patient answers questions from the case text only, and each case writes a stage report (mapping, coverage, rank); see ddx-osprey-usage/CLAUDE.md.
Last reconciled: 2026-11-16 · plan osprey-dx-accuracy task 023
The diagnosis of section 5g on a second, Mastra-native run engine, plus the case library and the learning loop. Same roles and nav item; no new page. Engine side: §Diagnosis engine, paragraphs Mastra spine, Learning loop, Assistant tools. Keys: §Mastra spine keys.
State. The spine is built and switchable per org with module.diagnosis.engine (legacy | mastra). The seed
is legacy: every org runs today's pipeline until an org admin switches. The parity, accuracy, time and token runs
have not run yet; no measured number is claimed here.
Usage harness (not a product screen): osprey-usage parity compares a legacy run with a mastra run per case,
osprey-usage signals <runDir> exports stage misses as count-only signals, and suite flow-intake3 drives the mixed
intake end to end; see ddx-osprey-usage/CLAUDE.md.
Last reconciled: 2026-11-17 · plan osprey-mastra-native task 064
The case chat and the main Assistant answer a diagnosis question with artifact cards, not only text. Engine side: §Diagnosis engine, paragraph Artifact tools.
Open items: the vector-map card link opens the global map and ignores ?run=; a ?run= link to an older run of a case does not replace the latest run in the cockpit. The manuals ddx-manuals/osprey-assistant and ddx-manuals/osprey-diagnosis show the old chat and need a re-render.
Cases can be grouped by a subject code or a cohort code, an outcome can be recorded per subject, and the assistant can list the doctor's cases. Same roles and nav item as section 5g. Names and code rules: §6.5b. Engine side: §Diagnosis engine, paragraph Case groups, outcome and case directory. Kernel side: .
Accepted limits: (1) the outcome check runs before the write, so two saves at the same moment can both reach the engine and leave two dx_feedback rows; the second case write answers 409 (the full fix is an engine idempotency key, a later plan). (2) The dx_case_list card stores its rows, titles included, in osprey.event. (3) The report-files list cuts at LIST_QUERY_LIMIT_MAX rows with no truncated flag. (4) The per-entry outcome history list was not walked live; the history link shows after a record. Open items from the walk: the create-group dialog shows a duplicate error twice; the assistant card header repeats "Case list"; the outcome form has two buttons named "Record outcome" and "Current outcome" shows twice when open.
The assistant offers a case, binds voice to a case and learns from recorded outcomes. Wiring map of the four turns: .
Accepted limit: voice number resolution depends on the spoken-form pattern; an unmatched form reaches the model as text.
The Assistant can run a whole case study by chat: open or create a case, answer the question form, see the safety result, get the report as a PDF, record the outcome, look at projects and groups, and propose card changes. Wiring map: . Keys: §Diagnosis keys.
Known limits (open, from the headed walk of plan task 043; none is fixed):
dx_card_propose instead of dx_card_retire. The reviewer (platform super-admin) reaches the Assistant page since 2026-11-18 (section 5o); the review chat cards are not walked there yet.update op. A member who can only read a case gets 403 on every turn of that chat, also for a pure question (section 5o, open points).DiagnosisCardDetail) shows nothing about a retired card; only the chat card does.One stage per case, a tabbed case page, runs that every reader of the case can see, and projects that hold cases. Same roles and nav item as section 5g. Wiring of the Assistant gate: . Keys: §Diagnosis keys.
Open points of the headed walk (plan task 018; not fixed):
x-real-ip for the web trusted client-IP key (deploy/scripts/check-env.sh); the dev BFF sends no node token (a debug line per request).The diagnosis screens act as one product, runs and cases have no dead end, and the Assistant can do what the UI can do, by proposal card. Same roles and nav item as section 5g. Wiring of the tools: . Push hints: "System hints". Keys: .
Deploy order (open item for the release): run pnpm osprey db migrate in the engine before the new engine code (sql/045); add DDX_API_CENTRIFUGO_CLIENT_URL to the server ddx-api.env; restart Centrifugo for the new namespace system; run pnpm install (ddx-api gains the centrifuge client).
Open points (from the plan walk, not fixed):
dx_ask_more and dx_question_propose show a live-run refusal with the generic failure text, not the fixed DX_RUN_ACTIVE wording.Last reconciled: 2026-11-18 · plan osprey-cockpit-hardening task 021 (sections 5n, 5o, 5p)
adr/
deploy/
research/