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 the resolved runtime env file, validates by constructing a Settings instance, and reports validation failures through the shared UI error presenter.
• Settings resolves its env file in this order: explicit _env_file, ENV_FILE, then the repository-root .env.production.
• Runtime Settings resolves its write target in this order: explicit function override (tests/tools), RUNTIME_SETTINGS_ENV_FILE environment variable (deployment override), ENV_FILE, then the repository-root .env.production.
• Runtime Settings changes require application restart to take effect.
• Runtime Settings renders a host-side restart command (docker compose -f docker-compose.production.yml up -d --force-recreate app worker) so operators can apply saved values without granting Docker control to the app container.
• 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 deployment/helper keys (CLOUDFLARE_TUNNEL_TOKEN, BACKUP_DIR, BACKUP_RETENTION_DAYS, RUNTIME_SETTINGS_ENV_FILE, ENV_FILE, COMPOSE_FILE) plus legacy/deprecated keys (POSTGRES_*, DATABASE_BACKUP_DIR, APP_DATA_BACKUP_DIR, UPLOADS_BACKUP_DIR, SYNOLOGY_BACKUP_DIR), and directs edits for those keys to the resolved runtime env file path.
• 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 also provides GEDCOM upload and Run GEDCOM Import actions, using the same queue-backed MaintenanceRun history/log flow.
• 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