Skip to content

Loomarr Configuration — Subsystem Design

Status: Living companion to design.md; the settings subsystem is implemented. Precedence: decision 0008 is authoritative for the decision — settings live in the app, the environment pins, env > database > default. design.md §15 moved here (§12 below), and its settings table was retired in favour of the generated settings reference. This doc is authoritative for the configuration subsystem’s design: the registry, resolution semantics, secrets lifecycle, Settings UI, and onboarding integration. Conflicts → main doc wins on policy, this doc on mechanics; fix the loser in the same PR.


1. Lineage & the split

Loomarr’s model is the *arr convention with one addition:

AppWhere settings liveWhat we take
Sonarr/RadarrUI settings + generated API key shown in-app + per-page “Show advanced” toggleThe IA: grouped pages, advanced toggle, explicit save bar, API key in the UI
SeerrWizard-driven; settings persisted by the appOnboarding is configuration: wizard steps are settings forms with live tests
LoomarrBoth of the above, plus deterministic env pinningGitOps users pin any key via env; it wins and locks the field with provenance

The storage-tier rule (so future keys self-classify): a setting is bootstrap iff it is needed before the database opens or shapes the process envelope that must exist before the app graph can be built — DATABASE_URL, AUTO_MIGRATE, LISTEN_ADDR, LOG_LEVEL, and the installation encryption key that must be available before any secret-bearing row is decoded. Everything else is app-managed and env-pinnable. That answers where a value is stored, not when a saved value is safe to apply: app-managed settings still classify into the runtime lifecycles in §3.

The bootstrap FILE tier (revised — V5). Bootstrap keys were env-only, because the registry lives in the database they are needed to open. That reasoning is unchanged; what it did not anticipate is the wizard needing to write one. The Database step (§13) asks “SQLite or PostgreSQL?” and must persist the answer — it cannot write into the database it is choosing, and it cannot set an env var that survives a restart. A file beside the database is the only writable store that exists before the database does. So:

env > file > default — bootstrap keys only env > database > default — every app-managed setting, unchanged

  • Env still wins. A GitOps pin is never overridden by something the wizard wrote; the wizard reports the key as pinned instead, the same contract the registry’s pinned provenance already gives the Settings UI.
  • The file holds bootstrap keys ONLY. It is not a second settings store. An app-managed key there is a category error, not a typo — it would create two places to look for one answer — so it is rejected by name at both read and write, and the error points at Settings.
  • Absent file = today’s behaviour exactly. This tier adds a lookup, never a requirement.
  • bootstrap.json lives in the data directory (beside the SQLite file), written atomically at 0600: it decides where the database is, so a half-written one would leave the next boot unable to find its own data, and DATABASE_URL routinely carries a password. Secrets the app can mint itself (API_TOKEN, PLAYOUT_TOKEN) are generated, never demanded.
    • The data directory is decided once and recorded. The first boot derives it (the SQLite file’s directory, else /data) and PersistDataDir writes it into the file as DATA_DIR (a file-only key with no env var); every later boot reads it back, so a database cutover cannot move the directory holding the installation key. A file written before this key existed gets it on its next boot.
    • Environment is read in one place. config.LoadEnv parses an explicit environment map (config.Load passes the process environment), the process environment is never mutated, config.ReadSecret is the single reader behind every <VAR>_FILE, and internal/envaccess_architecture_test.go fails any os.Getenv/os.LookupEnv/os.Setenv outside internal/platform/config that is not allowlisted with a reason.
    • ⚠ The file is SEARCHED across two directories, and that is load-bearing (V11). DataDirFor is scheme-dependent — the SQLite file’s own directory for sqlite://, the conventional /data for postgres:// — so a SQLite→PostgreSQL migration moved where the next boot looked for the file. With the database anywhere other than /data, the file recording the switch was written beside the SQLite database and then never read again: the app booted back onto SQLite, having apparently migrated successfully. The switch silently undid itself. Reads now try the database’s own directory first (an operator who pinned a SQLite path meant that one), then /data; writes are unchanged, so an existing install’s file keeps being found and nothing has to move. A malformed file still fails the boot rather than falling through to the next directory — a file that exists and is wrong is an operator error to surface, not a reason to quietly use a different one.

The installation-key tier is separate from bootstrap.json. LOOMARR_ENCRYPTION_KEY or LOOMARR_ENCRYPTION_KEY_FILE supplies one base64url-encoded 256-bit key; setting both is an ambiguous boot error. When neither is set, Loomarr atomically creates /data/encryption.key at mode 0600 and uses it on later boots. The database stores only a non-secret fingerprint, so a second PostgreSQL replica with a different local file fails before reading credentials rather than writing unreadable ciphertext. Multi-replica deployments therefore mount the same key file or inject the same environment secret into every replica. The key file is deliberately not part of a database-only backup: losing it makes encrypted credentials unrecoverable, while copying it beside that backup collapses the protection to the security of the combined copy.

Installation-key replacement is an explicit one-boot maintenance flow. Set the new key through the ordinary current-key variable and the existing key through LOOMARR_ENCRYPTION_KEY_PREVIOUS or its _FILE form. Loomarr verifies the previous fingerprint, atomically rewraps every DEK under the new key, and updates the fingerprint; after a successful boot, remove the previous-key input. Providing both previous forms is an error, and a wrong previous key changes nothing.

The per-channel tier (added with programming-design.md): a policy instance is channel data, stored on the channel row, edited in proposal review / the channel editor, and never env-addressable. Some policy fields also have an env-pinnable registry fallback today: the rolling schedule horizon, filler break frequency, playout backend, and auto-curation limits. Their full precedence is:

channel policy > registry default > built-in

Other programming fields — including ordering, separation, and seasonality — currently resolve directly from channel policy to their built-in behavior. They must not be presented as Settings defaults until a consumed registry tier exists. The test for a future knob remains: would two channels sensibly want different values? Yes → policy field, with a registry default only when the product needs fleet-wide control. No → plain registry setting.

Self-updating channels (programming-design.md §8.2) follow this tier exactly. A channel opts into scheduled re-curation via a per-channel policy.autoCurate field (rides policy_json, no schema change — like rules/filler/window before it), and the two thresholds it’s bounded by have the classic split: the global defaults recurate.min_score_pct (the quality bar a net-new title must clear) and recurate.max_titles (the growth cap) are registry settings (env-pinnable, hot-applied per call), while policy.autoCurate may carry a per-channel override of either. job.recurate.schedule is a plain global KindCron job knob (all channels re-curate on one clock). The registry values are read live inside the re-curation grant, so raising the fleet-wide bar takes effect on the next run with no restart.


2. The registry — every setting declared exactly once

type Setting struct {
Key string // "library.url"
EnvVar string // "LIBRARY_URL" — the pin
Group Group // connections.media_server | connections.requester |
// connections.tunarr | ai | channels | filler |
// users_security | advanced
Owner Owner // stable task id; browser paths stay frontend-owned
Kind Kind // string | int | bool | duration | url | enum | secret | string_list
Default any
Enum []string // Kind == enum
Secret bool
Advanced bool // hidden behind the per-page "Show advanced" toggle
RequiredFor Feature // "" | acquisition | suggestions | filler — feature gating (§7)
Validate func(any) error // shape validation (URL normalization lives here)
Test *ConnectionTest // optional live test — powers wizard, checklist, Test buttons
Doc string // one-liner: UI help text + generated docs
}

The registry is the single source of truth, with the same committed-artifact discipline as OpenAPI: make config-docs generates docs/reference/settings.md (grouped tables, owner tasks, env names, defaults, docs) and CI fails on drift (git diff --exit-code). The main doc’s §15 table is a human mirror; the generated file is the contract. A setting that isn’t in the registry does not exist — validation, the API, the UI, the wizard, and the docs all derive from it.

Code reads a setting through a generated typed handle, never a string key. go generate ./internal/platform/settings (make settings-keys, run by cmd/settings-keys) writes internal/platform/settings/keys_gen.go: one variable per non-MigrationOnly setting, typed by its Kind (settings.LibraryURL is a StringKey, settings.FillerSourceFolderEnabled a BoolKey, and so on for IntKey, DurationKey, StringListKey). A caller writes settings.LibraryURL.Get(r) against a settings.Reader — *settings.Service, the composition root’s generation-frozen view, or a test fake — so a misspelt or retired key is a compile error and a kind mismatch cannot be written. A reader that cannot answer (no store, or a key it does not hold) yields the setting’s declared default, which keeps a default-on feature on in a degraded boot. MigrationOnly settings have no handle. TestKeysGenIsCurrent fails when the registry and keys_gen.go drift, and TestNoSettingKeyLiteralsOutsideSettings fails on any string literal in production code outside internal/platform/settings that equals a handle-bearing key.

Group and Owner answer different questions. A group is the registry’s stable form and documentation grouping; an owner identifies the one task where a person changes the value. Every public setting has exactly one known owner. The API exposes that owner id, while one frontend destination catalog maps ids to labels, aliases, role visibility, and paths. The backend never knows browser paths. Action-owned destinations such as database migration, paired devices, diagnostics, and About live only in that catalog because they do not represent registry values.


3. Resolution & runtime semantics

resolve(key) per read: env → db → default, with asymmetric error handling that matches who made the mistake:

  • Invalid env value → fail the boot, loudly, naming the variable and the expected shape. An operator typed it; silence would hide their error behind mystery behavior.
  • Invalid db value → log a warning, fall through to default, surface a caution chip on the field. The app wrote it (or a migration drifted); self-heal and tell the human, don’t crash a running install.
  • Env unset after previously pinning: next boot, provenance flips to db (or default) and the field unlocks. Pinning is a live property of the environment, not a ratchet.
  • Env set but empty (LLM_MODEL=) counts as unset, and resolution falls through to db → default. A blank assignment is what an unfilled .env template looks like, not a decision to pin a setting to the empty string — and the two are indistinguishable to us, so we side with the reading that cannot silently destroy an operator’s saved value. Treating it as a pin produced exactly that: the §8.1 picker wrote llm.model to the db and hot-swapped the live suggester, while every read still resolved to the empty env pin, so the checklist reported “no model selected” immediately after one was, and the choice vanished on the next restart. Consequently there is no way to pin a setting to the empty string via env — deliberate: “unset” and “set to nothing” mean the same thing to an operator, and clearing a value is what the db layer (and the Settings UI) is for.
  • Boot logs every empty pin it ignored, at WARN, naming the variable: an operator who meant to blank something must not have to infer that we disregarded it.

3.1 Taking a key back from the environment (the unlock)

An env pin is normally the one thing an admin cannot change from the UI, and §2’s tagline — “it wins and locks the field” — is why. That is right for GitOps and wrong for the case that motivated this: an operator who put a value in .env to get the app booting, then reached the wizard and found the field they needed to correct was read-only, with the only documented way out being edit a file on the host and restart. On an appliance-style install that is not a workflow, it is a dead end.

So a key can be explicitly taken back: an admin unlocks it, and from that moment the stored value wins for that key until it is handed back.

This is a durable claim, not a session toggle — and that is the whole design. Env is re-read every boot, so an unlock that lived in memory would resolve back to env on restart and silently discard what the operator saved. That is precisely the LLM_MODEL failure recorded above (write succeeds, every read still returns env, the value vanishes on restart), and shipping a button that reproduces it would be worse than the locked field, which at least tells the truth. The claim therefore persists in the database (migration 00020, env_override), rides §16 backups like any other durable state, and survives restarts and redeploys.

The rules:

  • Unlock is per key. Never global, and never implied by writing a value — an ordinary PATCH to a pinned key still returns pinned (§7). Taking a key from the deploy config is a separate, deliberate act.
  • Admin only, and audited. It reuses updated_by/updated_at, so the field’s existing “changed by … · when” line reports who overrode the environment. An operator inspecting a box that is not behaving like its .env must be able to find out why from the app.
  • Provenance stays the three-value enum env | db | default (§5 already rejected a fourth chip). An unlocked key resolving to its stored value is honestly db. The lock state is a separate boolean on the entry — envOverride — so the UI can say “overriding SEERR_URL” rather than implying the environment is unset. Conflating the two would make an overridden key indistinguishable from one the environment never mentioned.
  • Re-locking is one click and loses nothing. Clearing the flag returns the key to env precedence with the stored value still in the database, so handing control back to GitOps is reversible in both directions.
  • DELETE /v1/settings/{key} still 409s on a locked key (§7). The explicit clear drops a stored override so a key falls back to env/default; on a pinned key that is a contradiction. On an unlocked key it succeeds and the key reverts to the env value — which is the correct meaning of “clear my override” once the operator has taken the key back.
  • Bootstrap keys are never unlockable. DATABASE_URL, LISTEN_ADDR, LOG_LEVEL, AUTO_MIGRATE are read before the database opens (§2’s classification rule), so a flag stored in that database cannot affect them. Offering the control would be a lie; the API rejects it rather than accepting a write that does nothing.
  • Unlocking SEEDS the stored value from the env value it is taking over, and does not change what the app is doing. The alternative — unlock to an empty row — would make the act of unlocking blank the setting, so an operator who wanted to correct one character in a URL would instead knock the service offline the moment they clicked. Unlock is a transfer of authority, not an edit; the value changes on the next save, by the human, deliberately.
  • ⚠ Secrets are the exception: they never seed. Seeding would copy a credential out of the environment into the database and therefore into every §16 backup, quietly widening where that secret lives — a security change disguised as a convenience. An unlocked secret is set:false and the operator must enter one, which is the same replace-only flow §4 already defines and the only one that keeps “where did this credential come from” answerable.

The honest cost, recorded rather than glossed: a redeployed .env no longer fully describes a running instance. That is a real loss for GitOps, and it is why the act is explicit, per-key, admin-only, audited, and visible on the field — an operator who never unlocks anything keeps exactly the old contract.

Secrets via files: every secret env var also accepts the Docker-secrets idiom — LIBRARY_TOKEN_FILE=/run/secrets/emby loads the value from the file (trailing newline stripped). <VAR> and <VAR>_FILE both set → boot error (ambiguous).

Runtime application has three lifecycles; “app-managed” does not mean “hot-applied”:

  1. Per-operation snapshot. Connections and other multi-request adapters resolve all coupled values once before an operation begins. A save affects the next operation, never the middle of the current one.
  2. Per-run policy. Job intervals, limits, and selection policy resolve when the next tick, pass, reconcile, or pod begins. They change what future work decides without rebuilding the module that performs it.
  3. Generation-scoped topology/resource. A filesystem root or similar resource that gives durable relative data its meaning is resolved once while BuildHandler constructs a generation. Saving a replacement persists the desired value immediately, but every module continues to use the generation’s immutable applied value until Loomarr restarts in place. This is not a failed hot-apply: it is the safety boundary that prevents one catalog row from being interpreted under two roots while requests and jobs overlap.

The concrete rules are:

  • The settings service holds an in-memory snapshot (RWMutex) refreshed on local write and, for Postgres replicas, by one generation-owned reader every 30 seconds (main doc §5). Each tick uses one full-table read that returns values and environment-override ownership together, then publishes both under one lock; a failed read keeps the prior complete generation and retries on the next tick. Cancelling the application generation stops the reader. SQLite starts no reader and incurs no polling queries because it remains single-process by contract.

  • One PATCH is one durable commit. Validation, env-pin refusal, and result reporting remain per key: invalid and pinned edits are reported and excluded, while every valid upsert or clear in the request commits in one store transaction with its own canonical value and shared audit timestamp/author. The in-memory snapshot reloads only after that commit. This is load-bearing for coupled settings such as {library.flavor, library.url, library.token}: a Postgres replica that refreshes during another replica’s save sees the complete old tuple or the complete new tuple, never durable intermediate rows assembled from both generations.

  • Connections read through per use: the shared HTTP client factory (§6 main doc) fetches one complete connection from the snapshot at call time. Every media-library operation resolves library.flavor, library.url, and library.token together with ResolveMany, then carries that immutable {flavor, url, token} through all of its requests. Saving a Jellyfin flavor, URL, and token therefore enables the next lookup; rotating the token or changing flavor affects the next operation; and an operation already in flight never mixes a credential with another server or auth scheme. An incomplete triple is unconfigured and makes no outbound request. The library and other optional adapters remain constructed while configuration is empty, so saving, rotating, or clearing settings takes effect without rebuilding BuildHandler. In particular, every Tunarr Programmer operation snapshots its URL, transcode override, and filler attach policy together; a settings save affects the next operation, never the middle of the current one. Endpoint-derived caches are scoped to the normalized URL and invalidated when it changes, so repointing Tunarr cannot reuse a transcode id or content index learned from the previous instance. Saving or clearing tmdb.api_key likewise enables or disables TMDB search, channel icon suggestions, and suggestion grounding on the next operation without a restart. The Catalog’s all scope — used by both /v1/search?scope=all and the Suggester’s grounding tool — independently considers the complete live media-library connection and TMDB key, so either configured corpus remains useful on its own. An unconfigured optional corpus is skipped only for all; explicitly selecting that corpus still returns its configuration error.

  • Intervals re-read per tick: tickers ask the snapshot each cycle; changing CHANNEL_RECONCILE_EVERY takes effect next tick.

  • Long-lived constructions rebuild on change: the LLM client subscribes via Watch(keys...) <-chan Change and reconstructs. (This is the same seam the §8.1 model-selection hot-swap uses — an atomic-pointer provider that rebuilds on a persisted llm.* change.)

  • filler.dir and filler.watch_dir are one generation-scoped storage layout. The clip root is the interpretation base for every catalog path; the watch folder drains into it. Applying either one independently would let a saved watch path move files into the old root, or let playout serve the new root while the pipeline still writes the old one. One immutable pair is handed to scan, intake, fetch, split, pipeline, artwork adoption, media serving, source/watch status, and internal playout. The settings Test probes the desired pair before restart; operational routes report and use the applied pair.

  • The configured clip spelling and Loomarr’s traversal spelling have distinct roles. Loomarr may resolve symlinks and filesystem aliases for safe local traversal, but it registers the operator-configured shared-volume path with Tunarr. A path that Loomarr can resolve is not necessarily present under the same spelling in Tunarr’s mount namespace.

  • RestartRequired is honest for both bootstrap drift and generation-scoped app-setting drift. Revised (V5): the UI edits one bootstrap key — the wizard’s Database step writes DATABASE_URL to the bootstrap file (above). Revised again here: app-managed storage topology can also be saved in the registry while waiting on the same restart control. Storage tier and runtime lifecycle are orthogonal.

    Revised again (V13): the flag is now computed, and there is a restart control to act on it. It was a hardcoded true on the database switchover response — the only place that could set it — which made it a property of one endpoint rather than of the instance. It is now derived by comparing each restart-scoped key’s running/applied value against its resolved/desired value. Every bootstrap key is restart-scoped (a generation reads them all when it starts, LOG_LEVEL included), and config.ChangedKeys walks the struct, so a new boot key is covered without a list to maintain. So GET /v1/system/restart can name the specific key: “You changed filler.dir. Loomarr is still running the old value until it restarts.” ⚠ Derived, never a sticky boolean someone remembers to set. A flag written at the moment of an edit is wrong the moment the operator edits it back, and would nag about a restart that is no longer needed. Comparing running-vs-resolved cannot drift, because it re-reads the same resolution the app itself uses. Reverting filler.dir or filler.watch_dir to the applied value likewise removes it from the pending list; no sticky “restart needed” bit is written. The restart mechanism (in-process rebuild, no supervisor, no re-exec) is design.md §9.2.

A storage-layout save is not a data migration. Loomarr never copies, moves, or deletes the old clip library merely because either path was edited. The operator makes the target directory and its mount available, moves or copies media deliberately when that is the intent, tests the desired layout, then restarts. The next generation reconciles the catalog against the selected root. A missing target may be created by the generation; a later create/scan failure degrades filler visibly and must not turn into a successful empty scan that prunes the last known catalog. An existing ancestor that cannot be inspected far enough to rule out a watch/clip alias fails the new generation before any filler consumer starts. That stricter fail-closed case is deliberate: continuing with an unverifiable topology could let duplicate intake delete the catalog itself.

Replica consequence. Restart state is per running process even though the desired registry value is shared. A Postgres deployment must give every Loomarr replica the same filesystem mounts and roll every replica before the layout is considered applied fleet-wide. The in-app restart endpoint restarts the replica that handled it; a database lock cannot make an unmounted host path appear on another machine. SQLite remains one replica by contract.

Audit: the settings table carries updated_at + updated_by (nullable — env/migration writes have none). The UI shows “changed by Matt · 2d ago” per field; same spirit as approved_by.


4. Secrets lifecycle

Generation: 256-bit random, base64url, created idempotently inside the first-migration transaction (alongside the instance id).

Encryption at rest uses envelope encryption. One deep secret-protection module owns the versioned storage envelope, key wrapping, authenticated encryption, rotation, and safe errors. It generates data-encryption keys (DEKs), wraps them with the installation key (the KEK), and stores only wrapped DEKs in the database. Secret values use AES-256-GCM with a fresh nonce and authenticated context containing the record kind, stable record identity, and field name. Copying ciphertext between two settings or notification destinations therefore fails closed.

One DEK is active for new writes. Retired wrapped DEKs remain readable until every referenced value is re-encrypted; rotation activates a fresh DEK before that bounded migration begins. An installation-key replacement rewraps DEKs while old and new key material are deliberately present for the maintenance operation and does not rewrite every secret value. Key identifiers, versions, nonces, ciphertext, and fingerprints are never themselves treated as credentials, but none may appear in ordinary logs, activity, diagnostics, metrics, or problem bodies.

The protected set is every reversibly stored database secret: generated operational secrets, registry KindSecret values (including SMTP, Library, requester, TMDB, LLM, and SSO credentials), and notification-provider secret fields such as tokens, passwords, private keys, and credential-bearing webhook URLs. Provider definitions classify fields; a client-provided generic map cannot downgrade a secret to plaintext configuration. Sessions, device credentials, Invitation grants, and password-recovery grants remain one-way hashes and are not encrypted.

Startup does not seal plaintext setting secrets. A protected setting stored as plaintext predates encrypted settings (v0.2.0-beta.1); boot fails closed with one error per such key, never printing the value, telling the operator to upgrade through a v0.2.x release first or clear that setting and re-enter it. Missing keys, authentication failure, or unknown envelope versions likewise stop readiness without clearing or overwriting durable values. Sealing a value cannot erase plaintext already present in old backups, replicas, SQLite free pages, or WAL history; operators whose threat model includes those artifacts rotate the upstream credentials.

Display policy (Sonarr-model, differentiated by purpose):

  • API_TOKEN and PLAYOUT_TOKEN are operational values you must paste elsewhere — viewable on demand by admins (eye toggle + copy button), exactly like Sonarr’s API key.
  • Integration secrets you entered (Emby token, Seerr key, TMDB, LLM key) — masked after save (set · …a1b2 preview), replace-only. The API returns {set: true, preview, provenance} — never the value. (The §8.1 hosted llm.api_key.<provider> keys follow this exact rule: stored, previewed, never echoed by any GET.)

Authentication sessions have no generated signing secret. A session token is an opaque random credential stored only as a SHA-256 hash in the database; cookie authentication resolves that hash and the owning user on every request. Session revocation therefore happens through the session row or user-disable workflow, never by rotating unrelated application configuration.

Regeneration side-effects (typed-confirmation dialogs, effects stated up front):

SecretImmediate effectUX contract
API_TOKENOld token dead instantlyShow the new token once prominently; remind that machine clients/scripts must update.
PLAYOUT_TOKENExisting device and signed URLs stop authorizing; the durable Live TV workflow republishes the tuner/listing pair with the new tokenShow the new /playout/tuner.m3u?token=… URL for manual consumers; automatic wiring is repaired through the backend-transition coordinator.

Redaction is systemic, not per-callsite: the settings service exposes a Redactor (the current set of secret values) wired into the slog handler — a secret value appearing in any log line is replaced before write. Secrets are excluded from /v1/setup/status, from validation error strings (validators must never echo the value), and from RFC 7807 bodies. There is a test that greps captured logs for a known secret and demands zero hits.


5. Settings UI — information architecture

Settings opens on a task-based home, not a category tab and not an automatic redirect. The primary control is a finder over human labels, descriptions, common aliases, exact keys, and environment variable names. A result navigates to its one curated owner; it does not create another inline editor. Empty and no-result states keep the browseable task groups visible.

Home groupDestinations
Set up LoomarrConnections, AI, channel defaults, notifications
Access and devicesRecipient-facing address, sessions, SSO, paired devices, generated secrets, encryption
This serverPlayback, storage, backups
TroubleshootBackground tasks, diagnostics, database migration, version and About
FillerOne link into Filler’s own settings index; global Settings never duplicates those controls

The raw registry editor is a quiet Advanced settings escape hatch, not a peer of everyday tasks. Individual destinations show a compact Settings breadcrumb/back action and one Find another setting affordance. The persistent top-level Settings matrix and nested System matrix are removed. /settings/system is a grouped server/troubleshooting landing page, while its task pages remain path-addressable. The one-field General surface is folded into Access and devices, as is the existing Security content; the superseded General and Security routes are removed. Destination changes use paths. Finder text, disclosure state, and table filters remain local state rather than destination routing.

The established destination behavior remains unchanged: Connections owns its live tests and automatic wiring; AI owns provider, credentials, model selection, and behavior; channel defaults contain only values channels actually inherit; notifications use the provider workflow; Playback separates Loomarr controls from Tunarr-owned profiles; Access and devices owns sign-in/device choices and progressively discloses secrets and encryption. The recipient-facing address continues to be edited and validated exactly as before, and the server never derives it from request headers.

⚠ Advanced settings is EDITABLE. The earlier mock draws it as a read-only lookup. That works only if every key also has a home page — and the restructure above broke exactly that: GroupAdvanced holds 19 keys (job schedules, TTLs, the reconcile interval) whose only editor was the Advanced page that folded into this one. A read-only table would leave all 19 uneditable with nothing on screen saying so, and the loss falls in the seam between two phases that each look complete alone. So rows edit in place, through the same SettingField every other page uses (a compact mode) and staging into the same cross-tab buffer — env-pinned locking and the secret replace-flow (§4) behave identically here. The lookup half still governs presentation: keys are monospace and verbatim, never humanized, because someone arrives holding a literal job.workers from a compose file and a row reading “Job workers” does not match the string they are carrying.

The exception is an action-owned value whose safe write is more than a registry PATCH. llm.model stays searchable and shows its resolved value, but its action deep-links to the AI picker instead of rendering free text: selection also verifies tool capability, preserves the branded hosted provider, and hot-swaps the client. Letting the raw table bypass those effects would make the escape hatch a second, less-safe implementation of the same product decision.

V55 closes the loophole that made this escape hatch the only home of ordinary settings. Every non-advanced key has an owning workflow page; the raw table links to that page, carries the same help and environment-takeover affordance as the full field, and exposes the explicit Clear override operation. Editing remains available for genuine advanced keys and for operators who arrive with a literal key, but the table is never the sole UI for a product decision.

Two consequences worth stating, because both are easy to “fix” wrongly later:

  • Three provenance chips, not the mock’s four. The mock adds generated, but generated secrets (playout_token, the API token) are a separate registry (internal/platform/settings/secrets.go) and are not settings entries at all — the API’s provenance enum is exactly env/db/default. A fourth chip would render a state the backend never sends. Those secrets have their own panel under Access and devices, where view/copy/regenerate belong.
  • The compact control has no <label>, so it must carry aria-labelledby pointing at the row’s visible Key cell. Naming it by title alone is an axe label-title-only violation rated serious: a sighted mouse user gets a tooltip, a screen-reader user gets an unnamed text box. The visible label already exists on the row — it just has to be associated, not duplicated.

Display semantics are registry-owned. A setting carries its human label and presentation (plain, duration, bytes, cron, path, language, switch) beside its validation kind. Validation still decides what may be stored; presentation decides how the same value is explained and edited. This keeps 720h as the stable wire/storage value while every UI says “30 days”, and keeps a byte ceiling from appearing as an unexplained integer. A plain number stored in a larger unit declares that Unit (GiB, MiB, %), which the editor shows beside the box. The key suffix (_gb, _mb, _pct) and the declared unit must agree, and a registry test enforces it. Enum options remain []EnumOption{Value, Label} for the same reason. An open-ended setting may also declare Presets []Preset{Value, Label}: common choices offered ahead of Custom, without closing the set. The registry parses every preset as the setting itself would (a preset it would refuse fails the build) and publishes it in canonical form (24h is served as 24h0m0s), so a UI matches the current value by string and keeps no list of its own. Language presentation is the intentional localization exception: the registry owns the supported BCP 47 codes, while a client renders those codes in its active interface locale through CLDR/Intl.DisplayNames; the enum label is only a code-shaped fallback for clients without localization support. This prevents English language names from becoming backend contract or being copied into every client. The UI may fall back to humanizing an unknown key only in the raw escape hatch; workflow forms never derive product copy from identifiers.

Conditional fields (ShowWhen). A setting may declare ShowWhen map[string][]string — it is shown only when the current value of a named key is one of the listed values (empty = always shown). llm.api_key is hosted-only, while llm.url applies to both providers: it is the Ollama host for local AI and the OpenAI-compatible base URL for hosted AI. Hiding the local URL would make a non-default Ollama host impossible to configure. The UI evaluates conditions against live edits; a hidden field’s value is untouched.

Unavailable fields stay legible. A workflow may disable a setting whose prerequisite cannot currently run, but it must render the reason beside that same control. This is distinct from an environment pin: provenance says who owns a value; unavailability says whether the app can act on it. The saved desired value is retained so fixing the prerequisite activates the operator’s prior choice instead of resetting it. The disabled control and its reason remain programmatically associated for assistive technology.

V55 surface audit decisions

  • Retired declared-but-unconsumed promises: season.precision, playout.transport, suggest.auto_approve, sched.backfill, ingest.max_concurrent, filler.starter_collection, reconcile.every, and event.webhook_url. Reintroducing one requires its consumer in the same change.
  • Retired the remaining declared-but-unconsumed promises: the sched.* policy defaults and seasonal.mode, the global playout.subtitles default, and user.sync_every. Per-channel programming policy remains the place to set ordering, separation, and seasonal behaviour; subtitle burn-in is not exposed until the encoder actually honours it; user import remains an explicit admin action until there is a scheduled consumer. A control that merely round-trips through the registry is not implemented.
  • Image formats, remote concurrency, and the remote-artwork retention ceiling are implementation policy, not operator preference. AVIF/WebP/JPEG compatibility, the provider concurrency cap, and the six-month compliance ceiling are fixed by the image module. Operators control storage, outbound fetching, upload size, and derivative cache budget.

Field anatomy: label · control · provenance chip (set via environment = locked; caution chip on self-healed values) · unavailable reason where applicable · one-line doc · Test button where testable · “changed by … · when”. Two of these are present but not permanently visible, so a page of fields reads as controls rather than a wall of prose: the one-line doc lives in an (i) hover tooltip (kept in the DOM via aria-describedby for screen readers), and the “changed by … · when” audit line reveals on hover/focus of the field (kept in the DOM, opacity-toggled, so it’s keyboard- and reader-reachable). The provenance chip, unavailable reason, caution chip, and validation stay always-visible — they change what the field is or does, not merely its history.

One curated home, with progressive disclosure. Advanced settings remains the raw-key escape hatch, but every key has only one task-shaped editor elsewhere. A control does not appear on both an operational workflow and a generic Settings page: the workflow owns it when its effect is best understood beside the affected work (for example, auto-filing beside Incoming clips), while service and model configuration stays in Settings. Workflow pages group controls by the question they answer, show ordinary choices first, and put tuning limits, executable paths, and pipeline budgets behind the group’s Advanced disclosure. A safe default is not a reason to make its tuning knob part of the everyday path. Group headings carry a one-line explanation when the distinction would otherwise be unclear.

Playback applies that rule to the encoder specifically: automatic selection is the ordinary path, so the free-form playout.encoder override is Advanced alongside executable and storage paths. The page leads with the read-only live status because it answers who is actually streaming, which GPU or software path is active, and whether any fallback encoders are consuming capacity before the operator changes a preference. Tunarr-backed channels keep their encoding profile in Connections → Tunarr; Playback explains that ownership instead of presenting Loomarr’s internal controls as if they reconfigured Tunarr.

Connections applies the same rule to service-owned identifiers. Loomarr automatically chooses Tunarr’s Default transcode profile and the first Sonarr/Radarr profile and root folder when their fields are blank. Their free-form identifiers are therefore labelled as overrides and remain behind the connection block’s Advanced disclosure; the ordinary path asks only how to reach the service. Access and devices likewise keeps cookie.secure behind Advanced because auto follows the request and is the safe ordinary path; changing the transport policy is deployment troubleshooting, not a routine sign-in preference.

Save model — explicit, spanning the whole Settings surface (Sonarr’s sticky save bar): the buffer and the bar both live in the Settings layout, not on a page. Navigation is not a commit boundary, and a per-page buffer silently discarded edits when moving between destinations. Edits accumulate with dirty tracking; a persistent bar offers Save/Discard; navigation away with dirty state prompts. Chosen over per-field autosave because connection settings often change together (URL + token) and half-saved pairs mid-test are a footgun. Save = validate → persist → apply by §3 lifecycle → per-key results (RFC 7807 problems map to inline field errors; pinned keys are rejected with the chip explanation). A generation-scoped save is still successful: the field shows the desired value and the derived restart notice explains why the applied value has not moved yet.

The save bar spans destinations, not just a page. Dirty state survives switching between Connections, AI, Defaults and so on: an operator who edits a connection, checks a default, and comes back must not silently lose the first edit. One edits map keyed by setting id, one bar, one Save. The alternative — per-tab state — makes the bar’s “3 unsaved” mean something different depending on where you are standing, which is worse than no count.

Four INLINE-COMMIT exceptions, and they are all verbs. These commit immediately and are deliberately outside the save bar, because each is an action rather than a staged edit — you do not “stage” regenerating a secret, and a Save button next to Run now would be nonsense:

ActionWhereWhy it cannot stage
Select a modelAIHot-swaps the live suggester (§8.1); the picker’s whole point is trying one
Pull a modelAIA long streaming download with its own progress, not a value
Regenerate a secretAccess and devicesDestructive and irreversible — it invalidates the old value on the spot (§4)
Run a job nowSystem → TasksTriggers work; there is no “unsaved run”

Everything else on every page goes through the bar. A fifth exception should be argued for against this list, not added quietly.

This applies to contextual workflow editors too. Filler’s Incoming-page auto-filing panel is the curated home for its enable switch and confidence threshold, but those values are staged inside the panel and committed with an explicit Save auto-filing action. Being closer to the affected clips is not permission to introduce an uncued autosave model.

Filler settings use the same workspace heading and navigation as Sources, Incoming, and Library. /filler/settings is a small task index grouped into everyday choices and advanced tuning; it does not silently choose Automatic downloads. Folders, downloads, storage, Incoming history, breaks, review, playback, limits, and tools use canonical path segments, never destination query parameters. One task is visible at a time and a compact switcher beside its heading replaces the buried More settings disclosure. Incoming, Sources, storage warnings, diagnostics, and global search link to the exact task. Incoming itself explains how long Ready clips remain visible and links quietly to Incoming history; changing that live duration affects the next read only, never removes a clip from the Library or changes playback eligibility. Path changes preserve the shared staged edits and single save bar. Settings remain reachable before Filler is configured so setup is not a dead end.

Everything on Connections is self-diagnosing — and quiet once set up. A connection block (Media server, Requester, Tunarr, TMDB) is a collapsible card carrying its own live status dot + inline Test verdict + Fix → link — the same shell the wizard’s Connect step uses (config-design §6; the shared ConnectionBlock component). Each block says what the service enables, whether it is optional for the current path, and what saving wires automatically. When several checks fail, only the first failing block opens while every other failure remains labelled needs attention in its collapsed header. Connection blocks behave as an accordion after that — opening one closes the prior block — because several simultaneous service forms recreate the same wall of controls the initial triage avoids. A fully set-up install shows quiet collapsed blocks with nothing to worry about.

Wiring is an effect of saving, not a manual action. Registering the durably applied internal-or-Tunarr tuner/guide pair in the media server (livetv) and, on the Tunarr path, pointing Tunarr at the library (tunarr_library) are idempotent and fully derived from saved connection values — there is no decision to make and re-running is a no-op. Relevant saves run publication through the durable backend-transition coordinator; a later effect failure never rolls back the saved setting and surfaces on the relevant connection’s own status. The page therefore has no wiring buttons and no separate checklist — both would be scaffolding a set-up operator shouldn’t have to see. This holds in the wizard too: there is no standalone “Live TV” / “TV guide” wizard step. Saving the selected backend’s connection settings already publishes the guide, so a dedicated step would only re-run the same no-op and add a redundant click — the livetv outcome instead surfaces on the media-server verdict. The webhook handshake does remain a first-run wizard step, because it is genuinely interactive (a paste-and-listen flow that can’t be derived from a saved value), not a resting Connections concern. Settings remains the troubleshooting console (main doc §13) because each block is re-testable in place and every failure links to its fix.


6. Onboarding integration — the wizard is the settings system

No parallel form system. Each wizard step renders the relevant settings group’s form (essentials only — Advanced keys hidden), pre-resolved (env-pinned fields render locked), with the group’s live test inline. Configure → validate → save → advance. The wizard writes through the exact same PATCH path as Settings.

  • Step → group mapping: claim (auth, pre-settings) → playout choice (playout.backend; see below) (picking internal reveals server.public_url on that same step and requires a persisted absolute address the media server can reach; picking Tunarr instead reveals Connections/Tunarr + its media-source check there, because “who plays my channels” and “where is it” are one decision; saving auto-wires Live TV into the guide — no separate step*)* → Connections/media-server → Connections/requester + webhook handshake (displays the generated secret’s URL, listens for Test) → AI (skippable; includes the §8.1 model picker) → Filler (skippable; drop-folder path + optional starter ingest targets) → guided first channel.
  • ⚠ The step list is DERIVED from playout.backend, not constant (design §13). Internal playout is the default since §9.1, but the wizard hardcoded tunarr as a blocking check and gave it a wiring step, so the default path demanded a second server it would never use and refused to continue without it. The blocking set is now media_server alone on the internal path, media_server + tunarr on the Tunarr path; the Tunarr form and the “give Tunarr your library” step exist only on the Tunarr path. Removed steps are hidden, not marked satisfied — a rail entry reading “not needed” still advertises work that is not part of this install.
  • Being configured elsewhere does not stop a check blocking. Tunarr’s form lives on the Playout step, but on the Tunarr path its check still gates the Connections step. Where a setting is edited and where its failure is reported are separate questions, and conflating them would either hide a real blocker or move the whole checklist.
  • A blocking check is a property of the chosen path, so nothing that cannot be satisfied can block. This is the same rule the skippable steps encode, applied one level up: an internal install can never turn tunarr green, and a gate on a check the operator cannot satisfy is a dead end the wizard’s Back/Continue offers no way around.
  • Skippable steps are neutral, not red: checklist states are pass | fail | skipped | pinned. Skipping AI doesn’t shame you with a red X — it shows a neutral “not configured” that links back here.
  • First-run detection: the setup.completed registry key (bool, SETUP_COMPLETED, Advanced — dotted to match every other key); until set, / routes to the wizard. The wizard’s final step sets it through the ordinary PATCH /v1/settings path, so it is a setting like any other. “Re-run setup” lives in Settings forever.
  • Defaults philosophy: every optional key ships a working default, so the shortest honest path to a live channel is the media server plus Loomarr’s reachable address — Loomarr plays the channels itself (§9.1), and server.public_url tells that media server where to fetch the streams. The address is required only on this path, stays locked when SERVER_PUBLIC_URL pins it, and is never guessed from request headers. Choosing Tunarr replaces that address requirement with Tunarr. Seerr adds acquisitions; AI adds suggestions.

7. Feature gating derives from settings completeness — with one environment-derived exception

RequiredFor on registry keys computes feature availability:

  • Suggestions unavailable → POST /v1/proposals rejects before creating a Job with a 409 problem whose stable type identifies the first actionable blocker. Missing provider/model setup is feature_not_configured and deep-links to Settings→AI; a configured provider and selected model with missing TMDB grounding is grounding_not_configured and deep-links to the TMDB block on Settings→Connections. The response never calls AI unconfigured when only grounding is absent. The Add channel panel reads this authoritative diagnosis rather than re-deriving readiness, and renders it before any retry. The panel preserves the complete draft Intent (description and constraints) in session storage while the operator follows a setup link. Settings carries a visible Return to channel action; returning reopens Add channel with that draft restored, but never auto-submits a paid model request. A successful Proposal Job, Start over, or an intentional panel close clears the draft. A member who cannot edit Settings receives administrator-directed guidance instead of an unusable admin link. Never a stack trace, never a dead button, never a false diagnosis.
  • Requester unconfigured → proposals still generate from the library; acquisitions render disabled with “Connect Seerr to request missing titles.”
  • Filler unconfigured → channels build without pods; the channel card notes “no filler drop-folder configured.”

ingest is the exception, and it is deliberate. Its availability is not a settings question — it depends on whether yt-dlp + ffmpeg are actually runnable, which no setting can assert. It therefore resolves from binary presence at startup rather than from RequiredFor.

⚠ This paragraph used to say the gate meant “you are on loomarr:latest, switch to loomarr:filler”. That two-tag split no longer exists — the single image always ships the tooling (design §16) — so ingest off now means a degraded install: a custom image built without the vendored binaries, or a configured path that is missing or not executable. The UI copy must say that, not send an operator hunting for an image tag nobody publishes. The underlying rule is unchanged and is why this exception is recorded at all: pointing someone at Settings for a gate no setting can open is the dead end this section exists to prevent — and pointing them at a nonexistent image is the same mistake wearing different clothes.

The rule that survives: one function computes both the feature verdict and its ordered missing prerequisites, and every consumer reads it. The checklist, the tab states, API gating, and recovery copy never re-derive availability — only the inputs differ, never the seam.

Policy effects are channel data; only consumed fallbacks are Settings defaults. The rolling schedule horizon and filler break frequency resolve as channel choice > registry default > built-in and are read again when a channel is rebuilt. Ordering, separation, and seasonality currently resolve as channel policy > built-in; no registry value is shown for them. The channel editor must describe the active ladder in user language rather than implying a Settings tier that does not exist.


8. API contract (extends main doc §7)

  • GET /v1/settings → grouped entries: {key, group, owner, kind, apply: live | restart, value | {set, preview}, provenance, advanced, doc, enum, requiredFor, testable, updatedBy, updatedAt}. owner is the stable task id from the registry; it is never a browser path.
  • PATCH /v1/settings → per-key results {saved | invalid(problem) | pinned}; persistence is immediate and runtime application follows the key’s §3 lifecycle. An empty value clears an optional key, except on a secret, where it is invalid (§9).
  • A shared settings commit owner sends every staged key through that PATCH and clears only keys whose returned status is saved. invalid and pinned edits remain staged beside their field-level result; one successful key never makes a rejected sibling disappear. Installation location always stages country and place together, so its success message and Setup continuation require both to be saved rather than transport-level HTTP 200.
  • GET /v1/locations?q=&limit= searches the embedded city/country index; GET /v1/locations/suggestion checks allowlisted provider geography headers only from a peer in security.trusted_proxies, then checks the effective public client IP against the embedded country index; POST /v1/locations/resolve maps explicitly shared device coordinates to its nearest supported place. Cloudflare, CloudFront, and Vercel work directly; every other CDN/proxy—including Fastly, Akamai, a load balancer, or a custom edge—can set the provider-neutral X-Loomarr-Geo-Country and optional X-Loomarr-Geo-City headers. All are admin-only, bounded, same-origin operations. Suggestions never save automatically, and no path stores a position or calls a runtime provider.
  • DELETE /v1/settings/{key} → the explicit clear: drops the stored override so the key reverts to env/default. This is the only way to unset a secret. 204 on success; 404 for an unknown key; 409 when the key is env-pinned (the environment wins — unset the variable to manage it in the app). Runtime application follows the same lifecycle as PATCH.
  • Backend hot-apply is a durable mutate → prepare → publish → retire transition, not merely an immediate callback. PATCH, clear, environment takeover/hand-back, and PLAYOUT_TOKEN rotation enter one coordinator before their durable mutation. The coordinator holds the same workflow lock across that mutation and every follow-on phase. Guide/now-next and in-app routing continue to read the durable applied backend while active inherited channels are prepared for the target; ordinary reconcile reads non-empty prepared first (then applied) so concurrent maintenance cannot undo partially converged target state. Explicitly pinned, paused, and detached channels do not join that fleet barrier. The target is checkpointed in prepared before convergence starts, and every retry re-runs the idempotent fleet barrier, so cancellation, failure, or restart cannot mistake the checkpoint for proof of completed convergence. Preparing internal playout durably opens its token-authenticated M3U/XMLTV/direct transport before the media server refreshes the new tuner/listing pair, but does not switch ordinary UI routes early. Only after target refresh and cutover succeed is applied advanced; stale Loomarr-owned registrations retire last. A failure before publication preserves the old routes and registration, while a retirement failure leaves the new backend applied and retries cleanup. The system checkpoint survives restart, and both a later relevant settings write and channel maintenance resume it (including URL-only repair when the backend name did not change). A URL-only repair replays the inherited-channel fleet barrier before publisher preparation and refresh; failure or restart retries that ordering instead of exposing a newly configured publisher ahead of its channels. Desired is re-read inside the coordinator’s serialization boundary, so an older maintenance retry cannot publish after a newer save. On Postgres that boundary is a store-owned, database-scoped advisory lock held across the relevant setting write, checkpoint load, every external publisher phase, and checkpoint save; separate replicas therefore cannot insert a newer desired write midway through an older publication. Only after acquiring it does a replica refresh both setting values and provenance, then mutate and resolve desired. The refresh precedes even a mutation that becomes a no-op: whether a PATCH is environment-pinned, or whether an env-override handoff made it writable, must be decided from the durable snapshot rather than stale process memory. A queued process therefore cannot reject or reverse a newer ownership handoff when its work finally runs. SQLite uses the same interface with its single-process mutex, consistent with SQLite’s one-replica contract. Failure to acquire the workflow lock means the mutation did not run and the write request returns unavailable. Once the durable checkpoint is initialized, each reconcile attempt and routing request reads it once rather than trusting the controller’s process-local mirror; this makes prepared transport and applied routing visible immediately on every Postgres replica. These reads are lock-free and fail closed. A committed mutation remains successful when a later transition phase fails; the transition stays pending for maintenance retry.
  • POST /v1/setup/test body {check} → run one named check (powers per-block Test buttons); GET /v1/setup/status runs all.
  • GET /v1/settings/secrets/{name} → reveal a generated token’s value ({value}), the read half of §4’s “viewable on demand by admins (eye toggle + copy button)”. Without this, the only way to see PLAYOUT_TOKEN would be to rotate it, which stops every media-server tuner already configured; the Live TV setup step needs to show the URL, not change it.
  • POST /v1/settings/secrets/{name}/regenerate → per §4 side-effects. Rotating PLAYOUT_TOKEN invokes the same durable publication repair because internal tuner/guide URLs embed it; the publisher reads the durable token inside the workflow lock, and Postgres request authorization reads that same row so every replica admits the new device URL and rejects the old one immediately. A repair failure leaves the rotation successful and the transition pending. API_TOKEN bearer authorization uses the same replica-coherent read (SQLite remains cache-only); rotating API_TOKEN has no Live TV consequence.
  • The §8.1 model-selection routes (GET /v1/system/llm, POST /v1/system/llm/{select,test,pull}) are the AI group’s live-configuration surface — the same admin-gated, secret-masking discipline applies (keys never returned).
  • All admin; secrets masked everywhere per §4.

9. Failure modes & edges (decided)

  • Concurrent edits: last-write-wins per key (updated_at); the save bar refreshes provenance/values on conflict rather than silently clobbering the whole page.
  • URL normalization in Validate (scheme required, trailing slash stripped) so http://emby:8096/ and http://emby:8096 are one value.
  • Unknown keys in the DB (only reachable if the downgrade guard were bypassed): ignored with a warning, never fatal.
  • Empty-string PATCH on an optional key clears it (reverts to default); on a required-shape key it’s invalid. A secret is the exception: an empty-string PATCH on a secret key is invalid (“replace-only”), never a clear. Reason: GET /v1/settings deliberately returns no value for a secret (§4), so a client that reads settings and writes them back would submit "" for every secret — silently destroying the stored Emby token, Seerr/TMDB/LLM keys. Making the round-trip loud and harmless rather than quietly destructive is worth more than the convenience of clear-by-empty, and §4 already calls secrets replace-only. Clearing a secret is an explicit act: DELETE /v1/settings/{key} (§8).
  • Secret shape sanity-check (in parseKind for KindSecret, so it guards every secret — Emby/Jellyfin token, Seerr/TMDB/LLM keys, and any future one). Secrets have no universal format, so this is a sanity guard, not a format check: the raw value is trimmed of surrounding whitespace (a common paste artifact), then rejected as invalid if it (a) contains internal whitespace (space/tab/newline — no real API key or token does) or (b) is shorter than 4 characters after trimming (a 1–3 char fragment). This exists because a secret otherwise stores any string verbatim, and a connection-test hint ("set a media server flavor (emby | jellyfin)") once ended up persisted as library.token, which then made every media-server probe fail with a 401 that looked like a credential problem rather than a corrupt-store problem. The length floor is deliberately LOW (4) because this guard also runs on the resolve/read path — a stored value is re-parsed on read and self-heals to the default if it no longer parses (§9 “db drift”) — so a higher floor would retroactively invalidate a real short key already in a user’s store on upgrade. The whitespace check is what actually catches the error-string corruption; the length floor is a light bonus. The message is secret-safe — it names the problem (“a token can’t contain spaces”), never echoes the value (§4). The parsed (trimmed) value is what gets persisted (see the canonical-value rule below), so the store never keeps the surrounding whitespace. This does not replace the live connection Test, which is the real proof a token works.
  • Canonical value on write. PATCH persists the value the parse produced, not the raw input — so a URL’s stripped trailing slash and a secret’s trimmed whitespace are what land in the store, and the stored form matches the resolved form. (Storing raw would keep e.g. http://emby:8096/ on disk while resolving to http://emby:8096, a silent disagreement.)

10. Testing (extends main doc §19)

  • Resolution matrix per Kind: env beats db beats default; invalid env fails boot with the var named; invalid db self-heals to default + warning surfaced.
  • Pin lifecycle: set env → locked + pinned on PATCH; unset env + reboot → unlocked, provenance db.
  • Hot-apply: change library URL via PATCH → next Lookup hits the new host (mock); interval change takes effect next tick; an §8.1 model select hot-swaps the live suggester provider without restart.
  • Generation-scoped layout: build on clip/watch layout A, save layout B, and prove settings show desired B while scan, intake, pipeline, media serving, artwork adoption and playout all stay on applied A; restart into a fresh generation and prove every consumer moves to B together. Saving both paths in one PATCH must never combine old root with new watch. Reverting both before restart clears derived drift. A failed target scan must preserve the last known catalog.
  • Secrets: generation idempotent across restarts; <VAR>_FILE loads (and <VAR>+_FILE together fails boot); regen side-effects (sessions die incl. caller’s; handshake check goes red until fresh Test); the log-grep redaction test (a known secret never appears in captured logs, error bodies, or setup/status).
  • Feature gating: AI keys absent → Suggest returns the 409 problem and the computed feature set says so; add the keys → gate opens without restart.
  • make config-docs drift check green.

11. Build integration

  • Phase 1 (built as a cross-phase retrofit, 2026-07-15): registry + resolution + env/_FILE loading + snapshot/Watch + redactor into slog. make config-docs target. The settings table gains its updated_at/updated_by audit columns (§3) via forward-only migration 00008 (an ALTER TABLE settings ADD COLUMN …, the second real ALTER after 00007’s policy_json; the bare (key,value) KV from 00001 never drops). The proposed registry middle tier for ChannelPolicy was later retired in V55 because no production scheduling path consumed it; channel policy now resolves directly to the scheduler’s documented built-ins.
  • Phase 8: the §8 API surface.
  • Phase 9: generated API/playout tokens + rotation side-effects (auth interplay).
  • Phase 13: Settings pages, save bar, provenance chips, wizard-as-settings-forms, feature-gated empty states.
  • This doc is a seed doc: incorporate as docs/config-design.md during phase 14; docs/reference/settings.md is the generated reference beside it.

12. Rules carried from the former design.md §15

design.md §15 repeated the registry as a hand-written table. The generated settings reference is the key reference; these rules lived only in that table and stay here.

  • Zero required environment for a SQLite first run. docker run -v loomarr-data:/data loomarr reaches the wizard; DATABASE_URL defaults to SQLite under /data.
  • Route-mounting switches are bootstrap-tier. LOOMARR_DEV_LOGIN, LOOMARR_PPROF and LOOMARR_METRICS_TOKEN[_FILE] decide which routes exist or gate an unauthenticated surface, so they are read at boot and never registry keys an admin session could flip at runtime. Boot warns while dev login or pprof is on. An unset metrics token refuses /v1/metrics (fail closed), and the metrics credential is deliberately separate from API_TOKEN.
  • Demo mode is bootstrap-tier too. LOOMARR_DEMO_USERNAME and LOOMARR_DEMO_PASSWORD (both or neither; boot refuses one alone) make the server a demo site: the unauthenticated GET /v1/setup/state returns that account so the sign-in screen can offer it, and the app shows the demo tour. The password is public by design, so only the demo site sets them.
  • The TMDB stand-in is bootstrap-tier. LOOMARR_TMDB_BASE_URL (an absolute http(s) URL; boot refuses anything else) points the TMDB client at a stand-in instead of the public API, so a lane or demo backend grounds suggestions over the demo library’s invented catalogue without a real key or real titles (#1941). The client’s base URL is fixed for its lifetime, and redirecting every grounding lookup is not something an admin session should flip, so it is read at boot. Boot warns while it is set.
  • LLM_* environment values are initial defaults when no in-app selection exists; an in-app provider selection (llm.provider, llm.url, llm.model, llm.api_key.<provider>) overrides them and hot-swaps the running suggester.
  • Pipeline budgets: zero means none. For the filler pipeline’s per-run budgets, 0 is a distinct “never do this work on this box” state, not “use the default”.
  • One-time SMTP upgrade input. The legacy NOTIFICATIONS_EMAIL_* and NOTIFICATIONS_SMTP_* variables are read only for the one upgrade inspection described in auth; they never pin, recreate or update a provider afterwards. New installs configure SMTP only in Settings → Notifications.
  • Secrets are stored in the database like the rest of the *arr ecosystem, masked after save (replace-only), never logged, excluded from /v1/setup/status, and may come from <VAR>_FILE; they are never baked into the image (§4).