# 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 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`