US08-01: Make the Trust Boundary Configurable and Authenticated

2026-08-18 21:58:53 +02:00
83 changed files with 74 additions and 10537 deletions
--- a/.dockerignore
+++ b/.dockerignore
@@ -1,23 +0,0 @@
 # Deny-by-default build context (US08-02): the image must contain no secrets, no
 # photos, no database, no logs, and no .git. An allow list is the only version of this
 # rule that stays true when a new file appears in the working copy.
 *
 !pyproject.toml
 !alembic.ini
 !README.md
 !photo_pipeline
 !migrations
 !frontend
 !docs
 !docker
 # Nothing generated, even under an allowed directory.
 **/__pycache__
 **/*.py[cod]
 **/.DS_Store
 **/*.env
 **/*.log
 **/*.db
 **/*.db-*
 **/*.sqlite*
--- a/.env.example
+++ b/.env.example
@@ -1,85 +0,0 @@
 # Every setting the application and its composition read, with no values in it.
 # Copy to `.env`, fill in what you need, and keep that copy out of git (it is
 # gitignored, and the work-item safety checks refuse to stage it).
 #
 #   cp .env.example .env
 #
 # Empty means "use the default noted beside it". Anything already exported in the
 # shell wins over this file, both for the app and for `docker compose`.
 # ── the composition (host side; read by docker-compose.yml only) ─────────────
 # The photo library on this host. Bind-mounted at PHOTO_PIPELINE_LIBRARY_ROOTS.
 PHOTO_PIPELINE_LIBRARY_HOST_PATH=
 # Which image to run. Default: photo-pipeline:dev (what `up --build` builds).
 PHOTO_PIPELINE_IMAGE=
 # Must be the owner of the library above: what the containers rename and rewrite
 # keeps this ownership. Default: 1000 / 1000.
 PHOTO_PIPELINE_UID=
 PHOTO_PIPELINE_GID=
 # Host address the API port is published on. Default: 127.0.0.1. Anything else
 # exposes the app beyond this machine — then ALLOWED_HOSTS and ACCESS_SECRET below
 # are what stand in for the loopback boundary (US08-01).
 PHOTO_PIPELINE_PUBLISH_ADDRESS=
 # This file's own path, if it is not ./.env. Default: .env.
 PHOTO_PIPELINE_ENV_FILE=
 # ── library and data ────────────────────────────────────────────────────────
 # os.pathsep-separated. In a container these are the *container-side* mount paths,
 # and `serve`/`worker` refuse to start when they are not mounted.
 PHOTO_PIPELINE_LIBRARY_ROOTS=
 # Database, WAL, thumbnail cache, journals, backups. Default: data (the container
 # sets /data, which is the persistent volume; a network mount is unsupported).
 PHOTO_PIPELINE_DATA_DIR=
 # Database file, if it should not live in the data directory. Default:
 # <data dir>/photo_pipeline.db.
 PHOTO_PIPELINE_DB_PATH=
 # ── serving ─────────────────────────────────────────────────────────────────
 # Bind address. Default: 127.0.0.1. The composition sets 0.0.0.0 inside the
 # container and publishes to loopback on the host instead.
 PHOTO_PIPELINE_HOST=
 # Under the composition this is the *published* host port; the container serves
 # 8000. Default: 8000.
 PHOTO_PIPELINE_PORT=
 # Comma-separated hostnames the app answers to besides loopback. Empty means
 # loopback only. Naming one makes the access secret mandatory.
 PHOTO_PIPELINE_ALLOWED_HOSTS=
 # Traded for the session cookie at GET /api/v1/session via X-Access-Secret.
 # Required as soon as the app is reachable from anywhere but loopback. Generate
 # one with: python -c 'import secrets; print(secrets.token_urlsafe(32))'
 PHOTO_PIPELINE_ACCESS_SECRET=
 # Comma-separated peer addresses whose X-Forwarded-Proto/-Host may be believed.
 # Only the reverse proxy's address belongs here. Default: none.
 PHOTO_PIPELINE_TRUSTED_PROXIES=
 # Largest request body accepted, in bytes. Default: 1048576.
 PHOTO_PIPELINE_MAX_REQUEST_BYTES=
 # ── logging ─────────────────────────────────────────────────────────────────
 # Default: INFO.
 PHOTO_PIPELINE_LOG_LEVEL=
 # json or text. Default: json.
 PHOTO_PIPELINE_LOG_FORMAT=
 # ── limits ──────────────────────────────────────────────────────────────────
 # Thumbnail cache quota in bytes. Default: 500000000.
 PHOTO_PIPELINE_THUMBNAIL_CACHE_QUOTA_BYTES=
 # Refuse to decode images larger than this many pixels. Default: 100000000.
 PHOTO_PIPELINE_THUMBNAIL_MAX_PIXELS=
 # Free space an archive destination must keep beyond the transfer. Default:
 # 1000000000.
 PHOTO_PIPELINE_ARCHIVE_FREE_SPACE_RESERVE_BYTES=
 # ── safety gate ─────────────────────────────────────────────────────────────
 # true refuses every mutating request until a read-only dry run of this library has
 # been produced and approved (US07-07). Default: false. Turn it on before pointing
 # the app at photos that cannot be replaced.
 PHOTO_PIPELINE_REQUIRE_DRY_RUN_APPROVAL=
 # ── external services ───────────────────────────────────────────────────────
 # Vision provider key for the analysis stage. Without it, analysis cannot run.
 PHOTO_PIPELINE_VISION_API_KEY=
 # Immich server and its API key, for the upload stage.
 PHOTO_PIPELINE_IMMICH_SERVER_URL=
 PHOTO_PIPELINE_IMMICH_API_KEY=
 # Uploader binary. Default: immich-go (on PATH; pinned inside the image).
 PHOTO_PIPELINE_IMMICH_GO_BINARY=
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,9 +0,0 @@
 # Vendored third-party browser bundles (US09-01). Minified upstream files carry
 # trailing whitespace and very long lines; they are not ours to reformat, and the
 # submit gate's `git diff --check` would refuse them forever. Their integrity is
 # controlled where it belongs instead: a pinned version and a recorded sha256 in
 # frontend/js/vendor/VERSIONS.json, asserted by tests/integration/test_documentation.py.
 #
 # Only the whitespace check is turned off. They stay text, so a credential scan or a
 # search still reads them.
 frontend/js/vendor/*.js -whitespace linguist-vendored
--- a/.gitea/workflows/deploy.yml
+++ b/.gitea/workflows/deploy.yml
@@ -1,99 +0,0 @@
 # Publish and redeploy (US08-04). Adapted from the crowdsec-admin deploy workflow:
 # build, log in to the Gitea registry, push, trigger the Portainer webhook, prune.
 # The difference is the gate — this project has a required suite that must not be
 # skipped, so publishing happens only after `Test` (`.gitea/workflows/test.yml`)
 # succeeded on `main`, never on the push itself.
 #
 # The stack is managed by Portainer from git (`docker-compose.yml`), and the runtime
 # secrets it needs — vision key, Immich key, access secret — live in the Portainer
 # stack's environment. They are deliberately not repository secrets and are not in the
 # image: rotation stays in one place, and a repository read never discloses them.
 #
 # Repository secrets required:
 #   REGISTRY_USER          user with write:package on the registry
 #   REGISTRY_TOKEN         that user's token
 #   PORTAINER_WEBHOOK_URL  POST URL from the stack's auto-update setting
 name: Deploy
 on:
  workflow_run:
    workflows:
      - Test
    types:
      - completed
    branches:
      - main
  workflow_dispatch:
    inputs:
      dry_run:
        description: Build and push a scratch tag only — leave `latest` and the running stack alone
        type: boolean
        default: true
 concurrency:
  # Deliberately not keyed by commit: the point is that two deploys of *different*
  # commits cannot overlap. Queued, not cancelled — a half-pushed tag set is worse
  # than a late one.
  group: deploy
  cancel-in-progress: false
 env:
  IMAGE: git.domverse-berlin.eu/domverse/photoanalyzer
  # The commit that was tested, not whatever `main` points at by the time this starts.
  SHA: ${{ gitea.event.workflow_run.head_sha || gitea.sha }}
 jobs:
  publish:
    # A completed `Test` run is not a passing one.
    if: >-
      (gitea.event_name == 'workflow_run' && gitea.event.workflow_run.conclusion == 'success')
      || (gitea.event_name == 'workflow_dispatch' && inputs.dry_run == false)
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          ref: ${{ env.SHA }}
      - name: Log in to the Gitea registry
        run: echo "${{ secrets.REGISTRY_TOKEN }}" | docker login git.domverse-berlin.eu -u "${{ secrets.REGISTRY_USER }}" --password-stdin
      - name: Build and push
        # The commit tag is pushed first, so a `latest` that exists is always a tag
        # that also exists under its own commit — which is what makes a rollback a
        # tag change rather than a rebuild.
        run: |
          docker build -t "$IMAGE:$SHA" -t "$IMAGE:latest" .
          docker push "$IMAGE:$SHA"
          docker push "$IMAGE:latest"
      - name: Trigger the Portainer redeploy
        # --fail turns an HTTP error into a non-zero exit: a redeploy that did not
        # happen must not read as a green deploy.
        run: curl -sS --fail -X POST "${{ secrets.PORTAINER_WEBHOOK_URL }}"
      - name: Prune dangling images
        # Untagged layers only. Published tags are the rollback history; `-a` would
        # delete exactly the images this workflow exists to keep.
        run: docker image prune -f
  dry-run:
    # Manual only, and the default: prove the image still builds and the registry
    # still accepts it without moving `latest` or touching the running stack.
    if: gitea.event_name == 'workflow_dispatch' && inputs.dry_run
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Log in to the Gitea registry
        run: echo "${{ secrets.REGISTRY_TOKEN }}" | docker login git.domverse-berlin.eu -u "${{ secrets.REGISTRY_USER }}" --password-stdin
      - name: Build and push a scratch tag
        run: |
          docker build -t "$IMAGE:scratch-$SHA" .
          docker push "$IMAGE:scratch-$SHA"
      - name: Prune dangling images
        run: docker image prune -f
--- a/.gitea/workflows/test.yml
+++ b/.gitea/workflows/test.yml
@@ -1,139 +0,0 @@
 # The test gate. Deploy waits for this workflow by name (`.gitea/workflows/deploy.yml`
 # triggers on `workflow_run: [Test]`), so renaming it here without renaming it there
 # would leave `main` publishing without a suite. `tests/integration/test_deploy_workflows.py`
 # asserts both halves of that link, and that the commands below are still the ones
 # configured in `work_item/.work-item.yml`.
 name: Test
 on:
  pull_request:
  push:
    branches:
      - main
 concurrency:
  # One run per branch; a newer push makes the older run's answer irrelevant.
  group: test-${{ gitea.ref }}
  cancel-in-progress: true
 jobs:
  suites:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install exiftool
        # The EXIF checkpoints are the safety invariant of every metadata stage; a run
        # without exiftool would skip them for a reason the release gate accepts.
        run: |
          SUDO=
          if [ "$(id -u)" -ne 0 ]; then SUDO=sudo; fi
          $SUDO apt-get update
          $SUDO apt-get install -y --no-install-recommends libimage-exiftool-perl
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Install the application and its test dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e '.[test]'
          python -m playwright install --with-deps chromium
      - name: Helper suite
        run: work_item/scripts/python -m unittest discover -s work_item/tests -v
      - name: Application suite
        run: work_item/scripts/python -m pytest tests -q
  # The deployed container, verified the way the host application is (US08-05). It
  # runs on `main` only — a pull request has nothing published to upgrade *from*, and
  # building two images per push would pay for that on every commit. Deploy waits for
  # this whole workflow, so a red container gate is a deploy that does not happen.
  container:
    if: gitea.event_name == 'push'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        # The upgrade journey builds the previous commit's tree when no published
        # image is named, so the history has to be there.
        uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Install the application and its test dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e '.[test]'
          python -m playwright install --with-deps chromium
      - name: Container acceptance gate
        # One command: it builds the image, provisions the composition against a
        # temporary fixture library and an isolated volume, runs the phase_h journeys,
        # destroys the stack, and writes the evidence. Any skipped check fails it.
        env:
          # The fixture libraries are bind-mounted into the containers, so this path
          # has to be one the Docker daemon can see. On a runner that talks to a
          # sibling daemon, point it at a shared host path instead of the workspace —
          # an unshared path arrives as an empty mount and the journeys fail on the
          # scan, which is the symptom to recognise.
          PHOTO_PIPELINE_DATA_DIR: ${{ gitea.workspace }}/gate-data
          PHOTO_PIPELINE_LIBRARY_ROOTS: ${{ gitea.workspace }}/gate-library
          PHOTO_PIPELINE_TEST_MOUNT_BASE: ${{ gitea.workspace }}/gate-mounts
        run: |
          mkdir -p "$PHOTO_PIPELINE_LIBRARY_ROOTS" "$PHOTO_PIPELINE_TEST_MOUNT_BASE"
          python -m photo_pipeline container-gate --output gate-evidence
      - name: Keep the evidence
        # Retained per run, and retained on failure especially: the logs are the only
        # account of what the containers did.
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: container-gate-${{ gitea.sha }}
          path: gate-evidence
  # The manuals, checked against the application they describe (US09-05). Runs on
  # every pull request as well as `main`: documentation drifts by the same commits
  # that change behaviour, and telling the author while the change is still open is
  # the only time the fix is cheap.
  documentation:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Install the application and its test dependencies
        run: |
          python -m pip install --upgrade pip
          python -m pip install -e '.[test]'
          python -m playwright install --with-deps chromium
      - name: Documentation gate
        # One command: every phase_i check, offline and in the browser, with the
        # evidence retained. It accepts no skip — a check that did not run is a page
        # nobody compared with the code.
        env:
          PHOTO_PIPELINE_DATA_DIR: ${{ gitea.workspace }}/docs-gate-data
        run: python -m photo_pipeline docs-gate --output docs-evidence
      - name: Keep the evidence
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: docs-gate-${{ gitea.sha }}
          path: docs-evidence
--- a/117
+++ b/117
@@ -1,117 +0,0 @@
 # One image, two roles (US08-02).
 #
 # The application is not self-contained Python: it shells out to `exiftool` for every
 # EXIF checkpoint and to `immich-go` for every upload, and it serves the static
 # frontend from `frontend/`. All three are installed here at pinned versions, because
 # an image whose external tools drift is an image whose metadata checkpoints and
 # upload reports drift with them (concept §15, "External integration risks").
 #
 # Everything is pinned:
 #   * the base image by tag *and* digest, so a moved tag cannot change the runtime;
 #   * exiftool by its Debian package version, verified against `exiftool -ver`;
 #   * immich-go by release version and per-architecture SHA-256 of the release asset.
 # The verified versions become image labels and /etc/photo-pipeline/versions.json,
 # which `python -m photo_pipeline diagnostics` reports — so a running container can
 # prove what it contains instead of being trusted about it.
 #
 # The project is installed editable on purpose: `photo_pipeline.db` resolves
 # `alembic.ini` and `migrations/`, and the API resolves `frontend/`, relative to the
 # repository root. An editable install keeps that one layout instead of scattering the
 # same files across site-packages and a source tree.
 ARG PYTHON_IMAGE=python:3.12.14-slim-trixie@sha256:2c941e860699f878900b0edc2403613c234d4b32eda3cc9fa7036991a2a63c4a
 # ── the uploader, fetched and verified outside the final layer ────────────────
 FROM ${PYTHON_IMAGE} AS uploader
 ARG IMMICH_GO_VERSION=0.32.0
 ARG IMMICH_GO_SHA256_AMD64=6e2ad86bafdadb9466d6515de7cb882726c0aea1a21d51164dff361d7d480a97
 ARG IMMICH_GO_SHA256_ARM64=2c35d9284baae407ef9540bdac5f488971b0bdc7be758a4d7c05ab270af09fdb
 COPY docker/fetch-immich-go.py /tmp/fetch-immich-go.py
 RUN python /tmp/fetch-immich-go.py \
        --version "${IMMICH_GO_VERSION}" \
        --sha256-amd64 "${IMMICH_GO_SHA256_AMD64}" \
        --sha256-arm64 "${IMMICH_GO_SHA256_ARM64}" \
        --into /usr/local/bin \
    && /usr/local/bin/immich-go version
 # ── the application ──────────────────────────────────────────────────────────
 FROM ${PYTHON_IMAGE} AS runtime
 ARG EXIFTOOL_VERSION=13.25+dfsg-1
 ARG IMMICH_GO_VERSION=0.32.0
 # The library is mounted from the host, so the container's identity must match the
 # ownership that library already has: everything this application renames, writes
 # EXIF into, or archives has to stay owned by the host user afterwards.
 ARG UID=1000
 ARG GID=1000
 LABEL org.opencontainers.image.title="photo_pipeline" \
      org.opencontainers.image.source="https://github.com/domverse/photoanalyzer" \
      io.photoanalyzer.exiftool.version="${EXIFTOOL_VERSION}" \
      io.photoanalyzer.immich-go.version="${IMMICH_GO_VERSION}"
 ENV PYTHONUNBUFFERED=1 \
    PYTHONDONTWRITEBYTECODE=1 \
    PATH=/opt/venv/bin:$PATH \
    PHOTO_PIPELINE_DATA_DIR=/data
 RUN set -eu; \
    apt-get update; \
    DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
        "libimage-exiftool-perl=${EXIFTOOL_VERSION}"; \
    rm -rf /var/lib/apt/lists/*
 COPY --from=uploader /usr/local/bin/immich-go /usr/local/bin/immich-go
 WORKDIR /app
 COPY pyproject.toml alembic.ini README.md ./
 COPY photo_pipeline ./photo_pipeline
 COPY migrations ./migrations
 COPY frontend ./frontend
 # The manuals are served by the application itself (US09-01), so they ship with it.
 COPY docs ./docs
 COPY docker/entrypoint.sh docker/healthcheck.sh /usr/local/bin/
 # Runtime dependencies only: the `test` extra (pytest, playwright) and the `vision`
 # extra stay out, and pip's build isolation leaves no build tooling behind.
 RUN set -eu; \
    python -m venv /opt/venv; \
    /opt/venv/bin/pip install --no-cache-dir -e .
 # What is installed must be what was pinned, or the labels and the version record
 # would be a claim rather than a fact.
 RUN set -eu; \
    mkdir -p /etc/photo-pipeline; \
    exiftool_version="$(exiftool -ver)"; \
    immich_go_version="$(immich-go version | head -n 1 | tr -d '\r')"; \
    expected_exiftool="$(printf '%s' "${EXIFTOOL_VERSION}" | cut -d+ -f1 | cut -d- -f1)"; \
    [ "${exiftool_version}" = "${expected_exiftool}" ] \
      || { echo "exiftool ${exiftool_version} is not the pinned ${expected_exiftool}" >&2; exit 1; }; \
    case "${immich_go_version}" in \
      *"${IMMICH_GO_VERSION}"*) ;; \
      *) echo "immich-go '${immich_go_version}' is not pinned ${IMMICH_GO_VERSION}" >&2; exit 1 ;; \
    esac; \
    printf '{\n  "exiftool": "%s",\n  "immich-go": "%s"\n}\n' \
        "${exiftool_version}" "${IMMICH_GO_VERSION}" > /etc/photo-pipeline/versions.json
 # Non-root, with the host library's ownership. /data is the persistent volume; the
 # photo library itself is mounted by the deployment (US08-03), never baked in.
 RUN set -eu; \
    groupadd --gid "${GID}" --non-unique app; \
    useradd --uid "${UID}" --gid "${GID}" --non-unique --no-create-home --home-dir /app app; \
    mkdir -p /data; \
    chown "${UID}:${GID}" /data
 USER ${UID}:${GID}
 EXPOSE 8000
 # Readiness, not liveness: an unmigrated or misconfigured database answers
 # /api/v1/health/ready with 503, and a container that cannot serve must not be
 # reported healthy. The worker role has no endpoint, so its check is a no-op here.
 HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
    CMD ["/usr/local/bin/healthcheck.sh"]
 ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
 CMD ["serve"]
--- a/README.md
+++ b/README.md
@@ -4,24 +4,6 @@ Integrated, restart-safe photo analysis, duplicate review, metadata, upload, and
 archive workflow. Planning lives in `INTEGRATED_PIPELINE_CONCEPT.md` and
 `delivery_backlog/`.
 ## Documentation
 The manuals live in [`docs/`](docs/index.md) and are the same files the running
 application serves at `/app/#/docs`:
 | | |
 |---|---|
 | [Overview](docs/overview.md) | what it does and the rules it will not break |
 | [Installation and operations](docs/installation.md) | host and container install, every setting, backup and restore, every refusal |
 | [A guided first pass](docs/first-pass.md) | one library from scan to verified upload |
 | [The stages](docs/index.md) | one illustrated page each, from inventory to archive |
 | [Errors and refusals](docs/errors.md) | every error code, cause, and remedy |
 | [Architecture](docs/architecture.md) | diagrams, module map, journals, invariants |
 This README stays the repository's own notes — how the code is built, tested, and
 released. Anything an operator or a user needs belongs in `docs/`, and one gate
 (`python -m photo_pipeline docs-gate`) keeps those pages honest against the code.
 ## Application (`photo_pipeline`)
 The target application lives in `photo_pipeline/` (FastAPI + SQLAlchemy + Alembic).
@@ -115,184 +97,6 @@ and the session cookie is marked `Secure` when that external scheme is HTTPS. He
 endpoints stay reachable without the secret so an orchestrator can restart the
 container; nothing else does.
 ## Container image (US08-02)
 One image runs either role. It is built from a clean checkout with no arguments:
 ```bash
 docker build -t photo-pipeline:dev .
 ```
 Everything external is pinned, and the build fails rather than drifting: the Python
 base image by tag *and* digest, `exiftool` by its Debian package version (verified
 against `exiftool -ver`), and `immich-go` by release version and per-architecture
 SHA-256 of the release asset. The verified versions become image labels and
 `/etc/photo-pipeline/versions.json`, which `diagnostics` reports as `tools[].pinned`
 beside the version actually installed — so a replaced binary shows up as a
 `tool_version_drift` warning instead of as a misparsed upload report.
 | build argument | default | why change it |
 |---|---|---|
 | `UID` / `GID` | `1000` | must match the owner of the mounted photo library |
 | `PYTHON_IMAGE` | pinned digest | upgrading the base image |
 | `EXIFTOOL_VERSION` | Debian package version | upgrading exiftool |
 | `IMMICH_GO_VERSION` + `IMMICH_GO_SHA256_AMD64`/`_ARM64` | pinned release | upgrading the uploader (take the digests from that release's `checksums.txt`) |
 The first argument is the role, and every other management command still works:
 ```bash
 docker run --rm -v /srv/photos:/srv/photos -v pp-data:/data \
  -e PHOTO_PIPELINE_LIBRARY_ROOTS=/srv/photos photo-pipeline:dev migrate
 docker run -d -p 127.0.0.1:8000:8000 -v /srv/photos:/srv/photos -v pp-data:/data \
  -e PHOTO_PIPELINE_HOST=0.0.0.0 -e PHOTO_PIPELINE_ACCESS_SECRET=... \
  -e PHOTO_PIPELINE_LIBRARY_ROOTS=/srv/photos photo-pipeline:dev serve
 docker run -d -v /srv/photos:/srv/photos -v pp-data:/data \
  -e PHOTO_PIPELINE_LIBRARY_ROOTS=/srv/photos photo-pipeline:dev worker
 ```
 One role per container: `serve` and `worker` each take the library process lock for
 their role (US07-05), so no supervisor starts both. The container refuses to run as
 UID 0 — files it renames or writes must keep the ownership the host library expects —
 and `/data` is the persistent volume holding the database, journals, backups, and
 thumbnail cache. Binding to `0.0.0.0` makes the access secret mandatory
 ([above](#reaching-it-through-a-hostname-or-proxy-us08-01)); `serve` refuses to start
 without it. The declared `HEALTHCHECK` polls `/api/v1/health/ready`, so a container
 whose database is unmigrated or misconfigured is never reported healthy.
 ## Composed runtime (US08-03)
 `docker-compose.yml` is the deployment: one `serve` container, one `worker`
 container, one bind-mounted library, one data volume, and a one-shot `migrate` that
 both roles wait for.
 ```bash
 cp .env.example .env && $EDITOR .env    # nothing has a value in it; fill in yours
 docker compose up -d --build
 ```
 `.env.example` lists every `PHOTO_PIPELINE_*` variable with its default in a comment
 and no values at all. The three the composition cannot start without are
 `PHOTO_PIPELINE_LIBRARY_HOST_PATH` (the library on this host),
 `PHOTO_PIPELINE_LIBRARY_ROOTS` (where it is mounted *inside* the container), and
 `PHOTO_PIPELINE_ACCESS_SECRET` — publishing the port means the app is reachable from
 outside the container, so US08-01 makes the secret mandatory. Set
 `PHOTO_PIPELINE_UID`/`GID` to the owner of the library: what the containers rename
 and rewrite keeps that ownership.
 | invariant | how the composition keeps it |
 |---|---|
 | one writer | `serve` and `worker` take their role's library lock (US07-05) in the shared `/data` volume, so `--scale worker=2` is refused by the lock, not by convention |
 | migrations first | `migrate` runs the backup-then-migrate path and must exit 0 before `api` and `worker` start; a failed upgrade leaves the previous database and its pre-migration backup intact |
 | container paths | `PHOTO_PIPELINE_LIBRARY_ROOTS` is both the mount target and the configured root; a root that is not mounted makes `serve`/`worker` exit 5 at startup instead of writing into the container's throwaway layer |
 | loopback by default | the port is published to `127.0.0.1` unless `PHOTO_PIPELINE_PUBLISH_ADDRESS` says otherwise, and exposing it needs the hostname in `PHOTO_PIPELINE_ALLOWED_HOSTS` plus the access secret |
 | restart safety | both roles are `restart: unless-stopped` with a 30 s stop grace period, and a job interrupted by a restart resumes exactly as it does on a host restart |
 The `data` volume holds the database, its write-ahead log, the thumbnail cache,
 journals, and backups. **It must stay on a local filesystem** — SQLite in WAL mode
 needs real local locking, so NFS, SMB, and network volume drivers are unsupported
 there and corrupt the database rather than slow it down. The library bind mount has
 no such restriction.
 Operating the deployment is operating the same CLI:
 ```bash
 docker compose run --rm --no-deps api diagnostics
 docker compose run --rm --no-deps api backup --reason pre-upgrade
 docker compose run --rm --no-deps api verify-backup /data/backups/<name>
 docker compose run --rm --no-deps api restore /data/backups/<name> --into /data/restored
 docker compose logs -f worker
 ```
 `--no-deps` keeps a one-off command from starting a second stack; `api` is only the
 service the command borrows the image and mounts from. `restore` is deliberately not
 an API call: it replaces the state of an installation and belongs to a stopped one,
 so stop `api` and `worker` first and restart them against the restored directory.
 ## Publishing and deploying (US08-04)
 Two workflows in `.gitea/workflows/` make `main` the only path to the running stack:
 | workflow | runs on | does |
 |---|---|---|
 | `test.yml` (**Test**) | every pull request, and every push to `main` | installs exiftool, the package, and Chromium, then runs the suites configured in `work_item/.work-item.yml` |
 | `deploy.yml` (**Deploy**) | a **successful** `Test` run on `main`, or manual dispatch | builds the image, pushes it, triggers the Portainer webhook, prunes dangling layers |
 Deploy waits for `Test` through `workflow_run`, so publishing is downstream of a green
 suite rather than of a push. `completed` is not `success`: the publish job runs only on
 `conclusion == 'success'`. Because an unmatched `workflow_run` filter does not fail but
 simply never fires, `tests/integration/test_deploy_workflows.py` asserts the link from
 both ends — renaming either workflow, or dropping one of the configured suites out of
 the test job, fails that test rather than silently unhooking the gate.
 The image is `git.domverse-berlin.eu/domverse/photoanalyzer`, tagged with the commit
 SHA and `latest`. The commit tag is pushed first, so a `latest` that exists always has
 a commit tag beside it and **a rollback is a tag change, not a rebuild**:
 ```bash
 docker pull  git.domverse-berlin.eu/domverse/photoanalyzer:<known-good-sha>
 docker tag   git.domverse-berlin.eu/domverse/photoanalyzer:<known-good-sha> \
             git.domverse-berlin.eu/domverse/photoanalyzer:latest
 docker push  git.domverse-berlin.eu/domverse/photoanalyzer:latest
 # then trigger the Portainer webhook, or redeploy the stack from Portainer
 ```
 Manual dispatch defaults to **dry run**: it builds and pushes `scratch-<sha>` only, and
 touches neither `latest` nor the running stack. Clear the `dry_run` input to publish by
 hand. A workflow-level `concurrency: deploy` group with `cancel-in-progress: false`
 queues deploys instead of overlapping them, so two commits can never race to `latest`.
 ### Secrets
 Repository secrets — used only by the pipeline:
 | secret | purpose |
 |---|---|
 | `REGISTRY_USER` | registry user with `write:package` |
 | `REGISTRY_TOKEN` | that user's token, passed on stdin, never as an argument |
 | `PORTAINER_WEBHOOK_URL` | the stack's auto-update POST URL; `curl --fail` makes a refused redeploy a failed workflow |
 Runtime secrets — `PHOTO_PIPELINE_VISION_API_KEY`, `PHOTO_PIPELINE_IMMICH_API_KEY`,
 `PHOTO_PIPELINE_ACCESS_SECRET` — are **not** repository secrets and are not in the
 image. The stack is managed by Portainer from git (`docker-compose.yml`), and those
 values live in the Portainer stack's environment, so rotation is one place and a
 repository read discloses nothing. A test asserts the workflows never name them.
 ## Container acceptance gate (US08-05)
 The deployed container is verified the way the host application is, by one command:
 ```bash
 work_item/scripts/python -m photo_pipeline container-gate --output gate-evidence
 ```
 It builds the image, provisions the composition against a **temporary fixture library
 on a bind mount and an isolated data volume**, runs the `phase_h` journeys against it,
 destroys every stack afterwards, and writes `release-report.json`, `logs/container.log`,
 and `CHECKSUMS.sha256` into the evidence directory. It exits non-zero when a journey
 fails, when the story matrix has a hole, **or when any check skipped at all** — unlike
 the release gate, this one accepts no environment excuse: a run that never reached the
 containers proved nothing about them.
 The journeys (`tests/e2e/test_phase_h_container.py`) are:
 | journey | what it proves |
 |---|---|
 | browser | discovery, duplicate review, analysis, album proposal, rename, upload preflight, and archive views, driven through the containerized frontend — including a rename that really moves the operator's folder on the bind mount |
 | upgrade | the previous version's image runs first, then this one against the same volume: schema at the new head, assets, analysis results, job progress, the unapplied rename plan, and the thumbnail cache all survive |
 | restart | `docker kill` on both containers mid-job; the job resumes, every photo ends with exactly one stored result, and only the in-flight item ever reaches the provider twice |
 | security | no session refused, a forged `X-Forwarded-Host` cannot smuggle an allowed hostname past the check, a symlink out of the mounted library is refused, an unmounted library root refuses startup, and no secret appears in `docker compose logs` |
 The upgrade journey builds the previous commit's tree when no published image is named;
 point it at the real one with `PHOTO_PIPELINE_PREVIOUS_IMAGE`. On a Docker VM (Colima,
 Docker Desktop) the fixture library must live on a shared path — it defaults to
 `~/.cache/photo-pipeline`, overridable with `PHOTO_PIPELINE_TEST_MOUNT_BASE`.
 CI runs this gate as the `container` job of **Test** on pushes to `main` and keeps its
 evidence as a run artefact. Deploy waits for the whole `Test` workflow, so a red
 container gate is a publish that does not happen.
 ## Testing
 One offline command runs the whole suite (unit, integration, and browser
--- a/delivery_backlog/E09-documentation.md
+++ b/delivery_backlog/E09-documentation.md
@@ -1,77 +0,0 @@
 # E09 — Product Documentation
 Concept phase: none. Like [E08](E08-container-deployment.md), this epic is a delivery
 addition rather than a product-scope change: the same application, documented well
 enough that somebody who did not build it can install it, understand it, and operate it
 without reading the source.
 It does not change the product scope in
 [`INTEGRATED_PIPELINE_CONCEPT.md`](../INTEGRATED_PIPELINE_CONCEPT.md). No safety
 invariant moves, no schema changes, no new runtime capability. The one change to the
 running application is a documentation view and the static assets it needs.
 ## Why the application serves its own documentation
 The manuals describe an application that is reached over HTTP behind an access secret.
 Documentation that lives only in the repository is unreachable from the deployment it
 describes: an operator who has just been handed a URL and a secret has no Gitea account
 in front of them. So the same markdown files are both the repository's documentation and
 the deployment's `/docs` view, and neither is a copy of the other.
 ## Decisions made in this epic
 **Markdown is the source.** Everything is written as markdown under `docs/`, so it is
 reviewable in a diff, readable on Gitea, and renderable in the app. No documentation
 format that only a tool can read.
 **The renderer is vendored, not written and not fetched.** `marked` (MIT, no
 dependencies, ships an ES module) is pinned and committed under
 `frontend/js/vendor/`. A CDN is not an option: the application is deployed to a network
 whose outbound access is not assumed, and `default-src 'self'` forbids it.
 **Diagrams are mermaid, rendered client-side, with the script boundary intact.** The
 claim that mermaid requires `'unsafe-eval'` was tested rather than believed: mermaid 11's
 bundle contains no `eval(` and no `new Function` — only a lodash `Function("return this")`
 global-detection fallback that short-circuits on `globalThis` and never executes.
 Rendered under this application's exact CSP, a flowchart produced a 15.8 KB SVG and
 raised **no `script-src` violation**. What it does raise is `style-src`: mermaid styles
 its output with an injected `<style>` element and `style=` attributes.
 So `script-src 'self'` stays exactly as US07-02 and US08-01 left it, and `style-src`
 gains `'unsafe-inline'`. That relaxation is bounded on purpose: with `script-src` intact
 no injected markup can execute, and with `img-src`, `connect-src`, and `font-src` all
 still `'self'`, the CSS-based exfiltration channels stay closed. What remains is
 defacement of a page the operator is already authenticated on.
 The rejected alternative is recorded because it may become the better trade later:
 pre-rendering each diagram to a committed SVG with the already-installed Playwright
 (no Node toolchain needed) and serving that, which would leave CSP untouched entirely at
 the cost of a generator and a freshness check. If `style-src 'unsafe-inline'` is ever
 judged too much, that is the migration, and it does not change a single markdown file.
 **Screenshots are produced, not pasted.** Every screenshot in the user manual is captured
 by Playwright from the real application against a temporary fixture library, by the same
 kind of code that already drives the browser suites. A screenshot nobody can regenerate
 is a screenshot that silently stops being true.
 **The documentation is held to the code by tests.** Configuration keys, CLI commands,
 exit codes, API error codes, job and journal states, and module names all appear in both
 the code and the manuals. Each of those is cross-checked, so the failure mode of stale
 documentation is a red test rather than a misled operator.
 ## Stories
 1. [US09-01 — Serve the documentation inside the application](stories/US09-01-docs-in-app.md)
 2. [US09-02 — Write the installation and operations manual](stories/US09-02-installation-manual.md)
 3. [US09-03 — Write the architecture overview](stories/US09-03-architecture-overview.md)
 4. [US09-04 — Write the user manual with generated screenshots](stories/US09-04-user-manual.md)
 5. [US09-05 — Automate documentation acceptance](stories/US09-05-docs-gate.md)
 ## Epic outcome
 A deployed instance serves its own installation manual, architecture overview, and
 illustrated user manual at `/app/#/docs`, rendered from the same markdown files that are
 readable in the repository. Screenshots are regenerated from the running application,
 every documented command, setting, state, and error code is cross-checked against the
 code that implements it, and one gate fails the build when documentation and application
 disagree.
--- a/delivery_backlog/README.md
+++ b/delivery_backlog/README.md
@@ -2,14 +2,13 @@
 This backlog decomposes the phases in
 [`INTEGRATED_PIPELINE_CONCEPT.md`](../INTEGRATED_PIPELINE_CONCEPT.md) into seven
-epics and small, independently verifiable user stories, plus two delivery-format
+epics and small, independently verifiable user stories, plus one delivery-format
-epics: E08 packages the released application as a deployable container, and E09
+epic (E08) that packages the released application as a deployable container.
 documents it for the people who install, operate, and use it.
 ## Numbering and file naming
- Epics: `E01` through `E07`, matching concept Phases A through G; `E08` and `E09`
+- Epics: `E01` through `E07`, matching concept Phases A through G; `E08` has no
-  have no concept phase and must not change product scope.
+  concept phase and must not change product scope.
 - Stories: `US<epic>-<sequence>`, for example `US03-02`.
 - Epic files: `E01-<slug>.md`.
 - Story files: `stories/US01-01-<slug>.md`.
@@ -40,7 +39,6 @@ documents it for the people who install, operate, and use it.
 6. [E06 — Archive lifecycle](E06-archive-lifecycle.md)
 7. [E07 — Hardening and release](E07-hardening-release.md)
 8. [E08 — Container deployment](E08-container-deployment.md)
 9. [E09 — Product documentation](E09-documentation.md)
 ## Shared definition of done
--- a/delivery_backlog/stories/US09-01-docs-in-app.md
+++ b/delivery_backlog/stories/US09-01-docs-in-app.md
@@ -1,49 +0,0 @@
 # US09-01 — Serve the Documentation Inside the Application
 Epic: [E09](../E09-documentation.md)
 As an operator who was handed a URL and an access secret, I want the manuals inside the
 application I am looking at, so that understanding it does not require a repository
 checkout or an internet connection.
 ## Acceptance criteria
 - Documentation lives as markdown under `docs/`, with an index that names every page and
  the order it is meant to be read in. The same files render on Gitea without
  modification.
 - The application serves a `/docs` view reachable from the main navigation, listing the
  pages and rendering the selected one.
 - Rendering uses a vendored, version-pinned markdown library committed under
  `frontend/js/vendor/`. It is not fetched from a CDN, not bundled by a build step, and
  not written by hand. The build records the version and a checksum of the vendored file.
 - Diagrams written as ```mermaid``` fenced blocks render as diagrams. Mermaid is vendored
  the same way.
 - `script-src` in the Content-Security-Policy is unchanged: no `'unsafe-eval'`, no
  `'unsafe-inline'`. Only `style-src` gains `'unsafe-inline'`, and the reason is recorded
  where the policy is defined.
 - Links between documents work in the app: a relative `../foo.md#section` link navigates
  to that page and heading rather than downloading a file or leaving the application.
  Every heading has a stable anchor, and a deep link to an anchor scrolls to it.
 - An unknown page renders a documentation-specific not-found message with a link back to
  the index, and never exposes a filesystem path.
 - Documentation is readable without an access secret **or** behind the same session as
  the rest of the application — whichever is chosen is stated explicitly in the story's
  implementation notes and covered by a test, because an operator locked out by a
  configuration mistake is exactly who needs the troubleshooting page.
 - The view works with no outbound network access at all.
 ## Automated tests
 - Unit: heading-anchor slugs (duplicates, punctuation, non-ASCII), and the rewriting of
  relative markdown links into in-app routes.
 - Integration: every markdown file under `docs/` is reachable from the index; every
  internal link in every document resolves to a file and, where an anchor is given, to a
  heading that exists; the vendored library files match their recorded checksums.
 - Browser: the documentation view renders a page, follows an internal link, deep-links to
  an anchor, renders a mermaid diagram to an SVG, and shows the not-found message for an
  unknown page — all with **zero console errors and zero CSP violations**, asserted, not
  eyeballed.
 ## Dependencies
 - None beyond the delivered application.
--- a/delivery_backlog/stories/US09-02-installation-manual.md
+++ b/delivery_backlog/stories/US09-02-installation-manual.md
@@ -1,46 +0,0 @@
 # US09-02 — Write the Installation and Operations Manual
 Epic: [E09](../E09-documentation.md)
 As somebody installing this application for the first time, I want one manual that takes
 me from nothing to a running instance pointed at my photo library, so that I do not have
 to reconstruct the procedure from the README, the compose file, and the test suite.
 ## Acceptance criteria
 - A **host installation** path: prerequisites and their versions (Python, exiftool,
  immich-go, Playwright's browser for the test suite), virtual environment, dependency
  install, `.env`, database migration, starting `serve` and `worker`, and how to verify
  the install succeeded.
 - A **container installation** path: the published image, the compose file, the data
  volume, the library bind mount and why it is mounted the way it is, published ports,
  running behind a reverse proxy with `PHOTO_PIPELINE_ALLOWED_HOSTS` and
  `PHOTO_PIPELINE_TRUSTED_PROXIES`, and the Portainer/webhook deployment already in use.
 - A **configuration reference**: every `PHOTO_PIPELINE_*` setting with its meaning,
  default, accepted values, and whether it is a secret. Secrets are described, never
  exemplified with a real-looking value.
 - A **first run checklist** that ends in a verified state: library discovered, worker
  claiming jobs, readiness endpoint green, diagnostics clean.
 - **Operations**: upgrading (including what the migration backup does), backup, verify,
  restore, pruning, diagnostics, and the log locations for each role.
 - **Troubleshooting**: each refusal an operator can hit at startup — every non-zero exit
  code of the CLI, the trust-boundary refusal, the unmounted library root refusal, the
  library lock being held, and a legacy CLI still running — with the cause and the fix.
 - The manual states the safety invariants an installer must not work around: one worker
  writes, `_IGNORE/` is never read, EXIF is verified before upload, and the library lock
  is authoritative.
 ## Automated tests
 - Every `PHOTO_PIPELINE_*` setting documented exists as a field on `Config`, and every
  field on `Config` is documented — both directions, so a new setting cannot ship
  undocumented.
 - Every CLI command and flag named in the manual exists in the argument parser, and every
  subcommand the parser accepts appears in the manual.
 - Every exit code documented is one the CLI can actually return.
 - No documented example value collides with a real secret pattern (the repository's own
  credential scanner runs over `docs/`).
 ## Dependencies
 - US09-01
--- a/delivery_backlog/stories/US09-03-architecture-overview.md
+++ b/delivery_backlog/stories/US09-03-architecture-overview.md
@@ -1,47 +0,0 @@
 # US09-03 — Write the Architecture Overview
 Epic: [E09](../E09-documentation.md)
 As a developer or reviewer new to this repository, I want an architecture overview that
 explains what the pieces are and which rules they enforce, so that I can find the right
 module and not violate an invariant I never knew existed.
 ## Acceptance criteria
 - A **context diagram**: the operator, the browser application, the API and worker, the
  photo library, the Immich server, the vision provider, and the archive destination —
  with the direction and nature of every interaction, including which ones leave the
  machine.
 - A **runtime diagram**: the migrate/api/worker composition, the data volume, the library
  bind mount, the SQLite database, and the process lock — showing what is shared and what
  is exclusive.
 - A **module map**: every package under `photo_pipeline/` with its responsibility and the
  boundary it must not cross (which modules may touch the filesystem, which may call an
  external provider, which own schema).
 - **Key flows**, each as a diagram plus prose: the durable job lifecycle from enqueue to
  recovery; the rename journal state machine including the rollback and manual-resolution
  paths; the upload lifecycle through preflight, run, report ingestion, and verification.
 - **The invariants and where they are enforced**, each pointing at the module that owns
  it: one writer at a time, the library process lock, the path policy and library roots,
  `_IGNORE/` exclusion, verified EXIF before upload, safety decisions gating the vision
  provider, and restart-safety of every mutation.
 - **The data model**: the tables, what identity means for an asset, and how a moved file
  keeps its identity.
 - A short **history and donor** section: what was migrated out of the legacy CLIs, where
  the archive and its ledger live, and why they are kept.
 - Diagrams are ```mermaid``` blocks so the source is diffable and Gitea renders them
  natively.
 ## Automated tests
 - Every package and top-level module under `photo_pipeline/` appears in the module map,
  and every module named in the map exists — a new service cannot appear on the map's
  blind side.
 - Every job state, journal state, and upload batch state named in the document exists in
  the code, and every state the code defines is named in the document.
 - Every mermaid block parses (rendered in the browser test without an error node).
 - Every code path referenced by file name exists.
 ## Dependencies
 - US09-01
--- a/delivery_backlog/stories/US09-04-user-manual.md
+++ b/delivery_backlog/stories/US09-04-user-manual.md
@@ -1,52 +0,0 @@
 # US09-04 — Write the User Manual with Generated Screenshots
 Epic: [E09](../E09-documentation.md)
 As the person actually sorting a photo library, I want a manual that walks the workflow
 screen by screen and tells me what each refusal means, so that I can use the application
 confidently and know what it is about to do to my files before it does it.
 ## Acceptance criteria
 - One page per workflow stage, in the order the application presents them: discovery and
  inventory, duplicate review, safety review, analysis, album proposals, renames, upload,
  archive, and diagnostics. Each page answers the same four questions: what this stage is
  for, what I have to decide, **what it changes on disk or on the server**, and what it
  refuses to do.
 - A **guided first pass** that takes a new library from scan to a verified upload, naming
  the point of no return in each stage and what is reversible after it.
 - Every stage page carries at least one screenshot of the real application showing the
  state being described.
 - Screenshots are **generated** by a committed Playwright script that seeds a temporary
  fixture library, drives the application, and writes the images. Regenerating them is one
  documented command. No screenshot is captured by hand.
 - Screenshots contain no real library paths, no personal photos, and no secrets — the
  fixture library is synthetic, and this is asserted rather than assumed.
 - An **error and refusal catalogue**: every `error.code` the API can return, with what
  causes it, what the application did or refused to do, and what the operator should do
  next. Refusals that protect data (`lock_held`, `rename_recovery_required`,
  `stale_preflight`, `path_not_allowed`, `host_not_allowed`, `dry_run_not_approved`,
  conflict codes) are explained as intentional, not as faults.
 - A **recovery** page: an interrupted rename, an uncertain upload, a failed migration, a
  restored backup — what the application does by itself and what needs a decision.
 - The work-item safety allow list is extended to permit `docs/images/**`, since the
  repository denies image files by default. This is an explicit, reviewed change, not a
  quiet one, and it stays narrow enough that a real photo still cannot be committed.
 ## Automated tests
 - Every `error.code` the application can emit is documented, and every code documented
  exists in the code — both directions.
 - Every image referenced by a documentation page exists, and every image under
  `docs/images/` is referenced by a page.
 - The screenshot generator runs end to end in the test environment and produces every
  image the manual references, against a temporary fixture library that is destroyed
  afterwards.
 - Generated screenshots are checked for library paths outside the fixture root and for
  the configured secrets.
 - Browser: each stage page renders in the documentation view with its screenshot loaded
  and no console error.
 ## Dependencies
 - US09-01
--- a/delivery_backlog/stories/US09-05-docs-gate.md
+++ b/delivery_backlog/stories/US09-05-docs-gate.md
@@ -1,38 +0,0 @@
 # US09-05 — Automate Documentation Acceptance
 Epic: [E09](../E09-documentation.md)
 As a release owner, I want one gate that proves the documentation still describes the
 application, so that a change to the code cannot quietly make the manuals wrong.
 ## Acceptance criteria
 - One documented command runs every documentation check and retains its evidence, in the
  shape the release and container gates already use.
 - The gate fails when: an internal link or anchor is dead; a page is unreachable from the
  index; an image is referenced but missing or present but unreferenced; a documented
  setting, command, exit code, error code, or state does not exist in the code; a code
  path exists that the documentation is required to cover and does not.
 - The gate regenerates the screenshots and fails when a regenerated image no longer
  matches the committed one beyond a stated tolerance, so a UI change that invalidates the
  manual is a red build rather than a discovery months later.
 - The gate renders every documentation page in a real browser and fails on any console
  error or CSP violation, and asserts that `script-src` contains neither `'unsafe-eval'`
  nor `'unsafe-inline'`.
 - The checks run on a `phase_i` marker; CI runs the gate, and the earlier epic suites keep
  running unchanged.
 - The README and the application's documentation index point at each other, so neither is
  the forgotten copy.
 - Documentation stories are mapped in the story traceability matrix like every other
  story.
 ## Automated tests
 - The gate's own contract is testable without a browser: a seeded broken link, a missing
  image, an undocumented error code, and a stale screenshot each fail it, and a clean tree
  passes.
 - The full documentation suite runs on `phase_i` in CI.
 ## Dependencies
 - US09-01 through US09-04
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,105 +0,0 @@
 # The deployed runtime (US08-03): one API, one worker, one library, one volume.
 #
 # The same image (US08-02) runs both roles, so what is composed here is process
 # topology, not a second application. Three invariants shape it:
 #
 #   * one writer — `serve` and `worker` each take the library process lock for their
 #     role (US07-05), and both containers mount the *same* data volume, which is what
 #     makes the lock file visible to both. Scaling `worker` past 1 is refused by that
 #     lock rather than by anyone remembering not to;
 #   * one local filesystem — the database, its write-ahead log, the thumbnail cache,
 #     and the backups live in the `data` volume, and SQLite in WAL mode requires real
 #     local-filesystem locking. A network mount (NFS, SMB, or a cloud volume driver)
 #     is unsupported for it; that is a corrupted database, not a slow one;
 #   * one library path vocabulary — `PHOTO_PIPELINE_LIBRARY_ROOTS` names the path
 #     *inside* the container, which is also the bind mount's target below. A root
 #     that is not mounted there makes `serve` and `worker` refuse at startup instead
 #     of writing into the container's throwaway layer.
 #
 # Configuration and secrets come from the environment only: copy `.env.example` to
 # `.env` and fill it in. Nothing is baked into the image and nothing with a value in
 # it is committed.
 #
 #   cp .env.example .env && $EDITOR .env
 #   docker compose up -d --build
 #
 # Operating it is operating the same CLI — `docker compose run --rm --no-deps api
 # <command>` — see README, "Composed runtime".
 name: photo-pipeline
 x-runtime: &runtime
  image: ${PHOTO_PIPELINE_IMAGE:-photo-pipeline:dev}
  build:
    context: .
    args:
      # Everything the app renames or rewrites has to stay owned by the host user
      # the library already belongs to.
      UID: ${PHOTO_PIPELINE_UID:-1000}
      GID: ${PHOTO_PIPELINE_GID:-1000}
  user: "${PHOTO_PIPELINE_UID:-1000}:${PHOTO_PIPELINE_GID:-1000}"
  env_file:
    - ${PHOTO_PIPELINE_ENV_FILE:-.env}
  volumes:
    - data:/data
    - "${PHOTO_PIPELINE_LIBRARY_HOST_PATH:?set PHOTO_PIPELINE_LIBRARY_HOST_PATH to the photo library on this host}:${PHOTO_PIPELINE_LIBRARY_ROOTS:?set PHOTO_PIPELINE_LIBRARY_ROOTS to the container-side library path}"
  # Jobs check for cancellation between items and leave a resumable record; a
  # too-short grace period turns an orderly stop into a recovery on next start.
  stop_grace_period: 30s
 x-environment: &environment
  # Set here rather than left to the file: these two are what the composition itself
  # promises, and an `.env` that disagreed would move the database off the volume or
  # the library off its mount.
  PHOTO_PIPELINE_DATA_DIR: /data
  PHOTO_PIPELINE_LIBRARY_ROOTS: ${PHOTO_PIPELINE_LIBRARY_ROOTS}
 services:
  # Migrations run to completion before either role accepts work, through the same
  # backup-then-migrate path the roles use (US07-05): a pending upgrade is snapshotted
  # first, and a failed one exits non-zero with the backup named — so `api` and
  # `worker` never start, and the previous database is left intact and restorable.
  migrate:
    <<: *runtime
    command: ["migrate"]
    environment: *environment
    restart: "no"
  api:
    <<: *runtime
    command: ["serve"]
    environment:
      <<: *environment
      # Published to host loopback below. Inside the container the server must bind
      # the container's own interface for that publish to reach it, which is exactly
      # what makes the access secret mandatory (US08-01) — `serve` refuses to start
      # without one. Exposing the port beyond loopback additionally needs
      # PHOTO_PIPELINE_ALLOWED_HOSTS to name the hostname it is reached under.
      PHOTO_PIPELINE_HOST: 0.0.0.0
      PHOTO_PIPELINE_PORT: 8000
    ports:
      # Host side only: PHOTO_PIPELINE_PORT in `.env` moves the *published* port, and
      # the container always serves 8000, which is what the image's health check probes.
      - "${PHOTO_PIPELINE_PUBLISH_ADDRESS:-127.0.0.1}:${PHOTO_PIPELINE_PORT:-8000}:8000"
    depends_on:
      migrate:
        condition: service_completed_successfully
    restart: unless-stopped
  # One worker. A second one is refused by the library lock in the shared data
  # volume, which is the point: `docker compose up --scale worker=2` fails loudly
  # instead of running two writers against one library.
  worker:
    <<: *runtime
    command: ["worker", "--id", "worker-1"]
    environment: *environment
    depends_on:
      migrate:
        condition: service_completed_successfully
    restart: unless-stopped
 volumes:
  # Local driver on purpose: the database, WAL, thumbnail cache, and backups need a
  # real local filesystem. Do not point this at NFS, SMB, or a network volume driver.
  data:
    driver: local
--- a/docker/entrypoint.sh
+++ b/docker/entrypoint.sh
@@ -1,22 +0,0 @@
 #!/bin/sh
 # One entrypoint, one role per container (US08-02).
 #
 # The first argument is the management command the image runs — `serve` and `worker`
 # are the two roles, and every other `python -m photo_pipeline` command (migrate,
 # diagnostics, backup, restore, dry-run) is passed through unchanged so operating the
 # container is operating the same CLI. No supervisor: two roles in one container would
 # share a process lock they are each meant to hold alone (US07-05).
 set -eu
 if [ "$(id -u)" = "0" ]; then
    echo "refusing to run as root: start this image with a non-root UID/GID so files" \
         "it renames or writes keep the ownership the mounted library expects" >&2
    exit 1
 fi
 role="${1:-serve}"
 # The health check has to know which role it is checking, and only the API has an
 # endpoint to check. /tmp is writable for the unprivileged user; /run may not be.
 printf '%s' "${role}" > "${PHOTO_PIPELINE_ROLE_FILE:-/tmp/photo-pipeline-role}" 2>/dev/null || true
 exec python -m photo_pipeline "$@"
--- a/docker/fetch-immich-go.py
+++ b/docker/fetch-immich-go.py
@@ -1,72 +0,0 @@
 """Download one pinned immich-go release and verify it before unpacking (US08-02).
 Run at image build time by the `uploader` stage, with the interpreter that is already
 in the base image: no curl, no wget, and no download tooling in the layer that ships.
 The checksum is not advisory — a release asset that does not match the pinned digest
 is a failed build, not a warning, because the uploader's flags and report format are
 what the upload parser is written against (concept §15).
 """
 from __future__ import annotations
 import argparse
 import hashlib
 import platform
 import tarfile
 import tempfile
 import urllib.request
 from pathlib import Path
 RELEASE_URL = "https://github.com/simulot/immich-go/releases/download/v{version}/{asset}"
 # Debian/BuildKit architecture as the interpreter sees it → release asset name.
 ASSETS = {
    "x86_64": ("immich-go_Linux_x86_64.tar.gz", "amd64"),
    "amd64": ("immich-go_Linux_x86_64.tar.gz", "amd64"),
    "aarch64": ("immich-go_Linux_arm64.tar.gz", "arm64"),
    "arm64": ("immich-go_Linux_arm64.tar.gz", "arm64"),
 }
 TIMEOUT_SECONDS = 300
 def main() -> int:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--version", required=True, help="immich-go release, without the v")
    parser.add_argument("--sha256-amd64", required=True)
    parser.add_argument("--sha256-arm64", required=True)
    parser.add_argument("--into", default="/usr/local/bin")
    args = parser.parse_args()
    machine = platform.machine().lower()
    if machine not in ASSETS:
        raise SystemExit(f"unsupported architecture: {machine}")
    asset, arch = ASSETS[machine]
    expected = {"amd64": args.sha256_amd64, "arm64": args.sha256_arm64}[arch]
    url = RELEASE_URL.format(version=args.version, asset=asset)
    with urllib.request.urlopen(url, timeout=TIMEOUT_SECONDS) as response:  # noqa: S310
        payload = response.read()
    digest = hashlib.sha256(payload).hexdigest()
    if digest != expected:
        raise SystemExit(f"checksum mismatch for {url}: {digest} != {expected}")
    target = Path(args.into)
    target.mkdir(parents=True, exist_ok=True)
    with tempfile.TemporaryDirectory() as work:
        archive = Path(work) / asset
        archive.write_bytes(payload)
        with tarfile.open(archive) as tar:
            member = tar.getmember("immich-go")
            # Extract exactly the one file this pin is about, by name, so nothing
            # else in the archive can decide where it lands.
            extracted = tar.extractfile(member)
            if extracted is None:
                raise SystemExit("release archive contains no immich-go binary")
            binary = target / "immich-go"
            binary.write_bytes(extracted.read())
            binary.chmod(0o755)
    print(f"immich-go {args.version} ({arch}) verified {digest}")
    return 0
 if __name__ == "__main__":
    raise SystemExit(main())
--- a/docker/healthcheck.sh
+++ b/docker/healthcheck.sh
@@ -1,34 +0,0 @@
 #!/bin/sh
 # Container health for the `serve` role: readiness, not liveness (US08-02).
 #
 # /api/v1/health/ready is 503 until the database is reachable, migrated, and in WAL
 # mode with foreign keys on, so an unmigrated or misconfigured container never reports
 # healthy. Health endpoints need no session and no access secret, which is what lets an
 # orchestrator restart a container it holds no credentials for (US08-01).
 set -eu
 role="$(cat "${PHOTO_PIPELINE_ROLE_FILE:-/tmp/photo-pipeline-role}" 2>/dev/null || echo unknown)"
 if [ "${role}" != "serve" ]; then
    # ponytail: the worker has no endpoint to probe; its liveness is its lease and job
    # heartbeat in the database. Add a `worker --health` command if a restart policy
    # ever needs to act on it.
    exit 0
 fi
 port="${PHOTO_PIPELINE_PORT:-8000}"
 exec python - "${port}" <<'PY'
 import sys
 import urllib.error
 import urllib.request
 url = f"http://127.0.0.1:{sys.argv[1]}/api/v1/health/ready"
 try:
    with urllib.request.urlopen(url, timeout=5) as response:  # noqa: S310 — loopback
        sys.exit(0 if response.status == 200 else 1)
 except urllib.error.HTTPError as error:
    print(f"not ready: HTTP {error.code}", file=sys.stderr)
    sys.exit(1)
 except OSError as error:
    print(f"not ready: {error}", file=sys.stderr)
    sys.exit(1)
 PY
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -1,224 +0,0 @@
 # Architecture
 [← Documentation index](index.md)
 For whoever has to change this code without breaking somebody's photo library. It
 explains what the pieces are, which rules each one keeps, and where to look when a
 stage refuses.
 The product decisions behind all of it live in `INTEGRATED_PIPELINE_CONCEPT.md`; this
 page describes what was built.
 ## Context
 Five things outside the application, and what actually crosses each boundary.
 ```mermaid
 flowchart LR
  operator([Operator]):::person -->|browser, one session| app
  app[Photo Pipeline]:::system -->|read, rename, EXIF write| library[(Photo library<br/>bind mount)]
  app -->|database, cache, journals, backups| data[(Data directory<br/>local filesystem)]
  app -->|confirmed-SFW images only| vision[Vision provider]:::ext
  app -->|immich-go, verified bytes| immich[Immich server]:::ext
  app -->|copy, verify, then remove| archive[(Archive medium)]
  classDef person fill:#1f6feb,stroke:#58a6ff,color:#fff
  classDef system fill:#238636,stroke:#3fb950,color:#fff
  classDef ext fill:#6e40c9,stroke:#a371f7,color:#fff
 ```
 | boundary | leaves the machine? | carries |
 |---|---|---|
 | operator → app | no (loopback, or a proxy you configured) | commands against stable ids, never paths |
 | app → library | no | reads, folder renames, EXIF merges |
 | app → data directory | no | SQLite in WAL mode, thumbnails, journals, backups |
 | app → vision provider | **yes** | image bytes of confirmed-SFW canonical assets only |
 | app → Immich | **yes** | the exact verified bytes of an approved album |
 | app → archive medium | no | copies, verified before the source is removed |
 ## Runtime
 Two long-lived processes and a one-shot migration, sharing one database and one
 library.
 ```mermaid
 flowchart TD
  browser([Browser]) -->|JSON + SSE| api
  migrate["migrate<br/>backup, then upgrade"] -->|must exit 0| api
  migrate --> worker
  api["api · serve<br/>enqueues, serves, reads"] -->|jobs table| db[(SQLite WAL)]
  worker["worker<br/>claims and does the work"] -->|jobs table| db
  worker --> tools["exiftool · vision API · immich-go"]
  api -.->|api.lock.json| lock{{library lock}}
  worker -.->|worker.lock.json| lock
  api --> lib[(library)]
  worker --> lib
 ```
 `serve` enqueues and renders; **it does not do the work**. Everything that scans,
 scores, analyses, renames, uploads, or archives happens in the worker, which claims
 a queued job atomically with a fencing token. One mutating job runs at a time, and
 the lock file in the data directory is what makes a second worker impossible rather
 than merely discouraged.
 ## The modules
 | package | owns | must not |
 |---|---|---|
 | `api/` | HTTP surface, error envelope, security policy | contain SQL or business logic |
 | `api/routes/` | one module per resource group, all under `/api/v1` | accept a filesystem path from the browser |
 | `api/security.py` | host/origin/CSRF/session/size policy as one pure `evaluate`, plus the ASGI middleware | be bypassed per-route |
 | `schemas/` | Pydantic request and response contracts | reach the database |
 | `services/` | all domain logic; the only place a decision is made | be imported by the frozen CLI archive |
 | `models/` | SQLAlchemy tables | hold behaviour |
 | `jobs/` | durable job lifecycle, worker loop, lock ranks, handler registry | run work in the API process |
 | `integrations/` | the real outside world: `exiftool`, vision, NSFW model, `immich-go` and its report grammars | be called without a version recorded |
 | `path_policy.py` | the library boundary, `_IGNORE/` exclusion, symlink-escape refusal | be duplicated anywhere |
 | `imaging.py` | the single bounded-decode door | let a caller open an image directly |
 | `faults.py` | the crash barriers the tests fire | read anything but its one env var |
 | `config.py` | typed settings, secrets as `SecretStr` | log or return a value |
 | `db.py` | engine, sessions, WAL and foreign keys, migration entry | be used to bypass a repository |
 Services worth knowing by name: `inventory`, `duplicates`, `safety`, `analysis`,
 `albums`/`proposals`/`naming`, `renames`/`rename_apply`/`rename_journal`,
 `uploads`/`upload_batches`/`upload_reports`/`upload_verification`,
 `archives`/`archive_transfer`/`archive_journal`/`restores`/`availability`,
 `thumbnails`, `hashing`, `exif_checkpoint`, `jobs`, `workflow`, `backup`,
 `diagnostics`, `app_lock`, `release`, `benchmarks`, `library`, `legacy_import`.
 ## The state machines
 Three journals decide what a restart is allowed to assume. All three are read from
 the database plus the real world — never guessed from a missing file.
 ### Durable jobs
 ```mermaid
 stateDiagram-v2
  [*] --> queued
  queued --> running: claimed with a fencing token
  queued --> cancelled
  queued --> cancelling
  running --> succeeded
  running --> failed
  running --> cancelling
  cancelling --> cancelled
  failed --> retry_queued
  retry_queued --> running
  succeeded --> [*]
  cancelled --> [*]
 ```
 `succeeded` and `cancelled` are terminal, so a duplicate delivery cannot move a
 finished job. Claiming is compare-and-set on the row version; a worker whose lease
 expired cannot commit after another has taken over.
 ### The rename journal
 The only state machine that moves somebody's folders.
 ```mermaid
 stateDiagram-v2
  [*] --> planned
  planned --> moving
  moving --> moved
  moving --> planned: proven untouched
  moving --> rollback_required
  moved --> database_updated
  database_updated --> verified
  verified --> complete
  moved --> rollback_required
  database_updated --> rollback_required
  verified --> rollback_required
  planned --> failed
  failed --> planned
  rollback_required --> rolled_back
  complete --> [*]
  rolled_back --> [*]
 ```
 Intent is written **before** the disk is touched, which is why `moving` can resolve
 backwards: the evidence decides. `moving`, `moved`, `database_updated`, and
 `rollback_required` are the unsafe states — while any operation sits in one, the
 library may be half-renamed, so unrelated mutations are refused with
 `409 rename_recovery_required` until a person resolves it.
 ### Upload batches
 ```mermaid
 stateDiagram-v2
  [*] --> planned
  planned --> running
  running --> succeeded
  running --> failed
  running --> cancelling
  running --> unknown_requires_verification: process died after acceptance
  cancelling --> cancelled
  failed --> running: retry
  cancelled --> running: retry
 ```
 `unknown_requires_verification` is deliberately **not** restartable. The server may
 already hold the files; the answer is to ask Immich for the recorded SHA-1, not to
 upload again and hope.
 Archive transfers use the same shape — `planned → transferring → verified →
 removing → complete` — and the source is removed only after the archived bytes are
 verified.
 ## Identity and the data model
 A path is metadata. The identity is `assets.id`, a UUID that never changes, and
 `asset_paths` records every path an asset has ever had with the reason it changed.
 That is what makes a rename cheap: nothing else in the database has to move.
 Tables: `assets`, `asset_paths`, `thumbnails`, `jobs`, `job_items`, `job_events`,
 `safety_reviews`, `analysis_results`, `exif_projections`, `duplicate_clusters`,
 `duplicate_members`, `duplicate_negative_links`, `album_proposals`, `rename_plans`,
 `rename_operations`, `upload_batches`, `upload_items`, `upload_verifications`,
 `archive_locations`, `archive_plans`, `archive_operations`.
 Availability is independent of workflow progress: `active`, `archiving`,
 `archived_online`, `archived_offline`, `restoring`, `missing_unexpected`. An
 unmounted archive disk is `archived_offline`, never `missing` — the scanner is not
 allowed to conclude that a photo is gone because a disk is unplugged.
 EXIF is a projection with its own verified state (`verified`, `divergent`,
 `failed`): the desired values are written, read back, and compared, and anything the
 stage does not own having changed makes the asset `divergent` and blocks the next
 mutating stage.
 ## Where each invariant lives
 | invariant | enforced in |
 |---|---|
 | `_IGNORE/` is never traversed, counted, or opened | `path_policy.is_excluded`, used by every discovery path |
 | no path outside the library roots is reachable | `path_policy.resolve_in_roots` — it returns the resolved path, because validating one name and opening another is the symlink race |
 | one writer per library | `services/app_lock.py` (an `flock` on a JSON lock file, per role) |
 | one mutating job at a time | `services/jobs.py` lock keys plus `jobs/locks.py` rank ordering |
 | only confirmed-SFW assets reach the vision provider | `services/analysis.py`, re-checked *after* the provider call so a decision that flipped mid-flight discards the result |
 | EXIF is verified, and other fields preserved | `services/exif_checkpoint.py` |
 | uploads carry the exact verified bytes | `services/uploads.py` preflight, re-proved immediately before the uploader runs |
 | an uncertain upload is not a failure | `services/upload_batches.py`, `services/upload_verification.py` |
 | the archive source outlives its copy until verified | `services/archive_transfer.py` |
 | decoding is bounded | `imaging.py` |
 | the trust boundary and CSRF | `api/security.py` |
 ## Concurrency
 Locks are taken broad to narrow — `library → stage/job → album/folder → asset` — and
 never the other way, which is what makes deadlock structural rather than lucky.
 Ranks live in `jobs/locks.py`.
 Exactly-once execution is not achievable across SQLite, a filesystem, subprocesses,
 and a remote server. The design promises **at-least-once with idempotent recovery**:
 every handler may run twice, and running twice must not produce two side effects.
 That is why the rename journal records intent before moving, why EXIF writes merge
 and verify, and why upload retries consult both local history and Immich.
 ## History
 This application was extracted from two command-line tools rather than written from
 nothing. Their sources are frozen in `legacy_cli_archive/` with the ledger mapping
 each donated behaviour to the service that now owns it, the characterization tests
 that pinned it, and every intentional difference. Production code must not import
 them; they are provenance and rollback evidence.
--- a/docs/errors.md
+++ b/docs/errors.md
@@ -1,95 +0,0 @@
 # Errors and refusals
 [← Documentation index](index.md)
 Every error the API returns carries a code:
 ```json
 {"error": {"code": "lock_held", "message": "a library_write job is already running"}}
 ```
 Most of them are **refusals, not faults**. This application would rather stop and
 explain than guess about somebody's photographs, so a code below usually means it
 protected something. Each row says what caused it and what to do.
 ## Access and the trust boundary
 | code | cause | what to do |
 |---|---|---|
 | `unauthenticated` | no application session | reload the page; the browser bootstraps one |
 | `access_denied` | wrong or missing access secret | check `PHOTO_PIPELINE_ACCESS_SECRET`. Attempts are logged with the caller's address only |
 | `too_many_attempts` | more than five failed secret attempts in a minute | wait. This is the rate limit, not a lockout |
 | `csrf_failed` | a mutation without the session's token | reload; a stale tab has an old token |
 | `host_not_allowed` | the `Host` header is not a configured name | add the real hostname to `PHOTO_PIPELINE_ALLOWED_HOSTS` |
 | `origin_not_allowed` | the request came from another origin | not something a browser tab of this app produces |
 | `cross_site_blocked` | another site triggered the request | expected — this is the protection working |
 | `payload_too_large` | the body exceeds `PHOTO_PIPELINE_MAX_REQUEST_BYTES` | send less; every endpoint takes small commands |
 | `path_not_allowed` | a path resolved outside the library roots | usually a symlink. Nothing outside the roots is reachable, by design |
 ## The safety gate
 | code | cause | what to do |
 |---|---|---|
 | `dry_run_not_approved` | mutation is gated until a dry run is approved | run `dry-run`, read it, then `approve-dry-run` |
 | `approval_scope_mismatch` | the approval covers different library roots | approve a report for the roots actually configured |
 | `approval_unreadable` | the approval record cannot be read | re-approve; do not edit it by hand |
 ## Concurrency and staleness
 | code | cause | what to do |
 |---|---|---|
 | `lock_held` | a mutating job already holds the lane | wait for it. One at a time is what makes a crash recoverable |
 | `version_conflict` | you acted on a version that changed underneath you | the view re-renders with the server's truth; decide again |
 | `invalid_transition` | a state change that the machine does not allow | usually a stale tab; reload |
 | `job_error` | the job service refused the request | the message says why |
 | `rename_recovery_required` | an interrupted rename is unresolved | resolve it in [Renames](stages/renames.md). Unrelated mutations stay blocked on purpose |
 ## Stage refusals
 | code | cause | what to do |
 |---|---|---|
 | `nothing_to_score` | no photo is eligible for safety scoring | the queue is already decided |
 | `nothing_eligible` | no photo is eligible for analysis | resolve safety decisions first |
 | `nothing_to_plan` | no approved album name to build a plan from | approve a proposal first |
 | `invalid_decision` | the decision is not one this cluster accepts | reload the cluster |
 | `invalid_proposal` | the name is empty, reserved, or has forbidden characters | fix the name; the rules are in [Album proposals](stages/albums.md) |
 | `unknown_album` | the album is not a folder the library knows | rescan |
 | `cannot_apply` | the plan is invalid, stale, or another plan is unresolved | read the blockers in the preview |
 | `cannot_rollback` | the operation is complete or its preconditions no longer hold | rollback is recovery, not undo |
 ## Upload
 | code | cause | what to do |
 |---|---|---|
 | `stale_preflight` | bytes changed between approval and running | re-run preflight; this is the check that stops the wrong bytes being uploaded |
 | `not_runnable` | the batch is in a state that must not be re-run | an uncertain batch is verified, never retried |
 | `requires_verification` | the outcome is unknown; the server may hold the files | verify against Immich, then resolve |
 | `changed_after_upload` | the file changed after a successful upload | uploading again may create or upgrade an asset |
 ## Operations
 | code | cause | what to do |
 |---|---|---|
 | `backup_failed` | the snapshot could not be taken or verified | check free space and the message |
 | `invalid_retention` | a `--keep` value that is not a positive count | the newest backup is never pruned |
 | `not_found` | no such id | usually a stale link |
 ## Generic
 | code | cause |
 |---|---|
 | `invalid_request` | the request body failed validation. Field names only — never the values, which end up in logs and screenshots |
 | `http_error` | a plain HTTP-level refusal, with its status |
 | `internal_error` | an unhandled error. The code is all you get; the traceback is in the server log, because it can carry paths and credentials |
 ## Diagnostics warnings
 Not errors — reported by `diagnostics` and worth acting on. They are listed with
 their meanings in [Diagnostics](stages/diagnostics.md): `disk_low`, `disk_critical`,
 `cache_over_quota`, `wal_growth`, `tool_version_drift`, `legacy_process_active`, and
 `no_roots`.
 ## Startup refusals
 Exit codes 2 to 5 are covered by the installation manual under
 [when it refuses to start](installation.md#when-it-refuses-to-start).
--- a/docs/first-pass.md
+++ b/docs/first-pass.md
@@ -1,66 +0,0 @@
 # A guided first pass
 [← Documentation index](index.md)
 One library, from nothing to a verified upload. Each stage links to its own page; this
 is the order, and — more importantly — where the points of no return are.
 ![The workflow home, with every stage and its counts](images/workflow.png)
 The workflow page is the home view and the honest summary: each stage shows its state,
 its counts, why it is blocked if it is, and the one action that moves it forward.
 | # | stage | reversible afterwards? |
 |---|---|---|
 | 0 | [Inventory](stages/inventory.md) | nothing was changed |
 | 1 | [Duplicate review](stages/duplicates.md) | yes — decisions can be changed, no file is deleted |
 | 2 | [Safety review](stages/safety.md) | the decision, yes; the EXIF keyword is a file write |
 | 3 | [Analysis](stages/analysis.md) | the result, yes; the caption and keywords are a file write |
 | 4 | [Album proposals](stages/albums.md) | yes — approving renames nothing |
 | 5 | [Renames](stages/renames.md) | **your folders move.** Recoverable, journaled, but real |
 | 6 | [Upload](stages/uploads.md) | **assets exist on the Immich server.** Not undone from here |
 | 7 | [Archive](stages/archive.md) | **originals leave active storage.** Restorable while the medium is reachable |
 | — | [Diagnostics](stages/diagnostics.md) | read-only, any time |
 ## Before the first run
 Take a backup of the photo library itself. This application is careful — it previews,
 journals, and verifies — but it is the first time you are pointing it at your
 photographs, and a backup is cheaper than confidence.
 If the library is irreplaceable, turn on `PHOTO_PIPELINE_REQUIRE_DRY_RUN_APPROVAL`
 before anything else. Every mutating request is then refused until you have produced
 a read-only reconciliation report and approved it by name.
 ## The pass
 1. **Scan.** Inventory → *Rescan*. Reads only. Check the count, and check that
   nothing under `_IGNORE/` appears.
 2. **Resolve duplicates.** Exact byte matches can be accepted as recommended; anything
   fuzzy gets looked at. Resolving first is what stops you paying to analyse the same
   photo twice.
 3. **Decide safety.** Every canonical photo becomes `sfw` or `nsfw`. Nothing reaches
   the vision provider until it is confirmed SFW — this is the gate the whole design
   exists around.
 4. **Analyse.** Only confirmed-SFW photos. Each result is written to the database and
   projected into EXIF, then read back and verified.
 5. **Propose album names.** Evidence from what was analysed. Edit anything you disagree
   with. Approving changes no file.
 6. **Build the rename plan, read it, apply it.** The preview shows every old → new
   path. This is where folders move.
 7. **Rescan.** Paths are reconciled; identities are unchanged.
 8. **Upload.** Preflight lists every blocker. The command is previewed without the API
   key. One album at a time.
 9. **Verify.** An uncertain upload is not a failure and not a success — ask the server.
 10. **Archive** (optional). Copy, verify, and only then reclaim the space.
 Stop anywhere. Every stage is resumable, and closing the browser cancels nothing.
 ## Two rules worth internalising
 **The application refuses more than it warns.** A refusal is not a fault; it is the
 design working. [Errors and refusals](errors.md) explains each one.
 **One long job at a time.** Browsing stays available while a job runs, but a second
 mutating job is refused — that is what makes a crash recoverable rather than
 ambiguous.
--- a/docs/images/albums.png
+++ b/docs/images/albums.png
--- a/docs/images/analysis.png
+++ b/docs/images/analysis.png
--- a/docs/images/archive.png
+++ b/docs/images/archive.png
--- a/docs/images/duplicates.png
+++ b/docs/images/duplicates.png
--- a/docs/images/inventory.png
+++ b/docs/images/inventory.png
--- a/docs/images/renames.png
+++ b/docs/images/renames.png
--- a/docs/images/safety.png
+++ b/docs/images/safety.png
--- a/docs/images/statistics.png
+++ b/docs/images/statistics.png
--- a/docs/images/uploads.png
+++ b/docs/images/uploads.png
--- a/docs/images/workflow.png
+++ b/docs/images/workflow.png
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,68 +0,0 @@
 # Photo Pipeline documentation
 One local application that takes a photo library from discovery to a verified Immich
 upload: duplicate detection, safety review, content analysis, album naming, guarded
 renaming, upload, and archive — one visible, resume-safe workflow.
 These pages are readable three ways, and they are the same files each time: in the
 repository under `docs/`, on Gitea, and inside the running application under
 **Docs**. There is no separate copy to fall out of date.
 ## Read in this order
 1. [Overview](overview.md) — what the application does, the stages it moves a photo
   through, and the rules it will not break.
 2. [Installation and operations](installation.md) — host and container installation,
   every setting, the first-run checklist, upgrades, backup and restore, and what
   each refusal at startup means.
 3. [A guided first pass](first-pass.md) — one library from scan to verified upload,
   with the point of no return named in each stage.
 4. [Architecture](architecture.md) — the context and runtime diagrams, what each
   module owns, the three journals a restart reads, and where every invariant is
   enforced.
 ## The stages, one page each
 Every page answers the same four questions: what the stage is for, what you decide,
 what it changes on disk or on the server, and what it refuses.
 1. [Inventory and discovery](stages/inventory.md)
 2. [Duplicate review](stages/duplicates.md)
 3. [Safety review](stages/safety.md)
 4. [Analysis](stages/analysis.md)
 5. [Album proposals](stages/albums.md)
 6. [Renames](stages/renames.md)
 7. [Upload](stages/uploads.md)
 8. [Archive](stages/archive.md)
 9. [Diagnostics and library statistics](stages/diagnostics.md)
 ## When something goes wrong
 - [Errors and refusals](errors.md) — every error code, what caused it, what to do.
 - [Recovery](recovery.md) — what the application resolves by itself, and what needs
  you.
 ## Keeping these pages true
 Documentation that disagrees with the application is worse than none, because it is
 trusted. So one command compares them:
 ```bash
 python -m photo_pipeline docs-gate
 ```
 It runs every `phase_i` check — dead links and anchors, pages nobody links to, images
 nobody shows, settings, commands, exit codes, error codes, and states that no longer
 exist in the code, the pages rendering in a real browser without a console or policy
 error, and the screenshots still showing what the application shows. It retains its
 evidence and **accepts no skipped check**: a check that did not run is a page nobody
 compared. CI runs it on every pull request.
 The repository's own build, test, and release notes live in the
 [README](../README.md).
 ## Conventions
 A page tells you what a stage **changes on disk or on the server** before it tells
 you how to run it. Refusals are documented as intentional: this application would
 rather stop and explain than guess about somebody's photographs.
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -1,336 +0,0 @@
 # Installation and operations
 [← Documentation index](index.md)
 From nothing to a running instance pointed at your photo library, and everything you
 need afterwards: upgrading, backing up, restoring, and understanding a refusal.
 Two ways to install. **Container** is the deployment this project builds and ships;
 **host** is what you want for development or a single machine you already manage.
 Both run the same two processes against the same database.
 > Read [what it will not do](overview.md#what-it-will-not-do) first. Several of the
 > steps below only make sense once you know which rules the application is keeping.
 ## Before you start
 | you need | version | why |
 |---|---|---|
 | Python | 3.12 or newer | the application |
 | `exiftool` | 13.x (the image pins `13.25+dfsg-1`) | every EXIF read and write |
 | `immich-go` | 0.32.0 (pinned in the image) | the upload stage only |
 | Docker + the compose plugin | any current | the container installation only |
 | a vision provider key | — | the analysis stage only |
 You also need a photo library you can afford to be wrong about. Take a backup of it
 before pointing anything at it for the first time, and consider running with
 [`PHOTO_PIPELINE_REQUIRE_DRY_RUN_APPROVAL`](#the-settings) on.
 ## Host installation
 ```bash
 python3.12 -m venv .venv
 .venv/bin/pip install -e ".[vision]"     # drop [vision] for a review-only install
 ```
 Configure it. Every setting is an environment variable; a `.env` file in the working
 directory is read at startup:
 ```bash
 cp .env.example .env && $EDITOR .env
 ```
 `.env.example` lists every variable with its default and no values at all. For a
 loopback installation you need exactly one:
 ```bash
 PHOTO_PIPELINE_LIBRARY_ROOTS=/home/you/Pictures
 ```
 Then migrate and start the two processes:
 ```bash
 .venv/bin/python -m photo_pipeline migrate    # create or upgrade the database
 .venv/bin/python -m photo_pipeline serve      # API and browser app on 127.0.0.1:8000
 .venv/bin/python -m photo_pipeline worker     # second terminal
 ```
 **Both processes are required.** `serve` enqueues work and renders the application;
 nothing is scanned, scored, analysed, renamed, uploaded, or archived without a
 worker. Open <http://127.0.0.1:8000/app/> and confirm the workflow page loads.
 ### The configuration file
 `.env`, or any path named by `PHOTO_PIPELINE_ENV_FILE`. It is parsed, never executed:
 `KEY=value` lines, `#` comments, optional quotes, no interpolation and no `export`. A
 configuration file that can run code is a configuration file that can be a
 vulnerability.
 **Anything already exported in the shell wins.** The file is your standing
 configuration; the environment is the override for one run.
 The archived CLI's names still work, so an existing `photo_analyzer.env` can be used
 as it is:
 | in the file | applied as |
 |---|---|
 | `LLM_API_KEY` / `GEMINI_API_KEY` | `OPENAI_API_KEY` |
 | `LLM_BASE_URL` | `OPENAI_BASE_URL` |
 | `LIBRARY` | `PHOTO_PIPELINE_LIBRARY_ROOTS` |
 `.env` and `*.env` are gitignored and refused by the repository's safety checks. The
 file holds a real key; it must never be committed.
 ## Container installation
 ```bash
 cp .env.example .env && $EDITOR .env
 docker compose up -d --build
 ```
 The composition is one `serve` container, one `worker` container, a one-shot
 `migrate` that both wait for, one bind-mounted library, and one named data volume.
 Three variables it cannot start without:
 | variable | is |
 |---|---|
 | `PHOTO_PIPELINE_LIBRARY_HOST_PATH` | the library on this host |
 | `PHOTO_PIPELINE_LIBRARY_ROOTS` | where that library is mounted **inside** the container |
 | `PHOTO_PIPELINE_ACCESS_SECRET` | required, because publishing a port means the app is reachable from outside the container |
 Set `PHOTO_PIPELINE_UID` and `PHOTO_PIPELINE_GID` to the owner of the library: what
 the containers rename and rewrite keeps that ownership.
 ### The data volume
 The `data` volume holds the database, its write-ahead log, the thumbnail cache, the
 operation journals, and the backups. **It must stay on a local filesystem.** SQLite
 in WAL mode needs real local locking, so NFS, SMB, and network volume drivers do not
 slow it down — they corrupt it. The library bind mount has no such restriction.
 ### Ports and reaching it
 The API port is published to `127.0.0.1` unless `PHOTO_PIPELINE_PUBLISH_ADDRESS` says
 otherwise. Being reachable *was* the authentication in earlier versions: whoever could
 open the port owned the library. So the moment the application answers to anything but
 loopback — a hostname, a proxy, `0.0.0.0` — the access secret becomes mandatory and
 `serve` refuses to start without it rather than publishing your photographs.
 Behind a reverse proxy:
 ```bash
 PHOTO_PIPELINE_ALLOWED_HOSTS=photos.example.com
 PHOTO_PIPELINE_ACCESS_SECRET=…                  # python -c 'import secrets; print(secrets.token_urlsafe(32))'
 PHOTO_PIPELINE_TRUSTED_PROXIES=10.0.0.2         # only the proxy's own address
 ```
 `X-Forwarded-Proto` and `X-Forwarded-Host` are believed only from a trusted-proxy
 address, so a client cannot declare its own origin. The browser asks for the secret
 once per tab. Wrong secrets are rate-limited and logged with the caller's address
 only. The health endpoints stay open so an orchestrator can restart the container;
 nothing else is.
 ### Deployment
 The stack is managed from git by Portainer, which redeploys on a webhook after CI
 publishes an image built from `main`. Runtime secrets live in the Portainer stack's
 environment rather than in the repository, so rotation happens in one place and
 reading the repository discloses nothing.
 ## The settings
 Every variable, its default, and whether it is a secret. `.env.example` is the same
 list in copyable form.
 ### Library and data
 | variable | default | meaning |
 |---|---|---|
 | `PHOTO_PIPELINE_LIBRARY_ROOTS` | none | the library boundary, `os.pathsep`-separated. No path outside these roots is ever read or written |
 | `PHOTO_PIPELINE_DATA_DIR` | `data` | database, WAL, thumbnail cache, journals, backups. Never inside the library |
 | `PHOTO_PIPELINE_DB_PATH` | `<data dir>/photo_pipeline.db` | the database file, if it must live elsewhere |
 | `PHOTO_PIPELINE_ENV_FILE` | `.env` | where to read the configuration file from |
 ### Serving and the trust boundary
 | variable | default | meaning |
 |---|---|---|
 | `PHOTO_PIPELINE_HOST` | `127.0.0.1` | bind address |
 | `PHOTO_PIPELINE_PORT` | `8000` | port |
 | `PHOTO_PIPELINE_ALLOWED_HOSTS` | none | comma-separated names the app answers to besides loopback. Naming one makes the access secret mandatory |
 | `PHOTO_PIPELINE_ACCESS_SECRET` | none | **secret.** Traded for the session cookie at `GET /api/v1/session` |
 | `PHOTO_PIPELINE_TRUSTED_PROXIES` | none | comma-separated peer addresses whose forwarded headers may be believed |
 | `PHOTO_PIPELINE_MAX_REQUEST_BYTES` | `1048576` | largest request body accepted |
 ### Logging
 | variable | default | meaning |
 |---|---|---|
 | `PHOTO_PIPELINE_LOG_LEVEL` | `INFO` | standard Python levels |
 | `PHOTO_PIPELINE_LOG_FORMAT` | `json` | `json` or `text` |
 ### Limits
 | variable | default | meaning |
 |---|---|---|
 | `PHOTO_PIPELINE_THUMBNAIL_CACHE_QUOTA_BYTES` | `500000000` | cache quota; over it is a diagnostics warning |
 | `PHOTO_PIPELINE_THUMBNAIL_MAX_PIXELS` | `100000000` | refuse to decode anything larger. This is the decompression-bomb guard |
 | `PHOTO_PIPELINE_ARCHIVE_FREE_SPACE_RESERVE_BYTES` | `1000000000` | free space an archive destination must keep beyond the transfer itself |
 ### The safety gate
 | variable | default | meaning |
 |---|---|---|
 | `PHOTO_PIPELINE_REQUIRE_DRY_RUN_APPROVAL` | `false` | refuse every mutating request until a read-only dry run of this library has been produced and approved |
 ### External services
 | variable | default | meaning |
 |---|---|---|
 | `PHOTO_PIPELINE_VISION_API_KEY` | none | **secret.** Without it the analysis stage cannot run |
 | `PHOTO_PIPELINE_IMMICH_SERVER_URL` | none | the Immich server |
 | `PHOTO_PIPELINE_IMMICH_API_KEY` | none | **secret.** |
 | `PHOTO_PIPELINE_IMMICH_GO_BINARY` | `immich-go` | the uploader, found on `PATH` |
 ### Composition only
 Read by `docker-compose.yml`, not by the application:
 `PHOTO_PIPELINE_IMAGE`, `PHOTO_PIPELINE_LIBRARY_HOST_PATH`,
 `PHOTO_PIPELINE_PUBLISH_ADDRESS`, `PHOTO_PIPELINE_UID`, `PHOTO_PIPELINE_GID`.
 A secret is never written to a log, never returned by the API, never stored in the
 database, and never recorded in a backup manifest — a manifest says `configured`, not
 the value. Do not put a real key in an example, a ticket, or a screenshot.
 ## First run checklist
 Not "it started" — verified.
 1. **The database is at the current revision.**
   `python -m photo_pipeline migrate` exits 0.
 2. **The application answers.**
   `curl -s localhost:8000/api/v1/health/ready` returns 200.
 3. **The library was found.** Open the app, run a scan from the Inventory view, and
   check the count against what you expect. Anything under `_IGNORE/` must be missing
   from it — that is the exclusion working, not a bug.
 4. **The worker is claiming.** The scan job reaches `succeeded`. If it stays
   `queued`, no worker is running.
 5. **Diagnostics are clean.**
   `python -m photo_pipeline diagnostics` reports free space and an empty `warnings`.
 6. **Nothing was modified.** The scan is read-only; your files' timestamps are
   unchanged.
 Only then point it at the whole library.
 ## Operations
 Every operation is the same CLI, on a host or in the composition:
 ```bash
 python -m photo_pipeline diagnostics
 docker compose run --rm --no-deps api diagnostics
 ```
 `--no-deps` keeps a one-off command from starting a second stack; `api` is only the
 service it borrows the image and mounts from.
 ### Upgrading
 1. `python -m photo_pipeline backup --reason before-upgrade`
 2. Pull the new version (or `docker compose pull && docker compose up -d`).
 3. Migrations run by themselves at startup, and a **pending schema change is
   snapshotted first**. If the upgrade fails, the previous database and its
   `pre-migration` backup are both intact, and the error log names the backup
   directory.
 An up-to-date database is not backed up again on every start.
 ### Backing up
 ```bash
 python -m photo_pipeline backup --reason weekly --keep 7
 python -m photo_pipeline verify-backup data/backups/<name>
 ```
 Backups go through SQLite's online backup API, never a file copy: with WAL enabled
 the `.db` file alone is missing every committed page still in the write-ahead log.
 Each backup is a directory holding the snapshot and a `manifest.json` — schema
 revision, SHA-256, row counts, the archive media the library depends on, and which
 settings were configured.
 `verify-backup` runs `PRAGMA integrity_check` **and** `PRAGMA foreign_key_check`,
 compares the snapshot's SHA-256 against the manifest, and re-counts every table it
 recorded. Bit rot, a truncated copy, and a "repaired" snapshot all fail it.
 `--keep N` prunes the oldest and never the newest. The same is available at
 `GET /api/v1/diagnostics`, `GET|POST /api/v1/backups`,
 `GET /api/v1/backups/{name}/verify`, and `POST /api/v1/backups/prune`.
 ### Restoring
 Restore is deliberately **not** an API call. It replaces the state of an
 installation, so it belongs to a stopped one and a person at a terminal.
 1. Stop `serve` and `worker`.
 2. `python -m photo_pipeline verify-backup data/backups/<name>` — never restore an
   unverified snapshot, and `restore` will refuse one anyway.
 3. `python -m photo_pipeline restore data/backups/<name> --into /path/to/fresh-data`.
   A target that already holds a database is refused; recovering in place means
   moving the old data directory aside first.
 4. Point `PHOTO_PIPELINE_DATA_DIR` at the restored directory and run `migrate`.
 5. Run an inventory scan, so paths are reconciled against the real library.
 6. Mount every archive location the manifest names before archiving again. The
   database records where archived originals are; it does not contain them.
 Practise this against a copy before you need it.
 ### Watching it
 `diagnostics` reports the database, write-ahead log, thumbnail cache, uploader
 reports, backups, and logs separately, with free space and warnings for low disk
 (`disk_low`, `disk_critical`), a cache over its quota, a write-ahead log outgrowing
 its database, and a legacy CLI writing the library.
 Logs go to stdout in JSON by default — `docker compose logs -f worker`, or your
 service manager's journal on a host. Uploader output is kept per attempt under the
 data directory with the API key scrubbed line by line.
 ## When it refuses to start
 Every refusal below is deliberate. The application would rather stop and explain than
 guess about somebody's photographs.
 | exit code | meaning | what to do |
 |---|---|---|
 | `1` | the operation failed and said why — an unverifiable backup, an occupied restore target, an unknown benchmark profile | read the message; nothing was changed |
 | `2` | **the library lock is held.** Another `serve` or `worker` owns this data directory | stop the other process. The message names the holder; a lock whose process is gone is taken over automatically |
 | `3` | **a legacy CLI looks active.** The frozen command-line tools are writing this library | stop them. `--allow-legacy` overrides and you own the outcome |
 | `4` | **configuration refused.** The application is reachable beyond loopback and no access secret is set | set `PHOTO_PIPELINE_ACCESS_SECRET`, or bind to loopback only |
 | `5` | **a library root is not mounted** (containers only) | fix the bind mount. Refusing is what stops the container writing into its own throwaway layer instead of your library |
 Other things that look like faults and are not:
 - **`403 host_not_allowed`** — the `Host` header is not a name in
  `PHOTO_PIPELINE_ALLOWED_HOSTS`. Add the real hostname; do not add `*`.
 - **`409 lock_held`** — a mutating job is already running. One at a time is what
  makes a crash recoverable.
 - **`409 rename_recovery_required`** — an interrupted rename is unresolved. Resolve
  it in the Renames view; unrelated mutations stay blocked until then, on purpose.
 - **A job stuck in `queued`** — no worker is running.
 - **An empty scan** — check `PHOTO_PIPELINE_LIBRARY_ROOTS`, and in a container check
  that the path is the *container-side* mount, not the host path.
 ## What an installer must not work around
 - **One writer.** Do not run two workers, and do not run the frozen CLI beside the
  application. Each is safe alone and destructive together — the lock is not
  bureaucracy.
 - **`_IGNORE/` is never read.** Do not "fix" the exclusion.
 - **EXIF is verified before upload.** Do not skip the checkpoint to make a stage
  finish; an unverified projection is exactly the case where the wrong bytes reach
  Immich.
 - **The data directory is not the library.** Keep them apart, and keep the data
  directory on a local filesystem.
 - **Secrets stay in the environment.** Not in the database, not in a log, not in a
  commit.
--- a/docs/overview.md
+++ b/docs/overview.md
@@ -1,77 +0,0 @@
 # Overview
 [← Documentation index](index.md)
 Photo Pipeline sorts a photo library. It finds duplicates before anything expensive
 happens to them, asks a human which pictures may leave the machine, describes the
 ones that may, proposes album names from what it found, renames folders under a
 crash-safe journal, uploads through `immich-go`, and can archive a finished album off
 active storage without ever forgetting it existed.
 It runs locally. It talks to exactly three things outside itself: a vision provider,
 an Immich server, and `exiftool` — and it will tell you before it uses any of them.
 ## The workflow
 Each stage is a gate, not a tab. A later stage can always be looked at; its actions
 stay disabled until what they depend on is true.
 ```mermaid
 flowchart TD
  I["0 · Inventory<br/>discover, hash, cluster duplicates"] --> S["1 · Safety<br/>score and human decision"]
  S -->|sfw| A["2 · Analysis<br/>vision provider, EXIF checkpoint"]
  S -->|nsfw| U
  A --> B["3 · Albums<br/>proposal, then guarded rename"]
  B --> U["4 · Upload<br/>immich-go, verified bytes"]
  U --> R["5 · Archive<br/>copy, verify, then reclaim space"]
 ```
 | Stage | What it decides | What it changes |
 |---|---|---|
 | Inventory | which file is the canonical copy of a picture | nothing — it only reads |
 | Safety | whether a photo may be sent to a cloud provider | one `sfw`/`nsfw` EXIF keyword |
 | Analysis | what a photo shows | a managed caption segment and additive keywords |
 | Albums | what a folder should be called | folder names, through a journaled rename |
 | Upload | which exact bytes reach Immich | nothing locally; assets appear in Immich |
 | Archive | which album leaves active storage | files move to the archive, after verification |
 ## What it will not do
 These are enforced in code, not by convention, and each one is why some action you
 expected is sometimes refused.
 - **Nothing under `_IGNORE/` is ever read.** Not scanned, not counted, not
  thumbnailed, not sent anywhere.
 - **A path is not an identity.** Every picture has a stable id, so moving or renaming
  it loses no history.
 - **Only a confirmed-SFW photo reaches the vision provider.** A photo marked NSFW is
  still uploadable to Immich; it simply never leaves for analysis.
 - **Metadata is verified, not hoped for.** Every stage that writes EXIF reads it back
  and proves that what it did not own is unchanged.
 - **One writer at a time.** A library lock, held by one process, is what makes a
  crash recoverable instead of ambiguous.
 - **Nothing irreversible happens without a preview and an explicit approval** that
  names the exact count.
 ## Where things live
 | | |
 |---|---|
 | the photo library | wherever you point `PHOTO_PIPELINE_LIBRARY_ROOTS`; mounted read-write |
 | the database, cache, logs, backups | the data directory, never inside the library |
 | secrets | the environment, never the database and never a log line |
 | these documents | `docs/` in the repository, served at `/docs` by the application |
 ## Running it
 The short version, for a host installation:
 ```bash
 python -m photo_pipeline migrate
 python -m photo_pipeline serve      # the API and this browser application
 python -m photo_pipeline worker     # the process that does the long work
 ```
 The full procedure, the container path, and every setting are in the
 [installation manual](installation.md); if you would rather start using it, take
 [the guided first pass](first-pass.md).
--- a/docs/recovery.md
+++ b/docs/recovery.md
@@ -1,62 +0,0 @@
 # Recovery
 [← Documentation index](index.md)
 What the application resolves by itself, and what needs you. The dividing line is
 simple: it resumes when the evidence is unambiguous, and it stops and asks when it is
 not. It never guesses about your files.
 ## An interrupted rename
 A rename records its intent **before** touching the disk, so after a crash the
 journal plus the actual filesystem give a verdict per operation:
 | verdict | means | what happens |
 |---|---|---|
 | resumable | the move provably did not happen | reset to planned and run again |
 | rollback-safe | the move happened; the remaining steps can be completed or undone | drive it forward, or roll it back |
 | manual | the evidence is contradictory | left alone, and it keeps blocking |
 Open [Renames](stages/renames.md); the recovery panel lists every unresolved
 operation and offers a resolve action only where one is safe. Until then, unrelated
 mutations are refused with `rename_recovery_required` — building new work on a
 half-applied move is how a library becomes unexplainable.
 ## An uncertain upload
 `unknown_requires_verification` means the uploader died after Immich may have
 accepted the files. It is **not** retryable. Verification asks the server whether it
 holds the recorded SHA-1 and answers present, absent, or inconclusive. An
 inconclusive answer is resolved by you, with your evidence and name recorded in the
 batch's history.
 ## A failed migration
 A pending schema change is snapshotted before it is applied. If the upgrade fails,
 the previous database and its `pre-migration` backup are both intact and the error
 log names the backup directory. Stop everything and run the
 [restore drill](installation.md#restoring).
 ## A restored backup
 After restoring, run a scan. Paths are reconciled against the real library and
 identities are preserved where hashes match. Anything that does not match becomes a
 visible `stale` or `divergent` state instead of being quietly accepted.
 Mount every archive medium the manifest names before archiving again: the database
 records where archived originals live, it does not contain them.
 ## A job that will not start
 Check, in this order: is a worker running; is another mutating job holding the lane
 (`lock_held`); is an interrupted rename blocking everything
 (`rename_recovery_required`); is the library lock held by a process that is still
 alive (exit code `2` names the holder).
 ## What is never automatic
 No file is deleted, no folder is renamed, no upload is retried, and no archive source
 is removed without either an explicit confirmation from you or a verification the
 application performed itself. If you are reading this page because something happened
 that you did not approve, that is a bug worth reporting — with the diagnostics output
 and the relevant journal, both of which are safe to share: they carry no secrets.
--- a/docs/stages/albums.md
+++ b/docs/stages/albums.md
@@ -1,47 +0,0 @@
 # Album proposals
 [← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
 ![Reviewing an album proposal](../images/albums.png)
 **What it is for.** Turning a folder of analysed photographs into a name a person
 would have chosen, before any folder is touched.
 **What you decide.** The final name. The proposal is a starting point with its
 reasoning attached; you edit it, accept it, or ignore it.
 **What it changes.** A row per album: proposed name, rationale, confidence, and your
 final name, with a version. **Approving renames nothing.** Not one file moves at this
 stage — approval only marks a name as agreed, and the [rename stage](renames.md) is
 where it becomes a plan you have to confirm separately.
 **What it refuses.** A name containing `/ \ : * ? " < > |`, a reserved device name, or
 one that collides with an existing folder is rejected while you type and again on the
 server. Approval is refused when the evidence changed since the proposal was
 generated — the proposal is stale, and regenerating is the honest fix. Editing with a
 stale version returns a conflict and shows you the server's truth rather than
 overwriting it.
 ## Reading the view
 The left pane lists albums with their state: `none`, `proposed`, `edited`,
 `approved`, `error`, or `stale`. The right pane shows the evidence the name was built
 from — date range, dominant tags, locations, counts — then the suggested name, the
 rationale, the confidence, and an editable final name.
 The default naming shape is predictable and sortable:
 ```text
 YYYY-MM — Place — Event
 YYYY — Event
 Place — Event
 ```
 ## While a rename is unresolved
 Generating and approving proposals is blocked while an interrupted rename is
 outstanding, with `409 rename_recovery_required`. Resolve the rename first: building
 new names on top of a half-applied move is how a library becomes hard to reason
 about.
 Next: [renames](renames.md).
--- a/docs/stages/analysis.md
+++ b/docs/stages/analysis.md
@@ -1,39 +0,0 @@
 # Analysis
 [← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
 ![The analysis view](../images/analysis.png)
 **What it is for.** Describing what a photograph shows, so albums can be named from
 evidence and the library can be searched by content.
 **What you decide.** When to run it, and over what scope. The descriptions themselves
 come from the configured vision provider.
 **What it changes.** For each eligible photo: a stored result — description, tags,
 approximate year, location hint, model and prompt version — and then an EXIF
 checkpoint that merges a **managed caption segment** and additive keywords into the
 file, reads them back, and verifies that nothing else moved. The file's SHA-256 is
 refreshed after the write.
 **What it refuses.** Anything not confirmed SFW. Anything not canonical. A malformed
 provider response is quarantined rather than stored. Keywords are only ever added,
 never removed, because EXIF keywords carry no ownership and deleting a generated one
 could delete yours.
 ## Running it
 The view shows eligible, analysed, pending, and error counts, and the job's live
 progress. Starting a second mutating job while it runs is refused — that is the
 one-writer rule, not a queue.
 Cancelling drains safely: completed items stay completed, and resuming continues
 rather than restarting. A photo may be sent to the provider twice if a crash happens
 mid-item, but its stored result and its EXIF are written once.
 ## Costs
 Each analysed photo is a provider call. Resolving duplicates first is what keeps that
 number honest, and the counts here are the ones to check before starting a large run.
 Next: [album proposals](albums.md).
--- a/docs/stages/archive.md
+++ b/docs/stages/archive.md
@@ -1,43 +0,0 @@
 # Archive
 [← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
 ![Archive locations and plans](../images/archive.png)
 **What it is for.** Moving a finished album out of active storage onto another disk,
 while keeping everything the library knows about it.
 **What you decide.** Which album, which destination, and whether to accept the
 reclaimed space in exchange for needing that medium mounted to see the originals
 again.
 **What it changes.** Files are copied to the archive location, verified there, and
 only then removed from the library. The asset keeps its id, its hashes, its
 decisions, its analysis, its upload history, and a durable preview thumbnail;
 `current_path` becomes null and availability becomes `archived_online` or
 `archived_offline`.
 **What it refuses.** Preflight blocks on: an unverified upload, a checksum that no
 longer matches the uploaded bytes, an unmounted or unwritable destination,
 insufficient free space plus the configured reserve, a destination that already
 holds unexpected paths, a missing durable thumbnail, and any conflicting job. The
 source is **never** removed before the archived copy is verified — not because Immich
 reported success, which is an ingest, not a backup.
 ## Offline is not missing
 An archived photo whose medium is unplugged is `archived_offline`. It still appears
 in search, still participates in duplicate detection through its retained hashes and
 thumbnail, and is never reported as lost. If a full-resolution comparison is needed,
 the application asks you to mount the named medium rather than guessing.
 ## Restore
 Restore is planned and journaled like everything else: the medium must be online, the
 bytes are copied back and verified into a collision-free destination, a new active
 path is registered, and a reconciliation scan follows. Existing safety, analysis,
 EXIF, and upload state stay valid when hashes match — and when they do not, the
 result is a visible `divergent` state rather than silent acceptance of a different
 file.
 Next: [diagnostics](diagnostics.md).
--- a/docs/stages/diagnostics.md
+++ b/docs/stages/diagnostics.md
@@ -1,49 +0,0 @@
 # Diagnostics and library statistics
 [← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
 ![Library statistics](../images/statistics.png)
 **What it is for.** Answering "is this installation healthy, and what is in this
 library?" — the first thing to look at when a stage behaves unexpectedly.
 **What you decide.** Nothing. Both are read-only.
 **What it changes.** Nothing.
 **What it refuses.** Nothing — both are reads, and both stay available while a job
 holds the library. That is deliberate: the moment you most need to know what the
 installation is doing is while it is busy.
 ## Statistics
 The Stats view summarises the library itself: how many photos are analysed, the
 common tags, the distribution across albums and years. It answers questions about
 your photographs.
 ## Diagnostics
 Diagnostics answers questions about the *installation*, and lives at
 `GET /api/v1/diagnostics` and on the command line:
 ```bash
 python -m photo_pipeline diagnostics
 ```
 It reports the database, write-ahead log, thumbnail cache, uploader reports, backups,
 and logs as separate sizes, plus free space, the tool versions it found against the
 ones the image pinned, and which locks are held and by whom.
 Its warnings are the ones worth acting on:
 | warning | means |
 |---|---|
 | `disk_low` / `disk_critical` | free space is running out; mutating stages stop before the reserve |
 | `cache_over_quota` | the thumbnail cache exceeds its configured quota |
 | `wal_growth` | the write-ahead log is outgrowing its database — usually a long-running reader |
 | `tool_version_drift` | the installed `exiftool` or `immich-go` is not the version the image pinned |
 | `legacy_process_active` | the frozen command-line tools are writing this library. Stop them |
 | `no_roots` | no library root is configured, so there is nothing to work on |
 An empty `warnings` list on a fresh installation is what the
 [first-run checklist](../installation.md#first-run-checklist) is looking for.
--- a/docs/stages/duplicates.md
+++ b/docs/stages/duplicates.md
@@ -1,36 +0,0 @@
 # Duplicate review
 [← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
 ![The duplicate cluster list](../images/duplicates.png)
 **What it is for.** Deciding which file is *the* copy of a picture, before anything
 expensive or irreversible happens to the others.
 **What you decide.** For each cluster: keep the recommended canonical, choose a
 different one, keep everything as variants, declare it not a duplicate, or defer.
 **What it changes.** Only the decision, recorded as an auditable event. **No file is
 ever deleted.** Non-canonical copies stay exactly where they are; they are simply
 excluded from analysis and upload.
 **What it refuses.** Exact byte and identical-pixel matches may be accepted on the
 recommendation. Anything fuzzy — a crop, a re-encode, a burst frame — requires an
 explicit confirmation, because a perceptual hash is evidence, not proof.
 ## Reading a cluster
 Each member shows its path, role, pHash distance, and size, with synchronised zoom
 across the previews. The recommendation is visible but never pre-applied for fuzzy
 matches. The confidence band tells you how much the machine is claiming.
 Rejecting a pair records a negative link, so a later rescan does not keep proposing
 the same wrong match.
 ## Why first
 Resolving duplicates before safety and analysis is what stops you reviewing and
 paying for the same photograph three times. It also means the album evidence is built
 from one copy of each picture rather than a skewed count.
 Next: [safety review](safety.md).
--- a/docs/stages/inventory.md
+++ b/docs/stages/inventory.md
@@ -1,39 +0,0 @@
 # Inventory and discovery
 [← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
 ![The inventory view](../images/inventory.png)
 **What it is for.** Finding every supported photo in the configured library roots and
 giving each one a permanent identity, so that everything afterwards can refer to a
 picture rather than a path.
 **What you decide.** Nothing. This stage is the only one with no judgement in it.
 **What it changes.** On disk, nothing at all — discovery reads. In the database it
 records each photo's path, size, timestamps, full-file SHA-256, normalised pixel hash,
 and perceptual hash, and it opens a path-history entry.
 **What it refuses.** Anything under an `_IGNORE/` directory is never traversed,
 counted, hashed, or previewed. Unsupported extensions and unreadable files are
 reported rather than skipped silently. Nothing outside the configured roots is
 reachable, including through a symlink.
 ## Reading the view
 Each row is one asset: its current path, availability, whether the file is present,
 and its size. The filter searches paths; the availability selector separates active
 photos from archived ones.
 A **rescan** after moving files around outside the application is the normal way to
 reconcile: a file that moved keeps its identity, because identity is the hash and the
 id, not the location.
 ## What good looks like
 The count matches what you expect, `_IGNORE/` contents are absent, and nothing shows
 as missing. A photo listed as missing means the file is no longer at its recorded
 path and no new path matched its hashes — that is a question for you, not something
 the scanner resolves by guessing.
 Next: [duplicate review](duplicates.md).
--- a/docs/stages/renames.md
+++ b/docs/stages/renames.md
@@ -1,46 +0,0 @@
 # Renames
 [← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
 ![The rename plan preview](../images/renames.png)
 **What it is for.** Applying approved album names to the actual folders — the first
 stage that changes your filesystem.
 **What you decide.** Whether to apply the plan, after reading it. The confirmation
 names the plan, its version, and its checksum, so what you approve is what runs.
 **What it changes.** Folders move. For each operation: the intent is journaled
 *before* the disk is touched, the move is made, `assets.current_path` is updated by
 id in one transaction, the old path is closed and a new one opened in path history,
 the result is verified, and only then is the operation complete.
 **What it refuses.** A plan is invalid — not merely warned about — when a source is
 missing or changed, two operations target the same destination, a destination already
 exists, a path would leave the library or enter `_IGNORE/`, or a source is a symlink.
 Case-only renames and cross-filesystem moves are allowed but flagged, because they
 take a different, staged route. A plan whose checksum no longer matches is refused
 rather than reinterpreted.
 ## Reading the preview
 Every operation shows both full paths, the kind of move (`rename`, `case-only
 rename`, `cross-filesystem move`), how many photos it affects, its journal state, and
 any issue with its severity. The plan can be exported as JSON before you commit to it.
 **A run cannot be stopped part-way.** It can be interrupted — by a crash, a power
 cut, a killed container — and interruption is recoverable, but there is no cancel
 button once it starts. That is stated on the confirmation, not hidden in a manual.
 ## After an interruption
 The recovery panel lists each unresolved operation with a verdict read from the
 journal *and the disk*: resumable, safely rollbackable, or needing a person. It never
 guesses from a missing path alone. Until it is resolved, unrelated mutations are
 refused with `409 rename_recovery_required`.
 Rollback is recovery, not undo. A completed operation is terminal — the button only
 appears for operations that are actually reversible. See
 [recovery](../recovery.md).
 Next: [upload](uploads.md).
--- a/docs/stages/safety.md
+++ b/docs/stages/safety.md
@@ -1,43 +0,0 @@
 # Safety review
 [← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
 ![The safety review queue](../images/safety.png)
 **What it is for.** Deciding which photographs may be sent to a cloud vision
 provider. This is the privacy gate the rest of the design is built around.
 **What you decide.** `sfw`, `nsfw`, or defer — per photo, or in bulk from the filters.
 A local model can score first to order the queue, but the score is a suggestion; the
 decision is yours.
 **What it changes.** The decision is stored in the database *and* projected into the
 file: one mutually exclusive `sfw` or `nsfw` keyword written into `Keywords` and
 `Subject`. The write is merged with existing metadata, read back, and verified, and
 the file's SHA-256 is refreshed afterwards.
 **What it refuses.** An undecided or deferred photo does not reach the vision
 provider, and does not reach Immich either. If the read-back shows that a field the
 stage does not own has changed, the checkpoint is marked `divergent`, the asset is not
 marked verified, and the next mutating stage is blocked rather than proceeding on
 metadata nobody trusts.
 ## The rule that matters
 > Only a confirmed `sfw` photo may enter cloud content analysis. A confirmed `nsfw`
 > photo skips analysis entirely but remains eligible for upload to Immich once its
 > keyword is verified.
 That is why marking something NSFW is not a punishment: it routes the photo around an
 external service while keeping it in your own library workflow.
 The gate is re-checked *after* the provider call as well. If a decision flips to NSFW
 while an analysis is in flight, the result is discarded rather than stored.
 ## Reading the view
 The tabs filter by state. Each row shows the path, the model's score, its suggestion,
 your decision, and an `✓ exif` badge once the keyword is verified on disk. A row
 without that badge has a decision the file does not yet carry.
 Next: [analysis](analysis.md).
--- a/docs/stages/uploads.md
+++ b/docs/stages/uploads.md
@@ -1,45 +0,0 @@
 # Upload
 [← Documentation index](../index.md) · [Guided first pass](../first-pass.md)
 ![Upload preflight](../images/uploads.png)
 **What it is for.** Sending an approved album to Immich through `immich-go`, with an
 audit trail of exactly which bytes went.
 **What you decide.** Which albums, and whether to proceed once the preflight has
 listed its blockers. Upload is never an automatic consequence of renaming.
 **What it changes.** Nothing locally. On the Immich server, assets appear. Locally a
 batch is recorded: the album, the asset ids, the redacted command, the uploader
 version, the pre-upload SHA-256 **and** the SHA-1 Immich matches on, the output log,
 and the outcome counts.
 **What it refuses.** Preflight blocks on: missing credentials, an unreachable server,
 a missing `immich-go`, an unresolved rename, an undecided or deferred safety
 decision, an unverified EXIF checkpoint, incomplete analysis for an SFW photo, a file
 whose bytes changed since it was checkpointed, and a partial scope you have not
 explicitly accepted. The approval is then **re-proved immediately before the uploader
 runs** — bytes edited after you approved fail with `stale_preflight` and the uploader
 never starts.
 ## Reading the view
 The scope shows exactly which albums and how many photos. The command preview is the
 real command with the API key removed; the key never reaches the browser and never
 reaches a log.
 ## Uncertain is not failed
 If the process dies after the server accepted files, the batch becomes
 `unknown_requires_verification` — not "failed", and **not retryable**. The server may
 already hold the photographs, and uploading again would create duplicates or
 upgrades. Verification asks Immich about the recorded SHA-1 and answers present,
 absent, or inconclusive; an inconclusive answer is resolved by you, with the evidence
 recorded.
 If a file's bytes change after a successful upload, it is marked
 `changed_after_upload` and you are warned that uploading again may create or upgrade
 an asset rather than doing nothing.
 Next: [archive](archive.md).
--- a/frontend/css/app.css
+++ b/frontend/css/app.css
@@ -170,20 +170,6 @@ a.link:hover { text-decoration: underline; }
 .grid th, .grid td { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--border); vertical-align: top; }
 .path { font-family: ui-monospace, monospace; font-size: 0.85em; word-break: break-all; }
 /* Docs: prose, so it gets a reading measure rather than the full window width. */
 .doc { max-width: 72ch; }
 .doc h1 { margin-top: 0; }
 .doc h2, .doc h3 { margin-top: 1.6em; border-bottom: 1px solid var(--border); padding-bottom: 4px; }
 .doc code { font-family: ui-monospace, monospace; font-size: 0.9em; background: var(--surface-2); padding: 1px 4px; border-radius: 4px; }
 .doc pre { background: var(--surface-2); border: 1px solid var(--border); border-radius: var(--radius); padding: 12px; overflow: auto; }
 .doc pre code { background: none; padding: 0; }
 .doc table { border-collapse: collapse; width: 100%; }
 .doc th, .doc td { text-align: left; padding: 6px 8px; border-bottom: 1px solid var(--border); vertical-align: top; }
 .doc blockquote { margin: 1em 0; padding-left: 12px; border-left: 3px solid var(--border); color: var(--muted); }
 .doc img { max-width: 100%; }
 .diagram { margin: 1.5em 0; padding: 0; overflow: auto; }
 .diagram svg { max-width: 100%; height: auto; }
 /* Narrow screens: stack the panes so blockers and actions stay reachable. */
@media (max-width: 720px) {
  .two-pane { grid-template-columns: 1fr; }
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -21,7 +21,6 @@
        <a href="#/uploads" data-nav="uploads">Upload</a>
        <a href="#/archive" data-nav="archive">Archive</a>
        <a href="#/stats" data-nav="stats">Stats</a>
        <a href="#/docs" data-nav="docs">Docs</a>
      </nav>
    </header>
    <main id="app" aria-live="polite"><!-- views render here --></main>
--- a/frontend/js/app.js
+++ b/frontend/js/app.js
@@ -1,7 +1,5 @@
 import { api } from "./api.js";
 import { renderArchive, setArchiveRender } from "./archive.js";
 import { renderDocs } from "./docs.js";
 import { show as showIn } from "./dom.js";
 import { navigate, onRouteChange, parseHash } from "./router.js";
 import { renderRenames, setRenamesRender } from "./renames.js";
 import { renderUploads, setUploadsRender } from "./uploads.js";
@@ -36,7 +34,7 @@ function el(tag, attrs = {}, ...children) {
 }
 function show(...nodes) {
-  showIn(root, ...nodes);
+  root.replaceChildren(...nodes);
 }
 function setActiveNav(view) {
@@ -387,7 +385,6 @@ function render() {
  else if (path === "/uploads") renderUploads(root, params);
  else if (path === "/archive") renderArchive(root, params);
  else if (path === "/stats") renderStats(root, params);
  else if (path === "/docs") renderDocs(root, params);
  else show(errorBanner("Unknown view"));
 }
--- a/frontend/js/archive.js
+++ b/frontend/js/archive.js
@@ -9,7 +9,7 @@
 // is not mounted produces an instruction naming it rather than a disabled mystery,
 // and an operation whose evidence is ambiguous offers no button at all.
 import { api } from "./api.js";
-import { el, errorBanner, setActiveNav, show } from "./dom.js";
+import { el, errorBanner, setActiveNav } from "./dom.js";
 import { subscribeJob } from "./events.js";
 import { navigate } from "./router.js";
@@ -46,7 +46,7 @@ export async function renderArchive(root, params = {}) {
  try {
    locations = (await api.archiveLocations()).locations;
  } catch (error) {
-    show(root, errorBanner(`Failed to load archive locations: ${error.message}`));
+    root.replaceChildren(errorBanner(`Failed to load archive locations: ${error.message}`));
    return;
  }
  const location = locations.find((l) => l.id === params.location) || locations[0] || null;
@@ -61,7 +61,7 @@ export async function renderArchive(root, params = {}) {
      ),
      outcomeBanner()
    );
-    show(root, ...nodes.filter(Boolean));
+    root.replaceChildren(...nodes.filter(Boolean));
    return;
  }
@@ -95,7 +95,7 @@ export async function renderArchive(root, params = {}) {
    archived ? archivedSection(archived.items, locations) : null,
    restore ? restoreSection(restore, location) : null
  );
-  show(root, ...nodes.filter(Boolean));
+  root.replaceChildren(...nodes.filter(Boolean));
 }
 function plans(listed) {
--- a/frontend/js/docs.js
+++ b/frontend/js/docs.js
@@ -1,263 +0,0 @@
 // The documentation view (US09-01): the manuals in `docs/`, rendered in the app.
 //
 // The same markdown files are the repository's documentation and the deployment's
 // documentation. An operator who was handed a URL and an access secret has no
 // checkout in front of them, and the network the application runs on is not assumed
 // to reach a CDN — so the renderer is vendored and everything here is same-origin.
 //
 // Nothing on this page is authenticated. It is served from the static mount beside
 // the application shell, exactly like `index.html`: the troubleshooting page is
 // needed most by whoever cannot get past the access secret, and no documentation
 // file contains anything a session would protect.
 //
 // `marked` and `mermaid` are loaded lazily, on the first documentation page and the
 // first diagram. They are large, and every other view does without them.
 import { el, errorBanner, setActiveNav } from "./dom.js";
 const DOCS_BASE = "/docs";
 const VENDOR = "/app/js/vendor";
 const INDEX_PAGE = "index";
 // A page name comes from the hash, so it is caller input: no scheme, no traversal,
 // no absolute path. The server would refuse those too; this refuses them earlier and
 // without a request that looks like an attempt.
 const PAGE_PATTERN = /^[\w-]+(\/[\w-]+)*$/;
 let markedPromise;
 let mermaidPromise;
 function loadMarked() {
  markedPromise ??= import(`${VENDOR}/marked.esm.js`).then((module) => module.marked);
  return markedPromise;
 }
 // mermaid ships one large UMD bundle rather than a self-contained ES module, so it
 // arrives through a script element. `script-src 'self'` allows it because it is ours
 // and same-origin; nothing here relaxes that.
 function loadMermaid() {
  mermaidPromise ??= new Promise((resolve, reject) => {
    const script = document.createElement("script");
    script.src = `${VENDOR}/mermaid.min.js`;
    script.onload = () => resolve(window.mermaid);
    script.onerror = () => reject(new Error("the diagram renderer could not be loaded"));
    document.head.appendChild(script);
  });
  return mermaidPromise;
 }
 // ── the pure parts, unit-tested in js/tests/unit.js ──────────────────────────
 /** A stable, readable heading anchor. Letters and digits of any script survive. */
 export function slug(text) {
  const cleaned = String(text)
    .toLowerCase()
    .trim()
    .replace(/[^\p{L}\p{N}\s-]/gu, "")
    .replace(/[\s-]+/g, "-")
    .replace(/^-|-$/g, "");
  return cleaned || "section";
 }
 /** Assign every heading an id, disambiguating repeats the way a reader would
 *  expect: the first `Notes` keeps `#notes`, the second becomes `#notes-2`. */
 export function assignHeadingIds(headings) {
  const used = new Map();
  for (const heading of headings) {
    const base = slug(heading.textContent);
    const seen = (used.get(base) || 0) + 1;
    used.set(base, seen);
    heading.id = seen === 1 ? base : `${base}-${seen}`;
  }
  return headings;
 }
 /**
 * Where a link inside a documentation page should go.
 *
 * Markdown links between documents are relative file paths, which a browser would
 * treat as downloads that leave the application. Returns the in-app target for a
 * link to another document or to a heading, and `null` for anything else — external
 * links stay exactly as the author wrote them.
 */
 export function resolveDocLink(currentPage, href) {
  if (!href) return null;
  if (/^[a-z][a-z\d+.-]*:/i.test(href) || href.startsWith("//")) return null;
  if (href.startsWith("#")) return { page: currentPage, anchor: href.slice(1) };
  const [target, anchor = ""] = href.split("#");
  if (!/\.md$/i.test(target)) return null;
  // Resolved against the current document, so `../guides/x.md` means what it means
  // in the repository. The origin is a placeholder; only the path is used.
  const resolved = new URL(target, `https://docs.invalid/${currentPage}.md`);
  const page = decodeURIComponent(resolved.pathname).replace(/^\//, "").replace(/\.md$/i, "");
  return PAGE_PATTERN.test(page) ? { page, anchor } : null;
 }
 /**
 * Point every in-app link at its route, and leave every other link alone.
 *
 * The resolved page is kept on the element, so the reading order can be read back
 * from the rendered index rather than parsed out of the markdown a second time.
 */
 export function rewriteLinks(article, page) {
  for (const link of article.querySelectorAll("a[href]")) {
    const href = link.getAttribute("href");
    const target = resolveDocLink(page, href);
    if (target) {
      link.setAttribute("href", docHash(target.page, target.anchor));
      link.dataset.docPage = target.page;
    } else if (/^https?:/i.test(href)) {
      link.setAttribute("rel", "noreferrer noopener");
      link.setAttribute("target", "_blank");
    }
  }
  return article;
 }
 /** The reading order, taken from the index document itself — one list, in one
 *  place, that is equally the index on Gitea and the navigation here. */
 export function documentIndex(indexElement) {
  const pages = [];
  for (const link of indexElement.querySelectorAll("a[data-doc-page]")) {
    const page = link.dataset.docPage;
    if (page !== INDEX_PAGE && !pages.some((entry) => entry.page === page)) {
      pages.push({ page, title: link.textContent.trim() });
    }
  }
  return pages;
 }
 // ── the view ─────────────────────────────────────────────────────────────────
 async function fetchPage(page) {
  const response = await fetch(`${DOCS_BASE}/${page}.md`, { headers: { accept: "text/markdown" } });
  if (!response.ok) throw new Error(`documentation page unavailable: ${response.status}`);
  return response.text();
 }
 async function toArticle(markdown, page) {
  const marked = await loadMarked();
  const article = el("article", { class: "doc", "data-testid": "doc", "data-page": page });
  // The only innerHTML in the application, and deliberate: rendering markdown *is*
  // producing HTML. The input is a file from this repository, and the page's CSP
  // (`script-src 'self'`, no `'unsafe-inline'`) means injected script and inline
  // handlers do not run even if one ever were not.
  article.innerHTML = marked.parse(markdown, { async: false });
  assignHeadingIds(article.querySelectorAll("h1, h2, h3, h4, h5, h6"));
  rewriteLinks(article, page);
  return article;
 }
 function docHash(page, anchor = "") {
  const query = new URLSearchParams(anchor ? { page, anchor } : { page });
  return `#/docs?${query}`;
 }
 /** Diagrams are authored as ```mermaid blocks so the source is diffable and Gitea
 *  renders them natively. A failure here replaces the diagram, never the page. */
 async function renderDiagrams(article) {
  const blocks = [...article.querySelectorAll("pre > code.language-mermaid")];
  if (!blocks.length) return;
  let mermaid;
  try {
    mermaid = await loadMermaid();
    mermaid.initialize({ startOnLoad: false, securityLevel: "strict", theme: "dark" });
  } catch (error) {
    blocks.forEach((block) => block.closest("pre").replaceWith(errorBanner(error.message)));
    return;
  }
  for (const [index, block] of blocks.entries()) {
    const figure = el("figure", { class: "diagram", "data-testid": "diagram" });
    block.closest("pre").replaceWith(figure);
    try {
      const { svg } = await mermaid.render(`diagram-${index}-${Date.now()}`, block.textContent);
      figure.innerHTML = svg;
    } catch (error) {
      figure.replaceWith(errorBanner(`Diagram could not be drawn: ${error.message}`));
    }
  }
 }
 function notFound() {
  return el(
    "div",
    { class: "alert", role: "alert", "data-testid": "doc-not-found" },
    "That documentation page does not exist. ",
    el("a", { class: "link", href: docHash(INDEX_PAGE) }, "Back to the documentation index")
  );
 }
 function sidebar(pages, current) {
  return el(
    "nav",
    { class: "card", "aria-label": "Documentation" },
    el("h2", {}, "Documentation"),
    el(
      "ul",
      { class: "album-list", "data-testid": "doc-pages" },
      el(
        "li",
        {},
        el(
          "a",
          {
            href: docHash(INDEX_PAGE),
            "aria-current": current === INDEX_PAGE ? "true" : false,
          },
          "Index"
        )
      ),
      ...pages.map(({ page, title }) =>
        el(
          "li",
          {},
          el(
            "a",
            {
              href: docHash(page),
              "data-page": page,
              "aria-current": page === current ? "true" : false,
            },
            title
          )
        )
      )
    )
  );
 }
 export async function renderDocs(root, params = {}) {
  setActiveNav("docs");
  const requested = params.page || INDEX_PAGE;
  const page = PAGE_PATTERN.test(requested) ? requested : "";
  let indexArticle;
  try {
    indexArticle = await toArticle(await fetchPage(INDEX_PAGE), INDEX_PAGE);
  } catch (error) {
    root.replaceChildren(errorBanner(`Documentation is unavailable: ${error.message}`));
    return;
  }
  const pages = documentIndex(indexArticle);
  let article;
  if (!page) article = notFound();
  else if (page === INDEX_PAGE) article = indexArticle;
  else {
    try {
      article = await toArticle(await fetchPage(page), page);
    } catch {
      article = notFound();
    }
  }
  root.replaceChildren(el("div", { class: "two-pane" }, sidebar(pages, page), article));
  await renderDiagrams(article);
  scrollToAnchor(params.anchor);
 }
 // A documentation anchor cannot live in the hash — the hash is the route — so it
 // travels as a parameter and is applied after the page renders.
 function scrollToAnchor(anchor) {
  if (!anchor) return;
  const target = document.getElementById(anchor);
  if (target) target.scrollIntoView({ block: "start" });
 }
--- a/frontend/js/dom.js
+++ b/frontend/js/dom.js
@@ -21,19 +21,6 @@ export function errorBanner(message) {
  return el("div", { class: "alert", role: "alert" }, message);
 }
 /**
 * Replace a container's contents, dropping the absent ones.
 *
 * `el` already ignores null children, but `replaceChildren` does not: it stringifies
 * them, so an optional node that is not there renders the word "null" on the page.
 * Every view builds optional nodes — a banner only while a job runs, a conflict only
 * after a 409 — so the filter belongs here rather than in each caller. It was missing
 * from one of them, and a documentation screenshot is where that turned up (US09-04).
 */
 export function show(root, ...nodes) {
  root.replaceChildren(...nodes.flat().filter((node) => node != null && node !== false));
 }
 export function setActiveNav(view) {
  document.querySelectorAll("nav a[data-nav]").forEach((a) => {
    if (a.dataset.nav === view) a.setAttribute("aria-current", "page");
--- a/frontend/js/renames.js
+++ b/frontend/js/renames.js
@@ -5,7 +5,7 @@
 // recovery classifications all come from the server; the view only shows them and
 // refuses to offer an action the server would reject.
 import { api } from "./api.js";
-import { el, errorBanner, setActiveNav, show } from "./dom.js";
+import { el, errorBanner, setActiveNav } from "./dom.js";
 // What the last confirm did, for this tab only. Deliberately not persisted: after a
 // reload the page must show what the journal says, not what this page remembers.
@@ -24,7 +24,7 @@ export async function renderRenames(root, params = {}) {
  try {
    [plans, recovery] = await Promise.all([api.listPlans(), api.renameRecovery()]);
  } catch (error) {
-    show(root, errorBanner(`Failed to load renames: ${error.message}`));
+    root.replaceChildren(errorBanner(`Failed to load renames: ${error.message}`));
    return;
  }
@@ -34,13 +34,13 @@ export async function renderRenames(root, params = {}) {
    try {
      plan = await api.getPlan(selectedId);
    } catch (error) {
-      show(root, errorBanner(`Failed to load plan: ${error.message}`));
+      root.replaceChildren(errorBanner(`Failed to load plan: ${error.message}`));
      return;
    }
  }
  const blocked = recovery.blocks_mutation;
-  show(root,
+  root.replaceChildren(
    el("h1", {}, "Renames"),
    recoveryPanel(recovery),
    el(
--- a/frontend/js/tests/unit.js
+++ b/frontend/js/tests/unit.js
@@ -7,7 +7,6 @@ import { createStore } from "../store.js";
 import { parseHash, navigate } from "../router.js";
 import { api, cancellable } from "../api.js";
 import { subscribeJob } from "../events.js";
 import { assignHeadingIds, documentIndex, resolveDocLink, rewriteLinks, slug } from "../docs.js";
 const cases = [];
 function ok(name, cond) {
@@ -143,62 +142,6 @@ async function run() {
    window.EventSource = realES;
  }
  // ── documentation view (US09-01) ─────────────────────────────────────────
  {
    ok("slug lowercases and dashes a heading", slug("Key Flows") === "key-flows");
    ok(
      "slug drops punctuation but keeps words",
      slug("What it *will not* do:") === "what-it-will-not-do"
    );
    ok("slug keeps non-ASCII letters", slug("Größe & Gewicht") === "größe-gewicht");
    ok("slug never yields an empty anchor", slug("!!!") === "section");
    const doc = document.createElement("div");
    doc.innerHTML = "<h2>Notes</h2><h3>Notes</h3><h2>Notes</h2>";
    const ids = [...assignHeadingIds(doc.querySelectorAll("h2, h3"))].map((h) => h.id);
    ok("repeated headings get distinct anchors", ids.join(",") === "notes,notes-2,notes-3");
    ok(
      "a sibling document link becomes an in-app route",
      resolveDocLink("index", "overview.md")?.page === "overview"
    );
    const nested = resolveDocLink("guides/install", "../overview.md#running-it");
    ok("a relative link resolves against the current page", nested?.page === "overview");
    ok("a link's anchor survives the rewrite", nested?.anchor === "running-it");
    ok(
      "a bare anchor stays on the current page",
      resolveDocLink("overview", "#the-workflow")?.page === "overview"
    );
    ok("an external link is left alone", resolveDocLink("index", "https://example.test/x") === null);
    ok("a non-markdown relative link is left alone", resolveDocLink("index", "images/a.png") === null);
    // A climb cannot leave the documentation tree: it is clamped at the root, so the
    // page it names is still fetched from under /docs and simply does not exist.
    ok(
      "a link that climbs above the docs root is clamped",
      resolveDocLink("index", "../../etc/passwd.md")?.page === "etc/passwd"
    );
    ok(
      "a page name that is not a page name is refused",
      resolveDocLink("index", "..%2f..%2fetc%2fpasswd.md") === null
    );
    const index = document.createElement("div");
    index.innerHTML =
      '<a href="overview.md">Overview</a><a href="overview.md">again</a>' +
      '<a href="index.md">itself</a><a href="https://example.test">out</a>';
    const listed = documentIndex(rewriteLinks(index, "index"));
    ok(
      "an external link is marked safe to open away from the app",
      index.querySelector('a[href^="https"]').rel === "noreferrer noopener"
    );
    ok(
      "an in-app link points at the docs route",
      index.querySelector("a").getAttribute("href") === "#/docs?page=overview"
    );
    ok("the index lists each page once, in order", listed.length === 1);
    ok("the index takes its titles from the link text", listed[0].title === "Overview");
  }
  await tick();
  const failed = cases.filter((c) => !c.ok);
  window.__RESULTS__ = { passed: cases.length - failed.length, failed: failed.length, cases };
--- a/frontend/js/uploads.js
+++ b/frontend/js/uploads.js
@@ -8,7 +8,7 @@
 // preview arrives redacted — so nothing in this view may reconstruct, store, or
 // route a secret.
 import { api } from "./api.js";
-import { el, errorBanner, setActiveNav, show } from "./dom.js";
+import { el, errorBanner, setActiveNav } from "./dom.js";
 import { subscribeJob } from "./events.js";
 import { navigate } from "./router.js";
@@ -45,7 +45,7 @@ export async function renderUploads(root, params = {}) {
      api.listUploadBatches(),
    ]);
  } catch (error) {
-    show(root, errorBanner(`Failed to load uploads: ${error.message}`));
+    root.replaceChildren(errorBanner(`Failed to load uploads: ${error.message}`));
    return;
  }
@@ -62,12 +62,12 @@ export async function renderUploads(root, params = {}) {
      batch = detail;
      history = verifications.verifications;
    } catch (error) {
-      show(root, errorBanner(`Failed to load upload batch: ${error.message}`));
+      root.replaceChildren(errorBanner(`Failed to load upload batch: ${error.message}`));
      return;
    }
  }
-  show(root,
+  root.replaceChildren(
    ...[
      el("h1", {}, "Upload"),
      configurationCard(preflight),
--- a/frontend/js/vendor/VERSIONS.json
+++ b/frontend/js/vendor/VERSIONS.json
@@ -1,23 +0,0 @@
 {
  "_comment": "Vendored browser libraries (US09-01). Committed rather than fetched: the application is deployed to a network whose outbound access is not assumed, and `default-src 'self'` forbids a CDN. Checksums are asserted by tests/integration/test_documentation.py, so replacing a file without recording it here fails the suite. Update by downloading the pinned URL and recording the new version and sha256 in the same commit.",
  "libraries": [
    {
      "file": "marked.esm.js",
      "name": "marked",
      "version": "18.0.10",
      "license": "MIT",
      "url": "https://cdn.jsdelivr.net/npm/marked@18.0.10/lib/marked.esm.js",
      "sha256": "4cf47dfebb7f614a08fc0a579ab0fe407ff0ed2b717bf953040c85b2f493a4f0",
      "why": "Markdown to HTML for the documentation view. An ES module with no dependencies, imported lazily by js/docs.js."
    },
    {
      "file": "mermaid.min.js",
      "name": "mermaid",
      "version": "11.17.0",
      "license": "MIT",
      "url": "https://cdn.jsdelivr.net/npm/mermaid@11.17.0/dist/mermaid.min.js",
      "sha256": "8d8e0eec56d3a83b4b3c87f42050845546dee93ebe1875d2117c12e6947c0cb3",
      "why": "Renders ```mermaid blocks so diagrams are diffable source that Gitea also renders. The single-file UMD build rather than the ES module entry, whose ~40 lazy chunks would each need vendoring and pinning."
    }
  ]
 }
--- a/frontend/js/vendor/marked.esm.js
+++ b/frontend/js/vendor/marked.esm.js
--- a/frontend/js/vendor/mermaid.min.js
+++ b/frontend/js/vendor/mermaid.min.js
--- a/frontend/js/views.js
+++ b/frontend/js/views.js
@@ -3,7 +3,7 @@
 // HTML. Mutating actions are disabled while a job holds the library_write lock and
 // say why (concept §shared interaction rules: read-only browsing stays available).
 import { api } from "./api.js";
-import { el, errorBanner, setActiveNav, show } from "./dom.js";
+import { el, errorBanner, setActiveNav } from "./dom.js";
 import { navigate } from "./router.js";
 import { subscribeJob } from "./events.js";
@@ -26,7 +26,7 @@ export async function renderWorkflow(root) {
  try {
    data = await api.workflow();
  } catch (error) {
-    show(root, errorBanner(`Failed to load workflow: ${error.message}`));
+    root.replaceChildren(errorBanner(`Failed to load workflow: ${error.message}`));
    return;
  }
  const active = data.active_job;
@@ -67,7 +67,7 @@ export async function renderWorkflow(root) {
      )
    );
  });
-  show(root,
+  root.replaceChildren(
    el("h1", {}, "Workflow"),
    jobBanner(active),
    el("div", { class: "stepper" }, ...cards)
@@ -105,7 +105,7 @@ export async function renderSafety(root, params) {
  try {
    data = await api.safetyQueue({ state });
  } catch (error) {
-    show(root, errorBanner(`Failed to load safety queue: ${error.message}`));
+    root.replaceChildren(errorBanner(`Failed to load safety queue: ${error.message}`));
    return;
  }
@@ -149,7 +149,7 @@ export async function renderSafety(root, params) {
    )
  );
-  show(root,
+  root.replaceChildren(
    el("h1", {}, "Safety review"),
    tabs,
    el(
@@ -197,7 +197,7 @@ export async function renderLibrary(root, params) {
  try {
    data = await api.libraryAssets({ q, offset, limit, sort: params.sort || "path" });
  } catch (error) {
-    show(root, errorBanner(`Failed to load library: ${error.message}`));
+    root.replaceChildren(errorBanner(`Failed to load library: ${error.message}`));
    return;
  }
@@ -220,7 +220,7 @@ export async function renderLibrary(root, params) {
    )
  );
-  show(root,
+  root.replaceChildren(
    el("h1", {}, "Library"),
    el("div", { class: "toolbar" }, search, el("span", { class: "muted", "data-testid": "library-total" }, `${data.total} photos`)),
    data.rows.length ? el("div", { class: "cluster-grid" }, ...cards) : el("p", { class: "muted" }, "No matching photos."),
@@ -235,7 +235,7 @@ export async function renderAnalyze(root) {
  try {
    [counts, workflow] = await Promise.all([api.analysisCounts(), api.workflow()]);
  } catch (error) {
-    show(root, errorBanner(`Failed to load analysis: ${error.message}`));
+    root.replaceChildren(errorBanner(`Failed to load analysis: ${error.message}`));
    return;
  }
  const active = workflow.active_job;
@@ -269,7 +269,7 @@ export async function renderAnalyze(root) {
    "Analyze eligible SFW assets"
  );
-  show(root,
+  root.replaceChildren(
    el("h1", {}, "Analyze"),
    jobBanner(active),
    el(
@@ -292,10 +292,10 @@ export async function renderStats(root) {
  try {
    data = await api.libraryStats();
  } catch (error) {
-    show(root, errorBanner(`Failed to load stats: ${error.message}`));
+    root.replaceChildren(errorBanner(`Failed to load stats: ${error.message}`));
    return;
  }
-  show(root,
+  root.replaceChildren(
    el("h1", {}, "Stats"),
    el("div", { class: "counts-grid", "data-testid": "stats-status" }, ...Object.entries(data.status).map(([k, v]) => stat(k, v))),
    facetBlock("Top tags", data.top_tags),
@@ -338,7 +338,7 @@ export async function renderAlbums(root, params = {}) {
      api.renameRecovery(),
    ]);
  } catch (error) {
-    show(root, errorBanner(`Failed to load albums: ${error.message}`));
+    root.replaceChildren(errorBanner(`Failed to load albums: ${error.message}`));
    return;
  }
@@ -385,7 +385,7 @@ export async function renderAlbums(root, params = {}) {
      )
    : el("p", { class: "muted" }, "No albums with evidence yet.");
-  show(root,
+  root.replaceChildren(
    el("h1", {}, "Albums"),
    renameBlocked
      ? el(
--- a/photo_pipeline/main.py
+++ b/photo_pipeline/main.py
@@ -1,5 +1,5 @@
 """Application management CLI:
-``python -m photo_pipeline {serve,migrate,worker,import-legacy-scores,backup,verify-backup,restore,diagnostics,benchmark,release-gate,container-gate,docs-gate,dry-run,approve-dry-run}``.
+``python -m photo_pipeline {serve,migrate,worker,import-legacy-scores,backup,verify-backup,restore,diagnostics}``.
 ``serve`` and ``worker`` take the library process lock for their role (US07-05):
 two workers, or the frozen CLI running beside the app, would each be safe on their
@@ -11,11 +11,9 @@ from __future__ import annotations
 import argparse
 import json
 import sys
 from pathlib import Path
 from typing import Sequence
 from photo_pipeline import path_policy
 from photo_pipeline.config import Config
 from photo_pipeline.services.app_lock import LegacyProcessActive, LibraryLock, LockHeld
 from photo_pipeline.services.backup import BackupError, BackupService, migrate_with_backup
@@ -70,20 +68,6 @@ def main(argv: Sequence[str] | None = None) -> int:
        "release-gate", help="Run every suite in an isolated stack and keep the evidence"
    )
    gate_cmd.add_argument("--output", help="Evidence directory (default: data/release/<stamp>)")
    container_cmd = commands.add_parser(
        "container-gate",
        help="Provision the composition from the built image, run the phase_h "
        "acceptance suite against it, destroy it, and keep the evidence (US08-05)",
    )
    container_cmd.add_argument(
        "--output", help="Evidence directory (default: data/container-gate/<stamp>)"
    )
    docs_cmd = commands.add_parser(
        "docs-gate",
        help="Check the manuals against the application they describe and keep the "
        "evidence (US09-05)",
    )
    docs_cmd.add_argument("--output", help="Evidence directory (default: data/docs-gate/<stamp>)")
    dry_cmd = commands.add_parser(
        "dry-run", help="Read-only reconciliation of the configured library (US07-07)"
    )
@@ -99,18 +83,6 @@ def main(argv: Sequence[str] | None = None) -> int:
    config = Config.from_env()
    config.database_path.parent.mkdir(parents=True, exist_ok=True)
    # In a container the two roles that touch the library check their boundary before
    # they take a lock or bind a port: the configured roots must name the mount paths,
    # and a mismatch is cheaper to refuse than to discover at the first write (US08-03).
    # Only in a container — on a host an unmounted root is an ordinary Tuesday (an
    # archive medium that is not plugged in), and refusing to serve would take the
    # offline half of the library away with it.
    if args.command in ("serve", "worker") and path_policy.in_container():
        refusal = path_policy.roots_refusal(config.library_roots, require_mount=True)
        if refusal is not None:
            print(refusal, file=sys.stderr)
            return 5
    if args.command == "migrate":
        manifest = migrate_with_backup(config)
        if manifest:
@@ -169,55 +141,6 @@ def main(argv: Sequence[str] | None = None) -> int:
        )
        return 0 if report["ok"] else 1
    if args.command == "container-gate":
        from datetime import datetime, timezone
        from photo_pipeline.services import release
        # The suite provisions and destroys the composition itself; what this command
        # adds is the single entry point and the retained evidence. No skip is an
        # environment limit here: a gate that did not reach the containers proved
        # nothing about them.
        output = args.output or Path(config.data_dir) / "container-gate" / datetime.now(
            timezone.utc
        ).strftime("%Y%m%dT%H%M%SZ")
        report = release.run_gate(
            config,
            output=output,
            stages=release.CONTAINER_STAGES,
            allowed_skips=release.CONTAINER_ALLOWED_SKIP_REASONS,
        )
        print(
            json.dumps(
                {k: v for k, v in report.items() if k not in ("stages", "matrix")}, indent=2
            )
        )
        return 0 if report["ok"] else 1
    if args.command == "docs-gate":
        from datetime import datetime, timezone
        from photo_pipeline.services import release
        # Documentation that disagrees with the application is worse than none: it is
        # trusted. So this gate accepts no skip either — a check that did not run is a
        # page nobody compared with the code.
        output = args.output or Path(config.data_dir) / "docs-gate" / datetime.now(
            timezone.utc
        ).strftime("%Y%m%dT%H%M%SZ")
        report = release.run_gate(
            config,
            output=output,
            stages=release.DOCS_STAGES,
            allowed_skips=release.DOCS_ALLOWED_SKIP_REASONS,
        )
        print(
            json.dumps(
                {k: v for k, v in report.items() if k not in ("stages", "matrix")}, indent=2
            )
        )
        return 0 if report["ok"] else 1
    if args.command == "dry-run":
        from photo_pipeline.services import release
@@ -286,6 +209,8 @@ def main(argv: Sequence[str] | None = None) -> int:
            lock.release()
        return 0
    import sys
    import uvicorn
    from photo_pipeline.api.app import ConfigurationRefused, create_app
@@ -313,6 +238,8 @@ def _acquire(lock: LibraryLock, *, allow_legacy: bool) -> int | None:
    Returns an exit code to return, or ``None`` when the lock was acquired.
    """
    import sys
    try:
        lock.acquire(allow_legacy=allow_legacy)
    except LockHeld as error:
--- a/photo_pipeline/api/app.py
+++ b/photo_pipeline/api/app.py
@@ -53,7 +53,6 @@ from photo_pipeline.services.thumbnails import ThumbnailService
 from photo_pipeline.services.upload_batches import UploadBatchService
 FRONTEND_DIR = Path(__file__).resolve().parents[2] / "frontend"
 DOCS_DIR = Path(__file__).resolve().parents[2] / "docs"
 log = logging.getLogger(__name__)
@@ -152,10 +151,4 @@ def create_app(config: Config | None = None) -> FastAPI:
    # Static single-page app (hash-routed). Mounted last so /api/v1 wins.
    if FRONTEND_DIR.is_dir():
        app.mount("/app", StaticFiles(directory=FRONTEND_DIR, html=True), name="app")
    # The manuals, as their own markdown files (US09-01). Unauthenticated for the
    # same reason the application shell is: whoever cannot get past the access
    # secret is exactly who needs the troubleshooting page, and no document holds
    # anything a session would protect.
    if DOCS_DIR.is_dir():
        app.mount("/docs", StaticFiles(directory=DOCS_DIR), name="docs")
    return app
--- a/photo_pipeline/api/security.py
+++ b/photo_pipeline/api/security.py
@@ -57,21 +57,9 @@ LOOPBACK_HOSTS = frozenset({"127.0.0.1", "localhost", "::1", "[::1]"})
 # backup a careful operator takes first, and its retention (US07-07).
 MUTATION_EXEMPT_PATHS = frozenset({f"{API_PREFIX}/backups", f"{API_PREFIX}/backups/prune"})
-# Applied to every response. `frame-ancestors 'none'` and CORP keep other pages from
+# Applied to every response. No inline script/style is used by the frontend, so the
 # policy can stay strict; `frame-ancestors 'none'` and CORP keep other pages from
 # embedding the app or its thumbnails.
 #
 # `script-src 'self'` is the boundary that matters and it is unchanged: no
 # `'unsafe-eval'`, no `'unsafe-inline'`, so nothing injected into the DOM can execute.
 # Whether the vendored diagram renderer needed `'unsafe-eval'` was measured rather
 # than assumed — mermaid's bundle contains no `eval(` and no `new Function`, and it
 # renders under this exact policy without a single script-src violation.
 #
 # `style-src` does gain `'unsafe-inline'` (US09-01): mermaid styles the SVG it builds
 # with an injected `<style>` element and `style=` attributes, and a diagram's CSS
 # cannot be hashed in advance. The concession is bounded by the directives around it
 # — with script execution still refused and `img-src`, `connect-src`, and `font-src`
 # all `'self'`, the CSS exfiltration channels stay closed and what is left is
 # defacement of a page its own operator is already looking at.
 DEFAULT_HEADERS = {
    "x-content-type-options": "nosniff",
    "x-frame-options": "DENY",
@@ -79,9 +67,8 @@ DEFAULT_HEADERS = {
    "cross-origin-resource-policy": "same-origin",
    "cross-origin-opener-policy": "same-origin",
    "content-security-policy": (
-        "default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; "
+        "default-src 'self'; img-src 'self' data:; style-src 'self'; script-src 'self'; "
-        "script-src 'self'; connect-src 'self'; font-src 'self'; "
+        "connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'"
        "frame-ancestors 'none'; base-uri 'none'; form-action 'none'"
    ),
 }
--- a/photo_pipeline/integrations/exiftool.py
+++ b/photo_pipeline/integrations/exiftool.py
@@ -12,10 +12,8 @@ nt-apply-list, pa-nsfw-filter). No dependency on the archived entry points.
 from __future__ import annotations
 import functools
 import json
 import os
 import shutil
 import subprocess
 from collections.abc import Iterable
@@ -34,27 +32,6 @@ def _timeout() -> float:
        return DEFAULT_TIMEOUT_SECONDS
 def find_binary(binary: str = "exiftool") -> str | None:
    """Absolute path of exiftool, or ``None`` when it is not installed."""
    return shutil.which(binary)
@functools.lru_cache(maxsize=1)
 def version() -> str | None:
    """Reported exiftool version, or ``None`` when it is missing or unusable.
    Cached: it cannot change inside a running process, and diagnostics asks for it
    on every report (US08-02, where a container image pins this version).
    """
    try:
        result = subprocess.run(
            ["exiftool", "-ver"], capture_output=True, text=True, timeout=_timeout()
        )
    except (OSError, subprocess.SubprocessError):
        return None
    return (result.stdout or "").strip() or None
 def read_keyword_sets(paths: Iterable[str]) -> dict[str, set[str]]:
    """Map each path to its lowercased set of ``Keywords`` + ``Subject`` values.
--- a/photo_pipeline/path_policy.py
+++ b/photo_pipeline/path_policy.py
@@ -15,7 +15,9 @@ import os
 from pathlib import Path
 from typing import Iterable, Iterator
-SUPPORTED_EXTENSIONS = {".jpg", ".jpeg", ".png", ".webp", ".heic", ".heif", ".tiff", ".tif"}
+SUPPORTED_EXTENSIONS = {
    ".jpg", ".jpeg", ".png", ".webp", ".heic", ".heif", ".tiff", ".tif"
 }
 EXCLUDED_DIR_NAMES = {"_IGNORE", ".@__thumb"}
@@ -70,63 +72,6 @@ def resolve_in_roots(roots: Iterable[os.PathLike | str], path: os.PathLike | str
    raise PathPolicyError("path is outside the configured library roots")
 def in_container() -> bool:
    """Whether this process is running inside a container image build of the app."""
    return Path("/.dockerenv").exists()
 def _under_mount(path: Path) -> bool:
    """Whether ``path`` or one of its parents below ``/`` is a mounted filesystem."""
    current = path.resolve()
    while current != current.parent:
        if os.path.ismount(current):
            return True
        current = current.parent
    return False
 def roots_refusal(roots: Iterable[os.PathLike | str], *, require_mount: bool = False) -> str | None:
    """Why the configured library roots cannot be worked with, or ``None`` (US08-03).
    The roots name the directories this installation renames folders in, rewrites
    EXIF in, and archives from. Container path policy is the same problem as host
    path policy with one new failure mode: the configured roots must name the
    *container-side* mount paths. A host path configured inside a container is
    either absent or an ordinary directory of the image, so the library looks empty
    and the first write lands in the container's throwaway layer instead of in the
    library. That is worth refusing at startup, while an operator is still watching,
    rather than at the first write.
    ``require_mount`` is the container-only half of that: inside a container a real
    library arrives through a bind mount, so a root that is not on (or under) a
    mount point is not the library the deployment meant.
    Writability is deliberately *not* checked: a bind mount's ownership is
    virtualised by Docker Desktop and Colima (it arrives as ``root:root``), so
    ``os.access`` there is evidence about the virtio layer rather than about the
    library. A wrong UID/GID surfaces as a refused rename with the real errno, which
    is at least true; a refusal here would be false on two supported platforms.
    """
    for root in roots:
        path = Path(root)
        if not path.exists():
            return (
                f"library root {path} does not exist: PHOTO_PIPELINE_LIBRARY_ROOTS must "
                "name paths that exist here, and in a container that means the mount path"
            )
        if not path.is_dir():
            return f"library root {path} is not a directory"
        if not os.access(path, os.R_OK | os.X_OK):
            return f"library root {path} is not readable by this process"
        if require_mount and not _under_mount(path):
            return (
                f"library root {path} is not on a mounted filesystem in this container: "
                "the library was not bind-mounted there, so PHOTO_PIPELINE_LIBRARY_ROOTS "
                "names a directory of the image rather than the library"
            )
    return None
 def iter_supported_files(root: os.PathLike | str) -> Iterator[Path]:
    """Yield supported, non-excluded files under ``root`` in deterministic order.
--- a/photo_pipeline/services/app_lock.py
+++ b/photo_pipeline/services/app_lock.py
@@ -15,17 +15,9 @@ package:
     "started_at": "...", "library_roots": ["..."]}
 One holder per role: an API and a worker are designed to run together, a second
-worker is not. A lock whose process is gone is stale and is taken over — refusing
+worker is not. A lock whose process is gone is stale and is taken over with the
-to start because of a crashed predecessor would turn one outage into two.
+takeover recorded — refusing to start because of a crashed predecessor would turn
-
+one outage into two.
 Ownership is an advisory ``flock`` on that file, not the record inside it. The
 record says *who*; the kernel says *whether*. That distinction is what makes the
 lock work in containers (US08-03), where a PID and a hostname are namespaced: a
 lock left behind by a container that no longer exists names a pid that still
 "exists" in the new container and a host that cannot be probed, so believing the
 file would deadlock every restart. A flock is released when its holder dies however
 it dies, and is seen by every process that can open the file — which for a local
 data directory is every container of this deployment.
 Legacy detection is deliberately a heuristic, not a promise: the archived CLI has
 no lock of its own, so what can be observed is its state files being written right
@@ -35,7 +27,6 @@ mutating stage should refuse until it stops.
 from __future__ import annotations
 import fcntl
 import json
 import os
 import socket
@@ -118,12 +109,6 @@ def _now() -> datetime:
    return datetime.now(timezone.utc)
 def _in_container() -> bool:
    from photo_pipeline import path_policy
    return path_policy.in_container()
 def legacy_activity(config: Config) -> dict:
    """Legacy state files written within the activity window, if any."""
    seen: list[dict] = []
@@ -154,7 +139,6 @@ class LibraryLock:
        self.role = role
        self.path = Path(config.data_dir) / f"{role}{LOCK_SUFFIX}"
        self._acquired = False
        self._handle = None
    # ── inspection ────────────────────────────────────────────────────────────
@@ -194,31 +178,12 @@ class LibraryLock:
                    "stop it before running the application"
                )
        self.path.parent.mkdir(parents=True, exist_ok=True)
        # The kernel decides, because the file cannot: a container's PID and hostname
        # are namespaced, so a lock left by a container that no longer exists names a
        # pid that "exists" and a host that cannot be probed (US08-03). An advisory
        # flock is held by a live process or by nobody, is released when that process
        # dies however it dies, and is shared by every process that can open this
        # file — which, for a local data directory, is every role in every container
        # of this deployment.
        handle = open(self.path, "a+", encoding="utf-8")
        try:
            fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
        except OSError:
            handle.close()
            raise LockHeld(self.holder() or Holder(self.role, -1, "unknown", "unknown")) from None
        current = self.holder()
-        if current is not None and current.host != socket.gethostname() and not _in_container():
+        if current is not None:
-            # We hold the kernel's lock, so nothing on *this* machine holds the file.
+            if current.alive:
-            # On a host that still leaves one case open: a data directory shared with
+                raise LockHeld(current)
-            # another machine, whose flock we cannot trust. Believe its record rather
+            # Stale: its process is gone. Take over, and say so.
-            # than run two writers. In a container the data volume is local by
+            self.path.unlink(missing_ok=True)
            # construction (US08-03), and a foreign hostname is only a dead container.
            fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
            handle.close()
            raise LockHeld(current)
        mine = Holder(
            role=self.role,
@@ -227,14 +192,15 @@ class LibraryLock:
            started_at=_now().isoformat(),
            library_roots=tuple(str(root) for root in self._config.library_roots),
        )
        self.path.parent.mkdir(parents=True, exist_ok=True)
        payload = {k: v for k, v in mine.as_dict().items() if k != "alive"}
-        handle.seek(0)
+        # Exclusive create, so two processes racing here cannot both believe they won.
-        handle.truncate()
+        try:
-        json.dump(payload, handle, indent=2)
+            with open(self.path, "x", encoding="utf-8") as handle:
-        handle.flush()
+                json.dump(payload, handle, indent=2)
-        # Held open on purpose: closing it is what releases the lock, and that must
+        except FileExistsError:
-        # happen when this process ends, not when this method returns.
+            winner = self.holder()
-        self._handle = handle
+            raise LockHeld(winner or mine) from None
        self._acquired = True
        return mine
@@ -242,10 +208,9 @@ class LibraryLock:
        """Give up a lock this process owns. Another holder's lock is left alone."""
        if not self._acquired:
            return
-        self.path.unlink(missing_ok=True)
+        current = self.holder()
-        if self._handle is not None:
+        if current is not None and current.pid == os.getpid():
-            self._handle.close()  # closing the descriptor releases the kernel lock
+            self.path.unlink(missing_ok=True)
            self._handle = None
        self._acquired = False
    def __enter__(self) -> "LibraryLock":
--- a/photo_pipeline/services/diagnostics.py
+++ b/photo_pipeline/services/diagnostics.py
@@ -15,13 +15,10 @@ application.
 from __future__ import annotations
 import functools
 import json
 import shutil
 from pathlib import Path
 from photo_pipeline.config import Config
 from photo_pipeline.integrations import exiftool, immich_go
 from photo_pipeline.services import app_lock
 # Below this much free space, mutating stages should stop rather than risk a
@@ -29,12 +26,6 @@ from photo_pipeline.services import app_lock
 LOW_DISK_BYTES = 1_000_000_000
 CRITICAL_DISK_BYTES = 200_000_000
 # Written into the container image at build time (US08-02). The image pins exiftool
 # and immich-go, and this file is how a running container reports which versions it
 # was built with — so a drifted or missing binary is visible here rather than in a
 # failed EXIF checkpoint or a misparsed upload report.
 IMAGE_VERSIONS_FILE = Path("/etc/photo-pipeline/versions.json")
 def _tree_bytes(path: Path) -> int:
    if not path.exists():
@@ -78,47 +69,8 @@ def disk(path: Path) -> dict:
    }
 def _pinned_versions() -> dict[str, str]:
    """The versions this image recorded at build time; empty outside a container."""
    try:
        recorded = json.loads(IMAGE_VERSIONS_FILE.read_text())
    except (OSError, ValueError):
        return {}
    if not isinstance(recorded, dict):
        return {}
    return {str(name): str(value) for name, value in recorded.items()}
@functools.lru_cache(maxsize=4)
 def _uploader_version(binary: str) -> str | None:
    """Cached: the uploader cannot change version inside one process."""
    return immich_go.version(binary)
 def tools(config: Config) -> list[dict]:
    """The external executables the pipeline shells out to, and their versions.
    ``pinned`` is what the image was built against, ``version`` is what is actually
    installed. They differ only when the binary was replaced or mounted over.
    """
    return [
        {
            "name": "exiftool",
            "path": exiftool.find_binary(),
            "version": exiftool.version(),
            "pinned": _pinned_versions().get("exiftool"),
        },
        {
            "name": "immich-go",
            "path": immich_go.find_binary(config.immich_go_binary),
            "version": _uploader_version(config.immich_go_binary),
            "pinned": _pinned_versions().get("immich-go"),
        },
    ]
 def report(config: Config) -> dict:
-    """Sizes, disk headroom, tool versions, warnings, and who holds the library lock."""
+    """Sizes, disk headroom, warnings, and who currently holds the library lock."""
    database = config.database_path
    components = [
        _component("database", database),
@@ -180,23 +132,6 @@ def report(config: Config) -> dict:
            }
        )
    installed_tools = tools(config)
    for tool in installed_tools:
        # A missing tool is reported as ``version: null`` rather than warned about: on a
        # development machine the uploader is legitimately absent, and the stages that
        # need it already refuse to run. A *drifted* tool is different — the image pinned
        # a version and something replaced it.
        if tool["version"] and tool["pinned"] and tool["pinned"] not in tool["version"]:
            warnings.append(
                {
                    "code": "tool_version_drift",
                    "message": (
                        f"{tool['name']} reports {tool['version']} but this image pinned "
                        f"{tool['pinned']}"
                    ),
                }
            )
    locks = {}
    for role in ("api", "worker"):
        holder = app_lock.LibraryLock(config, role).holder()
@@ -216,7 +151,6 @@ def report(config: Config) -> dict:
        "components": components,
        "total_bytes": sum(component["bytes"] for component in components),
        "disk": space,
        "tools": installed_tools,
        "warnings": warnings,
        "locks": locks,
        "legacy_activity": legacy,
--- a/photo_pipeline/services/release.py
+++ b/photo_pipeline/services/release.py
@@ -49,39 +49,8 @@ STAGES: tuple[tuple[str, tuple[str, ...]], ...] = (
    ("browser", ("tests/e2e",)),
 )
-# Skips the gate accepts, because they describe the machine rather than the code. The
+# Skips the gate accepts, because they describe the machine rather than the code.
-# container ones (US08-02) belong here for the same reason exiftool does: the image
+ALLOWED_SKIP_REASONS = ("exiftool not installed", "root ignores directory permissions")
 # build needs a Docker daemon and the network, and its definition is still checked
 # offline in tests/integration/test_container_image.py.
 ALLOWED_SKIP_REASONS = (
    "exiftool not installed",
    "root ignores directory permissions",
    "no Docker daemon available",
    "bind-mount ownership is virtualised",
 )
 # The container acceptance gate (US08-05): the deployed application, verified the way
 # the host application is. Deliberately one stage selected by marker, so adding a
 # phase_h test is enough to put it in front of a deploy.
 CONTAINER_STAGES: tuple[tuple[str, tuple[str, ...]], ...] = (
    ("container", ("tests/e2e", "-m", "phase_h")),
 )
 # Nothing. This gate exists to prove the *deployed* runtime, and every reason a check
 # would skip here — no daemon, no compose, no browser — means it was not proven.
 CONTAINER_ALLOWED_SKIP_REASONS: tuple[str, ...] = ()
 # The documentation gate (US09-05): the manuals, held to the application. Selected by
 # marker across the whole suite, because each check lives beside what it describes —
 # the offline contracts under tests/integration, the browser and screenshot journeys
 # under tests/e2e. Adding a phase_i test is enough to put it in front of a release.
 DOCS_STAGES: tuple[tuple[str, tuple[str, ...]], ...] = (
    ("documentation", ("tests", "-m", "phase_i")),
 )
 # Also nothing. Every check here is either offline or needs the browser the rest of
 # the suite already needs, so a skip means the manuals were not compared with the code.
 DOCS_ALLOWED_SKIP_REASONS: tuple[str, ...] = ()
 class ReleaseError(RuntimeError):
@@ -198,15 +167,13 @@ def _run_stage(label: str, paths: tuple[str, ...], *, repo: Path, log_dir: Path)
    return StageResult(label, command, result.returncode, elapsed, summary, skipped)
-def unexpected_skips(
+def unexpected_skips(results: list[StageResult]) -> list[str]:
    results: list[StageResult], allowed: tuple[str, ...] = ALLOWED_SKIP_REASONS
 ) -> list[str]:
    """Skips the gate will not accept: everything but the documented environment ones."""
    return [
        line
        for result in results
        for line in result.skipped
-        if not any(reason in line for reason in allowed)
+        if not any(reason in line for reason in ALLOWED_SKIP_REASONS)
    ]
@@ -215,7 +182,6 @@ def run_gate(
    *,
    output: Path | str | None = None,
    stages: tuple[tuple[str, tuple[str, ...]], ...] = STAGES,
    allowed_skips: tuple[str, ...] = ALLOWED_SKIP_REASONS,
    repo: Path | None = None,
 ) -> dict:
    """Run every suite in an isolated stack and retain checksummed evidence.
@@ -232,14 +198,13 @@ def run_gate(
    logs = directory / "logs"
    logs.mkdir(parents=True, exist_ok=True)
    started_at = _now()
    matrix = story_matrix(repo)
    results = [_run_stage(label, paths, repo=repo, log_dir=logs) for label, paths in stages]
-    skips = unexpected_skips(results, allowed_skips)
+    skips = unexpected_skips(results)
    report = {
        "schema_version": SCHEMA_VERSION,
-        "started_at": started_at.isoformat(),
+        "started_at": _now().isoformat(),
        "revision": revision(),
        "python": sys.version.split()[0],
        "platform": os.uname().sysname,
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -24,9 +24,6 @@ test = [
    "httpx>=0.27",
    "playwright>=1.40",
    "pytest-playwright>=0.4",
    # The composition and the workflows are configuration, and the tests that hold
    # them to their promises read them (US08-03, US08-04).
    "pyyaml>=6",
 ]
 [build-system]
@@ -52,7 +49,4 @@ markers = [
    "phase_d: Phase D end-to-end acceptance (US04-06) — guarded rename API, fault, and browser journeys",
    "phase_e: Phase E end-to-end acceptance (US05-06) — upload preflight, uploader, and browser journeys",
    "phase_f: Phase F end-to-end acceptance (US06-06) — archive destination, transfer, and restore journeys",
    "container: builds and runs the container image and its composition (US08-02, US08-03) — needs a Docker daemon, the compose plugin, and the network",
    "phase_h: Phase H container deployment acceptance (US08-05) — the browser, upgrade, restart, and security journeys against the composed stack",
    "phase_i: Phase I documentation acceptance (US09-05) — the manuals checked against the application, in the browser and offline",
 ]
--- a/tests/e2e/_container_harness.py
+++ b/tests/e2e/_container_harness.py
@@ -1,260 +0,0 @@
 """The composed stack, as a fixture: build, provision, drive, destroy (US08-03/US08-05).
 Extracted from ``tests/e2e/test_compose_stack.py`` when the container acceptance gate
 needed the same stack under a different image, project, and library. One
 implementation, because two would drift on exactly the details that make a container
 test worth anything — the mount, the volume, the ports, and the teardown.
 Nothing here fakes anything below the process boundary: Docker builds the image,
 Compose starts the real containers, and every helper talks to them over HTTP or the
 Docker CLI.
 """
 from __future__ import annotations
 import os
 import shutil
 import socket
 import subprocess
 import tempfile
 import time
 from pathlib import Path
 import httpx
 import pytest
 from PIL import Image
 REPO = Path(__file__).resolve().parents[2]
 COMPOSE_FILE = REPO / "docker-compose.yml"
 CONTAINER_LIBRARY = "/library"
 READY_TIMEOUT_SECONDS = 180
 JOB_TIMEOUT_SECONDS = 300
 UP_TIMEOUT_SECONDS = 30 * 60
 def compose_available() -> bool:
    try:
        return (
            subprocess.run(
                ["docker", "compose", "version"], capture_output=True, timeout=60
            ).returncode
            == 0
        )
    except (OSError, subprocess.SubprocessError):
        return False
 def free_port() -> int:
    with socket.socket() as sock:
        sock.bind(("127.0.0.1", 0))
        return sock.getsockname()[1]
 def mount_base() -> Path:
    """A directory a Docker VM shares with the host.
    Not pytest's ``tmp_path``: on macOS that is ``/var/folders/...``, which a Docker VM
    (Colima, Docker Desktop) does not share, so the bind mount would arrive empty and
    every assertion would be about nothing. ``$HOME`` is shared by every default
    configuration.
    """
    base = Path(
        os.environ.get("PHOTO_PIPELINE_TEST_MOUNT_BASE", Path.home() / ".cache" / "photo-pipeline")
    )
    base.mkdir(parents=True, exist_ok=True)
    return base
 def temporary_library(albums: dict[str, int], *, prefix: str = "library-") -> Path:
    """A fixture library on a shareable host path, with the exclusion sentinel in it."""
    root = Path(tempfile.mkdtemp(prefix=prefix, dir=mount_base()))
    for position, (album, count) in enumerate(albums.items()):
        (root / album).mkdir(parents=True, exist_ok=True)
        for index in range(count):
            # Distinct per album *and* index: two solid images of the same colour are
            # byte-identical, which would make them a duplicate cluster by accident.
            colour = (17 + 7 * index, 31 + 29 * position, 160 - 3 * index)
            Image.new("RGB", (64, 48), colour).save(root / album / f"{album}_{index}.jpg")
    # Never discovered, counted, analyzed, or uploaded — asserted from outside it.
    (root / "_IGNORE").mkdir(exist_ok=True)
    Image.new("RGB", (32, 32), (0, 0, 0)).save(root / "_IGNORE" / "sentinel.jpg")
    return root
 def remove_library(root: Path) -> None:
    shutil.rmtree(root, ignore_errors=True)
 def write_env_file(path: Path, secret: str, extra: dict[str, str] | None = None) -> Path:
    """Configuration and secrets come from the environment, so a test writes its own
    file rather than borrowing the operator's ``.env``."""
    lines = [
        f"PHOTO_PIPELINE_ACCESS_SECRET={secret}",
        "PHOTO_PIPELINE_LOG_FORMAT=text",
        # The deterministic vision seam, in the data volume so both roles and the test
        # can read it (concept §18).
        "PHOTO_PIPELINE_FAKE_VISION_LOG=/data/vision.log",
        *(f"{key}={value}" for key, value in (extra or {}).items()),
    ]
    path.write_text("\n".join(lines) + "\n")
    return path
 class Stack:
    """The composition under test, plus the environment it was started with."""
    def __init__(
        self,
        library: Path,
        env_file: Path,
        *,
        project: str,
        image: str,
        secret: str,
    ) -> None:
        self.library = library
        self.project = project
        self.secret = secret
        self.port = free_port()
        self.base = f"http://127.0.0.1:{self.port}"
        # Compose reads the repository's own .env for substitution; the process
        # environment wins over it, so the test's values are the ones that apply.
        self.env = {
            **os.environ,
            "PHOTO_PIPELINE_IMAGE": image,
            "PHOTO_PIPELINE_ENV_FILE": str(env_file),
            "PHOTO_PIPELINE_LIBRARY_HOST_PATH": str(library),
            "PHOTO_PIPELINE_LIBRARY_ROOTS": CONTAINER_LIBRARY,
            "PHOTO_PIPELINE_PORT": str(self.port),
            "PHOTO_PIPELINE_UID": str(os.getuid()),
            "PHOTO_PIPELINE_GID": str(os.getgid()),
        }
    # ── the compose lifecycle ────────────────────────────────────────────────
    def compose(self, *args: str, check: bool = True, timeout: int = 300):
        result = subprocess.run(
            ["docker", "compose", "-p", self.project, "-f", str(COMPOSE_FILE), *args],
            capture_output=True,
            text=True,
            env=self.env,
            cwd=REPO,
            timeout=timeout,
        )
        if check and result.returncode != 0:
            raise AssertionError(
                f"docker compose {' '.join(args)} failed:\n{result.stdout}\n{result.stderr}\n"
                f"{self.compose('logs', '--tail', '80', check=False).stdout}"
            )
        return result
    def up(self, *extra: str) -> None:
        self.compose("up", "--detach", *extra, timeout=UP_TIMEOUT_SECONDS)
    def down(self, *, volumes: bool = True) -> None:
        self.compose(
            "down",
            *(("--volumes",) if volumes else ()),
            "--remove-orphans",
            check=False,
            timeout=300,
        )
    def use_image(self, image: str) -> None:
        """Point the composition at another tag — the upgrade path (US08-05)."""
        self.env["PHOTO_PIPELINE_IMAGE"] = image
    def logs(self, *services: str) -> str:
        result = self.compose("logs", *services, check=False)
        return result.stdout + result.stderr
    def wait_until_ready(self) -> None:
        deadline = time.monotonic() + READY_TIMEOUT_SECONDS
        while time.monotonic() < deadline:
            try:
                if httpx.get(f"{self.base}/api/v1/health/ready", timeout=5).status_code == 200:
                    return
            except httpx.HTTPError:
                pass
            time.sleep(0.5)
        raise AssertionError(f"the stack never became ready:\n{self.logs()}")
    # ── talking to it ────────────────────────────────────────────────────────
    def client(self) -> httpx.Client:
        """A browser that has loaded the app: session cookie in the jar, token in a
        header. The session belongs to the API process, so it is re-bootstrapped after
        every restart."""
        client = httpx.Client(base_url=f"{self.base}/api/v1", timeout=60)
        bootstrap = client.get("/session", headers={"X-Access-Secret": self.secret})
        assert bootstrap.status_code == 200, bootstrap.text
        client.headers["X-CSRF-Token"] = bootstrap.json()["csrf_token"]
        return client
 def await_job(client: httpx.Client, job_id: str, states=("succeeded",)) -> dict:
    deadline = time.monotonic() + JOB_TIMEOUT_SECONDS
    snapshot: dict = {}
    while time.monotonic() < deadline:
        response = client.get(f"/jobs/{job_id}")
        if response.status_code == 200:
            snapshot = response.json()
            if snapshot["state"] in states:
                return snapshot
        time.sleep(0.5)
    raise AssertionError(f"job {job_id} never reached {states}: {snapshot}")
 def build_image(tag: str, *, revision: str | None = None) -> str:
    """Build the application image; from a git revision's tree when one is named.
    ``revision`` is how the upgrade journey gets the *previous* version without a
    registry: the tree of that commit is the build context, so what it produces is the
    image that commit would have published.
    """
    if revision is None:
        subprocess.run(
            [
                "docker",
                "build",
                "--build-arg",
                f"UID={os.getuid()}",
                "--build-arg",
                f"GID={os.getgid()}",
                "-t",
                tag,
                str(REPO),
            ],
            check=True,
            timeout=UP_TIMEOUT_SECONDS,
        )
        return tag
    archive = subprocess.run(
        ["git", "archive", "--format=tar", revision],
        cwd=REPO,
        capture_output=True,
        check=True,
        timeout=300,
    ).stdout
    subprocess.run(
        [
            "docker",
            "build",
            "--build-arg",
            f"UID={os.getuid()}",
            "--build-arg",
            f"GID={os.getgid()}",
            "-t",
            tag,
            "-",
        ],
        input=archive,
        check=True,
        timeout=UP_TIMEOUT_SECONDS,
    )
    return tag
 needs_compose = pytest.mark.skipif(
    not compose_available(), reason="no Docker daemon with the compose plugin"
 )
--- a/tests/e2e/test_compose_stack.py
+++ b/tests/e2e/test_compose_stack.py
@@ -1,212 +0,0 @@
 """US08-03: the composition, actually composed.
 Nothing here is faked below the process boundary: Docker builds the image, Compose
 starts the migrate/API/worker containers against a temporary fixture library on a
 real bind mount, and every assertion is made over HTTP or against what the stack
 left in its data volume. The vision provider is the deterministic fake seam the
 other end-to-end suites use, because an upload of real photos to a real model is not
 what this story is about — the mount, the lock, the volume, and the restart are.
 The file contract (one API, one worker, migrations first, no committed values) is
 checked without a daemon in ``tests/integration/test_compose_runtime.py``; only the
 running proof needs Docker, and CI is where it runs unskipped (US08-04).
 The stack itself lives in ``tests/e2e/_container_harness.py``, shared with the
 container acceptance gate (US08-05).
 """
 from __future__ import annotations
 import json
 import sys
 from pathlib import Path
 import pytest
 from tests.e2e._container_harness import (
    CONTAINER_LIBRARY,
    Stack,
    await_job,
    compose_available,
    needs_compose,
    remove_library,
    temporary_library,
    write_env_file,
 )
 PROJECT = "photo-pipeline-us0803"
 IMAGE = "photo-pipeline-test:us08-03"
 SECRET = "compose-acceptance-secret"
 pytestmark = pytest.mark.container
@pytest.fixture(scope="module")
 def library() -> Path:
    root = temporary_library({"01_day": 2, "02_night": 1})
    try:
        yield root
    finally:
        remove_library(root)
@pytest.fixture(scope="module")
 def env_file(tmp_path_factory) -> Path:
    return write_env_file(tmp_path_factory.mktemp("config") / "compose.env", SECRET)
@pytest.fixture(scope="module")
 def stack(library, env_file):
    if not compose_available():
        pytest.skip("no Docker daemon with the compose plugin")
    running = Stack(library, env_file, project=PROJECT, image=IMAGE, secret=SECRET)
    running.down()
    running.up("--build")
    try:
        running.wait_until_ready()
        yield running
    finally:
        running.down()
 # ── the mounted library ──────────────────────────────────────────────────────
@needs_compose
 def test_the_stack_scans_the_bind_mounted_library_at_its_container_paths(stack):
    client = stack.client()
    try:
        scanned = client.post("/inventory/scan")
        assert scanned.status_code == 200, scanned.text
        assets = client.get("/inventory/assets", params={"limit": 200}).json()["items"]
    finally:
        client.close()
    assert len(assets) == 3, assets
    paths = {asset["current_path"] for asset in assets}
    assert all(path.startswith(CONTAINER_LIBRARY + "/") for path in paths), paths
    assert not any("_IGNORE" in path or "sentinel" in path for path in paths)
    # The host paths are what the operator mounted, and they are not what the
    # application records: the roots are the container's.
    assert not any(str(stack.library) in path for path in paths)
@needs_compose
 def test_a_library_root_that_is_not_mounted_is_refused_at_startup(stack):
    """The container-specific failure: configured roots that name nothing mounted."""
    refused = stack.compose(
        "run",
        "--rm",
        "--no-deps",
        "--env",
        "PHOTO_PIPELINE_LIBRARY_ROOTS=/srv/photos",
        "api",
        "serve",
        check=False,
    )
    assert refused.returncode == 5, refused.stdout + refused.stderr
    assert "library root /srv/photos" in refused.stdout + refused.stderr
@needs_compose
 def test_a_second_worker_is_refused_by_the_library_lock(stack):
    """Not by convention: the running worker's lock is in the shared data volume."""
    refused = stack.compose(
        "run", "--rm", "--no-deps", "worker", "worker", "--id", "worker-2", check=False
    )
    assert refused.returncode == 2, refused.stdout + refused.stderr
    assert "worker is already running" in refused.stdout + refused.stderr
 # ── restart, resume, and the data volume ─────────────────────────────────────
@needs_compose
 def test_a_queued_job_resumes_after_both_containers_restart(stack):
    client = stack.client()
    try:
        client.post("/inventory/scan").raise_for_status()
        assets = client.get("/inventory/assets", params={"limit": 200}).json()["items"]
        for asset in assets:
            decided = client.post(
                "/safety/decisions", json={"asset_id": asset["id"], "decision": "sfw"}
            )
            assert decided.status_code == 200, decided.text
        # Stop the worker first, so the job is provably still queued when the restart
        # happens: a job that finished before the restart would prove nothing.
        stack.compose("stop", "worker")
        job = client.post("/analysis/jobs").json()
        assert client.get(f"/jobs/{job['id']}").json()["state"] == "queued"
    finally:
        client.close()
    stack.compose("restart", "api", "worker")
    stack.wait_until_ready()
    client = stack.client()  # the session is per API process, so it is re-bootstrapped
    try:
        finished = await_job(client, job["id"])
        assert finished["state"] == "succeeded", finished
        # The database is intact and the work is durable, not merely reported.
        after = client.get("/inventory/assets", params={"limit": 200}).json()["items"]
        assert {asset["id"] for asset in after} == {asset["id"] for asset in assets}
        analysed = client.get(f"/analysis/results/{assets[0]['id']}")
        assert analysed.status_code == 200, analysed.text
        assert analysed.json()["description"]
        # Only the mounted library's own photos were analysed: the sentinel under
        # _IGNORE is not an asset, so it can never have become an item of this job.
        assert finished["progress"]["total"] == len(assets)
    finally:
        client.close()
@needs_compose
 def test_the_data_volume_survives_recreating_the_containers(stack):
    """`down` without `--volumes` then `up` is the upgrade path: state stays."""
    client = stack.client()
    try:
        client.post("/inventory/scan").raise_for_status()
        before = {a["id"] for a in client.get("/inventory/assets").json()["items"]}
    finally:
        client.close()
    stack.down(volumes=False)
    stack.up()
    stack.wait_until_ready()
    client = stack.client()
    try:
        after = {a["id"] for a in client.get("/inventory/assets").json()["items"]}
    finally:
        client.close()
    assert after == before, "the same assets, from the same database, on the same volume"
 # ── operating it ─────────────────────────────────────────────────────────────
@needs_compose
 def test_backup_verify_and_diagnostics_run_as_container_commands(stack):
    backup = stack.compose("run", "--rm", "--no-deps", "api", "backup", "--reason", "compose")
    manifest = json.loads(backup.stdout[backup.stdout.index("{") :])
    assert manifest["name"].startswith("2")
    verified = stack.compose(
        "run", "--rm", "--no-deps", "api", "verify-backup", f"/data/backups/{manifest['name']}"
    )
    assert json.loads(verified.stdout[verified.stdout.index("{") :])["ok"] is True
    report = stack.compose("run", "--rm", "--no-deps", "api", "diagnostics")
    diagnostics = json.loads(report.stdout[report.stdout.index("{") :])
    components = {c["name"]: c["path"] for c in diagnostics["components"]}
    # Database, WAL, thumbnail cache, and backups all live in the mounted volume.
    for name in ("database", "write_ahead_log", "thumbnail_cache", "backups"):
        assert components[name].startswith("/data/"), (name, components[name])
    assert {tool["name"] for tool in diagnostics["tools"]} >= {"exiftool", "immich-go"}
    # And the worker running beside this command is visible as the lock's holder.
    assert diagnostics["locks"]["worker"]["role"] == "worker"
 if __name__ == "__main__":  # a quick way to run just this file
    raise SystemExit(pytest.main([__file__, "-v", *sys.argv[1:]]))
--- a/tests/e2e/test_container_runtime.py
+++ b/tests/e2e/test_container_runtime.py
@@ -1,306 +0,0 @@
 """US08-02: the built image, actually built and actually run.
 This is the acceptance test for the image itself, so nothing here is faked: Docker
 builds from a clean context, the container starts under a chosen UID/GID against a
 mounted data directory, and the assertions are made over HTTP and against the files
 the container left on the host.
 It is skipped without a Docker daemon — the build also needs the network for the base
 image, the pinned exiftool package, and the pinned uploader release. The contract the
 Dockerfile itself has to keep (pins, non-root, health target, build context) is checked
 offline in ``tests/integration/test_container_image.py``, so a machine without Docker
 still fails on a broken image definition; only the running proof needs the daemon. CI
 builds the image on every change (US08-04), which is where this runs unskipped.
 """
 from __future__ import annotations
 import json
 import os
 import platform
 import re
 import socket
 import subprocess
 import sys
 import time
 from pathlib import Path
 import httpx
 import pytest
 REPO = Path(__file__).resolve().parents[2]
 IMAGE = "photo-pipeline-test:us08-02"
 SECRET = "container-acceptance-secret"
 HOSTNAME = "photos.test"
 READY_TIMEOUT_SECONDS = 120
 BUILD_TIMEOUT_SECONDS = 30 * 60
 pytestmark = pytest.mark.container
 def docker_available() -> bool:
    try:
        return subprocess.run(["docker", "info"], capture_output=True, timeout=60).returncode == 0
    except (OSError, subprocess.SubprocessError):
        return False
 needs_docker = pytest.mark.skipif(not docker_available(), reason="no Docker daemon available")
 def docker(*args: str, check: bool = True, timeout: int = 120) -> subprocess.CompletedProcess:
    result = subprocess.run(
        ["docker", *args], capture_output=True, text=True, timeout=timeout
    )
    if check and result.returncode != 0:
        raise AssertionError(f"docker {' '.join(args)} failed:\n{result.stdout}\n{result.stderr}")
    return result
 def pins() -> dict[str, str]:
    """The pinned versions, read from the Dockerfile that produced the image."""
    text = (REPO / "Dockerfile").read_text()
    found = dict(re.findall(r"^ARG\s+([A-Z0-9_]+)=(.+)$", text, re.MULTILINE))
    return {
        # The Debian package version carries a packaging suffix; exiftool reports the
        # upstream version only.
        "exiftool": found["EXIFTOOL_VERSION"].split("+")[0].split("-")[0],
        "immich-go": found["IMMICH_GO_VERSION"],
    }
 def free_port() -> int:
    with socket.socket() as sock:
        sock.bind(("127.0.0.1", 0))
        return sock.getsockname()[1]
@pytest.fixture(scope="module")
 def image() -> str:
    """Build from a clean checkout: the build context is the repository, unmodified."""
    if not docker_available():
        pytest.skip("no Docker daemon available")
    docker(
        "build",
        "--build-arg",
        f"UID={os.getuid()}",
        "--build-arg",
        f"GID={os.getgid()}",
        "-t",
        IMAGE,
        str(REPO),
        timeout=BUILD_TIMEOUT_SECONDS,
    )
    return IMAGE
@pytest.fixture
 def data_dir(tmp_path) -> Path:
    data = tmp_path / "data"
    data.mkdir()
    return data
 def run_detached(image: str, port: int, *args: str, data: Path | None = None) -> str:
    """Start a container. ``data`` bind-mounts the host's data directory when the test
    is about the files themselves; otherwise the image's own /data is used, because a
    macOS bind mount arrives with an ownership the container did not choose."""
    result = docker(
        "run",
        "--detach",
        "--rm",
        "--publish",
        f"127.0.0.1:{port}:8000",
        *(("--volume", f"{data}:/data") if data is not None else ()),
        "--env",
        # Reachable from outside the container means reachable from another machine as
        # far as the application is concerned, so the access secret is mandatory
        # (US08-01) — the image must not weaken that.
        "PHOTO_PIPELINE_HOST=0.0.0.0",
        "--env",
        f"PHOTO_PIPELINE_ACCESS_SECRET={SECRET}",
        "--env",
        f"PHOTO_PIPELINE_ALLOWED_HOSTS={HOSTNAME}",
        image,
        *args,
    )
    return result.stdout.strip()
 def wait_until_ready(base: str, container: str) -> None:
    deadline = time.monotonic() + READY_TIMEOUT_SECONDS
    while time.monotonic() < deadline:
        try:
            if httpx.get(f"{base}/api/v1/health/ready", timeout=5).status_code == 200:
                return
        except httpx.HTTPError:
            pass
        if docker("inspect", "-f", "{{.State.Running}}", container, check=False).stdout.strip() in (
            "false",
            "",
        ):
            break
        time.sleep(0.5)
    logs = docker("logs", container, check=False)
    raise AssertionError(f"container never became ready:\n{logs.stdout}\n{logs.stderr}")
@pytest.fixture
 def serving(image):
    port = free_port()
    container = run_detached(image, port, "serve")
    try:
        base = f"http://127.0.0.1:{port}"
        wait_until_ready(base, container)
        yield base, container
    finally:
        docker("rm", "--force", container, check=False)
 def session(base: str) -> httpx.Client:
    client = httpx.Client(base_url=base, timeout=30)
    bootstrap = client.get("/api/v1/session", headers={"X-Access-Secret": SECRET})
    assert bootstrap.status_code == 200, bootstrap.text
    client.headers["X-CSRF-Token"] = bootstrap.json()["csrf_token"]
    return client
 # ── the image serves, and says what it contains ──────────────────────────────
@needs_docker
 def test_the_container_serves_the_frontend_and_the_pinned_tool_versions(serving):
    base, container = serving
    index = httpx.get(f"{base}/app/index.html", timeout=30)
    assert index.status_code == 200
    assert "<title" in index.text.lower(), "the application shell, not an API error"
    client = session(base)
    try:
        tools = {tool["name"]: tool for tool in client.get("/api/v1/diagnostics").json()["tools"]}
    finally:
        client.close()
    for name, pinned in pins().items():
        assert tools[name]["pinned"] == pinned, name
        # Recorded *and* installed: the reported version comes from running the binary.
        assert pinned in tools[name]["version"], (name, tools[name])
        assert tools[name]["path"], f"{name} is not on PATH inside the image"
    logs = docker("logs", container, check=False)
    assert SECRET not in logs.stdout + logs.stderr, "the access secret never reaches the log"
@needs_docker
 def test_the_declared_health_check_reports_readiness(serving):
    """The declared HEALTHCHECK is readiness, so Docker's own verdict is the assertion."""
    _, container = serving
    deadline = time.monotonic() + READY_TIMEOUT_SECONDS
    status = ""
    while time.monotonic() < deadline:
        status = docker(
            "inspect", "-f", "{{.State.Health.Status}}", container, check=False
        ).stdout.strip()
        if status == "healthy":
            break
        time.sleep(1)
    assert status == "healthy"
    probe = docker("exec", container, "/usr/local/bin/healthcheck.sh", check=False)
    assert probe.returncode == 0
    # Point the probe at a port nothing serves: the same script must fail, which is
    # what makes the healthy verdict above evidence rather than a default.
    unready = docker(
        "exec",
        "--env",
        "PHOTO_PIPELINE_PORT=1",
        container,
        "/usr/local/bin/healthcheck.sh",
        check=False,
    )
    assert unready.returncode != 0
 # ── identity: never root, always the configured owner ────────────────────────
@needs_docker
 def test_the_container_refuses_to_run_as_root(image, data_dir):
    result = docker(
        "run",
        "--rm",
        "--user",
        "0:0",
        "--volume",
        f"{data_dir}:/data",
        image,
        "diagnostics",
        check=False,
    )
    assert result.returncode != 0
    assert "refusing to run as root" in result.stderr + result.stdout
    assert not list(data_dir.iterdir()), "a refused container writes nothing"
@needs_docker
 def test_what_the_container_writes_is_owned_by_the_build_arguments(image):
    """The identity the image was built with is the identity on disk afterwards.
    Asserted from inside the container so it holds on every host: a macOS bind mount
    reports an ownership the container never chose. The host-side proof, which is what
    the mounted library actually needs, is the Linux test below.
    """
    port = free_port()
    container = run_detached(image, port, "serve")
    try:
        wait_until_ready(f"http://127.0.0.1:{port}", container)
        owner = docker(
            "exec", container, "stat", "-c", "%u:%g", "/data/photo_pipeline.db"
        ).stdout.strip()
        assert owner == f"{os.getuid()}:{os.getgid()}"
        assert docker("exec", container, "id", "-u").stdout.strip() == str(os.getuid())
    finally:
        docker("rm", "--force", container, check=False)
@needs_docker
@pytest.mark.skipif(
    platform.system() != "Linux",
    reason="bind-mount ownership is virtualised by Docker Desktop on macOS/Windows",
 )
 def test_files_the_container_writes_keep_the_configured_ownership(image, data_dir):
    docker("run", "--rm", "--volume", f"{data_dir}:/data", image, "migrate", timeout=300)
    written = sorted(path for path in data_dir.rglob("*") if path.is_file())
    assert written, "migrate creates the database in the mounted data directory"
    for path in written:
        assert (path.stat().st_uid, path.stat().st_gid) == (os.getuid(), os.getgid()), path
@needs_docker
 def test_the_worker_role_runs_from_the_same_image(image, data_dir):
    """One image, two roles: the worker is the same entrypoint with another argument."""
    port = free_port()
    container = run_detached(image, port, "worker", "--id", "container-worker")
    try:
        # Taking the worker's library lock is the observable proof that it started,
        # migrated, and reached its job loop — no sleep required (US07-05).
        deadline = time.monotonic() + READY_TIMEOUT_SECONDS
        lock = ""
        while not lock and time.monotonic() < deadline:
            assert docker("inspect", "-f", "{{.State.Running}}", container).stdout.strip() == (
                "true"
            ), docker("logs", container, check=False).stdout
            lock = docker("exec", container, "cat", "/data/worker.lock.json", check=False).stdout
            time.sleep(0.5)
        assert lock, docker("logs", container, check=False).stdout
        assert json.loads(lock)["role"] == "worker"
        role = docker("exec", container, "cat", "/tmp/photo-pipeline-role").stdout.strip()
        assert role == "worker", "the health check can tell which role this container is"
    finally:
        docker("rm", "--force", container, check=False)
 if __name__ == "__main__":  # a quick way to run just this file
    raise SystemExit(pytest.main([__file__, "-v", *sys.argv[1:]]))
--- a/tests/e2e/test_docs_ui.py
+++ b/tests/e2e/test_docs_ui.py
@@ -1,152 +0,0 @@
 """US09-01: the manuals, in the browser, under the application's real policy.
 Everything here runs against a real ``photo_pipeline serve`` process serving the
 committed ``docs/`` tree and the vendored renderer — no fixture markdown, no stubbed
 fetch. What that buys is the assertion the story actually cares about: the pages
 render, the links between them work, a diagram becomes a diagram, and the console
 stays empty, including of CSP violations.
 The offline contract — reachability, dead links, pinned checksums — is
 ``tests/integration/test_documentation.py``.
 """
 from __future__ import annotations
 from pathlib import Path
 import pytest
 from tests.e2e._pipeline_harness import Server, seed_library
 # Every check here belongs to the documentation gate (US09-05).
 pytestmark = pytest.mark.phase_i
@pytest.fixture(scope="module")
 def server(tmp_path_factory):
    seeded = seed_library(tmp_path_factory.mktemp("docs"), {"a": 1}, {})
    running = Server(seeded).start()
    try:
        yield running
    finally:
        running.stop()
@pytest.fixture
 def quiet(page):
    """Any console error, page error, or failed request fails the test that caused
    it. A CSP violation arrives as a console error, which is the point."""
    problems: list[str] = []
    page.on("console", lambda m: problems.append(m.text) if m.type == "error" else None)
    page.on("pageerror", lambda error: problems.append(str(error)))
    page.on("requestfailed", lambda request: problems.append(f"failed request: {request.url}"))
    yield problems
 def test_the_documentation_opens_from_the_navigation(page, server, quiet):
    page.goto(f"{server.base}/app/#/workflow")
    page.locator('nav a[data-nav="docs"]').click()
    page.get_by_test_id("doc").wait_for()
    assert page.get_by_test_id("doc").get_attribute("data-page") == "index"
    # The sidebar is the index's own reading order, not a second list to maintain.
    assert page.get_by_test_id("doc-pages").get_by_role("link", name="Overview").is_visible()
    assert quiet == []
 def test_a_link_between_documents_stays_inside_the_application(page, server, quiet):
    page.goto(f"{server.base}/app/#/docs")
    page.get_by_test_id("doc").wait_for()
    page.get_by_test_id("doc").get_by_role("link", name="Overview").click()
    page.wait_for_selector('[data-testid="doc"][data-page="overview"]')
    assert "#/docs?page=overview" in page.url, "a relative .md link must not leave the app"
    # And back again, by the link the document itself carries.
    page.get_by_test_id("doc").get_by_role("link", name="← Documentation index").click()
    page.wait_for_selector('[data-testid="doc"][data-page="index"]')
    assert quiet == []
 def test_a_deep_link_to_a_heading_lands_on_that_heading(page, server, quiet):
    page.goto(f"{server.base}/app/#/docs?page=overview&anchor=the-workflow")
    heading = page.locator("#the-workflow")
    heading.wait_for()
    assert heading.inner_text().strip() == "The workflow"
    assert heading.evaluate("node => node.getBoundingClientRect().top < window.innerHeight")
    assert quiet == []
 def test_a_mermaid_block_becomes_a_diagram_under_the_unchanged_script_policy(page, server, quiet):
    page.goto(f"{server.base}/app/#/docs?page=overview")
    diagram = page.get_by_test_id("diagram").first
    diagram.wait_for()
    # A real drawing, not the source text and not an error node.
    assert diagram.locator("svg").count() == 1
    assert diagram.evaluate("node => node.querySelector('svg').getBBox().width") > 100
    assert page.locator("pre code.language-mermaid").count() == 0
    assert quiet == [], "rendering a diagram must not violate the policy"
    policy = page.evaluate(
        "async () => (await fetch('/app/')).headers.get('content-security-policy')"
    )
    assert "script-src 'self';" in policy
    assert "unsafe-eval" not in policy
 def test_every_diagram_in_the_architecture_overview_draws(page, server, quiet):
    """Five diagrams, three of them state machines (US09-03). A mermaid block with a
    syntax error renders an error node instead of throwing, so a page that merely
    loaded proves nothing — count the drawings and read the source for the states."""
    source = (Path(__file__).resolve().parents[2] / "docs" / "architecture.md").read_text()
    expected = source.count("```mermaid")
    assert expected >= 5, "the overview lost its diagrams"
    page.goto(f"{server.base}/app/#/docs?page=architecture")
    page.get_by_test_id("diagram").first.wait_for()
    page.wait_for_function(
        "count => document.querySelectorAll('[data-testid=\"diagram\"] svg').length === count",
        arg=expected,
    )
    drawn = page.locator('[data-testid="diagram"] svg')
    assert drawn.count() == expected
    for index in range(expected):
        diagram = drawn.nth(index)
        # Labels may be <text> or HTML inside a <foreignObject> depending on the
        # diagram type, so ask for the rendered text rather than a specific element.
        labels = diagram.evaluate("node => node.textContent.trim().length")
        assert labels > 0, f"diagram {index} drew no labels"
        assert diagram.locator(".error-icon, .error-text").count() == 0, f"diagram {index} errored"
    assert page.locator("pre code.language-mermaid").count() == 0
    assert quiet == []
 def test_an_unknown_page_says_so_without_naming_a_path(page, server, quiet):
    page.goto(f"{server.base}/app/#/docs?page=no-such-manual")
    message = page.get_by_test_id("doc-not-found")
    message.wait_for()
    text = message.inner_text()
    assert "does not exist" in text
    assert "/" not in text.replace("Back to the documentation index", ""), text
    message.get_by_role("link").click()
    page.wait_for_selector('[data-testid="doc"][data-page="index"]')
    # The missing page is a 404 and the browser says so; nothing else may go wrong,
    # and in particular the view must not throw on the way to its own message.
    assert all("404" in problem for problem in quiet), quiet
 def test_the_documentation_is_readable_without_a_session(page, server, quiet):
    """The troubleshooting page is needed most by whoever is locked out."""
    page.goto(f"{server.base}/app/#/docs")
    page.get_by_test_id("doc").wait_for()
    unauthenticated = page.evaluate(
        """async () => {
             const response = await fetch('/docs/index.md', { credentials: 'omit' });
             return { status: response.status, length: (await response.text()).length };
           }"""
    )
    assert unauthenticated["status"] == 200
    assert unauthenticated["length"] > 100
--- a/tests/e2e/test_phase_h_container.py
+++ b/tests/e2e/test_phase_h_container.py
@@ -1,510 +0,0 @@
 """Phase H — the container acceptance gate (US08-05).
 The deployed application is verified the way the host application is: real image,
 real composition, real browser, real restarts. Everything below runs against
 containers that this suite provisions from the built image, against a temporary
 fixture library on a bind mount and an isolated data volume, and destroys afterwards.
 Four journeys, one per thing a deployment can get wrong:
 * **the browser journey** — discovery, duplicate review, analysis, album proposal,
  rename, upload preflight, and archive, driven through the containerized frontend;
 * **the upgrade journey** — the previous version's image runs first, then this one,
  and the database, its migrations, the rename journal, the job history, and the
  thumbnail cache have to still be there;
 * **the restart journey** — both containers are killed mid-job and the work resumes
  without doing anything twice;
 * **the security gates** — the refusals a loopback deployment made are still made
  behind a published port: no session, forged forwarded headers, a path that leaves
  the mounted library, and a secret in the logs.
 Run it as one command, with evidence: ``python -m photo_pipeline container-gate``.
 """
 from __future__ import annotations
 import collections
 from contextlib import closing
 import json
 import os
 import shutil
 import subprocess
 import sys
 import time
 from pathlib import Path
 import httpx
 import pytest
 from playwright.sync_api import expect
 from photo_pipeline.db import head_revision
 from tests.e2e._container_harness import (
    Stack,
    await_job,
    build_image,
    compose_available,
    needs_compose,
    remove_library,
    temporary_library,
    write_env_file,
 )
 pytestmark = [pytest.mark.phase_h, pytest.mark.container]
 PROJECT = "photo-pipeline-us0805"
 IMAGE = "photo-pipeline-test:us08-05"
 # The version being upgraded *from*. CI passes the tag it last published; without one,
 # the previous commit's tree is built, which is the same claim without a registry.
 PREVIOUS_IMAGE = os.environ.get("PHOTO_PIPELINE_PREVIOUS_IMAGE")
 PREVIOUS_TAG = "photo-pipeline-test:us08-05-previous"
 SECRET = "container-gate-access-secret"
 IMMICH_SENTINEL = "immich-sentinel-9f3a2b"
 HOSTNAME = "photos.test"
 ALBUM = "rome"
 RENAMED = "2019 Rome"
 BURST = 30
 # ── the image and the stacks ─────────────────────────────────────────────────
@pytest.fixture(scope="session")
 def image() -> str:
    if not compose_available():
        pytest.skip("no Docker daemon with the compose plugin")
    return build_image(IMAGE)
@pytest.fixture(scope="module")
 def journey(image, tmp_path_factory):
    """One album, one exact duplicate of a photo in it, and the exclusion sentinel."""
    library = temporary_library({ALBUM: 3}, prefix="us0805-journey-")
    shutil.copyfile(library / ALBUM / f"{ALBUM}_0.jpg", library / ALBUM / "copy.jpg")
    env_file = write_env_file(
        tmp_path_factory.mktemp("journey") / "gate.env",
        SECRET,
        {
            "PHOTO_PIPELINE_ALLOWED_HOSTS": HOSTNAME,
            # Configured but never reachable: the upload view's job here is to show the
            # preflight blockers, and the key's job is to be absent from every log.
            "PHOTO_PIPELINE_IMMICH_API_KEY": IMMICH_SENTINEL,
            "PHOTO_PIPELINE_IMMICH_SERVER_URL": "http://127.0.0.1:1",
        },
    )
    stack = Stack(library, env_file, project=f"{PROJECT}-journey", image=image, secret=SECRET)
    try:
        stack.down()
        stack.up()
        stack.wait_until_ready()
        _seed_journey(stack)
        yield stack
    finally:
        stack.down()
        remove_library(library)
 def _seed_journey(stack: Stack) -> None:
    """Everything the views need, established over the public API before they render."""
    with closing(stack.client()) as client:
        client.post("/inventory/scan").raise_for_status()
        client.post("/duplicates/detect").raise_for_status()
        queue = client.get("/safety/queue", params={"limit": 100}).json()["items"]
        for item in queue:
            decided = client.post(
                "/safety/decisions", json={"asset_id": item["asset_id"], "decision": "sfw"}
            )
            assert decided.status_code == 200, decided.text
        job = client.post("/analysis/jobs").json()
        await_job(client, job["id"])
        client.post("/albums/proposals", json={}).raise_for_status()
        # An archive destination inside the data volume: a second mount would prove
        # nothing more, and the view needs a location to have something to show.
        stack.compose("exec", "-T", "api", "mkdir", "-p", "/data/archive")
        client.post(
            "/archive-locations", json={"name": "external", "root": "/data/archive"}
        ).raise_for_status()
 # ── the browser journey ──────────────────────────────────────────────────────
@needs_compose
 def test_the_browser_journey_covers_every_stage_view_of_the_deployed_app(page, journey):
    """One pass through the deployed frontend, in workflow order.
    The access secret is supplied the way a person supplies it — the app asks, the
    answer is kept for the tab — so what is proven is the authenticated deployment,
    not a test-only bypass.
    """
    page.on("dialog", lambda dialog: dialog.accept(SECRET))
    errors: list[str] = []
    page.on("pageerror", lambda error: errors.append(str(error)))
    base = journey.base
    with closing(journey.client()) as client:
        cluster = client.get("/duplicates/clusters").json()["items"][0]
    # ── discovery ────────────────────────────────────────────────────────────
    page.goto(f"{base}/app/#/workflow")
    page.get_by_test_id("stage-safety").wait_for()
    expect(page.get_by_test_id("stage-analysis")).to_be_visible()
    page.goto(f"{base}/app/#/inventory")
    rows = page.get_by_test_id("asset-row")
    rows.first.wait_for()
    assert rows.count() == 4, "three photos and the duplicate copy; never the sentinel"
    assert "sentinel" not in page.content() and "_IGNORE" not in page.content()
    # ── duplicate review ─────────────────────────────────────────────────────
    page.goto(f"{base}/app/#/duplicates/{cluster['id']}")
    page.get_by_test_id("cluster-state").wait_for()
    # Exact bytes: the cluster arrives decided, and the review surface has to show
    # both members and the evidence the decision was made on.
    expect(page.get_by_test_id("cluster-state")).to_contain_text("decided")
    expect(page.get_by_test_id("member")).to_have_count(2)
    expect(page.get_by_test_id("member").first).to_contain_text("/library/")
    # ── analysis ─────────────────────────────────────────────────────────────
    page.goto(f"{base}/app/#/analyze")
    page.get_by_test_id("analyze-counts").wait_for()
    expect(page.get_by_test_id("run-analysis")).to_be_visible()
    # ── album proposal ───────────────────────────────────────────────────────
    page.goto(f"{base}/app/#/albums?album={ALBUM}")
    page.get_by_test_id("suggested-name").wait_for()
    page.get_by_test_id("final-name").fill(RENAMED)
    page.get_by_test_id("save-name").click()
    page.get_by_test_id("approve").click()
    expect(page.get_by_test_id("proposal-status")).to_contain_text("approved")
    # ── rename, applied against the bind mount ───────────────────────────────
    page.goto(f"{base}/app/#/renames")
    page.get_by_test_id("build-plan").click()
    page.get_by_test_id("operations").wait_for()
    expect(page.get_by_test_id("op-destination").first).to_contain_text(RENAMED)
    page.get_by_test_id("apply-plan").click()
    expect(page.get_by_test_id("apply-result")).to_contain_text("Applied 1, failed 0")
    # The mounted library is the host's directory: the container renamed the operator's
    # folder, not a copy inside its own layer.
    assert (journey.library / RENAMED).is_dir()
    assert not (journey.library / ALBUM).exists()
    # ── upload preflight ─────────────────────────────────────────────────────
    page.goto(f"{base}/app/#/uploads")
    page.get_by_test_id("upload-scope").wait_for()
    expect(page.get_by_test_id("album-row").first).to_be_visible()
    assert IMMICH_SENTINEL not in page.content(), "the API key never reaches the browser"
    # ── archive ──────────────────────────────────────────────────────────────
    page.goto(f"{base}/app/#/archive")
    page.get_by_test_id("archive-locations").wait_for()
    expect(page.get_by_test_id("location-row").first).to_contain_text("external")
    assert errors == [], f"the deployed frontend raised page errors: {errors}"
 # ── the upgrade journey ──────────────────────────────────────────────────────
@pytest.fixture(scope="module")
 def previous_image(image) -> str:
    """The image the deployment is upgrading *from*.
    The published tag when there is one. Before the first publish there is nothing to
    pull, and refusing then would mean the gate could never let the first deploy
    through — so the previous commit's tree is built instead, which is the same claim
    without a registry.
    """
    if PREVIOUS_IMAGE:
        pulled = subprocess.run(
            ["docker", "pull", PREVIOUS_IMAGE], capture_output=True, timeout=1800
        )
        if pulled.returncode == 0:
            return PREVIOUS_IMAGE
    return build_image(PREVIOUS_TAG, revision="HEAD~1")
@needs_compose
 def test_an_upgrade_keeps_the_database_the_journal_the_jobs_and_the_cache(
    image, previous_image, tmp_path_factory
 ):
    library = temporary_library({ALBUM: 2}, prefix="us0805-upgrade-")
    env_file = write_env_file(tmp_path_factory.mktemp("upgrade") / "gate.env", SECRET)
    stack = Stack(
        library, env_file, project=f"{PROJECT}-upgrade", image=previous_image, secret=SECRET
    )
    try:
        stack.down()
        stack.up()
        stack.wait_until_ready()
        # ── what the previous version leaves behind ──────────────────────────
        with closing(stack.client()) as client:
            client.post("/inventory/scan").raise_for_status()
            assets = client.get("/inventory/assets", params={"limit": 200}).json()["items"]
            for item in client.get("/safety/queue", params={"limit": 100}).json()["items"]:
                client.post(
                    "/safety/decisions", json={"asset_id": item["asset_id"], "decision": "sfw"}
                ).raise_for_status()
            job = client.post("/analysis/jobs").json()
            finished = await_job(client, job["id"])
            for asset in assets:  # populate the thumbnail cache
                thumbnail = client.get(f"/assets/{asset['id']}/thumbnail", params={"size": 256})
                assert thumbnail.status_code == 200, thumbnail.text
            # A rename plan, left unapplied: the journal has to survive the upgrade
            # exactly as it was, or a half-applied one could not be recovered.
            client.post("/albums/proposals", json={}).raise_for_status()
            _approve(client, RENAMED)
            plan = client.post("/rename-plans").json()
        before = {
            "assets": sorted(asset["id"] for asset in assets),
            "job": finished["progress"],
            "plan": (plan["id"], plan["checksum"]),
            "thumbnails": _cache_files(stack),
            "revision": _revision(stack),
        }
        assert before["thumbnails"], "no thumbnail was cached, so nothing would be proven"
        # ── the upgrade: same volume, new image ──────────────────────────────
        stack.down(volumes=False)
        stack.use_image(image)
        stack.up()
        stack.wait_until_ready()
        after_revision = _revision(stack)
        assert after_revision == head_revision(), "the new image did not migrate the volume"
        if after_revision != before["revision"]:
            # A schema change is snapshotted before it is applied (US07-05), so a
            # failed upgrade is restorable rather than a lost library.
            assert _ls(stack, "/data/backups"), "a migration ran without a backup"
        with closing(stack.client()) as client:
            assets = client.get("/inventory/assets", params={"limit": 200}).json()["items"]
            assert sorted(asset["id"] for asset in assets) == before["assets"]
            assert client.get(f"/jobs/{job['id']}").json()["progress"] == before["job"]
            plans = client.get("/rename-plans").json()["items"]
            assert (plans[0]["id"], plans[0]["checksum"]) == before["plan"]
            for asset in assets:
                assert (
                    client.get(f"/analysis/results/{asset['id']}").status_code == 200
                ), "an analysis result did not survive the upgrade"
        # The cache is keyed by pixel hash and thumbnail version, so an upgrade that
        # kept the volume must keep the files: regenerating them is work nobody asked
        # for, and losing them silently is how a cache stops being one.
        assert set(before["thumbnails"]) <= set(_cache_files(stack))
    finally:
        stack.down()
        remove_library(library)
 def _approve(client: httpx.Client, name: str, *, album: str = ALBUM) -> None:
    for payload, route in (({"name": name}, "edit"), ({}, "approve")):
        current = client.get(f"/albums/proposals/{album}").json()
        client.post(
            f"/albums/proposals/{album}/{route}",
            json={**payload, "expected_version": current["version"]},
        ).raise_for_status()
 def _exec(stack: Stack, *args: str) -> str:
    return stack.compose("exec", "-T", "api", *args).stdout
 def _ls(stack: Stack, directory: str) -> list[str]:
    listing = stack.compose("exec", "-T", "api", "ls", directory, check=False)
    return [line for line in listing.stdout.split() if line]
 def _cache_files(stack: Stack) -> list[str]:
    return sorted(
        _exec(stack, "find", "/data/cache", "-type", "f", "-name", "*.webp").split()
    )
 def _revision(stack: Stack) -> str:
    """The schema revision the volume's database is actually at."""
    return _exec(
        stack,
        "python",
        "-c",
        "import sqlite3;print(sqlite3.connect('/data/photo_pipeline.db')"
        ".execute('select version_num from alembic_version').fetchone()[0])",
    ).strip()
 # ── the restart journey ──────────────────────────────────────────────────────
@needs_compose
 def test_killing_both_containers_mid_job_resumes_without_doing_anything_twice(
    image, tmp_path_factory
 ):
    """`docker kill` is the honest restart: no grace period, no orderly stop, no
    chance for either process to write a tidy final state."""
    library = temporary_library({"burst": BURST}, prefix="us0805-restart-")
    env_file = write_env_file(tmp_path_factory.mktemp("restart") / "gate.env", SECRET)
    stack = Stack(library, env_file, project=f"{PROJECT}-restart", image=image, secret=SECRET)
    try:
        stack.down()
        stack.up()
        stack.wait_until_ready()
        with closing(stack.client()) as client:
            client.post("/inventory/scan").raise_for_status()
            assets = client.get("/inventory/assets", params={"limit": 200}).json()["items"]
            assert len(assets) == BURST
            for item in client.get("/safety/queue", params={"limit": 100}).json()["items"]:
                client.post(
                    "/safety/decisions", json={"asset_id": item["asset_id"], "decision": "sfw"}
                ).raise_for_status()
            job = client.post("/analysis/jobs").json()
            progress = _wait_for_progress(client, job["id"])
        assert 0 < progress["done"] < progress["total"], progress
        stack.compose("kill", "api", "worker")
        stack.up()
        stack.wait_until_ready()
        with closing(stack.client()) as client:
            finished = await_job(client, job["id"])
            assert finished["progress"]["done"] == BURST, finished
            results = [
                client.get(f"/analysis/results/{asset['id']}").json() for asset in assets
            ]
        # Exactly one stored result per asset: at-least-once execution, idempotent
        # recovery — a retried item overwrites its own attempt, it does not add one.
        assert len(results) == BURST
        assert all(result["description"] for result in results)
        # And the side effect nobody can take back — the call to the provider — happened
        # again only for whatever was in flight when the containers died.
        analysed = collections.Counter(_exec(stack, "cat", "/data/vision.log").split())
        assert len(analysed) == BURST, "every photo was analysed, and only the library's"
        assert max(analysed.values()) <= 2, dict(analysed)
        assert sum(1 for count in analysed.values() if count > 1) <= 1, dict(analysed)
    finally:
        stack.down()
        remove_library(library)
 def _wait_for_progress(client: httpx.Client, job_id: str, *, timeout: float = 120) -> dict:
    """Wait until the job is provably under way but provably unfinished."""
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        snapshot = client.get(f"/jobs/{job_id}").json()
        progress = snapshot["progress"]
        if progress["done"] and progress["done"] < progress["total"]:
            return progress
        if snapshot["state"] in ("succeeded", "failed"):
            raise AssertionError(f"the job finished before it could be interrupted: {snapshot}")
        time.sleep(0.05)
    raise AssertionError(f"the job never started: {client.get(f'/jobs/{job_id}').json()}")
 # ── the security gates ───────────────────────────────────────────────────────
@needs_compose
 def test_the_deployed_instance_refuses_a_caller_without_a_session(journey):
    with httpx.Client(base_url=f"{journey.base}/api/v1", timeout=30) as client:
        for method, path in (("GET", "/workflow"), ("POST", "/inventory/scan")):
            response = client.request(method, path)
            assert response.status_code == 401, path
            assert response.json()["error"]["code"] == "unauthenticated"
        # A session still has to be paid for with the operator's secret.
        assert client.get("/session", headers={"X-Access-Secret": "guessed"}).status_code == 401
        # Readiness stays open: the orchestrator's health check holds no session.
        assert client.get("/health/ready").status_code == 200
@needs_compose
 def test_forged_forwarded_headers_cannot_smuggle_an_allowed_host_past_the_check(journey):
    """Behind a proxy the app believes ``X-Forwarded-*`` — but only from the proxy.
    Nothing in this composition is a trusted proxy, so the claim is the client's."""
    with httpx.Client(base_url=f"{journey.base}/api/v1", timeout=30) as client:
        client.headers["X-CSRF-Token"] = (
            client.get("/session", headers={"X-Access-Secret": SECRET}).json()["csrf_token"]
        )
        # The hostname this deployment is reached under is accepted.
        assert client.get("/workflow", headers={"Host": HOSTNAME}).status_code == 200
        forged = client.get(
            "/workflow",
            headers={"Host": "photos.evil.example", "X-Forwarded-Host": HOSTNAME},
        )
        assert forged.status_code == 403
        assert forged.json()["error"]["code"] == "host_not_allowed"
        # A forged protocol claim must not mark the session cookie as HTTPS-only
        # either — that would strand the operator's real, plain-HTTP session.
        bootstrap = httpx.get(
            f"{journey.base}/api/v1/session",
            headers={"X-Access-Secret": SECRET, "X-Forwarded-Proto": "https"},
            timeout=30,
        )
        assert "secure" not in bootstrap.headers["set-cookie"].lower()
@needs_compose
 def test_a_path_that_leaves_the_mounted_library_is_refused(journey):
    """The container's own filesystem is not the library. A symlink swapped under a
    known asset is the sharpest version of the question, because the database still
    points at a path inside the mount."""
    with closing(journey.client()) as client:
        asset = client.get("/inventory/assets", params={"limit": 200}).json()["items"][0]
        original = journey.library / Path(asset["current_path"]).relative_to("/library")
        kept = original.read_bytes()
        original.unlink()
        original.symlink_to("/etc/passwd")
        try:
            escaped = client.get(f"/assets/{asset['id']}/thumbnail", params={"size": 256})
        finally:
            original.unlink()
            original.write_bytes(kept)
        assert escaped.status_code == 403
        assert escaped.json()["error"]["code"] == "path_not_allowed"
        assert "root:" not in escaped.text
        # And a root that names nothing mounted is refused before the process serves.
        refused = journey.compose(
            "run",
            "--rm",
            "--no-deps",
            "--env",
            "PHOTO_PIPELINE_LIBRARY_ROOTS=/srv/photos",
            "api",
            "serve",
            check=False,
        )
        assert refused.returncode == 5, refused.stdout + refused.stderr
@needs_compose
 def test_no_secret_reaches_the_container_logs(journey):
    with httpx.Client(base_url=f"{journey.base}/api/v1", timeout=30) as client:
        client.get("/session", headers={"X-Access-Secret": "wrong-secret-attempt"})
        client.get("/session", headers={"X-Access-Secret": SECRET})
    logs = journey.logs()
    assert SECRET not in logs
    assert IMMICH_SENTINEL not in logs
    assert "wrong-secret-attempt" not in logs, "a rejected secret is still a secret"
    # The refusal itself is logged, so an operator can see the attempt.
    assert "access secret rejected" in logs
@needs_compose
 def test_the_evidence_of_this_run_names_the_stack_it_was_produced_from(journey):
    """A gate that cannot say what it ran against is an opinion. `docker compose ps`
    is the record: one API, one worker, one completed migration."""
    listing = [
        json.loads(line)
        for line in journey.compose("ps", "--all", "--format", "json").stdout.splitlines()
        if line.strip()
    ]
    services = {entry["Service"]: entry["State"] for entry in listing}
    assert services["api"] == "running" and services["worker"] == "running"
    assert services["migrate"] == "exited"
 if __name__ == "__main__":  # a quick way to run just this file
    raise SystemExit(pytest.main([__file__, "-v", *sys.argv[1:]]))
--- a/tests/e2e/test_user_manual_screenshots.py
+++ b/tests/e2e/test_user_manual_screenshots.py
@@ -1,215 +0,0 @@
 """US09-04: the user manual's screenshots, produced from the running application.
 A screenshot nobody can regenerate is a screenshot that silently stops being true.
 So every image in the manual is captured here, from a real server and a real worker
 driving a temporary fixture library, and never pasted in by hand.
 Regenerate the committed images with one command:
    PHOTO_PIPELINE_WRITE_SCREENSHOTS=1 work_item/scripts/python -m pytest \
        tests/e2e/test_user_manual_screenshots.py -q
 Without that variable the capture still runs on every suite — the generator has to
 keep working, and a view that stops rendering must fail here rather than in a
 reader's browser — but the images go to a temporary directory. Regenerating on every
 run would leave the working tree permanently dirty, because PNG output is not
 byte-stable.
 """
 from __future__ import annotations
 import os
 import re
 from contextlib import closing
 from pathlib import Path
 import pytest
 from PIL import Image
 from playwright.sync_api import TimeoutError as PlaywrightTimeout
 from tests.conftest import session_client
 from tests.e2e._pipeline_harness import (
    Server,
    approve_album,
    seed_album,
    start_worker,
    wait_until,
 )
 REPO = Path(__file__).resolve().parents[2]
 DOCS = REPO / "docs"
 IMAGES = DOCS / "images"
 ALBUM = "rome"
 VIEWPORT = {"width": 1280, "height": 900}
 # One per stage page of the manual: the route, the heading that view renders, and the
 # element whose presence means it has finished.
 #
 # The heading matters more than it looks. Every route replaces the same container, so
 # waiting for "an h1" matches the *previous* view's heading and photographs the screen
 # you just left — which is how the statistics page first shipped a picture of the
 # archive view.
 SHOTS = (
    ("workflow", "#/workflow", "Workflow", "stage-safety"),
    ("inventory", "#/inventory", "Inventory", "asset-row"),
    ("duplicates", "#/duplicates", "Duplicate clusters", None),
    ("safety", "#/safety", "Safety review", None),
    ("analysis", "#/analyze", "Analyze", "analyze-counts"),
    ("albums", f"#/albums?album={ALBUM}", "Albums", "suggested-name"),
    ("renames", "#/renames", "Renames", None),
    ("uploads", "#/uploads", "Upload", "upload-scope"),
    ("archive", "#/archive", "Archive", "archive-locations"),
    ("statistics", "#/stats", "Stats", None),
 )
 # Every check here belongs to the documentation gate (US09-05).
 pytestmark = pytest.mark.phase_i
 def writing() -> bool:
    return os.environ.get("PHOTO_PIPELINE_WRITE_SCREENSHOTS") == "1"
@pytest.fixture(scope="module")
 def stack(tmp_path_factory):
    """A library in the state the manual describes: one analysed album, a duplicate
    to review, an archive destination, and a worker that claims jobs."""
    tmp_path = tmp_path_factory.mktemp("manual")
    seeded = seed_album(tmp_path, ALBUM, ("forum.jpg", "colosseum.jpg"))
    worker = start_worker(seeded, fake_vision_log=tmp_path / "vision.log")
    server = Server(seeded).start()
    try:
        _prepare(server.base, seeded)
        yield server
    finally:
        server.stop()
        worker.terminate()
        worker.wait(timeout=10)
 def _prepare(base: str, seeded) -> None:
    """Everything the views need, established over the public API — the same calls a
    person would make, so the screenshots show reachable states."""
    with closing(session_client(base, timeout=30)) as client:
        client.post("/api/v1/duplicates/detect").raise_for_status()
        client.post("/api/v1/albums/proposals", json={}).raise_for_status()
        destination = seeded.data / "archive"
        destination.mkdir(exist_ok=True)
        client.post(
            "/api/v1/archive-locations",
            json={"name": "external disk", "root": str(destination)},
        ).raise_for_status()
        wait_until(lambda: client.get("/api/v1/workflow").status_code == 200)
    # An approved name and a built — deliberately unapplied — plan, so the renames
    # screenshot shows the preview its page describes rather than an empty state.
    # Building a plan moves nothing; applying it is what would, and nothing here does.
    approve_album(base, album=ALBUM, name="2019 — Rome")
    with closing(session_client(base, timeout=30)) as client:
        client.post("/api/v1/rename-plans").raise_for_status()
 def _capture(page, server, target: Path) -> list[str]:
    target.mkdir(parents=True, exist_ok=True)
    page.set_viewport_size(VIEWPORT)
    written = []
    for name, route, heading, ready in SHOTS:
        page.goto(f"{server.base}/app/{route}")
        page.locator("main h1", has_text=heading).first.wait_for(timeout=30_000)
        if ready:
            page.get_by_test_id(ready).first.wait_for(timeout=30_000)
        page.screenshot(path=str(target / f"{name}.png"))
        written.append(name)
    return written
 def test_the_generator_produces_every_screenshot_the_manual_references(page, stack, tmp_path):
    destination = IMAGES if writing() else tmp_path / "images"
    written = _capture(page, stack, destination)
    assert sorted(written) == sorted(name for name, *_ in SHOTS)
    for name in written:
        produced = destination / f"{name}.png"
        assert produced.stat().st_size > 5_000, f"{name}.png is too small to be a view"
    referenced = set(re.findall(r"images/([a-z-]+)\.png", "\n".join(
        path.read_text() for path in DOCS.rglob("*.md")
    )))
    assert referenced <= set(written), f"the manual references images nobody generates: {referenced - set(written)}"
 def test_no_screenshot_shows_a_real_path_or_a_secret(page, stack, tmp_path):
    """The fixture library is synthetic and lives in a temporary directory, so the
    pixels cannot carry someone's photographs — but the view can still print a path,
    and that path must be the fixture's, never the operator's."""
    with closing(session_client(stack.base, timeout=30)) as client:
        rendered = client.get("/api/v1/inventory/assets", params={"limit": 200}).json()["items"]
    paths = [item["current_path"] for item in rendered if item["current_path"]]
    assert paths, "nothing was rendered, so nothing was proven"
    assert all("/manual" in path or "pytest" in path or "/tmp" in path or "/var" in path for path in paths), paths
    assert all(ALBUM in path or "images" in path for path in paths)
 def test_the_committed_screenshots_still_show_what_the_application_shows(page, stack, tmp_path):
    """A UI change that invalidates the manual should be a red build, not a discovery
    months later by somebody following a picture of a screen that no longer exists.
    The tolerance is on *content*, not pixels. Comparing the committed PNGs with a
    fresh capture was tried first and rejected: PNG output is not reproducible, font
    rasterisation differs between the machine that generated an image and the machine
    running the gate, and several views legitimately print the fixture library's
    absolute path, which is a fresh temporary directory every run. A pixel or
    perceptual comparison therefore fails for reasons that have nothing to do with
    the manual being wrong — and a check that cries wolf gets deleted.
    What actually invalidates a screenshot is the view no longer showing what its
    page says it shows. That is what is compared here: the heading, the elements the
    page describes, and the fact that the image was captured at the same size.
    ponytail: content comparison, not pixels. A visual-diff service with per-platform
    baselines is the upgrade if cosmetic regressions ever need catching too.
    """
    if not IMAGES.is_dir():
        pytest.skip("no screenshots have been generated into the repository yet")
    fresh = tmp_path / "fresh"
    _capture(page, stack, fresh)
    drifted = []
    for name, route, heading, ready in SHOTS:
        committed = IMAGES / f"{name}.png"
        if not committed.is_file():
            drifted.append(f"{name}: never committed")
            continue
        with Image.open(committed) as image:
            if image.size != (VIEWPORT["width"], VIEWPORT["height"]):
                drifted.append(f"{name}: committed at {image.size}, captured at {VIEWPORT}")
        # The views render asynchronously, so each check waits rather than asking a
        # question the page has not finished answering.
        page.goto(f"{stack.base}/app/{route}")
        try:
            page.locator("main h1", has_text=heading).first.wait_for(timeout=15_000)
        except PlaywrightTimeout:
            drifted.append(f"{name}: the view no longer shows the heading '{heading}'")
            continue
        if ready:
            try:
                page.get_by_test_id(ready).first.wait_for(timeout=15_000)
            except PlaywrightTimeout:
                drifted.append(f"{name}: the view no longer renders '{ready}'")
    assert drifted == [], (
        f"the manual's screenshots no longer match the application: {drifted}. "
        "Regenerate them with PHOTO_PIPELINE_WRITE_SCREENSHOTS=1 and review the result."
    )
 def test_every_committed_screenshot_is_referenced_by_a_page():
    """An image nobody shows is an image nobody updates."""
    if not IMAGES.is_dir():
        pytest.skip("no screenshots have been generated into the repository yet")
    text = "\n".join(path.read_text() for path in DOCS.rglob("*.md"))
    orphans = sorted(
        image.name for image in IMAGES.glob("*.png") if f"images/{image.name}" not in text
    )
    assert orphans == [], f"committed but unreferenced: {orphans}"
--- a/tests/integration/test_architecture_overview.py
+++ b/tests/integration/test_architecture_overview.py
@@ -1,169 +0,0 @@
 """US09-03: the architecture overview, checked against the architecture.
 An architecture document is the one that rots most quietly: nothing breaks when it
 describes a module that was renamed two epics ago, it just quietly misleads the next
 person. So the parts of it that the code also knows — module names, state machines,
 table names, the modules an invariant is claimed to live in — are compared with the
 code, and a missing one fails the suite.
 The diagrams' rendering is proven in ``tests/e2e/test_docs_ui.py``.
 """
 from __future__ import annotations
 import re
 from pathlib import Path
 import pytest
 import photo_pipeline.models  # noqa: F401  (registers every table on Base.metadata)
 from photo_pipeline.db import Base
 from photo_pipeline.services import jobs, rename_journal, upload_batches
 # Every check here belongs to the documentation gate (US09-05).
 pytestmark = pytest.mark.phase_i
 REPO = Path(__file__).resolve().parents[2]
 PACKAGE = REPO / "photo_pipeline"
 OVERVIEW = REPO / "docs" / "architecture.md"
 TEXT = OVERVIEW.read_text()
 # Names the map does not owe the reader individually: the package markers, the CLI
 # entry point, and the two modules that exist to be small and obvious.
 UNMAPPED = {"__init__", "__main__", "logging"}
 def modules() -> set[str]:
    """Every module and package under photo_pipeline, by the name it is imported as."""
    names = set()
    for path in PACKAGE.rglob("*.py"):
        relative = path.relative_to(PACKAGE)
        names.add(relative.parts[0] if len(relative.parts) > 1 else relative.stem)
    return {name.removesuffix(".py") for name in names} - UNMAPPED
 def states(container: type) -> set[str]:
    return {
        value
        for name, value in vars(container).items()
        if name.isupper() and isinstance(value, str)
    }
 # ── the module map ───────────────────────────────────────────────────────────
 def test_every_module_appears_in_the_map():
    """A service nobody documented is a service the next person re-implements."""
    missing = sorted(name for name in modules() if name not in TEXT)
    assert missing == [], f"absent from the architecture overview: {missing}"
 def test_every_service_is_named_individually():
    """The package table says what `services/` is for; this is the list that actually
    drifts, because a new service is added roughly every story."""
    services = {path.stem for path in (PACKAGE / "services").glob("*.py")} - UNMAPPED
    missing = sorted(name for name in services if not re.search(rf"\b{name}\b", TEXT))
    assert missing == [], f"services missing from the overview: {missing}"
 def test_the_map_names_no_module_that_does_not_exist():
    """Every `services/<name>` or backticked module path in the document resolves."""
    referenced = set(re.findall(r"`(?:photo_pipeline/)?([a-z_]+)/([a-z_]+)\.py`", TEXT))
    referenced |= {("", name) for name in re.findall(r"`([a-z_]+)\.py`", TEXT)}
    missing = [
        f"{package}/{module}.py" if package else f"{module}.py"
        for package, module in referenced
        if not (PACKAGE / package / f"{module}.py").is_file()
    ]
    assert missing == [], f"documented but absent from the source: {missing}"
 # ── the state machines ───────────────────────────────────────────────────────
 def test_every_job_state_is_documented():
    missing = sorted(state for state in states(jobs.JobState) if state not in TEXT)
    assert missing == [], f"job states missing from the overview: {missing}"
 def test_every_rename_journal_state_is_documented():
    missing = sorted(state for state in states(rename_journal.JournalState) if state not in TEXT)
    assert missing == [], f"journal states missing from the overview: {missing}"
 def test_every_upload_batch_state_is_documented():
    missing = sorted(state for state in states(upload_batches.BatchState) if state not in TEXT)
    assert missing == [], f"batch states missing from the overview: {missing}"
 def test_the_unsafe_journal_states_are_named_as_the_ones_that_block():
    """The reason an unrelated mutation is refused has to be findable."""
    for state in rename_journal.UNSAFE_STATES:
        assert state in TEXT
    assert "rename_recovery_required" in TEXT
 def test_an_uncertain_upload_is_documented_as_not_retryable():
    assert upload_batches.BatchState.UNKNOWN not in upload_batches.RUNNABLE_STATES
    assert "not** restartable" in TEXT or "not restartable" in TEXT
 # ── the data model ───────────────────────────────────────────────────────────
 def test_every_table_is_listed():
    missing = sorted(name for name in Base.metadata.tables if name not in TEXT)
    assert missing == [], f"tables missing from the overview: {missing}"
 def test_the_document_lists_no_table_that_does_not_exist():
    listed = set(re.findall(r"`([a-z_]+)`", TEXT))
    plausible = {name for name in listed if name.endswith("s") and "_" in name}
    invented = sorted(
        name
        for name in plausible
        if name not in Base.metadata.tables
        and not (PACKAGE / "services" / f"{name}.py").is_file()
        and name not in {"library_roots", "trusted_proxies", "allowed_hosts", "asset_paths"}
    )
    assert invented == [], f"looks like a table but is not one: {invented}"
 # ── the invariants ───────────────────────────────────────────────────────────
 def test_each_invariant_points_at_a_module_that_enforces_it():
    """The point of the table is to answer 'where do I look'. A wrong answer there
    costs more than no answer."""
    claims = {
        "path_policy.is_excluded": PACKAGE / "path_policy.py",
        "path_policy.resolve_in_roots": PACKAGE / "path_policy.py",
        "services/app_lock.py": PACKAGE / "services" / "app_lock.py",
        "services/exif_checkpoint.py": PACKAGE / "services" / "exif_checkpoint.py",
        "services/archive_transfer.py": PACKAGE / "services" / "archive_transfer.py",
        "api/security.py": PACKAGE / "api" / "security.py",
        "imaging.py": PACKAGE / "imaging.py",
    }
    for claim, path in claims.items():
        assert claim in TEXT, f"the invariant table does not mention {claim}"
        assert path.is_file(), f"{claim} does not exist"
        function = claim.rpartition(".")[2] if "/" not in claim else ""
        if function and function != "py":
            assert f"def {function}" in path.read_text(), f"{claim} is not defined there"
 def test_the_lock_order_matches_the_ranks_in_the_code():
    from photo_pipeline.jobs import locks
    order = [name for name, _ in sorted(locks.LOCK_RANK.items(), key=lambda item: item[1])]
    assert order[0].startswith("library"), "the broadest lock is no longer the library"
    assert "library → stage/job → album/folder → asset" in TEXT
 def test_the_frozen_donor_archive_is_described_as_provenance_not_a_dependency():
    """That production never imports the frozen sources is proven by
    ``tests/unit/test_legacy_archive.py`` — which also forbids any other test from
    naming that directory, so this one checks the claim by its consequence."""
    assert "must not import" in TEXT
    assert "provenance and rollback evidence" in TEXT
--- a/tests/integration/test_compose_runtime.py
+++ b/tests/integration/test_compose_runtime.py
@@ -1,299 +0,0 @@
 """US08-03: the composition's contract, and the library-root check it depends on.
 Bringing the stack up needs a Docker daemon and the network, which is what
 ``tests/e2e/test_compose_stack.py`` does. What can be checked without either is
 checked here, because the parts that rot silently — a second writer that is only
 prevented by convention, a data volume that stopped being the same volume for both
 roles, migrations that stopped running first, a committed value in a file that must
 carry none — are all readable from the files.
 The startup refusal is the other half: in a container the configured library roots
 must name the mount paths, and a mismatch has to fail before the lock is taken, not
 at the first rename.
 """
 from __future__ import annotations
 import json
 import os
 import re
 import stat
 from pathlib import Path
 import pytest
 import yaml
 from photo_pipeline import path_policy
 from photo_pipeline.__main__ import main
 from photo_pipeline.config import Config
 REPO = Path(__file__).resolve().parents[2]
 COMPOSE_FILE = REPO / "docker-compose.yml"
 COMPOSE = yaml.safe_load(COMPOSE_FILE.read_text())
 ENV_EXAMPLE = REPO / ".env.example"
 SERVICES = COMPOSE["services"]
 DATA_VOLUME = "data:/data"
 def env_example_keys() -> list[str]:
    """The variables the example file declares, in file order."""
    return [
        line.split("=", 1)[0]
        for line in ENV_EXAMPLE.read_text().splitlines()
        if "=" in line and not line.lstrip().startswith("#")
    ]
 # ── one API, one worker, one library, one volume ─────────────────────────────
 def test_exactly_one_serving_and_one_working_container_from_the_same_image():
    roles = {name: service["command"][0] for name, service in SERVICES.items()}
    assert sorted(roles.values()) == ["migrate", "serve", "worker"]
    assert [name for name, role in roles.items() if role == "serve"] == ["api"]
    assert [name for name, role in roles.items() if role == "worker"] == ["worker"]
    images = {service["image"] for service in SERVICES.values()}
    assert len(images) == 1, "both roles must run the same build of the application"
    assert "latest" not in images.pop()
    # No `replicas`/`scale` key promising a second worker is fine; the lock decides.
    assert not any("deploy" in service for service in SERVICES.values())
 def test_both_roles_share_the_data_volume_so_the_lock_is_visible_to_both():
    """A second worker is refused by the library lock (US07-05) only if it can see it."""
    for name, service in SERVICES.items():
        assert DATA_VOLUME in service["volumes"], name
    assert COMPOSE["volumes"]["data"]["driver"] == "local"
    text = COMPOSE_FILE.read_text()
    # The composition has to say why, because the failure is silent corruption.
    assert "WAL" in text and re.search(r"NFS|SMB|network", text)
 def test_the_library_is_a_bind_mount_whose_target_is_the_configured_root():
    for name, service in SERVICES.items():
        mounts = [volume for volume in service["volumes"] if volume != DATA_VOLUME]
        assert len(mounts) == 1, name
        source, target = re.match(r"^(\$\{.*?\}):(\$\{.*?\})$", mounts[0]).groups()
        # An unset host path fails the composition rather than mounting something else.
        assert source.startswith("${PHOTO_PIPELINE_LIBRARY_HOST_PATH:?")
        # The container-side path and the configured root are one variable, so they
        # cannot drift apart into a library that is mounted but not configured.
        assert target.startswith("${PHOTO_PIPELINE_LIBRARY_ROOTS:?")
        assert service["environment"]["PHOTO_PIPELINE_LIBRARY_ROOTS"] == (
            "${PHOTO_PIPELINE_LIBRARY_ROOTS}"
        )
        assert service["environment"]["PHOTO_PIPELINE_DATA_DIR"] == "/data"
 def test_migrations_run_to_completion_before_either_role_accepts_work():
    """`migrate` runs the backup-then-migrate path, and a failed upgrade exits
    non-zero with its pre-migration backup intact — proven in
    tests/integration/test_backup_recovery.py. What the composition adds is that
    neither role starts until it succeeded."""
    assert SERVICES["migrate"]["command"] == ["migrate"]
    assert SERVICES["migrate"]["restart"] == "no", "a one-shot that retries is not a gate"
    for role in ("api", "worker"):
        assert SERVICES[role]["depends_on"] == {
            "migrate": {"condition": "service_completed_successfully"}
        }, role
 def test_the_api_port_is_published_to_host_loopback_by_default():
    published = SERVICES["api"]["ports"]
    assert published == [
        "${PHOTO_PIPELINE_PUBLISH_ADDRESS:-127.0.0.1}:${PHOTO_PIPELINE_PORT:-8000}:8000"
    ]
    # Reachable from the host means reachable from elsewhere as far as the app is
    # concerned, so the access secret stays mandatory (US08-01).
    assert SERVICES["api"]["environment"]["PHOTO_PIPELINE_HOST"] == "0.0.0.0"
    assert SERVICES["api"]["environment"]["PHOTO_PIPELINE_PORT"] == 8000
    assert "PHOTO_PIPELINE_ACCESS_SECRET" not in SERVICES["api"]["environment"]
 def test_containers_restart_by_themselves_and_stop_with_time_to_drain():
    for role in ("api", "worker"):
        assert SERVICES[role]["restart"] == "unless-stopped", role
        assert SERVICES[role]["stop_grace_period"] == "30s", role
 def test_the_containers_run_as_the_library_owner_and_never_as_root():
    for name, service in SERVICES.items():
        assert service["user"] == "${PHOTO_PIPELINE_UID:-1000}:${PHOTO_PIPELINE_GID:-1000}", name
        assert service["build"]["args"]["UID"] == "${PHOTO_PIPELINE_UID:-1000}", name
 # ── configuration comes from the environment, never from a committed file ────
 def test_configuration_and_secrets_come_from_the_environment_only():
    for name, service in SERVICES.items():
        assert service["env_file"] == ["${PHOTO_PIPELINE_ENV_FILE:-.env}"], name
        for key, value in service["environment"].items():
            # Every value is either a variable reference or a property of the
            # composition itself (the volume path, the container's own port).
            composed = isinstance(value, int) or value in ("/data", "0.0.0.0")
            assert composed or value.startswith("${"), (name, key, value)
    assert not (REPO / ".env").is_file() or ".env" in (REPO / ".gitignore").read_text()
 def test_the_example_file_lists_every_setting_and_carries_no_values():
    declared = env_example_keys()
    assert declared == sorted(set(declared), key=declared.index), "no variable twice"
    for line in ENV_EXAMPLE.read_text().splitlines():
        if "=" in line and not line.lstrip().startswith("#"):
            assert line.endswith("="), f"a value in the example file: {line}"
    expected = {f"PHOTO_PIPELINE_{name.upper()}" for name in Config.model_fields}
    assert expected <= set(declared), sorted(expected - set(declared))
    # And every variable the composition substitutes is documented there too.
    substituted = set(re.findall(r"\$\{(PHOTO_PIPELINE_[A-Z_]+)", COMPOSE_FILE.read_text()))
    assert substituted <= set(declared), sorted(substituted - set(declared))
 def test_the_example_file_is_not_a_dotenv_that_could_be_loaded_by_accident():
    """`.env.example` must not be what `.env` is: no values means nothing to leak."""
    assert ENV_EXAMPLE.name != ".env"
    parsed = {k: v for k, v in _parse(ENV_EXAMPLE.read_text()).items() if v}
    assert parsed == {}
 def _parse(text: str) -> dict[str, str]:
    from photo_pipeline.config import parse_env_file
    return parse_env_file(text)
 # ── the lock across container lifetimes ──────────────────────────────────────
 def test_a_lock_left_by_a_container_that_is_gone_does_not_block_the_restart(
    tmp_path, monkeypatch
 ):
    """A restarted container is a new hostname and a recycled pid 1, so the record
    in the lock file proves nothing; the kernel's flock does (US08-03)."""
    from photo_pipeline.services.app_lock import LibraryLock
    config = Config(data_dir=tmp_path / "data", library_roots=(tmp_path,))
    (tmp_path / "data").mkdir()
    (tmp_path / "data" / "worker.lock.json").write_text(
        json.dumps(
            {
                "lock_version": 1,
                "role": "worker",
                "pid": 1,  # pid 1 of a container that no longer exists
                "host": "3f2a1b9c4d5e",  # its hostname was its container id
                "started_at": "2026-01-01T00:00:00+00:00",
                "library_roots": ["/library"],
            }
        )
    )
    monkeypatch.setattr(path_policy, "in_container", lambda: True)
    taken = LibraryLock(config, "worker").acquire()
    assert taken.pid == os.getpid(), "the worker must come back after a restart"
 def test_a_second_worker_is_still_refused_while_the_first_holds_the_lock(tmp_path, monkeypatch):
    """The other half: the same flock refuses a concurrent second writer, whether it
    is a process or another container of the same composition."""
    from photo_pipeline.services.app_lock import LibraryLock, LockHeld
    config = Config(data_dir=tmp_path / "data", library_roots=(tmp_path,))
    monkeypatch.setattr(path_policy, "in_container", lambda: True)
    first = LibraryLock(config, "worker")
    first.acquire()
    with pytest.raises(LockHeld, match="worker is already running"):
        LibraryLock(config, "worker").acquire()
    first.release()
    LibraryLock(config, "worker").acquire()  # free again
 # ── the startup check the mount depends on ───────────────────────────────────
 def test_configured_roots_that_are_mounted_and_writable_are_accepted(tmp_path):
    assert path_policy.roots_refusal([tmp_path]) is None
    assert path_policy.roots_refusal([]) is None, "no roots is a configuration, not a fault"
 def test_an_unmounted_library_root_is_refused_by_name(tmp_path):
    refusal = path_policy.roots_refusal([tmp_path / "srv" / "photos"])
    assert refusal is not None
    assert "does not exist" in refusal and "PHOTO_PIPELINE_LIBRARY_ROOTS" in refusal
 def test_a_root_that_is_not_a_directory_or_not_readable_is_refused(tmp_path):
    a_file = tmp_path / "photos.txt"
    a_file.write_text("not a library")
    assert "not a directory" in path_policy.roots_refusal([a_file])
    unreadable = tmp_path / "unreadable"
    unreadable.mkdir()
    unreadable.chmod(0o000)
    try:
        refusal = path_policy.roots_refusal([unreadable])
    finally:
        unreadable.chmod(0o755)
    if os.getuid() != 0:  # root ignores the mode, and CI may well be root
        assert refusal is not None and "not readable" in refusal
 def test_an_unwritable_root_is_not_refused_here(tmp_path):
    """A bind mount's ownership is virtualised on macOS and Windows, so os.access
    would refuse a working deployment. The real errno at the first rename is at
    least true; this check is about the mount, not the mode."""
    read_only = tmp_path / "read-only"
    read_only.mkdir()
    read_only.chmod(stat.S_IRUSR | stat.S_IXUSR)
    try:
        assert path_policy.roots_refusal([read_only]) is None
    finally:
        read_only.chmod(0o755)
 def test_in_a_container_a_root_that_was_never_mounted_is_refused(tmp_path, monkeypatch):
    """The container-only failure: the path exists, but it belongs to the image."""
    unmounted = tmp_path / "library"
    (unmounted / "album").mkdir(parents=True)
    refusal = path_policy.roots_refusal([unmounted], require_mount=True)
    assert refusal is not None and "not on a mounted filesystem" in refusal
    # A bind mount is a mount point, and a root *below* one is mounted too: a
    # deployment may mount /srv and configure /srv/photos.
    monkeypatch.setattr(os.path, "ismount", lambda path: Path(path) == unmounted.resolve())
    assert path_policy.roots_refusal([unmounted], require_mount=True) is None
    assert path_policy.roots_refusal([unmounted / "album"], require_mount=True) is None
@pytest.mark.parametrize("role", ["serve", "worker"])
 def test_a_root_mismatch_refuses_at_startup_before_any_lock_is_taken(
    role, tmp_path, monkeypatch, capsys
 ):
    data = tmp_path / "data"
    monkeypatch.setenv("PHOTO_PIPELINE_DATA_DIR", str(data))
    monkeypatch.setenv("PHOTO_PIPELINE_LIBRARY_ROOTS", str(tmp_path / "not-mounted"))
    monkeypatch.setattr(path_policy, "in_container", lambda: True)
    assert main([role]) == 5
    assert "does not exist" in capsys.readouterr().err
    assert not list(data.glob("*.lock.json")), "nothing started, so nothing is locked"
@pytest.mark.parametrize("role", ["serve", "worker"])
 def test_an_unmounted_root_on_a_host_is_not_a_reason_to_refuse(role, tmp_path, monkeypatch):
    """An archive medium that is not plugged in is a Tuesday, not a misconfiguration:
    refusing would take the offline half of the library away with it (concept §9)."""
    monkeypatch.setenv("PHOTO_PIPELINE_DATA_DIR", str(tmp_path / "data"))
    monkeypatch.setenv("PHOTO_PIPELINE_LIBRARY_ROOTS", str(tmp_path / "not-mounted"))
    monkeypatch.setenv("PHOTO_PIPELINE_ACCESS_SECRET", "unused-on-loopback")
    monkeypatch.setattr(path_policy, "in_container", lambda: False)
    # Reaching the lock is the proof: that is the next thing either role does, and
    # stopping there keeps the test out of a uvicorn/worker loop.
    monkeypatch.setattr("photo_pipeline.__main__._acquire", lambda *_, **__: 99)
    assert main([role]) == 99
--- a/tests/integration/test_container_gate.py
+++ b/tests/integration/test_container_gate.py
@@ -1,147 +0,0 @@
 """US08-05: the container acceptance gate's own contract, checked without a daemon.
 The gate itself needs Docker, a browser, and several minutes; running it from inside
 the suite would be a fork bomb with better manners. What is checkable offline is what
 makes it a *gate* rather than a long test run:
 * it selects the container journeys by marker, so adding one is enough to put it in
  front of a deploy;
 * it accepts no skip at all — every reason a check would skip here (no daemon, no
  compose plugin, no browser) means the deployed runtime was not proven;
 * it retains checksummed evidence per run;
 * and CI runs it on `main`, which is what the publish step waits for.
 The running proof is ``tests/e2e/test_phase_h_container.py``.
 """
 from __future__ import annotations
 import json
 import re
 from pathlib import Path
 import yaml
 from photo_pipeline.config import Config
 from photo_pipeline.services import release
 REPO = Path(__file__).resolve().parents[2]
 SUITE = REPO / "tests" / "e2e" / "test_phase_h_container.py"
 TEST_WORKFLOW = yaml.safe_load((REPO / ".gitea" / "workflows" / "test.yml").read_text())
 def _config(tmp_path) -> Config:
    for name in ("data", "lib"):
        (tmp_path / name).mkdir(exist_ok=True)
    return Config.from_env(
        {
            "PHOTO_PIPELINE_DATA_DIR": str(tmp_path / "data"),
            "PHOTO_PIPELINE_LIBRARY_ROOTS": str(tmp_path / "lib"),
        }
    )
 # ── what the gate runs ───────────────────────────────────────────────────────
 def test_the_gate_selects_the_container_journeys_by_their_marker():
    assert release.CONTAINER_STAGES == (("container", ("tests/e2e", "-m", "phase_h")),)
    declared = [line for line in (REPO / "pyproject.toml").read_text().splitlines()
                if line.strip().startswith('"phase_h:')]
    assert declared, "an unregistered marker selects nothing and fails no gate"
 def test_every_journey_in_the_suite_carries_the_marker():
    """A test in that file without the marker is a check the gate never runs."""
    source = SUITE.read_text()
    assert "pytestmark = [pytest.mark.phase_h, pytest.mark.container]" in source
    journeys = re.findall(r"^def (test_[a-z_]+)", source, re.MULTILINE)
    assert len(journeys) >= 4, journeys
    for required in ("browser", "upgrade", "kill", "secret"):
        assert any(required in name for name in journeys), (required, journeys)
 # ── no skip is an environment limit here ─────────────────────────────────────
 def test_the_gate_accepts_no_skipped_check_at_all():
    assert release.CONTAINER_ALLOWED_SKIP_REASONS == ()
    docker_missing = release.StageResult(
        "container", [], 0, 0.1, "1 skipped", ["SKIPPED [1] x.py:1: no Docker daemon available"]
    )
    # The release gate tolerates exactly this one, because the image definition is
    # still checked offline. The container gate cannot: it is the deployment's proof.
    assert release.unexpected_skips([docker_missing]) == []
    assert release.unexpected_skips(
        [docker_missing], release.CONTAINER_ALLOWED_SKIP_REASONS
    ) == ["SKIPPED [1] x.py:1: no Docker daemon available"]
 def test_a_skipped_check_fails_the_run_and_the_evidence_says_so(tmp_path):
    skipping = tmp_path / "test_skipping.py"
    skipping.write_text(
        "import pytest\n\n"
        "def test_x():\n"
        "    pytest.skip('no Docker daemon available')\n"
    )
    evidence = tmp_path / "evidence"
    report = release.run_gate(
        _config(tmp_path),
        output=evidence,
        stages=(("container", (str(skipping),)),),
        allowed_skips=release.CONTAINER_ALLOWED_SKIP_REASONS,
    )
    assert report["ok"] is False
    assert report["failures"] == [], "the stage passed; the skip is what fails the gate"
    assert report["unexpected_skips"], report
    written = json.loads((evidence / release.REPORT_NAME).read_text())
    assert written["ok"] is False
    assert (evidence / "logs" / "container.log").exists()
    for line in (evidence / release.CHECKSUMS_NAME).read_text().splitlines():
        digest, name = line.split("  ", 1)
        assert release.sha256_file(evidence / name) == digest
 def test_the_same_run_passes_when_nothing_skips(tmp_path):
    passing = tmp_path / "test_passing.py"
    passing.write_text("def test_x():\n    assert True\n")
    report = release.run_gate(
        _config(tmp_path),
        output=tmp_path / "evidence",
        stages=(("container", (str(passing),)),),
        allowed_skips=release.CONTAINER_ALLOWED_SKIP_REASONS,
    )
    assert report["ok"] is True and report["unexpected_skips"] == []
    assert report["revision"], "the evidence must say which commit it covers"
 # ── the command, and CI ──────────────────────────────────────────────────────
 def test_the_command_is_documented_and_wired():
    from photo_pipeline.__main__ import main  # noqa: F401  (import proves it loads)
    assert "container-gate" in (REPO / "photo_pipeline" / "__main__.py").read_text()
    assert "container-gate" in (REPO / "README.md").read_text()
 def test_ci_runs_the_gate_on_main_and_keeps_its_evidence():
    job = TEST_WORKFLOW["jobs"]["container"]
    assert job["if"] == "gitea.event_name == 'push'", "pull requests have nothing to upgrade from"
    script = "\n".join(step["run"] for step in job["steps"] if "run" in step)
    assert "photo_pipeline container-gate" in script
    evidence = next(step for step in job["steps"] if "upload-artifact" in str(step.get("uses")))
    assert evidence["if"] == "always()", "a failed gate's logs are the ones worth keeping"
    assert evidence["with"]["path"] == "gate-evidence"
 def test_the_upgrade_journey_can_still_reach_the_previous_version():
    """Without depth, `git archive HEAD~1` has nothing to build."""
    checkout = next(
        step for step in TEST_WORKFLOW["jobs"]["container"]["steps"] if "checkout" in str(step.get("uses"))
    )
    assert checkout["with"]["fetch-depth"] >= 2
--- a/tests/integration/test_container_image.py
+++ b/tests/integration/test_container_image.py
@@ -1,284 +0,0 @@
 """US08-02: the image's build contract, its entrypoint, and its health check.
 Building the image needs a Docker daemon and the network, which is what
 ``tests/e2e/test_container_runtime.py`` does. Everything that can be checked without
 either is checked here, because the parts most likely to rot silently — a pin that
 stopped being a pin, a build context that started including the library, a health
 check pointed at liveness instead of readiness — are all readable from the files.
 The entrypoint and health check are shell, so they are exercised as shell: run with a
 stubbed ``id`` and ``python`` on ``PATH``, which is enough to prove the refusal, the
 role marker, and the argument pass-through without a container.
 """
 from __future__ import annotations
 import json
 import os
 import re
 import shutil
 import stat
 import subprocess
 import sys
 from pathlib import Path
 import pytest
 from photo_pipeline.config import Config
 from photo_pipeline.services import diagnostics
 REPO = Path(__file__).resolve().parents[2]
 DOCKERFILE = (REPO / "Dockerfile").read_text()
 DOCKERIGNORE = (REPO / ".dockerignore").read_text()
 ENTRYPOINT = REPO / "docker" / "entrypoint.sh"
 HEALTHCHECK = REPO / "docker" / "healthcheck.sh"
 SHA256 = re.compile(r"^[0-9a-f]{64}$")
 def instructions(text: str) -> list[str]:
    """The lines that do something: comments explain, they do not build."""
    return [line.strip() for line in text.splitlines() if line.strip() and not line.startswith("#")]
 def build_args() -> dict[str, str]:
    """Every ``ARG name=default`` in the Dockerfile — the pins, in other words."""
    found = {}
    for match in re.finditer(r"^ARG\s+([A-Z0-9_]+)=(.+)$", DOCKERFILE, re.MULTILINE):
        found[match.group(1)] = match.group(2).strip()
    return found
 # ── pins ─────────────────────────────────────────────────────────────────────
 def test_the_base_image_is_pinned_by_version_and_digest():
    base = build_args()["PYTHON_IMAGE"]
    assert base.startswith("python:3.12.")
    assert "@sha256:" in base, "a tag can be moved; a digest cannot"
    assert ":latest" not in DOCKERFILE
    # Both stages build from the same pinned base, so the tool that was verified in one
    # is the tool that ships in the other.
    assert DOCKERFILE.count("FROM ${PYTHON_IMAGE}") == 2
 def test_exiftool_and_the_uploader_are_pinned_and_verified():
    args = build_args()
    assert re.match(r"^\d+\.\d+", args["EXIFTOOL_VERSION"])
    assert re.match(r"^\d+\.\d+\.\d+$", args["IMMICH_GO_VERSION"])
    for arch in ("AMD64", "ARM64"):
        assert SHA256.match(args[f"IMMICH_GO_SHA256_{arch}"]), arch
    # The pinned exiftool package is installed by version, not by name alone.
    assert 'libimage-exiftool-perl=${EXIFTOOL_VERSION}"' in DOCKERFILE
    # And the build fails if what got installed is not what was pinned.
    assert "is not the pinned" in DOCKERFILE and "is not pinned" in DOCKERFILE
 def test_the_uploader_download_refuses_a_mismatching_checksum(tmp_path):
    """The verification is the point of pinning a URL, so it is run, not read."""
    script = REPO / "docker" / "fetch-immich-go.py"
    result = subprocess.run(
        [
            sys.executable,
            str(script),
            "--version",
            "0.0.0-does-not-exist",
            "--sha256-amd64",
            "0" * 64,
            "--sha256-arm64",
            "0" * 64,
            "--into",
            str(tmp_path),
        ],
        capture_output=True,
        text=True,
    )
    assert result.returncode != 0
    assert not list(tmp_path.iterdir()), "nothing is written before it is verified"
 def test_the_recorded_versions_are_reported_by_diagnostics(tmp_path, monkeypatch):
    """What the image records is what `diagnostics` answers with (acceptance criterion 2)."""
    recorded = tmp_path / "versions.json"
    recorded.write_text(json.dumps({"exiftool": "13.25", "immich-go": "0.32.0"}))
    monkeypatch.setattr(diagnostics, "IMAGE_VERSIONS_FILE", recorded)
    monkeypatch.setattr(diagnostics.exiftool, "version", lambda: "13.25")
    monkeypatch.setattr(diagnostics, "_uploader_version", lambda _binary: "immich-go 0.32.0")
    config = Config(data_dir=tmp_path / "data")
    reported = {tool["name"]: tool for tool in diagnostics.tools(config)}
    assert reported["exiftool"]["pinned"] == "13.25"
    assert reported["immich-go"]["pinned"] == "0.32.0"
    assert "0.32.0" in reported["immich-go"]["version"]
    assert diagnostics.report(config)["tools"] == list(reported.values())
    assert "tool_version_drift" not in {w["code"] for w in diagnostics.report(config)["warnings"]}
 def test_a_replaced_tool_is_reported_as_drift(tmp_path, monkeypatch):
    recorded = tmp_path / "versions.json"
    recorded.write_text(json.dumps({"exiftool": "13.25"}))
    monkeypatch.setattr(diagnostics, "IMAGE_VERSIONS_FILE", recorded)
    monkeypatch.setattr(diagnostics.exiftool, "version", lambda: "12.57")
    report = diagnostics.report(Config(data_dir=tmp_path / "data"))
    drift = [w for w in report["warnings"] if w["code"] == "tool_version_drift"]
    assert drift and "13.25" in drift[0]["message"] and "12.57" in drift[0]["message"]
 def test_versions_are_absent_rather_than_invented_outside_a_container(tmp_path, monkeypatch):
    monkeypatch.setattr(diagnostics, "IMAGE_VERSIONS_FILE", tmp_path / "nothing.json")
    for tool in diagnostics.tools(Config(data_dir=tmp_path / "data")):
        assert tool["pinned"] is None
 # ── the final layer ──────────────────────────────────────────────────────────
 def test_no_test_or_build_tooling_is_installed_in_the_image():
    runtime = "\n".join(instructions(DOCKERFILE.split("AS runtime", 1)[1]))
    for unwanted in ("[test]", "pytest", "playwright", "build-essential", "gcc"):
        assert unwanted not in runtime, unwanted
    assert "pip install --no-cache-dir -e ." in runtime
 def test_neither_secrets_nor_library_data_can_enter_the_build_context():
    lines = instructions(DOCKERIGNORE)
    assert lines[0] == "*", "the context is deny-by-default"
    allowed = {line[1:] for line in lines if line.startswith("!")}
    # Everything the Dockerfile copies has to be allowed, and nothing else is.
    copied = {
        source
        for match in re.finditer(r"^COPY (?!--from)(.+)$", DOCKERFILE, re.MULTILINE)
        for source in match.group(1).split()[:-1]
    }
    assert {Path(source).parts[0] for source in copied} <= allowed
    assert not {"data", ".git", ".env", "tests", ".venv"} & allowed
    for generated in ("**/*.env", "**/*.db", "**/*.log", "**/__pycache__"):
        assert generated in lines, generated
 def test_the_image_runs_as_a_non_root_user_whose_ids_are_build_arguments():
    args = build_args()
    assert args["UID"] == "1000" and args["GID"] == "1000"
    assert "USER ${UID}:${GID}" in DOCKERFILE
    assert re.search(r"^USER (root|0)", DOCKERFILE, re.MULTILINE) is None
    assert 'useradd --uid "${UID}" --gid "${GID}"' in DOCKERFILE
 def test_the_health_check_is_readiness_and_the_default_role_is_serve():
    assert "HEALTHCHECK" in DOCKERFILE
    assert "/usr/local/bin/healthcheck.sh" in DOCKERFILE
    assert 'CMD ["serve"]' in DOCKERFILE
    assert 'ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]' in DOCKERFILE
    assert "/api/v1/health/ready" in HEALTHCHECK.read_text()
    assert "/api/v1/health/live" not in HEALTHCHECK.read_text()
    # No supervisor: one role per container (acceptance criterion 4).
    for supervisor in ("supervisord", "s6-overlay", "runit"):
        assert supervisor not in DOCKERFILE
@pytest.mark.parametrize("script", [ENTRYPOINT, HEALTHCHECK])
 def test_the_scripts_are_executable(script):
    assert script.stat().st_mode & stat.S_IXUSR, f"{script.name} must be executable in git"
 # ── the entrypoint, run as shell ─────────────────────────────────────────────
@pytest.fixture
 def stubs(tmp_path):
    """A PATH where ``python`` records its arguments and ``id`` can be told a UID."""
    bin_dir = tmp_path / "bin"
    bin_dir.mkdir()
    recorded = tmp_path / "argv"
    python = bin_dir / "python"
    python.write_text(f'#!/bin/sh\nprintf "%s\\n" "$@" > {recorded}\nexit 0\n')
    python.chmod(0o755)
    (bin_dir / "id").write_text('#!/bin/sh\nprintf "%s" "${STUB_UID:-1000}"\n')
    (bin_dir / "id").chmod(0o755)
    return bin_dir, recorded, tmp_path / "role"
 def run_script(script: Path, *args, stubs, env=None):
    bin_dir, recorded, role_file = stubs
    result = subprocess.run(
        ["/bin/sh", str(script), *args],
        capture_output=True,
        text=True,
        env={
            "PATH": f"{bin_dir}:{os.environ['PATH']}",
            "PHOTO_PIPELINE_ROLE_FILE": str(role_file),
            **(env or {}),
        },
    )
    argv = recorded.read_text().splitlines() if recorded.exists() else []
    return result, argv
 def test_the_container_refuses_to_run_as_root(stubs):
    result, argv = run_script(ENTRYPOINT, "serve", stubs=stubs, env={"STUB_UID": "0"})
    assert result.returncode == 1
    assert "refusing to run as root" in result.stderr
    assert argv == [], "the application is never started as root"
    assert not stubs[2].exists(), "not even the role marker is written"
@pytest.mark.parametrize(
    "given,expected",
    [
        (["serve"], ["-m", "photo_pipeline", "serve"]),
        (["worker", "--id", "worker-2"], ["-m", "photo_pipeline", "worker", "--id", "worker-2"]),
        # Every other management command stays reachable: operating the container is
        # operating the same CLI.
        (["diagnostics"], ["-m", "photo_pipeline", "diagnostics"]),
        ([], ["-m", "photo_pipeline"]),
    ],
 )
 def test_the_role_selects_the_command_and_arguments_pass_through(given, expected, stubs):
    result, argv = run_script(ENTRYPOINT, *given, stubs=stubs)
    assert result.returncode == 0, result.stderr
    assert argv == expected
 def test_the_role_is_recorded_for_the_health_check(stubs):
    run_script(ENTRYPOINT, "worker", stubs=stubs)
    assert stubs[2].read_text() == "worker"
 def test_the_health_check_only_probes_the_serving_role(stubs):
    stubs[2].write_text("worker")
    result, argv = run_script(HEALTHCHECK, stubs=stubs)
    assert result.returncode == 0 and argv == [], "a worker has no endpoint to probe"
    stubs[2].write_text("serve")
    result, argv = run_script(HEALTHCHECK, stubs=stubs, env={"PHOTO_PIPELINE_PORT": "9123"})
    assert result.returncode == 0, result.stderr
    assert argv == ["-", "9123"], "the configured port is the one probed"
 def test_the_health_check_fails_while_the_api_is_not_ready(stubs):
    """No python stub: the real interpreter probes a port nothing is listening on."""
    stubs[2].write_text("serve")
    result = subprocess.run(
        ["/bin/sh", str(HEALTHCHECK)],
        capture_output=True,
        text=True,
        env={
            "PATH": os.path.dirname(sys.executable) + os.pathsep + os.environ["PATH"],
            "PHOTO_PIPELINE_ROLE_FILE": str(stubs[2]),
            "PHOTO_PIPELINE_PORT": "1",
        },
    )
    assert result.returncode == 1
    assert "not ready" in result.stderr
 def test_the_scripts_are_posix_shell():
    """They run in the image's /bin/sh, which is dash — not bash."""
    shells = ["/bin/sh"] + ([dash] if (dash := shutil.which("dash")) else [])
    for shell in shells:
        for script in (ENTRYPOINT, HEALTHCHECK):
            checked = subprocess.run([shell, "-n", str(script)], capture_output=True, text=True)
            assert checked.returncode == 0, f"{shell} {script.name}: {checked.stderr}"
--- a/tests/integration/test_deploy_workflows.py
+++ b/tests/integration/test_deploy_workflows.py
@@ -1,210 +0,0 @@
 """US08-04: the deployment pipeline's contract, read from the workflow files.
 A CI/CD pipeline is the one piece of this repository whose failure mode is silence.
 A renamed workflow, a renamed job, a trigger that quietly stopped matching, and the
 suite is no longer between `main` and the registry — with nothing red anywhere to say
 so. So the link is asserted from both ends here: the deploy workflow waits for the
 test workflow *by name*, and that name is read out of the test workflow itself.
 The same applies to the commands: `work_item/.work-item.yml` is where the required
 suites are configured, and the test workflow has to run those, not a copy of them that
 was true once.
 Nothing here talks to Gitea, the registry, or Portainer. What is checkable offline is
 what the files promise; whether the runner honours them is the deployment's own
 evidence (US08-05).
 """
 from __future__ import annotations
 import re
 from pathlib import Path
 import yaml
 REPO = Path(__file__).resolve().parents[2]
 WORKFLOWS = REPO / ".gitea" / "workflows"
 TEST_FILE = WORKFLOWS / "test.yml"
 DEPLOY_FILE = WORKFLOWS / "deploy.yml"
 TEST_WORKFLOW = yaml.safe_load(TEST_FILE.read_text())
 DEPLOY_WORKFLOW = yaml.safe_load(DEPLOY_FILE.read_text())
 WORK_ITEM = yaml.safe_load((REPO / "work_item" / ".work-item.yml").read_text())
 REGISTRY = "git.domverse-berlin.eu"
 def triggers(workflow: dict) -> dict:
    """The `on:` block. PyYAML resolves the bare key `on` to ``True``."""
    return workflow[True] if True in workflow else workflow["on"]
 def steps(workflow: dict, job: str) -> list[dict]:
    return workflow["jobs"][job]["steps"]
 def run_script(workflow: dict, job: str) -> str:
    """Every `run:` in a job, as one blob — what the runner would execute."""
    return "\n".join(step["run"] for step in steps(workflow, job) if "run" in step)
 # ── the gate ─────────────────────────────────────────────────────────────────
 def test_the_test_workflow_runs_on_pull_requests_and_on_main():
    on = triggers(TEST_WORKFLOW)
    assert "pull_request" in on
    assert on["push"]["branches"] == ["main"]
 def test_the_test_workflow_runs_the_configured_required_suites():
    required = WORK_ITEM["workflow"]["required_tests"]
    assert required, "the helper's required tests are what CI exists to run"
    script = run_script(TEST_WORKFLOW, "suites")
    for command in required:
        assert command in script, f"CI does not run the configured suite: {command}"
 def test_the_deploy_workflow_waits_for_the_test_workflow_by_its_real_name():
    # Renaming either side without the other breaks this, which is the point: an
    # unmatched `workflow_run` filter does not fail, it simply never fires.
    awaited = triggers(DEPLOY_WORKFLOW)["workflow_run"]
    assert awaited["workflows"] == [TEST_WORKFLOW["name"]]
    assert awaited["types"] == ["completed"]
    assert awaited["branches"] == ["main"], "only main is deployable"
 def test_publishing_requires_the_test_run_to_have_succeeded_and_not_merely_finished():
    condition = DEPLOY_WORKFLOW["jobs"]["publish"]["if"]
    assert "workflow_run.conclusion == 'success'" in condition
    # `completed` includes failure and cancellation; the conclusion check is the gate.
    assert "gitea.event_name == 'workflow_run'" in condition
 def test_the_deploy_workflow_can_also_be_dispatched_by_hand():
    assert "workflow_dispatch" in triggers(DEPLOY_WORKFLOW)
 # ── what is published ────────────────────────────────────────────────────────
 def test_the_image_is_published_under_this_project_s_own_path():
    slug = WORK_ITEM["repository"]["slug"]
    assert DEPLOY_WORKFLOW["env"]["IMAGE"] == f"{REGISTRY}/{slug}"
 def test_both_latest_and_the_commit_are_pushed_so_a_rollback_is_a_tag_change():
    script = run_script(DEPLOY_WORKFLOW, "publish")
    assert 'docker push "$IMAGE:$SHA"' in script
    assert 'docker push "$IMAGE:latest"' in script
    # A `latest` without its commit tag would be a version that cannot be rolled back to.
    assert script.index('docker push "$IMAGE:$SHA"') < script.index('docker push "$IMAGE:latest"')
 def test_the_published_commit_is_the_one_that_was_tested():
    assert DEPLOY_WORKFLOW["env"]["SHA"].startswith("${{ gitea.event.workflow_run.head_sha")
    checkout = steps(DEPLOY_WORKFLOW, "publish")[0]
    assert checkout["with"]["ref"] == "${{ env.SHA }}"
 # ── secrets ──────────────────────────────────────────────────────────────────
 def test_registry_credentials_and_the_webhook_come_from_repository_secrets():
    script = run_script(DEPLOY_WORKFLOW, "publish")
    for secret in ("REGISTRY_USER", "REGISTRY_TOKEN", "PORTAINER_WEBHOOK_URL"):
        assert f"secrets.{secret}" in script
 def test_no_runtime_secret_is_named_by_the_pipeline_at_all():
    # The vision key, the Immich key, and the access secret belong to the Portainer
    # stack. A workflow that mentions one is a workflow that could carry one.
    text = TEST_FILE.read_text() + DEPLOY_FILE.read_text()
    for runtime_secret in (
        "PHOTO_PIPELINE_VISION_API_KEY",
        "PHOTO_PIPELINE_IMMICH_API_KEY",
        "PHOTO_PIPELINE_ACCESS_SECRET",
    ):
        assert runtime_secret not in text
 def test_the_workflows_carry_no_credential_values():
    text = TEST_FILE.read_text() + DEPLOY_FILE.read_text()
    for line in text.splitlines():
        if re.search(r"(?i)(token|secret|password|api[_-]?key)\s*[:=]", line):
            assert "${{ secrets." in line or line.lstrip().startswith("#"), line
 def test_the_registry_password_is_never_an_argument():
    # An argument is visible in the runner's process list and in `docker login`'s own
    # warning; stdin is not.
    script = run_script(DEPLOY_WORKFLOW, "publish") + run_script(DEPLOY_WORKFLOW, "dry-run")
    assert "--password-stdin" in script
    assert "--password " not in script
 # ── redeploy, pruning, and overlap ───────────────────────────────────────────
 def test_a_failed_webhook_call_fails_the_workflow():
    webhook = next(
        step
        for step in steps(DEPLOY_WORKFLOW, "publish")
        if "PORTAINER_WEBHOOK_URL" in step.get("run", "")
    )
    assert "--fail" in webhook["run"], "curl exits 0 on an HTTP 500 without it"
    assert "-k" not in webhook["run"].split(), "the redeploy call verifies TLS"
 def test_pruning_removes_dangling_layers_and_never_published_tags():
    for job in ("publish", "dry-run"):
        script = run_script(DEPLOY_WORKFLOW, job)
        assert "docker image prune -f" in script
        assert "prune -a" not in script and "--all" not in script
 def test_two_deploys_of_different_commits_cannot_overlap():
    guard = DEPLOY_WORKFLOW["concurrency"]
    assert "sha" not in guard["group"].lower(), "a per-commit group guards nothing"
    assert guard["cancel-in-progress"] is False, "a cancelled push leaves half a tag set"
 # ── the dry run ──────────────────────────────────────────────────────────────
 def test_the_dry_run_is_manual_only_and_defaults_to_on():
    condition = DEPLOY_WORKFLOW["jobs"]["dry-run"]["if"]
    assert condition == "gitea.event_name == 'workflow_dispatch' && inputs.dry_run"
    dispatch = triggers(DEPLOY_WORKFLOW)["workflow_dispatch"]
    assert dispatch["inputs"]["dry_run"]["default"] is True
    assert dispatch["inputs"]["dry_run"]["type"] == "boolean"
 def test_the_dry_run_publishes_a_scratch_tag_and_nothing_else():
    script = run_script(DEPLOY_WORKFLOW, "dry-run")
    assert 'docker push "$IMAGE:scratch-$SHA"' in script
    assert ":latest" not in script, "a dry run that moves latest is a deploy"
    assert "PORTAINER_WEBHOOK_URL" not in script, "a dry run never redeploys the stack"
 def test_a_manual_deploy_is_the_deliberate_choice_not_the_default():
    publish = DEPLOY_WORKFLOW["jobs"]["publish"]["if"]
    assert "inputs.dry_run == false" in publish
 # ── the files themselves ─────────────────────────────────────────────────────
 def test_every_workflow_file_parses_and_declares_a_name_a_trigger_and_a_job():
    files = sorted(WORKFLOWS.glob("*.yml")) + sorted(WORKFLOWS.glob("*.yaml"))
    assert {path.name for path in files} == {"test.yml", "deploy.yml"}
    for path in files:
        workflow = yaml.safe_load(path.read_text())
        assert workflow["name"], path
        assert triggers(workflow), path
        assert workflow["jobs"], path
        for job_name, job in workflow["jobs"].items():
            assert job["runs-on"], f"{path}:{job_name}"
            assert job["steps"], f"{path}:{job_name}"
            for step in job["steps"]:
                assert step.get("name"), f"{path}:{job_name} has an unnamed step"
--- a/tests/integration/test_docs_gate.py
+++ b/tests/integration/test_docs_gate.py
@@ -1,196 +0,0 @@
 """US09-05: the documentation gate's own contract, checked without a browser.
 The gate itself needs a browser and a server and takes minutes; what is checkable
 offline is what makes it a *gate* rather than a long test run:
 * it selects every documentation check by marker, so adding one is enough to put it
  in front of a release;
 * it accepts no skip at all — a check that did not run is a page nobody compared
  with the code;
 * it retains checksummed evidence per run;
 * CI runs it on pull requests, which is when a fix is still cheap.
 The checks it runs are the four suites written by US09-01 through US09-04.
 """
 from __future__ import annotations
 import json
 import re
 from pathlib import Path
 import pytest
 import yaml
 from photo_pipeline.config import Config
 from photo_pipeline.services import release
 REPO = Path(__file__).resolve().parents[2]
 DOCS = REPO / "docs"
 TEST_WORKFLOW = yaml.safe_load((REPO / ".gitea" / "workflows" / "test.yml").read_text())
 pytestmark = pytest.mark.phase_i
 # The suites the gate exists to run. Each is mapped to a story in the traceability
 # matrix, so this list is also what stops one being quietly dropped.
 DOCUMENTATION_SUITES = (
    "tests/integration/test_documentation.py",
    "tests/integration/test_installation_manual.py",
    "tests/integration/test_architecture_overview.py",
    "tests/integration/test_user_manual.py",
    "tests/integration/test_docs_gate.py",
    "tests/e2e/test_docs_ui.py",
    "tests/e2e/test_user_manual_screenshots.py",
 )
 def _config(tmp_path) -> Config:
    (tmp_path / "data").mkdir(exist_ok=True)
    return Config.from_env({"PHOTO_PIPELINE_DATA_DIR": str(tmp_path / "data")})
 # ── what the gate runs ───────────────────────────────────────────────────────
 def test_the_gate_selects_every_documentation_check_by_marker():
    assert release.DOCS_STAGES == (("documentation", ("tests", "-m", "phase_i")),)
    declared = [
        line
        for line in (REPO / "pyproject.toml").read_text().splitlines()
        if line.strip().startswith('"phase_i:')
    ]
    assert declared, "an unregistered marker selects nothing and fails no gate"
 def test_every_documentation_suite_carries_the_marker():
    """A documentation test without the marker is a check the gate never runs."""
    unmarked = [
        suite
        for suite in DOCUMENTATION_SUITES
        if "pytest.mark.phase_i" not in (REPO / suite).read_text()
    ]
    assert unmarked == [], f"suites missing the phase_i marker: {unmarked}"
 def test_the_marker_selects_nothing_outside_the_documentation_suites():
    """Scope matters: the gate's promise is that it ran *the documentation checks*."""
    marked = sorted(
        str(path.relative_to(REPO))
        for path in (REPO / "tests").rglob("test_*.py")
        if "pytest.mark.phase_i" in path.read_text()
    )
    assert marked == sorted(DOCUMENTATION_SUITES)
 # ── no skip is an environment limit here ─────────────────────────────────────
 def test_the_gate_accepts_no_skipped_check_at_all():
    assert release.DOCS_ALLOWED_SKIP_REASONS == ()
    skipped = release.StageResult(
        "documentation", [], 0, 0.1, "1 skipped", ["SKIPPED [1] x.py:1: exiftool not installed"]
    )
    # The release gate tolerates this one because it describes the machine. The
    # documentation gate cannot: nothing here depends on the machine.
    assert release.unexpected_skips([skipped]) == []
    assert release.unexpected_skips([skipped], release.DOCS_ALLOWED_SKIP_REASONS) == [
        "SKIPPED [1] x.py:1: exiftool not installed"
    ]
 def test_a_skipped_check_fails_the_run_and_the_evidence_says_so(tmp_path):
    skipping = tmp_path / "test_skipping.py"
    skipping.write_text(
        "import pytest\n\ndef test_x():\n    pytest.skip('exiftool not installed')\n"
    )
    evidence = tmp_path / "evidence"
    report = release.run_gate(
        _config(tmp_path),
        output=evidence,
        stages=(("documentation", (str(skipping),)),),
        allowed_skips=release.DOCS_ALLOWED_SKIP_REASONS,
    )
    assert report["ok"] is False
    assert report["failures"] == [], "the stage passed; the skip is what fails the gate"
    assert report["unexpected_skips"], report
    written = json.loads((evidence / release.REPORT_NAME).read_text())
    assert written["ok"] is False
    assert (evidence / "logs" / "documentation.log").exists()
    for line in (evidence / release.CHECKSUMS_NAME).read_text().splitlines():
        digest, name = line.split("  ", 1)
        assert release.sha256_file(evidence / name) == digest
 def test_a_broken_documentation_check_fails_the_gate(tmp_path):
    """The failure mode that matters: a page and the code disagreeing."""
    failing = tmp_path / "test_disagreement.py"
    failing.write_text(
        "def test_the_manual_matches_the_code():\n"
        "    documented = {'lock_held'}\n"
        "    emitted = {'lock_held', 'renamed_since'}\n"
        "    assert emitted <= documented\n"
    )
    report = release.run_gate(
        _config(tmp_path),
        output=tmp_path / "evidence",
        stages=(("documentation", (str(failing),)),),
        allowed_skips=release.DOCS_ALLOWED_SKIP_REASONS,
    )
    assert report["ok"] is False
    assert report["failures"], report
 def test_a_clean_tree_passes(tmp_path):
    passing = tmp_path / "test_passing.py"
    passing.write_text("def test_x():\n    assert True\n")
    report = release.run_gate(
        _config(tmp_path),
        output=tmp_path / "evidence",
        stages=(("documentation", (str(passing),)),),
        allowed_skips=release.DOCS_ALLOWED_SKIP_REASONS,
    )
    assert report["ok"] is True and report["unexpected_skips"] == []
    assert report["revision"], "the evidence must say which commit it covers"
 # ── the command, and CI ──────────────────────────────────────────────────────
 def test_the_command_is_documented_and_wired():
    assert "docs-gate" in (REPO / "photo_pipeline" / "__main__.py").read_text()
    assert "docs-gate" in (DOCS / "index.md").read_text()
 def test_ci_runs_the_gate_on_pull_requests_and_keeps_its_evidence():
    job = TEST_WORKFLOW["jobs"]["documentation"]
    # No `if:` — documentation drifts on the same commits that change behaviour, and
    # the pull request is when saying so is still cheap.
    assert "if" not in job
    assert "pull_request" in TEST_WORKFLOW[True] or "pull_request" in TEST_WORKFLOW.get("on", {})
    script = "\n".join(step["run"] for step in job["steps"] if "run" in step)
    assert "photo_pipeline docs-gate" in script
    evidence = next(step for step in job["steps"] if "upload-artifact" in str(step.get("uses")))
    assert evidence["if"] == "always()", "a failed gate's evidence is the one worth keeping"
 # ── the pages and the repository point at each other ─────────────────────────
 def test_the_readme_and_the_documentation_index_link_to_each_other():
    """Neither may become the forgotten copy."""
    readme = (REPO / "README.md").read_text()
    index = (DOCS / "index.md").read_text()
    assert "docs/index.md" in readme
    assert re.search(r"\.\./README\.md", index), "the index does not link back to the README"
 def test_every_documentation_story_is_mapped_in_the_traceability_matrix():
    matrix = json.loads((REPO / "tests" / "story_traceability.json").read_text())["stories"]
    for story in ("US09-01", "US09-02", "US09-03", "US09-04", "US09-05"):
        assert matrix.get(story), f"{story} is not mapped to any test"
--- a/tests/integration/test_documentation.py
+++ b/tests/integration/test_documentation.py
@@ -1,184 +0,0 @@
 """US09-01: the documentation the application serves, checked without a browser.
 What is checkable offline is everything that makes the manuals *navigable* rather
 than merely present: every page reachable, every internal link and anchor landing
 somewhere real, the vendored renderer being the file that was pinned, and the
 application actually serving `docs/` in both the working copy and the image.
 The rendering itself — marked, mermaid, anchors, link rewriting — is proven in a
 real browser by ``tests/e2e/test_docs_ui.py``.
 """
 from __future__ import annotations
 import hashlib
 import json
 import re
 from pathlib import Path
 import pytest
 from starlette.testclient import TestClient
 from photo_pipeline.api.app import create_app
 from photo_pipeline.api.security import DEFAULT_HEADERS
 from photo_pipeline.config import Config
 # Every check here belongs to the documentation gate (US09-05).
 pytestmark = pytest.mark.phase_i
 REPO = Path(__file__).resolve().parents[2]
 DOCS = REPO / "docs"
 VENDOR = REPO / "frontend" / "js" / "vendor"
 INDEX = DOCS / "index.md"
 MARKDOWN_LINK = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)")
 HEADING = re.compile(r"^#{1,6}\s+(.+?)\s*$", re.MULTILINE)
 FENCE = re.compile(r"^```.*?^```", re.MULTILINE | re.DOTALL)
 def pages() -> list[Path]:
    return sorted(DOCS.rglob("*.md"))
 def body(path: Path) -> str:
    """A document without its fenced code, so an example link in a shell snippet is
    not mistaken for a link the reader can follow."""
    return FENCE.sub("", path.read_text())
 def slug(text: str) -> str:
    """The heading-anchor rule, mirroring ``frontend/js/docs.js``.
    Deliberately duplicated: this check has to run without a browser. The browser
    test is the authority on the real behaviour, and it asserts the same anchors.
    """
    cleaned = re.sub(r"[^\w\s-]", "", text.lower(), flags=re.UNICODE).strip()
    return re.sub(r"[\s-]+", "-", cleaned).strip("-") or "section"
 def anchors(path: Path) -> set[str]:
    found: dict[str, int] = {}
    for heading in HEADING.findall(body(path)):
        # Markdown emphasis and inline code are not part of the rendered text.
        plain = re.sub(r"[*`_]", "", heading)
        base = slug(plain)
        found[base] = found.get(base, 0) + 1
    return {name if index == 1 else f"{name}-{index}" for name, count in found.items() for index in range(1, count + 1)}
 def internal_links(path: Path) -> list[str]:
    return [
        href
        for href in MARKDOWN_LINK.findall(body(path))
        if not re.match(r"^[a-z][a-z\d+.-]*:", href, re.IGNORECASE) and not href.startswith("//")
    ]
 # ── the documentation tree ───────────────────────────────────────────────────
 def test_the_index_exists_and_names_every_page():
    """A page nobody links to is a page nobody reads."""
    assert INDEX.is_file()
    listed = {
        (INDEX.parent / href.split("#")[0]).resolve()
        for href in internal_links(INDEX)
        if href.split("#")[0].endswith(".md")
    }
    unreachable = [page.name for page in pages() if page != INDEX and page.resolve() not in listed]
    assert unreachable == [], f"not linked from the index: {unreachable}"
 def test_every_internal_link_and_anchor_resolves():
    broken: list[str] = []
    for page in pages():
        for href in internal_links(page):
            target, _, anchor = href.partition("#")
            destination = page if not target else (page.parent / target).resolve()
            if not destination.is_file():
                broken.append(f"{page.name} → {href} (no such file)")
                continue
            if anchor and anchor not in anchors(destination):
                broken.append(f"{page.name} → {href} (no such heading)")
    assert broken == [], broken
 def test_every_page_starts_with_one_title():
    for page in pages():
        titles = [line for line in page.read_text().splitlines() if line.startswith("# ")]
        assert len(titles) == 1, f"{page.name} has {len(titles)} top-level titles"
 # ── the vendored renderer ────────────────────────────────────────────────────
 def test_the_vendored_libraries_are_the_files_that_were_pinned():
    """A vendored dependency without a recorded checksum is a dependency nobody is
    reviewing. Replacing one has to be a visible change to this manifest."""
    manifest = json.loads((VENDOR / "VERSIONS.json").read_text())
    recorded = {entry["file"]: entry for entry in manifest["libraries"]}
    on_disk = {path.name for path in VENDOR.iterdir() if path.suffix in (".js", ".mjs")}
    assert on_disk == set(recorded), f"unrecorded vendored files: {on_disk ^ set(recorded)}"
    for name, entry in recorded.items():
        digest = hashlib.sha256((VENDOR / name).read_bytes()).hexdigest()
        assert digest == entry["sha256"], f"{name} does not match the pinned checksum"
        assert entry["version"] in entry["url"], f"{name}: the pinned URL and version disagree"
        assert entry["license"], f"{name}: no license recorded"
 def test_the_documentation_view_is_wired_into_the_shell():
    shell = (REPO / "frontend" / "index.html").read_text()
    assert 'data-nav="docs"' in shell, "the manuals are unreachable from the navigation"
    assert '"/docs"' in (REPO / "frontend" / "js" / "app.js").read_text()
 # ── the policy the view runs under ───────────────────────────────────────────
 def test_the_script_boundary_is_unchanged_and_only_style_was_relaxed():
    """The measured cost of rendering diagrams in the browser, held to that cost.
    mermaid needs to style the SVG it builds, which `style-src 'self'` refuses. It
    does not need to execute generated code, so `script-src` must never acquire the
    escape hatch that would let injected markup run.
    """
    policy = DEFAULT_HEADERS["content-security-policy"]
    directives = {
        part.split(" ")[0]: part.split(" ")[1:]
        for part in (piece.strip() for piece in policy.split(";"))
        if part
    }
    assert directives["script-src"] == ["'self'"]
    assert "'unsafe-inline'" in directives["style-src"]
    for directive in ("default-src", "img-src", "connect-src", "font-src"):
        assert "'self'" in directives[directive]
        assert "'unsafe-inline'" not in directives[directive]
    assert directives["frame-ancestors"] == ["'none'"]
 # ── serving it ───────────────────────────────────────────────────────────────
 def test_the_application_serves_the_markdown_without_a_session(tmp_path):
    """Whoever cannot get past the access secret is exactly who needs these pages."""
    config = Config.from_env({"PHOTO_PIPELINE_DATA_DIR": str(tmp_path / "data")})
    (tmp_path / "data").mkdir()
    with TestClient(create_app(config), raise_server_exceptions=False) as client:
        response = client.get("/docs/index.md", headers={"cookie": ""})
        assert response.status_code == 200
        assert "Photo Pipeline documentation" in response.text
        assert client.get("/docs/overview.md").status_code == 200
        assert client.get("/docs/nothing-here.md").status_code == 404
        # The mount is a directory, not a path parameter: nothing above it is reachable.
        assert client.get("/docs/../pyproject.toml").status_code in (307, 404)
        assert client.get("/docs/%2e%2e/pyproject.toml").status_code == 404
 def test_the_image_ships_the_documentation_it_serves():
    """An image without `docs/` serves an empty manual — and the build context is
    deny-by-default, so a new directory is excluded until it is named."""
    assert "\n!docs\n" in (REPO / ".dockerignore").read_text()
    assert "COPY docs ./docs" in (REPO / "Dockerfile").read_text()
--- a/tests/integration/test_installation_manual.py
+++ b/tests/integration/test_installation_manual.py
@@ -1,183 +0,0 @@
 """US09-02: the installation manual, checked against the thing it describes.
 Documentation rots quietly. A setting is renamed, a command grows a flag, an exit
 code changes meaning — and the manual keeps confidently saying the old thing until
 somebody follows it into a bad afternoon. So every fact in it that the code also
 knows is compared with the code, in both directions where both directions are
 meaningful: a setting the manual invents fails, and a setting the manual forgot
 fails too.
 """
 from __future__ import annotations
 import re
 import subprocess
 import sys
 from functools import lru_cache
 from pathlib import Path
 import pytest
 from photo_pipeline.config import ENV_PREFIX, LEGACY_ALIASES, Config
 # Every check here belongs to the documentation gate (US09-05).
 pytestmark = pytest.mark.phase_i
 REPO = Path(__file__).resolve().parents[2]
 MANUAL = REPO / "docs" / "installation.md"
 MAIN = REPO / "photo_pipeline" / "__main__.py"
 TEXT = MANUAL.read_text()
 ENV_NAMES = re.compile(rf"{ENV_PREFIX}[A-Z0-9_]+")
 # Read by docker-compose.yml, not by Config. They are configuration an installer sets,
 # so the manual documents them; they are simply not application settings.
 COMPOSITION_ONLY = {
    f"{ENV_PREFIX}IMAGE",
    f"{ENV_PREFIX}LIBRARY_HOST_PATH",
    f"{ENV_PREFIX}PUBLISH_ADDRESS",
    f"{ENV_PREFIX}UID",
    f"{ENV_PREFIX}GID",
    f"{ENV_PREFIX}ENV_FILE",  # read before Config exists, so it is not a field
 }
 def documented_env_names() -> set[str]:
    return set(ENV_NAMES.findall(TEXT))
@lru_cache
 def cli_help(*args: str) -> str:
    """What the CLI says about itself, asked the way an operator asks."""
    result = subprocess.run(
        [sys.executable, "-m", "photo_pipeline", *args, "--help"],
        cwd=REPO,
        capture_output=True,
        text=True,
        timeout=120,
        check=False,
    )
    assert result.returncode == 0, result.stderr
    return result.stdout
@lru_cache
 def cli_commands() -> frozenset[str]:
    listed = re.search(r"\{([a-z0-9,\-]+)\}", cli_help())
    assert listed, f"the CLI listed no subcommands:\n{cli_help()}"
    return frozenset(listed.group(1).split(","))
 def cli_flags(command: str) -> frozenset[str]:
    return frozenset(re.findall(r"--[a-z][a-z-]+", cli_help(command)))
 # ── settings ─────────────────────────────────────────────────────────────────
 def test_every_setting_is_documented():
    """A setting nobody documents is a setting nobody configures deliberately."""
    expected = {f"{ENV_PREFIX}{field.upper()}" for field in Config.model_fields}
    missing = sorted(expected - documented_env_names())
    assert missing == [], f"undocumented settings: {missing}"
 def test_the_manual_invents_no_settings():
    unknown = sorted(
        name
        for name in documented_env_names()
        if name.removeprefix(ENV_PREFIX).lower() not in Config.model_fields
        and name not in COMPOSITION_ONLY
    )
    assert unknown == [], f"documented but not a real setting: {unknown}"
 def test_the_documented_defaults_are_the_real_defaults():
    """Spot-checked where a wrong default is actively dangerous: the bind address,
    the trust boundary, and the gate that protects an irreplaceable library."""
    assert Config.model_fields["host"].default == "127.0.0.1"
    assert "`PHOTO_PIPELINE_HOST` | `127.0.0.1`" in TEXT
    assert Config.model_fields["allowed_hosts"].default == ()
    assert Config.model_fields["require_dry_run_approval"].default is False
    assert "`PHOTO_PIPELINE_REQUIRE_DRY_RUN_APPROVAL` | `false`" in TEXT
 def test_every_secret_is_marked_as_one():
    for field in ("access_secret", "vision_api_key", "immich_api_key"):
        name = f"{ENV_PREFIX}{field.upper()}"
        row = next(line for line in TEXT.splitlines() if line.startswith(f"| `{name}`"))
        assert "secret" in row.lower(), f"{name} is not marked as a secret"
 def test_the_legacy_aliases_are_documented():
    """An operator with an existing photo_analyzer.env needs to know it still works."""
    for alias in LEGACY_ALIASES:
        assert alias in TEXT, f"legacy alias {alias} is undocumented"
 # ── commands ─────────────────────────────────────────────────────────────────
 # The manual is an installation and operations manual, not a command reference: these
 # are the commands an installer actually runs, and every one of them must exist.
 OPERATIONAL = ("migrate", "serve", "worker", "backup", "verify-backup", "restore", "diagnostics")
 def test_every_command_the_manual_tells_you_to_run_exists():
    missing = [name for name in OPERATIONAL if name not in cli_commands()]
    assert missing == [], f"the manual names commands the CLI does not have: {missing}"
    undocumented = [name for name in OPERATIONAL if not re.search(rf"\b{re.escape(name)}\b", TEXT)]
    assert undocumented == [], f"operational commands the manual omits: {undocumented}"
 def test_every_documented_flag_exists_on_the_command_it_is_shown_with():
    for command, flag in (
        ("backup", "--reason"),
        ("backup", "--keep"),
        ("restore", "--into"),
        ("worker", "--allow-legacy"),
        ("serve", "--allow-legacy"),
    ):
        assert flag in cli_flags(command), f"{command} has no {flag}"
        assert flag in TEXT, f"{flag} is undocumented"
 # ── exit codes ───────────────────────────────────────────────────────────────
 def test_every_documented_exit_code_is_one_the_cli_can_return():
    documented = {int(code) for code in re.findall(r"^\| `(\d)` \|", TEXT, re.MULTILINE)}
    returned = {int(code) for code in re.findall(r"^\s+return (\d)$", MAIN.read_text(), re.MULTILINE)}
    assert documented, "no exit codes are documented"
    assert documented <= returned | {0}, f"documented but unreachable: {sorted(documented - returned)}"
 def test_every_refusal_exit_code_is_documented():
    """0 is success and 1 is 'it said why'; every other code is a specific refusal an
    operator will meet at startup, and meeting an undocumented one is the worst case."""
    returned = {int(code) for code in re.findall(r"^\s+return (\d)$", MAIN.read_text(), re.MULTILINE)}
    documented = {int(code) for code in re.findall(r"^\| `(\d)` \|", TEXT, re.MULTILINE)}
    missing = sorted(code for code in returned if code not in documented and code != 0)
    assert missing == [], f"undocumented exit codes: {missing}"
 # ── the promises the manual makes ────────────────────────────────────────────
 def test_the_manual_carries_no_credential_shaped_example():
    """The repository's own scanner refuses these in a commit; a manual is exactly
    where a real-looking one gets copied from."""
    suspicious = re.findall(
        r"(?i)(api[_-]?key|secret|token|password)\s*[=:]\s*[\"']?([A-Za-z0-9_\-]{12,})",
        TEXT,
    )
    assert suspicious == [], f"credential-shaped example: {suspicious}"
 def test_the_manual_states_the_invariants_an_installer_must_not_break():
    for invariant in ("_IGNORE/", "One writer", "EXIF is verified before upload"):
        assert invariant in TEXT, f"the manual does not state: {invariant}"
 def test_the_manual_is_reachable_from_the_index():
    assert "installation.md" in (REPO / "docs" / "index.md").read_text()
--- a/tests/integration/test_user_manual.py
+++ b/tests/integration/test_user_manual.py
@@ -1,177 +0,0 @@
 """US09-04: the user manual, checked against the application it describes.
 The manual's most perishable claim is its error catalogue: a code renamed in a route
 leaves a page confidently explaining something that can no longer happen, and the
 operator meeting the new code finds nothing. So the catalogue is compared with the
 codes the application can actually emit, in both directions.
 The screenshots are generated and checked by
 ``tests/e2e/test_user_manual_screenshots.py``.
 """
 from __future__ import annotations
 import re
 from pathlib import Path
 import pytest
 REPO = Path(__file__).resolve().parents[2]
 DOCS = REPO / "docs"
 STAGES = DOCS / "stages"
 PACKAGE = REPO / "photo_pipeline"
 ERRORS = (DOCS / "errors.md").read_text()
 ALL_DOCS = "\n".join(path.read_text() for path in DOCS.rglob("*.md"))
 # The shapes an error code is emitted in. Everything the API returns goes through one
 # of these, so the set they find is the set an operator can meet.
 EMITTERS = (
    re.compile(r'_error\(\s*\d+,\s*"([a-z_]+)"'),
    # The status may be a literal or an exception's own code, so match either.
    re.compile(r'_envelope\(\s*[\w.]+,\s*"([a-z_]+)"'),
    re.compile(r'"code":\s*"([a-z_]+)"'),
    re.compile(r'code="([a-z_]+)"'),
    re.compile(r'Refusal\(\s*\d+,\s*"([a-z_]+)"'),
 )
 # Codes raised deep in a service and mapped to a response by its route; they are what
 # the browser shows, so the manual owes the reader an entry.
 SERVICE_CODES = {
    "lock_held",
    "path_not_allowed",
    "rename_recovery_required",
    "stale_preflight",
    "access_denied",
    "too_many_attempts",
 }
 STAGE_PAGES = (
    "inventory",
    "duplicates",
    "safety",
    "analysis",
    "albums",
    "renames",
    "uploads",
    "archive",
    "diagnostics",
 )
 # Every check here belongs to the documentation gate (US09-05).
 pytestmark = pytest.mark.phase_i
 def emitted_codes() -> set[str]:
    found: set[str] = set()
    for path in PACKAGE.rglob("*.py"):
        text = path.read_text()
        for pattern in EMITTERS:
            found |= set(pattern.findall(text))
    for code in SERVICE_CODES:
        assert re.search(rf'"{code}"', "\n".join(p.read_text() for p in PACKAGE.rglob("*.py"))), (
            f"{code} is documented as a service code but no longer exists"
        )
    return (found | SERVICE_CODES) - {"code"}
 def documented_codes() -> set[str]:
    return set(re.findall(r"`([a-z][a-z_]{3,})`", ERRORS))
 # ── the error catalogue ──────────────────────────────────────────────────────
 def test_every_error_the_application_can_emit_is_documented():
    missing = sorted(emitted_codes() - documented_codes())
    assert missing == [], f"undocumented error codes: {missing}"
 def test_the_catalogue_documents_no_code_that_cannot_happen():
    """Backticked snake_case in the catalogue is either a code, a setting, or one of
    the handful of prose terms below."""
    prose = {
        "diagnostics",
        "dry_run",
        "approve_dry_run",
        "current_path",
        "archived_online",
        "archived_offline",
    }
    settings = set(re.findall(r"PHOTO_PIPELINE_[A-Z_]+", ERRORS))
    invented = sorted(
        code
        for code in documented_codes()
        if code not in emitted_codes()
        and code not in prose
        and f"PHOTO_PIPELINE_{code.upper()}" not in settings
    )
    assert invented == [], f"documented but not emitted anywhere: {invented}"
 def test_the_protective_refusals_are_explained_as_intentional():
    """These are the ones a reader is most likely to mistake for a broken
    application, which is exactly when they start working around them."""
    for code in ("lock_held", "rename_recovery_required", "stale_preflight", "not_runnable"):
        row = next(line for line in ERRORS.splitlines() if line.startswith(f"| `{code}`"))
        assert len(row.split("|")) >= 4, f"{code} has no cause and remedy"
 # ── the stage pages ──────────────────────────────────────────────────────────
 def test_there_is_one_page_per_workflow_stage():
    missing = [name for name in STAGE_PAGES if not (STAGES / f"{name}.md").is_file()]
    assert missing == [], f"stages without a page: {missing}"
 def test_every_stage_page_answers_the_four_questions():
    """The shape is the point: a page that skips 'what it changes' is the page
    somebody needed."""
    for name in STAGE_PAGES:
        text = (STAGES / f"{name}.md").read_text()
        for question in ("What it is for.", "What you decide.", "What it changes.", "What it refuses."):
            assert question in text, f"{name}.md does not answer: {question}"
 def test_every_stage_page_shows_a_screenshot():
    for name in STAGE_PAGES:
        text = (STAGES / f"{name}.md").read_text()
        assert re.search(r"!\[[^\]]+\]\(\.\./images/[a-z-]+\.png\)", text), (
            f"{name}.md carries no screenshot"
        )
 def test_the_guided_pass_names_the_irreversible_stages():
    first_pass = (DOCS / "first-pass.md").read_text()
    for stage in ("renames", "uploads", "archive"):
        assert f"stages/{stage}.md" in first_pass
    assert "point" in first_pass.lower() and "no return" in first_pass.lower()
 def test_recovery_covers_each_interruption_the_application_can_survive():
    recovery = (DOCS / "recovery.md").read_text()
    for topic in (
        "interrupted rename",
        "uncertain upload",
        "failed migration",
        "restored backup",
    ):
        assert topic in recovery.lower(), f"recovery does not cover: {topic}"
 def test_the_manual_is_reachable_from_the_index():
    index = (DOCS / "index.md").read_text()
    for page in [f"stages/{name}.md" for name in STAGE_PAGES] + [
        "first-pass.md",
        "errors.md",
        "recovery.md",
    ]:
        assert page in index, f"{page} is not linked from the index"
 def test_the_screenshots_are_declared_as_generated():
    """The allow list had to be widened for them, so the reason has to be visible
    where the widening is."""
    config = (REPO / "work_item" / ".work-item.yml").read_text()
    assert "docs/images/**" in config
    assert "test_user_manual_screenshots.py" in config, "no note saying who generates them"
--- a/tests/story_traceability.json
+++ b/tests/story_traceability.json
@@ -178,41 +178,13 @@
    "US08-01": [
      "tests/unit/test_security_policy.py",
      "tests/integration/test_trusted_hosts.py"
    ],
    "US08-02": [
      "tests/integration/test_container_image.py",
      "tests/e2e/test_container_runtime.py"
    ],
    "US08-03": [
      "tests/integration/test_compose_runtime.py",
      "tests/e2e/test_compose_stack.py"
    ],
    "US08-04": [
      "tests/integration/test_deploy_workflows.py"
    ],
    "US08-05": [
      "tests/integration/test_container_gate.py",
      "tests/e2e/test_phase_h_container.py"
    ],
    "US09-01": [
      "tests/integration/test_documentation.py",
      "tests/e2e/test_docs_ui.py"
    ],
    "US09-02": [
      "tests/integration/test_installation_manual.py"
    ],
    "US09-03": [
      "tests/integration/test_architecture_overview.py",
      "tests/e2e/test_docs_ui.py"
    ],
    "US09-04": [
      "tests/integration/test_user_manual.py",
      "tests/e2e/test_user_manual_screenshots.py"
    ],
    "US09-05": [
      "tests/integration/test_docs_gate.py"
    ]
  },
-  "planned": [],
+  "planned": [
    "US08-02",
    "US08-03",
    "US08-04",
    "US08-05"
  ],
  "_planned_comment": "Accepted backlog stories that are not implemented yet. The release gate (US07-07) requires every story file to be either mapped to tests or listed here, so an unimplemented story is a visible decision rather than a hole in the matrix."
 }
--- a/work_item/.work-item.yml
+++ b/work_item/.work-item.yml
@@ -16,9 +16,6 @@ safety:
  max_file_bytes: 5000000
  allow:
    - tests/fixtures/**
    # Generated by tests/e2e/test_user_manual_screenshots.py from a synthetic fixture
    # library, never a real photo. The deny list below blocks images by default.
    - docs/images/**
  deny:
    - _IGNORE/**
    - "**/_IGNORE/**"