Fuente: 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](/es/docs/shell-tree), [patterns.md](/es/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: full-bleed scene hero with the floating illustrative report, chapter bands (facts, how it works, knowledge, capabilities, specialties, privacy, FAQ) and a full-bleed closing band; no in-page anchor bar. The FAQ is visible text and feeds the FAQPage structured data | `/{locale}` | `ddx-web/src/components/site/home/SiteHomeSections.tsx`, `components/site/{SiteHero,SiteChapters}.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, a scene plate, chapters, a FAQ where it applies, and a closing band. 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` | | Imagery: 8 generated scene images (hero, engine, knowledge, reports, trust, 3 specialties), AVIF and WebP at 800 and 1600 px. No patient data, no identifiable faces. Prompts and provenance table: `ddx-web/site-assets/prompts/README.md` and `ddx-web/public/site/illustrations/README.md` | marketing pages | `ddx-web/public/site/img/`, `ddx-web/site-assets/prompts/` | | 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 | 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](/es/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](/es/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](/es/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](/es/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](/es/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](/es/docs/osprey-engine). Live transport: [realtime.md](/es/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](/es/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](/es/docs/osprey-engine) §Assistant platform. Voice transport: [realtime.md](/es/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](/es/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](/es/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](/es/docs/adr/0021-diagnosis-engine); engine design: [osprey-engine.md](/es/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](/es/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](/es/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` | `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](/es/docs/osprey-engine) §Diagnosis engine, paragraph Case Studio. Names and numbers: [naming-constitution.md](/es/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. ## 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](/es/docs/osprey-engine) §Diagnosis engine, paragraph Case drafts. Keys: [settings.md](/es/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](/es/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](/es/docs/osprey-engine) §Diagnosis engine, paragraphs Mastra spine, Learning loop, Assistant tools. Keys: [settings.md](/es/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_*` | | 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](/es/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 ## 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](/es/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](/es/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](/es/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](/es/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](/es/docs/deploy/README), quick path [deploy/CHECKLIST.md](/es/docs/deploy/CHECKLIST); targets `context/DEPLOY_TARGETS.md` | --- Last reconciled: 2026-11-17 · plan osprey-dx-cockpit-ui task 049 (cockpit v2 rows, section 5g)
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 | 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.
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
Last reconciled: 2026-11-17 · plan osprey-dx-cockpit-ui task 049 (cockpit v2 rows, section 5g)
adr/
deploy/
research/