transcription/docs/ui/pages/settings.md

Settings Page Contract

Purpose

Settings manages installation-local registries, safe runtime .env settings, and editable text assets from one route.

Route

Route	Purpose
/settings	Manage Runtime Settings, Document Types, Person Roles, Tags, Prompts, Home Page Text, and Maintenance runs.

Behavior

• The page title is Settings.
• Configuration surfaces are grouped as tabs:
  • Document Types
  • Person Roles
  • Tags
  • Prompts
  • Home Page Text
  • Maintenance
  • Runtime Settings
• Runtime Settings exposes an allowlisted set of non-secret fields synchronized with Settings model fields except excluded secret/unsafe fields.
• Runtime Settings is rendered as a compact two-column editor (Setting, Value) in a centered, narrower responsive container.
• Runtime Settings persists changes to .env, validates by constructing a Settings instance, and reports validation failures through the shared UI error presenter.
• Runtime Settings changes require application restart to take effect.
• Runtime Settings includes an explicit "Other settings not shown here" markdown table listing:
  • secrets (OPENROUTER_API_KEY, DATABASE__PASSWORD)
  • high-risk database connection settings (DATABASE__DRIVER, DATABASE__PATH, DATABASE__HOST, DATABASE__PORT, DATABASE__DATABASE, DATABASE__USER) and directs edits for those keys to .env.
• Document Types, Person Roles, and Tags support Add/Edit/Delete with existing guardrails.
• Prompts exposes only transcribe_document.md for editing and restore-from-backup.
• Home Page Text edits the same Markdown content rendered on /homepage.
• Maintenance provides queue-backed Run Backup and Run Storage Reconciliation actions.
• Maintenance run history shows job type, status, started/finished timestamps, duration, summary, and log view/download actions.
• Maintenance actions enqueue work and signal the worker; the page itself does not execute shell commands directly.

Acceptance Checklist

• /ui/settings renders all seven tabs.
• Registry and prompt workflows keep existing validation and error handling.
• Runtime Settings excludes secret fields and rejects invalid values.
• Saving Home Page Text persists content for the homepage view.

Implementation Anchors

• src/transcription/ui/pages/settings_page.py
• src/transcription/ui/runtime_settings_store.py
• src/transcription/ui/homepage_store.py
• tests/ui/test_pages_registration.py