Quelle: ddx-documentation/settings.md
One registry, three stored tiers, resolved once in ddx-api. Decision record: [ADR 0014](/de/docs/adr/0014-unified-settings). Task router row: `CLAUDE_TASK_FLOWS.md` row 4. ## Where settings live | Layer | Path | Role | |---|---|---| | Registry | `packages/ddx-contracts/src/settings.ts` | `SETTING_SCHEMAS` (Zod), `SETTING_DEFAULTS`, `SETTING_REGISTRY` (category + tier ACL) | | API mirror | `ddx-api/src/settings/settings.schemas.ts` | `satisfies`-locked to the registry: a drift fails typecheck | | Resolver | `ddx-api/src/settings/settings.resolver.ts`, `settings.service.ts` | merges the tiers; the only merge in the stack | | Org / user routes | `ddx-api/src/settings/settings.controller.ts` | `/orgs/:orgSlug/settings` (`/effective`, `/me/:key`) | | Platform routes | `ddx-api/src/settings/platform-settings.controller.ts` | GET `/platform/settings`, PATCH `/platform/settings/:key` | | Public branding read | `ddx-api/src/settings/platform-branding.controller.ts` | GET `/platform/branding` (anonymous, platform tier only; see Branding keys) | | Web facade | `ddx-web/src/components/providers/SettingsProvider.tsx` | `UnifiedSettingsProvider` (one query per org) | | Web hook | `ddx-web/src/lib/settings/use-unified-setting.ts` | `useUnifiedSetting(key)` → `{ setting, value, editable, pending, update }` | | Labels | `ddx-web/messages/{en,fr,de,es}/settings.json` | `settings.registry.keys.*`, `settings.registry.options.*` | | Seed | `ddx-api/prisma/seed/seed-main.ts` | `seedPlatformSettings()` writes one platform row per key from `SETTING_DEFAULTS` | ## Key shape `<scope>.<group>.<key>`. Scopes: `platform`, `site`, `portal`, `module.<moduleId>`. The group is one of `SETTING_CATEGORIES` (`locale`, `features`, `notifications`, `display`, `branding`, `assistant`). The `assistant.*` keys use the scope `assistant` with no `portal.` prefix (section Assistant keys). A `module.<moduleId>.<key>` key has no group segment; its registry entry declares the category. Examples: `portal.display.themeMode`, `portal.display.density` (`compact` | `cosy` | `large`, rows only), `portal.display.textSize` (`sm` | `md` | `lg`, type only), `portal.features.ai`, `portal.branding.palette`, `module.demo-entities.viewMode`. ## Tier and resolve model Resolve order, lowest first: **code → platform → org → user**. 1. **Code** — `SETTING_DEFAULTS` overlaid with the env model `DUDOXX_MODEL_NAME` (task 005). It answers when a key has no valid stored row, and `source` is then `code`. The env model counts only when it is a current `dudoxx` router alias; a retired or unknown alias yields `''`. A process env value beats `ddx-api/.env`. The code tier is read per request (`ddx-api/src/settings/settings-env-defaults.ts`) and is never cached. 2. **Platform** — one `PlatformSetting` row per key. Only a platform super-admin edits it, only through GET / PATCH `/platform/settings[/:key]`. PATCH needs the current `version` (optimistic lock). No org role can write this tier. 3. **Org** — the org row. Read / edit roles come from `SETTING_REGISTRY[key].tiers.org`. 4. **User** — only when the key declares `tiers.user`. Read / edit roles come from there. `source` on `GET settings/effective` is one of `SETTING_SOURCES` = `platform` · `org` · `user` · `code`. The stored tiers stay `SETTING_TIERS` (`platform|org|user`); only `source` can be `code`. ddx-api resolves the tiers once and serves the effective value. ddx-web never merges tiers, never keeps a second store, and never reads a preference from a cookie or localStorage as the source while the facade is mounted (a cookie may only cache the facade value). On a change, ddx-api emits `settings.changed` on the SSE bus with the **key and version only** — never the value. ddx-web maps it to the query key `['org', orgId, 'settings']` and refetches through the BFF. ## Snapshot cache ddx-api caches the stored rows of one tier per Redis key, never the merged tree and never the code tier. Keys `ddx:settings:snap:*` (`SETTINGS_REDIS_KEYS`: platform, org by `orgId`, user by `orgId` + `userId`), TTL 60 s. A write invalidates its own tier after the DB commit; a platform write clears every snapshot. Redis down or a Redis error reads the DB. The merge and the code tier run on every request. ## Org-write fix report `PATCH /orgs/:orgSlug/settings/:key` auto-fixes a conflicting write and says so. The answer is `{ data, fixes }` (`fixes` beside `data`, always present, empty when nothing changed). Each entry is a `SettingFixReportEntry` with `key`, `reason`, and `from` / `to` (`requestedKey` for a rename). Every fix also writes the audit action `org-setting.conflict-fix`. | `reason` | Trigger | Result | |---|---|---| | `renamed-key` | key listed in `SETTING_KEY_RENAMES` (the 5 renames of ADR 0014 Addendum 2026-10-25) | stored under the new key | | `retired-value` | value listed in `SETTING_RETIRED_VALUES` (`assistant.llm.model`: legacy router aliases, `dudoxx-embed`, `dudoxx-ocr`; provider keys: none today) | replaced by the valid platform row, else the code tier | Both tables are `NEEDS_REVIEW` (`packages/ddx-contracts/src/settings-conflicts.ts`). User and platform writes are not fixed. `assistant.llm.model` stores `''` (inherit) or a provider-prefixed id as `GET /osprey/models` lists it (`dudoxx/dudoxx-prod`). Retired-alias matching strips only the `dudoxx/` prefix. Env key names: `DUDOXX_MODEL_NAME` is listed in `ddx-api/ENV_VARIABLES.md` and in the ddx-api `EnvSchema`. ## Branding keys Five keys in category `branding` (plan `tenant-branding`, [ADR 0019](/de/docs/adr/0019-tenant-branding)). Each has a platform default and an org override; none has a user tier. Org tier: everyone reads, only `org-admin` edits. Platform tier: only platform `super-admin` edits. | Key | Schema | Default | Org tier | |---|---|---|---| | `portal.branding.displayName` | object `{ en?, fr?, de?, es? }`, each 1-48 chars, strict | `{}` (empty: the messages name `site.brand.name`) | read all · edit `org-admin` | | `portal.branding.palette` | `dudoxx` · `neutral` · `solace-grid` · `verdant-loop` | `dudoxx` | read all · edit `org-admin` | | `portal.branding.font` | `dudoxx` · `editorial` · `serif` | `dudoxx` | read all · edit `org-admin` | | `portal.branding.illustration` | `signal` · `grid` · `orbit` · `none` | `signal` | read all · edit `org-admin` | | `portal.branding.logo` | object `{ mode: platform \| generated \| upload, style: monogram-circle \| monogram-square \| wordmark }` | `{ mode: platform, style: monogram-square }` | read all · edit `org-admin` | Values are ids, never a colour or a font family. A palette id is the `data-brand` value of a vendored brand file; a font id is a `data-font` pair (`dudoxx` = Urbanist, `editorial` = Fraunces, `serif` = Source Serif 4). - **Public read**: `GET /platform/branding` returns `{ data: PlatformBranding }`, the five platform-tier values only (strict projection). The route is anonymous (`@Public()`), and the BFF lists `/platform/branding` in `PUBLIC_PATHS`, so the site and `/auth` read it without a session. ddx-web reads it cookie-less through `callUpstream` (`'use cache'`, tag `platform-branding`); a platform write to a branding key revalidates that tag. - **Editors**: the platform page (`/{locale}/platform/settings`) has a typed editor per key. The org settings page has a branding section with a live preview, and the new-tenant wizard (`<P>/settings/branding`) edits the same keys step by step. - **Portal fallback**: when an org never set `portal.branding.displayName` or `.logo` at org tier, the portal shows the org name and the uploaded org logo, else a mark generated from the org name. It never shows the platform name or logo; those stay on the site scope. - **Theme writer**: `BrandThemeScope` (`ddx-web/src/components/providers/BrandingProvider.tsx`) is the one writer of `<html data-brand|data-font>`. It is a layer stack: site scope, tenant scope, and a `preview` layer for a draft (the wizard). ## Assistant keys Twenty-four keys in category `assistant` (plans ai-assistant-platform, osprey-assistant-v2 and osprey-ux-overhaul). ddx-api sends all of them to the engine as base64url(JSON) in the `x-osprey-settings` header (no secret in any value, 12 KB cap). They have a platform default, an org override and, unless noted, a user override. Edit UI: `<P>/settings/assistant` (Personal and Organization tabs; sections llm, voice, persona, memory, files). | Key | Value | Default | Org tier | User tier | |---|---|---|---|---| | `assistant.llm.model` | registry model id; empty = engine default | `''` | read all, edit `org-admin` | yes | | `assistant.llm.effort` | `off` · `low` · `medium` · `high` · `max` | `off` | read all, edit `org-admin` | yes | | `assistant.voice.stt.provider` | `ddx-omni` · `deepgram` · `deepgram-onprem` | `ddx-omni` | read all, edit `org-admin` | NO (review 050 M1) | | `assistant.voice.tts.provider` | `ddx-omni` · `deepgram` · `inworld` · `murf` · `openrouter` · `elevenlabs` · `kyutai` | `ddx-omni` | read all, edit `org-admin` | NO (review 050 M1) | | `assistant.voice.tts.voice` | provider voice id; empty = provider default | `''` | read all, edit `org-admin` | yes | | `assistant.voice.turnDetection` | `{semanticEot, silenceShortMs, silenceLongMs, fillerGate, bargeIn}` | see `SETTING_DEFAULTS` | read all, edit `org-admin` | yes | | `assistant.voice.fallbackOrder` | ordered provider ids tried after a failure | `['deepgram']` | read all, edit `org-admin` | NO (review 050 M1) | | `assistant.persona.defaultId` | persona id or null | `null` | read all, edit `org-admin` | yes | | `assistant.agent.defaultId` | agent id or null; null = no default agent | `null` | read all, edit `org-admin` | yes | | `assistant.instructions` | `{aboutMe, howToAnswer}`, each at most 3000 UTF-8 bytes | empty strings | read all, edit `org-admin` | yes | | `assistant.style.tone` | `neutral` · `friendly` · `concise` · `formal` | `neutral` | read all, edit `org-admin` | yes | | `assistant.memory.enabled` | boolean | `true` | read all, edit `org-admin` | yes | | `assistant.files.maxBytes` | integer, at most 100 MiB | 20 MiB | read all, edit `org-admin` | NO | | `assistant.files.allowedKinds` | subset of `image` · `document` · `attachment` | all three | read all, edit `org-admin` | NO | | `assistant.llm.temperature` | number 0-2 | `0.7` | read all, edit `org-admin` | yes | | `assistant.llm.topP` | number 0-1 | `0.95` | read all, edit `org-admin` | yes | | `assistant.llm.topK` | integer 1-200 | `20` | read all, edit `org-admin` | yes | | `assistant.llm.maxOutputTokens` | integer 64-32768; clamped by the engine to the alias cap | `4096` | read all, edit `org-admin` | yes | | `assistant.llm.thinkingBudget` | integer 0-32768 token budget; 0 = thinking off; applies only when effort is `off` | `0` | read all, edit `org-admin` | yes | | `assistant.llm.mode` | `auto` · `chat` · `react` · `plan` (pins the lane; `auto` routes as before; a body lane wins) | `auto` | read all, edit `org-admin` | yes | | `assistant.voice.stt.language` | BCP-47 tag; empty = auto-detect | `''` | read all, edit `org-admin` | yes | | `assistant.voice.stt.smartFormat` | boolean | `true` | read all, edit `org-admin` | yes | | `assistant.voice.stt.keywords` | list of boosted terms, at most 600 UTF-8 bytes | `[]` | read all, edit `org-admin` | yes | | `assistant.voice.stt.endpointingMs` | integer milliseconds 10-5000 | `300` | read all, edit `org-admin` | yes | Which vendor receives patient audio is an org-admin decision, so the STT provider, the TTS provider and the fallback order are org-tier only (review 050 M1: `settings.ts` registry and `ddx-api/src/settings/settings.schemas.ts`). The engine also ignores a `start` message override of the providers. Platform page: scalar keys have inputs; the four structured keys (`turnDetection`, `fallbackOrder`, `instructions`, `allowedKinds`) show the platform seed read-only and are edited on the org settings page. The ten `assistant.llm.*` and `assistant.voice.stt.{language,smartFormat,keywords,endpointingMs}` keys travel in the same `x-osprey-settings` header (worst case about 9.2 KB of JSON, under the 12 KB cap). The engine applies the `llm` keys per turn and records them on `run.started.requestMeta`; the STT keys tune the Deepgram adapters. `GET /osprey/voice/stt-status` shows which STT provider is enabled, configured and healthy (org-admin sees every provider, other roles only the effective pick). Voice provider keys are engine env keys, not settings: [osprey-engine.md](/de/docs/osprey-engine) §Environment key names. ### Default agent (plan osprey-ux-overhaul) `assistant.agent.defaultId` has the same tiers as `assistant.persona.defaultId`: a platform default of `null`, an org override edited by `org-admin`, and a user override. The Settings page lists only enabled agents (org tier: org-scope agents only). An empty choice stores `null`. Engine fallback order for the agent of a turn: the agent in the turn body, then `assistant.agent.defaultId`, then no agent. A settings default is used only if it resolves to a runnable agent (visible, enabled, plugin enabled). If it does not resolve, the engine logs a warning and runs the turn without an agent. An agent id named in the turn body is never replaced by the default. The seeder sets the persona default at org tier (the org's "Osprey" persona); the agent default is opt-in (`--set-default-agent`), because a narrow seed agent as the org default hides tools from every new chat. Opt out with `--no-set-default-persona` and `--no-set-default-agent` (see `ddx-seeder/README.md`). The seeder skips a key whose org tier already holds a value, so an admin's choice is never overwritten. ## Diagnosis keys (plan diagnosis-engine) Keys `module.diagnosis.<key>` (the nineteen below, plus later additions), category `diagnosis`, platform default, org override (read `staff`, edit `org-admin`), no user tier (one threshold set per org). ddx-api sends them to the engine in the BODY of a run start or curator tick as `DxSettings`, never in `x-osprey-settings` (the engine rejects unknown header keys). The curator scheduler and the manual tick use the PLATFORM tier. Code constants are seeds only. | Key | Value | Default | |---|---|---| | `module.diagnosis.model` | Dudoxx router alias: `dudoxx-prod` · `dudoxx-forge` · `dudoxx-gemma` (never an OpenRouter id) | `dudoxx-prod` | | `module.diagnosis.lambdaAbsent` | weight of an absent finding in the likelihood score, 0-1 | `0.5` | | `module.diagnosis.gammaPrior` | exponent on the condition prior, 0-10 | `1` | | `module.diagnosis.pinFloor` | minimum posterior that keeps a pinned condition listed, 0-1 | `0.15` | | `module.diagnosis.trigramMin` | trigram similarity floor for a lexical concept match, 0-1 | `0.85` | | `module.diagnosis.vectorMin` | cosine floor for a vector concept match, 0-1 | `0.8` | | `module.diagnosis.rrfK` | reciprocal-rank-fusion constant k, 1-500 | `60` | | `module.diagnosis.retrievalTopK` | candidates kept per retrieval lane, 1-200 | `20` | | `module.diagnosis.maxRounds` | question rounds per run, 1-10 | `3` | | `module.diagnosis.roundTokenBudget` | model token budget of one round, 1000-1000000 | `60000` | | `module.diagnosis.stopPosterior` | top posterior that ends the question loop, 0-1 | `0.85` | | `module.diagnosis.eigEpsilon` | expected information gain below which no question is asked, 0-1 | `0.02` | | `module.diagnosis.mcSamples` | Monte Carlo samples of the information-gain estimate, 10-10000 | `500` | | `module.diagnosis.cohortMaxPatients` | patients in one cohort run, 1-200 | `25` | | `module.diagnosis.curatorEnabled` | curator schedule on or off | `false` | | `module.diagnosis.curatorIntervalMinutes` | minutes between curator ticks, 5-10080 | `1440` | | `module.diagnosis.curatorCardsPerTick` | cards one curator tick may draft, 1-50 | `3` | | `module.diagnosis.feedbackMinSupport` | doctor feedback items needed before a card change is proposed, 1-1000 | `5` | | `module.diagnosis.gateTop5Tolerance` | allowed top-5 accuracy drop of a candidate card set on the gold set, 0-1 | `0.02` | The table lists the first nineteen keys. Later plans added more `module.diagnosis.*` keys (map settings, miners, card author); the registry `packages/ddx-contracts/src/settings.ts` is the full list. ### Draft and mapping keys (plan osprey-dx-accuracy) Six more `module.diagnosis.*` keys, same rules as above (category `diagnosis`, platform default, org override; read `staff`, edit `org-admin`). Five reach the engine through `DxSettings`; `draftWatchPollSeconds` is read by ddx-api only. | Key | Value | Default | |---|---|---| | `module.diagnosis.conceptMatchTopK` | vector hits the concept-match step judges per mention, 1-200 | `40` | | `module.diagnosis.conceptMatchCandidates` | candidates concept-match offers per mention, 1-50 | `15` | | `module.diagnosis.conceptMatchNoteChars` | characters of the scrubbed case note given to concept-match, 0-20000 (0 = no note) | `6000` | | `module.diagnosis.draftAlternatives` | alternatives carried per draft item, 0-10 | `3` | | `module.diagnosis.draftStaleMinutes` | minutes after which a pending draft fill reads `failed` (`stale`), 1-120; also the give-up time of the ddx-api draft watch | `10` | | `module.diagnosis.draftWatchPollSeconds` | seconds between two ddx-api polls of a pending draft, 1-60 | `2` | ### Case report keys (plan osprey-case-studio) Two more `module.diagnosis.*` keys, same rules as above (category `diagnosis`, platform default, org override; read `staff`, edit `org-admin`). They shape the case report of a single case and of a cohort. | Key | Value | Default | |---|---|---| | `module.diagnosis.caseReportSections` | list of sections the report prints, at least one: `summary` · `intake` · `diagnoses` · `questions` · `safety` · `treatment` · `drugs` · `glossary` · `citations` | all nine | | `module.diagnosis.caseReportFormat` | format the export starts with: `pdf` or `markdown` | `pdf` | The decision-support disclaimer is not a section: it always prints, last. A section that is switched off is left out of both the Markdown and the PDF. The format key only decides which download is the main button; both files stay available. Vocabularies: `SETTING_CASE_REPORT_SECTIONS` and `SETTING_CASE_REPORT_FORMATS` in `packages/ddx-contracts/src/settings.ts`. The cohort size cap `module.diagnosis.cohortMaxPatients` (default 25, 1-200) is read from the effective setting; when a start has more patients than the cap, the case screen says "Too many patients. The limit is N." ### Card author keys (plan dx-card-kb) Same tiers as above (platform default, org override, read `staff`, edit `org-admin`, no user tier). The browser never sends them: ddx-api reads them with one `getEffective` read and puts them in the author run-start body as `{ model, sourcesPerCard, concurrency }` (`ddx-api/src/osprey/osprey-diagnosis-card-author.controller.ts`). | Key | Value | Default | |---|---|---| | `module.diagnosis.cardAuthorModel` | chat router alias that writes the card: `dudoxx-prod` · `dudoxx-forge` · the `or-*` chat aliases listed in `SETTING_CARD_AUTHOR_MODELS`. Card authoring carries no patient data, so `or-*` is allowed here (unlike `module.diagnosis.model`) | `dudoxx-prod` | | `module.diagnosis.cardAuthorSourcesPerCard` | fetched sources one run reads per card, 3-40 | `12` | | `module.diagnosis.cardAuthorConcurrency` | cards the author workflow writes in parallel, 1-8 | `2` | ### Mastra spine keys (plan osprey-mastra-native) Eighteen new `module.diagnosis.*` keys, same tiers as above (category `diagnosis`, platform default, org override, read `staff`, edit `org-admin`, no user tier). All reach the engine in the run-start body as `DxSettings` and freeze on the run row. Four layers carry each key: `packages/ddx-contracts/src/settings.ts` (+ `DxSettingsSchema`), `ddx-api/src/settings/settings.schemas.ts`, the 4 locale label files and the web field spec (`fields-platform.ts`). | Key | Value | Default | |---|---|---| | `module.diagnosis.engine` | run engine: `legacy` (workflow `osprey-diagnosis`) or `mastra` (workflow `osprey-dx-spine`); the stored run value decides for the run's whole life | `legacy` | | `module.diagnosis.agentHypothesisTopN` | hypotheses a spine agent sees, 1-50 | `5` | | `module.diagnosis.agentEvidencePerHypothesis` | evidence items per hypothesis a spine agent sees, 1-50 | `6` | | `module.diagnosis.deepReasonTopN` | hypotheses given to deep reasoning, 1-30 (seed = the former `DEEP_TOP` const) | `10` | | `module.diagnosis.agentMaxSteps` | agent steps per spine agent call, 1-20 | `4` | | `module.diagnosis.agentToolCallCap` | tool calls per spine agent call, 1-20 (the tool guard refuses the next one) | `3` | | `module.diagnosis.runInputTokenBudget` | input token budget of one run, 1000-1000000; `overBudget` in `result.budget` | `60000` | | `module.diagnosis.ingestChunkStrategy` | v3 card chunk strategy: `markdown` or `recursive` | `markdown` | | `module.diagnosis.ingestChunkMaxChars` | characters of one chunk, 200-8000 | `1200` | | `module.diagnosis.ingestChunkOverlap` | characters of overlap between chunks, 0-1000 | `100` | | `module.diagnosis.ingestExtract` | one-time keyword + question extract per new chunk | `true` | | `module.diagnosis.graphRagThreshold` | similarity threshold of the GraphRAG chunk walk, 0-1 | `0.7` | | `module.diagnosis.crossCaseRecall` | cross-case recall on case-scoped assistant turns | `true` | | `module.diagnosis.crossCaseRecallTopK` | recalled past-case items kept, 0-20 (0 = none) | `3` | | `module.diagnosis.recallLastMessages` | last messages kept in agent memory recall, 0-50 | `10` | | `module.diagnosis.similarCasesTopK` | similar past cases a search returns, 1-20 | `5` | | `module.diagnosis.boardSignalMinSupport` | board signals needed before a final diagnosis files a feedback proposal, and before a board concept act (switch, tick, untick) files a PENDING `mapping` proposal, 1-1000 | `3` | | `module.diagnosis.closedLoopRankTolerance` | gold-card rank loss per case the closed-loop check accepts, 0-10 (0 = exact) | `0` | Changed keys of earlier plans: - `module.diagnosis.rerankMode` gains `mastra` (Mastra `rerankWithScorer`); values are now `mmr` · `none` · `mastra` · `router:<alias>`; seed stays `mmr`. - `module.diagnosis.caseIndexEnabled` seed changes from `false` to `true`. - `module.diagnosis.draftWatchPollSeconds` (§Draft and mapping keys) is now also in `DxSettingsSchema`: the `dx_analyze_case` relay reads it from the run's frozen settings, then falls back to the seed. - `module.diagnosis.boardSignalMinSupport` now also gates the `mapping` proposal that board concept acts file (plan osprey-dx-cockpit-ui, features.md section 5g). - `module.diagnosis.cockpitUi` (cockpit switch, values `legacy` | `v2`) was added and removed inside plan osprey-dx-cockpit-ui. No row, no seed: the v2 cockpit is the only diagnosis UI. The legacy path and the `engine` key stay until the parity gate passes; the spine is not the default (seed `legacy`). ## Assistant values that are not settings (plan osprey-assistant-v3) The plan added no `assistant.*` key. These values sit outside the registry: | Value | Where it lives | Notes | |---|---|---| | Image model alias | engine env `OSPREY_IMAGE_MODEL` (`ddx-osprey-engine/.env`) | Prerequisite for `generate_image`: the alias (live: `dudoxx-image`) must be registered in the LiteLLM router that `DUDOXX_BASE_URL` points at. A blank or unregistered alias gives a `tool_unavailable` error naming the key. No price row exists for `dudoxx-image` yet, so image calls are unpriced | | Voice language | the UI locale, sent as `start.language` on the voice socket | Pins STT and reply language for the stream. Fallback is engine env `OSPREY_VOICE_LANGUAGE` (default de). The org tuning `assistant.voice.stt.language` is overridden while a language is pinned | | Document look | `OSPREY_DOCUMENT_PRESET` in `@ddx/contracts/osprey-document-preset` | One preset (`dudoxx`) shared by `generate_pdf`, `generate_docx` and the PDF viewer; not editable per org | | Model prices | ddx-api `ai` schema tables `ModelPrice` and `ModelPriceRevision` | Platform-wide per router alias; edited by the platform super-admin on the consumption price page. An unpriced alias gives cost NULL, shown as "no price". Usage events land in `OspreyUsageEvent` | ## Add a setting key 1. **Registry entry** in `packages/ddx-contracts/src/settings.ts`: - the key with its scope segment (`portal.<group>.<key>` or `module.<moduleId>.<key>`); - the Zod schema in `SETTING_SCHEMAS` (enum tuples as an exported `SETTING_*` const); - the default in `SETTING_DEFAULTS`; - the ACL in `SETTING_REGISTRY`: `category`, `tiers.org` (`read` / `edit` roles) and, when users may override it, `tiers.user`. 2. **API mirror** — add the same key to `ddx-api/src/settings/settings.schemas.ts`. The `satisfies` lock fails typecheck (lead-run) when the two drift. 3. **Labels in 4 locales** — `settings.registry.keys.<name>.label` and `.description`, plus `settings.registry.options.<name>.<value>` for each enum value, in `ddx-web/messages/{en,fr,de,es}/settings.json` (`<name>` = the last key segment, e.g. `themeMode`). All four files in the same change. A key shown on the portal settings page also adds its label keys to the typed union in `ddx-web/src/app/[locale]/(app)/portal/[orgSlug]/[role]/settings/_islands/model.ts`. 4. **UI control (optional)** — read and write it with `useUnifiedSetting('<key>')` inside `UnifiedSettingsProvider`. Use `editable` to disable the control and `update(value)` to write; the hook does the optimistic PATCH and the rollback. Compose the control from inventory entries (`@/inventory/<family>`), never a raw UI import in a page. 5. **Seed** — nothing to write. `seedPlatformSettings()` iterates `SETTING_KEYS` and creates the missing platform row from `SETTING_DEFAULTS` (create-only; a re-seed never overwrites an operator edit). No migration: the tiers are generic rows, never a per-key table. 6. **Gates** — `./ddx-manage.sh i18n` (labels) and `./ddx-manage.sh kernel` (regression guard) exit 0. Lint and typecheck run once by the lead at `/unify`. ## Never - A second settings store, a per-key table or a tier merge in ddx-web. - A setting value in an SSE payload. - A platform-tier write from any role but platform super-admin. - A label outside `ddx-web/messages/{en,fr,de,es}/`. --- Last reconciled: 2026-11-17 · plan osprey-dx-cockpit-ui task 049 (boardSignalMinSupport, cockpitUi removed)
One registry, three stored tiers, resolved once in ddx-api. Decision record:
. Task router row: CLAUDE_TASK_FLOWS.md row 4.
<scope>.<group>.<key>. Scopes: platform, site, portal, module.<moduleId>.
The group is one of SETTING_CATEGORIES (locale, features, notifications, display, branding, assistant).
The assistant.* keys use the scope assistant with no portal. prefix (section Assistant keys).
A module.<moduleId>.<key> key has no group segment; its registry entry declares the category.
Examples: portal.display.themeMode, portal.display.density (compact | cosy | large, rows only),
portal.display.textSize (sm | md | lg, type only),
portal.features.ai, portal.branding.palette, module.demo-entities.viewMode.
Resolve order, lowest first: code → platform → org → user.
SETTING_DEFAULTS overlaid with the env model DUDOXX_MODEL_NAME (task 005). It answers
when a key has no valid stored row, and source is then code. The env model counts only when it is
a current dudoxx router alias; a retired or unknown alias yields ''. A process env value beats
ddx-api/.env. The code tier is read per request (ddx-api/src/settings/settings-env-defaults.ts)
and is never cached.PlatformSetting row per key. Only a platform super-admin edits it,
only through GET / PATCH /platform/settings[/:key]. PATCH needs the current version
(optimistic lock). No org role can write this tier.SETTING_REGISTRY[key].tiers.org.tiers.user. Read / edit roles come from there.source on GET settings/effective is one of SETTING_SOURCES = platform · org · user · code.
The stored tiers stay SETTING_TIERS (platform|org|user); only source can be code.
ddx-api resolves the tiers once and serves the effective value. ddx-web never merges tiers, never keeps a second store, and never reads a preference from a cookie or localStorage as the source while the facade is mounted (a cookie may only cache the facade value).
On a change, ddx-api emits settings.changed on the SSE bus with the key and version
only — never the value. ddx-web maps it to the query key ['org', orgId, 'settings']
and refetches through the BFF.
ddx-api caches the stored rows of one tier per Redis key, never the merged tree and never the code tier.
Keys ddx:settings:snap:* (SETTINGS_REDIS_KEYS: platform, org by orgId, user by orgId + userId),
TTL 60 s. A write invalidates its own tier after the DB commit; a platform write clears every snapshot.
Redis down or a Redis error reads the DB. The merge and the code tier run on every request.
PATCH /orgs/:orgSlug/settings/:key auto-fixes a conflicting write and says so. The answer is
{ data, fixes } (fixes beside data, always present, empty when nothing changed). Each entry is a
SettingFixReportEntry with key, reason, and from / to (requestedKey for a rename).
Every fix also writes the audit action org-setting.conflict-fix.
Both tables are NEEDS_REVIEW (packages/ddx-contracts/src/settings-conflicts.ts). User and platform writes are not fixed.
assistant.llm.model stores '' (inherit) or a provider-prefixed id as GET /osprey/models lists it
(dudoxx/dudoxx-prod). Retired-alias matching strips only the dudoxx/ prefix. Env key names:
DUDOXX_MODEL_NAME is listed in ddx-api/ENV_VARIABLES.md and in the ddx-api EnvSchema.
Five keys in category branding (plan tenant-branding, ).
Each has a platform default and an org override; none has a user tier. Org tier: everyone reads,
only org-admin edits. Platform tier: only platform super-admin edits.
Values are ids, never a colour or a font family. A palette id is the data-brand value of a
vendored brand file; a font id is a data-font pair (dudoxx = Urbanist, editorial = Fraunces,
serif = Source Serif 4).
GET /platform/branding returns { data: PlatformBranding }, the five
platform-tier values only (strict projection). The route is anonymous (@Public()), and the BFF
lists /platform/branding in PUBLIC_PATHS, so the site and /auth read it without a session.
ddx-web reads it cookie-less through callUpstream ('use cache', tag platform-branding); a
platform write to a branding key revalidates that tag./{locale}/platform/settings) has a typed editor per key. The org
settings page has a branding section with a live preview, and the new-tenant wizard
(<P>/settings/branding) edits the same keys step by step.portal.branding.displayName or .logo at org tier,
the portal shows the org name and the uploaded org logo, else a mark generated from the org name.
It never shows the platform name or logo; those stay on the site scope.BrandThemeScope (ddx-web/src/components/providers/BrandingProvider.tsx) is
the one writer of <html data-brand|data-font>. It is a layer stack: site scope, tenant scope, and
a preview layer for a draft (the wizard).Twenty-four keys in category assistant (plans ai-assistant-platform, osprey-assistant-v2 and osprey-ux-overhaul). ddx-api sends all of them to the engine as
base64url(JSON) in the x-osprey-settings header (no secret in any value, 12 KB cap). They have a platform default,
an org override and, unless noted, a user override. Edit UI: <P>/settings/assistant (Personal and Organization tabs;
sections llm, voice, persona, memory, files).
Which vendor receives patient audio is an org-admin decision, so the STT provider, the TTS provider and the fallback
order are org-tier only (review 050 M1: settings.ts registry and ddx-api/src/settings/settings.schemas.ts). The engine
also ignores a start message override of the providers. Platform page: scalar keys have inputs; the four structured keys
(turnDetection, fallbackOrder, instructions, allowedKinds) show the platform seed read-only and are edited on the org
settings page. The ten assistant.llm.* and assistant.voice.stt.{language,smartFormat,keywords,endpointingMs} keys travel in the same
x-osprey-settings header (worst case about 9.2 KB of JSON, under the 12 KB cap). The engine applies the llm keys per turn and records them on
run.started.requestMeta; the STT keys tune the Deepgram adapters. GET /osprey/voice/stt-status shows which STT provider is enabled,
configured and healthy (org-admin sees every provider, other roles only the effective pick). Voice provider keys are engine env keys, not settings: §Environment key names.
assistant.agent.defaultId has the same tiers as assistant.persona.defaultId: a platform default of null, an org override edited by org-admin, and a user override. The Settings page lists only enabled agents (org tier: org-scope agents only). An empty choice stores null.
Engine fallback order for the agent of a turn: the agent in the turn body, then assistant.agent.defaultId, then no agent. A settings default is used only if it resolves to a runnable agent (visible, enabled, plugin enabled). If it does not resolve, the engine logs a warning and runs the turn without an agent. An agent id named in the turn body is never replaced by the default.
The seeder sets the persona default at org tier (the org's "Osprey" persona); the agent default is opt-in (--set-default-agent), because a narrow seed agent as the org default hides tools from every new chat. Opt out with --no-set-default-persona and --no-set-default-agent (see ddx-seeder/README.md). The seeder skips a key whose org tier already holds a value, so an admin's choice is never overwritten.
Keys module.diagnosis.<key> (the nineteen below, plus later additions), category diagnosis, platform default, org override (read staff, edit
org-admin), no user tier (one threshold set per org). ddx-api sends them to the engine in the BODY of a run start
or curator tick as DxSettings, never in x-osprey-settings (the engine rejects unknown header keys). The
curator scheduler and the manual tick use the PLATFORM tier. Code constants are seeds only.
The table lists the first nineteen keys. Later plans added more module.diagnosis.* keys (map settings, miners,
card author); the registry packages/ddx-contracts/src/settings.ts is the full list.
Six more module.diagnosis.* keys, same rules as above (category diagnosis, platform default, org override; read staff, edit org-admin). Five reach the engine through DxSettings; draftWatchPollSeconds is read by ddx-api only.
Two more module.diagnosis.* keys, same rules as above (category diagnosis, platform default, org override; read staff, edit org-admin). They shape the case report of a single case and of a cohort.
The decision-support disclaimer is not a section: it always prints, last. A section that is switched off is left out of both the Markdown and the PDF. The format key only decides which download is the main button; both files stay available. Vocabularies: SETTING_CASE_REPORT_SECTIONS and SETTING_CASE_REPORT_FORMATS in packages/ddx-contracts/src/settings.ts. The cohort size cap module.diagnosis.cohortMaxPatients (default 25, 1-200) is read from the effective setting; when a start has more patients than the cap, the case screen says "Too many patients. The limit is N."
Same tiers as above (platform default, org override, read staff, edit org-admin, no user tier). The browser never
sends them: ddx-api reads them with one getEffective read and puts them in the author run-start body as
{ model, sourcesPerCard, concurrency } (ddx-api/src/osprey/osprey-diagnosis-card-author.controller.ts).
Eighteen new module.diagnosis.* keys, same tiers as above (category diagnosis, platform default, org override,
read staff, edit org-admin, no user tier). All reach the engine in the run-start body as DxSettings and freeze
on the run row. Four layers carry each key: packages/ddx-contracts/src/settings.ts (+ DxSettingsSchema),
ddx-api/src/settings/settings.schemas.ts, the 4 locale label files and the web field spec
(fields-platform.ts).
Changed keys of earlier plans:
module.diagnosis.rerankMode gains mastra (Mastra rerankWithScorer); values are now mmr · none · mastra ·
router:<alias>; seed stays mmr.module.diagnosis.caseIndexEnabled seed changes from false to true.module.diagnosis.draftWatchPollSeconds (§Draft and mapping keys) is now also in DxSettingsSchema: the
dx_analyze_case relay reads it from the run's frozen settings, then falls back to the seed.module.diagnosis.boardSignalMinSupport now also gates the mapping proposal that board concept acts file (plan osprey-dx-cockpit-ui, features.md section 5g).module.diagnosis.cockpitUi (cockpit switch, values legacy | v2) was added and removed inside plan osprey-dx-cockpit-ui. No row, no seed: the v2 cockpit is the only diagnosis UI.The legacy path and the engine key stay until the parity gate passes; the spine is not the default (seed legacy).
The plan added no assistant.* key. These values sit outside the registry:
packages/ddx-contracts/src/settings.ts:
portal.<group>.<key> or module.<moduleId>.<key>);SETTING_SCHEMAS (enum tuples as an exported SETTING_* const);SETTING_DEFAULTS;SETTING_REGISTRY: category, tiers.org (read / edit roles) and,
when users may override it, tiers.user.ddx-api/src/settings/settings.schemas.ts. The
satisfies lock fails typecheck (lead-run) when the two drift.settings.registry.keys.<name>.label and .description, plus
settings.registry.options.<name>.<value> for each enum value, in
ddx-web/messages/{en,fr,de,es}/settings.json (<name> = the last key segment, e.g.
themeMode). All four files in the same change. A key shown on the portal settings page
also adds its label keys to the typed union in
ddx-web/src/app/[locale]/(app)/portal/[orgSlug]/[role]/settings/_islands/model.ts.useUnifiedSetting('<key>') inside
UnifiedSettingsProvider. Use editable to disable the control and update(value) to
write; the hook does the optimistic PATCH and the rollback. Compose the control from
inventory entries (@/inventory/<family>), never a raw UI import in a page.seedPlatformSettings() iterates SETTING_KEYS and creates
the missing platform row from SETTING_DEFAULTS (create-only; a re-seed never overwrites
an operator edit). No migration: the tiers are generic rows, never a per-key table../ddx-manage.sh i18n (labels) and ./ddx-manage.sh kernel (regression
guard) exit 0. Lint and typecheck run once by the lead at /unify.ddx-web/messages/{en,fr,de,es}/.Last reconciled: 2026-11-17 · plan osprey-dx-cockpit-ui task 049 (boardSignalMinSupport, cockpitUi removed)
adr/
deploy/
research/