Merge pull request 'FabledCurator can now tell you one of its own parts has stopped' (#250) from dev into main

The ask was a surface AND a path. The path is the part that was missing —
everything that could answer "is it running" lived inside Settings, which you
only open once you already suspect something.

**Re-used the indicator that already existed rather than adding a fourth.**
There were three partial surfaces: TopNav's health dot, PipelineStatusChip's
pulse, and the Settings Activity tab. None answered "is every part alive", and
a fourth would have made the question harder to answer, not easier.

TopNav's dot read /api/health — a no-DB liveness check proving only that the
WEB container is serving. Green there while a worker was dead is exactly what
it looked like, and a green dot beside the product name gets read as
"everything is fine". It now reflects the whole-stack verdict, and it is a
link: the place someone already looks when they suspect something is now also
the way to the detail.

The tooltip names the actual problem. "Scheduler has not checked in for 6 min"
sends someone somewhere; "something is unhealthy" sends them hunting.

/system is deliberately NOT in the nav row — TopNav builds that from routes
with a meta.title, and a sixth top-level tab for a page visited twice a year
costs more attention than it returns. It is reached from the dot.

The page lists every learned part with its state as a sentence rather than a
chip, and prints the staleness thresholds it was judged by, taken from the
endpoint so the UI keeps no second copy of them. PipelineStatusChip still
hand-rolls its own 3-minute scheduler window; that is now a duplicate of a
threshold the server owns, and worth collapsing once this has been watched
working.

The stores stay separate on purpose: system.js is "can I reach the API",
systemActivity.js is "what is the pipeline doing", systemHealth.js is "is
anything broken". Running and alive fail independently — an idle stack with a
dead worker looks identical to a healthy one on every activity surface, which
is the whole reason this milestone exists.

Not yet verified against a real stopped service. Rule 12 keeps a local stack
out of it, and frontend CI has no Vue type-check or visual regression, so this
needs an operator look rather than a green lane.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TTjbZZ6JirCMSaJzQV1RhA

.env.example

@@ -1,24 +1,103 @@
-# Database
-DB_USER=fabledcurator
-DB_PASSWORD=changeme_use_a_real_password
-DB_HOST=postgres
-DB_PORT=5432
-DB_NAME=fabledcurator
+# FabledCurator configuration.
+#
+# Copy to `.env` and edit before your first production start:
+#
+#     cp .env.example .env
+#
+# Only the two values under CHANGE THESE actually need your attention. The
+# rest have working defaults baked into docker-compose.yml and are listed
+# here so you know they exist, not because you have to set them.
+#
+# Almost nothing else lives here on purpose. FabledCurator is configured from
+# its own Settings UI, backed by the database — no restart, no YAML. If you
+# are looking for where to set an import path, a download schedule or an ML
+# threshold, it is in the app, not in this file.
 
-# Redis / Celery
-CELERY_BROKER_URL=redis://redis:6379/0
-CELERY_RESULT_BACKEND=redis://redis:6379/0
 
-# App
-# Generate with: openssl rand -hex 32
-SECRET_KEY=changeme_32_byte_hex_secret
+# ---------------------------------------------------------------------------
+# CHANGE THESE
+# ---------------------------------------------------------------------------
 
-# Extension API key — used in FC-3, lands later but reserved now
-# Generate with: openssl rand -hex 32
-EXTENSION_API_KEY=
+# The Postgres password. docker-compose.yml falls back to a published default
+# (`fabledcurator_dev`) so that `docker compose up` works with no config at
+# all — which is exactly why you must not leave it at that on a real install.
+# It is the credential protecting your stored platform session cookies.
+DB_PASSWORD=
 
-# Logging
+# Sets Quart's app.secret_key. Today it signs nothing: FabledCurator has no
+# login and uses no session cookies, so no value here is protecting anything
+# right now. Set it anyway. It is required at boot rather than defaulted so
+# that the day something session-backed does land, no instance is already
+# running on a value published in this file.
+#
+#     openssl rand -hex 32
+SECRET_KEY=
+
+
+# ---------------------------------------------------------------------------
+# FIRST BOOT ONLY — then delete this line
+# ---------------------------------------------------------------------------
+
+# FabledCurator encrypts your stored platform credentials with a Fernet key it
+# keeps at /images/secrets/credential_key.b64 — inside the ./images bind mount,
+# so it outlives the container. On a brand-new install that file does not exist
+# yet, and the app REFUSES TO START rather than quietly create one:
+#
+#     MissingCredentialKey: Fernet key file not found at
+#     /images/secrets/credential_key.b64
+#
+# That refusal is deliberate. Auto-creating a key is indistinguishable from the
+# disaster case — a restore that brought the database back but lost
+# ./images/secrets — and there it would mint a key that cannot decrypt anything,
+# leaving an instance that looks healthy while every paywalled download fails.
+# So the choice is yours to make explicitly, once.
+#
+# Set this for your first `up`, watch the container come up, then DELETE THE
+# LINE. Leaving it set disarms the protection permanently, on an instance that
+# by then has credentials worth protecting.
+#
+# BACK UP ./images/secrets/ ALONGSIDE YOUR DATABASE. The key is the only thing
+# that can read your stored credentials; a database restored without it needs
+# every credential re-entered by hand.
+CURATOR_BOOTSTRAP_NEW_KEY=1
+
+
+# ---------------------------------------------------------------------------
+# Optional — defaults are fine
+# ---------------------------------------------------------------------------
+
+# Host port the UI is published on. The container always listens on 8080;
+# this is only the left-hand side of the port mapping.
+PORT=8080
+
+# DEBUG | INFO | WARNING | ERROR
 LOG_LEVEL=INFO
 
-# Deployment posture: plain HTTP (no TLS in the app; reverse proxy if needed)
-# See docs/superpowers/specs/2026-05-13-fabledcurator-merge-design.md §2.1
+# Postgres identity. Change these only if you are pointing at a database you
+# manage yourself — the bundled postgres service is created with whatever is
+# set here, so changing them after the first start will not rename anything.
+DB_USER=fabledcurator
+DB_NAME=fabledcurator
+
+# Set by docker-compose.yml to reach the bundled services. Override only when
+# running Postgres or Redis outside this stack.
+# DB_HOST=postgres
+# DB_PORT=5432
+# CELERY_BROKER_URL=redis://redis:6379/0
+# CELERY_RESULT_BACKEND=redis://redis:6379/0
+
+
+# ---------------------------------------------------------------------------
+# There is no authentication variable here, and that is not an omission
+# ---------------------------------------------------------------------------
+#
+# FabledCurator has no login, no accounts and no permission model. Anything
+# that can reach PORT is an administrator and can read the platform session
+# cookies the app stores for Patreon, SubscribeStar and Pixiv.
+#
+# Bind it to a trusted network. See "Before you expose it" in README.md and
+# the deployment posture section of SECURITY.md.
+#
+# The Firefox extension's API key is NOT configured here — it is generated
+# automatically on first use and shown under Settings → Maintenance, where you
+# can also rotate it.

.forgejo/workflows/baseline.yml

@@ -0,0 +1,349 @@
+
+# TEMPORARY — milestone 328. Delete once the baseline has shipped and settled.
+#
+# Collapsing 89 alembic revisions into one baseline has exactly one dangerous
+# failure: the baseline does not reproduce the schema the chain produced, and
+# the divergence surfaces later, on the operator's live data, in whatever
+# migration comes next.
+#
+# So the comparison happens in CI, against a throwaway pgvector Postgres, where
+# nothing is at risk. It answers one question: does `upgrade head` on the
+# collapsed tree produce the same schema as `upgrade head` on the full chain?
+#
+# The chain is read out of GIT, not the working tree, which is what lets this
+# keep working now that the revisions are deleted — `chain_ref` names a commit
+# that still carries 0001..0089. That is the whole reason this is a workflow
+# rather than a script someone ran once.
+#
+# WHAT THIS CANNOT SEE, and it matters: the comparison is of SCHEMA. Migrations
+# 0002 and 0003 also INSERTED rows (the import_settings and ml_settings
+# singletons), and the application reads those with scalar_one(), which raises
+# on an empty result. A baseline that omitted them would produce an identical
+# schema, pass this check with a perfect diff, and crash a fresh install on its
+# first settings access. Only running the app against a new database finds
+# that class of defect. Do not read a green run here as "the baseline is
+# correct" — read it as "the schema is correct".
+#
+# Autogenerate now emits nearly all of the baseline unaided, which was NOT true
+# before #3275 put the previously migration-only objects onto the models — the
+# HNSW index with its opclass, the COALESCE expression index, the partial
+# unique indexes, 107 server_defaults, the enum CHECKs. An earlier attempt at
+# this squash was reverted precisely because the generator dropped them all
+# silently. What still needs hand-adding is only what cannot live in a model:
+# the two CREATE EXTENSION statements, the two seed rows, and the pgvector
+# import the generator forgets to write.
+name: Alembic baseline
+
+on:
+  workflow_dispatch:
+    inputs:
+      chain_ref:
+        description: 'Commit/tag carrying the full 0001..0089 chain (pinned: the tree no longer has it)'
+        type: string
+        default: '725bf15'
+      mode:
+        description: 'chain = compare against this tree''s migrations; models = compare against a schema built from the MODELS'
+        type: string
+        default: 'chain'
+
+jobs:
+  compare:
+    runs-on: python-ci
+    container:
+      image: git.fabledsword.com/bvandeusen/ci-python:3.14
+    env:
+      DB_USER: fabledcurator
+      DB_PASSWORD: ci_integration
+      DB_PORT: "5432"
+      DB_NAME: fabledcurator_test
+      SECRET_KEY: ci_integration_placeholder
+    services:
+      postgres:
+        image: pgvector/pgvector:pg16
+        env:
+          POSTGRES_USER: fabledcurator
+          POSTGRES_PASSWORD: ci_integration
+          POSTGRES_DB: fabledcurator_test
+        options: >-
+          --health-cmd "pg_isready -U fabledcurator"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Full history is the point: `chain_ref` is read out of git, so a
+          # shallow clone would not have the revisions to compare against.
+          fetch-depth: 0
+
+      - name: Resolve the Postgres service and install deps
+        run: |
+          set -eux
+          # Same service-IP dance as ci.yml's integration job; see the long
+          # comment there for why the job name must stay separator-free.
+          PG=$(docker ps --filter "name=compare" --filter "ancestor=pgvector/pgvector:pg16" -q | head -n1)
+          test -n "$PG"
+          PG_IP=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' "$PG")
+          test -n "$PG_IP"
+          echo "PG_CONTAINER=$PG" >> "$GITHUB_ENV"
+          echo "DB_HOST=$PG_IP" >> "$GITHUB_ENV"
+          # Socket probe in python, not bash's /dev/tcp — these steps run under
+          # `sh -e`, where that path does not exist. Same fix and same reasoning
+          # as ci.yml's integration job; see the comment there.
+          pg_ready=""
+          for i in $(seq 1 60); do
+            if python -c "import socket,sys; s=socket.socket(); s.settimeout(2); sys.exit(0 if s.connect_ex(('$PG_IP', 5432)) == 0 else 1)"; then
+              pg_ready=1
+              break
+            fi
+            sleep 2
+          done
+          if [ -z "$pg_ready" ]; then
+            echo "postgres at $PG_IP:5432 did not accept a connection within 120s"
+            exit 1
+          fi
+          if command -v uv >/dev/null 2>&1; then
+            uv pip install --system -r requirements.txt
+          else
+            pip install -r requirements.txt
+          fi
+
+      # DB 1: the 87-revision chain, read out of git at `chain_ref`.
+      #
+      # A git worktree rather than a checkout, so the current tree — which is
+      # what we are testing — is left completely alone.
+      - name: Build the schema the OLD chain produces
+        env:
+          CHAIN_REF: ${{ github.event.inputs.chain_ref }}
+          THIS_SHA: ${{ github.sha }}
+        run: |
+          set -eux
+          docker exec "$PG_CONTAINER" createdb -U fabledcurator fc_chain
+          # Blank means "the chain in this ref", which is what you want while
+          # the chain is still intact — comparing the models against a PINNED
+          # older commit reports every migration written since as a difference.
+          # Pin it only after the collapse, when the tree no longer has them.
+          git worktree add /tmp/chain "${CHAIN_REF:-$THIS_SHA}"
+          ls /tmp/chain/alembic/versions/*.py | wc -l
+          cd /tmp/chain
+          DB_NAME=fc_chain alembic upgrade head
+          cd -
+          docker exec "$PG_CONTAINER" pg_dump -U fabledcurator --schema-only \
+            --no-owner --no-privileges -d fc_chain > chain.sql
+          wc -l chain.sql
+          # Emit the dump itself, checksummed, for local analysis. Reconciling
+          # the models against the deployed schema (#3275) needs the ACTUAL
+          # schema, not an inference from a diff — parsing table context out of
+          # unified-diff hunks drops every table whose CREATE TABLE line falls
+          # outside a hunk, which silently under-reports.
+          #
+          # base64 + sha256 for the same reason as the candidate: a plain cat
+          # of a file this size was truncated mid-line by the runner with the
+          # step still green (run 4964).
+          set +x
+          B64=$(base64 -w 120 chain.sql)
+          echo "===== BEGIN CHAIN SCHEMA (base64) ====="
+          echo "$B64"
+          echo "===== END CHAIN SCHEMA ====="
+          echo "chain-sha256: $(sha256sum chain.sql | cut -d' ' -f1)"
+          echo "chain-bytes:  $(wc -c < chain.sql)"
+          set -x
+
+      # A candidate baseline, autogenerated from the models against an EMPTY
+      # database so every table shows up as a create. Printed for a human to
+      # finish — it will be missing the three raw-SQL items named at the top.
+      #
+      # Gated on the TREE, not on a workflow input. A `type: boolean` input
+      # read back as `github.event.inputs.generate == 'true'` silently
+      # evaluated false on this runner (run 4960 skipped this step entirely
+      # with no diagnostic) — the same `github.event.inputs` typing quirk
+      # build.yml already works around. The file count is the real question
+      # anyway: there is nothing to generate once the chain is collapsed.
+      - name: Autogenerate a candidate baseline
+        run: |
+          set -eux
+          if [ "$(ls alembic/versions/*.py | wc -l)" -le 1 ]; then
+            echo "already collapsed — nothing to generate"
+            exit 0
+          fi
+          docker exec "$PG_CONTAINER" createdb -U fabledcurator fc_gen
+          # Hide the existing revisions so alembic sees an empty history and
+          # emits the whole schema rather than a delta.
+          mkdir -p /tmp/versions_held
+          mv alembic/versions/*.py /tmp/versions_held/ 2>/dev/null || true
+          DB_NAME=fc_gen alembic revision --autogenerate -m "baseline" || true
+          # Printed rather than uploaded: ci-requirements.md records that this
+          # runner cannot do actions/upload-artifact@v4+, and the repo dropped
+          # the action entirely in 2026-05, so the job log is the retrieval
+          # channel actually proven here.
+          #
+          # base64, not the raw file. A plain `cat` of the ~33KB candidate was
+          # TRUNCATED MID-LINE by the runner on run 4964 — it stopped inside
+          # `sa.Column('mime', sa.String(length=128)` and carried straight on
+          # to the next traced command, with the step still green. A silent
+          # cut in the middle of a schema definition is the worst possible
+          # failure here, because the truncated text still looks like a
+          # plausible file.
+          #
+          # base64 at a fixed narrow width gives many short lines instead of
+          # few long ones, and — the actual point — a checksum and a line
+          # count that make truncation DETECTABLE rather than invisible.
+          set +x
+          F=$(ls alembic/versions/*.py | head -1)
+          B64=$(base64 -w 120 "$F")
+          echo "===== BEGIN CANDIDATE BASELINE (base64) ====="
+          echo "$B64"
+          echo "===== END CANDIDATE BASELINE ====="
+          echo "candidate-sha256: $(sha256sum "$F" | cut -d' ' -f1)"
+          echo "candidate-bytes:  $(wc -c < "$F")"
+          echo "candidate-b64-lines: $(echo "$B64" | wc -l)"
+          set -x
+          mkdir -p /tmp/candidate
+          cp alembic/versions/*.py /tmp/candidate/
+          # Put the tree back exactly as it was; this job never mutates state.
+          rm -f alembic/versions/*.py
+          mv /tmp/versions_held/*.py alembic/versions/ 2>/dev/null || true
+
+      # DB 2: what the CURRENT tree produces.
+      #
+      # `mode: models` applies the candidate autogenerated from the MODELS
+      # instead, which is what answers "do the models describe the schema?" —
+      # the question #3275 exists because nobody had ever asked it. Under that
+      # mode a clean diff means autogenerate is trustworthy again.
+      #
+      # The two extensions are created by hand first. They are database
+      # objects, not table metadata, so no model can carry them and their
+      # absence is not a model defect — it is simply outside what this
+      # comparison is asking about.
+      - name: Build the schema the CURRENT tree produces
+        env:
+          MODE: ${{ github.event.inputs.mode }}
+        run: |
+          set -eux
+          docker exec "$PG_CONTAINER" createdb -U fabledcurator fc_base
+          if [ "${MODE:-chain}" = "models" ]; then
+            docker exec "$PG_CONTAINER" psql -U fabledcurator -d fc_base \
+              -c "CREATE EXTENSION IF NOT EXISTS vector" \
+              -c "CREATE EXTENSION IF NOT EXISTS tsm_system_rows"
+            mkdir -p /tmp/held
+            mv alembic/versions/*.py /tmp/held/
+            cp /tmp/candidate/*.py alembic/versions/
+            # Autogenerate EMITS pgvector.sqlalchemy.vector.VECTOR(...) without
+            # importing it, so the file it writes cannot run:
+            #   NameError: name 'pgvector' is not defined
+            # Observed on run 4988, which is the proof rather than the theory.
+            # This is a defect in the GENERATOR, not in the models, so it is
+            # repaired here rather than counted as a schema difference — the
+            # comparison is about whether the models describe the schema.
+            sed -i '0,/^import sqlalchemy as sa$/s//import sqlalchemy as sa\nimport pgvector.sqlalchemy.vector/' alembic/versions/*.py
+            grep -n 'import pgvector' alembic/versions/*.py
+            ls alembic/versions/*.py
+            DB_NAME=fc_base alembic upgrade head
+            rm -f alembic/versions/*.py
+            mv /tmp/held/*.py alembic/versions/
+          else
+            ls alembic/versions/*.py | wc -l
+            DB_NAME=fc_base alembic upgrade head
+          fi
+          docker exec "$PG_CONTAINER" pg_dump -U fabledcurator --schema-only \
+            --no-owner --no-privileges -d fc_base > baseline.sql
+          wc -l baseline.sql
+
+      # The verdict.
+      #
+      # pg_dump orders dumpable objects by name within type, not by creation
+      # order, so two schemas built by different routes are directly
+      # comparable. Normalisation is deliberately minimal, because a filter
+      # that hides a real difference is the one way this check passes when it
+      # should fail — blank lines, SQL comments, trailing whitespace, and:
+      #
+      #   \restrict / \unrestrict — a per-invocation RANDOM NONCE that newer
+      #   pg_dump emits to fence the dump against injection during restore. It
+      #   differs on every run by construction, so it is noise by definition,
+      #   not a schema difference. Measured on run 4960, the control: two dumps
+      #   of the SAME schema came back 1123 lines each and differed on exactly
+      #   these two lines and nothing else. That control is what licenses this
+      #   filter — it was observed to be the only false positive, rather than
+      #   assumed to be one.
+      # Column ORDER inside a CREATE TABLE is compared separately from column
+      # CONTENT, and only content is fatal.
+      #
+      # A table built by 87 migrations has its columns in ADD COLUMN order; the
+      # same table built in one shot has them in declaration order. That is a
+      # real and permanent difference which no baseline can erase — the
+      # operator's existing database keeps chain order forever, a fresh install
+      # gets model order — so a check that fails on it would never pass and
+      # would teach nothing. FC reaches every column through the ORM by name,
+      # and `SELECT *` ordering is not depended on anywhere.
+      #
+      # So the second pass SORTS the column lines within each CREATE TABLE
+      # rather than DELETING them. That distinction is the whole point: sorting
+      # cannot hide a column that exists on one side only, or one whose type,
+      # nullability or default differs — those still land in the diff. A filter
+      # could have hidden all three.
+      #
+      # Both diffs are reported. The ordered one is informational; the
+      # order-insensitive one is the verdict.
+      - name: Diff
+        run: |
+          set -eu
+          norm() {
+            grep -vE '^\s*(--|$)' "$1" \
+              | grep -vE '^\\(un)?restrict ' \
+              | sed 's/[[:space:]]*$//'
+          }
+          norm chain.sql > a.txt
+          norm baseline.sql > b.txt
+          echo "normalised: chain=$(wc -l < a.txt) lines, current=$(wc -l < b.txt) lines"
+
+          sort_table_columns() {
+            python3 - "$1" <<'PYEOF'
+          import re, sys
+
+          lines = open(sys.argv[1]).read().splitlines()
+          out, block = [], None
+          for line in lines:
+              if block is not None:
+                  # ');' on its own closes the CREATE TABLE body.
+                  if line.strip() == ");":
+                      out.extend(sorted(block))
+                      out.append(line)
+                      block = None
+                  else:
+                      # Drop the list comma before sorting. Only the LAST
+                      # column lacks one, so keeping it would make every
+                      # reordering look like a content change as well — the
+                      # comma is punctuation, and carries no schema meaning.
+                      block.append(line.rstrip().rstrip(","))
+                  continue
+              out.append(line)
+              if re.match(r"CREATE TABLE .*\($", line):
+                  block = []
+          if block is not None:  # unterminated body: emit it rather than drop it
+              out.extend(block)
+          print("\n".join(out))
+          PYEOF
+          }
+          sort_table_columns a.txt > a.sorted.txt
+          sort_table_columns b.txt > b.sorted.txt
+          test "$(wc -l < a.sorted.txt)" = "$(wc -l < a.txt)"
+          test "$(wc -l < b.sorted.txt)" = "$(wc -l < b.txt)"
+
+          if diff -u a.txt b.txt > schema.diff; then
+            echo "ORDERED DIFF: identical, column order included."
+          else
+            echo "ORDERED DIFF: $(grep -cE '^[+-]' schema.diff) changed lines (informational):"
+            cat schema.diff
+          fi
+          echo
+          echo "================================================================"
+          echo
+          if diff -u a.sorted.txt b.sorted.txt > sorted.diff; then
+            echo "SCHEMAS MATCH — every difference above is column ORDER alone."
+          else
+            echo "SCHEMAS DIFFER — $(grep -cE '^[+-]' sorted.diff) changed lines that are NOT ordering:"
+            cat sorted.diff
+            echo
+            echo "The baseline is wrong, not the database. Do not stamp."
+            exit 1
+          fi

.forgejo/workflows/ci.yml

@@ -2,6 +2,7 @@ name: CI
 
 # CI lanes per FabledRulebook/forgejo.md "CI philosophy":
 #   - lint: ruff only, no dep install — fast-fail for the common lint bounce.
+#   - extension-version: the derived version resolves and is a shape AMO takes.
 #   - backend-lint-and-test: `pytest -m "not integration"`, no service containers.
 #   - frontend-build: vitest unit + vite build.
 #   - integration: pgvector + redis service containers; alembic + `pytest -m integration`.
@@ -9,10 +10,15 @@ name: CI
 on:
   push:
     branches: [dev, main]
-  # pull_request trigger intentionally absent — with branches: [dev, main]
-  # above, every PR commit already fires CI via the push event on dev. Adding
-  # pull_request would duplicate runs on dev→main PRs. FC has no fork PRs
-  # (single-operator Forgejo repo) so push coverage is complete.
+  # Renovate opens PRs from `renovate/*` branches into `dev`. Those branches
+  # never push to dev/main, so the push trigger above gives them NO pre-merge
+  # CI — a bump could only be validated after it was already merged. This
+  # pull_request trigger (base `dev` only) validates Renovate PRs before merge.
+  # It deliberately does NOT fire on dev→main PRs (base `main`), which still
+  # rely on the dev push run — so no duplicate runs. FC has no fork PRs
+  # (single-operator Forgejo repo), so secrets-on-PR is not a concern.
+  pull_request:
+    branches: [dev]
 
 jobs:
   # Fast-fail lint lane. ruff is pre-installed in the ci-python image, so
@@ -27,7 +33,93 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - name: Ruff lint
-        run: ruff check backend/ tests/ alembic/
+        # agent/ included so the GPU-agent is linted before its image is built
+        # (build.yml only `docker build`s it — this is where it gets checked).
+        # scripts/ likewise: release_notes.py runs only on a tag push, so a
+        # syntax or import error there would otherwise surface at the one
+        # moment nobody wants to debug a workflow.
+        run: ruff check backend/ tests/ alembic/ agent/ scripts/
+      - name: Agent syntax check
+        # The agent's runtime deps (torch/transformers/ultralytics) aren't in the
+        # CI image, so we can't import it — but compileall parses every module,
+        # catching syntax errors before the image build.
+        run: python -m compileall -q agent/fc_agent
+
+  # The extension version is DERIVED, not hand-maintained (milestone 271 step
+  # 4): build.yml computes it from the commit TIME of the newest packaged
+  # extension change and stamps it into manifest.json / package.json at build
+  # time. The guard that used to live here — "packaged files changed but nobody
+  # bumped the version" — was therefore checking a fact that had stopped
+  # existing. Worse than useless: it would have failed this lane on every real
+  # extension change, demanding a bump that decides nothing. Retired 2026-08-27
+  # rather than left running beside the new mechanism (rule 22).
+  #
+  # Two things are still worth asserting, and this is the only lane that can:
+  # the extension.yml suite runs on node:24-slim, which is exactly why
+  # version.spec.js sticks to packaging.sh's git-free subcommands.
+  #   1. the derivation actually resolves on this commit
+  #   2. the derived string is one AMO will accept, checked against Mozilla's
+  #      own published grammar rather than a loose "digits and dots"
+  #
+  # The MAJOR.MINOR-agreement check that used to be (2) is gone with milestone
+  # 318 step 8: the committed version no longer seeds anything, so there is no
+  # hand-set part left for the two files to disagree about.
+  #
+  # Deliberately NOT checked here: that the derived value beats what has already
+  # been signed. That guard belongs in build.yml, where it compares against the
+  # real ext-* releases. Comparing against origin/main here would be wrong —
+  # dev legitimately derives a LOWER value whenever main is ahead on the
+  # extension, and a lane that fails for being behind is a lane people learn to
+  # ignore.
+  extension-version:
+    runs-on: python-ci
+    container:
+      image: git.fabledsword.com/bvandeusen/ci-python:3.14
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The derivation needs real history: a depth-1 clone sees one commit
+          # and produces a wrong, too-low value RATHER THAN FAILING. Checking
+          # that here is half the point of the lane.
+          fetch-depth: 0
+      - name: Extension version derives cleanly
+        run: |
+          set -eu
+          # busybox sh on the act_runner — no bashisms (family rule).
+          VERSION=$(sh extension/scripts/packaging.sh version)
+          echo "derived: $VERSION"
+
+          # Mozilla's published grammar for AMO, transcribed verbatim from
+          # MDN's manifest.json/version page:
+          #
+          #     ^(0|[1-9][0-9]{0,8})([.](0|[1-9][0-9]{0,8})){0,3}$
+          #
+          # Not the looser `^[0-9]+(\.[0-9]+)*$` this lane used to carry. That
+          # one passes `2026.08.29.0201`, which AMO REJECTS — a segment must be
+          # the single digit 0 or start 1-9 — and it also passes five segments,
+          # where AMO allows four. Both would surface as a failed sign with the
+          # version already burned: AMO 409s on re-signing, so a rejected value
+          # cannot be reclaimed and cannot be reused. This lane is the cheap
+          # place to find out. (#3138, milestone 318 step 8.)
+          if ! echo "$VERSION" | grep -qE '^(0|[1-9][0-9]{0,8})(\.(0|[1-9][0-9]{0,8})){0,3}$'; then
+            echo "ERROR: derived version '$VERSION' is not a version AMO accepts."
+            echo "AMO's grammar: ^(0|[1-9][0-9]{0,8})([.](0|[1-9][0-9]{0,8})){0,3}$"
+            echo "Most likely cause: a zero-padded segment (08, 0201). The rest"
+            echo "of the family pads; the extension must not — see packaging.sh."
+            exit 1
+          fi
+
+          # ...and the shape this project actually derives. AMO would happily
+          # take `1.0.3500147` too, so the grammar check alone would not notice
+          # a regression to the pre-318 shape — which orders BELOW everything
+          # signed since, and is unrecoverable once Firefox has the higher one.
+          if ! echo "$VERSION" | grep -qE '^20[0-9][0-9]\.[0-9]{1,2}\.[0-9]{1,2}\.[0-9]{1,4}$'; then
+            echo "ERROR: derived version '$VERSION' is not YYYY.M.D.HHMM."
+            echo "Rule 148's CalVer is what build.yml signs; the old"
+            echo "1.0.<minutes> shape would order below every ext-2026.* release."
+            exit 1
+          fi
+          echo "OK: derived version $VERSION"
 
   backend-lint-and-test:
     runs-on: python-ci
@@ -40,6 +132,13 @@ jobs:
       SECRET_KEY: ci_unit_test_placeholder
     steps:
       - uses: actions/checkout@v4
+        with:
+          # Full history for tests/test_artifact_identity.py, which derives
+          # each artifact's revision to check the identity scheme. On a
+          # depth-1 clone that derivation either fails or returns the tip sha
+          # — so the lane would go green while asserting nothing, which is
+          # the one outcome worse than a red one.
+          fetch-depth: 0
 
       # Cache step removed 2026-05-26: act_runner's cache backend has been
       # broken on this homelab runner since 2026-05-15 (first as request-
@@ -85,10 +184,10 @@ jobs:
       # If we want strict lockfile-based reproducibility later, commit a
       # package-lock.json and flip this back to `npm ci`.
       - run: npm install --no-audit --no-fund
-      # `npm run check` (vue-tsc --noEmit) skipped: the frontend is pure JS
-      # with no .ts files and no JSDoc annotations, so vue-tsc has nothing
-      # to type-check. Re-enable once we add a tsconfig.json and either
-      # convert to TS or add JSDoc.
+      # No type-check step: the frontend is pure JS (no .ts files, no JSDoc),
+      # so a type-checker has nothing to do. The vue-tsc devDep + its `check`
+      # script were dropped 2026-07-11 rather than bumped to v3. If we add
+      # TS/JSDoc later, re-add a tsconfig.json + vue-tsc + a type-check step.
       - run: npm run test:unit
       - run: npm run build
 
@@ -156,10 +255,27 @@ jobs:
           export DB_HOST="$PG_IP"
           export CELERY_BROKER_URL="redis://$RD_IP:6379/0"
           export CELERY_RESULT_BACKEND="redis://$RD_IP:6379/0"
+          # These steps run under `sh -e`, not bash, so bash's /dev/tcp magic
+          # path does not exist here — the probe this loop used to run could
+          # never succeed and simply burned the full 120s on every run, green
+          # or red, then continued without having established anything. Python
+          # is in the image and needs no installed package for a socket
+          # connect, so it is the probe. Exhausting the budget is now a named
+          # failure rather than a silent fall-through (rule 156): if Postgres
+          # is genuinely not up, that is what the log should say, instead of
+          # whatever the first query happens to raise two minutes later.
+          pg_ready=""
           for i in $(seq 1 60); do
-            (echo > "/dev/tcp/$PG_IP/5432") >/dev/null 2>&1 && break
+            if python -c "import socket,sys; s=socket.socket(); s.settimeout(2); sys.exit(0 if s.connect_ex(('$PG_IP', 5432)) == 0 else 1)"; then
+              pg_ready=1
+              break
+            fi
             sleep 2
           done
+          if [ -z "$pg_ready" ]; then
+            echo "postgres at $PG_IP:5432 did not accept a connection within 120s"
+            exit 1
+          fi
           if command -v uv >/dev/null 2>&1; then
             uv pip install --system -r requirements.txt pytest pytest-asyncio
           else

.forgejo/workflows/extension.yml

@@ -1,5 +1,5 @@
 name: extension
-# Lint-only workflow. The sign-and-publish dance moved into build.yml's
+# Lint + unit tests. The sign-and-publish dance moved into build.yml's
 # `sign-extension` job (2026-05-25) — `:latest` now always bundles the XPI
 # because sign-extension runs as a build-web dependency in the SAME workflow,
 # eliminating the prior race between build.yml and a separate extension.yml.
@@ -10,20 +10,78 @@ on:
     paths:
       - 'extension/**'
       - '.forgejo/workflows/extension.yml'
+      # test/version.spec.js asserts things ABOUT the other two workflows —
+      # that neither inlines the packaged-file set, and that build.yml derives
+      # the shipped version rather than reading it out of the repo. A
+      # workflow-only edit can therefore break this suite, so it has to trigger
+      # it. build.yml joined the list at milestone 271 step 5, when the spec
+      # started asserting against it.
+      - '.forgejo/workflows/ci.yml'
+      - '.forgejo/workflows/build.yml'
   pull_request:
     branches: [main]
     paths:
       - 'extension/**'
+      - '.forgejo/workflows/ci.yml'
+      - '.forgejo/workflows/build.yml'
   workflow_dispatch:
 
 jobs:
   lint:
     runs-on: python-ci
     container:
-      image: node:22-bookworm-slim
+      image: node:24-bookworm-slim
     steps:
       - uses: actions/checkout@v4
-      - name: Install web-ext
-        run: cd extension && npm install --no-save --no-audit --no-fund
+      # Not --no-save: vitest and web-ext are both real devDependencies now,
+      # and the suite needs vitest resolvable from node_modules.
+      - name: Install dev dependencies
+        run: cd extension && npm install --no-audit --no-fund
       - name: Lint
         run: cd extension && npm run lint
+      # Pure-logic specs over lib/url.js and lib/platforms.js plus manifest /
+      # package version-consistency checks. No browser, no network.
+      - name: Unit tests
+        run: cd extension && npm run test:unit
+
+      # Everything else about packaging is asserted against our own declaration
+      # of what ships. This is the only check that asks web-ext what it ACTUALLY
+      # put in the archive. Until now that was an unverified assumption about
+      # glob semantics — and a fragile one: `test/**` reaches web-ext intact
+      # only because callers `set -f` first, so losing that quoting would
+      # silently start shipping dev files with no other signal.
+      - name: Verify XPI contents
+        run: |
+          set -eu
+          command -v unzip >/dev/null 2>&1 || { apt-get update -qq && apt-get install -y -qq unzip; }
+          cd extension
+          npm run build
+          ZIP=$(ls web-ext-artifacts/*.zip | head -1)
+          echo "=== packaged entries in $ZIP ==="
+          unzip -Z1 "$ZIP" | sort
+          echo "=== end ==="
+          ENTRIES=$(unzip -Z1 "$ZIP")
+          fail=0
+          # Must NOT ship: repo infrastructure with no business in a user's browser.
+          for pat in 'test/' 'scripts/' 'vitest.config.js' 'package.json' 'package-lock.json' 'README.md' 'node_modules/' 'web-ext-artifacts/'; do
+            if echo "$ENTRIES" | grep -q "^$pat"; then
+              echo "ERROR: '$pat' was packaged into the XPI but must not be"
+              fail=1
+            fi
+          done
+          # Must ship: if an exclusion pattern ever over-matches, the extension
+          # breaks at runtime rather than at build time, so assert presence too.
+          for req in 'manifest.json' 'lib/url.js' 'lib/api.js' 'lib/platforms.js' 'lib/cookies.js'; do
+            if ! echo "$ENTRIES" | grep -q "^$req$"; then
+              echo "ERROR: '$req' is missing from the XPI"
+              fail=1
+            fi
+          done
+          for dir in 'background/' 'popup/' 'options/' 'content/' 'icons/'; do
+            if ! echo "$ENTRIES" | grep -q "^$dir"; then
+              echo "ERROR: nothing from '$dir' was packaged"
+              fail=1
+            fi
+          done
+          [ "$fail" -eq 0 ] || exit 1
+          echo "XPI contents verified."

.forgejo/workflows/release.yml

@@ -0,0 +1,80 @@
+name: Release
+
+# A `v*` tag publishes a changelog. It does NOT build anything.
+#
+# Milestone 318 step 2 removed the tag trigger from build.yml: by the time
+# anyone tags a commit, `main` has already built and published it, and a
+# rebuild would re-push `:c-<sha>` — which rule 145 forbids even when the
+# source matches, since image configs carry timestamps and "same source" does
+# not mean "same manifest". That left the tag with no consequence at all.
+#
+# This is the consequence it has instead. Step 6 put the derived version in the
+# Settings footer, so an operator can say WHICH build they are running; this
+# says what is IN it that was not in the one they ran last month. Both halves
+# of one question (note #3127 §5).
+#
+# Nothing here runs on a schedule and nothing auto-tags on merge. Release tags
+# are bookmarks — cut one when you will want to point at that day by name,
+# otherwise don't (note #3127 §0). FC went twelve weeks between v26.06.04.0 and
+# the next one and nothing was wrong. A schedule would turn an optional
+# bookmark back into ceremony, which is the thing this milestone is removing.
+#
+# Cutting the tag is an explicit operator action under rule 2 ("`main` — never
+# without explicit request", which since 2026-08-28 covers PR, merge and tag
+# alike). This lane only decides what happens once they do.
+#
+# Requires repo secret RELEASE_TOKEN with the `write:release` scope — the same
+# PAT build.yml uses for the ext-<version> XPI asset cache.
+
+on:
+  push:
+    tags: ['v*']
+  # So a release body can be regenerated after the fact — the publisher PATCHes
+  # an existing release rather than falling through on a conflict, so re-running
+  # this on a tag rewrites the body instead of silently keeping the first one
+  # (note #3127 §6.7).
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag to (re)publish notes for'
+        required: true
+
+jobs:
+  changelog:
+    runs-on: python-ci
+    container:
+      image: git.fabledsword.com/bvandeusen/ci-python:3.14
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Load-bearing twice over: the previous release is found by walking
+          # ancestry back through the tag graph, and the cross-check against
+          # the derived web version calls artifacts.sh, which reads commit
+          # times. A shallow clone would find no previous tag and emit the
+          # entire history as the changelog — plausible-looking and wrong.
+          fetch-depth: 0
+          ref: ${{ github.event.inputs.tag || github.ref }}
+
+      # The `:c-<sha>` rollback refs are only real if `main` built this commit.
+      # The script checks that against origin/main and downgrades the claim to
+      # "unverified" when it cannot resolve one; fetching it here means that
+      # downgrade stays an actual signal instead of firing on every release.
+      - name: Make main's history resolvable
+        run: git fetch --no-tags --quiet origin +main:refs/remotes/origin/main || true
+
+      # TAG goes through the environment, not through `${{ }}` inside the
+      # run block. The value is operator-supplied, and an expression expanded
+      # into a shell line is expanded BEFORE the shell sees it — there is no
+      # quoting that makes that safe. On a tag push it is empty and the script
+      # falls back to GITHUB_REF.
+      - name: Publish the derived changelog
+        env:
+          RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
+          TAG: ${{ github.event.inputs.tag }}
+        run: |
+          set -eu
+          if [ -n "${TAG:-}" ]; then
+            python3 scripts/release_notes.py "$TAG"
+          else
+            python3 scripts/release_notes.py
+          fi

CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing
+
+FabledCurator is developed by a single maintainer for their own use, and
+published because it may be useful to others. That shapes what contribution
+looks like here.
+
+**Issues are welcome** — bug reports, and questions about running it, are
+genuinely useful and often the fastest way to find out that something is
+broken outside the one environment it was built in.
+
+**Open an issue before writing a pull request.** Not as a formality: the
+project has opinions that are not obvious from the code, and it is unpleasant
+for everyone when a finished patch turns out to conflict with one. A short
+issue first costs you nothing and may save you an evening.
+
+**Contributions are licensed under the AGPL-3.0**, like the rest of the
+project. By submitting one you agree it ships under that licence. There is no
+CLA and no copyright assignment.
+
+## Running it for development
+
+```bash
+docker compose up -d          # UI on http://localhost:8080
+```
+
+The dev override (`docker-compose.override.yml`) is auto-merged and builds the
+app images locally from source, so this needs no `.env` and no registry
+access. Postgres and Redis ports are exposed on the host.
+
+## What CI checks
+
+Every push runs these, and they are the definition of done for a change:
+
+```bash
+ruff check backend/ tests/ alembic/ agent/ scripts/   # lint (and import order)
+pytest tests/ -m "not integration"                    # backend unit tests
+pytest tests/ -m integration                          # needs pgvector + redis
+cd frontend && npm run test:unit && npm run build     # frontend
+```
+
+The integration lane builds its schema by running the real migrations
+(`alembic upgrade head`), never from ORM metadata — so a migration that does
+not apply cleanly fails CI rather than being discovered later.
+
+Note for the linter: ruff's isort runs with `order-by-type`, which sorts
+ALL-CAPS names ahead of CamelCase. `from sqlalchemy import JSON, DateTime, ...`
+is correct; putting `JSON` alphabetically between `Integer` and `String` is
+not. This catches people out.
+
+## Database changes
+
+The ORM models and the migration chain must agree. This is enforced, and it is
+enforced because they silently diverged for a long time and nobody noticed
+until they were compared: the models were missing indexes, defaults and
+uniqueness guarantees that only ever existed inside a migration, which made
+`alembic revision --autogenerate` actively unsafe to run.
+
+So: if you change a model, write the migration; if you write a migration,
+change the model to match. Both, in the same commit.
+
+Adding a value to a CHECK-constrained column means swapping the constraint in
+the same change — the constraint is not documentation, and a new value without
+it fails at insert time.
+
+## Branch model
+
+`dev` is where work happens. `main` is production and is only reached by a
+merge from `dev`, never pushed to directly. If you are sending a pull request,
+target `dev`.
+
+## Style
+
+Match the surrounding code. The one convention worth stating explicitly is
+that comments here explain *why*, especially where a choice looks wrong at a
+glance — a comment recording which migration a constraint came from, or why a
+default is a `text()` rather than a string, is the kind that has repeatedly
+turned out to be worth its space.

Dockerfile

@@ -1,6 +1,6 @@
-# syntax=docker/dockerfile:1.7
+# syntax=docker/dockerfile:1.25
 
-FROM node:22-alpine AS frontend-builder
+FROM node:24-alpine AS frontend-builder
 WORKDIR /build
 COPY frontend/package.json frontend/package-lock.json* ./
 # No package-lock.json is tracked yet (we don't run npm locally per
@@ -47,6 +47,29 @@ RUN chmod +x entrypoint.sh
 
 COPY --from=frontend-builder /build/dist ./frontend/dist
 
+# Which channel this image belongs to — `dev` or `main` (milestone 271 step 7).
+# build.yml passes it; /api/extension/manifest reports it beside the version so
+# an operator can tell which channel an install came from without the channel
+# ever touching the version string.
+#
+# Empty by default, deliberately: a locally-built image then reports NO channel
+# rather than claiming to be one, and the manifest omits the field entirely —
+# indistinguishable from an image built before the field existed, which is
+# exactly the shape every reader already has to handle.
+#
+# Declared LAST on purpose. An ARG/ENV invalidates every layer below it, and
+# these are the values that differ between builds of otherwise identical
+# source — put them any earlier and the two channels could never share a
+# cached pip install.
+#
+# FC_VERSION is what the instance reports about itself in the UI. Since
+# milestone 318 stopped publishing version image tags, that self-report is
+# the only answer to "which build is this?" — nothing else names it.
+ARG FC_CHANNEL=""
+ENV FC_CHANNEL=${FC_CHANNEL}
+ARG FC_VERSION=""
+ENV FC_VERSION=${FC_VERSION}
+
 EXPOSE 8080
 
 ENTRYPOINT ["./entrypoint.sh"]

Dockerfile.ml

@@ -1,4 +1,4 @@
-# syntax=docker/dockerfile:1.7
+# syntax=docker/dockerfile:1.25
 
 FROM python:3.14-slim
 ENV PYTHONUNBUFFERED=1 \

LICENSE

@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

README.md

@@ -1,50 +1,324 @@
 # FabledCurator
 
-Self-hosted media curation — gallery, ML tagging, and subscription-driven downloading in one app. Part of the FabledSword family.
+<!-- overview:start -->
+Self-hosted media curation — a gallery, ML auto-tagging, and subscription-driven
+downloading in one application. Part of the FabledSword family.
 
-Combines what was [ImageRepo](https://git.fabledsword.com/bvandeusen/ImageRepo) (gallery, ML, importer) and [GallerySubscriber](https://git.fabledsword.com/bvandeusen/GallerySubscriber) (gallery-dl wrapper, subscriptions, credential capture) into a single product.
+## What it does
 
-## Status
+You point it at creators you follow. It downloads what they post, files it,
+tags it, and gives you something better than a folder full of images to look
+through afterwards.
 
-Pre-v1. Not yet functional.
+- **Gallery and browsing.** Images, videos and multi-page works, organised by
+  artist, tag, post and series. A Showcase front page, a filterable gallery, a
+  similarity-driven Explore view, and a page-turning reader for series.
+- **Subscriptions.** Follows creators on Patreon, SubscribeStar, Pixiv and
+  anything `gallery-dl` supports, on a schedule. Handles paywalled posts using
+  your own logged-in session.
+- **ML tagging.** Runs image models in-container to suggest tags, group
+  characters, find near-duplicates and power similarity search. Suggestions are
+  reviewable — it proposes, you confirm, and it learns which proposals you keep
+  rejecting.
+- **Deduplication and provenance.** Everything that arrives is hashed and
+  deduplicated by content, metadata sidecars are read wherever the source
+  writes them, and every file keeps a record of where it came from.
+- **Maintenance.** Backups, library audits, thumbnail and embedding backfills,
+  orphan cleanup — all from the UI, all as background jobs you can watch.
 
-## Quick start
+Everything is configured from the Settings UI and stored in the database. There
+is no config file to edit beyond a handful of bootstrap environment variables.
+<!-- overview:end -->
 
-For local development and testing, just:
+## Before you expose it
+
+**FabledCurator has no login.** There are no user accounts, no passwords and no
+permission model. Anything that can reach the port is an administrator.
+
+That matters more here than it would in most self-hosted apps, because of what
+this one stores: **live platform session cookies for Patreon, SubscribeStar and
+Pixiv** — accounts that usually have a payment method attached. Whoever reaches
+the port can read them, alongside your entire library.
+
+So:
+
+- Bind it to a LAN, a VPN, or a tunnel you control.
+- Do not port-forward it. Do not put it on a public hostname.
+- A reverse proxy that adds TLS but no authentication **does not help**. If you
+  want it reachable from outside, put an authenticating proxy in front of it —
+  a forward-auth provider, HTTP basic auth, an identity-aware tunnel — and treat
+  that layer as the only thing standing between the internet and your accounts.
+
+This is a deliberate design decision for a single-operator tool on a trusted
+network, not a bug and not an oversight. It is stated here because it decides
+how you are allowed to deploy it. [SECURITY.md](SECURITY.md) covers the rest of
+the threat model.
+
+## Requirements
+
+- **Docker** with Compose v2.
+- **~4 GB RAM** for the app, plus whatever Postgres needs for your library size.
+- **Disk** for your media, plus several GB for ML model weights.
+- **No GPU required.** The ML worker runs on CPU — tagging and embedding are
+  slower, and that is the whole difference. A GPU is only involved if you
+  separately run the optional agent (below), which is a different machine's job.
+
+## Install
 
 ```bash
-docker compose up -d
-# UI: http://localhost:8080
-```
+git clone https://git.fabledsword.com/bvandeusen/FabledCurator.git
+cd FabledCurator
 
-That uses sane dev defaults baked into `docker-compose.yml` and the dev
-override (`docker-compose.override.yml`, auto-merged) — local builds, DEBUG
-logging, exposed Postgres + Redis ports on the host. No `.env` required.
+cp .env.example .env
+$EDITOR .env          # set DB_PASSWORD and SECRET_KEY
 
-For a production-like deployment, override the dev defaults via shell env
-or a `.env` file (see `.env.example` for the variable names) and use:
-
-```bash
 docker compose -f docker-compose.yml up -d
-# (skips the override so containers pull registry images)
 ```
 
+Then open <http://localhost:8080>.
+
+**The `-f docker-compose.yml` is required, not decoration.** Compose
+auto-merges `docker-compose.override.yml` when you leave it off, and that
+override builds the images locally from source — the contributor path, not
+yours. Naming the file explicitly skips the override and pulls the published
+`:latest` images, which is the stable channel built from `main`.
+
+If you forget it, the symptom is a long build instead of a quick pull.
+
+## First run
+
+The database schema is created automatically on first start — the web container
+runs its migrations before serving. Nothing to initialise by hand.
+
+**One thing does need a deliberate act, and the app will not start without it.**
+FabledCurator encrypts your stored platform credentials with a key it keeps at
+`./images/secrets/credential_key.b64`. On a brand-new install that file does not
+exist, and rather than quietly creating one the app stops:
+
+```
+MissingCredentialKey: Fernet key file not found at /images/secrets/credential_key.b64
+```
+
+Set `CURATOR_BOOTSTRAP_NEW_KEY=1` in your `.env` for the first `up`, then delete
+the line once the container is running. `.env.example` ships it with that
+instruction attached.
+
+The refusal is deliberate, and worth understanding rather than working around:
+auto-creating a key is indistinguishable from the disaster case — a restore that
+brought the database back but lost `./images/secrets` — where it would mint a key
+that cannot decrypt anything, leaving an instance that looks healthy while every
+paywalled download fails. Making you say so once, on an empty install, is the
+price of that not happening silently later.
+
+**Which means: back up `./images/secrets/` alongside your database.** It is the
+only thing that can read your stored credentials. A database restored without it
+needs every credential entered again by hand.
+
+A few other things are worth knowing about the first few minutes:
+
+- **The ML worker downloads its model weights on first boot**, several GB from
+  HuggingFace into `./models`. Until that finishes, tagging is queued rather
+  than broken. It is idempotent — a restart resumes rather than refetches.
+- **The gallery starts empty**, and that is the expected state. Add a creator
+  under **Subscriptions** and it fills as posts come down.
+- **If you already have a library on disk**, there is no screen that imports
+  it, and there is not going to be one. Folder ingestion had a UI until July
+  2026; it was retired once posts began arriving entirely through
+  subscriptions and the browser extension, and the decision to leave it
+  retired is deliberate — the folder path carries complexity the product does
+  not need in order to do its job. The supported way to fill a new install is
+  to add the creators you follow under **Subscriptions** and let it pull.
+
+  The `/api/import/trigger` endpoint is still wired up for anyone who wants to
+  script a one-off against a folder mounted at `./import`, and its progress
+  shows under **Settings → Activity**. Treat it as an unsupported escape
+  hatch rather than a feature: nothing in the UI drives it and nothing else
+  in this README depends on it.
+- **To download from a paywalled account**, FabledCurator needs that account's
+  session — see the browser extension below. Without one it can still fetch
+  public posts.
+- **Check Settings → Overview** to confirm the workers are alive. Every long
+  operation in FabledCurator is a background job, so if the queues are not
+  running, the UI will look like it is ignoring you rather than like it is
+  broken.
+
+## The browser extension
+
+A Firefox extension does two jobs: it hands your logged-in platform sessions to
+FabledCurator so it can download on your behalf, and it adds a creator as a
+subscription in one click from their page.
+
+It ships **inside the web image** — there is no add-on store listing to find.
+Go to **Subscriptions → Settings**, find the *Browser extension* card, and click
+**Install Firefox extension**. The XPI is Mozilla-signed, so Firefox installs it
+like any other add-on; the button serves it directly rather than making you
+download and side-load a file.
+
+It pairs with your instance using an API key generated automatically on first
+use. The bar directly under that card shows the key and can rotate it.
+
+See [extension/README.md](extension/README.md) for what it does in detail.
+
+## The GPU agent
+
+Optional, and separate. If you have a desktop with a graphics card, you can run
+an agent on it that leases ML jobs from FabledCurator over HTTP, does them on
+the GPU, and hands the results back. It never touches the database or Redis, so
+it is safe to run somewhere the rest of the stack is not.
+
+Run it for a burst of tagging, stop it to get your card back. It deploys from
+`agent/docker-compose.yml`, not the main stack — see
+[agent/README.md](agent/README.md).
+
+## Upgrading
+
+```bash
+docker compose -f docker-compose.yml pull
+docker compose -f docker-compose.yml up -d
+```
+
+Migrations run automatically on start. Take a database backup first — Settings →
+Maintenance has one — because the schema moves forward and does not move back.
+
 ## Deployment posture
 
-FabledCurator is designed to run inside a self-hosted homelab environment over plain HTTP. If you want TLS, terminate it at your reverse proxy. The app does not generate certificates, redirect to HTTPS, or set HSTS.
+FabledCurator is built to run inside a homelab over plain HTTP. It does not
+generate certificates, redirect to HTTPS, or set HSTS. If you want TLS,
+terminate it at your reverse proxy. See [Before you expose it](#before-you-expose-it)
+for why TLS alone is not enough.
+
+## Troubleshooting
+
+**The UI loads but nothing ever finishes.** The web container is up and the
+workers are not. `docker compose -f docker-compose.yml ps` — check `worker`,
+`scheduler` and `ml-worker` are healthy, not restarting.
+
+**`docker compose up` started building instead of pulling.** You left off
+`-f docker-compose.yml`, so the dev override took over. See [Install](#install).
+
+**Downloads fail with an auth error.** The stored session for that platform has
+expired. Re-capture it with the extension; sessions do not last forever.
+
+**Which build am I running?** The foot of Settings shows a version and a
+channel, and `/api/health` returns the same two fields. There are no version
+tags on the images, so this is the authoritative answer.
+
+---
+
+# Developing FabledCurator
+
+Everything below is about working on FabledCurator rather than running it. If
+you are installing it, you are done — see [CONTRIBUTING.md](CONTRIBUTING.md) if
+you want to send a patch.
+
+## Status and channels
+
+In production. `main` is continuously deployed — every merge builds and
+publishes `:latest`, so whatever is on `main` is what is running. Day-to-day
+work happens on `dev`, which publishes `:dev`.
+
+For local development, the dev override handles everything:
+
+```bash
+docker compose up -d          # note: no -f, so the override applies
+```
+
+That builds the images from source, turns on DEBUG logging, and exposes
+Postgres and Redis on the host. No `.env` required.
+
+## Versions and tags
+
+Three image tags exist, and no others:
+
+| Tag | Branch | Meaning |
+| --- | --- | --- |
+| `:latest` | `main` | Production. Moves on every merge. |
+| `:c-<sha>` | `main` | Immutable — the rollback unit, all three images together. |
+| `:dev` | `dev` | The rolling test channel. Moves on every push. |
+
+There are deliberately **no version tags**. Nothing pins one, and a per-build
+name nobody reads is upkeep for a model FC does not run (family rule 145; the
+reasoning is note #3127 §5). Rolling back is `docker pull …:c-<sha>`.
+
+Each artifact still has a version, derived rather than chosen: the commit time
+of the newest change to that artifact's *own* shipped files, as
+`YYYY.MM.DD.HHMM` UTC (rule 148). Four artifacts, four independent versions —
+a push touching only `agent/` re-versions the agent and leaves web and ml
+alone, and CI skips the builds whose content did not move.
+
+Because no registry name carries it, the running instance's own report is the
+only answer to "which build is this?". The foot of Settings shows
+`FabledCurator 2026.08.29.0201 · dev`, and `/api/health` returns the same two
+fields.
+
+Release tags are optional bookmarks — FC went twelve weeks without one and
+nothing was wrong. Pushing `v<version>` publishes a Forgejo release listing the
+commits since the previous tag; it builds no image.
+
+## What's in here
+
+Five deployable pieces, built by `.forgejo/workflows/build.yml`:
+
+| Piece | Built from | Image | Role |
+| --- | --- | --- | --- |
+| **Web / workers** | `Dockerfile` | `fabledcurator` | Quart API + the built Vue SPA in one image. `entrypoint.sh` picks the role: `web`, `worker`, `scheduler`. The `maintenance-long` service is a second `worker` pinned to the long-running maintenance queue. |
+| **ML worker** | `Dockerfile.ml` | `fabledcurator-ml` | Same app, plus `requirements-ml.txt` — tagging and embedding models that run in-container. |
+| **GPU agent** | `agent/Dockerfile` | `fabledcurator-agent` | Optional desktop-GPU worker (`agent/`). Leases jobs over **HTTP only** — never touches the database or Redis. See `agent/README.md`. |
+| **Firefox extension** | `extension/` | signed XPI | MV3 extension: pushes platform session cookies into FC and adds a creator as a Source in one click. AMO-signed on both `dev` and `main` (one signature per extension change, shared by the two channels), bundled into that channel's web image and served from Settings → Maintenance. See `extension/README.md`. |
+| **Data** | — | `pgvector/pgvector:pg16`, `redis:7-alpine` | Postgres with pgvector for embeddings; Redis as the Celery broker. |
 
 ## CI / Forgejo setup
 
-The repo's workflows expect:
+Four workflows: `ci.yml` (lint, extension-version check, backend unit tests,
+frontend build, integration), `extension.yml` (extension lint, vitest, XPI
+content verification), `build.yml` (sign + publish), and `release.yml`, which
+runs only on a `v*` tag and publishes a changelog without building anything.
 
-- **Runner label `python-ci`** — a Forgejo runner with Python 3.14, ruff, and Node 22 pre-installed. Both `ci.yml` and `build.yml` use this label. The runner image (`runner-base:python-ci`) is built from `CI-Runner/CI-python/` in the operator's workspace; `make push` from that directory builds and pushes a new image when toolchain pins change.
-- **Repo secret `RELEASE_TOKEN`** — a Forgejo PAT with the following scopes:
+**The toolchain each job runs in is its `container.image`, not its `runs-on`
+label.** `runs-on: python-ci` only schedules the job onto a runner; every job
+then names the image it actually wants. `ci-requirements.md` is the current,
+authoritative list of images and per-job installs — read that rather than a
+copy here, so the two can't drift.
+
+The repo expects one secret:
+
+- **`RELEASE_TOKEN`** — a Forgejo PAT with:
   - `write:package` + `read:package` — for `docker push` to `git.fabledsword.com`
-  - `write:release` — for future release-cutting workflows
-  - `write:issue` — for future issue-management automation
+  - `write:release` — for the `ext-<version>` releases that cache the signed XPI
+  - `write:issue` — for issue-management automation
 
   Generate at https://git.fabledsword.com/user/settings/applications. The injected `GITHUB_TOKEN` cannot be used because it lacks `write:package`.
 
+AMO signing additionally needs `MOZILLA_AMO_JWT_KEY` / `MOZILLA_AMO_JWT_SECRET`.
+It runs on **both** channels and is cached per version: because the version is
+derived from commit time, `dev` and `main` derive the same number for the same
+source, so `main` finds `dev`'s signature already cached and makes no second AMO
+call. That cache is why signing must be one-shot — AMO rejects a re-signed
+version.
+
+## History
+
+FabledCurator combines what was
+[ImageRepo](https://git.fabledsword.com/bvandeusen/ImageRepo) (gallery, ML,
+importer) and
+[GallerySubscriber](https://git.fabledsword.com/bvandeusen/GallerySubscriber)
+(gallery-dl wrapper, subscriptions, credential capture) into a single product.
+Both are superseded; neither is maintained.
+
 ## License
 
-Personal project; use at your own discretion.
+**GNU Affero General Public License v3.0** — see [LICENSE](LICENSE).
+
+You may run, study, modify and redistribute this software. The condition is
+reciprocity: if you distribute a modified version, or **run one as a network
+service that other people use**, you must offer those users the corresponding
+source under the same licence. That second clause (AGPL §13) is the reason this
+licence rather than the GPL — for a self-hosted web application, "distribution"
+otherwise never happens, and the obligation would never bite.
+
+Running an unmodified copy for yourself, your household or your organisation
+carries no obligation at all. Neither does modifying it privately. The licence
+asks something of you only when you hand your modified version to others.
+
+Contributions ship under the same licence — see [CONTRIBUTING](CONTRIBUTING.md).
+Security reports: [SECURITY.md](SECURITY.md).

SECURITY.md

@@ -0,0 +1,77 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+**Please do not put vulnerability details in a public issue.**
+
+This project has no private disclosure channel yet. Until it does, open an
+issue on the repository that says only that you have a security report — no
+reproduction steps, no affected endpoint, no payload — and a maintainer will
+reply with a private contact to send the details to.
+
+That is a deliberately awkward first step, and it exists because the
+alternative is worse: an issue tracker is public the moment it is written to,
+and every self-hosted instance stays vulnerable until its operator has had a
+chance to update.
+
+Please include, once you have a private channel:
+
+- what an attacker can do, and what access they need to start
+- the version or commit you tested
+- reproduction steps
+
+## Scope — what this software actually handles
+
+FabledCurator is self-hosted and holds things worth stating plainly, because
+they shape what counts as a serious bug here:
+
+- **Platform credentials.** The app captures and stores session cookies for
+  third-party subscription sites (Patreon, SubscribeStar, Pixiv) so it can
+  download on the operator's behalf. These are live credentials for accounts
+  that usually carry a payment method. Anything that discloses them, decrypts
+  them, or lets one user of a shared instance read another's is high severity.
+- **An extension API key.** The Firefox extension authenticates to the backend
+  with a shared key. Anything that leaks it or lets it be bypassed is a way in.
+- **No authentication of its own.** This is the most important thing on this
+  page. FabledCurator has no login, no user accounts and no permission model —
+  there is no `User` table and no session auth anywhere in the backend. Every
+  HTTP client that can reach the port is the administrator, with full read and
+  write access to everything above, including the stored platform credentials.
+  Access control is entirely the operator's job, done at the network layer.
+  Reports that an unauthenticated caller can reach an endpoint are therefore
+  describing the design; reports that something *crosses the network boundary
+  the operator drew* — an SSRF, a request forgery that rides a browser the
+  operator already has open, a path that leaks state to an origin the operator
+  did not authorise — are in scope and are serious.
+- **Arbitrary media from the internet.** Downloaded files are decoded, hashed,
+  thumbnailed and fed to ML models. Anything that turns a hostile file into
+  code execution is in scope.
+
+## Deployment posture — read this before reporting
+
+FabledCurator is designed to run **inside a private network, over plain HTTP,
+reachable only by its operator**. It does not terminate TLS, redirect to
+HTTPS, or set HSTS; if you want transport security, terminate it at your
+reverse proxy. It also does not authenticate anyone — see above. These are
+documented design decisions, not oversights.
+
+Putting this on the public internet, with or without TLS, hands whoever finds
+it your Patreon, SubscribeStar and Pixiv sessions. A reverse proxy that adds
+TLS but not an authentication layer does not change that.
+
+Reports that reduce to "the application is served over HTTP", "there is no
+HSTS header", or "the API needs no credentials" describe those decisions
+rather than vulnerabilities. Reports that the operator can cause the software
+to do something destructive are usually also by design — the operator is the
+administrator of their own instance.
+
+What remains in scope is everything that crosses a boundary the software is
+actually supposed to hold: between untrusted downloaded content and the host,
+between a third-party origin and an operator's open browser session, and
+between the credentials at rest and anything that is not the operator.
+
+## Supported versions
+
+Fixes land on the `main` branch and reach the `:latest` image. There are no
+maintained release branches — the supported version is the current one, and
+the remedy for a security issue is to update.

agent/Dockerfile

@@ -1,18 +1,24 @@
 # FabledCurator GPU agent — runs on the desktop with the GPU.
-# CUDA + cuDNN runtime so onnxruntime-gpu can use the card (it needs cuDNN 9 —
-# the plain -runtime image lacks it: "libcudnn.so.9: cannot open shared object
-# file"); ffmpeg for video frames.
-FROM nvidia/cuda:12.4.1-cudnn-runtime-ubuntu22.04
+# CUDA 12.9 + cuDNN 9 runtime so onnxruntime-gpu can use the card (it needs
+# cuDNN 9 — the plain -runtime image lacks it: "libcudnn.so.9: cannot open
+# shared object file"); ffmpeg for video frames. Ubuntu 24.04 → Python 3.12.
+# Stays on the CUDA-12 / cuDNN-9 line the default onnxruntime-gpu + torch are
+# built against (CUDA 13 has only nascent ONNX Runtime support).
+FROM nvidia/cuda:12.9.2-cudnn-runtime-ubuntu24.04
 
-ENV DEBIAN_FRONTEND=noninteractive PYTHONUNBUFFERED=1
+# PIP_BREAK_SYSTEM_PACKAGES: Ubuntu 24.04 marks its system Python as externally
+# managed (PEP 668), so a global `pip install` errors without this. It's a
+# single-purpose container — we own the whole environment, so installing into
+# the system site-packages is fine (and simplest — no venv on PATH to manage).
+ENV DEBIAN_FRONTEND=noninteractive PYTHONUNBUFFERED=1 PIP_BREAK_SYSTEM_PACKAGES=1
 RUN apt-get update \
     && apt-get install -y --no-install-recommends python3 python3-pip ffmpeg \
     && rm -rf /var/lib/apt/lists/*
 
 WORKDIR /app
-# torch from the CUDA-12.4 wheel index (matches the base image); its wheels
-# bundle their own CUDA + cuDNN and coexist with onnxruntime-gpu. Installed
-# first + separately so the GPU build of torch is deterministic and layer-cached.
+# torch from the CUDA-12.4 wheel index; its wheels bundle their own CUDA + cuDNN
+# so they run on the 12.9 base and coexist with onnxruntime-gpu. Installed first
+# + separately so the GPU build of torch is deterministic and layer-cached.
 RUN pip3 install --no-cache-dir torch==2.6.0 --index-url https://download.pytorch.org/whl/cu124
 COPY requirements.txt .
 RUN pip3 install --no-cache-dir -r requirements.txt

agent/docker-compose.yml

@@ -34,9 +34,29 @@ services:
       # Resume the worker automatically on container start (survive a reboot /
       # crash-restart while you're away). Set to 0 to require a manual Start.
       AUTO_START: ${AUTO_START:-1}
+      # Autoscale the worker count (throughput hill-climb that finds the sweet
+      # spot + backs off under VRAM pressure). On by default; toggle live in the
+      # control UI. Set to 0 to start in manual mode.
+      AUTO_SCALE: ${AUTO_SCALE:-1}
+      # Aggregate download cap in MB/s (stills + video streams combined), so the
+      # agent can't saturate the desktop's network and wreck browsing — WiFi
+      # especially. 0 = unlimited; tunable live in the control UI.
+      BANDWIDTH_LIMIT_MB_S: ${BANDWIDTH_LIMIT_MB_S:-8}
       # Crop embedder (SigLIP concept bag): float16 keeps VRAM low on a shared
       # desktop GPU; the model itself is announced by the server.
       SIGLIP_DTYPE: ${SIGLIP_DTYPE:-float16}
+      # Crop PROPOSERS (extra YOLO detectors → more/better concept crops). Each
+      # downloads its weights once (cached on the models volume) and self-disables
+      # if the download/load fails. Blank any one to turn it off.
+      #   PERSON_WEIGHTS: general COCO person detector (Western/realistic figures),
+      #     merged with the anime detector. yolo11n.pt (~6 MB, auto-downloaded).
+      #   ANATOMY_WEIGHTS: booru_yolo anime/furry/NSFW components (~40 MB). NB the
+      #     repo states no license — fine for private use. yolov8n_as01.pt is the
+      #     6 MB nano if you want lighter than yolov11m_aa22.pt.
+      #   PANEL_WEIGHTS: mosesb comic-panel detector (Apache-2.0), "hf_repo::file".
+      PERSON_WEIGHTS: ${PERSON_WEIGHTS:-yolo11n.pt}
+      ANATOMY_WEIGHTS: ${ANATOMY_WEIGHTS:-https://github.com/aperveyev/booru_yolo/raw/main/models/yolov11m_aa22.pt}
+      PANEL_WEIGHTS: ${PANEL_WEIGHTS:-mosesb/best-comic-panel-detection::best.pt}
     volumes:
       # Persist the downloaded ONNX models so restarts are fast.
       - fc-agent-models:/models

agent/fc_agent/app.py

@@ -1,21 +1,45 @@
 """FastAPI control surface for the agent (served on localhost).
 
-Start / stop the worker pool, tune the worker count live (trades desktop
-responsiveness for throughput), and watch GPU load + progress + the server-side
-queue. Config is env-seeded; the worker count is adjustable here on the fly.
+Start / stop the download→GPU pipeline, tune the downloader count live (the
+workload is download-bound, so downloaders are the dial that trades desktop
+bandwidth for throughput), and watch GPU load + buffer occupancy + progress +
+the server-side queue. Config is env-seeded; the downloader count is adjustable
+here on the fly (GPU consumers autoscale between 1 and 2 on their own).
 """
+import logging
+
 from fastapi import FastAPI, Request
 from fastapi.responses import HTMLResponse, JSONResponse
 
+from . import logbuf
 from .config import Config
 from .gpu import read_gpu
 from .worker import Worker
 
+log = logging.getLogger("fc_agent.app")
+
+# Bump on every agent change. The page embeds this and /status reports it; the UI
+# warns to reload when they differ — so a stale browser-cached page can't be
+# mistaken for "the new image didn't deploy". (Belt-and-braces with no-store.)
+VERSION = "2026-07-17.1 · idle model-unload: after ~5 min idle the GPU models release their VRAM and reload on the next job (env IDLE_UNLOAD_SECONDS, 0=off) · sleep mode sheds to one downloader"
+
+logbuf.install()
 cfg = Config.from_env()
 worker = Worker(cfg)
 app = FastAPI(title="FabledCurator GPU agent")
 
 
+@app.middleware("http")
+async def _no_store(request, call_next):
+    # The control page is a static string and the status/gpu/logs polls are
+    # live data — never let the browser cache either, or a freshly-pulled agent
+    # image still shows the OLD UI until a hard refresh (operator-flagged
+    # 2026-06-30).
+    resp = await call_next(request)
+    resp.headers["Cache-Control"] = "no-store"
+    return resp
+
+
 @app.on_event("startup")
 def _maybe_autostart() -> None:
     # With AUTO_START set, a container restart (host reboot, or `restart:
@@ -28,17 +52,19 @@ def _maybe_autostart() -> None:
 
 @app.get("/", response_class=HTMLResponse)
 def index() -> str:
-    return _PAGE
+    return _PAGE.replace("__BUILD__", VERSION)
 
 
 @app.post("/start")
 def start():
+    log.info("UI: Start button pressed")   # the press; worker logs the transition
     worker.start()
     return JSONResponse(worker.status())
 
 
 @app.post("/stop")
 def stop():
+    log.info("UI: Stop button pressed")
     worker.stop()
     return JSONResponse(worker.status())
 
@@ -50,85 +76,332 @@ async def concurrency(request: Request):
     return JSONResponse(worker.status())
 
 
+@app.post("/auto")
+async def auto(request: Request):
+    body = await request.json()
+    worker.set_auto(bool(body.get("value", True)))
+    return JSONResponse(worker.status())
+
+
+@app.post("/bandwidth")
+async def bandwidth(request: Request):
+    body = await request.json()
+    worker.set_bandwidth(float(body.get("value", 0)))
+    return JSONResponse(worker.status())
+
+
+@app.get("/gpu")
+def gpu():
+    # GPU meters poll this on their own fast cadence. It only reads local
+    # nvidia-smi — no curator round-trip — so the util/VRAM bars stay live even
+    # when /status is slow waiting on the (sometimes busy) curator queue call.
+    g = read_gpu() or {}
+    us = worker.util_smooth()
+    if us is not None:
+        g["util_smooth"] = round(us, 1)   # autoscaler's EWMA — the UI bar tracks this
+    return JSONResponse(g)
+
+
+@app.get("/logs")
+def logs():
+    return JSONResponse({"lines": list(logbuf.LINES)})
+
+
 @app.get("/status")
 def status():
+    # Pure in-memory read: worker.status() is lock-free and the queue snapshot is
+    # kept fresh by a background poller — NO inline curator call, so this can't
+    # stall the status view when curator is buried under a big backlog.
+    worker.note_ui()          # a browser is watching → keep the queue snapshot warm
     s = worker.status()
     s["fc_url"] = cfg.fc_url
     s["configured"] = bool(cfg.token)
-    s["gpu"] = read_gpu()
-    try:
-        s["queue"] = worker.client.queue_status()
-    except Exception:
-        s["queue"] = None
+    s["queue"] = worker.latest_queue()
+    s["build"] = VERSION
     return JSONResponse(s)
 
 
 _PAGE = """<!doctype html><html><head><meta charset=utf-8>
-<title>FabledCurator GPU agent</title>
+<meta name=viewport content="width=device-width,initial-scale=1">
+<title>FabledCurator · GPU agent</title>
 <style>
- body{font:14px system-ui;margin:2rem;max-width:680px;background:#14171a;color:#e8e8e8}
- h1{font-size:18px} button{font:14px system-ui;padding:.5rem 1rem;border:0;border-radius:6px;
- margin-right:.5rem;cursor:pointer;color:#fff} .start{background:#2e7d32}.stop{background:#b3261e}
- .step{background:#33373b;padding:.4rem .7rem;font-weight:700}
- .stat{display:inline-block;margin-right:1.5rem;vertical-align:top}
- .n{font-size:22px;font-weight:700} code{background:#222;padding:2px 6px;border-radius:4px}
- .q,.gpu{margin-top:1rem;color:#9aa} .bar{height:8px;border-radius:4px;background:#222;overflow:hidden;
- max-width:320px;margin-top:4px} .bar>i{display:block;height:100%;background:#3f7d3f}
- .row{margin:.8rem 0}
+ :root{--bg:#0f1216;--panel:#181c22;--panel2:#1e232b;--bd:#2a313b;--fg:#e9edf2;
+  --mut:#8b97a6;--acc:#e8923a;--grn:#46c46a;--red:#e8584d;--amb:#e8b23a}
+ *{box-sizing:border-box}
+ body{font:14px/1.5 system-ui,-apple-system,Segoe UI,Roboto,sans-serif;margin:0;
+  background:radial-gradient(1200px 600px at 50% -10%,#1a2029,#0f1216);color:var(--fg)}
+ .wrap{max-width:820px;margin:0 auto;padding:28px 20px 28px;height:100vh;
+  box-sizing:border-box;overflow:hidden;display:flex;flex-direction:column}
+ header{display:flex;align-items:center;justify-content:space-between;margin-bottom:4px}
+ .brand{display:flex;align-items:center;gap:10px;font-size:19px;font-weight:700;letter-spacing:.2px}
+ .logo{color:var(--acc);font-size:20px}
+ .brand .sub{color:var(--mut);font-weight:600;font-size:13px;text-transform:uppercase;letter-spacing:.12em}
+ .conn{display:flex;align-items:center;gap:8px;color:var(--mut);font-size:13px;font-weight:600}
+ .dot{width:9px;height:9px;border-radius:50%;background:var(--mut);box-shadow:0 0 0 0 rgba(0,0,0,0)}
+ .dot.green{background:var(--grn);box-shadow:0 0 10px 1px rgba(70,196,106,.5)}
+ .dot.amber{background:var(--amb)} .dot.red{background:var(--red)}
+ .meta{color:var(--mut);margin:0 0 18px;font-size:13px}
+ code{background:#11151a;border:1px solid var(--bd);padding:2px 7px;border-radius:6px;
+  font:12px ui-monospace,SFMono-Regular,Menlo,monospace;color:#cdd6e0}
+ .card{background:linear-gradient(180deg,var(--panel),var(--panel2));border:1px solid var(--bd);
+  border-radius:14px;padding:16px 18px;margin-bottom:14px;box-shadow:0 1px 0 rgba(255,255,255,.02) inset}
+ .card-h{font-size:11px;font-weight:800;letter-spacing:.12em;text-transform:uppercase;
+  color:var(--mut);margin-bottom:14px}
+ .controls{display:flex;align-items:center;gap:10px;flex-wrap:wrap}
+ .spacer{flex:1}
+ .btn{font:600 14px system-ui;padding:.5rem 1rem;border:1px solid transparent;border-radius:9px;
+  cursor:pointer;color:#fff;transition:.12s}
+ .btn:hover{transform:translateY(-1px)}
+ .btn[disabled]{opacity:.45;pointer-events:none;transform:none}
+ @keyframes pulse{0%,100%{opacity:1}50%{opacity:.4}}
+ .tile .n.busy{color:var(--acc);animation:pulse 1s ease-in-out infinite}
+ .btn.start{background:linear-gradient(180deg,#2f9c4c,#247a3c)}
+ .btn.stop{background:linear-gradient(180deg,#3a3f48,#2a2f37);color:#e9edf2;border-color:var(--bd)}
+ .switch{display:inline-flex;align-items:center;gap:8px;cursor:pointer;font-weight:600;user-select:none}
+ .switch input{display:none}
+ .switch .track{width:38px;height:22px;border-radius:11px;background:#2a313b;position:relative;transition:.15s}
+ .switch .track:after{content:"";position:absolute;top:2px;left:2px;width:18px;height:18px;border-radius:50%;
+  background:#cdd6e0;transition:.15s}
+ .switch input:checked+.track{background:var(--acc)}
+ .switch input:checked+.track:after{transform:translateX(16px);background:#fff}
+ .stepper{display:inline-flex;align-items:center;gap:6px}
+ .step{background:#262c34;color:var(--fg);border:1px solid var(--bd);border-radius:8px;
+  width:30px;height:32px;font:700 16px system-ui;cursor:pointer}
+ .step:hover{border-color:var(--acc)}
+ #conc,#bw{width:3.4rem;height:32px;text-align:center;font:700 16px system-ui;background:#11151a;
+  color:var(--fg);border:1px solid var(--bd);border-radius:8px}
+ .unit{color:var(--mut);font-size:12px;font-weight:600}
+ .hint{color:var(--mut);font-size:12px;margin-top:12px}
+ .tiles{display:grid;grid-template-columns:repeat(6,1fr);gap:8px;margin-bottom:16px}
+ .tile{background:#13171d;border:1px solid var(--bd);border-radius:10px;padding:12px 8px;text-align:center}
+ .tile .n{font:800 22px ui-monospace,monospace;line-height:1.1}
+ .tile .n.warn{color:var(--red)} .tile .n.ok{color:var(--grn)}
+ .tile .l{font-size:10px;text-transform:uppercase;letter-spacing:.06em;color:var(--mut);margin-top:4px}
+ .meters{display:flex;flex-direction:column;gap:10px;margin-bottom:14px}
+ .meter-h{display:flex;justify-content:space-between;font-size:12px;color:var(--mut);margin-bottom:4px}
+ .meter-h b{color:var(--fg);font-variant-numeric:tabular-nums}
+ .bar{height:9px;border-radius:5px;background:#11151a;border:1px solid var(--bd);overflow:hidden}
+ .bar>i{display:block;height:100%;width:0;background:linear-gradient(90deg,#3a7d57,var(--grn));transition:width .4s}
+ #utilbar{background:linear-gradient(90deg,#9a5a1f,var(--acc))}
+ #bufbar{background:linear-gradient(90deg,#2f5a9a,#4a86d8)}
+ .queue{font:13px ui-monospace,monospace;color:var(--mut)}
+ .banner{margin:0 0 14px;padding:.7rem .9rem;border-radius:10px;background:#3a2f12;
+  border:1px solid #5a4a17;color:#ffd98a;font-size:13px}
+ .logs-h{display:flex;align-items:center;justify-content:space-between}
+ .grow{flex:1;display:flex;flex-direction:column;min-height:0}
+ .grow .logs{flex:1;min-height:0}
+ .copybtn{font:600 11px system-ui;letter-spacing:.04em;text-transform:uppercase;
+  background:#262c34;color:var(--fg);border:1px solid var(--bd);border-radius:7px;
+  padding:5px 11px;cursor:pointer}
+ .copybtn:hover{border-color:var(--acc)}
+ .logs{margin:0;background:#0b0e12;border:1px solid var(--bd);border-radius:10px;padding:12px;
+  overflow:auto;font:12px/1.55 ui-monospace,SFMono-Regular,Menlo,monospace;
+  color:#b9c4d0;white-space:pre-wrap;word-break:break-word}
 </style></head><body>
-<h1>FabledCurator GPU agent</h1>
-<p>FC: <code id=fc>—</code> · token <code id=cfg>—</code></p>
-<div class=row>
- <button class=start onclick=act('start')>Start</button>
- <button class=stop onclick=act('stop')>Stop</button>
+<div class=wrap>
+ <header>
+  <div class=brand><span class=logo>◆</span> FabledCurator <span class=sub>GPU agent</span></div>
+  <div class=conn><span class="dot" id=dot></span><span id=connlbl>—</span></div>
+ </header>
+ <p class=meta>Server <code id=fc>—</code> · token <code id=cfg>—</code> · build <code id=build>__BUILD__</code></p>
+
+ <div id=verbanner class=banner style="display:none;background:#3a1212;border-color:#5a1717;color:#ffb3b3">
+  a newer agent version is running — reload this page (Ctrl+Shift+R) to update the controls
+ </div>
+ <div id=banner class=banner style=display:none>
+  curator unreachable — holding work + retrying, resumes on its own (no restart needed)
+ </div>
+
+ <section class=card>
+  <div class=card-h>Control</div>
+  <div class=controls>
+   <button class="btn start" id=startbtn onclick=act('start')>▶ Start</button>
+   <button class="btn stop" id=stopbtn onclick=act('stop')>■ Stop</button>
+   <div class=spacer></div>
+   <label class=switch><input type=checkbox id=autochk onchange="setauto(this.checked)"><span class=track></span>Auto</label>
+   <div class=stepper>
+    <button class=step onclick=setc(-1)>−</button>
+    <input id=conc type=number min=1 value=1 onchange="setv(this.value)">
+    <button class=step onclick=setc(1)>+</button>
+   </div>
+   <div class=stepper title="aggregate download cap, downloads + video streams combined — 0 = unlimited">
+    <input id=bw type=number min=0 step=1 value=8 onchange="setbw(this.value)">
+    <span class=unit>MB/s</span>
+   </div>
+  </div>
+  <div class=hint id=conchint>auto-tuning downloaders to keep the GPU fed · max 8</div>
+ </section>
+
+ <section class=card>
+  <div class=card-h>Status</div>
+  <div class=tiles>
+   <div class=tile><div class=n id=state>—</div><div class=l>state</div></div>
+   <div class=tile><div class=n id=jpm>—</div><div class=l>jobs / min</div></div>
+   <div class=tile><div class=n id=dpm>—</div><div class=l>downloads / min</div></div>
+   <div class=tile><div class="n ok" id=done>0</div><div class=l>processed</div></div>
+   <div class=tile><div class=n id=err>0</div><div class=l>errors</div></div>
+   <div class=tile><div class=n id=waited>0</div><div class=l>waited out</div></div>
+  </div>
+  <div class=meters>
+   <div class=meter><div class=meter-h><span>GPU util</span><b id=utillbl>—</b></div>
+    <div class=bar><i id=utilbar></i></div></div>
+   <div class=meter><div class=meter-h><span>VRAM</span><b id=vramlbl>—</b></div>
+    <div class=bar><i id=gpubar></i></div></div>
+   <div class=meter><div class=meter-h><span>buffer occupancy</span><b id=buflbl>—</b></div>
+    <div class=bar><i id=bufbar></i></div></div>
+  </div>
+  <div class=queue id=pipe>downloaders — · consumers — · on GPU 0</div>
+  <div class=queue id=queue>queue —</div>
+ </section>
+
+ <section class="card grow">
+  <div class="card-h logs-h">Logs
+   <button class=copybtn id=copybtn onclick=copyLogs()>Copy</button>
+  </div>
+  <pre class=logs id=logs>waiting for activity…</pre>
+ </section>
 </div>
-<div class=row>
- workers
- <button class=step onclick=setc(-1)>−</button>
- <input id=conc type=number min=1 value=1
-  style="width:3.5rem;font:700 16px system-ui;text-align:center;background:#222;color:#e8e8e8;border:1px solid #444;border-radius:6px;padding:.3rem"
-  onchange="setv(this.value)">
- <button class=step onclick=setc(1)>+</button>
- <span class=cap style=color:#9aa>(more = overlap I/O, fill the GPU) max <b id=capn>8</b></span>
-</div>
-<div class=row>
- <span class=stat><span class=n id=state>stopped</span><br>state</span>
- <span class=stat><span class=n id=active>0</span><br>active now</span>
- <span class=stat><span class=n id=done>0</span><br>processed</span>
- <span class=stat><span class=n id=err>0</span><br>errors</span>
- <span class=stat><span class=n id=wait>0</span><br>waited out</span>
-</div>
-<div id=banner style="display:none;margin:.6rem 0;padding:.5rem .8rem;border-radius:6px;background:#5a4a17;color:#ffe28a">
- curator unreachable — holding work + retrying, will resume on its own (no restart needed)
-</div>
-<div class=gpu id=gpu>GPU — …</div>
-<div class=bar><i id=gpubar style=width:0%></i></div>
-<div class=q id=queue></div>
 <script>
+ const PAGE_BUILD="__BUILD__"
  let CAP=8
- async function act(p){await fetch('/'+p,{method:'POST'});refresh()}
- function setc(d){ setv((parseInt(conc.value||'1'))+d) }
+ // Optimistic transitional state on click, then apply the POST's own status
+ // response (it returns worker.status()) for instant feedback — don't wait on the
+ // separate /status poll, which can lag behind the curator queue call.
+ async function act(p){
+  pending(p==='start'?'starting':'stopping')
+  // Abort a slow POST after 8s so the buttons never stay stuck — the periodic
+  // /status refresh (now always fast) recovers the true state either way.
+  const ac=new AbortController(); const to=setTimeout(()=>ac.abort(),8000)
+  try{ applyStatus(await (await fetch('/'+p,{method:'POST',signal:ac.signal})).json()) }
+  catch{ refresh() /* on abort/error, repaint the real state from /status */ }
+  finally{ clearTimeout(to) }
+ }
+ function pending(label){
+  // Instant optimistic feedback on click; applyStatus (POST response, then the
+  // periodic poll) then owns the real state + which buttons are enabled.
+  state.textContent=label; state.className='n busy'
+  dot.className='dot amber'
+  startbtn.disabled=true; stopbtn.disabled=true
+ }
+ function setc(d){ if(conc.disabled)return; setv((parseInt(conc.value||'1'))+d) }
  async function setv(v){
   v=Math.max(1,Math.min(CAP,parseInt(v)||1)); conc.value=v
   await fetch('/concurrency',{method:'POST',headers:{'Content-Type':'application/json'},
    body:JSON.stringify({value:v})});refresh()
  }
+ async function setauto(on){
+  await fetch('/auto',{method:'POST',headers:{'Content-Type':'application/json'},
+   body:JSON.stringify({value:on})});refresh()
+ }
+ async function setbw(v){
+  v=Math.max(0,parseFloat(v)||0); bw.value=v
+  await fetch('/bandwidth',{method:'POST',headers:{'Content-Type':'application/json'},
+   body:JSON.stringify({value:v})});refresh()
+ }
  async function refresh(){
-  const s=await (await fetch('/status')).json()
-  CAP=s.max_concurrency||8; capn.textContent=CAP
-  state.textContent=s.state; active.textContent=s.active; done.textContent=s.processed
-  err.textContent=s.errors; fc.textContent=s.fc_url; wait.textContent=s.transient||0
-  // Running but the queue read failed → curator is unreachable; show we're
-  // riding it out rather than erroring.
-  banner.style.display=(s.state==='running' && !s.queue)?'block':'none'
+  let s; try{ s=await (await fetch('/status')).json() }catch{ return }
+  applyStatus(s)
+ }
+ function applyStatus(s){
+  // NB: don't write a separate `capn` element here — conchint.textContent below
+  // rewrites the whole hint (incl. the max), and any child element nested in it
+  // would be destroyed by that write, breaking the NEXT applyStatus call.
+  CAP=s.max_concurrency||8
+  // The backend owns the state now (stopped|starting|running|stopping) and drives
+  // every transition, so the pill is always truthful — no client-side guessing
+  // from active>0, which used to wedge on "stopping" forever.
+  const st=s.state||'stopped'
+  const running=st==='running'
+  const busy=(st==='starting'||st==='stopping')
+  // Stale-page guard: if the server is a newer build than this page, the cached
+  // controls may misbehave — tell the operator to reload.
+  if(s.build && s.build!==PAGE_BUILD) verbanner.style.display='block'
+  state.textContent=st
+  state.className='n'+(busy?' busy':'')
+  // Buttons follow the real state so you can't fight a transition: Start only
+  // from stopped; Stop only while up; both disabled through "stopping" until the
+  // backend truthfully lands on "stopped".
+  startbtn.disabled=(st!=='stopped')
+  stopbtn.disabled=!(running||st==='starting')
+  // Throughput rates arrive READY from the backend (jobs/min ≈ GPU throughput,
+  // dl/min ≈ fetch throughput), computed there on a fixed cadence — so they show
+  // a real number no matter how often this tab polls (a backgrounded tab throttles
+  // its timers, which used to leave a client-side delta-rate blank forever).
+  jpm.textContent=(s.jobs_per_min!=null)?Math.round(s.jobs_per_min):'—'
+  dpm.textContent=(s.downloads_per_min!=null)?Math.round(s.downloads_per_min):'—'
+  done.textContent=s.processed
+  err.textContent=s.errors; err.className='n'+(s.errors>0?' warn':'')
+  waited.textContent=s.transient||0
+  // Instantaneous pool state → demoted to the sub-line, where its jumpiness reads
+  // as live churn rather than a "broken" headline metric.
+  // '=== false' (not falsy) so a stale page that doesn't send models_loaded shows
+  // nothing; when the idle monitor unloads, the VRAM meter drops alongside this.
+  pipe.textContent='downloaders '+(s.downloaders!=null?s.downloaders:'—')+' · consumers '+(s.consumers!=null?s.consumers:'—')+' · on GPU '+(s.active||0)
+   +' · net '+(s.net_mb_s!=null?s.net_mb_s.toFixed(1):'—')+' MB/s'
+   +(s.bandwidth_limit_mb_s>0?(' / cap '+s.bandwidth_limit_mb_s):'')
+   +(s.models_loaded===false?' · GPU models unloaded (idle — reload on next job)':'')
+  if(document.activeElement!==bw && s.bandwidth_limit_mb_s!=null) bw.value=s.bandwidth_limit_mb_s
+  // Buffer occupancy bar (also driven here so it tracks the /status cadence).
+  if(s.buffer!=null && s.buffer_max){ const p=Math.round(100*s.buffer/s.buffer_max)
+   buflbl.textContent=s.buffer+' / '+s.buffer_max; bufbar.style.width=p+'%' }
+  // Auto on → dial reflects the auto-chosen count (read-only); off → manual.
+  if(document.activeElement!==autochk) autochk.checked=!!s.auto
+  conc.disabled=!!s.auto; conc.style.opacity=s.auto?0.55:1
+  conchint.textContent=(s.auto?('auto-tuning downloaders to keep the GPU fed · max '+CAP):('manual downloaders · max '+CAP))
+   +(s.idle?' · idle — queue empty, lease poll backed off (new work noticed within ~15 min)'
+     :(s.bw_capped?' · holding at the bandwidth cap (more downloaders would not go faster)':''))
   if(document.activeElement!==conc) conc.value=s.concurrency
   conc.max=CAP
-  cfg.textContent=s.configured?'set':'MISSING'
-  if(s.gpu){
-   gpu.textContent=`GPU — ${s.gpu.util_pct}% util · VRAM ${s.gpu.mem_used_mb}/${s.gpu.mem_total_mb} MB · ${s.gpu.temp_c}°C`
-   gpubar.style.width=Math.round(100*s.gpu.mem_used_mb/s.gpu.mem_total_mb)+'%'
-  } else { gpu.textContent='GPU — n/a (CPU fallback?)'; gpubar.style.width='0%' }
-  queue.textContent=s.queue?`queue — pending ${s.queue.pending} · in flight ${s.queue.leased} · done ${s.queue.done} · errored ${s.queue.error}`:'queue — unreachable'
+  // Connection pill + queue come only from the /status poll (the Start/Stop POST
+  // responses skip the slow curator call to stay snappy) — guard so an action
+  // response doesn't blank them.
+  if('configured' in s){
+   const ok=s.configured
+   fc.textContent=s.fc_url; cfg.textContent=ok?'set':'MISSING'
+   // Pill colour + label track the real state: green only when running AND
+   // curator is answering; amber for the transient states + a running-but-
+   // unreachable curator; grey when stopped; red with no token.
+   let dc='dot', lbl='stopped'
+   if(!ok){ dc='dot red'; lbl='no token' }
+   else if(st==='running'){ dc='dot '+(s.queue?'green':'amber'); lbl=s.queue?'running':'running · curator unreachable' }
+   else if(st==='starting'){ dc='dot amber'; lbl='starting…' }
+   else if(st==='stopping'){ dc='dot amber'; lbl='stopping…' }
+   dot.className=dc; connlbl.textContent=lbl
+   banner.style.display=(st==='running' && !s.queue)?'block':'none'
+   queue.textContent=s.queue?('queue · pending '+s.queue.pending+' · in flight '+s.queue.leased+' · done '+s.queue.done+' · errored '+s.queue.error):'queue · unreachable'
+  }
  }
- refresh(); setInterval(refresh,3000)
+ // GPU meters poll their OWN endpoint on a fast cadence — kept off /status so a
+ // slow curator queue call can't freeze the bars (they only stale on refresh).
+ let UAVG=null   // smoothed util for the bar (raw util swings 0↔99; show the trend)
+ async function refreshGpu(){
+  let g; try{ g=await (await fetch('/gpu')).json() }catch{ return }
+  if(g && g.util_pct!=null){
+   // Prefer the agent's own EWMA (util_smooth) when running; otherwise smooth
+   // the raw reading here so a stopped agent's bar still glides, not jumps.
+   const raw=g.util_pct
+   UAVG = (g.util_smooth!=null) ? g.util_smooth
+         : (UAVG==null ? raw : 0.25*raw + 0.75*UAVG)
+   const used=g.mem_used_mb, tot=g.mem_total_mb||1
+   utillbl.textContent=Math.round(UAVG)+'% · '+g.temp_c+'°C'; utilbar.style.width=Math.round(UAVG)+'%'
+   vramlbl.textContent=used+' / '+tot+' MB'; gpubar.style.width=Math.round(100*used/tot)+'%'
+  } else { UAVG=null; utillbl.textContent='n/a'; vramlbl.textContent='n/a (CPU?)'; utilbar.style.width='0%'; gpubar.style.width='0%' }
+ }
+ async function refreshLogs(){
+  try{
+   const r=await (await fetch('/logs')).json()
+   const el=logs, atBottom=el.scrollHeight-el.scrollTop-el.clientHeight<40
+   el.textContent=(r.lines&&r.lines.length)?r.lines.join('\\n'):'waiting for activity…'
+   if(atBottom) el.scrollTop=el.scrollHeight
+  }catch{}
+ }
+ async function copyLogs(){
+  const txt=logs.textContent||''
+  try{ await navigator.clipboard.writeText(txt) }
+  catch{ const t=document.createElement('textarea'); t.value=txt; document.body.appendChild(t);
+   t.select(); try{document.execCommand('copy')}catch{}; t.remove() }
+  copybtn.textContent='Copied'; setTimeout(()=>{copybtn.textContent='Copy'},1200)
+ }
+ refresh(); refreshGpu(); refreshLogs()
+ setInterval(refresh,3000); setInterval(refreshGpu,1500); setInterval(refreshLogs,2500)
 </script></body></html>"""

agent/fc_agent/client.py

@@ -5,19 +5,69 @@ bytes, all over HTTP with the bearer token. No DB/Redis.
 """
 import requests
 from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
 
 
 class FcClient:
     def __init__(self, base_url: str, token: str, agent_id: str):
         self.base = base_url.rstrip("/")
         self.agent_id = agent_id
-        self.s = requests.Session()
-        self.s.headers["Authorization"] = f"Bearer {token}"
-        # Many worker threads share this Session; the default pool (10) would
+        # Main session: NO in-request retry — lease/fetch are cheap to redo and
+        # the worker loop already backs off + re-leases on failure. (Auto-retrying
+        # a lease could double-claim a batch if a response is lost.)
+        self.s = self._session(token)
+        # Submit session: retry in-place, because by submit time the GPU work is
+        # already DONE — a momentary blip (dropped connection, gateway 5xx during
+        # a curator redeploy) must not throw that work away and force a full
+        # re-download + recompute on another agent. A duplicate submit after a
+        # lost response is harmless: the job is already closed, so it just returns
+        # 409 lease_invalid (a no-op). Idempotent enough to retry POST safely.
+        retry = Retry(
+            total=3, connect=3, read=3, status=3,
+            backoff_factor=0.5,                       # ~0.5s, 1s, 2s between tries
+            status_forcelist=(500, 502, 503, 504),    # transient server/gateway
+            allowed_methods=frozenset({"POST"}),
+            raise_on_status=False,                     # let raise_for_status decide
+        )
+        self._submit_s = self._session(token, retry)
+
+    @staticmethod
+    def _session(token: str, retry: Retry | None = None) -> requests.Session:
+        s = requests.Session()
+        s.headers["Authorization"] = f"Bearer {token}"
+        # Many worker threads share a Session; the default pool (10) would
         # throttle them + spam "connection pool is full". Size it for the cap.
-        adapter = HTTPAdapter(pool_connections=64, pool_maxsize=64)
-        self.s.mount("http://", adapter)
-        self.s.mount("https://", adapter)
+        adapter = HTTPAdapter(
+            pool_connections=64, pool_maxsize=64, max_retries=retry or 0
+        )
+        s.mount("http://", adapter)
+        s.mount("https://", adapter)
+        return s
+
+    def _submit(self, path: str, payload: dict) -> dict:
+        """POST to a submit endpoint on the RETRYING session (by submit time the
+        GPU work is done — a blip must not throw it away), raise on a hard error,
+        and return the parsed JSON. `agent_id` is added to every body."""
+        r = self._submit_s.post(
+            f"{self.base}{path}",
+            json={"agent_id": self.agent_id, **payload},
+            timeout=120,
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def _post_quiet(self, path: str, payload: dict) -> None:
+        """Fire-and-forget POST on the main session — heartbeat/fail/release are
+        best-effort, so a transport error is swallowed (the worker's own retry and
+        the server's orphan-recovery cover a lost call). `agent_id` is added."""
+        try:
+            self.s.post(
+                f"{self.base}{path}",
+                json={"agent_id": self.agent_id, **payload},
+                timeout=30,
+            )
+        except requests.RequestException:
+            pass
 
     def lease(self, batch_size: int) -> list[dict]:
         r = self.s.post(
@@ -29,57 +79,62 @@ class FcClient:
         return r.json().get("jobs", [])
 
     def submit(self, job_id: int, regions: list[dict], replace_kinds: list[str]) -> dict:
-        r = self.s.post(
-            f"{self.base}/api/gpu/jobs/submit",
-            json={
-                "agent_id": self.agent_id, "job_id": job_id,
-                "regions": regions, "replace_kinds": replace_kinds,
-            },
-            timeout=120,
-        )
-        r.raise_for_status()
-        return r.json()
+        return self._submit("/api/gpu/jobs/submit", {
+            "job_id": job_id, "regions": regions, "replace_kinds": replace_kinds,
+        })
+
+    def submit_embedding(self, job_id: int, embedding: list, version: str) -> dict:
+        """Post a whole-image SigLIP embedding (the 'embed' task) → image_record."""
+        return self._submit("/api/gpu/jobs/submit_embedding", {
+            "job_id": job_id, "embedding": embedding, "embedding_version": version,
+        })
 
     def heartbeat(self, job_ids: list[int]) -> None:
-        try:
-            self.s.post(
-                f"{self.base}/api/gpu/jobs/heartbeat",
-                json={"agent_id": self.agent_id, "job_ids": job_ids},
-                timeout=30,
-            )
-        except requests.RequestException:
-            pass
+        self._post_quiet("/api/gpu/jobs/heartbeat", {"job_ids": job_ids})
 
     def fail(self, job_id: int, error: str) -> None:
-        try:
-            self.s.post(
-                f"{self.base}/api/gpu/jobs/fail",
-                json={"agent_id": self.agent_id, "job_id": job_id, "error": error},
-                timeout=30,
-            )
-        except requests.RequestException:
-            pass
+        self._post_quiet("/api/gpu/jobs/fail", {"job_id": job_id, "error": error})
 
     def release(self, job_ids: list[int]) -> None:
         # Graceful hand-back on stop so orphaned work is re-leased at once.
         if not job_ids:
             return
-        try:
-            self.s.post(
-                f"{self.base}/api/gpu/jobs/release",
-                json={"agent_id": self.agent_id, "job_ids": job_ids},
-                timeout=30,
-            )
-        except requests.RequestException:
-            pass
+        self._post_quiet("/api/gpu/jobs/release", {"job_ids": job_ids})
 
-    def fetch_image(self, image_url: str) -> bytes:
+    def fetch_image(self, image_url: str, throttle=None) -> bytes:
         # image_url is a server-relative path ("/images/...").
-        r = self.s.get(f"{self.base}{image_url}", timeout=180)
-        r.raise_for_status()
-        return r.content
+        # timeout=(connect, read): the read timeout is BETWEEN-BYTES, not total,
+        # so a large-but-flowing download still completes — but a stuck/dead
+        # connection (curator overloaded) fails in 60s instead of hanging a
+        # downloader for 180s and piling up concurrent stuck requests on curator.
+        # With a throttle (the worker's shared TokenBucket), the body is streamed
+        # in chunks and each chunk is charged to the global bandwidth budget —
+        # pausing between reads lets TCP flow control pace curator's send side.
+        with self.s.get(
+            f"{self.base}{image_url}", timeout=(10, 60), stream=throttle is not None
+        ) as r:
+            r.raise_for_status()
+            if throttle is None:
+                return r.content
+            buf = bytearray()
+            for chunk in r.iter_content(chunk_size=262_144):
+                throttle.take(len(chunk))
+                buf.extend(chunk)
+            return bytes(buf)
+
+    def is_reachable(self) -> bool:
+        """Cheap 'is curator responding at all right now?' check. Used to decide,
+        when a video can't be sampled, between a transient outage (keep retrying —
+        survives a redeploy) and an unprocessable file (fail it, don't loop)."""
+        try:
+            r = self.s.get(f"{self.base}/api/gpu/status", timeout=5)
+            return r.status_code < 500
+        except requests.RequestException:
+            return False
 
     def queue_status(self) -> dict:
-        r = self.s.get(f"{self.base}/api/gpu/status", timeout=15)
+        # Short timeout: this backs the UI /status poll, so a busy curator must
+        # not hang the page for long (the GPU meters poll /gpu separately).
+        r = self.s.get(f"{self.base}/api/gpu/status", timeout=5)
         r.raise_for_status()
         return r.json()

agent/fc_agent/config.py

@@ -1,8 +1,18 @@
 """Agent config, all from env (the control container is configured at run)."""
+# Lazy annotations so the `from_env(cls) -> Config` self-reference is a string,
+# not evaluated at class-definition time — otherwise it NameErrors on the agent's
+# Python 3.10 (CI lints on 3.14, where PEP 649 hides this).
+from __future__ import annotations
+
 import os
 from dataclasses import dataclass
 
 
+def _bool_env(name: str, default: str = "") -> bool:
+    """A boolean env var — present + truthy ('1'/'true'/'yes') → True."""
+    return os.environ.get(name, default).lower() in ("1", "true", "yes")
+
+
 @dataclass
 class Config:
     fc_url: str          # base URL of the FabledCurator web service
@@ -18,9 +28,38 @@ class Config:
     #                            the server announces in the lease)
     auto_start: bool     # start the worker pool on boot (so a container restart
     #                      resumes processing without anyone clicking Start)
+    auto_scale: bool     # autoscale the worker count (throughput hill-climb)
+    # Crop PROPOSERS (extra YOLO detectors that say where to crop). Each weight
+    # spec is an ultralytics name | http(s) URL | "hf_repo::file" ("" = off).
+    person_weights: str  # general COCO person detector (Western/realistic figs)
+    person_conf: float
+    anatomy_weights: str  # booru_yolo anime/furry/NSFW components
+    anatomy_conf: float
+    panel_weights: str    # comic-panel detector
+    panel_conf: float
+    max_components: int   # cap anatomy component crops per frame
+    max_panels: int       # cap panel crops per frame
+    max_figures: int      # cap figure boxes per frame (each = a CCIP call + crop)
+    max_regions: int      # hard cap on total regions per JOB (submit-size backstop)
+    dedupe_iou: float     # crops overlapping >= this (same kind) are near-dupes,
+    #                       dropped before the embed; >=1.0 disables it
+    frame_dedupe_distance: int  # video frames whose dHash differs by < this many
+    #                             bits are near-duplicates, dropped before detect;
+    #                             higher keeps more frames, 0 disables
+    ffmpeg_timeout: float  # hard ceiling (s) for ffmpeg-from-URL video sampling;
+    #                        generous so a SLOW media link still completes
+    bandwidth_limit_mb_s: float  # aggregate download cap in MEGABYTES/s across
+    #                              all downloaders + video streams (0 = unlimited);
+    #                              tunable live from the agent UI
+    idle_unload_seconds: float   # after this long with the GPU idle (nothing in
+    #                              flight, queue empty or Stopped), unload the
+    #                              SigLIP embedder + YOLO proposers to free their
+    #                              VRAM; they reload lazily on the next job. A
+    #                              24/7 agent otherwise squats on ~5GB doing
+    #                              nothing. 0 disables (keep models warm forever).
 
     @classmethod
-    def from_env(cls) -> "Config":
+    def from_env(cls) -> Config:
         return cls(
             fc_url=os.environ.get("FC_URL", "http://localhost:8000").rstrip("/"),
             token=os.environ.get("FC_TOKEN", ""),
@@ -32,5 +71,30 @@ class Config:
             poll_idle_seconds=float(os.environ.get("POLL_IDLE_SECONDS", "10")),
             embed_dtype=os.environ.get("SIGLIP_DTYPE", "float16"),
             embed_model_override=os.environ.get("EMBED_MODEL_NAME", ""),
-            auto_start=os.environ.get("AUTO_START", "").lower() in ("1", "true", "yes"),
+            auto_start=_bool_env("AUTO_START"),
+            auto_scale=_bool_env("AUTO_SCALE", "true"),
+            person_weights=os.environ.get("PERSON_WEIGHTS", "yolo11n.pt"),
+            person_conf=float(os.environ.get("PERSON_CONF", "0.35")),
+            anatomy_weights=os.environ.get("ANATOMY_WEIGHTS", ""),
+            anatomy_conf=float(os.environ.get("ANATOMY_CONF", "0.30")),
+            panel_weights=os.environ.get("PANEL_WEIGHTS", ""),
+            panel_conf=float(os.environ.get("PANEL_CONF", "0.30")),
+            max_components=int(os.environ.get("MAX_COMPONENTS", "8")),
+            max_panels=int(os.environ.get("MAX_PANELS", "8")),
+            max_figures=int(os.environ.get("MAX_FIGURES", "8")),
+            max_regions=int(os.environ.get("MAX_REGIONS", "128")),
+            dedupe_iou=float(os.environ.get("DEDUPE_IOU", "0.85")),
+            frame_dedupe_distance=int(os.environ.get("FRAME_DEDUPE_DISTANCE", "8")),
+            ffmpeg_timeout=float(os.environ.get("FFMPEG_TIMEOUT", "1200")),
+            # Default 8 MB/s (~64 Mbit/s): ~20% of the measured ~300 Mbit/s home
+            # WiFi, so browsing stays snappy while the agent works — yet MORE
+            # sweep throughput than the self-inflicted congestion collapse this
+            # replaces (2026-07-02: 8 unthrottled downloaders bufferbloated the
+            # link to ~1-1.5 MB/s per stream, browser included). Raise it (or 0)
+            # from the agent UI on wired/faster networks.
+            bandwidth_limit_mb_s=float(os.environ.get("BANDWIDTH_LIMIT_MB_S", "8")),
+            # 5 min: long enough that a lull between job bursts doesn't thrash the
+            # (few-second) reload, short enough that an agent left running with an
+            # empty queue hands its VRAM back promptly.
+            idle_unload_seconds=float(os.environ.get("IDLE_UNLOAD_SECONDS", "300")),
         )

agent/fc_agent/detectors.py

@@ -0,0 +1,233 @@
+"""Region PROPOSERS — small YOLO detectors that decide WHERE to crop. They run
+on the agent GPU and their boxes feed the crop → SigLIP → max-over-bag pipeline:
+
+  - person (general COCO yolo11n): full-figure boxes for realistic / Western art
+    the anime person-detector misses; NMS-merged with imgutils detect_person and
+    fed to CCIP (identity) + a concept crop.
+  - anatomy (booru_yolo): anime / furry / NSFW torso components (head, cat-head,
+    boob, hip, …) — concept crops aligned to the operator's tag vocabulary.
+  - panel (mosesb): a comic page → panel regions → concept crops.
+
+Each proposer is INDEPENDENTLY optional + guarded: a bad weight path or an
+inference error disables just that proposer (logged) and never breaks the
+worker, which still falls back to imgutils detection. Weights resolve from an
+ultralytics builtin name ("yolo11n.pt"), an http(s) URL, or "hf_repo::file" —
+cached under HF_HOME so the download happens once.
+"""
+import logging
+import os
+import threading
+import types
+from pathlib import Path
+
+log = logging.getLogger("fc_agent.detectors")
+_CACHE = Path(os.environ.get("HF_HOME", "/models")) / "yolo"
+
+
+def _resolve(spec: str) -> str | None:
+    """A local weights path (downloading if needed) or an ultralytics builtin
+    name. None if the spec is empty/unresolvable."""
+    if not spec:
+        return None
+    if "::" in spec:                                    # hf_repo::filename
+        repo, _, fname = spec.partition("::")
+        from huggingface_hub import hf_hub_download
+        return hf_hub_download(
+            repo_id=repo, filename=fname, cache_dir=str(_CACHE)
+        )
+    if spec.startswith(("http://", "https://")):
+        _CACHE.mkdir(parents=True, exist_ok=True)
+        dest = _CACHE / spec.rsplit("/", 1)[-1]
+        if not dest.is_file():
+            import requests
+            r = requests.get(spec, timeout=300)
+            r.raise_for_status()
+            dest.write_bytes(r.content)
+        return str(dest)
+    return spec                                         # ultralytics builtin name
+
+
+def _iou(a, b) -> float:
+    ax, ay, aw, ah = a
+    bx, by, bw, bh = b
+    ix = max(0.0, min(ax + aw, bx + bw) - max(ax, bx))
+    iy = max(0.0, min(ay + ah, by + bh) - max(ay, by))
+    inter = ix * iy
+    union = aw * ah + bw * bh - inter
+    return inter / union if union > 0 else 0.0
+
+
+def nms_merge(boxes, iou_thresh: float = 0.6):
+    """Greedy NMS over (bbox_norm, score, label) from possibly several detectors,
+    so the same figure found by two of them collapses to one (higher-score) box."""
+    kept = []
+    for bb, sc, lb in sorted(boxes, key=lambda b: b[1], reverse=True):
+        if all(_iou(bb, k[0]) < iou_thresh for k in kept):
+            kept.append((bb, sc, lb))
+    return kept
+
+
+def dedupe_crops(pending, iou_thresh: float = 0.85):
+    """Greedy high-IoU dedupe over a list of (crop, region_template) pairs, run
+    just before the batched SigLIP embed so we never embed the same region twice.
+
+    Figure boxes are already NMS-merged and each YOLO self-NMSes, but the combined
+    per-frame pile (figure→concept ∪ anatomy component→concept ∪ panel) can still
+    carry genuine near-duplicates across proposers — e.g. a figure box that nearly
+    coincides with an anatomy component on a solo bust, or overlapping booru head
+    classes on one head. Those embed the same region twice, wasting GPU and a slot
+    against max_regions.
+
+    Boxes are compared ONLY within the same output kind and dropped when they
+    overlap at >= iou_thresh, keeping the highest-scoring one. The HIGH default
+    threshold is deliberate: it collapses only true near-identical boxes while
+    preserving intentional nested crops across scopes (a whole figure vs a small
+    head component sit well below it) and distinct kinds (concept vs panel). A
+    value >= 1.0 effectively disables it (nothing but an exact box matches)."""
+    kept = []
+    kept_boxes: dict = {}   # kind -> [bbox, ...] already kept
+    for crop, tmpl in sorted(
+        pending, key=lambda p: p[1].get("score") or 0.0, reverse=True
+    ):
+        bb = tmpl.get("bbox")
+        prior = kept_boxes.setdefault(tmpl.get("kind"), [])
+        if bb is not None and any(_iou(bb, kb) >= iou_thresh for kb in prior):
+            continue
+        prior.append(bb)
+        kept.append((crop, tmpl))
+    return kept
+
+
+class YoloProposer:
+    """One lazily-loaded ultralytics YOLO. detect(image) → [(bbox_norm, score,
+    label)] with bbox normalized (x, y, w, h) in [0,1]. Self-disables on any
+    load/inference failure."""
+
+    def __init__(self, name, weights, conf=0.25, keep_labels=None):
+        self.name = name
+        self._spec = weights
+        self._conf = conf
+        self._keep = [k.lower() for k in keep_labels] if keep_labels else None
+        self._model = None
+        self._ok = True
+        self._lock = threading.Lock()
+
+    def _load(self):
+        if self._model is not None or not self._ok:
+            return
+        with self._lock:
+            if self._model is not None or not self._ok:
+                return
+            try:
+                from ultralytics import YOLO
+                path = _resolve(self._spec)
+                if path is None:
+                    self._ok = False
+                    return
+                self._model = YOLO(path)
+                # Disable ultralytics' load-time Conv+BN fusion. AutoBackend fuses
+                # the graph on the first predict; some checkpoints (yolo11n, the
+                # comic-panel model) crash that step with "'Conv' object has no
+                # attribute 'bn'" (a partially-fused / version-mismatched graph),
+                # which silently disabled those proposers (operator-flagged
+                # 2026-07-01). Unfused inference is correct — only marginally
+                # slower — and this is robust across ultralytics versions; if a
+                # future version ignores the override, the detect() guard below
+                # still self-disables the proposer instead of spamming per image.
+                inner = getattr(self._model, "model", None)
+                if inner is not None:
+                    inner.fuse = types.MethodType(lambda self, *a, **k: self, inner)
+                log.info("detector %s loaded (%s)", self.name, path)
+            except Exception as exc:   # noqa: BLE001
+                log.warning("detector %s disabled (load failed): %s", self.name, exc)
+                self._ok = False
+
+    def detect(self, image):
+        self._load()
+        if self._model is None:
+            return []
+        try:
+            res = self._model.predict(image, conf=self._conf, verbose=False)[0]
+        except Exception as exc:   # noqa: BLE001
+            # Permanently self-disable on the FIRST inference failure rather than
+            # re-throwing (and re-logging) on every image forever — an unfixable
+            # model fault degrades to "this proposer is off", logged once.
+            log.warning("detector %s disabled (inference failed): %s", self.name, exc)
+            self._ok = False
+            self._model = None
+            return []
+        iw, ih = image.size
+        names = getattr(res, "names", None) or {}
+        out = []
+        for b in res.boxes:
+            label = str(names.get(int(b.cls), int(b.cls))).lower()
+            if self._keep is not None and not any(k in label for k in self._keep):
+                continue
+            x0, y0, x1, y1 = (float(v) for v in b.xyxy[0].tolist())
+            out.append((
+                (x0 / iw, y0 / ih, (x1 - x0) / iw, (y1 - y0) / ih),
+                float(b.conf), label,
+            ))
+        return out
+
+    def unload(self) -> None:
+        """Drop the loaded YOLO so its VRAM can be reclaimed; detect() reloads it
+        lazily on the next job. Leaves _ok untouched — a healthy proposer comes
+        back, but one that self-disabled on a fault stays off."""
+        with self._lock:
+            self._model = None
+
+
+class Proposers:
+    """The agent's proposer set, built from config. Each detector is optional —
+    an empty weight spec leaves that proposer off."""
+
+    def __init__(self, cfg):
+        self.cfg = cfg
+        self._person = (
+            YoloProposer("person-coco", cfg.person_weights,
+                         conf=cfg.person_conf, keep_labels=["person"])
+            if cfg.person_weights else None
+        )
+        self._anatomy = (
+            YoloProposer("anatomy", cfg.anatomy_weights, conf=cfg.anatomy_conf)
+            if cfg.anatomy_weights else None
+        )
+        self._panel = (
+            YoloProposer("panel", cfg.panel_weights, conf=cfg.panel_conf)
+            if cfg.panel_weights else None
+        )
+
+    def figures(self, image, base_boxes):
+        """Merge imgutils person boxes (base_boxes: [(bbox, score)]) with the
+        general COCO person detector → NMS'd figure boxes [(bbox, score, label)],
+        capped to the highest-scoring max_figures. Uncapped, a busy/huge image
+        (many characters) yields hundreds of boxes → hundreds of per-figure CCIP
+        calls + crops → a 30s+ job and an oversized submit (operator-flagged)."""
+        boxes = [(bb, sc if sc is not None else 1.0, "person") for bb, sc in base_boxes]
+        if self._person is not None:
+            boxes += self._person.detect(image)
+        return nms_merge(boxes)[: self.cfg.max_figures]   # nms_merge is score-desc
+
+    @staticmethod
+    def _top(detector, image, cap: int):
+        """Top-`cap` detections by score from an optional proposer (None → the
+        proposer is off → []). Shared by the anatomy + panel proposers, which
+        differ only in which detector and which cap."""
+        if detector is None:
+            return []
+        return sorted(detector.detect(image), key=lambda b: b[1], reverse=True)[:cap]
+
+    def components(self, image):
+        return self._top(self._anatomy, image, self.cfg.max_components)
+
+    def panels(self, image):
+        return self._top(self._panel, image, self.cfg.max_panels)
+
+    def unload(self) -> None:
+        """Release every loaded proposer's YOLO (idle VRAM reclaim). The worker
+        also drops its reference to this Proposers and rebuilds a fresh one via
+        _proposers_for on the next job, so this is belt-and-braces."""
+        for p in (self._person, self._anatomy, self._panel):
+            if p is not None:
+                p.unload()

agent/fc_agent/embedder.py

@@ -58,12 +58,35 @@ class CropEmbedder:
 
     def embed(self, image: Image.Image) -> list[float]:
         """A crop → its embedding as a plain float list, ready to POST."""
+        return self.embed_batch([image])[0]
+
+    def embed_batch(self, images: list) -> list[list[float]]:
+        """Embed many crops in ONE forward pass — far better GPU utilisation +
+        only one lock acquisition than embedding each crop separately (which
+        starved the GPU and serialised the whole pool)."""
+        if not images:
+            return []
         self.load()
         torch = self._torch
-        enc = self._processor(images=image, return_tensors="pt")
+        enc = self._processor(images=images, return_tensors="pt")
         pixel_values = enc["pixel_values"].to(self._device, self._dt)
         with self._infer_lock, torch.no_grad():
             out = self._model.get_image_features(pixel_values=pixel_values)
         pooled = out.pooler_output if hasattr(out, "pooler_output") else out
-        vec = pooled[0].float().cpu().numpy().astype(np.float32).reshape(-1)
-        return vec.tolist()
+        arr = pooled.float().cpu().numpy().astype(np.float32)
+        return [row.reshape(-1).tolist() for row in arr]
+
+    def unload(self) -> bool:
+        """Drop the loaded model so its VRAM can be reclaimed — the idle monitor
+        calls this after a spell with no work so an idle agent doesn't squat on
+        the card; the next embed() reloads it lazily (a few seconds). Held under
+        BOTH the load and inference locks so it can never race a concurrent load
+        or an in-flight forward pass. Returns True if a model was actually
+        released (the caller then runs one empty_cache() to hand the freed blocks
+        back to the driver)."""
+        with self._load_lock, self._infer_lock:
+            if self._model is None:
+                return False
+            self._model = None
+            self._processor = None
+            return True

agent/fc_agent/gpu.py

@@ -1,10 +1,24 @@
 """GPU load readout via nvidia-smi (present in the container thanks to the
 NVIDIA Container Toolkit's `utility` capability). Returns None if unavailable —
-the UI just shows n/a (e.g. CPU-fallback run)."""
+the UI just shows n/a (e.g. CPU-fallback run).
+
+Reads are CACHED and de-duplicated: the UI meter polls fast, /status reads it,
+and the autoscaler samples it — if each spawned its own `nvidia-smi` (slow on a
+busy GPU) those blocking subprocesses would pile up in the server's thread pool
+and make the Start/Stop buttons feel dead. So a short TTL serves recent callers
+from cache, and only ONE probe runs at a time (others get the last value)."""
 import subprocess
+import threading
+import time
+
+_TTL = 1.0                       # seconds a sample is reused before re-probing
+_lock = threading.Lock()
+_cache: dict | None = None
+_cache_t = 0.0
+_probing = False
 
 
-def read_gpu() -> dict | None:
+def _probe() -> dict | None:
     try:
         out = subprocess.run(
             [
@@ -28,3 +42,24 @@ def read_gpu() -> dict | None:
         }
     except (ValueError, IndexError):
         return None
+
+
+def read_gpu(max_age: float = _TTL) -> dict | None:
+    """Latest GPU reading, cached. Serves from cache when fresh; when stale,
+    exactly one caller re-probes while the rest get the last value — so request
+    threads never block behind more than one `nvidia-smi`."""
+    global _cache, _cache_t, _probing
+    now = time.monotonic()
+    with _lock:
+        fresh = _cache is not None and (now - _cache_t) < max_age
+        if fresh or _probing:        # fresh, or a probe is already running
+            return _cache
+        _probing = True
+    try:
+        val = _probe()
+    finally:
+        with _lock:
+            _cache = val
+            _cache_t = time.monotonic()
+            _probing = False
+    return val

agent/fc_agent/logbuf.py

@@ -0,0 +1,44 @@
+"""In-memory log ring buffer so the control UI can show recent agent logs
+(detector loads, job errors, autoscaler decisions, outage back-offs) without
+needing `docker logs`. A bounded deque holds the last N formatted lines; a
+logging.Handler appends to it; the UI polls /logs."""
+import logging
+from collections import deque
+
+LINES: deque[str] = deque(maxlen=400)
+
+
+class RingHandler(logging.Handler):
+    def emit(self, record: logging.LogRecord) -> None:
+        try:
+            LINES.append(self.format(record))
+        except Exception:
+            pass
+
+
+_installed = False
+
+
+def install(level: int = logging.INFO) -> None:
+    """Attach the ring handler to the root logger once. fc_agent module loggers
+    propagate to root, so their records land here."""
+    global _installed
+    if _installed:
+        return
+    _installed = True
+    h = RingHandler()
+    h.setFormatter(
+        logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s", "%H:%M:%S")
+    )
+    root = logging.getLogger()
+    root.addHandler(h)
+    if root.level == logging.NOTSET or root.level > level:
+        root.setLevel(level)
+    # Keep the buffer signal-rich: silence the chatty HTTP/download libs (every
+    # HF model fetch logs per-request) so the console shows agent activity —
+    # detector loads, job errors, autoscale moves — not request spam.
+    for noisy in (
+        "uvicorn.access", "ultralytics", "httpx", "httpcore",
+        "huggingface_hub", "urllib3", "filelock",
+    ):
+        logging.getLogger(noisy).setLevel(logging.WARNING)

agent/fc_agent/media.py

@@ -2,17 +2,77 @@
 (ffmpeg) at the cadence FC sends — so a video becomes a bag of per-frame
 instances, each with a timestamp."""
 import io
+import logging
 import os
+import signal
 import subprocess
 import tempfile
+import time
 
-from PIL import Image
+from PIL import Image, ImageFile
+
+from .throttle import PidReadMeter
+
+log = logging.getLogger("fc_agent.media")
+
+# Load slightly-truncated images (a few missing trailing bytes) instead of
+# raising — matches the server embedder. These are common in scraped libraries
+# and would otherwise fail the job 3× then error (operator-flagged 2026-06-30).
+ImageFile.LOAD_TRUNCATED_IMAGES = True
+
+# Disable PIL's decompression-bomb guard: this is a TRUSTED local library, not an
+# untrusted upload surface, so a legitimately huge image (high-res scans/prints,
+# 90M+ pixels) must load. The default 89M-pixel limit only WARNS, but PIL raises
+# DecompressionBombError at 2× (~179M px) — which would fail those jobs outright
+# (operator-flagged 2026-06-30, images of 90–95M px).
+Image.MAX_IMAGE_PIXELS = None
 
 
 def is_video(mime: str) -> bool:
     return bool(mime) and (mime.startswith("video/") or mime in {"image/gif"})
 
 
+def _dhash(img: Image.Image, size: int = 8) -> int:
+    """Difference hash: compare adjacent pixels of a (size+1 × size) grayscale
+    thumbnail → a `size*size`-bit fingerprint. Cheap (64 comparisons on a 72-px
+    thumbnail) and robust to scaling/compression noise — near-identical frames
+    hash within a few bits, a real scene change moves many."""
+    small = img.convert("L").resize((size + 1, size))
+    px = list(small.getdata())
+    bits = 0
+    for row in range(size):
+        base = row * (size + 1)
+        for col in range(size):
+            bits = (bits << 1) | int(px[base + col] > px[base + col + 1])
+    return bits
+
+
+def dedupe_frames(
+    frames: list[tuple[float, Image.Image]], min_distance: int
+) -> list[tuple[float, Image.Image]]:
+    """Drop visually near-duplicate frames. A near-static video sampled into many
+    frames re-runs the WHOLE detect→CCIP→SigLIP chain on ~identical frames — the
+    dominant video load. Greedy perceptual-hash dedup: keep a frame only if its
+    dHash differs from every already-kept frame by >= min_distance bits (Hamming),
+    so a static run collapses to one frame while genuinely distinct scenes all
+    survive. Order + timestamps preserved. CPU-only (64-bit int XORs), so it runs
+    in the decode stage and spares the GPU the skipped frames entirely.
+
+    min_distance is the coarseness dial: higher keeps more frames (safer for brief
+    localized changes an 8×8 hash can miss), 0 disables. The first frame is always
+    kept (nothing to compare against)."""
+    if min_distance <= 0 or len(frames) <= 1:
+        return frames
+    kept: list[tuple[float, Image.Image]] = []
+    hashes: list[int] = []
+    for t, frame in frames:
+        h = _dhash(frame)
+        if all(bin(h ^ k).count("1") >= min_distance for k in hashes):
+            hashes.append(h)
+            kept.append((t, frame))
+    return kept
+
+
 def to_rgb(img: Image.Image) -> Image.Image:
     """RGB, flattening any transparency onto white first. A naive convert('RGB')
     on a palette-with-transparency image (common for character PNGs on a clear
@@ -32,32 +92,162 @@ def load_image(data: bytes) -> Image.Image:
     return to_rgb(Image.open(io.BytesIO(data)))
 
 
-def sample_frames(
-    data: bytes, interval_seconds: float, max_frames: int
+# ffmpeg reconnect flags — resume a dropped HTTP transfer (a slow/contended media
+# store can cut a long stream) instead of failing the whole job. Relies only on
+# HTTP + Range, which every FC deployment serves → environment-agnostic.
+_RECONNECT = [
+    "-reconnect", "1", "-reconnect_streamed", "1",
+    "-reconnect_on_network_error", "1", "-reconnect_delay_max", "5",
+]
+
+
+def _collect_frames(
+    tmp: str, interval: float, cap: int
 ) -> list[tuple[float, Image.Image]]:
-    """Extract up to max_frames frames at one-every-interval_seconds via ffmpeg.
-    Returns [(timestamp_seconds, frame)]. Empty on failure (caller falls back)."""
+    out: list[tuple[float, Image.Image]] = []
+    names = sorted(n for n in os.listdir(tmp) if n.startswith("f_"))
+    for i, name in enumerate(names[:cap]):
+        with Image.open(os.path.join(tmp, name)) as im:
+            out.append((round(i * interval, 2), to_rgb(im)))
+    return out
+
+
+def _terminate(proc: subprocess.Popen) -> None:
+    """Stop an ffmpeg cleanly, then hard-kill if it ignores SIGTERM."""
+    try:
+        # A bandwidth-paused (SIGSTOPped) process can't receive SIGTERM until it
+        # resumes — always CONT first so termination is prompt, not queued.
+        proc.send_signal(signal.SIGCONT)
+    except OSError:
+        pass
+    proc.terminate()
+    try:
+        proc.wait(timeout=2)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        try:
+            proc.wait(timeout=2)
+        except subprocess.TimeoutExpired:
+            pass
+
+
+def _pause(proc: subprocess.Popen, seconds: float, should_stop) -> bool:
+    """SIGSTOP ffmpeg for ~`seconds` of bandwidth debt, staying responsive to
+    Stop. While paused, the kernel socket buffer fills and TCP flow control
+    stalls curator's send side — that's the throttle. SIGCONT is ALWAYS sent
+    before returning. False = a Stop arrived mid-pause."""
+    try:
+        proc.send_signal(signal.SIGSTOP)
+    except OSError:
+        return True                     # already exited — nothing to pause
+    try:
+        end = time.monotonic() + seconds
+        while (left := end - time.monotonic()) > 0:
+            if should_stop and should_stop():
+                return False
+            time.sleep(min(0.5, left))
+        return True
+    finally:
+        try:
+            proc.send_signal(signal.SIGCONT)
+        except OSError:
+            pass
+
+
+def sample_frames_from_url(
+    url: str, interval_seconds: float, max_frames: int,
+    *, headers: str = "", timeout: float = 1200.0, should_stop=None,
+    governor=None,
+) -> tuple[list[tuple[float, Image.Image]], str | None]:
+    """Sample frames by pointing ffmpeg STRAIGHT at the media URL — it Range-reads
+    only the video index + up to max_frames worth of content, so the agent never
+    downloads the whole file (VR/4K originals run 800MB+ and would buffer ~1GB in
+    RAM and get cut off mid-download). Reconnect flags resume a dropped transfer;
+    the timeout is the per-video ceiling (a slow/reconnecting stream can otherwise
+    run for minutes). `should_stop` is polled while ffmpeg runs so a Stop KILLS the
+    subprocess at once — otherwise a downloader stuck in a long decode keeps the
+    agent "working" long after Stop. `governor` (the worker's shared TokenBucket)
+    meters ffmpeg's network reads from outside via /proc/<pid>/io and SIGSTOPs
+    the process into budget, so video streaming honors the same aggregate
+    bandwidth cap as still downloads.
+
+    Returns (frames, reason): frames is empty on failure/stop/timeout, and
+    `reason` then carries the SPECIFIC cause (ffmpeg's stderr tail / timeout) so
+    the caller can put it in the job's error — a bare "no frames" hid a filter
+    bug as "unprocessable" for weeks. None reason on success."""
     interval = max(0.5, float(interval_seconds or 4.0))
     cap = max(1, int(max_frames or 64))
+    hdr = ["-headers", headers] if headers else []
+    # select (NOT the fps filter): always keep the FIRST frame, then one per
+    # `interval` seconds of timestamp. fps=1/N emits round(duration/N) frames,
+    # which is ZERO for any clip shorter than ~N/2 seconds — a whole class of
+    # short animation loops failed as "unprocessable" that way (operator-flagged
+    # 2026-07-02: 0.5s/1.75s clips). scale=out_range=full converts limited-range
+    # yuv420p to full range so the mjpeg (jpg) encoder accepts it at default
+    # strictness instead of erroring on "non full-range YUV".
+    vf = (
+        f"select='isnan(prev_selected_t)+gte(t-prev_selected_t\\,{interval})',"
+        "scale=out_range=full"
+    )
     with tempfile.TemporaryDirectory() as tmp:
-        src = os.path.join(tmp, "in")
-        with open(src, "wb") as fh:
-            fh.write(data)
         pattern = os.path.join(tmp, "f_%05d.jpg")
+        cmd = ["ffmpeg", "-nostdin", "-loglevel", "error", *_RECONNECT, *hdr,
+               "-i", url, "-vf", vf, "-fps_mode", "vfr",
+               "-frames:v", str(cap), "-q:v", "3", pattern]
+        # ffmpeg's stderr goes to a file (not a PIPE, which could fill and
+        # deadlock; not DEVNULL, which is how a filter bug hid as "unprocessable"
+        # for weeks) — on failure its tail is logged so the operator can see WHY.
+        errpath = os.path.join(tmp, "stderr.txt")
         try:
-            subprocess.run(
-                [
-                    "ffmpeg", "-nostdin", "-loglevel", "error", "-i", src,
-                    "-vf", f"fps=1/{interval}", "-frames:v", str(cap),
-                    "-q:v", "3", pattern,
-                ],
-                check=True, timeout=600,
-            )
-        except (subprocess.SubprocessError, FileNotFoundError):
-            return []
-        out: list[tuple[float, Image.Image]] = []
-        names = sorted(n for n in os.listdir(tmp) if n.startswith("f_"))
-        for i, name in enumerate(names[:cap]):
-            with Image.open(os.path.join(tmp, name)) as im:
-                out.append((round(i * interval, 2), to_rgb(im)))
-        return out
+            with open(errpath, "wb") as errf:
+                proc = subprocess.Popen(
+                    cmd, stdin=subprocess.DEVNULL,
+                    stdout=subprocess.DEVNULL, stderr=errf,
+                )
+                meter = PidReadMeter(proc.pid) if governor is not None else None
+                # Poll rather than block, so a Stop (or the per-video timeout) can
+                # kill a slow/wedged ffmpeg promptly instead of waiting it out.
+                start = time.monotonic()
+                while True:
+                    try:
+                        proc.wait(timeout=0.5)
+                        break
+                    except subprocess.TimeoutExpired:
+                        stopped = should_stop and should_stop()
+                        if stopped or (time.monotonic() - start > timeout):
+                            _terminate(proc)
+                            if stopped:
+                                return [], "stopped"
+                            log.warning("ffmpeg timed out after %.0fs: %s",
+                                        timeout, url)
+                            return [], f"ffmpeg timed out after {timeout:.0f}s"
+                        if meter is not None:
+                            read = meter.delta()
+                            if read is None:      # /proc gone → stop governing
+                                meter = None
+                            elif (debt := governor.charge(read)) > 0:
+                                # Over budget: pause ffmpeg until the bucket
+                                # recovers. Pause time counts toward `timeout`
+                                # (it stays the wedge backstop either way).
+                                if not _pause(proc, debt, should_stop):
+                                    _terminate(proc)
+                                    return [], "stopped"
+        except (OSError, ValueError) as exc:
+            return [], f"ffmpeg not runnable: {exc}"
+        frames = _collect_frames(tmp, interval, cap)
+        if not frames:
+            reason = f"ffmpeg exit {proc.returncode}: {_tail(errpath)}"
+            log.warning("ffmpeg produced no frames for %s — %s", url, reason)
+            return [], reason
+        return frames, None
+
+
+def _tail(path: str, limit: int = 300) -> str:
+    """Last `limit` chars of a (stderr) file, flattened — for failure logs."""
+    try:
+        with open(path, "rb") as f:
+            f.seek(0, os.SEEK_END)
+            f.seek(max(0, f.tell() - limit))
+            return f.read().decode("utf-8", "replace").replace("\n", " ").strip()
+    except OSError:
+        return "?"

agent/fc_agent/throttle.py

@@ -0,0 +1,111 @@
+"""Global download-bandwidth governor (one token bucket for the whole agent).
+
+The agent lives on someone's desktop and shares that desktop's network —
+typically WiFi, where saturating the link doesn't just slow other apps: it
+bufferbloats the airtime (RTT 21→45ms) and collapses EVERY connection,
+the operator's browser included. Measured 2026-07-02: the idle link moved
+~38 MB/s single-stream, but under the 8-downloader sweep every stream on the
+machine crawled at ~1-1.5 MB/s. So the cap is on the AGGREGATE, not per
+stream: still downloads pump their chunks through take(), and ffmpeg video
+streams — whose sockets live in a subprocess we can't wrap — are metered from
+outside via /proc/<pid>/io and paused (SIGSTOP) into budget using charge()'s
+debt signal; TCP flow control then stalls the sender while ffmpeg sleeps.
+
+Accounting is post-paid (charge the bytes first, then wait out any debt): the
+bytes have already crossed the network by the time we count them, and it means
+a chunk larger than one second of budget can never deadlock the bucket.
+Stdlib-only on purpose — unit-tested in CI, where the agent's ML deps
+don't exist.
+"""
+import threading
+import time
+
+
+class TokenBucket:
+    """Thread-safe token bucket in bytes/second. rate 0 = unlimited.
+
+    `consumed` is the monotonic total of bytes charged (throttled or not) —
+    the worker's rate loop derives the UI's "net MB/s" readout from it.
+    """
+
+    def __init__(self, rate_bytes_per_s: float = 0.0):
+        self._cond = threading.Condition()
+        self._rate = max(0.0, float(rate_bytes_per_s))
+        # Burst = one second of budget: enough that chunked reads stay smooth,
+        # small enough that a burst can't meaningfully lift the average.
+        self._level = self._rate
+        self._stamp = time.monotonic()
+        self.consumed = 0
+
+    @property
+    def rate(self) -> float:
+        return self._rate
+
+    def set_rate(self, rate_bytes_per_s: float) -> None:
+        """Retune live (the UI dial). Waiters re-check immediately, so raising
+        the cap (or lifting it with 0) unblocks a mid-download wait at once."""
+        with self._cond:
+            self._refill_locked()          # settle elapsed time at the OLD rate
+            self._rate = max(0.0, float(rate_bytes_per_s))
+            self._level = min(self._level, self._rate)
+            self._cond.notify_all()
+
+    def _refill_locked(self) -> None:
+        now = time.monotonic()
+        self._level = min(self._rate, self._level + (now - self._stamp) * self._rate)
+        self._stamp = now
+
+    def take(self, n: int) -> None:
+        """Charge n bytes and block until the budget recovers (stills path)."""
+        with self._cond:
+            self.consumed += n
+            if self._rate <= 0:
+                return
+            self._refill_locked()
+            self._level -= n
+            while self._level < 0:
+                # Wake early on set_rate; cap the wait so a big debt is paid in
+                # re-checked slices rather than one long uninterruptible sleep.
+                self._cond.wait(min(-self._level / self._rate, 0.5))
+                if self._rate <= 0:
+                    return
+                self._refill_locked()
+
+    def charge(self, n: int) -> float:
+        """Charge n bytes WITHOUT blocking; return seconds of debt (0 = within
+        budget). The ffmpeg governor can't block the subprocess's own reads, so
+        it SIGSTOPs the process for (about) the returned debt instead."""
+        with self._cond:
+            self.consumed += n
+            if self._rate <= 0:
+                return 0.0
+            self._refill_locked()
+            self._level -= n
+            return max(0.0, -self._level / self._rate)
+
+
+class PidReadMeter:
+    """Cumulative read-bytes meter for a subprocess, via /proc/<pid>/io.
+
+    `rchar` counts every read() syscall's bytes — for a streaming ffmpeg the
+    network reads dominate, so the delta is a good-enough aggregate-bandwidth
+    signal (it's a governor, not a billing meter). Returns None when /proc is
+    unavailable (process exited, or a non-Linux host): the caller then simply
+    doesn't govern — degrade to unthrottled rather than break video sampling.
+    """
+
+    def __init__(self, pid: int):
+        self._path = f"/proc/{pid}/io"
+        self._last = 0
+
+    def delta(self) -> int | None:
+        try:
+            with open(self._path, "rb") as f:
+                for line in f:
+                    if line.startswith(b"rchar:"):
+                        total = int(line.split()[1])
+                        d, self._last = total - self._last, total
+                        return max(0, d)
+        except (OSError, ValueError):
+            return None
+        return None

agent/requirements.txt

@@ -7,6 +7,9 @@ onnxruntime-gpu
 # Dockerfile from the CUDA-12.4 wheel index so the GPU build is deterministic;
 # transformers loads whatever SigLIP-family model the server announces.
 transformers>=4.45
+# Crop PROPOSERS — small YOLO detectors (booru_yolo anatomy, COCO person, comic
+# panel) that decide where to crop. Uses the torch already installed above.
+ultralytics>=8.3
 # Control surface + HTTP.
 fastapi
 uvicorn[standard]

agent/ruff.toml

@@ -0,0 +1,7 @@
+# The agent runs on the CUDA base image's Python 3.12 (Ubuntu 24.04) — NOT the
+# 3.14 that CI's ci-python image and the repo-root ruff.toml target. Pin the
+# agent to py312 so ruff enforces 3.12 compatibility and never auto-applies a
+# 3.14-only fix (e.g. unquoting a self-referential annotation, which PEP 649
+# makes safe on 3.14 but NameErrors on 3.12). Inherit the root lint rules.
+extend = "../ruff.toml"
+target-version = "py312"

alembic/versions/0001_initial_unified_schema.py

@@ -1,277 +0,0 @@
-"""initial unified schema
-
-Revision ID: 0001
-Revises:
-Create Date: 2026-05-13
-
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-from pgvector.sqlalchemy import Vector
-
-revision: str = "0001"
-down_revision: Union[str, None] = None
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.execute("CREATE EXTENSION IF NOT EXISTS vector")
-
-    op.create_table(
-        "artist",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("name", sa.String(length=255), nullable=False),
-        sa.Column("slug", sa.String(length=255), nullable=False),
-        sa.Column("notes", sa.Text(), nullable=True),
-        sa.Column("is_subscription", sa.Boolean(), nullable=False, server_default=sa.false()),
-        sa.Column("auto_check", sa.Boolean(), nullable=False, server_default=sa.true()),
-        sa.Column("check_interval_seconds", sa.Integer(), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.PrimaryKeyConstraint("id", name="pk_artist"),
-        sa.UniqueConstraint("name", name="uq_artist_name"),
-        sa.UniqueConstraint("slug", name="uq_artist_slug"),
-    )
-
-    op.create_table(
-        "source",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("artist_id", sa.Integer(), nullable=False),
-        sa.Column("platform", sa.String(length=64), nullable=False),
-        sa.Column("url", sa.Text(), nullable=False),
-        sa.Column("enabled", sa.Boolean(), nullable=False, server_default=sa.true()),
-        sa.Column("config_overrides", sa.JSON(), nullable=True),
-        sa.Column("last_checked_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("last_error", sa.Text(), nullable=True),
-        sa.Column("check_interval_override", sa.Integer(), nullable=True),
-        sa.ForeignKeyConstraint(
-            ["artist_id"], ["artist.id"], name="fk_source_artist_id_artist", ondelete="CASCADE"
-        ),
-        sa.PrimaryKeyConstraint("id", name="pk_source"),
-    )
-    op.create_index("ix_source_artist_id", "source", ["artist_id"])
-
-    op.create_table(
-        "credential",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("platform", sa.String(length=64), nullable=False),
-        sa.Column("kind", sa.String(length=32), nullable=False),
-        sa.Column("encrypted_blob", sa.LargeBinary(), nullable=False),
-        sa.Column("status", sa.String(length=32), nullable=False, server_default="active"),
-        sa.Column(
-            "captured_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=True),
-        sa.PrimaryKeyConstraint("id", name="pk_credential"),
-        sa.UniqueConstraint("platform", name="uq_credential_platform"),
-    )
-
-    op.create_table(
-        "post",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("source_id", sa.Integer(), nullable=False),
-        sa.Column("external_post_id", sa.String(length=128), nullable=False),
-        sa.Column("post_url", sa.Text(), nullable=True),
-        sa.Column("post_title", sa.Text(), nullable=True),
-        sa.Column("post_date", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("raw_metadata", sa.JSON(), nullable=True),
-        sa.Column(
-            "downloaded_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.ForeignKeyConstraint(
-            ["source_id"], ["source.id"], name="fk_post_source_id_source", ondelete="CASCADE"
-        ),
-        sa.PrimaryKeyConstraint("id", name="pk_post"),
-        sa.UniqueConstraint("source_id", "external_post_id", name="uq_post_source_external_id"),
-    )
-    op.create_index("ix_post_source_id", "post", ["source_id"])
-
-    op.create_table(
-        "image_record",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("path", sa.Text(), nullable=False),
-        sa.Column("sha256", sa.String(length=64), nullable=False),
-        sa.Column("phash", sa.String(length=32), nullable=True),
-        sa.Column("size_bytes", sa.BigInteger(), nullable=False),
-        sa.Column("mime", sa.String(length=64), nullable=False),
-        sa.Column("width", sa.Integer(), nullable=True),
-        sa.Column("height", sa.Integer(), nullable=True),
-        sa.Column("thumbnail_path", sa.Text(), nullable=True),
-        sa.Column(
-            "origin",
-            sa.Enum(
-                "downloaded",
-                "imported_filesystem",
-                "uploaded",
-                name="origin_enum",
-            ),
-            nullable=False,
-        ),
-        sa.Column("primary_post_id", sa.Integer(), nullable=True),
-        sa.Column("wd14_predictions", sa.JSON(), nullable=True),
-        sa.Column("wd14_model_version", sa.String(length=128), nullable=True),
-        sa.Column("siglip_embedding", Vector(1152), nullable=True),
-        sa.Column("siglip_model_version", sa.String(length=128), nullable=True),
-        sa.Column("centroid_scores", sa.JSON(), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.ForeignKeyConstraint(
-            ["primary_post_id"],
-            ["post.id"],
-            name="fk_image_record_primary_post_id_post",
-            ondelete="SET NULL",
-        ),
-        sa.PrimaryKeyConstraint("id", name="pk_image_record"),
-        sa.UniqueConstraint("path", name="uq_image_record_path"),
-        sa.UniqueConstraint("sha256", name="uq_image_record_sha256"),
-    )
-    op.create_index("ix_image_record_sha256", "image_record", ["sha256"])
-    op.create_index("ix_image_record_phash", "image_record", ["phash"])
-    op.create_index("ix_image_record_primary_post_id", "image_record", ["primary_post_id"])
-
-    op.create_table(
-        "image_provenance",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("image_record_id", sa.Integer(), nullable=False),
-        sa.Column("post_id", sa.Integer(), nullable=False),
-        sa.Column("source_id", sa.Integer(), nullable=False),
-        sa.Column("captured_metadata", sa.JSON(), nullable=True),
-        sa.Column(
-            "captured_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.ForeignKeyConstraint(
-            ["image_record_id"],
-            ["image_record.id"],
-            name="fk_image_provenance_image_record_id_image_record",
-            ondelete="CASCADE",
-        ),
-        sa.ForeignKeyConstraint(
-            ["post_id"],
-            ["post.id"],
-            name="fk_image_provenance_post_id_post",
-            ondelete="CASCADE",
-        ),
-        sa.ForeignKeyConstraint(
-            ["source_id"],
-            ["source.id"],
-            name="fk_image_provenance_source_id_source",
-            ondelete="CASCADE",
-        ),
-        sa.PrimaryKeyConstraint("id", name="pk_image_provenance"),
-    )
-    op.create_index("ix_image_provenance_image_record_id", "image_provenance", ["image_record_id"])
-    op.create_index("ix_image_provenance_post_id", "image_provenance", ["post_id"])
-    op.create_index("ix_image_provenance_source_id", "image_provenance", ["source_id"])
-
-    op.create_table(
-        "tag",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("name", sa.String(length=255), nullable=False),
-        sa.Column("namespace", sa.String(length=64), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.PrimaryKeyConstraint("id", name="pk_tag"),
-        sa.UniqueConstraint("name", name="uq_tag_name"),
-    )
-    op.create_index("ix_tag_name", "tag", ["name"])
-    op.create_index("ix_tag_namespace", "tag", ["namespace"])
-
-    op.create_table(
-        "image_tag",
-        sa.Column("image_record_id", sa.Integer(), nullable=False),
-        sa.Column("tag_id", sa.Integer(), nullable=False),
-        sa.Column("source", sa.String(length=32), nullable=False, server_default="manual"),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.ForeignKeyConstraint(
-            ["image_record_id"],
-            ["image_record.id"],
-            name="fk_image_tag_image_record_id_image_record",
-            ondelete="CASCADE",
-        ),
-        sa.ForeignKeyConstraint(
-            ["tag_id"], ["tag.id"], name="fk_image_tag_tag_id_tag", ondelete="CASCADE"
-        ),
-        sa.PrimaryKeyConstraint("image_record_id", "tag_id", name="pk_image_tag"),
-    )
-
-    op.create_table(
-        "download_event",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("source_id", sa.Integer(), nullable=False),
-        sa.Column("post_id", sa.Integer(), nullable=True),
-        sa.Column("status", sa.String(length=32), nullable=False),
-        sa.Column(
-            "started_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("bytes_downloaded", sa.BigInteger(), nullable=False, server_default="0"),
-        sa.Column("files_count", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("error", sa.Text(), nullable=True),
-        sa.ForeignKeyConstraint(
-            ["source_id"],
-            ["source.id"],
-            name="fk_download_event_source_id_source",
-            ondelete="CASCADE",
-        ),
-        sa.ForeignKeyConstraint(
-            ["post_id"],
-            ["post.id"],
-            name="fk_download_event_post_id_post",
-            ondelete="SET NULL",
-        ),
-        sa.PrimaryKeyConstraint("id", name="pk_download_event"),
-    )
-    op.create_index("ix_download_event_source_id", "download_event", ["source_id"])
-    op.create_index("ix_download_event_post_id", "download_event", ["post_id"])
-
-
-def downgrade() -> None:
-    op.drop_table("download_event")
-    op.drop_table("image_tag")
-    op.drop_table("tag")
-    op.drop_table("image_provenance")
-    op.drop_table("image_record")
-    op.execute("DROP TYPE IF EXISTS origin_enum")
-    op.drop_table("post")
-    op.drop_table("credential")
-    op.drop_table("source")
-    op.drop_table("artist")
-    op.execute("DROP EXTENSION IF EXISTS vector")

alembic/versions/0002_fc2a_tag_kinds_and_import_tasks.py

@@ -1,208 +0,0 @@
-"""fc2a: tag kinds, import_task, import_batch, integrity_status
-
-Revision ID: 0002
-Revises: 0001
-Create Date: 2026-05-14
-
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0002"
-down_revision: Union[str, None] = "0001"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-TAG_KINDS = (
-    "artist",
-    "character",
-    "fandom",
-    "general",
-    "series",
-    "archive",
-    "post",
-    "meta",
-    "rating",
-)
-
-
-def upgrade() -> None:
-    # --- Tag kind enum + fandom_id ---
-    tag_kind = sa.Enum(*TAG_KINDS, name="tag_kind")
-    tag_kind.create(op.get_bind(), checkfirst=True)
-
-    op.add_column(
-        "tag",
-        sa.Column("kind", tag_kind, nullable=False, server_default="general"),
-    )
-    op.add_column(
-        "tag",
-        sa.Column("fandom_id", sa.Integer(), nullable=True),
-    )
-    op.create_foreign_key(
-        "fk_tag_fandom_id_tag",
-        "tag",
-        "tag",
-        ["fandom_id"],
-        ["id"],
-        ondelete="SET NULL",
-    )
-
-    # Drop the old global uniqueness on name; add kind+fandom-aware uniqueness.
-    op.drop_constraint("uq_tag_name", "tag", type_="unique")
-    op.drop_index("ix_tag_name", table_name="tag")
-    op.execute(
-        """
-        CREATE UNIQUE INDEX uq_tag_name_kind_fandom
-          ON tag (name, kind, COALESCE(fandom_id, 0))
-        """
-    )
-
-    # CHECK: fandom_id is only allowed for character kind.
-    op.create_check_constraint(
-        "ck_tag_fandom_requires_character",
-        "tag",
-        "(fandom_id IS NULL) OR (kind = 'character')",
-    )
-
-    # Drop the old namespace column — superseded by kind.
-    op.drop_index("ix_tag_namespace", table_name="tag")
-    op.drop_column("tag", "namespace")
-
-    # --- ImportBatch ---
-    op.create_table(
-        "import_batch",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("triggered_by", sa.String(length=32), nullable=False),
-        sa.Column("source_path", sa.Text(), nullable=False),
-        sa.Column("scan_mode", sa.String(length=16), nullable=False),
-        sa.Column(
-            "started_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("total_files", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("imported", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("skipped", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("failed", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("status", sa.String(length=16), nullable=False, server_default="running"),
-        sa.PrimaryKeyConstraint("id", name="pk_import_batch"),
-    )
-    op.create_index("ix_import_batch_status", "import_batch", ["status"])
-
-    # --- ImportTask ---
-    op.create_table(
-        "import_task",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("batch_id", sa.Integer(), nullable=False),
-        sa.Column("source_path", sa.Text(), nullable=False),
-        sa.Column("task_type", sa.String(length=16), nullable=False),
-        sa.Column("status", sa.String(length=16), nullable=False, server_default="pending"),
-        sa.Column("result_image_id", sa.Integer(), nullable=True),
-        sa.Column("error", sa.Text(), nullable=True),
-        sa.Column("size_bytes", sa.BigInteger(), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column("started_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
-        sa.ForeignKeyConstraint(
-            ["batch_id"],
-            ["import_batch.id"],
-            name="fk_import_task_batch_id_import_batch",
-            ondelete="CASCADE",
-        ),
-        sa.ForeignKeyConstraint(
-            ["result_image_id"],
-            ["image_record.id"],
-            name="fk_import_task_result_image_id_image_record",
-            ondelete="SET NULL",
-        ),
-        sa.PrimaryKeyConstraint("id", name="pk_import_task"),
-    )
-    op.create_index("ix_import_task_batch_id", "import_task", ["batch_id"])
-    op.create_index("ix_import_task_status", "import_task", ["status"])
-    op.create_index(
-        "ix_import_task_created_at_desc",
-        "import_task",
-        [sa.text("created_at DESC")],
-    )
-
-    # --- ImportSettings (single-row table) ---
-    op.create_table(
-        "import_settings",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("import_scan_path", sa.Text(), nullable=False, server_default="/import"),
-        sa.Column("min_width", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("min_height", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column(
-            "skip_transparent", sa.Boolean(), nullable=False, server_default=sa.false()
-        ),
-        sa.Column(
-            "transparency_threshold",
-            sa.Float(),
-            nullable=False,
-            server_default="0.9",
-        ),
-        sa.Column(
-            "skip_single_color", sa.Boolean(), nullable=False, server_default=sa.false()
-        ),
-        sa.Column(
-            "single_color_threshold",
-            sa.Float(),
-            nullable=False,
-            server_default="0.95",
-        ),
-        sa.Column("single_color_tolerance", sa.Integer(), nullable=False, server_default="30"),
-        sa.PrimaryKeyConstraint("id", name="pk_import_settings"),
-        sa.CheckConstraint("id = 1", name="ck_import_settings_singleton"),
-    )
-    # Seed the single row immediately so callers can always SELECT id=1.
-    op.execute("INSERT INTO import_settings (id) VALUES (1)")
-
-    # --- ImageRecord additions ---
-    op.add_column(
-        "image_record",
-        sa.Column(
-            "integrity_status",
-            sa.String(length=24),
-            nullable=False,
-            server_default="unknown",
-        ),
-    )
-    op.create_index(
-        "ix_image_record_integrity_status",
-        "image_record",
-        ["integrity_status"],
-    )
-
-
-def downgrade() -> None:
-    op.drop_index("ix_image_record_integrity_status", table_name="image_record")
-    op.drop_column("image_record", "integrity_status")
-
-    op.drop_table("import_settings")
-    op.drop_index("ix_import_task_created_at_desc", table_name="import_task")
-    op.drop_index("ix_import_task_status", table_name="import_task")
-    op.drop_index("ix_import_task_batch_id", table_name="import_task")
-    op.drop_table("import_task")
-    op.drop_index("ix_import_batch_status", table_name="import_batch")
-    op.drop_table("import_batch")
-
-    op.drop_constraint("ck_tag_fandom_requires_character", "tag", type_="check")
-    op.execute("DROP INDEX uq_tag_name_kind_fandom")
-    op.add_column("tag", sa.Column("namespace", sa.String(length=64), nullable=True))
-    op.create_index("ix_tag_namespace", "tag", ["namespace"])
-    op.create_index("ix_tag_name", "tag", ["name"], unique=False)
-    op.create_unique_constraint("uq_tag_name", "tag", ["name"])
-    op.drop_constraint("fk_tag_fandom_id_tag", "tag", type_="foreignkey")
-    op.drop_column("tag", "fandom_id")
-    op.drop_column("tag", "kind")
-    sa.Enum(name="tag_kind").drop(op.get_bind(), checkfirst=True)

alembic/versions/0003_fc2b_ml_pipeline.py

@@ -1,172 +0,0 @@
-"""fc2b: ML pipeline — allowlist, aliases, centroids, ml_settings
-
-Revision ID: 0003
-Revises: 0002
-Create Date: 2026-05-15
-
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-from pgvector.sqlalchemy import Vector
-
-revision: str = "0003"
-down_revision: Union[str, None] = "0002"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    # 3.1 rename wd14_* -> tagger_*
-    op.alter_column("image_record", "wd14_predictions", new_column_name="tagger_predictions")
-    op.alter_column(
-        "image_record", "wd14_model_version", new_column_name="tagger_model_version"
-    )
-
-    # 3.2 tag_allowlist
-    op.create_table(
-        "tag_allowlist",
-        sa.Column("tag_id", sa.Integer(), nullable=False),
-        sa.Column(
-            "min_confidence", sa.Float(), nullable=False, server_default="0.95"
-        ),
-        sa.Column(
-            "added_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.ForeignKeyConstraint(
-            ["tag_id"], ["tag.id"], name="fk_tag_allowlist_tag_id_tag",
-            ondelete="CASCADE",
-        ),
-        sa.PrimaryKeyConstraint("tag_id", name="pk_tag_allowlist"),
-        sa.CheckConstraint(
-            "min_confidence > 0 AND min_confidence <= 1",
-            name="ck_tag_allowlist_confidence_range",
-        ),
-    )
-
-    # 3.3 tag_suggestion_rejection
-    op.create_table(
-        "tag_suggestion_rejection",
-        sa.Column("image_record_id", sa.Integer(), nullable=False),
-        sa.Column("tag_id", sa.Integer(), nullable=False),
-        sa.Column(
-            "rejected_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.ForeignKeyConstraint(
-            ["image_record_id"], ["image_record.id"],
-            name="fk_tsr_image_record_id_image_record", ondelete="CASCADE",
-        ),
-        sa.ForeignKeyConstraint(
-            ["tag_id"], ["tag.id"], name="fk_tsr_tag_id_tag", ondelete="CASCADE",
-        ),
-        sa.PrimaryKeyConstraint(
-            "image_record_id", "tag_id", name="pk_tag_suggestion_rejection"
-        ),
-    )
-    op.create_index(
-        "ix_tag_suggestion_rejection_tag", "tag_suggestion_rejection", ["tag_id"]
-    )
-
-    # 3.4 tag_alias
-    op.create_table(
-        "tag_alias",
-        sa.Column("alias_string", sa.String(length=255), nullable=False),
-        sa.Column("alias_category", sa.String(length=32), nullable=False),
-        sa.Column("canonical_tag_id", sa.Integer(), nullable=False),
-        sa.Column(
-            "created_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.ForeignKeyConstraint(
-            ["canonical_tag_id"], ["tag.id"],
-            name="fk_tag_alias_canonical_tag_id_tag", ondelete="CASCADE",
-        ),
-        sa.PrimaryKeyConstraint(
-            "alias_string", "alias_category", name="pk_tag_alias"
-        ),
-    )
-    op.create_index("ix_tag_alias_canonical", "tag_alias", ["canonical_tag_id"])
-
-    # 3.5 tag_reference_embedding (centroids)
-    op.create_table(
-        "tag_reference_embedding",
-        sa.Column("tag_id", sa.Integer(), nullable=False),
-        sa.Column("embedding", Vector(1152), nullable=False),
-        sa.Column("reference_count", sa.Integer(), nullable=False),
-        sa.Column("model_version", sa.String(length=128), nullable=False),
-        sa.Column(
-            "updated_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.ForeignKeyConstraint(
-            ["tag_id"], ["tag.id"],
-            name="fk_tag_reference_embedding_tag_id_tag", ondelete="CASCADE",
-        ),
-        sa.PrimaryKeyConstraint("tag_id", name="pk_tag_reference_embedding"),
-    )
-
-    # 3.6 ml_settings singleton
-    op.create_table(
-        "ml_settings",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column(
-            "suggestion_threshold_artist", sa.Float(), nullable=False,
-            server_default="0.30",
-        ),
-        sa.Column(
-            "suggestion_threshold_character", sa.Float(), nullable=False,
-            server_default="0.50",
-        ),
-        sa.Column(
-            "suggestion_threshold_copyright", sa.Float(), nullable=False,
-            server_default="0.50",
-        ),
-        sa.Column(
-            "suggestion_threshold_general", sa.Float(), nullable=False,
-            server_default="0.95",
-        ),
-        sa.Column(
-            "centroid_similarity_threshold", sa.Float(), nullable=False,
-            server_default="0.55",
-        ),
-        sa.Column(
-            "min_reference_images", sa.Integer(), nullable=False,
-            server_default="5",
-        ),
-        sa.Column(
-            "tagger_model_version", sa.String(length=128), nullable=False,
-            server_default="camie-tagger-v2",
-        ),
-        sa.Column(
-            "embedder_model_version", sa.String(length=128), nullable=False,
-            server_default="siglip-so400m-patch14-384",
-        ),
-        sa.Column(
-            "updated_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.PrimaryKeyConstraint("id", name="pk_ml_settings"),
-        sa.CheckConstraint("id = 1", name="ck_ml_settings_singleton"),
-    )
-    op.execute("INSERT INTO ml_settings (id) VALUES (1)")
-
-
-def downgrade() -> None:
-    op.drop_table("ml_settings")
-    op.drop_table("tag_reference_embedding")
-    op.drop_index("ix_tag_alias_canonical", table_name="tag_alias")
-    op.drop_table("tag_alias")
-    op.drop_index(
-        "ix_tag_suggestion_rejection_tag", table_name="tag_suggestion_rejection"
-    )
-    op.drop_table("tag_suggestion_rejection")
-    op.drop_table("tag_allowlist")
-    op.alter_column(
-        "image_record", "tagger_model_version", new_column_name="wd14_model_version"
-    )
-    op.alter_column(
-        "image_record", "tagger_predictions", new_column_name="wd14_predictions"
-    )

alembic/versions/0004_fc2c_i_tsm_system_rows.py

@@ -1,23 +0,0 @@
-"""fc2c-i: enable tsm_system_rows for scalable random sampling
-
-Revision ID: 0004
-Revises: 0003
-Create Date: 2026-05-15
-
-"""
-from typing import Sequence, Union
-
-from alembic import op
-
-revision: str = "0004"
-down_revision: Union[str, None] = "0003"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.execute("CREATE EXTENSION IF NOT EXISTS tsm_system_rows")
-
-
-def downgrade() -> None:
-    op.execute("DROP EXTENSION IF EXISTS tsm_system_rows")

alembic/versions/0005_fc2c_iii_a_series_page.py

@@ -1,50 +0,0 @@
-"""fc2c-iii-a: series_page ordered membership
-
-Revision ID: 0005
-Revises: 0004
-Create Date: 2026-05-16
-
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0005"
-down_revision: Union[str, None] = "0004"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "series_page",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("series_tag_id", sa.Integer(), nullable=False),
-        sa.Column("image_id", sa.Integer(), nullable=False),
-        sa.Column("page_number", sa.Integer(), nullable=False),
-        sa.Column(
-            "created_at", sa.DateTime(timezone=True),
-            nullable=False, server_default=sa.func.now(),
-        ),
-        sa.Column(
-            "updated_at", sa.DateTime(timezone=True),
-            nullable=False, server_default=sa.func.now(),
-        ),
-        sa.ForeignKeyConstraint(
-            ["series_tag_id"], ["tag.id"], ondelete="CASCADE"
-        ),
-        sa.ForeignKeyConstraint(
-            ["image_id"], ["image_record.id"], ondelete="CASCADE"
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("image_id", name="uq_series_page_image"),
-    )
-    op.create_index(
-        "ix_series_page_series_tag_id", "series_page", ["series_tag_id"]
-    )
-
-
-def downgrade() -> None:
-    op.drop_index("ix_series_page_series_tag_id", table_name="series_page")
-    op.drop_table("series_page")

alembic/versions/0006_fc2d_phash_threshold.py

@@ -1,30 +0,0 @@
-"""fc2d: import_settings.phash_threshold
-
-Revision ID: 0006
-Revises: 0005
-Create Date: 2026-05-17
-
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0006"
-down_revision: Union[str, None] = "0005"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "import_settings",
-        sa.Column(
-            "phash_threshold", sa.Integer(),
-            nullable=False, server_default="10",
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("import_settings", "phash_threshold")

alembic/versions/0007_fc2d_post_metadata_fields.py

@@ -1,31 +0,0 @@
-"""fc2d-iv: post.description + post.attachment_count
-
-Revision ID: 0007
-Revises: 0006
-Create Date: 2026-05-18
-
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0007"
-down_revision: Union[str, None] = "0006"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "post", sa.Column("description", sa.Text(), nullable=True)
-    )
-    op.add_column(
-        "post",
-        sa.Column("attachment_count", sa.Integer(), nullable=True),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("post", "attachment_count")
-    op.drop_column("post", "description")

alembic/versions/0008_fc2d_vii_c_artist_deconfliction.py

@@ -1,52 +0,0 @@
-"""fc2d-vii-c: image_record.artist_id + backfill + drop artist tags
-
-Revision ID: 0008
-Revises: 0007
-Create Date: 2026-05-18
-
-Internal forward-correctness migration (the big legacy-import migration
-stays deferred). downgrade() does NOT recreate deleted artist tags;
-downgrade is dev-only and the data is reconstructable by re-import.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-from backend.app.utils.artist_backfill import (
-    BACKFILL_PRIMARY_SQL,
-    BACKFILL_PROVENANCE_SQL,
-    BACKFILL_TAG_SQL,
-    DELETE_ARTIST_TAGS_SQL,
-)
-
-revision: str = "0008"
-down_revision: Union[str, None] = "0007"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "image_record",
-        sa.Column("artist_id", sa.Integer(), nullable=True),
-    )
-    op.create_foreign_key(
-        "fk_image_record_artist_id", "image_record", "artist",
-        ["artist_id"], ["id"], ondelete="SET NULL",
-    )
-    op.create_index(
-        "ix_image_record_artist_id", "image_record", ["artist_id"],
-    )
-    op.execute(BACKFILL_PRIMARY_SQL)
-    op.execute(BACKFILL_PROVENANCE_SQL)
-    op.execute(BACKFILL_TAG_SQL)
-    op.execute(DELETE_ARTIST_TAGS_SQL)
-
-
-def downgrade() -> None:
-    op.drop_index("ix_image_record_artist_id", table_name="image_record")
-    op.drop_constraint(
-        "fk_image_record_artist_id", "image_record", type_="foreignkey"
-    )
-    op.drop_column("image_record", "artist_id")

alembic/versions/0009_fc2d_iii_post_attachment.py

@@ -1,68 +0,0 @@
-"""fc2d-iii: post_attachment + import_batch.attachments
-
-Revision ID: 0009
-Revises: 0008
-Create Date: 2026-05-19
-
-Internal forward-correctness migration (big legacy-import migration
-stays deferred). No backfill — no attachments exist yet.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0009"
-down_revision: Union[str, None] = "0008"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "post_attachment",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column(
-            "post_id", sa.Integer(),
-            sa.ForeignKey("post.id", ondelete="SET NULL"), nullable=True,
-        ),
-        sa.Column(
-            "artist_id", sa.Integer(),
-            sa.ForeignKey("artist.id", ondelete="SET NULL"), nullable=True,
-        ),
-        sa.Column("sha256", sa.String(64), nullable=False),
-        sa.Column("path", sa.Text(), nullable=False),
-        sa.Column("original_filename", sa.Text(), nullable=False),
-        sa.Column("ext", sa.String(32), nullable=False),
-        sa.Column("mime", sa.String(128), nullable=True),
-        sa.Column("size_bytes", sa.BigInteger(), nullable=False),
-        sa.Column(
-            "captured_at", sa.DateTime(timezone=True),
-            server_default=sa.func.now(), nullable=False,
-        ),
-    )
-    op.create_index(
-        "ix_post_attachment_sha256", "post_attachment", ["sha256"],
-        unique=True,
-    )
-    op.create_index(
-        "ix_post_attachment_post_id", "post_attachment", ["post_id"],
-    )
-    op.create_index(
-        "ix_post_attachment_artist_id", "post_attachment", ["artist_id"],
-    )
-    op.add_column(
-        "import_batch",
-        sa.Column(
-            "attachments", sa.Integer(), nullable=False,
-            server_default="0",
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("import_batch", "attachments")
-    op.drop_index("ix_post_attachment_artist_id", table_name="post_attachment")
-    op.drop_index("ix_post_attachment_post_id", table_name="post_attachment")
-    op.drop_index("ix_post_attachment_sha256", table_name="post_attachment")
-    op.drop_table("post_attachment")

alembic/versions/0010_fc3a_source_unique_artist_platform_url.py

@@ -1,32 +0,0 @@
-"""fc3a: unique(source.artist_id, source.platform, source.url)
-
-Revision ID: 0010
-Revises: 0009
-Create Date: 2026-05-20
-
-Enforces FC-3a's dedup invariant at the DB level. No backfill — no
-existing rows are expected to collide; if they do the migration will
-fail loudly (intended).
-"""
-from typing import Sequence, Union
-
-from alembic import op
-
-revision: str = "0010"
-down_revision: Union[str, None] = "0009"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_unique_constraint(
-        "uq_source_artist_platform_url",
-        "source",
-        ["artist_id", "platform", "url"],
-    )
-
-
-def downgrade() -> None:
-    op.drop_constraint(
-        "uq_source_artist_platform_url", "source", type_="unique"
-    )

alembic/versions/0011_fc3b_credential_schema_alignment.py

@@ -1,41 +0,0 @@
-"""fc3b: rename credential.kind -> credential_type, drop status, add last_verified
-
-Revision ID: 0011
-Revises: 0010
-Create Date: 2026-05-20
-
-Aligns the credential table with the GallerySubscriber wire-field names
-so the existing browser extension can POST to FC unmodified. Greenfield —
-no rows exist in production yet, so no data preservation logic is
-needed; the rename uses ALTER COLUMN rather than copy-then-drop.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0011"
-down_revision: Union[str, None] = "0010"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.alter_column("credential", "kind", new_column_name="credential_type")
-    op.drop_column("credential", "status")
-    op.add_column(
-        "credential",
-        sa.Column("last_verified", sa.DateTime(timezone=True), nullable=True),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("credential", "last_verified")
-    op.add_column(
-        "credential",
-        sa.Column(
-            "status", sa.String(length=32), nullable=False,
-            server_default="active",
-        ),
-    )
-    op.alter_column("credential", "credential_type", new_column_name="kind")

alembic/versions/0012_fc3b_app_setting.py

@@ -1,36 +0,0 @@
-"""fc3b: app_setting key/value table
-
-Revision ID: 0012
-Revises: 0011
-Create Date: 2026-05-20
-
-A simple key/value table for small app settings that don't fit
-ImportSettings. Initially seeds only `extension_api_key` (done in
-create_app on first boot — not in the migration, to keep it
-deterministic and independent of randomness).
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0012"
-down_revision: Union[str, None] = "0011"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "app_setting",
-        sa.Column("key", sa.String(length=64), primary_key=True),
-        sa.Column("value", sa.Text(), nullable=False),
-        sa.Column(
-            "updated_at", sa.DateTime(timezone=True),
-            nullable=False, server_default=sa.func.now(),
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_table("app_setting")

alembic/versions/0013_fc3c_download_event_metadata.py

@@ -1,52 +0,0 @@
-"""fc3c: download_event.metadata + import_settings downloader fields
-
-Revision ID: 0013
-Revises: 0012
-Create Date: 2026-05-20
-
-Additive only. download_event.metadata is the rich JSONB blob FC-3c
-populates per run (run_stats, stdout/stderr, quarantined paths, import
-summary). import_settings gains two operator-tunable downloader knobs:
-download_rate_limit_seconds (gallery-dl extractor.sleep) and
-download_validate_files (toggle the magic-byte validator).
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-from sqlalchemy.dialects import postgresql
-
-revision: str = "0013"
-down_revision: Union[str, None] = "0012"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "download_event",
-        sa.Column(
-            "metadata", postgresql.JSONB,
-            nullable=False, server_default=sa.text("'{}'::jsonb"),
-        ),
-    )
-    op.add_column(
-        "import_settings",
-        sa.Column(
-            "download_rate_limit_seconds", sa.Float(),
-            nullable=False, server_default="3.0",
-        ),
-    )
-    op.add_column(
-        "import_settings",
-        sa.Column(
-            "download_validate_files", sa.Boolean(),
-            nullable=False, server_default=sa.true(),
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("import_settings", "download_validate_files")
-    op.drop_column("import_settings", "download_rate_limit_seconds")
-    op.drop_column("download_event", "metadata")

alembic/versions/0014_fc3d_scheduling.py

@@ -1,58 +0,0 @@
-"""fc3d: scheduling + source health columns
-
-Revision ID: 0014
-Revises: 0013
-Create Date: 2026-05-21
-
-Additive only. source.consecutive_failures (default 0, DownloadService
-finalize hook owns the writes). import_settings gains the three
-scheduling knobs (global default interval, event retention, failure
-warning threshold).
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0014"
-down_revision: Union[str, None] = "0013"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "source",
-        sa.Column(
-            "consecutive_failures", sa.Integer(),
-            nullable=False, server_default="0",
-        ),
-    )
-    op.add_column(
-        "import_settings",
-        sa.Column(
-            "download_schedule_default_seconds", sa.Integer(),
-            nullable=False, server_default="28800",
-        ),
-    )
-    op.add_column(
-        "import_settings",
-        sa.Column(
-            "download_event_retention_days", sa.Integer(),
-            nullable=False, server_default="90",
-        ),
-    )
-    op.add_column(
-        "import_settings",
-        sa.Column(
-            "download_failure_warning_threshold", sa.Integer(),
-            nullable=False, server_default="5",
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("import_settings", "download_failure_warning_threshold")
-    op.drop_column("import_settings", "download_event_retention_days")
-    op.drop_column("import_settings", "download_schedule_default_seconds")
-    op.drop_column("source", "consecutive_failures")

alembic/versions/0015_fc5_migration_run.py

@@ -1,51 +0,0 @@
-"""fc5: migration_run table
-
-Revision ID: 0015
-Revises: 0014
-Create Date: 2026-05-22
-
-Additive only. New table tracks each invocation of the FC-5 migration
-tooling (backup, gs, ir, ml_queue, verify, rollback). kind/status are
-plain String(32) — values validated at the API layer per the spec, not
-a Postgres ENUM (so adding kinds later doesn't need a schema migration).
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-from sqlalchemy.dialects import postgresql
-
-revision: str = "0015"
-down_revision: Union[str, None] = "0014"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "migration_run",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column("kind", sa.String(32), nullable=False, index=True),
-        sa.Column("status", sa.String(32), nullable=False, index=True),
-        sa.Column(
-            "dry_run", sa.Boolean(), nullable=False, server_default=sa.false(),
-        ),
-        sa.Column(
-            "started_at", sa.DateTime(timezone=True),
-            nullable=False, server_default=sa.func.now(),
-        ),
-        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column(
-            "counts", postgresql.JSONB,
-            nullable=False, server_default=sa.text("'{}'::jsonb"),
-        ),
-        sa.Column("error", sa.Text(), nullable=True),
-        sa.Column(
-            "metadata", postgresql.JSONB,
-            nullable=False, server_default=sa.text("'{}'::jsonb"),
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_table("migration_run")

alembic/versions/0016_fc3i_task_run.py

@@ -1,86 +0,0 @@
-"""fc3i: task_run table
-
-Revision ID: 0016
-Revises: 0015
-Create Date: 2026-05-24
-
-Additive only. New table records every Celery task attempt via signal
-handlers (backend.app.celery_signals). Status is plain String(16) not
-Postgres ENUM (per feedback_check_existing_enums: ENUM columns hard-
-fail at INSERT, String columns extend cleanly).
-
-Composite indexes anticipate the three dashboard panes:
-- (queue, started_at desc)   — per-lane recent activity
-- (status, started_at desc)  — recent failures pane
-- (task_name, started_at desc) — drill-down by task
-
-Indexed columns get individual indexes via `index=True` on the model;
-the composites below cover the multi-column lookups.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0016"
-down_revision: Union[str, None] = "0015"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "task_run",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column("celery_task_id", sa.String(length=64), nullable=False),
-        sa.Column("queue", sa.String(length=32), nullable=False),
-        sa.Column("task_name", sa.String(length=128), nullable=False),
-        sa.Column("target_id", sa.Integer(), nullable=True),
-        sa.Column("started_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("duration_ms", sa.Integer(), nullable=True),
-        sa.Column(
-            "status", sa.String(length=16), nullable=False,
-            server_default="running",
-        ),
-        sa.Column("error_type", sa.String(length=128), nullable=True),
-        sa.Column("error_message", sa.Text(), nullable=True),
-        sa.Column("retry_count", sa.Integer(), nullable=True),
-        sa.Column("worker_hostname", sa.String(length=128), nullable=True),
-        sa.Column("args_summary", sa.String(length=255), nullable=True),
-    )
-
-    # Single-column indexes (matches Mapped[...].index=True on model).
-    op.create_index("ix_task_run_celery_task_id", "task_run", ["celery_task_id"])
-    op.create_index("ix_task_run_queue", "task_run", ["queue"])
-    op.create_index("ix_task_run_task_name", "task_run", ["task_name"])
-    op.create_index("ix_task_run_started_at", "task_run", ["started_at"])
-    op.create_index("ix_task_run_finished_at", "task_run", ["finished_at"])
-    op.create_index("ix_task_run_status", "task_run", ["status"])
-
-    # Composite indexes for dashboard query patterns.
-    op.create_index(
-        "ix_task_run_queue_started",
-        "task_run", ["queue", sa.text("started_at DESC")],
-    )
-    op.create_index(
-        "ix_task_run_status_started",
-        "task_run", ["status", sa.text("started_at DESC")],
-    )
-    op.create_index(
-        "ix_task_run_name_started",
-        "task_run", ["task_name", sa.text("started_at DESC")],
-    )
-
-
-def downgrade() -> None:
-    op.drop_index("ix_task_run_name_started", table_name="task_run")
-    op.drop_index("ix_task_run_status_started", table_name="task_run")
-    op.drop_index("ix_task_run_queue_started", table_name="task_run")
-    op.drop_index("ix_task_run_status", table_name="task_run")
-    op.drop_index("ix_task_run_finished_at", table_name="task_run")
-    op.drop_index("ix_task_run_started_at", table_name="task_run")
-    op.drop_index("ix_task_run_task_name", table_name="task_run")
-    op.drop_index("ix_task_run_queue", table_name="task_run")
-    op.drop_index("ix_task_run_celery_task_id", table_name="task_run")
-    op.drop_table("task_run")

alembic/versions/0017_fc3h_backup_run.py

@@ -1,82 +0,0 @@
-"""fc3h: backup_run table
-
-Revision ID: 0017
-Revises: 0016
-Create Date: 2026-05-24
-
-Additive. New table records every backup/restore attempt with artifact
-metadata. Lifecycle tracking lives in task_run from FC-3i; this is
-artifact-only (paths, sizes, tag, restore lineage).
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0017"
-down_revision: Union[str, None] = "0016"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "backup_run",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column("kind", sa.String(length=16), nullable=False),
-        sa.Column(
-            "status", sa.String(length=16), nullable=False,
-            server_default="pending",
-        ),
-        sa.Column("tag", sa.String(length=64), nullable=True),
-        sa.Column("triggered_by", sa.String(length=32), nullable=False),
-        sa.Column("started_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("sql_path", sa.Text(), nullable=True),
-        sa.Column("tar_path", sa.Text(), nullable=True),
-        sa.Column("size_bytes", sa.BigInteger(), nullable=True),
-        sa.Column("error", sa.Text(), nullable=True),
-        sa.Column(
-            "manifest", sa.JSON(), nullable=False, server_default="{}",
-        ),
-        sa.Column(
-            "restored_from_id", sa.Integer(),
-            sa.ForeignKey("backup_run.id", ondelete="SET NULL"),
-            nullable=True,
-        ),
-    )
-
-    # Single-column indexes (matches Mapped[...].index=True).
-    op.create_index("ix_backup_run_kind", "backup_run", ["kind"])
-    op.create_index("ix_backup_run_status", "backup_run", ["status"])
-    op.create_index("ix_backup_run_tag", "backup_run", ["tag"])
-    op.create_index("ix_backup_run_started_at", "backup_run", ["started_at"])
-    op.create_index("ix_backup_run_finished_at", "backup_run", ["finished_at"])
-
-    # Composite indexes for dashboard query patterns.
-    op.create_index(
-        "ix_backup_run_kind_started",
-        "backup_run", ["kind", sa.text("started_at DESC")],
-    )
-    op.create_index(
-        "ix_backup_run_status_finished",
-        "backup_run", ["status", sa.text("finished_at DESC")],
-    )
-    # Partial index: only tagged rows participate in retention-exempt query.
-    op.create_index(
-        "ix_backup_run_tag_partial",
-        "backup_run", ["tag"],
-        postgresql_where=sa.text("tag IS NOT NULL"),
-    )
-
-
-def downgrade() -> None:
-    op.drop_index("ix_backup_run_tag_partial", table_name="backup_run")
-    op.drop_index("ix_backup_run_status_finished", table_name="backup_run")
-    op.drop_index("ix_backup_run_kind_started", table_name="backup_run")
-    op.drop_index("ix_backup_run_finished_at", table_name="backup_run")
-    op.drop_index("ix_backup_run_started_at", table_name="backup_run")
-    op.drop_index("ix_backup_run_tag", table_name="backup_run")
-    op.drop_index("ix_backup_run_status", table_name="backup_run")
-    op.drop_index("ix_backup_run_kind", table_name="backup_run")
-    op.drop_table("backup_run")

alembic/versions/0018_fc3h_backup_settings.py

@@ -1,62 +0,0 @@
-"""fc3h: backup_* knobs on import_settings
-
-Revision ID: 0018
-Revises: 0017
-Create Date: 2026-05-24
-
-Adds four columns to the singleton import_settings row:
-  - backup_db_nightly_enabled (default False — opt-in)
-  - backup_db_nightly_hour_utc (default 3)
-  - backup_db_keep_last_n (default 14)
-  - backup_images_keep_last_n (default 3)
-
-server_default ensures the singleton row is backfilled in place
-without an UPDATE statement.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0018"
-down_revision: Union[str, None] = "0017"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "import_settings",
-        sa.Column(
-            "backup_db_nightly_enabled", sa.Boolean(),
-            nullable=False, server_default=sa.false(),
-        ),
-    )
-    op.add_column(
-        "import_settings",
-        sa.Column(
-            "backup_db_nightly_hour_utc", sa.Integer(),
-            nullable=False, server_default="3",
-        ),
-    )
-    op.add_column(
-        "import_settings",
-        sa.Column(
-            "backup_db_keep_last_n", sa.Integer(),
-            nullable=False, server_default="14",
-        ),
-    )
-    op.add_column(
-        "import_settings",
-        sa.Column(
-            "backup_images_keep_last_n", sa.Integer(),
-            nullable=False, server_default="3",
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("import_settings", "backup_images_keep_last_n")
-    op.drop_column("import_settings", "backup_db_keep_last_n")
-    op.drop_column("import_settings", "backup_db_nightly_hour_utc")
-    op.drop_column("import_settings", "backup_db_nightly_enabled")

alembic/versions/0019_import_batch_refreshed.py

@@ -1,38 +0,0 @@
-"""import_batch.refreshed counter for deep-scan sidecar re-application
-
-Revision ID: 0019
-Revises: 0018
-Create Date: 2026-05-25
-
-Adds a `refreshed` counter to `import_batch`, mirroring the existing
-`imported`/`skipped`/`failed`/`attachments` columns. Deep scan now
-re-applies sidecar metadata to already-imported files (the IR feature
-that didn't make the FC port the first time); a "refreshed" outcome
-increments this counter so the UI can surface "X new, Y refreshed"
-instead of the misleading "Scan complete — no new files" message.
-
-server_default=0 backfills existing rows in place — no UPDATE needed.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0019"
-down_revision: Union[str, None] = "0018"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "import_batch",
-        sa.Column(
-            "refreshed", sa.Integer(),
-            nullable=False, server_default=sa.text("0"),
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("import_batch", "refreshed")

alembic/versions/0020_library_audit_run.py

@@ -1,65 +0,0 @@
-"""fc-cleanup: library_audit_run table for async transparency/single_color audits
-
-Revision ID: 0020
-Revises: 0019
-Create Date: 2026-05-26
-
-The table backs the async audit lifecycle: rule + params snapshot, status
-state machine ('running' → 'ready' → 'applied'/'cancelled'/'error'), and
-the matched_ids JSONB array that the apply step deletes. Capped at 50k IDs
-per row by the scan task (oversize = rule too aggressive, operator narrows
-before re-running).
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-from sqlalchemy.dialects import postgresql
-
-revision: str = "0020"
-down_revision: Union[str, None] = "0019"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "library_audit_run",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column("rule", sa.String(32), nullable=False),
-        sa.Column("params", postgresql.JSONB(astext_type=sa.Text()), nullable=False),
-        sa.Column(
-            "status", sa.String(16),
-            nullable=False, server_default="running",
-        ),
-        sa.Column(
-            "started_at", sa.DateTime(timezone=True),
-            nullable=False, server_default=sa.func.now(),
-        ),
-        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column(
-            "scanned_count", sa.Integer(),
-            nullable=False, server_default="0",
-        ),
-        sa.Column(
-            "matched_count", sa.Integer(),
-            nullable=False, server_default="0",
-        ),
-        sa.Column(
-            "matched_ids", postgresql.JSONB(astext_type=sa.Text()),
-            nullable=False, server_default=sa.text("'[]'::jsonb"),
-        ),
-        sa.Column("error", sa.Text(), nullable=True),
-    )
-    op.create_index(
-        "ix_library_audit_run_rule", "library_audit_run", ["rule"],
-    )
-    op.create_index(
-        "ix_library_audit_run_status", "library_audit_run", ["status"],
-    )
-
-
-def downgrade() -> None:
-    op.drop_index("ix_library_audit_run_status", table_name="library_audit_run")
-    op.drop_index("ix_library_audit_run_rule", table_name="library_audit_run")
-    op.drop_table("library_audit_run")

alembic/versions/0021_image_provenance_unique.py

@@ -1,54 +0,0 @@
-"""provenance-race: dedupe + UNIQUE(image_record_id, post_id) on image_provenance
-
-Revision ID: 0021
-Revises: 0020
-Create Date: 2026-05-26
-
-Closes the race in Importer._apply_sidecar's existence-check + INSERT pattern.
-Two workers writing for the same (image, post) pair both saw no existing row
-and both inserted, leaving duplicates that then broke .scalar_one_or_none()
-on every subsequent deep-scan rederive against those images
-(MultipleResultsFound). Most plausibly seeded when the 5-min recovery sweep
-re-enqueued a still-running long-import task and the second worker collided
-with the first inside _apply_sidecar.
-
-Migration steps:
-  1. DELETE all but min(id) per (image_record_id, post_id) pair. Operator's
-     DB had 2 affected pairs at write-time; harmless no-op if zero.
-  2. Add UNIQUE constraint so the importer's new savepoint+IntegrityError
-     recovery path can trip on collision and re-select, mirroring
-     uq_source_artist_platform_url and uq_post_source_external_id.
-"""
-from typing import Sequence, Union
-
-from alembic import op
-
-revision: str = "0021"
-down_revision: Union[str, None] = "0020"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.execute(
-        """
-        DELETE FROM image_provenance ip1
-        USING image_provenance ip2
-        WHERE ip1.image_record_id = ip2.image_record_id
-          AND ip1.post_id = ip2.post_id
-          AND ip1.id > ip2.id
-        """
-    )
-    op.create_unique_constraint(
-        "uq_image_provenance_image_post",
-        "image_provenance",
-        ["image_record_id", "post_id"],
-    )
-
-
-def downgrade() -> None:
-    op.drop_constraint(
-        "uq_image_provenance_image_post",
-        "image_provenance",
-        type_="unique",
-    )

alembic/versions/0022_source_per_artist_platform.py

@@ -1,223 +0,0 @@
-"""source-collapse: one Source per (artist, platform) — consolidate junk per-post Sources
-
-Revision ID: 0022
-Revises: 0021
-Create Date: 2026-05-26
-
-Closes the operator-flagged 2026-05-26 issue where the filesystem importer
-called _find_or_create_source(url=sd.post_url), creating one Source row per
-imported post URL. Operator's Atole artist had 406 Source rows where there
-should have been 1 (the /cw/Atole subscription Source).
-
-Source represents a subscription feed (one per artist+platform — the
-gallery-dl URL polled by the FC-3 downloader). Posts hang off it. The
-filesystem importer was misusing Source as a per-post key.
-
-Migration steps per (artist_id, platform) group with >1 Source:
-  1. Pick canonical — prefer a URL NOT matching '/posts/<id>$' (real
-     campaign URL like /cw/Atole); else min(id).
-  2. PRE-merge any Posts under non-canonical sources whose
-     external_post_id ALREADY exists under the canonical source. (Same
-     gallery-dl post imported via two different sidecar paths can plant
-     two Post rows with identical external_post_id under different
-     Sources for the same artist.) Repoint ImageProvenance +
-     ImageRecord.primary_post_id to the canonical-side Post, dedupe
-     ImageProvenance against alembic 0021's uq, then delete the
-     non-canonical-side Post. This MUST happen before step 3 — Postgres
-     fires uq_post_source_external_id row-by-row during the bulk UPDATE
-     and the merge-after-reparent ordering 500s on first collision
-     (operator-hit during v26.05.26.1 deploy, 2026-05-26).
-  3. Reparent remaining Posts onto canonical (no collisions possible now).
-  4. Reparent ImageProvenance.source_id off the non-canonical sources.
-  5. Delete the orphan Source rows.
-  6. If the canonical Source's URL still looks like a per-post URL (no
-     campaign URL existed among candidates), rewrite it to
-     'sidecar:<platform>:<artist_slug>' so the artist detail page shows
-     something readable.
-"""
-from typing import Sequence, Union
-
-from alembic import op
-from sqlalchemy import text
-
-revision: str = "0022"
-down_revision: Union[str, None] = "0021"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-_POST_URL_RE = r"/posts/[^/]+$"
-
-
-def upgrade() -> None:
-    conn = op.get_bind()
-
-    # Find (artist_id, platform) groups with > 1 Source row.
-    groups = conn.execute(text("""
-        SELECT artist_id, platform
-        FROM source
-        GROUP BY artist_id, platform
-        HAVING COUNT(*) > 1
-    """)).fetchall()
-
-    for artist_id, platform in groups:
-        rows = conn.execute(
-            text("""
-                SELECT id, url FROM source
-                WHERE artist_id = :a AND platform = :p
-                ORDER BY id ASC
-            """),
-            {"a": artist_id, "p": platform},
-        ).fetchall()
-
-        # Canonical: first row whose URL doesn't look like a per-post URL;
-        # else min(id).
-        canonical_id = None
-        for sid, url in rows:
-            if not _matches_post_url(url):
-                canonical_id = sid
-                break
-        if canonical_id is None:
-            canonical_id = rows[0][0]
-
-        other_ids = [sid for sid, _ in rows if sid != canonical_id]
-        if not other_ids:
-            continue
-
-        # STEP 2: PRE-merge ALL Posts with duplicate external_post_id
-        # across the entire (canonical + others) group, BEFORE the bulk
-        # reparent. Two cases must both be handled:
-        #   (A) canonical has Post X with epid=N; an "other" source has
-        #       Post Y with epid=N → after bulk UPDATE, (canonical, N)
-        #       collides with itself.
-        #   (B) two different "other" sources each have a Post with
-        #       epid=N; canonical has none → after bulk UPDATE, both
-        #       are repointed to (canonical, N) and the second collides.
-        # The earlier version of this migration only handled (A); the
-        # operator's deploy 2026-05-26 tripped (B) at line 139.
-        # Fix: group ALL Posts in the (artist, platform) by epid; for
-        # any group with count>1, pick the keep (prefer one already
-        # under canonical; else lowest id) and merge the rest into it.
-        all_posts = conn.execute(
-            text("""
-                SELECT external_post_id, id, source_id
-                FROM post
-                WHERE source_id = :canonical OR source_id = ANY(:others)
-                ORDER BY external_post_id, id
-            """),
-            {"canonical": canonical_id, "others": other_ids},
-        ).fetchall()
-        by_epid: dict = {}
-        for epid, post_id, src_id in all_posts:
-            by_epid.setdefault(epid, []).append((post_id, src_id))
-        for _epid, posts in by_epid.items():
-            if len(posts) <= 1:
-                continue
-            # Prefer a Post already under canonical as the keep.
-            canonical_posts = [p for p in posts if p[1] == canonical_id]
-            if canonical_posts:
-                keep_id = canonical_posts[0][0]
-            else:
-                keep_id = posts[0][0]  # already sorted by id ASC
-            drop_ids = [p[0] for p in posts if p[0] != keep_id]
-            for drop_id in drop_ids:
-                # Pre-delete image_provenance rows under drop_ whose
-                # image_record_id ALREADY has a provenance under keep —
-                # the UPDATE below would otherwise repoint them and
-                # trip uq_image_provenance_image_post (alembic 0021)
-                # row-by-row before any after-the-fact dedupe could
-                # run. Operator's v26.05.26.3 deploy 2026-05-26 tripped
-                # this at line 123.
-                conn.execute(
-                    text("""
-                        DELETE FROM image_provenance
-                        WHERE post_id = :drop_
-                          AND image_record_id IN (
-                              SELECT image_record_id FROM image_provenance
-                              WHERE post_id = :keep
-                          )
-                    """),
-                    {"keep": keep_id, "drop_": drop_id},
-                )
-                # Now safe to repoint the survivors.
-                conn.execute(
-                    text("""
-                        UPDATE image_provenance SET post_id = :keep
-                        WHERE post_id = :drop_
-                    """),
-                    {"keep": keep_id, "drop_": drop_id},
-                )
-                conn.execute(
-                    text("""
-                        UPDATE image_record SET primary_post_id = :keep
-                        WHERE primary_post_id = :drop_
-                    """),
-                    {"keep": keep_id, "drop_": drop_id},
-                )
-                conn.execute(
-                    text("DELETE FROM post WHERE id = :drop_"),
-                    {"drop_": drop_id},
-                )
-
-        # STEP 3: Bulk reparent the remaining Posts off the other
-        # Sources. After step 2, no collisions on
-        # (canonical, external_post_id) are possible.
-        conn.execute(
-            text("""
-                UPDATE post SET source_id = :canonical
-                WHERE source_id = ANY(:others)
-            """),
-            {"canonical": canonical_id, "others": other_ids},
-        )
-
-        # STEP 4: Reparent ImageProvenance.source_id (denormalized FK).
-        # No UNIQUE on source_id; safe bulk update.
-        conn.execute(
-            text("""
-                UPDATE image_provenance SET source_id = :canonical
-                WHERE source_id = ANY(:others)
-            """),
-            {"canonical": canonical_id, "others": other_ids},
-        )
-
-        # STEP 5: Drop the orphan Sources.
-        conn.execute(
-            text("DELETE FROM source WHERE id = ANY(:others)"),
-            {"others": other_ids},
-        )
-
-        # If the canonical's URL still looks per-post (no campaign URL
-        # existed among the candidates), rewrite to a synthetic anchor so
-        # the artist detail page renders something readable.
-        canonical_url = conn.execute(
-            text("SELECT url FROM source WHERE id = :id"),
-            {"id": canonical_id},
-        ).scalar_one()
-        if _matches_post_url(canonical_url):
-            slug = conn.execute(
-                text("SELECT slug FROM artist WHERE id = :id"),
-                {"id": artist_id},
-            ).scalar_one()
-            conn.execute(
-                text("""
-                    UPDATE source
-                    SET url = :new_url, enabled = false
-                    WHERE id = :id
-                """),
-                {
-                    "id": canonical_id,
-                    "new_url": f"sidecar:{platform}:{slug}",
-                },
-            )
-
-
-def downgrade() -> None:
-    # Lossy migration — orphan Sources deleted, Posts reparented, Posts
-    # merged. No safe downgrade. If you need to roll back the schema
-    # invariant, fork from 0021 and re-run filesystem imports.
-    pass
-
-
-def _matches_post_url(url: str) -> bool:
-    """True if url ends with /posts/<token> (gallery-dl-style per-post URL)."""
-    import re
-    return bool(re.search(_POST_URL_RE, url or ""))

alembic/versions/0023_drop_meta_rating_tag_kinds.py

@@ -1,99 +0,0 @@
-"""drop meta + rating tag kinds — operator-retired 2026-05-26
-
-Revision ID: 0023
-Revises: 0022
-Create Date: 2026-05-26
-
-Operator decided meta + rating aren't valid tag kinds for FC. Per-row
-behavior: DELETE existing rows (operator chose "clean break" over
-"convert to general"). All cascading FKs (image_tag, tag_alias,
-tag_allowlist, tag_reference_embedding, tag_suggestion_rejection,
-series_page) use ondelete="CASCADE" so a single DELETE on tag cleans
-the related rows in one go.
-
-After the data cleanup, recreate the tag_kind ENUM without 'meta' /
-'rating' (Postgres has no `ALTER TYPE ... DROP VALUE`; standard
-rename-create-cast-drop dance). The server default 'general' is
-dropped before the type swap and restored after.
-"""
-from typing import Sequence, Union
-
-from alembic import op
-
-revision: str = "0023"
-down_revision: Union[str, None] = "0022"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    # 1. Delete tags of the retired kinds. CASCADE handles related tables.
-    op.execute("DELETE FROM tag WHERE kind IN ('meta', 'rating')")
-
-    # 2. Drop the CHECK constraint that references the enum's literal
-    #    values. Postgres can't resolve `kind = 'character'` across the
-    #    type swap below — the literal would bind to the new tag_kind
-    #    but the column is on tag_kind_old, producing
-    #    "operator does not exist: tag_kind = tag_kind_old".
-    #    (Operator-hit during the v26.05.26.5 deploy attempt; ck was
-    #    originally added by alembic 0002.) Recreated post-swap.
-    op.drop_constraint(
-        "ck_tag_fandom_requires_character", "tag", type_="check"
-    )
-
-    # 3. Drop the server default — ALTER COLUMN TYPE can't carry it
-    #    across the type swap below.
-    op.execute("ALTER TABLE tag ALTER COLUMN kind DROP DEFAULT")
-
-    # 4. Recreate the tag_kind enum without meta/rating.
-    op.execute("ALTER TYPE tag_kind RENAME TO tag_kind_old")
-    op.execute(
-        "CREATE TYPE tag_kind AS ENUM ("
-        "'artist', 'character', 'fandom', 'general', "
-        "'series', 'archive', 'post'"
-        ")"
-    )
-    op.execute(
-        "ALTER TABLE tag "
-        "ALTER COLUMN kind TYPE tag_kind "
-        "USING kind::text::tag_kind"
-    )
-    op.execute("DROP TYPE tag_kind_old")
-
-    # 5. Restore the server default.
-    op.execute("ALTER TABLE tag ALTER COLUMN kind SET DEFAULT 'general'")
-
-    # 6. Restore the CHECK constraint (now bound to the new tag_kind).
-    op.create_check_constraint(
-        "ck_tag_fandom_requires_character",
-        "tag",
-        "(fandom_id IS NULL) OR (kind = 'character')",
-    )
-
-
-def downgrade() -> None:
-    # Add the values back to the enum so old code can boot. The deleted
-    # tag rows are gone permanently — no safe restore.
-    op.drop_constraint(
-        "ck_tag_fandom_requires_character", "tag", type_="check"
-    )
-    op.execute("ALTER TABLE tag ALTER COLUMN kind DROP DEFAULT")
-    op.execute("ALTER TYPE tag_kind RENAME TO tag_kind_old")
-    op.execute(
-        "CREATE TYPE tag_kind AS ENUM ("
-        "'artist', 'character', 'fandom', 'general', "
-        "'series', 'archive', 'post', 'meta', 'rating'"
-        ")"
-    )
-    op.execute(
-        "ALTER TABLE tag "
-        "ALTER COLUMN kind TYPE tag_kind "
-        "USING kind::text::tag_kind"
-    )
-    op.execute("DROP TYPE tag_kind_old")
-    op.execute("ALTER TABLE tag ALTER COLUMN kind SET DEFAULT 'general'")
-    op.create_check_constraint(
-        "ck_tag_fandom_requires_character",
-        "tag",
-        "(fandom_id IS NULL) OR (kind = 'character')",
-    )

alembic/versions/0024_backfill_post_title_from_description.py

@@ -1,80 +0,0 @@
-"""backfill post.post_title from description first-line — 2026-05-27
-
-Revision ID: 0024
-Revises: 0023
-Create Date: 2026-05-27
-
-SubscribeStar gallery-dl always writes `title: ""` and embeds the leading
-sentence inside `content` HTML. FC's sidecar parser was leaving
-post_title NULL for every SubscribeStar post since FC-3 shipped. The
-parser fix (sidecar._first_line_text fallback) now synthesizes a title
-at parse time; this migration applies the same logic retroactively to
-existing rows.
-
-Operator-flagged 2026-05-27 after inspecting
-/mnt/Data/Patreon/Cheunart/subscribestar/ sidecars.
-
-Idempotent: only touches rows where post_title IS NULL or empty AND
-description IS NOT NULL. Re-running the migration is a no-op.
-"""
-from __future__ import annotations
-
-import re
-from typing import Sequence, Union
-
-from alembic import op
-from sqlalchemy import text
-
-revision: str = "0024"
-down_revision: Union[str, None] = "0023"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-_TAG_RE = re.compile(r"<[^>]+>")
-_WS_RE = re.compile(r"\s+")
-
-
-def _first_line_text(body: str, limit: int = 120) -> str | None:
-    """Mirror of sidecar._first_line_text. Kept inline so the migration
-    doesn't carry a runtime import dependency from app code that may
-    have moved by the time the migration is replayed years from now."""
-    if not body:
-        return None
-    text_ = _TAG_RE.sub(" ", body)
-    text_ = text_.replace("\xa0", " ")
-    for line in text_.splitlines():
-        line = _WS_RE.sub(" ", line).strip()
-        if line:
-            if len(line) > limit:
-                return line[: limit - 1].rstrip() + "…"
-            return line
-    return None
-
-
-def upgrade() -> None:
-    bind = op.get_bind()
-    rows = bind.execute(
-        text(
-            "SELECT id, description FROM post "
-            "WHERE (post_title IS NULL OR post_title = '') "
-            "AND description IS NOT NULL AND description <> ''"
-        )
-    ).fetchall()
-    updated = 0
-    for row in rows:
-        derived = _first_line_text(row.description)
-        if not derived:
-            continue
-        bind.execute(
-            text("UPDATE post SET post_title = :t WHERE id = :id"),
-            {"t": derived, "id": row.id},
-        )
-        updated += 1
-    print(f"0024: backfilled post_title on {updated} row(s)")
-
-
-def downgrade() -> None:
-    # No safe restore — we can't tell which post_titles were derived vs
-    # genuinely present. Leave the column alone on rollback.
-    pass

alembic/versions/0025_fix_subscribestar_post_ids.py

@@ -1,288 +0,0 @@
-"""sidecar-audit followup: correct external_post_id + post_url across all platforms
-
-Revision ID: 0025
-Revises: 0024
-Create Date: 2026-05-27
-
-Closes the operator-flagged 2026-05-27 sidecar audit findings. Three
-data-correctness bugs across non-Patreon platforms had been silently
-corrupting Posts since FC-3 shipped; the parser fix (sidecar.py, same
-commit) addresses new imports. This migration cleans up existing rows.
-
-Per-platform actions:
-
-  subscribestar — gallery-dl wrote the per-attachment id in `id` and
-    the actual post id in `post_id`. FC's parser picked `id`, so every
-    multi-image SubscribeStar post was fragmented into N Post rows.
-    1. For each SubscribeStar Post, read its sidecar (via the related
-       ImageRecord's on-disk path), pull `post_id`, overwrite
-       external_post_id and post_url.
-    2. Merge groups of Posts under one source that now share an
-       external_post_id (fragments of the same actual post). Same
-       ImageProvenance pre-delete + repoint dance as alembic 0022.
-
-  hentaifoundry — sidecars have NO `url` field; `src` is the image
-    URL. FC's parser stored post_url=NULL. Read each HF Post's sidecar
-    for `user` + `index`, derive the canonical /pictures/user/<u>/<i>
-    permalink. external_post_id (= `index`) was already correct.
-
-  discord — gallery-dl wrote the CDN attachment URL in `url`. FC's
-    parser stored that as post_url. Read each Discord Post's sidecar
-    for the server/channel/message triple, derive the proper
-    discord.com/channels/.../<message> permalink. external_post_id (=
-    `message_id`) was already correct.
-
-  pixiv — pure-SQL backfill: replace any `i.pximg.net`-style URL on
-    Post.post_url with the derived `/artworks/<id>` permalink. Pixiv
-    external_post_id (= `id`) was already correct; no sidecar IO
-    needed.
-
-Idempotent: re-running on already-corrected data is a no-op (skips
-rows whose derived value matches what's already stored).
-
-Posts whose related ImageRecord paths don't resolve on disk (orphaned
-filesystem state) are skipped with a count in the migration output —
-those will be picked up by a future deep-scan.
-"""
-from __future__ import annotations
-
-import json
-import re
-from pathlib import Path
-from typing import Sequence, Union
-
-from alembic import op
-from sqlalchemy import text
-
-revision: str = "0025"
-down_revision: Union[str, None] = "0024"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-# Mirror of sidecar._NUMBERING_PREFIX. Kept inline so the migration is
-# self-contained (the operator's banked rule:
-# reference_postgres_enum_swap_drop_checks.md says migrations shouldn't
-# import from runtime app code).
-_NUMBERING_PREFIX = re.compile(r"^\d+_(.+)$")
-
-
-def _find_sidecar(media_path: Path) -> Path | None:
-    """gallery-dl writes the sidecar under the unprefixed stem
-    (`HOLLOW-ICHIGO.json`) while the media file gets a NN_ ordering
-    prefix (`01_HOLLOW-ICHIGO.png`). Try in order:
-      1. <stem>.json next to the media
-      2. <media>.json next to the media (full-name variant)
-      3. strip the NN_ prefix from the stem, then <stripped>.json
-    """
-    if not media_path:
-        return None
-    cand = media_path.with_suffix(".json")
-    if cand.is_file():
-        return cand
-    cand = media_path.parent / f"{media_path.name}.json"
-    if cand.is_file():
-        return cand
-    m = _NUMBERING_PREFIX.match(media_path.stem)
-    if m:
-        cand = media_path.parent / f"{m.group(1)}.json"
-        if cand.is_file():
-            return cand
-    return None
-
-
-def _str_id(v) -> str | None:
-    """str() a JSON scalar id; reject bool (JSON booleans are ints in
-    Python's eyes but they aren't valid sidecar ids)."""
-    if isinstance(v, bool):
-        return None
-    if isinstance(v, (str, int)) and str(v).strip():
-        return str(v).strip()
-    return None
-
-
-def _str_field(v) -> str | None:
-    if isinstance(v, str) and v.strip():
-        return v.strip()
-    return None
-
-
-def upgrade() -> None:
-    conn = op.get_bind()
-
-    # ── PART 1: Per-platform corrections requiring filesystem IO ─────
-    # SubscribeStar, HentaiFoundry, Discord all need fields from the
-    # sidecar to construct the right post_url. We walk each Post's
-    # related ImageRecord.path to find the sidecar, read it, derive,
-    # and update.
-    targets = conn.execute(text("""
-        SELECT p.id, p.external_post_id, p.post_url, s.platform
-        FROM post p
-        JOIN source s ON s.id = p.source_id
-        WHERE s.platform IN ('subscribestar', 'hentaifoundry', 'discord')
-    """)).fetchall()
-
-    stats: dict[str, dict[str, int]] = {
-        plat: {"read": 0, "updated": 0, "no_sidecar": 0}
-        for plat in ("subscribestar", "hentaifoundry", "discord")
-    }
-    for post_row in targets:
-        plat = post_row.platform
-        path = _first_attachment_path(conn, post_row.id)
-        if not path:
-            stats[plat]["no_sidecar"] += 1
-            continue
-        sidecar = _find_sidecar(Path(path))
-        if sidecar is None:
-            stats[plat]["no_sidecar"] += 1
-            continue
-        try:
-            data = json.loads(sidecar.read_text(encoding="utf-8"))
-        except (OSError, json.JSONDecodeError):
-            stats[plat]["no_sidecar"] += 1
-            continue
-        stats[plat]["read"] += 1
-
-        new_epid = post_row.external_post_id
-        new_url = None
-        if plat == "subscribestar":
-            pid = _str_id(data.get("post_id"))
-            if pid:
-                new_epid = pid
-                new_url = f"https://www.subscribestar.com/posts/{pid}"
-        elif plat == "hentaifoundry":
-            user = _str_field(data.get("user")) or _str_field(data.get("artist"))
-            idx = _str_id(data.get("index"))
-            if user and idx:
-                new_url = f"https://www.hentai-foundry.com/pictures/user/{user}/{idx}"
-        elif plat == "discord":
-            sid = _str_id(data.get("server_id"))
-            cid = _str_id(data.get("channel_id"))
-            mid = _str_id(data.get("message_id"))
-            if sid and cid and mid:
-                new_url = f"https://discord.com/channels/{sid}/{cid}/{mid}"
-
-        # Idempotent: skip if nothing changed.
-        if new_epid == post_row.external_post_id and new_url == post_row.post_url:
-            continue
-        conn.execute(
-            text("""
-                UPDATE post
-                SET external_post_id = :epid, post_url = :url
-                WHERE id = :id
-            """),
-            {"epid": new_epid, "url": new_url, "id": post_row.id},
-        )
-        stats[plat]["updated"] += 1
-
-    for plat, s in stats.items():
-        print(
-            f"0025: {plat} — read {s['read']} sidecars, "
-            f"updated {s['updated']} Posts, "
-            f"{s['no_sidecar']} Posts had no resolvable sidecar"
-        )
-
-    # ── PART 2: Merge SubscribeStar fragments now sharing epid ───────
-    # After Part 1, each group of Posts under one source with the SAME
-    # new external_post_id is a fragment-set of the same actual post.
-    # Merge to one canonical row. Pre-handle the same ImageProvenance
-    # collision pattern as alembic 0022 (uq_image_provenance_image_post).
-    fragment_groups = conn.execute(text("""
-        SELECT p.source_id, p.external_post_id,
-               ARRAY_AGG(p.id ORDER BY p.id ASC) AS post_ids
-        FROM post p
-        JOIN source s ON s.id = p.source_id
-        WHERE s.platform = 'subscribestar'
-          AND p.external_post_id IS NOT NULL
-        GROUP BY p.source_id, p.external_post_id
-        HAVING COUNT(*) > 1
-    """)).fetchall()
-
-    merged = 0
-    for grp in fragment_groups:
-        post_ids = list(grp.post_ids)
-        keep_id, *drop_ids = post_ids
-        for drop_id in drop_ids:
-            # Pre-DELETE colliding ImageProvenance under drop_ that
-            # already exist under keep (alembic 0022 banked the pattern).
-            conn.execute(
-                text("""
-                    DELETE FROM image_provenance
-                    WHERE post_id = :drop_
-                      AND image_record_id IN (
-                          SELECT image_record_id FROM image_provenance
-                          WHERE post_id = :keep
-                      )
-                """),
-                {"keep": keep_id, "drop_": drop_id},
-            )
-            conn.execute(
-                text("""
-                    UPDATE image_provenance SET post_id = :keep
-                    WHERE post_id = :drop_
-                """),
-                {"keep": keep_id, "drop_": drop_id},
-            )
-            conn.execute(
-                text("""
-                    UPDATE image_record SET primary_post_id = :keep
-                    WHERE primary_post_id = :drop_
-                """),
-                {"keep": keep_id, "drop_": drop_id},
-            )
-            conn.execute(
-                text("""
-                    UPDATE post_attachment SET post_id = :keep
-                    WHERE post_id = :drop_
-                """),
-                {"keep": keep_id, "drop_": drop_id},
-            )
-            conn.execute(
-                text("DELETE FROM post WHERE id = :drop_"),
-                {"drop_": drop_id},
-            )
-            merged += 1
-    print(f"0025: subscribestar — merged {merged} duplicate Post fragments")
-
-    # ── PART 3: Pixiv post_url backfill (pure SQL) ───────────────────
-    # Pixiv's external_post_id is already correct (gallery-dl's `id` is
-    # the post id). Only post_url needs derivation: replace anything
-    # under i.pximg.net (the file URL) with the /artworks/<id> permalink.
-    pixiv_updated = conn.execute(text("""
-        UPDATE post p
-        SET post_url = 'https://www.pixiv.net/artworks/' || p.external_post_id
-        FROM source s
-        WHERE p.source_id = s.id
-          AND s.platform = 'pixiv'
-          AND p.external_post_id IS NOT NULL
-          AND (p.post_url IS NULL
-               OR p.post_url LIKE 'https://i.pximg.net/%'
-               OR p.post_url LIKE 'http://i.pximg.net/%')
-    """)).rowcount
-    print(f"0025: pixiv — backfilled post_url on {pixiv_updated} Posts")
-
-
-def _first_attachment_path(conn, post_id: int) -> str | None:
-    """Return any ImageRecord.path attached to this post (via
-    ImageProvenance). Lowest-id row keeps the migration deterministic
-    so re-running on the same DB picks the same sidecar."""
-    row = conn.execute(
-        text("""
-            SELECT ir.path
-            FROM image_provenance ip
-            JOIN image_record ir ON ir.id = ip.image_record_id
-            WHERE ip.post_id = :pid
-            ORDER BY ip.id ASC
-            LIMIT 1
-        """),
-        {"pid": post_id},
-    ).first()
-    return row[0] if row else None
-
-
-def downgrade() -> None:
-    # Lossy: external_post_id values were overwritten with the correct
-    # post_id; original per-attachment ids weren't preserved. Post-merge
-    # also deleted drop rows. No safe restore. To roll back the schema
-    # invariant, fork from 0024 and re-run sidecar imports.
-    pass

alembic/versions/0026_import_task_recovery_count_refetched.py

@@ -1,53 +0,0 @@
-"""import_task.recovery_count + refetched — poison-pill circuit breaker
-
-Revision ID: 0026
-Revises: 0025
-Create Date: 2026-05-28
-
-Backs the import-task resilience work (operator-flagged 2026-05-28):
-
-- recovery_count: how many times recover_interrupted_tasks has
-  re-queued this row from a stuck 'processing' state. A row that
-  hard-crashes the worker (OOM / segfault on a corrupt or oversized
-  input) leaves no terminal flip, so the sweep re-queues it — and
-  without a cap it would loop forever, re-crashing the worker each
-  time. After MAX_RECOVERY_ATTEMPTS the sweep marks it 'failed' with a
-  diagnostic instead.
-
-- refetched: whether a one-shot re-download has already been attempted
-  for this task's file. Bounds the Layer-2 re-fetch remediation to a
-  single attempt so source-side corruption doesn't loop.
-
-Both default to 0 / false; additive, no backfill needed.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0026"
-down_revision: Union[str, None] = "0025"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "import_task",
-        sa.Column(
-            "recovery_count", sa.Integer(), nullable=False,
-            server_default="0",
-        ),
-    )
-    op.add_column(
-        "import_task",
-        sa.Column(
-            "refetched", sa.Boolean(), nullable=False,
-            server_default=sa.false(),
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("import_task", "refetched")
-    op.drop_column("import_task", "recovery_count")

alembic/versions/0027_drop_migration_run.py

@@ -1,50 +0,0 @@
-"""drop migration_run — one-and-done GS/IR migration tooling removed
-
-Revision ID: 0027
-Revises: 0026
-Create Date: 2026-05-29
-
-The GS/IR migration tooling (services/migrators, /api/migrate, the
-run_migration task, LegacyMigrationCard, and the MigrationRun model) was
-removed after the migration cutover completed. This drops its now-orphaned
-run-log table. Downgrade recreates the table (mirrors the old model) so the
-migration is reversible.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-from sqlalchemy.dialects.postgresql import JSONB
-
-revision: str = "0027"
-down_revision: Union[str, None] = "0026"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.drop_table("migration_run")
-
-
-def downgrade() -> None:
-    op.create_table(
-        "migration_run",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column("kind", sa.String(length=32), nullable=False),
-        sa.Column("status", sa.String(length=32), nullable=False),
-        sa.Column("dry_run", sa.Boolean(), nullable=False, server_default=sa.false()),
-        sa.Column(
-            "started_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column(
-            "counts", JSONB(), nullable=False, server_default=sa.text("'{}'::jsonb"),
-        ),
-        sa.Column("error", sa.Text(), nullable=True),
-        sa.Column(
-            "metadata", JSONB(), nullable=False, server_default=sa.text("'{}'::jsonb"),
-        ),
-    )
-    op.create_index("ix_migration_run_kind", "migration_run", ["kind"])
-    op.create_index("ix_migration_run_status", "migration_run", ["status"])

alembic/versions/0028_collapse_sidecar_synthetics_into_real_sources.py

@@ -1,190 +0,0 @@
-"""collapse-sidecar-synthetic: repoint Posts/ImageProvenance/DownloadEvents
-from `sidecar:<platform>:<slug>` synthetic Source anchors onto the real
-Source for the same (artist, platform) when one exists, then delete the
-synthetic.
-
-Revision ID: 0028
-Revises: 0027
-Create Date: 2026-05-31
-
-Background: alembic 0022 (2026-05-26) consolidated the old per-post-URL
-Source rows into one canonical Source per (artist, platform). When NO
-real campaign URL was salvageable among the candidates, it rewrote the
-canonical row to url='sidecar:<platform>:<slug>' enabled=false as a
-disabled anchor for any Posts already attached.
-
-That was fine while it was the only Source for that artist+platform.
-But: the unique constraint on Source is (artist_id, platform, url), not
-(artist_id, platform). When the operator later added the real
-subscription via the UI / extension / etc., a SECOND row landed —
-the real one — with id > the synthetic. Both coexisted.
-
-Two follow-on problems surfaced 2026-05-31:
-
-  1. The Subscriptions UI listed both rows. The synthetic was disabled
-     so the scheduler never polled it, but it looked like a phantom
-     subscription. (Fixed in same commit by SourceService.list filter.)
-  2. importer._source_for_sidecar picked Source by `ORDER BY id ASC
-     LIMIT 1`, so EVERY gallery-dl download since the real Source was
-     added attached its Post to the SYNTHETIC anchor, not the real
-     Source. (Fixed in same commit by preferring non-sidecar URLs.)
-
-This migration is the data half of the cleanup: for every (artist,
-platform) with both a synthetic AND a real Source, repoint the
-synthetic's children (Posts, ImageProvenance, DownloadEvents) onto the
-real Source and delete the synthetic. Reuses the same epid/provenance
-collision dance from alembic 0022 because the same uniqueness
-constraints fire row-by-row during bulk UPDATEs.
-
-Lone synthetic anchors — those where no real Source for the same
-(artist, platform) exists (e.g., filesystem-imported artist with no
-subscription added) — are LEFT INTACT. They anchor real imported
-content; deleting them would CASCADE-delete the Posts the operator
-imported. The SourceService.list filter hides them from the UI; the
-operator can delete them by hand if they want the underlying imports
-gone.
-"""
-from typing import Sequence, Union
-
-from alembic import op
-from sqlalchemy import text
-
-revision: str = "0028"
-down_revision: Union[str, None] = "0027"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    conn = op.get_bind()
-
-    # Find (artist_id, platform) groups where BOTH a sidecar synthetic
-    # and at least one real Source exist.
-    groups = conn.execute(text("""
-        SELECT artist_id, platform
-        FROM source
-        GROUP BY artist_id, platform
-        HAVING bool_or(url LIKE 'sidecar:%')
-           AND bool_or(url NOT LIKE 'sidecar:%')
-    """)).fetchall()
-
-    for artist_id, platform in groups:
-        rows = conn.execute(
-            text("""
-                SELECT id, url FROM source
-                WHERE artist_id = :a AND platform = :p
-                ORDER BY id ASC
-            """),
-            {"a": artist_id, "p": platform},
-        ).fetchall()
-
-        synthetic_ids = [sid for sid, url in rows if url.startswith("sidecar:")]
-        real_rows = [(sid, url) for sid, url in rows if not url.startswith("sidecar:")]
-        if not synthetic_ids or not real_rows:
-            continue  # belt+suspenders; the GROUP BY already filtered
-
-        # Canonical real: lowest-id non-sidecar Source.
-        canonical_id = real_rows[0][0]
-
-        # STEP A: PRE-merge Post collisions on (canonical, external_post_id).
-        # Mirror alembic 0022's pre-merge logic — when synth has Post X
-        # epid=N and real has Post Y epid=N, the bulk UPDATE below would
-        # trip uq_post_source_external_id row-by-row. Group all Posts
-        # under (canonical + synthetics) by epid; for any group >1,
-        # pick a keep (prefer one already under canonical, else lowest
-        # id) and merge the rest into it.
-        all_posts = conn.execute(
-            text("""
-                SELECT external_post_id, id, source_id
-                FROM post
-                WHERE source_id = :canonical OR source_id = ANY(:synths)
-                ORDER BY external_post_id, id
-            """),
-            {"canonical": canonical_id, "synths": synthetic_ids},
-        ).fetchall()
-        by_epid: dict = {}
-        for epid, post_id, src_id in all_posts:
-            by_epid.setdefault(epid, []).append((post_id, src_id))
-        for _epid, posts in by_epid.items():
-            if len(posts) <= 1:
-                continue
-            canonical_side = [p for p in posts if p[1] == canonical_id]
-            keep_id = canonical_side[0][0] if canonical_side else posts[0][0]
-            drop_ids = [p[0] for p in posts if p[0] != keep_id]
-            for drop_id in drop_ids:
-                # Pre-delete image_provenance rows under drop_ whose
-                # image_record_id already has provenance under keep —
-                # avoids tripping uq_image_provenance_image_post (0021)
-                # row-by-row during the repoint UPDATE.
-                conn.execute(
-                    text("""
-                        DELETE FROM image_provenance
-                        WHERE post_id = :drop_
-                          AND image_record_id IN (
-                              SELECT image_record_id FROM image_provenance
-                              WHERE post_id = :keep
-                          )
-                    """),
-                    {"keep": keep_id, "drop_": drop_id},
-                )
-                conn.execute(
-                    text("""
-                        UPDATE image_provenance SET post_id = :keep
-                        WHERE post_id = :drop_
-                    """),
-                    {"keep": keep_id, "drop_": drop_id},
-                )
-                conn.execute(
-                    text("""
-                        UPDATE image_record SET primary_post_id = :keep
-                        WHERE primary_post_id = :drop_
-                    """),
-                    {"keep": keep_id, "drop_": drop_id},
-                )
-                conn.execute(
-                    text("DELETE FROM post WHERE id = :drop_"),
-                    {"drop_": drop_id},
-                )
-
-        # STEP B: Bulk reparent the remaining Posts off the synthetics.
-        conn.execute(
-            text("""
-                UPDATE post SET source_id = :canonical
-                WHERE source_id = ANY(:synths)
-            """),
-            {"canonical": canonical_id, "synths": synthetic_ids},
-        )
-
-        # STEP C: Reparent ImageProvenance.source_id (denormalized FK;
-        # no UNIQUE on source_id, safe bulk).
-        conn.execute(
-            text("""
-                UPDATE image_provenance SET source_id = :canonical
-                WHERE source_id = ANY(:synths)
-            """),
-            {"canonical": canonical_id, "synths": synthetic_ids},
-        )
-
-        # STEP D: Reparent any DownloadEvent.source_id. Synthetics are
-        # enabled=false so the scheduler never created events for them;
-        # this is belt+suspenders for any rows planted by manual force
-        # or older code paths.
-        conn.execute(
-            text("""
-                UPDATE download_event SET source_id = :canonical
-                WHERE source_id = ANY(:synths)
-            """),
-            {"canonical": canonical_id, "synths": synthetic_ids},
-        )
-
-        # STEP E: Drop the now-empty synthetics.
-        conn.execute(
-            text("DELETE FROM source WHERE id = ANY(:synths)"),
-            {"synths": synthetic_ids},
-        )
-
-
-def downgrade() -> None:
-    # Lossy migration — synthetic Sources deleted, Posts repointed and
-    # potentially merged. No safe downgrade.
-    pass

alembic/versions/0029_drop_artist_copyright_ml_thresholds.py

@@ -1,71 +0,0 @@
-"""drop artist + copyright ml thresholds; lower general default to 0.50
-
-Revision ID: 0029
-Revises: 0028
-Create Date: 2026-06-01
-
-Operator-flagged 2026-06-01: the view modal's Suggestions panel hides
-most general-category predictions because the default threshold is
-0.95. Lowering the default to 0.50 (matches character) so general
-suggestions surface more aggressively; the value remains tunable in
-Settings → ML.
-
-Same change retires two ML suggestion categories whose Tag.kind
-surfaces are unused:
-
-- `artist`: retired in FC-2d-vii-c — artist identity is acquisition-
-  derived (image_record.artist_id), never ML-inferred. The threshold
-  column was a leftover from before that retirement.
-- `copyright`: retired 2026-06-01 — the app uses `fandom` for the
-  franchise/copyright concept (per TagsView.vue's doc comment); no
-  Tag rows of kind=copyright exist, and the threshold column never
-  fed anything user-visible.
-
-Both columns are dropped from ml_settings; the existing row's
-suggestion_threshold_general value is bumped from 0.95 to 0.50 iff
-it's still at the old default, so deployed installs pick up the new
-UX without overriding any operator tuning.
-"""
-from typing import Sequence, Union
-
-from alembic import op
-from sqlalchemy import text
-
-revision: str = "0029"
-down_revision: Union[str, None] = "0028"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    # Bump the general threshold for installs still at the old default.
-    op.execute(text(
-        "UPDATE ml_settings "
-        "SET suggestion_threshold_general = 0.50 "
-        "WHERE id = 1 AND suggestion_threshold_general = 0.95"
-    ))
-    op.drop_column("ml_settings", "suggestion_threshold_artist")
-    op.drop_column("ml_settings", "suggestion_threshold_copyright")
-
-
-def downgrade() -> None:
-    # Restore the columns with their prior defaults. The bump from
-    # 0.95 → 0.50 isn't reversible without remembering whether the
-    # operator had explicitly set 0.95 (unlikely — that was just the
-    # default) so we leave the current general value as-is.
-    from sqlalchemy import Column, Float
-
-    op.add_column(
-        "ml_settings",
-        Column(
-            "suggestion_threshold_artist",
-            Float, nullable=False, server_default="0.30",
-        ),
-    )
-    op.add_column(
-        "ml_settings",
-        Column(
-            "suggestion_threshold_copyright",
-            Float, nullable=False, server_default="0.50",
-        ),
-    )

alembic/versions/0030_nullable_post_source_id_denorm_artist_id.py

@@ -1,145 +0,0 @@
-"""nullable post.source_id + denormalized post.artist_id; retire sidecar synthetics
-
-Revision ID: 0030
-Revises: 0029
-Create Date: 2026-06-01
-
-Operator-asked 2026-06-01 after the Dymkens orphan investigation: the
-sidecar synthetic Source pattern (`sidecar:<platform>:<slug>` rows
-with enabled=false) was technically correct but misled the operator
-into thinking they had phantom subscriptions. The synthetics existed
-solely to satisfy `Post.source_id NOT NULL` for filesystem-imported
-content with no real subscription.
-
-This migration makes the data model honest:
-
-1. **Post gets a denormalized `artist_id` column** so artist filters
-   work without traversing `Post → Source.artist_id`. Backfilled from
-   the existing Source linkage, then NOT NULL'd.
-2. **`Post.source_id` becomes nullable**, FK ondelete `CASCADE` → `SET
-   NULL`. Deleting a Source detaches its Posts instead of destroying
-   imported content (semantically: subscription ends, archive stays).
-3. **`ImageProvenance.source_id` becomes nullable** with the same FK
-   semantic change.
-4. **Sidecar synthetic Sources are deleted** — first NULL out the
-   FKs from Post + ImageProvenance pointing at them (so the implicit
-   CASCADE doesn't fire), then delete. DownloadEvent FK is unchanged
-   (still CASCADE'd, NOT NULL'd) — synthetics have `enabled=false`
-   so no events exist for them.
-
-Uniqueness handling: the existing `uq_post_source_external_id`
-(source_id, external_post_id) keeps working for source-bound Posts
-(Postgres treats NULL != NULL so NULL-source rows aren't deduped by
-it). A second partial unique index covers the NULL-source case on
-(artist_id, external_post_id) so filesystem-imported posts still
-dedupe within an artist.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-from sqlalchemy import text
-
-revision: str = "0030"
-down_revision: Union[str, None] = "0029"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    conn = op.get_bind()
-
-    # Step 1: add Post.artist_id, initially nullable for backfill.
-    # FK naming follows the Base.metadata naming_convention
-    # (fk_<table>_<column>_<referred_table>) — alembic 0001 set this up.
-    op.add_column(
-        "post",
-        sa.Column("artist_id", sa.Integer, nullable=True),
-    )
-    op.create_foreign_key(
-        "fk_post_artist_id_artist", "post", "artist",
-        ["artist_id"], ["id"], ondelete="CASCADE",
-    )
-
-    # Step 2: backfill from Source.artist_id (every existing Post has a
-    # Source today, so every row gets populated).
-    conn.execute(text("""
-        UPDATE post p
-        SET artist_id = s.artist_id
-        FROM source s
-        WHERE p.source_id = s.id AND p.artist_id IS NULL
-    """))
-
-    # Sanity: count any remaining NULLs. Should be zero pre-this-migration.
-    remaining = conn.execute(text(
-        "SELECT COUNT(*) FROM post WHERE artist_id IS NULL"
-    )).scalar_one()
-    if remaining:
-        raise RuntimeError(
-            f"alembic 0030: {remaining} post rows have no resolvable "
-            f"artist_id after backfill. Investigate before continuing."
-        )
-
-    # Step 3: enforce NOT NULL + add index for artist-filter queries.
-    op.alter_column("post", "artist_id", nullable=False)
-    op.create_index("ix_post_artist_id", "post", ["artist_id"])
-
-    # Step 4: relax post.source_id + flip FK to SET NULL. The original FK
-    # name from alembic 0001 is `fk_post_source_id_source` per the
-    # NAMING_CONVENTION in models/base.py.
-    op.alter_column("post", "source_id", nullable=True)
-    op.drop_constraint("fk_post_source_id_source", "post", type_="foreignkey")
-    op.create_foreign_key(
-        "fk_post_source_id_source", "post", "source",
-        ["source_id"], ["id"], ondelete="SET NULL",
-    )
-
-    # Step 5: relax image_provenance.source_id + flip FK to SET NULL.
-    op.alter_column("image_provenance", "source_id", nullable=True)
-    op.drop_constraint(
-        "fk_image_provenance_source_id_source", "image_provenance",
-        type_="foreignkey",
-    )
-    op.create_foreign_key(
-        "fk_image_provenance_source_id_source", "image_provenance", "source",
-        ["source_id"], ["id"], ondelete="SET NULL",
-    )
-
-    # Step 6: partial unique index on (artist_id, external_post_id) for
-    # NULL-source Posts. The existing uq_post_source_external_id keeps
-    # guarding source-bound rows; NULL-source rows now dedupe within
-    # an artist.
-    op.execute(
-        "CREATE UNIQUE INDEX uq_post_artist_external_id_null_source "
-        "ON post (artist_id, external_post_id) "
-        "WHERE source_id IS NULL"
-    )
-
-    # Step 7: retire sidecar synthetic Sources. NULL out the references
-    # FIRST (the new FK is SET NULL so CASCADE wouldn't fire anyway, but
-    # being explicit makes the intent clear). Then delete the synthetic
-    # source rows. Any DownloadEvent rows under synthetics CASCADE-die
-    # with the source — synthetics have enabled=false so there shouldn't
-    # be any in practice.
-    conn.execute(text("""
-        UPDATE post
-        SET source_id = NULL
-        WHERE source_id IN (SELECT id FROM source WHERE url LIKE 'sidecar:%')
-    """))
-    conn.execute(text("""
-        UPDATE image_provenance
-        SET source_id = NULL
-        WHERE source_id IN (SELECT id FROM source WHERE url LIKE 'sidecar:%')
-    """))
-    deleted = conn.execute(text(
-        "DELETE FROM source WHERE url LIKE 'sidecar:%' RETURNING id"
-    )).rowcount
-    print(f"alembic 0030: deleted {deleted} sidecar synthetic source rows")
-
-
-def downgrade() -> None:
-    # Lossy migration — the deleted sidecar synthetics can't be
-    # restored from the orphan post.source_id / image_provenance.source_id
-    # values, and the partial unique index encodes a constraint that
-    # NULL-source Posts may now exist. No safe downgrade.
-    pass

alembic/versions/0031_source_backfill_runs_remaining.py

@@ -1,45 +0,0 @@
-"""source.backfill_runs_remaining: sticky deep-scan mode
-
-Revision ID: 0031
-Revises: 0030
-Create Date: 2026-06-01
-
-Tick vs backfill mode for subscription downloads. When
-`backfill_runs_remaining > 0`, the next N download runs use
-`skip: True` + 30-min timeout (walk full history). When 0, runs use
-`skip: "exit:20"` + 14.5-min timeout (catch-up mode, exits early once
-20 contiguous archived items are seen).
-
-Operator-flagged 2026-06-01 (Knuxy run #38887): a creator with ~550
-archived posts saturates the 870s catch-up timeout even when there is
-no new content, because gallery-dl's default `skip: True` keeps walking.
-Tick mode short-circuits that; backfill mode is the explicit opt-in for
-deep history scans.
-
-Default 0 (all existing subscriptions start in tick mode).
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0031"
-down_revision: Union[str, None] = "0030"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "source",
-        sa.Column(
-            "backfill_runs_remaining",
-            sa.Integer,
-            nullable=False,
-            server_default="0",
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("source", "backfill_runs_remaining")

alembic/versions/0032_source_error_type.py

@@ -1,41 +0,0 @@
-"""source.error_type: surface ErrorType taxonomy in FailingSourcesCard
-
-Revision ID: 0032
-Revises: 0031
-Create Date: 2026-06-02
-
-Audit 2026-06-02: the backend computes 13 ErrorType categories (auth_error,
-rate_limited, not_found, access_denied, validation_failed, etc.) and
-stamps each one on DownloadEvent.metadata, but the Source row only carried
-the free-text last_error. Operators couldn't bulk-triage failing sources
-("all auth_error → rotate cookies, all rate_limited → just wait") without
-opening Logs per row.
-
-This column receives the last error_type from _update_source_health
-and gets cleared on a successful run. Nullable + indexed so the failing-
-sources rollup can filter/group cheaply.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0032"
-down_revision: Union[str, None] = "0031"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "source",
-        sa.Column("error_type", sa.String(length=32), nullable=True),
-    )
-    op.create_index(
-        "ix_source_error_type", "source", ["error_type"],
-    )
-
-
-def downgrade() -> None:
-    op.drop_index("ix_source_error_type", table_name="source")
-    op.drop_column("source", "error_type")

alembic/versions/0033_suggestion_threshold_default_070.py

@@ -1,48 +0,0 @@
-"""suggestion_threshold default 0.50 → 0.70
-
-Revision ID: 0033
-Revises: 0032
-Create Date: 2026-06-02
-
-Operator-flagged 2026-06-02 — the 0.50 default (set on 2026-06-01) is
-too noisy in practice; raise to 0.70 for both suggestion categories.
-
-Only conditionally updates singletons whose current value is still the
-2026-06-01 default (0.50). Operators who deliberately tuned their row
-to some other value (0.55, 0.65, 0.80, etc. via the Settings UI) keep
-their pick — the migration only catches the unchanged-default case.
-"""
-from typing import Sequence, Union
-
-from alembic import op
-
-revision: str = "0033"
-down_revision: Union[str, None] = "0032"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.execute(
-        "UPDATE ml_settings "
-        "SET suggestion_threshold_character = 0.70 "
-        "WHERE id = 1 AND suggestion_threshold_character = 0.50"
-    )
-    op.execute(
-        "UPDATE ml_settings "
-        "SET suggestion_threshold_general = 0.70 "
-        "WHERE id = 1 AND suggestion_threshold_general = 0.50"
-    )
-
-
-def downgrade() -> None:
-    op.execute(
-        "UPDATE ml_settings "
-        "SET suggestion_threshold_character = 0.50 "
-        "WHERE id = 1 AND suggestion_threshold_character = 0.70"
-    )
-    op.execute(
-        "UPDATE ml_settings "
-        "SET suggestion_threshold_general = 0.50 "
-        "WHERE id = 1 AND suggestion_threshold_general = 0.70"
-    )

alembic/versions/0034_artist_visit.py

@@ -1,53 +0,0 @@
-"""artist_visit: per-artist last-viewed timestamp for the "+N new" badge
-
-Revision ID: 0034
-Revises: 0033
-Create Date: 2026-06-03
-
-Powers the artists-directory "+N new since last visit" badge + ArtistView
-banner. Single row per artist (no user_id yet — rule #47 multi-user ACL
-is aspirational; widens to (user_id, artist_id) PK when User lands).
-
-Seed every existing artist with `last_viewed_at = NOW()` so the badge
-starts at 0 across the board — no noisy "you have 5000 unseen images"
-on first deploy. New artists auto-get a row via
-`ArtistService.find_or_create`.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0034"
-down_revision: Union[str, None] = "0033"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "artist_visit",
-        sa.Column(
-            "artist_id",
-            sa.Integer,
-            sa.ForeignKey("artist.id", ondelete="CASCADE"),
-            primary_key=True,
-        ),
-        sa.Column(
-            "last_viewed_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("NOW()"),
-        ),
-    )
-    # Seed: every existing artist starts "fully caught up". Without this,
-    # every operator with N artists would see N badges (worth of every
-    # image ever imported) on first deploy.
-    op.execute(
-        "INSERT INTO artist_visit (artist_id, last_viewed_at) "
-        "SELECT id, NOW() FROM artist"
-    )
-
-
-def downgrade() -> None:
-    op.drop_table("artist_visit")

alembic/versions/0035_image_record_effective_date.py

@@ -1,70 +0,0 @@
-"""image_record.effective_date: materialized gallery sort key + index
-
-Revision ID: 0035
-Revises: 0034
-Create Date: 2026-06-04
-
-The gallery ordered/cursored on COALESCE(post.post_date,
-image_record.created_at) across the Post outer join. That expression spans
-two tables, so no index can serve it — every /scroll sorted a large slice
-of the library, and the frontend fired ten of them serially per initial
-load. Materialize the value into image_record.effective_date and index
-(effective_date DESC, id DESC) so the cursor scroll is an index range scan.
-
-Backfill = COALESCE(primary post's post_date, created_at) so existing rows
-keep their exact ordering. New rows get the created_at-equivalent server
-default; services/importer.py overrides it with the post's date when a
-primary post with a date is linked.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0035"
-down_revision: Union[str, None] = "0034"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    # Add nullable first so the backfill can populate before NOT NULL.
-    op.add_column(
-        "image_record",
-        sa.Column("effective_date", sa.DateTime(timezone=True), nullable=True),
-    )
-    # Pure set-based UPDATEs (no per-row params) — immune to the 65535
-    # bind-parameter ceiling regardless of library size.
-    op.execute(
-        """
-        UPDATE image_record AS ir
-        SET effective_date = COALESCE(p.post_date, ir.created_at)
-        FROM post AS p
-        WHERE ir.primary_post_id = p.id
-        """
-    )
-    op.execute(
-        """
-        UPDATE image_record
-        SET effective_date = created_at
-        WHERE effective_date IS NULL
-        """
-    )
-    op.alter_column(
-        "image_record",
-        "effective_date",
-        nullable=False,
-        server_default=sa.text("now()"),
-    )
-    # DESC/DESC matches the gallery's ORDER BY effective_date DESC, id DESC
-    # so the scroll is a forward index scan; raw SQL because alembic's
-    # column list doesn't express per-column DESC cleanly.
-    op.execute(
-        "CREATE INDEX ix_image_record_effective_date "
-        "ON image_record (effective_date DESC, id DESC)"
-    )
-
-
-def downgrade() -> None:
-    op.drop_index("ix_image_record_effective_date", table_name="image_record")
-    op.drop_column("image_record", "effective_date")

alembic/versions/0036_siglip_embedding_hnsw_index.py

@@ -1,41 +0,0 @@
-"""image_record.siglip_embedding: HNSW cosine index for "more like this"
-
-Revision ID: 0036
-Revises: 0035
-Create Date: 2026-06-04
-
-Gallery Phase 3 (visual similarity search) ranks images by
-`siglip_embedding.cosine_distance(source_embedding)`. Without an index that's
-a sequential scan computing a 1152-dim distance for every row — fine at small
-scale, but it grows linearly with the library. Add an HNSW index with
-`vector_cosine_ops` so the top-N nearest search is sub-50ms ANN.
-
-1152 dims is under pgvector's 2000-dim HNSW limit, so HNSW (no training,
-better recall than IVFFlat) is the right choice. ONE-TIME COST: building the
-index over the existing embeddings (~57k vectors on the operator's library)
-locks image_record for ~30-60s during this migration on deploy — acceptable
-for a single-operator homelab. NULL embeddings (videos / not-yet-embedded
-rows) are simply not indexed.
-"""
-from typing import Sequence, Union
-
-from alembic import op
-
-revision: str = "0036"
-down_revision: Union[str, None] = "0035"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    # Raw SQL: alembic's create_index doesn't express the `USING hnsw (...
-    # vector_cosine_ops)` access-method + opclass cleanly. Must match the
-    # query's cosine_distance operator class to be usable by the planner.
-    op.execute(
-        "CREATE INDEX ix_image_record_siglip_hnsw "
-        "ON image_record USING hnsw (siglip_embedding vector_cosine_ops)"
-    )
-
-
-def downgrade() -> None:
-    op.drop_index("ix_image_record_siglip_hnsw", table_name="image_record")

alembic/versions/0037_patreon_seen_media.py

@@ -1,53 +0,0 @@
-"""patreon_seen_media: per-source ledger of already-ingested Patreon media
-
-Revision ID: 0037
-Revises: 0036
-Create Date: 2026-06-05
-
-Native Patreon ingester (build step 2a). Replaces gallery-dl's
-archive.sqlite3 with our own queryable table. The downloader upserts one
-row per (source, media) so routine walks skip media we've already
-processed; a future "recovery" mode bypasses the ledger to re-walk.
-
-`filehash` is a 32-hex Patreon CDN MD5, OR a video sentinel of the form
-``video:<post_id>:<media_id>`` — hence String(128). The unique
-constraint on (source_id, filehash) is the dedup upsert key.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0037"
-down_revision: Union[str, None] = "0036"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "patreon_seen_media",
-        sa.Column("id", sa.Integer, primary_key=True),
-        sa.Column(
-            "source_id",
-            sa.Integer,
-            sa.ForeignKey("source.id", ondelete="CASCADE"),
-            nullable=False,
-            index=True,
-        ),
-        sa.Column("filehash", sa.String(128), nullable=False),
-        sa.Column("post_id", sa.String(64), nullable=True),
-        sa.Column(
-            "seen_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("NOW()"),
-        ),
-        sa.UniqueConstraint(
-            "source_id", "filehash", name="uq_patreon_seen_media_source_id"
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_table("patreon_seen_media")

alembic/versions/0038_patreon_failed_media.py

@@ -1,58 +0,0 @@
-"""patreon_failed_media: per-source dead-letter ledger for failing Patreon media
-
-Revision ID: 0038
-Revises: 0037
-Create Date: 2026-06-06
-
-Plan #705 (#7). Media that keeps failing to download/validate (404'd CDN,
-deleted post, geo-blocked Mux, persistently-corrupt bytes) gets recorded here
-with an attempt counter; once it crosses the dead-letter threshold the ingester
-skips it on routine walks (recovery still re-attempts). A clean download clears
-the row. UNIQUE (source_id, filehash) is the upsert key (same media key the
-seen-ledger uses).
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0038"
-down_revision: Union[str, None] = "0037"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "patreon_failed_media",
-        sa.Column("id", sa.Integer, primary_key=True),
-        sa.Column(
-            "source_id",
-            sa.Integer,
-            sa.ForeignKey("source.id", ondelete="CASCADE"),
-            nullable=False,
-            index=True,
-        ),
-        sa.Column("filehash", sa.String(128), nullable=False),
-        sa.Column("attempts", sa.Integer, nullable=False, server_default="1"),
-        sa.Column("last_error", sa.Text, nullable=True),
-        sa.Column(
-            "first_failed_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("NOW()"),
-        ),
-        sa.Column(
-            "last_failed_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("NOW()"),
-        ),
-        sa.UniqueConstraint(
-            "source_id", "filehash", name="uq_patreon_failed_media_source_id"
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_table("patreon_failed_media")

alembic/versions/0039_library_audit_resume.py

@@ -1,40 +0,0 @@
-"""library_audit_run: resume cursor + progress timestamp for chunked scans
-
-Revision ID: 0039
-Revises: 0038
-Create Date: 2026-06-07
-
-scan_library_for_rule used to run one 2h pass that timed out on large libraries
-and monopolized the concurrency-1 maintenance queue (operator-flagged). It now
-runs short time-boxed chunks that re-enqueue: `resume_after_id` persists the
-keyset cursor so the next chunk continues where it left off, and
-`last_progress_at` lets the recovery sweep tell a progressing multi-chunk audit
-from a genuinely stuck one.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0039"
-down_revision: Union[str, None] = "0038"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "library_audit_run",
-        sa.Column(
-            "resume_after_id", sa.Integer, nullable=False, server_default="0"
-        ),
-    )
-    op.add_column(
-        "library_audit_run",
-        sa.Column("last_progress_at", sa.DateTime(timezone=True), nullable=True),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("library_audit_run", "last_progress_at")
-    op.drop_column("library_audit_run", "resume_after_id")

alembic/versions/0040_series_chapters.py

@@ -1,108 +0,0 @@
-"""series chapters: chapter layer over series_page (FC-6.1)
-
-Revision ID: 0040
-Revises: 0039
-Create Date: 2026-06-07
-
-A series (Tag kind='series') gains an ordered chapter layer. Reading order
-becomes (series_chapter.chapter_number, series_page.page_number). Every existing
-series is backfilled into a single auto-chapter (chapter_number=1) holding its
-current flat pages, so no data is lost and the old flat ordering is preserved.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0040"
-down_revision: Union[str, None] = "0039"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "series_chapter",
-        sa.Column("id", sa.Integer, primary_key=True),
-        sa.Column(
-            "series_tag_id",
-            sa.Integer,
-            sa.ForeignKey("tag.id", ondelete="CASCADE"),
-            nullable=False,
-        ),
-        sa.Column("chapter_number", sa.Integer, nullable=False),
-        sa.Column("title", sa.Text, nullable=True),
-        sa.Column(
-            "is_placeholder", sa.Boolean, nullable=False, server_default="false"
-        ),
-        sa.Column("stated_page_start", sa.Integer, nullable=True),
-        sa.Column("stated_page_end", sa.Integer, nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-    )
-    op.create_index(
-        "ix_series_chapter_series_tag_id", "series_chapter", ["series_tag_id"]
-    )
-
-    # New columns on series_page; chapter_id starts nullable so we can backfill.
-    op.add_column(
-        "series_page", sa.Column("chapter_id", sa.Integer, nullable=True)
-    )
-    op.add_column(
-        "series_page", sa.Column("stated_page", sa.Integer, nullable=True)
-    )
-
-    conn = op.get_bind()
-    # One auto-chapter per existing series (any series_tag_id present in pages).
-    conn.execute(
-        sa.text(
-            "INSERT INTO series_chapter "
-            "(series_tag_id, chapter_number, is_placeholder, created_at, updated_at) "
-            "SELECT DISTINCT series_tag_id, 1, false, now(), now() "
-            "FROM series_page"
-        )
-    )
-    # Point every existing page at its series' auto-chapter.
-    conn.execute(
-        sa.text(
-            "UPDATE series_page sp "
-            "SET chapter_id = sc.id "
-            "FROM series_chapter sc "
-            "WHERE sc.series_tag_id = sp.series_tag_id"
-        )
-    )
-
-    # Now lock chapter_id down: NOT NULL + FK (cascade) + index.
-    op.alter_column("series_page", "chapter_id", nullable=False)
-    op.create_foreign_key(
-        "fk_series_page_chapter_id",
-        "series_page",
-        "series_chapter",
-        ["chapter_id"],
-        ["id"],
-        ondelete="CASCADE",
-    )
-    op.create_index(
-        "ix_series_page_chapter_id", "series_page", ["chapter_id"]
-    )
-
-
-def downgrade() -> None:
-    op.drop_index("ix_series_page_chapter_id", table_name="series_page")
-    op.drop_constraint(
-        "fk_series_page_chapter_id", "series_page", type_="foreignkey"
-    )
-    op.drop_column("series_page", "stated_page")
-    op.drop_column("series_page", "chapter_id")
-    op.drop_index("ix_series_chapter_series_tag_id", table_name="series_chapter")
-    op.drop_table("series_chapter")

alembic/versions/0041_series_suggestions.py

@@ -1,98 +0,0 @@
-"""series suggestions: assisted-continuation matcher (FC-6.3)
-
-Revision ID: 0041
-Revises: 0040
-Create Date: 2026-06-07
-
-A confirm-only queue of "this post may continue this series" hints, plus two
-import_settings knobs (enable + score threshold) for the matcher.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0041"
-down_revision: Union[str, None] = "0040"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "series_suggestion",
-        sa.Column("id", sa.Integer, primary_key=True),
-        sa.Column(
-            "post_id",
-            sa.Integer,
-            sa.ForeignKey("post.id", ondelete="CASCADE"),
-            nullable=False,
-        ),
-        sa.Column(
-            "series_tag_id",
-            sa.Integer,
-            sa.ForeignKey("tag.id", ondelete="CASCADE"),
-            nullable=False,
-        ),
-        sa.Column("score", sa.Float, nullable=False),
-        sa.Column("signals", sa.JSON, nullable=True),
-        sa.Column(
-            "status", sa.String(16), nullable=False, server_default="pending"
-        ),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.UniqueConstraint(
-            "post_id", "series_tag_id", name="uq_series_suggestion_post_series"
-        ),
-    )
-    op.create_index(
-        "ix_series_suggestion_post_id", "series_suggestion", ["post_id"]
-    )
-    op.create_index(
-        "ix_series_suggestion_series_tag_id",
-        "series_suggestion",
-        ["series_tag_id"],
-    )
-    op.create_index(
-        "ix_series_suggestion_status", "series_suggestion", ["status"]
-    )
-
-    op.add_column(
-        "import_settings",
-        sa.Column(
-            "series_suggest_enabled",
-            sa.Boolean,
-            nullable=False,
-            server_default=sa.true(),
-        ),
-    )
-    op.add_column(
-        "import_settings",
-        sa.Column(
-            "series_suggest_threshold",
-            sa.Float,
-            nullable=False,
-            server_default="0.5",
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("import_settings", "series_suggest_threshold")
-    op.drop_column("import_settings", "series_suggest_enabled")
-    op.drop_index("ix_series_suggestion_status", table_name="series_suggestion")
-    op.drop_index(
-        "ix_series_suggestion_series_tag_id", table_name="series_suggestion"
-    )
-    op.drop_index("ix_series_suggestion_post_id", table_name="series_suggestion")
-    op.drop_table("series_suggestion")

alembic/versions/0042_series_chapter_stated_part.py

@@ -1,32 +0,0 @@
-"""series chapter stated_part: operator-facing Part N label (FC-6.4)
-
-Revision ID: 0042
-Revises: 0041
-Create Date: 2026-06-07
-
-A chapter's positional chapter_number is auto-managed (rewritten 1..N on
-reorder/delete), so it can't double as the installment number the operator wants
-to type (e.g. a series authored from a post that is Part 2). Add a nullable
-stated_part alongside it — the same split as series_page.page_number (order) vs
-series_page.stated_page (printed number). Nullable; the UI falls back to
-chapter_number when unset.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0042"
-down_revision: Union[str, None] = "0041"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "series_chapter", sa.Column("stated_part", sa.Integer, nullable=True)
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("series_chapter", "stated_part")

alembic/versions/0043_post_attachment_per_post_unique.py

@@ -1,62 +0,0 @@
-"""post_attachment: per-post sha uniqueness (empty-post flood fix)
-
-Revision ID: 0043
-Revises: 0042
-Create Date: 2026-06-08
-
-PostAttachment.sha256 was GLOBALLY unique, so a non-art file the creator attaches
-to many posts (a standard pdf/zip/link-card) only ever got ONE row — on the first
-post — leaving every later post a bare shell (no image, no attachment). The native
-Patreon backfill of Anduo surfaced 1589 such shells (operator-flagged 2026-06-08).
-
-Switch to PER-POST uniqueness: the on-disk blob stays sha-deduped, but each post
-gets its own row. Replace the unique sha256 index with a plain lookup index plus
-two partial uniques — (post_id, sha256) for real posts and (sha256) for the
-NULL-post filesystem case (still one row per file there).
-
-Existing data has ≤1 row per sha (the old global unique), so the new partial
-uniques can't be violated on upgrade — no data backfill needed here. The bare-post
-shells themselves are removed by the separate prune-empty-posts cleanup tool.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0043"
-down_revision: Union[str, None] = "0042"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    # Drop the global unique index; recreate it as a plain (non-unique) lookup
-    # index so sha-based reads keep their index (matches the model's index=True).
-    op.drop_index("ix_post_attachment_sha256", table_name="post_attachment")
-    op.create_index(
-        "ix_post_attachment_sha256", "post_attachment", ["sha256"],
-    )
-    op.create_index(
-        "uq_post_attachment_post_sha", "post_attachment",
-        ["post_id", "sha256"], unique=True,
-        postgresql_where=sa.text("post_id IS NOT NULL"),
-    )
-    op.create_index(
-        "uq_post_attachment_null_post_sha", "post_attachment",
-        ["sha256"], unique=True,
-        postgresql_where=sa.text("post_id IS NULL"),
-    )
-
-
-def downgrade() -> None:
-    op.drop_index(
-        "uq_post_attachment_null_post_sha", table_name="post_attachment"
-    )
-    op.drop_index(
-        "uq_post_attachment_post_sha", table_name="post_attachment"
-    )
-    op.drop_index("ix_post_attachment_sha256", table_name="post_attachment")
-    op.create_index(
-        "ix_post_attachment_sha256", "post_attachment", ["sha256"],
-        unique=True,
-    )

alembic/versions/0044_ml_settings_tagger_store_floor.py

@@ -1,37 +0,0 @@
-"""ml_settings.tagger_store_floor
-
-The ingest confidence floor below which tagger predictions are not stored,
-promoted from the TAGGER_STORE_FLOOR env var to a DB-backed, UI-tunable
-setting. Default 0.70 (was an env default of 0.05): the suggestion path
-already filters at 0.70 and the centroid/learned path covers low-confidence
-preferred tags, so the sub-0.70 tail was redundant weight — it had grown
-image_record's TOAST to ~100 GB. See plan-task #764.
-
-Revision ID: 0044
-Revises: 0043
-Create Date: 2026-06-10
-
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0044"
-down_revision: Union[str, None] = "0043"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "ml_settings",
-        sa.Column(
-            "tagger_store_floor", sa.Float(),
-            nullable=False, server_default="0.7",
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("ml_settings", "tagger_store_floor")

alembic/versions/0045_image_prediction_table.py

@@ -1,69 +0,0 @@
-"""image_prediction table (DDL only — backfill runs as a background task)
-
-Normalizes the per-image tagger predictions out of the JSON blob into a
-queryable table (#768). This migration creates ONLY the table + indexes — it
-is pure DDL and commits instantly, so web boots immediately.
-
-The data backfill from the existing image_record.tagger_predictions JSON is
-deliberately NOT done here. Doing it inline made the whole migration one
-transaction over the ~100 GB TOAST: nothing committed until the very end, it
-was invisible/unmonitorable mid-run, and an early MATERIALIZED-CTE form spilled
-the full 100 GB to temp. Instead the backfill is the
-backend.app.tasks.admin.backfill_image_predictions_task — batched by id window,
-committed per chunk (visible progress + resumable), idempotent
-(ON CONFLICT DO NOTHING). Trigger it from Settings → Maintenance once web is up.
-
-The old image_record.tagger_predictions column is left in place (vestigial) and
-dropped in a follow-up once the backfill + code cutover are verified — dropping
-it needs an ACCESS EXCLUSIVE lock on the hot image_record table (the 0044 lock
-class), so it's deferred to a quiesced-worker window.
-
-Revision ID: 0045
-Revises: 0044
-Create Date: 2026-06-10
-
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0045"
-down_revision: Union[str, None] = "0044"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "image_prediction",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column(
-            "image_record_id", sa.Integer(),
-            sa.ForeignKey("image_record.id", ondelete="CASCADE"),
-            nullable=False,
-        ),
-        sa.Column("raw_name", sa.String(length=255), nullable=False),
-        sa.Column("category", sa.String(length=64), nullable=False),
-        sa.Column("score", sa.Float(), nullable=False),
-        sa.UniqueConstraint(
-            "image_record_id", "raw_name", name="image_raw_name",
-        ),
-    )
-    op.create_index(
-        "ix_image_prediction_image", "image_prediction", ["image_record_id"],
-    )
-    op.create_index(
-        "ix_image_prediction_name_score", "image_prediction",
-        ["raw_name", "score"],
-    )
-    # No data backfill here — see the module docstring. The one-time copy from
-    # image_record.tagger_predictions runs as backfill_image_predictions_task
-    # (batched, resumable, idempotent), kept out of this transaction so web boots
-    # without waiting on a ~100 GB pass.
-
-
-def downgrade() -> None:
-    op.drop_index("ix_image_prediction_name_score", "image_prediction")
-    op.drop_index("ix_image_prediction_image", "image_prediction")
-    op.drop_table("image_prediction")

alembic/versions/0046_drop_tagger_predictions.py

@@ -1,43 +0,0 @@
-"""drop image_record.tagger_predictions (predictions normalized to image_prediction)
-
-Final step of #768. The per-tag predictions now live in the image_prediction
-table (backfilled from the JSON, read by suggestions + allowlist, written by
-tag_and_embed). The old JSON column is dead weight — and it's the ~100 GB of
-sub-0.70 score tail that bloated image_record's TOAST and broke DB backups
-(#739). Dropping it is a fast catalog change; it does NOT reclaim the disk on
-its own — run `VACUUM FULL image_record` (or pg_repack) afterward, off-hours,
-to return the space to the OS so backups go small.
-
-DROP COLUMN needs a brief ACCESS EXCLUSIVE lock on image_record; env.py's
-lock_timeout guards it, so quiesce the ml-worker if a tagging run is in flight
-(see the migration-lock reference). tagger_model_version is kept — it's the
-"has this been tagged / is it current?" signal the backfill sweep reads.
-
-Revision ID: 0046
-Revises: 0045
-Create Date: 2026-06-11
-
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0046"
-down_revision: Union[str, None] = "0045"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.drop_column("image_record", "tagger_predictions")
-
-
-def downgrade() -> None:
-    # Re-add the column empty. The JSON data is not restored (it lived only in
-    # this column); a downgrade would re-tag or backfill from image_prediction
-    # separately if ever needed.
-    op.add_column(
-        "image_record",
-        sa.Column("tagger_predictions", sa.JSON(), nullable=True),
-    )

alembic/versions/0047_series_chapter_dividers.py

@@ -1,175 +0,0 @@
-"""series chapters become cosmetic dividers; pages become one series-global run
-
-FC-6.x reframe (#789). A series is now ONE flat, series-global ordered run of
-pages; chapters stop owning pages and become labeled dividers anchored to the
-page that begins them.
-
-Migration (order matters — series_page.chapter_id cascades, so it must be
-dropped BEFORE any chapter row is deleted, or pages would cascade away):
-  a. Renumber series_page.page_number to a series-global 1..N (ordered by the
-     OLD (chapter_number, page_number)).
-  b. Add series_chapter.anchor_page_id and populate it with each chapter's first
-     page (lowest new page_number).
-  c. Drop series_page.chapter_id (severs the cascade link).
-  d. Prune chapters that shouldn't become dividers: empty/placeholder ones (no
-     anchor) and the redundant unlabeled chapter that would sit at page 1.
-  e. Reshape series_chapter into the divider: drop chapter_number,
-     is_placeholder, stated_page_start/end; make anchor_page_id NOT NULL +
-     UNIQUE + FK→series_page ON DELETE CASCADE.
-
-Revision ID: 0047
-Revises: 0046
-Create Date: 2026-06-11
-
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0047"
-down_revision: Union[str, None] = "0046"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    # a. series-global page numbering, preserving the old reading order.
-    op.execute(
-        """
-        WITH ordered AS (
-            SELECT sp.id,
-                   ROW_NUMBER() OVER (
-                       PARTITION BY sp.series_tag_id
-                       ORDER BY sc.chapter_number, sp.page_number, sp.id
-                   ) AS rn
-            FROM series_page sp
-            JOIN series_chapter sc ON sc.id = sp.chapter_id
-        )
-        UPDATE series_page sp
-        SET page_number = ordered.rn
-        FROM ordered
-        WHERE sp.id = ordered.id
-        """
-    )
-
-    # b. anchor each existing chapter at its first page (lowest new page_number).
-    op.add_column(
-        "series_chapter",
-        sa.Column("anchor_page_id", sa.Integer(), nullable=True),
-    )
-    op.execute(
-        """
-        WITH firsts AS (
-            SELECT DISTINCT ON (sp.chapter_id)
-                   sp.chapter_id, sp.id AS page_id
-            FROM series_page sp
-            ORDER BY sp.chapter_id, sp.page_number, sp.id
-        )
-        UPDATE series_chapter sc
-        SET anchor_page_id = firsts.page_id
-        FROM firsts
-        WHERE firsts.chapter_id = sc.id
-        """
-    )
-
-    # c. sever the ownership link (drops the FK + index with the column) BEFORE
-    #    pruning chapters, so deleting a chapter can't cascade-delete its pages.
-    op.drop_column("series_page", "chapter_id")
-
-    # d. prune chapters that don't become dividers: placeholders / empty ones
-    #    (no anchor), and the unlabeled chapter that would land redundantly at
-    #    page 1 (the series just starts — no divider needed there).
-    op.execute(
-        """
-        DELETE FROM series_chapter sc
-        USING (
-            SELECT sc2.id
-            FROM series_chapter sc2
-            LEFT JOIN series_page sp ON sp.id = sc2.anchor_page_id
-            WHERE sc2.anchor_page_id IS NULL
-               OR (sp.page_number = 1
-                   AND sc2.title IS NULL
-                   AND sc2.stated_part IS NULL)
-        ) gone
-        WHERE sc.id = gone.id
-        """
-    )
-
-    # e. reshape into the divider model.
-    op.drop_column("series_chapter", "chapter_number")
-    op.drop_column("series_chapter", "is_placeholder")
-    op.drop_column("series_chapter", "stated_page_start")
-    op.drop_column("series_chapter", "stated_page_end")
-    op.alter_column("series_chapter", "anchor_page_id", nullable=False)
-    op.create_unique_constraint(
-        "uq_series_chapter_anchor_page", "series_chapter", ["anchor_page_id"]
-    )
-    op.create_foreign_key(
-        "fk_series_chapter_anchor_page",
-        "series_chapter",
-        "series_page",
-        ["anchor_page_id"],
-        ["id"],
-        ondelete="CASCADE",
-    )
-
-
-def downgrade() -> None:
-    # Lossy: dividers can't be reconstructed as owning chapters. Collapse back to
-    # exactly one chapter per series that owns all its pages in order.
-    op.add_column(
-        "series_page", sa.Column("chapter_id", sa.Integer(), nullable=True)
-    )
-    op.drop_constraint(
-        "fk_series_chapter_anchor_page", "series_chapter", type_="foreignkey"
-    )
-    op.drop_constraint(
-        "uq_series_chapter_anchor_page", "series_chapter", type_="unique"
-    )
-    op.drop_column("series_chapter", "anchor_page_id")
-    op.add_column(
-        "series_chapter",
-        sa.Column(
-            "chapter_number", sa.Integer(), nullable=False, server_default="1"
-        ),
-    )
-    op.add_column(
-        "series_chapter",
-        sa.Column(
-            "is_placeholder", sa.Boolean(), nullable=False,
-            server_default="false",
-        ),
-    )
-    op.add_column(
-        "series_chapter",
-        sa.Column("stated_page_start", sa.Integer(), nullable=True),
-    )
-    op.add_column(
-        "series_chapter",
-        sa.Column("stated_page_end", sa.Integer(), nullable=True),
-    )
-    op.execute("DELETE FROM series_chapter")
-    op.execute(
-        """
-        INSERT INTO series_chapter (series_tag_id, chapter_number)
-        SELECT DISTINCT series_tag_id, 1 FROM series_page
-        """
-    )
-    op.execute(
-        """
-        UPDATE series_page sp
-        SET chapter_id = sc.id
-        FROM series_chapter sc
-        WHERE sc.series_tag_id = sp.series_tag_id
-        """
-    )
-    op.alter_column("series_page", "chapter_id", nullable=False)
-    op.create_foreign_key(
-        "fk_series_page_chapter",
-        "series_page",
-        "series_chapter",
-        ["chapter_id"],
-        ["id"],
-        ondelete="CASCADE",
-    )

alembic/versions/0048_series_page_pending_status.py

@@ -1,45 +0,0 @@
-"""series_page pending staging: status + nullable page_number (#789 Phase 2)
-
-Pages added from a post no longer append straight into the run — they land
-'pending' with a NULL page_number, staged grouped by their source post so the
-operator can drop junk (text-free alts, bumpers) and place the keepers into the
-sequence. A page only gets a series-global page_number once it's 'placed'.
-
-Revision ID: 0048
-Revises: 0047
-Create Date: 2026-06-11
-
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0048"
-down_revision: Union[str, None] = "0047"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "series_page",
-        sa.Column(
-            "status", sa.String(length=16), nullable=False,
-            server_default="placed",
-        ),
-    )
-    op.alter_column(
-        "series_page", "page_number",
-        existing_type=sa.Integer(), nullable=True,
-    )
-
-
-def downgrade() -> None:
-    # Lossy: pending pages are unsorted staging rows with no order — drop them.
-    op.execute("DELETE FROM series_page WHERE status = 'pending'")
-    op.alter_column(
-        "series_page", "page_number",
-        existing_type=sa.Integer(), nullable=False,
-    )
-    op.drop_column("series_page", "status")

alembic/versions/0049_external_link_table.py

@@ -1,90 +0,0 @@
-"""external_link table — off-platform file-host links found in post bodies
-
-Creators host the real files on mega.nz / Google Drive / MediaFire / Dropbox /
-Pixeldrain and link them in the post text. This table records each such link
-(so nothing is silently dropped), and doubles as the dedup + dead-letter ledger
-the download worker (a later slice) walks. `url` keeps the FULL link including
-the `#fragment` — mega.nz's decryption key lives there; truncating it makes the
-file undownloadable.
-
-CHECK whitelists for host + status include the full enum up front (incl. the
-download-worker statuses) so the worker slice needs no constraint migration.
-
-Revision ID: 0049
-Revises: 0048
-Create Date: 2026-06-14
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0049"
-down_revision: Union[str, None] = "0048"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "external_link",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column(
-            "post_id", sa.Integer(),
-            sa.ForeignKey("post.id", ondelete="CASCADE"), nullable=False,
-        ),
-        sa.Column(
-            "artist_id", sa.Integer(),
-            sa.ForeignKey("artist.id", ondelete="SET NULL"), nullable=True,
-        ),
-        sa.Column("host", sa.String(length=16), nullable=False),
-        sa.Column("url", sa.Text(), nullable=False),
-        sa.Column("label", sa.Text(), nullable=True),
-        sa.Column(
-            "status", sa.String(length=16), nullable=False,
-            server_default="pending",
-        ),
-        sa.Column("attempts", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("last_error", sa.Text(), nullable=True),
-        sa.Column(
-            "attachment_id", sa.Integer(),
-            sa.ForeignKey("post_attachment.id", ondelete="SET NULL"),
-            nullable=True,
-        ),
-        sa.Column(
-            "created_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column("completed_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("duration_seconds", sa.Float(), nullable=True),
-        sa.CheckConstraint(
-            "host IN ('mega','gdrive','mediafire','dropbox','pixeldrain')",
-            name="ck_external_link_host",
-        ),
-        sa.CheckConstraint(
-            "status IN ('pending','downloading','downloaded','failed',"
-            "'skipped','dead')",
-            name="ck_external_link_status",
-        ),
-    )
-    op.create_index(
-        "ix_external_link_post_id", "external_link", ["post_id"],
-    )
-    op.create_index(
-        "ix_external_link_artist_id", "external_link", ["artist_id"],
-    )
-    op.create_index(
-        "ix_external_link_status", "external_link", ["status"],
-    )
-    op.create_index(
-        "uq_external_link_post_url", "external_link", ["post_id", "url"],
-        unique=True,
-    )
-
-
-def downgrade() -> None:
-    op.drop_index("uq_external_link_post_url", table_name="external_link")
-    op.drop_index("ix_external_link_status", table_name="external_link")
-    op.drop_index("ix_external_link_artist_id", table_name="external_link")
-    op.drop_index("ix_external_link_post_id", table_name="external_link")
-    op.drop_table("external_link")

alembic/versions/0050_external_link_host_toggles.py

@@ -1,38 +0,0 @@
-"""import_settings: per-host enable toggles for external file-host downloads
-
-Operator levers (#830): disable a single host (e.g. mega.nz when it's
-rate-limiting/banning) without touching the others. The worker reads these via
-getattr and defaults to enabled, so the toggles default TRUE (works out of the
-box, rule #26).
-
-Revision ID: 0050
-Revises: 0049
-Create Date: 2026-06-14
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0050"
-down_revision: Union[str, None] = "0049"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-_HOSTS = ("mega", "gdrive", "mediafire", "dropbox", "pixeldrain")
-
-
-def upgrade() -> None:
-    for host in _HOSTS:
-        op.add_column(
-            "import_settings",
-            sa.Column(
-                f"extdl_{host}_enabled", sa.Boolean(), nullable=False,
-                server_default=sa.true(),
-            ),
-        )
-
-
-def downgrade() -> None:
-    for host in _HOSTS:
-        op.drop_column("import_settings", f"extdl_{host}_enabled")

alembic/versions/0051_image_source_provenance.py

@@ -1,38 +0,0 @@
-"""image_record: source_url + source_filehash (inline-image localization)
-
-#830 Phase 2. To render a post body faithfully we serve LOCAL copies of inline
-images instead of hotlinking the public CDN. The join key between a body
-`<img src=CDN>` and the local file is the CDN's 32-hex filehash (the same
-identity extract_media dedups by). Persist it (indexed) plus the full source
-URL for provenance/debugging. Both NULL for filesystem-imported / pre-existing
-rows — those fall back to hotlinking until re-downloaded.
-
-Revision ID: 0051
-Revises: 0050
-Create Date: 2026-06-14
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0051"
-down_revision: Union[str, None] = "0050"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column("image_record", sa.Column("source_url", sa.Text(), nullable=True))
-    op.add_column(
-        "image_record", sa.Column("source_filehash", sa.String(length=32), nullable=True)
-    )
-    op.create_index(
-        "ix_image_record_source_filehash", "image_record", ["source_filehash"]
-    )
-
-
-def downgrade() -> None:
-    op.drop_index("ix_image_record_source_filehash", table_name="image_record")
-    op.drop_column("image_record", "source_filehash")
-    op.drop_column("image_record", "source_url")

alembic/versions/0052_image_duration_seconds.py

@@ -1,32 +0,0 @@
-"""image_record: duration_seconds (Tier-1 video near-dup key)
-
-#871. Videos previously deduped on sha256 only (pHash is images-only), so a
-different encode/remux of the same video imported as a distinct record. Persist
-the container duration so the importer can treat same-artist videos with matching
-duration (+ aspect ratio) as the same content and dedup/supersede like images.
-NULL for images and for video rows imported before this column existed (a
-backfill re-probes those so they participate in dedup).
-
-Revision ID: 0052
-Revises: 0051
-Create Date: 2026-06-16
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0052"
-down_revision: Union[str, None] = "0051"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "image_record", sa.Column("duration_seconds", sa.Float(), nullable=True)
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("image_record", "duration_seconds")

alembic/versions/0053_ml_settings_video_tagging.py

@@ -1,49 +0,0 @@
-"""ml_settings: video tagging knobs (cadence sampling + noise floor)
-
-#747. Video tag quality/perf: sample frames at a fixed cadence (interval) so a
-tag's frame-presence reflects real screen time, cap total frames so long videos
-stay bounded, and keep a tag only if it appears in >= min_tag_frames sampled
-frames. Operator-tunable via Settings → ML (replaces the VIDEO_ML_FRAMES env var).
-
-Revision ID: 0053
-Revises: 0052
-Create Date: 2026-06-16
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0053"
-down_revision: Union[str, None] = "0052"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "ml_settings",
-        sa.Column(
-            "video_frame_interval_seconds", sa.Float(), nullable=False,
-            server_default="4.0",
-        ),
-    )
-    op.add_column(
-        "ml_settings",
-        sa.Column(
-            "video_max_frames", sa.Integer(), nullable=False, server_default="64",
-        ),
-    )
-    op.add_column(
-        "ml_settings",
-        sa.Column(
-            "video_min_tag_frames", sa.Integer(), nullable=False,
-            server_default="3",
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("ml_settings", "video_min_tag_frames")
-    op.drop_column("ml_settings", "video_max_frames")
-    op.drop_column("ml_settings", "video_frame_interval_seconds")

alembic/versions/0054_subscribestar_ledgers.py

@@ -1,82 +0,0 @@
-"""subscribestar_seen_media + subscribestar_failed_media: per-source ledgers
-
-Revision ID: 0054
-Revises: 0053
-Create Date: 2026-06-17
-
-SubscribeStar native ingester (phase 1 of the gallery-dl → native-core
-migration). Mirrors the Patreon ledger tables (0037/0038): a seen-ledger so
-routine walks skip already-ingested media (recovery bypasses it) and a
-dead-letter ledger so persistently-failing media stops re-burning backfill
-chunks. `filehash` is a CDN content hash when present, else a synthesized
-``<post_id>:<filename>`` key — hence String(128). UNIQUE (source_id, filehash)
-is the upsert key on each.
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0054"
-down_revision: Union[str, None] = "0053"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "subscribestar_seen_media",
-        sa.Column("id", sa.Integer, primary_key=True),
-        sa.Column(
-            "source_id",
-            sa.Integer,
-            sa.ForeignKey("source.id", ondelete="CASCADE"),
-            nullable=False,
-            index=True,
-        ),
-        sa.Column("filehash", sa.String(128), nullable=False),
-        sa.Column("post_id", sa.String(64), nullable=True),
-        sa.Column(
-            "seen_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("NOW()"),
-        ),
-        sa.UniqueConstraint(
-            "source_id", "filehash", name="uq_subscribestar_seen_media_source_id"
-        ),
-    )
-    op.create_table(
-        "subscribestar_failed_media",
-        sa.Column("id", sa.Integer, primary_key=True),
-        sa.Column(
-            "source_id",
-            sa.Integer,
-            sa.ForeignKey("source.id", ondelete="CASCADE"),
-            nullable=False,
-            index=True,
-        ),
-        sa.Column("filehash", sa.String(128), nullable=False),
-        sa.Column("attempts", sa.Integer, nullable=False, server_default="1"),
-        sa.Column("last_error", sa.Text, nullable=True),
-        sa.Column(
-            "first_failed_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("NOW()"),
-        ),
-        sa.Column(
-            "last_failed_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("NOW()"),
-        ),
-        sa.UniqueConstraint(
-            "source_id", "filehash", name="uq_subscribestar_failed_media_source_id"
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_table("subscribestar_failed_media")
-    op.drop_table("subscribestar_seen_media")

alembic/versions/0055_image_provenance_from_attachment.py

@@ -1,55 +0,0 @@
-"""image_provenance: from_attachment_id (which archive an image was extracted from)
-
-Milestone #87. When an image is pulled out of a .zip/.rar, record WHICH archive
-PostAttachment it came from, so the provenance UI can show the single archive a
-file lives inside instead of every attachment on the post. Nullable FK with
-ON DELETE SET NULL — a loose (non-archive) download leaves it NULL, and deleting
-the archive attachment forgets the linkage without destroying the (image, post)
-provenance edge. Existing rows are NULL until the reextract backfill stamps them.
-
-Revision ID: 0055
-Revises: 0054
-Create Date: 2026-06-22
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0055"
-down_revision: Union[str, None] = "0054"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "image_provenance",
-        sa.Column("from_attachment_id", sa.Integer(), nullable=True),
-    )
-    op.create_index(
-        "ix_image_provenance_from_attachment_id",
-        "image_provenance",
-        ["from_attachment_id"],
-    )
-    op.create_foreign_key(
-        "fk_image_provenance_from_attachment",
-        "image_provenance",
-        "post_attachment",
-        ["from_attachment_id"],
-        ["id"],
-        ondelete="SET NULL",
-    )
-
-
-def downgrade() -> None:
-    op.drop_constraint(
-        "fk_image_provenance_from_attachment",
-        "image_provenance",
-        type_="foreignkey",
-    )
-    op.drop_index(
-        "ix_image_provenance_from_attachment_id",
-        table_name="image_provenance",
-    )
-    op.drop_column("image_provenance", "from_attachment_id")

alembic/versions/0056_tag_eval_run.py

@@ -1,43 +0,0 @@
-"""tag_eval_run: persisted head-vs-centroid tagging eval runs (#1130)
-
-Milestone #114 slice 1. A long ml-queue eval whose full report must SURVIVE
-navigation, so the run + report live in a row the admin card rehydrates from
-(mirrors library_audit_run). running -> ready / error.
-
-Revision ID: 0056
-Revises: 0055
-Create Date: 2026-06-28
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-from sqlalchemy.dialects.postgresql import JSONB
-
-revision: str = "0056"
-down_revision: Union[str, None] = "0055"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "tag_eval_run",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column("params", JSONB(), nullable=False),
-        sa.Column("status", sa.String(length=16), nullable=False, server_default="running"),
-        sa.Column(
-            "started_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("report", JSONB(), nullable=True),
-        sa.Column("error", sa.Text(), nullable=True),
-        sa.Column("last_progress_at", sa.DateTime(timezone=True), nullable=True),
-    )
-    op.create_index("ix_tag_eval_run_status", "tag_eval_run", ["status"])
-
-
-def downgrade() -> None:
-    op.drop_index("ix_tag_eval_run_status", table_name="tag_eval_run")
-    op.drop_table("tag_eval_run")

alembic/versions/0057_tag_positive_confirmation.py

@@ -1,40 +0,0 @@
-"""tag_positive_confirmation: operator-affirmed correct positives (#1130)
-
-Mirror of tag_suggestion_rejection. "Keep" on a doubted positive records here so
-the eval's doubts list stops resurfacing confirmed-correct images every run.
-
-Revision ID: 0057
-Revises: 0056
-Create Date: 2026-06-28
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0057"
-down_revision: Union[str, None] = "0056"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "tag_positive_confirmation",
-        sa.Column(
-            "image_record_id", sa.Integer(),
-            sa.ForeignKey("image_record.id", ondelete="CASCADE"), primary_key=True,
-        ),
-        sa.Column(
-            "tag_id", sa.Integer(),
-            sa.ForeignKey("tag.id", ondelete="CASCADE"), primary_key=True, index=True,
-        ),
-        sa.Column(
-            "confirmed_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_table("tag_positive_confirmation")

alembic/versions/0058_tag_head.py

@@ -1,95 +0,0 @@
-"""tag_head + head_training_run: production heads that learn from tags (#114)
-
-The eval (#1130) proved the frozen-embedding + trained-head spine; this lands its
-production form. tag_head stores one logistic-regression head per concept (the
-new suggestion source, replacing Camie + centroid); head_training_run tracks the
-batch that (re)trains them. Adds two head-training tunables to ml_settings.
-
-Revision ID: 0058
-Revises: 0057
-Create Date: 2026-06-28
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-from pgvector.sqlalchemy import Vector
-from sqlalchemy.dialects.postgresql import JSONB
-
-revision: str = "0058"
-down_revision: Union[str, None] = "0057"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-_HEAD_DIM = 1152
-
-
-def upgrade() -> None:
-    op.create_table(
-        "tag_head",
-        sa.Column(
-            "tag_id", sa.Integer(),
-            sa.ForeignKey("tag.id", ondelete="CASCADE"), primary_key=True,
-        ),
-        sa.Column("embedding_version", sa.String(length=128), nullable=False),
-        sa.Column("weights", Vector(_HEAD_DIM), nullable=False),
-        sa.Column("bias", sa.Float(), nullable=False),
-        sa.Column("suggest_threshold", sa.Float(), nullable=False),
-        sa.Column("auto_apply_threshold", sa.Float(), nullable=True),
-        sa.Column("n_pos", sa.Integer(), nullable=False),
-        sa.Column("n_neg", sa.Integer(), nullable=False),
-        sa.Column("ap", sa.Float(), nullable=False),
-        sa.Column("precision_cv", sa.Float(), nullable=False),
-        sa.Column("recall", sa.Float(), nullable=False),
-        sa.Column(
-            "trained_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column("metrics", JSONB(), nullable=True),
-    )
-
-    op.create_table(
-        "head_training_run",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column("params", JSONB(), nullable=False),
-        sa.Column(
-            "status", sa.String(length=16), nullable=False,
-            server_default="running",
-        ),
-        sa.Column(
-            "started_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("n_trained", sa.Integer(), nullable=True),
-        sa.Column("n_skipped", sa.Integer(), nullable=True),
-        sa.Column("error", sa.Text(), nullable=True),
-        sa.Column("last_progress_at", sa.DateTime(timezone=True), nullable=True),
-    )
-    op.create_index(
-        "ix_head_training_run_status", "head_training_run", ["status"],
-    )
-
-    # Head-training tunables on the ml_settings singleton.
-    op.add_column(
-        "ml_settings",
-        sa.Column(
-            "head_min_positives", sa.Integer(), nullable=False,
-            server_default="8",
-        ),
-    )
-    op.add_column(
-        "ml_settings",
-        sa.Column(
-            "head_auto_apply_precision", sa.Float(), nullable=False,
-            server_default="0.97",
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("ml_settings", "head_auto_apply_precision")
-    op.drop_column("ml_settings", "head_min_positives")
-    op.drop_index("ix_head_training_run_status", table_name="head_training_run")
-    op.drop_table("head_training_run")
-    op.drop_table("tag_head")

alembic/versions/0059_head_auto_apply.py

@@ -1,70 +0,0 @@
-"""head_auto_apply_run + earned-auto-apply settings (#114)
-
-A graduated head can apply its tag without a human, gated by a master switch +
-a support floor. head_auto_apply_run tracks each sweep / dry-run preview.
-
-Revision ID: 0059
-Revises: 0058
-Create Date: 2026-06-29
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-from sqlalchemy.dialects.postgresql import JSONB
-
-revision: str = "0059"
-down_revision: Union[str, None] = "0058"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "head_auto_apply_run",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column(
-            "dry_run", sa.Boolean(), nullable=False, server_default=sa.false()
-        ),
-        sa.Column("params", JSONB(), nullable=False),
-        sa.Column(
-            "status", sa.String(length=16), nullable=False,
-            server_default="running",
-        ),
-        sa.Column(
-            "started_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column("finished_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("n_applied", sa.Integer(), nullable=True),
-        sa.Column("report", JSONB(), nullable=True),
-        sa.Column("error", sa.Text(), nullable=True),
-        sa.Column("last_progress_at", sa.DateTime(timezone=True), nullable=True),
-    )
-    op.create_index(
-        "ix_head_auto_apply_run_status", "head_auto_apply_run", ["status"],
-    )
-
-    op.add_column(
-        "ml_settings",
-        sa.Column(
-            "head_auto_apply_enabled", sa.Boolean(), nullable=False,
-            server_default=sa.true(),  # opt-out: on by default (operator-asked)
-        ),
-    )
-    op.add_column(
-        "ml_settings",
-        sa.Column(
-            "head_auto_apply_min_positives", sa.Integer(), nullable=False,
-            server_default="30",
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("ml_settings", "head_auto_apply_min_positives")
-    op.drop_column("ml_settings", "head_auto_apply_enabled")
-    op.drop_index(
-        "ix_head_auto_apply_run_status", table_name="head_auto_apply_run"
-    )
-    op.drop_table("head_auto_apply_run")

alembic/versions/0060_head_metrics.py

@@ -1,74 +0,0 @@
-"""head_metric + head_metrics_snapshot: auto-apply observability (#114)
-
-Running misfire/under-fire counters per concept (captured at correction time,
-since image_tag.source is lost on delete) + a daily per-concept time-series so
-the operator can tune the precision target + support floor from real data.
-
-Revision ID: 0060
-Revises: 0059
-Create Date: 2026-06-29
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0060"
-down_revision: Union[str, None] = "0059"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "head_metric",
-        sa.Column(
-            "tag_id", sa.Integer(),
-            sa.ForeignKey("tag.id", ondelete="CASCADE"), primary_key=True,
-        ),
-        sa.Column("n_misfires", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("n_underfires", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column(
-            "updated_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-    )
-
-    op.create_table(
-        "head_metrics_snapshot",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column(
-            "tag_id", sa.Integer(),
-            sa.ForeignKey("tag.id", ondelete="CASCADE"),
-        ),
-        sa.Column("name", sa.String(length=255), nullable=False),
-        sa.Column(
-            "snapshot_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column("n_auto_applied", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("n_misfires", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("n_underfires", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("ap", sa.Float(), nullable=True),
-        sa.Column("precision_cv", sa.Float(), nullable=True),
-        sa.Column("recall", sa.Float(), nullable=True),
-        sa.Column("n_pos", sa.Integer(), nullable=True),
-    )
-    op.create_index(
-        "ix_head_metrics_snapshot_tag_id", "head_metrics_snapshot", ["tag_id"],
-    )
-    op.create_index(
-        "ix_head_metrics_snapshot_snapshot_at", "head_metrics_snapshot",
-        ["snapshot_at"],
-    )
-
-
-def downgrade() -> None:
-    op.drop_index(
-        "ix_head_metrics_snapshot_snapshot_at", table_name="head_metrics_snapshot"
-    )
-    op.drop_index(
-        "ix_head_metrics_snapshot_tag_id", table_name="head_metrics_snapshot"
-    )
-    op.drop_table("head_metrics_snapshot")
-    op.drop_table("head_metric")

alembic/versions/0061_image_region.py

@@ -1,59 +0,0 @@
-"""image_region: detected/proposed regions + their crop embeddings (#114)
-
-Storage backbone of the crop pipeline. A region = normalized bbox + the crop's
-embedding (CCIP for face/figure → character id; SigLIP for concept regions →
-head bag-of-embeddings). Also serves as grounded-tag bbox provenance.
-
-Revision ID: 0061
-Revises: 0060
-Create Date: 2026-06-29
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-from pgvector.sqlalchemy import Vector
-
-revision: str = "0061"
-down_revision: Union[str, None] = "0060"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-_CCIP_DIM = 768
-_SIGLIP_DIM = 1152
-
-
-def upgrade() -> None:
-    op.create_table(
-        "image_region",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column(
-            "image_record_id", sa.Integer(),
-            sa.ForeignKey("image_record.id", ondelete="CASCADE"), nullable=False,
-        ),
-        sa.Column("kind", sa.String(length=16), nullable=False),
-        # Video/animated: source frame timestamp (seconds); NULL for stills.
-        sa.Column("frame_time", sa.Float(), nullable=True),
-        sa.Column("rx", sa.Float(), nullable=False),
-        sa.Column("ry", sa.Float(), nullable=False),
-        sa.Column("rw", sa.Float(), nullable=False),
-        sa.Column("rh", sa.Float(), nullable=False),
-        sa.Column("score", sa.Float(), nullable=True),
-        sa.Column("detector_version", sa.String(length=64), nullable=True),
-        sa.Column("crop_version", sa.String(length=64), nullable=True),
-        sa.Column("embedding_version", sa.String(length=128), nullable=True),
-        sa.Column("ccip_embedding", Vector(_CCIP_DIM), nullable=True),
-        sa.Column("siglip_embedding", Vector(_SIGLIP_DIM), nullable=True),
-        sa.Column(
-            "created_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-    )
-    op.create_index(
-        "ix_image_region_image_record_id", "image_region", ["image_record_id"],
-    )
-
-
-def downgrade() -> None:
-    op.drop_index("ix_image_region_image_record_id", table_name="image_region")
-    op.drop_table("image_region")

alembic/versions/0062_gpu_job.py

@@ -1,55 +0,0 @@
-"""gpu_job: the HTTP-leased GPU work queue for the desktop agent (#114)
-
-The agent stays HTTP-only — the server enqueues per-(image, task) jobs here and
-the agent leases/submits over the web API; Redis/Postgres stay private.
-
-Revision ID: 0062
-Revises: 0061
-Create Date: 2026-06-29
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0062"
-down_revision: Union[str, None] = "0061"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        "gpu_job",
-        sa.Column("id", sa.Integer(), primary_key=True),
-        sa.Column(
-            "image_record_id", sa.Integer(),
-            sa.ForeignKey("image_record.id", ondelete="CASCADE"), nullable=False,
-        ),
-        sa.Column("task", sa.String(length=32), nullable=False),
-        sa.Column(
-            "status", sa.String(length=16), nullable=False,
-            server_default="pending",
-        ),
-        sa.Column("lease_token", sa.String(length=64), nullable=True),
-        sa.Column("leased_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("lease_expires_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("attempts", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("error", sa.Text(), nullable=True),
-        sa.Column(
-            "created_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-        sa.Column(
-            "updated_at", sa.DateTime(timezone=True), nullable=False,
-            server_default=sa.func.now(),
-        ),
-    )
-    op.create_index("ix_gpu_job_image_record_id", "gpu_job", ["image_record_id"])
-    op.create_index("ix_gpu_job_status", "gpu_job", ["status"])
-
-
-def downgrade() -> None:
-    op.drop_index("ix_gpu_job_status", table_name="gpu_job")
-    op.drop_index("ix_gpu_job_image_record_id", table_name="gpu_job")
-    op.drop_table("gpu_job")

alembic/versions/0063_ccip_match_threshold.py

@@ -1,33 +0,0 @@
-"""ml_settings.ccip_match_threshold — tunable CCIP character-match cut (#114)
-
-The v1 matcher used a flat 0.75 cosine; live data showed that over-fires (a
-high-reference character matched a scatter of images). 0.85 keeps the confident
-single-character matches and drops the noise. Tunable from the GPU agent card.
-
-Revision ID: 0063
-Revises: 0062
-Create Date: 2026-06-29
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0063"
-down_revision: Union[str, None] = "0062"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "ml_settings",
-        sa.Column(
-            "ccip_match_threshold", sa.Float(), nullable=False,
-            server_default="0.85",
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("ml_settings", "ccip_match_threshold")

alembic/versions/0064_ccip_auto_apply.py

@@ -1,42 +0,0 @@
-"""ml_settings: CCIP auto-apply switch + threshold (#114)
-
-Confident CCIP character matches auto-tag (source='ccip_auto') on a daily sweep,
-so identity tags keep flowing without pressing a button. ON by default (opt-out,
-like head auto-apply); the high threshold (0.92, above the 0.85 suggest cut) +
-single-character references keep it safe, and every auto-tag is reversible.
-
-Revision ID: 0064
-Revises: 0063
-Create Date: 2026-06-30
-"""
-from typing import Sequence, Union
-
-import sqlalchemy as sa
-from alembic import op
-
-revision: str = "0064"
-down_revision: Union[str, None] = "0063"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.add_column(
-        "ml_settings",
-        sa.Column(
-            "ccip_auto_apply_enabled", sa.Boolean(), nullable=False,
-            server_default=sa.true(),
-        ),
-    )
-    op.add_column(
-        "ml_settings",
-        sa.Column(
-            "ccip_auto_apply_threshold", sa.Float(), nullable=False,
-            server_default="0.92",
-        ),
-    )
-
-
-def downgrade() -> None:
-    op.drop_column("ml_settings", "ccip_auto_apply_threshold")
-    op.drop_column("ml_settings", "ccip_auto_apply_enabled")

alembic/versions/0089_baseline.py

@@ -0,0 +1,836 @@
+"""The whole schema, in one migration.
+
+This replaces alembic revisions 0001..0089 — the entire build-out of the
+project, 89 files and ~6,000 lines that a new installation used to replay in
+order to arrive at a schema this file creates in one pass. Nothing about the
+resulting database changes; what goes away is the requirement that a stranger
+re-run our development history to get it.
+
+## Why the revision id is 0089
+
+`revision = "0089"` and `down_revision = None` are both deliberate, and the
+combination is the entire migration strategy for existing installations.
+
+An already-deployed database has `alembic_version = '0089'`, because it ran the
+real 0089. This file claims that same id, so alembic reads the version table,
+sees head already reached, and does nothing at all. No stamp is needed — which
+matters because `alembic stamp` writes a version string without validating
+anything about the schema it is writing it against, and a stamp that is wrong
+is indistinguishable from one that is right until the next migration fails.
+
+An empty database has no version row, so alembic runs this file and then
+records `0089`. Both paths converge on the same schema and the same version,
+and neither requires anyone to assert anything by hand.
+
+The next migration written after this one is `0090`, exactly as it would have
+been. The numbering is continuous across the collapse on purpose.
+
+## What was added to the generated output, and why
+
+`alembic revision --autogenerate` produced almost all of this from the models,
+which is only true because #3275 first made the models actually describe the
+schema. Before that reconciliation the generator silently omitted eleven
+indexes and three uniqueness guarantees, and an earlier attempt at this squash
+had to be reverted for exactly that reason.
+
+Four things still had to be added by hand, because they are not in the models:
+
+1. **`CREATE EXTENSION vector`** (from 0001) and **`tsm_system_rows`** (0004).
+   Extensions are database objects, not table metadata, so no model can carry
+   them. `IF NOT EXISTS` because a re-run must not fail.
+
+2. **Three seed inserts** — the two settings singletons (0002, 0003) and the
+   three hygiene system tags (0075). Some migrations did not only build schema;
+   they inserted rows the product needs in order to function, and nothing in
+   the application ever creates them. Every consumer reads them with
+   `scalar_one()`, which RAISES `NoResultFound` on an empty result rather than
+   returning None, so their absence is a crash and not a degradation.
+
+   Distinguishing these from the other data statements in the chain is the
+   whole trick, and the rule turns out to be mechanical:
+
+     * `INSERT ... VALUES (...)` with literal values is a SEED. It creates
+       something the product ships. It must be carried.
+     * `INSERT ... SELECT ... FROM <table>` is a BACKFILL. It derives rows
+       from rows that already exist, so on an empty database it inserts
+       nothing and carrying it would be pointless. 0034 (artist_visit), 0040
+       and 0047 (series_chapter) are all of this shape and are correctly
+       absent here.
+
+   This category is invisible to every automated check this project has:
+   `baseline.yml` compares SCHEMA, and a baseline missing all three seeds still
+   produces a byte-identical schema and a perfectly green diff. What caught the
+   system tags was the integration suite — 36 tests failing on
+   `NoResultFound` — after a first version of this file shipped with only the
+   two settings rows. A first-run check against the real application is the
+   only thing that finds this class of defect.
+
+3. **The `pgvector` import.** Autogenerate emits qualified
+   `pgvector.sqlalchemy.vector.VECTOR(...)` references without importing the
+   package, so the file it writes cannot execute — `NameError: name 'pgvector'
+   is not defined`, observed on run 4988.
+
+The other data statements in the old chain were deliberately NOT carried over.
+0023's `DELETE FROM tag WHERE kind IN (...)`, and 0047's `series_page` /
+`series_chapter` deletes, are historical cleanups that operate on rows an empty
+database does not have.
+
+## Downgrade
+
+There is none. A baseline's downgrade would be "drop the entire schema", which
+is not a migration but a data-loss event wearing one as a disguise. Restore
+from a backup instead — that is what backup_run exists for.
+
+Revision ID: 0089
+Revises:
+Create Date: 2026-09-01
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+import pgvector.sqlalchemy.vector
+from sqlalchemy.dialects import postgresql
+
+revision: str = "0089"
+down_revision: Union[str, None] = None
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # Extensions first: image_record.siglip_embedding is a vector column and
+    # cannot be created before the type exists. From 0001 and 0004.
+    op.execute("CREATE EXTENSION IF NOT EXISTS vector")
+    op.execute("CREATE EXTENSION IF NOT EXISTS tsm_system_rows")
+
+    op.create_table('app_setting',
+    sa.Column('key', sa.String(length=64), nullable=False),
+    sa.Column('value', sa.Text(), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.PrimaryKeyConstraint('key', name=op.f('pk_app_setting'))
+    )
+    op.create_table('artist',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('name', sa.String(length=255), nullable=False),
+    sa.Column('slug', sa.String(length=255), nullable=False),
+    sa.Column('notes', sa.Text(), nullable=True),
+    sa.Column('is_subscription', sa.Boolean(), server_default='false', nullable=False),
+    sa.Column('auto_check', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('check_interval_seconds', sa.Integer(), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_artist')),
+    sa.UniqueConstraint('slug', name=op.f('uq_artist_slug'))
+    )
+    op.create_table('backup_run',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('kind', sa.String(length=16), nullable=False),
+    sa.Column('status', sa.String(length=16), server_default='pending', nullable=False),
+    sa.Column('tag', sa.String(length=64), nullable=True),
+    sa.Column('triggered_by', sa.String(length=32), nullable=False),
+    sa.Column('started_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('finished_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('sql_path', sa.Text(), nullable=True),
+    sa.Column('tar_path', sa.Text(), nullable=True),
+    sa.Column('size_bytes', sa.BigInteger(), nullable=True),
+    sa.Column('error', sa.Text(), nullable=True),
+    sa.Column('manifest', sa.JSON(), server_default='{}', nullable=False),
+    sa.Column('restored_from_id', sa.Integer(), nullable=True),
+    sa.ForeignKeyConstraint(['restored_from_id'], ['backup_run.id'], name=op.f('fk_backup_run_restored_from_id_backup_run'), ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_backup_run'))
+    )
+    op.create_index(op.f('ix_backup_run_finished_at'), 'backup_run', ['finished_at'], unique=False)
+    op.create_index('ix_backup_run_kind_started', 'backup_run', ['kind', sa.literal_column('started_at DESC')], unique=False)
+    op.create_index(op.f('ix_backup_run_restored_from_id'), 'backup_run', ['restored_from_id'], unique=False)
+    op.create_index(op.f('ix_backup_run_started_at'), 'backup_run', ['started_at'], unique=False)
+    op.create_index('ix_backup_run_status_finished', 'backup_run', ['status', sa.literal_column('finished_at DESC')], unique=False)
+    op.create_index(op.f('ix_backup_run_tag'), 'backup_run', ['tag'], unique=False)
+    op.create_index('ix_backup_run_tag_partial', 'backup_run', ['tag'], unique=False, postgresql_where=sa.text('tag IS NOT NULL'))
+    op.create_table('credential',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('platform', sa.String(length=64), nullable=False),
+    sa.Column('credential_type', sa.String(length=32), nullable=False),
+    sa.Column('encrypted_blob', sa.LargeBinary(), nullable=False),
+    sa.Column('captured_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('expires_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('last_verified', sa.DateTime(timezone=True), nullable=True),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_credential')),
+    sa.UniqueConstraint('platform', name=op.f('uq_credential_platform'))
+    )
+    op.create_table('head_auto_apply_run',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('dry_run', sa.Boolean(), server_default='false', nullable=False),
+    sa.Column('params', postgresql.JSONB(astext_type=sa.Text()), nullable=False),
+    sa.Column('status', sa.String(length=16), server_default='running', nullable=False),
+    sa.Column('started_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('finished_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('n_applied', sa.Integer(), nullable=True),
+    sa.Column('report', postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+    sa.Column('error', sa.Text(), nullable=True),
+    sa.Column('last_progress_at', sa.DateTime(timezone=True), nullable=True),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_head_auto_apply_run'))
+    )
+    op.create_index(op.f('ix_head_auto_apply_run_status'), 'head_auto_apply_run', ['status'], unique=False)
+    op.create_table('head_training_run',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('params', postgresql.JSONB(astext_type=sa.Text()), nullable=False),
+    sa.Column('status', sa.String(length=16), server_default='running', nullable=False),
+    sa.Column('started_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('finished_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('n_trained', sa.Integer(), nullable=True),
+    sa.Column('n_skipped', sa.Integer(), nullable=True),
+    sa.Column('error', sa.Text(), nullable=True),
+    sa.Column('last_progress_at', sa.DateTime(timezone=True), nullable=True),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_head_training_run'))
+    )
+    op.create_index(op.f('ix_head_training_run_status'), 'head_training_run', ['status'], unique=False)
+    op.create_table('import_batch',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('triggered_by', sa.String(length=32), nullable=False),
+    sa.Column('source_path', sa.Text(), nullable=False),
+    sa.Column('scan_mode', sa.String(length=16), nullable=False),
+    sa.Column('started_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('finished_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('total_files', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('imported', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('skipped', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('failed', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('attachments', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('refreshed', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('status', sa.String(length=16), server_default='running', nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_import_batch'))
+    )
+    op.create_index(op.f('ix_import_batch_status'), 'import_batch', ['status'], unique=False)
+    op.create_table('import_settings',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('import_scan_path', sa.Text(), server_default='/import', nullable=False),
+    sa.Column('min_width', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('min_height', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('skip_transparent', sa.Boolean(), server_default='false', nullable=False),
+    sa.Column('transparency_threshold', sa.Float(), server_default='0.9', nullable=False),
+    sa.Column('skip_single_color', sa.Boolean(), server_default='false', nullable=False),
+    sa.Column('single_color_threshold', sa.Float(), server_default='0.95', nullable=False),
+    sa.Column('single_color_tolerance', sa.Integer(), server_default='30', nullable=False),
+    sa.Column('phash_threshold', sa.Integer(), server_default='10', nullable=False),
+    sa.Column('download_rate_limit_seconds', sa.Float(), server_default='3', nullable=False),
+    sa.Column('download_validate_files', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('download_schedule_default_seconds', sa.Integer(), server_default='28800', nullable=False),
+    sa.Column('download_event_retention_days', sa.Integer(), server_default='90', nullable=False),
+    sa.Column('download_failure_warning_threshold', sa.Integer(), server_default='5', nullable=False),
+    sa.Column('backup_db_nightly_enabled', sa.Boolean(), server_default='false', nullable=False),
+    sa.Column('backup_db_nightly_hour_utc', sa.Integer(), server_default='3', nullable=False),
+    sa.Column('backup_db_keep_last_n', sa.Integer(), server_default='14', nullable=False),
+    sa.Column('backup_images_keep_last_n', sa.Integer(), server_default='3', nullable=False),
+    sa.Column('series_suggest_enabled', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('series_suggest_threshold', sa.Float(), server_default='0.5', nullable=False),
+    sa.Column('extdl_mega_enabled', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('extdl_gdrive_enabled', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('extdl_mediafire_enabled', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('extdl_dropbox_enabled', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('extdl_pixeldrain_enabled', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('translation_enabled', sa.Boolean(), server_default='false', nullable=False),
+    sa.Column('interpreter_base_url', sa.Text(), server_default='', nullable=False),
+    sa.Column('translation_target_lang', sa.Text(), server_default='en', nullable=False),
+    sa.Column('translation_min_confidence', sa.Float(), server_default=sa.text('0.9'), nullable=False),
+    sa.Column('wip_title_tagging_enabled', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('wip_soft_title_tagging_enabled', sa.Boolean(), server_default='false', nullable=False),
+    sa.CheckConstraint('id = 1', name=op.f('ck_import_settings_singleton')),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_import_settings'))
+    )
+    op.create_table('library_audit_run',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('rule', sa.String(length=32), nullable=False),
+    sa.Column('params', postgresql.JSONB(astext_type=sa.Text()), nullable=False),
+    sa.Column('status', sa.String(length=16), server_default='running', nullable=False),
+    sa.Column('started_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('finished_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('scanned_count', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('matched_count', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('matched_ids', postgresql.JSONB(astext_type=sa.Text()), server_default=sa.text("'[]'::jsonb"), nullable=False),
+    sa.Column('error', sa.Text(), nullable=True),
+    sa.Column('resume_after_id', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('last_progress_at', sa.DateTime(timezone=True), nullable=True),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_library_audit_run'))
+    )
+    op.create_index(op.f('ix_library_audit_run_rule'), 'library_audit_run', ['rule'], unique=False)
+    op.create_index(op.f('ix_library_audit_run_status'), 'library_audit_run', ['status'], unique=False)
+    op.create_table('ml_settings',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('cpu_embed_enabled', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('video_frame_interval_seconds', sa.Float(), server_default='4', nullable=False),
+    sa.Column('video_max_frames', sa.Integer(), server_default='64', nullable=False),
+    sa.Column('head_min_positives', sa.Integer(), server_default='8', nullable=False),
+    sa.Column('head_auto_apply_precision', sa.Float(), server_default='0.97', nullable=False),
+    sa.Column('head_auto_apply_enabled', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('head_auto_apply_min_positives', sa.Integer(), server_default='30', nullable=False),
+    sa.Column('ccip_match_threshold', sa.Float(), server_default='0.85', nullable=False),
+    sa.Column('ccip_auto_apply_enabled', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('ccip_auto_apply_threshold', sa.Float(), server_default='0.92', nullable=False),
+    sa.Column('presentation_auto_apply_enabled', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('presentation_auto_apply_threshold', sa.Float(), server_default=sa.text('0.90'), nullable=False),
+    sa.Column('presentation_conflict_threshold', sa.Float(), server_default=sa.text('0.50'), nullable=False),
+    sa.Column('process_auto_apply_enabled', sa.Boolean(), server_default='false', nullable=False),
+    sa.Column('process_auto_apply_threshold', sa.Float(), server_default='0.90', nullable=False),
+    sa.Column('process_conflict_threshold', sa.Float(), server_default='0.50', nullable=False),
+    sa.Column('embedder_model_version', sa.String(length=128), server_default='siglip2-so400m-patch16-512', nullable=False),
+    sa.Column('embedder_model_name', sa.String(length=128), server_default='google/siglip2-so400m-patch16-512', nullable=False),
+    sa.Column('detector_person_enabled', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('detector_person_weights', sa.String(length=512), server_default='yolo11n.pt', nullable=False),
+    sa.Column('detector_person_conf', sa.Float(), server_default=sa.text('0.35'), nullable=False),
+    sa.Column('detector_anatomy_enabled', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('detector_anatomy_weights', sa.String(length=512), server_default='https://github.com/aperveyev/booru_yolo/raw/main/models/yolov11m_aa22.pt', nullable=False),
+    sa.Column('detector_anatomy_conf', sa.Float(), server_default=sa.text('0.30'), nullable=False),
+    sa.Column('detector_panel_enabled', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('detector_panel_weights', sa.String(length=512), server_default='mosesb/best-comic-panel-detection::best.pt', nullable=False),
+    sa.Column('detector_panel_conf', sa.Float(), server_default=sa.text('0.30'), nullable=False),
+    sa.Column('detector_max_figures', sa.Integer(), server_default='8', nullable=False),
+    sa.Column('detector_max_components', sa.Integer(), server_default='8', nullable=False),
+    sa.Column('detector_max_panels', sa.Integer(), server_default='8', nullable=False),
+    sa.Column('detector_max_regions', sa.Integer(), server_default='128', nullable=False),
+    sa.Column('detector_dedupe_iou', sa.Float(), server_default=sa.text('0.85'), nullable=False),
+    sa.Column('ccip_ref_signature', sa.String(length=128), nullable=True),
+    sa.Column('ccip_prototype_cap', sa.Integer(), server_default='64', nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.CheckConstraint('id = 1', name=op.f('ck_ml_settings_singleton')),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_ml_settings'))
+    )
+    op.create_table('tag',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('name', sa.String(length=255), nullable=False),
+    sa.Column('kind', sa.Enum('artist', 'character', 'fandom', 'general', 'series', 'archive', 'post', name='tag_kind'), server_default='general', nullable=False),
+    sa.Column('fandom_id', sa.Integer(), nullable=True),
+    sa.Column('is_system', sa.Boolean(), server_default=sa.text('false'), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.CheckConstraint("(fandom_id IS NULL) OR (kind = 'character')", name=op.f('ck_tag_fandom_requires_character')),
+    sa.ForeignKeyConstraint(['fandom_id'], ['tag.id'], name=op.f('fk_tag_fandom_id_tag'), ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_tag'))
+    )
+    op.create_index(op.f('ix_tag_fandom_id'), 'tag', ['fandom_id'], unique=False)
+    op.create_index('uq_tag_name_kind_fandom', 'tag', ['name', 'kind', sa.literal_column('COALESCE(fandom_id, 0)')], unique=True)
+    op.create_table('task_run',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('celery_task_id', sa.String(length=64), nullable=False),
+    sa.Column('queue', sa.String(length=32), nullable=False),
+    sa.Column('task_name', sa.String(length=128), nullable=False),
+    sa.Column('target_id', sa.Integer(), nullable=True),
+    sa.Column('started_at', sa.DateTime(timezone=True), nullable=False),
+    sa.Column('finished_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('duration_ms', sa.Integer(), nullable=True),
+    sa.Column('status', sa.String(length=16), server_default='running', nullable=False),
+    sa.Column('error_type', sa.String(length=128), nullable=True),
+    sa.Column('error_message', sa.Text(), nullable=True),
+    sa.Column('retry_count', sa.Integer(), nullable=True),
+    sa.Column('worker_hostname', sa.String(length=128), nullable=True),
+    sa.Column('args_summary', sa.String(length=255), nullable=True),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_task_run'))
+    )
+    op.create_index(op.f('ix_task_run_celery_task_id'), 'task_run', ['celery_task_id'], unique=False)
+    op.create_index(op.f('ix_task_run_finished_at'), 'task_run', ['finished_at'], unique=False)
+    op.create_index('ix_task_run_name_started', 'task_run', ['task_name', sa.literal_column('started_at DESC')], unique=False)
+    op.create_index('ix_task_run_queue_started', 'task_run', ['queue', sa.literal_column('started_at DESC')], unique=False)
+    op.create_index(op.f('ix_task_run_started_at'), 'task_run', ['started_at'], unique=False)
+    op.create_index('ix_task_run_status_started', 'task_run', ['status', sa.literal_column('started_at DESC')], unique=False)
+    op.create_table('artist_visit',
+    sa.Column('artist_id', sa.Integer(), nullable=False),
+    sa.Column('last_viewed_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['artist_id'], ['artist.id'], name=op.f('fk_artist_visit_artist_id_artist'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('artist_id', name=op.f('pk_artist_visit'))
+    )
+    op.create_table('ccip_prototype_state',
+    sa.Column('tag_id', sa.Integer(), nullable=False),
+    sa.Column('fingerprint', sa.String(length=64), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['tag_id'], ['tag.id'], name=op.f('fk_ccip_prototype_state_tag_id_tag'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('tag_id', name=op.f('pk_ccip_prototype_state'))
+    )
+    op.create_table('head_metric',
+    sa.Column('tag_id', sa.Integer(), nullable=False),
+    sa.Column('n_misfires', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('n_underfires', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['tag_id'], ['tag.id'], name=op.f('fk_head_metric_tag_id_tag'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('tag_id', name=op.f('pk_head_metric'))
+    )
+    op.create_table('head_metrics_snapshot',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('tag_id', sa.Integer(), nullable=True),
+    sa.Column('name', sa.String(length=255), nullable=False),
+    sa.Column('snapshot_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('n_auto_applied', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('n_misfires', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('n_underfires', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('ap', sa.Float(), nullable=True),
+    sa.Column('precision_cv', sa.Float(), nullable=True),
+    sa.Column('recall', sa.Float(), nullable=True),
+    sa.Column('n_pos', sa.Integer(), nullable=True),
+    sa.ForeignKeyConstraint(['tag_id'], ['tag.id'], name=op.f('fk_head_metrics_snapshot_tag_id_tag'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_head_metrics_snapshot'))
+    )
+    op.create_index(op.f('ix_head_metrics_snapshot_snapshot_at'), 'head_metrics_snapshot', ['snapshot_at'], unique=False)
+    op.create_index(op.f('ix_head_metrics_snapshot_tag_id'), 'head_metrics_snapshot', ['tag_id'], unique=False)
+    op.create_table('source',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('artist_id', sa.Integer(), nullable=False),
+    sa.Column('platform', sa.String(length=64), nullable=False),
+    sa.Column('url', sa.Text(), nullable=False),
+    sa.Column('enabled', sa.Boolean(), server_default='true', nullable=False),
+    sa.Column('config_overrides', sa.JSON(), nullable=True),
+    sa.Column('last_checked_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('last_error', sa.Text(), nullable=True),
+    sa.Column('error_type', sa.String(length=32), nullable=True),
+    sa.Column('check_interval_override', sa.Integer(), nullable=True),
+    sa.Column('consecutive_failures', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('backfill_runs_remaining', sa.Integer(), server_default='0', nullable=False),
+    sa.ForeignKeyConstraint(['artist_id'], ['artist.id'], name=op.f('fk_source_artist_id_artist'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_source')),
+    sa.UniqueConstraint('artist_id', 'platform', 'url', name='uq_source_artist_platform_url')
+    )
+    op.create_index(op.f('ix_source_artist_id'), 'source', ['artist_id'], unique=False)
+    op.create_index(op.f('ix_source_error_type'), 'source', ['error_type'], unique=False)
+    op.create_table('tag_alias',
+    sa.Column('alias_string', sa.String(length=255), nullable=False),
+    sa.Column('alias_category', sa.String(length=32), nullable=False),
+    sa.Column('canonical_tag_id', sa.Integer(), nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['canonical_tag_id'], ['tag.id'], name=op.f('fk_tag_alias_canonical_tag_id_tag'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('alias_string', 'alias_category', name=op.f('pk_tag_alias'))
+    )
+    op.create_index('ix_tag_alias_canonical', 'tag_alias', ['canonical_tag_id'], unique=False)
+    op.create_table('tag_head',
+    sa.Column('tag_id', sa.Integer(), nullable=False),
+    sa.Column('embedding_version', sa.String(length=128), nullable=False),
+    sa.Column('weights', pgvector.sqlalchemy.vector.VECTOR(dim=1152), nullable=False),
+    sa.Column('bias', sa.Float(), nullable=False),
+    sa.Column('suggest_threshold', sa.Float(), nullable=False),
+    sa.Column('auto_apply_threshold', sa.Float(), nullable=True),
+    sa.Column('n_pos', sa.Integer(), nullable=False),
+    sa.Column('n_neg', sa.Integer(), nullable=False),
+    sa.Column('ap', sa.Float(), nullable=False),
+    sa.Column('precision_cv', sa.Float(), nullable=False),
+    sa.Column('recall', sa.Float(), nullable=False),
+    sa.Column('trained_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('train_fingerprint', sa.String(length=128), nullable=True),
+    sa.Column('metrics', postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+    sa.ForeignKeyConstraint(['tag_id'], ['tag.id'], name=op.f('fk_tag_head_tag_id_tag'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('tag_id', name=op.f('pk_tag_head'))
+    )
+    op.create_table('patreon_failed_media',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('source_id', sa.Integer(), nullable=False),
+    sa.Column('filehash', sa.String(length=128), nullable=False),
+    sa.Column('attempts', sa.Integer(), server_default='1', nullable=False),
+    sa.Column('last_error', sa.Text(), nullable=True),
+    sa.Column('first_failed_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('last_failed_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['source_id'], ['source.id'], name=op.f('fk_patreon_failed_media_source_id_source'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_patreon_failed_media')),
+    sa.UniqueConstraint('source_id', 'filehash', name='uq_patreon_failed_media_source_id')
+    )
+    op.create_index(op.f('ix_patreon_failed_media_source_id'), 'patreon_failed_media', ['source_id'], unique=False)
+    op.create_table('patreon_seen_media',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('source_id', sa.Integer(), nullable=False),
+    sa.Column('filehash', sa.String(length=128), nullable=False),
+    sa.Column('post_id', sa.String(length=64), nullable=True),
+    sa.Column('seen_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['source_id'], ['source.id'], name=op.f('fk_patreon_seen_media_source_id_source'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_patreon_seen_media')),
+    sa.UniqueConstraint('source_id', 'filehash', name='uq_patreon_seen_media_source_id')
+    )
+    op.create_index(op.f('ix_patreon_seen_media_source_id'), 'patreon_seen_media', ['source_id'], unique=False)
+    op.create_table('pixiv_failed_media',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('source_id', sa.Integer(), nullable=False),
+    sa.Column('filehash', sa.String(length=128), nullable=False),
+    sa.Column('attempts', sa.Integer(), server_default='1', nullable=False),
+    sa.Column('last_error', sa.Text(), nullable=True),
+    sa.Column('first_failed_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('last_failed_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['source_id'], ['source.id'], name=op.f('fk_pixiv_failed_media_source_id_source'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_pixiv_failed_media')),
+    sa.UniqueConstraint('source_id', 'filehash', name='uq_pixiv_failed_media_source_id')
+    )
+    op.create_index(op.f('ix_pixiv_failed_media_source_id'), 'pixiv_failed_media', ['source_id'], unique=False)
+    op.create_table('pixiv_seen_media',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('source_id', sa.Integer(), nullable=False),
+    sa.Column('filehash', sa.String(length=128), nullable=False),
+    sa.Column('post_id', sa.String(length=64), nullable=True),
+    sa.Column('seen_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['source_id'], ['source.id'], name=op.f('fk_pixiv_seen_media_source_id_source'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_pixiv_seen_media')),
+    sa.UniqueConstraint('source_id', 'filehash', name='uq_pixiv_seen_media_source_id')
+    )
+    op.create_index(op.f('ix_pixiv_seen_media_source_id'), 'pixiv_seen_media', ['source_id'], unique=False)
+    op.create_table('post',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('source_id', sa.Integer(), nullable=True),
+    sa.Column('artist_id', sa.Integer(), nullable=False),
+    sa.Column('external_post_id', sa.String(length=128), nullable=False),
+    sa.Column('post_url', sa.Text(), nullable=True),
+    sa.Column('post_title', sa.Text(), nullable=True),
+    sa.Column('post_date', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('raw_metadata', sa.JSON(), nullable=True),
+    sa.Column('description', sa.Text(), nullable=True),
+    sa.Column('attachment_count', sa.Integer(), nullable=True),
+    sa.Column('post_title_translated', sa.Text(), nullable=True),
+    sa.Column('description_translated', sa.Text(), nullable=True),
+    sa.Column('translated_source_lang', sa.String(length=8), nullable=True),
+    sa.Column('translation_engine_version', sa.String(length=128), nullable=True),
+    sa.Column('translated_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('translation_override', sa.String(length=16), server_default='auto', nullable=False),
+    sa.Column('downloaded_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.CheckConstraint("translation_override IN ('auto', 'force', 'original')", name=op.f('ck_post_translation_override')),
+    sa.ForeignKeyConstraint(['artist_id'], ['artist.id'], name=op.f('fk_post_artist_id_artist'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['source_id'], ['source.id'], name=op.f('fk_post_source_id_source'), ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_post')),
+    sa.UniqueConstraint('source_id', 'external_post_id', name='uq_post_source_external_id')
+    )
+    op.create_index(op.f('ix_post_artist_id'), 'post', ['artist_id'], unique=False)
+    op.create_index(op.f('ix_post_source_id'), 'post', ['source_id'], unique=False)
+    op.create_index('uq_post_artist_external_id_null_source', 'post', ['artist_id', 'external_post_id'], unique=True, postgresql_where=sa.text('source_id IS NULL'))
+    op.create_table('subscribestar_failed_media',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('source_id', sa.Integer(), nullable=False),
+    sa.Column('filehash', sa.String(length=128), nullable=False),
+    sa.Column('attempts', sa.Integer(), server_default='1', nullable=False),
+    sa.Column('last_error', sa.Text(), nullable=True),
+    sa.Column('first_failed_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('last_failed_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['source_id'], ['source.id'], name=op.f('fk_subscribestar_failed_media_source_id_source'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_subscribestar_failed_media')),
+    sa.UniqueConstraint('source_id', 'filehash', name='uq_subscribestar_failed_media_source_id')
+    )
+    op.create_index(op.f('ix_subscribestar_failed_media_source_id'), 'subscribestar_failed_media', ['source_id'], unique=False)
+    op.create_table('subscribestar_seen_media',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('source_id', sa.Integer(), nullable=False),
+    sa.Column('filehash', sa.String(length=128), nullable=False),
+    sa.Column('post_id', sa.String(length=64), nullable=True),
+    sa.Column('seen_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['source_id'], ['source.id'], name=op.f('fk_subscribestar_seen_media_source_id_source'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_subscribestar_seen_media')),
+    sa.UniqueConstraint('source_id', 'filehash', name='uq_subscribestar_seen_media_source_id')
+    )
+    op.create_index(op.f('ix_subscribestar_seen_media_source_id'), 'subscribestar_seen_media', ['source_id'], unique=False)
+    op.create_table('download_event',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('source_id', sa.Integer(), nullable=False),
+    sa.Column('post_id', sa.Integer(), nullable=True),
+    sa.Column('status', sa.String(length=32), nullable=False),
+    sa.Column('started_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('finished_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('bytes_downloaded', sa.BigInteger(), server_default='0', nullable=False),
+    sa.Column('files_count', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('error', sa.Text(), nullable=True),
+    sa.Column('metadata', postgresql.JSONB(astext_type=sa.Text()), server_default=sa.text("'{}'::jsonb"), nullable=False),
+    sa.ForeignKeyConstraint(['post_id'], ['post.id'], name=op.f('fk_download_event_post_id_post'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['source_id'], ['source.id'], name=op.f('fk_download_event_source_id_source'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_download_event'))
+    )
+    op.create_index(op.f('ix_download_event_post_id'), 'download_event', ['post_id'], unique=False)
+    op.create_index(op.f('ix_download_event_source_id'), 'download_event', ['source_id'], unique=False)
+    op.create_table('image_record',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('path', sa.Text(), nullable=False),
+    sa.Column('sha256', sa.String(length=64), nullable=False),
+    sa.Column('phash', sa.String(length=32), nullable=True),
+    sa.Column('size_bytes', sa.BigInteger(), nullable=False),
+    sa.Column('mime', sa.String(length=64), nullable=False),
+    sa.Column('width', sa.Integer(), nullable=True),
+    sa.Column('height', sa.Integer(), nullable=True),
+    sa.Column('duration_seconds', sa.Float(), nullable=True),
+    sa.Column('integrity_status', sa.String(length=24), server_default='unknown', nullable=False),
+    sa.Column('thumbnail_path', sa.Text(), nullable=True),
+    sa.Column('source_url', sa.Text(), nullable=True),
+    sa.Column('source_filehash', sa.String(length=32), nullable=True),
+    sa.Column('origin', sa.Enum('downloaded', 'imported_filesystem', 'uploaded', name='origin_enum'), nullable=False),
+    sa.Column('primary_post_id', sa.Integer(), nullable=True),
+    sa.Column('artist_id', sa.Integer(), nullable=True),
+    sa.Column('siglip_embedding', pgvector.sqlalchemy.vector.VECTOR(dim=1152), nullable=True),
+    sa.Column('siglip_model_version', sa.String(length=128), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('effective_date', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('earliest_post_date', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['artist_id'], ['artist.id'], name='fk_image_record_artist_id', ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['primary_post_id'], ['post.id'], name=op.f('fk_image_record_primary_post_id_post'), ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_image_record')),
+    sa.UniqueConstraint('path', name=op.f('uq_image_record_path')),
+    sa.UniqueConstraint('sha256', name='uq_image_record_sha256')
+    )
+    op.create_index(op.f('ix_image_record_artist_id'), 'image_record', ['artist_id'], unique=False)
+    op.create_index('ix_image_record_earliest_post_date', 'image_record', [sa.literal_column('earliest_post_date DESC'), sa.literal_column('id DESC')], unique=False)
+    op.create_index('ix_image_record_effective_date', 'image_record', [sa.literal_column('effective_date DESC'), sa.literal_column('id DESC')], unique=False)
+    op.create_index(op.f('ix_image_record_integrity_status'), 'image_record', ['integrity_status'], unique=False)
+    op.create_index(op.f('ix_image_record_phash'), 'image_record', ['phash'], unique=False)
+    op.create_index(op.f('ix_image_record_primary_post_id'), 'image_record', ['primary_post_id'], unique=False)
+    op.create_index('ix_image_record_siglip_hnsw', 'image_record', ['siglip_embedding'], unique=False, postgresql_using='hnsw', postgresql_ops={'siglip_embedding': 'vector_cosine_ops'})
+    op.create_index(op.f('ix_image_record_source_filehash'), 'image_record', ['source_filehash'], unique=False)
+    op.create_table('post_attachment',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('post_id', sa.Integer(), nullable=True),
+    sa.Column('artist_id', sa.Integer(), nullable=True),
+    sa.Column('sha256', sa.String(length=64), nullable=False),
+    sa.Column('path', sa.Text(), nullable=False),
+    sa.Column('original_filename', sa.Text(), nullable=False),
+    sa.Column('ext', sa.String(length=32), nullable=False),
+    sa.Column('mime', sa.String(length=128), nullable=True),
+    sa.Column('size_bytes', sa.BigInteger(), nullable=False),
+    sa.Column('captured_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['artist_id'], ['artist.id'], name=op.f('fk_post_attachment_artist_id_artist'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['post_id'], ['post.id'], name=op.f('fk_post_attachment_post_id_post'), ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_post_attachment'))
+    )
+    op.create_index(op.f('ix_post_attachment_artist_id'), 'post_attachment', ['artist_id'], unique=False)
+    op.create_index(op.f('ix_post_attachment_post_id'), 'post_attachment', ['post_id'], unique=False)
+    op.create_index(op.f('ix_post_attachment_sha256'), 'post_attachment', ['sha256'], unique=False)
+    op.create_index('uq_post_attachment_null_post_sha', 'post_attachment', ['sha256'], unique=True, postgresql_where=sa.text('post_id IS NULL'))
+    op.create_index('uq_post_attachment_post_sha', 'post_attachment', ['post_id', 'sha256'], unique=True, postgresql_where=sa.text('post_id IS NOT NULL'))
+    op.create_table('series_suggestion',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('post_id', sa.Integer(), nullable=False),
+    sa.Column('series_tag_id', sa.Integer(), nullable=False),
+    sa.Column('score', sa.Float(), nullable=False),
+    sa.Column('signals', sa.JSON(), nullable=True),
+    sa.Column('status', sa.String(length=16), server_default='pending', nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['post_id'], ['post.id'], name=op.f('fk_series_suggestion_post_id_post'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['series_tag_id'], ['tag.id'], name=op.f('fk_series_suggestion_series_tag_id_tag'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_series_suggestion')),
+    sa.UniqueConstraint('post_id', 'series_tag_id', name='uq_series_suggestion_post_series')
+    )
+    op.create_index(op.f('ix_series_suggestion_post_id'), 'series_suggestion', ['post_id'], unique=False)
+    op.create_index(op.f('ix_series_suggestion_series_tag_id'), 'series_suggestion', ['series_tag_id'], unique=False)
+    op.create_index(op.f('ix_series_suggestion_status'), 'series_suggestion', ['status'], unique=False)
+    op.create_table('external_link',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('post_id', sa.Integer(), nullable=False),
+    sa.Column('artist_id', sa.Integer(), nullable=True),
+    sa.Column('host', sa.String(length=16), nullable=False),
+    sa.Column('url', sa.Text(), nullable=False),
+    sa.Column('label', sa.Text(), nullable=True),
+    sa.Column('status', sa.String(length=16), server_default='pending', nullable=False),
+    sa.Column('attempts', sa.Integer(), server_default=sa.text('0'), nullable=False),
+    sa.Column('last_error', sa.Text(), nullable=True),
+    sa.Column('attachment_id', sa.Integer(), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('completed_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('duration_seconds', sa.Float(), nullable=True),
+    sa.CheckConstraint("host IN ('mega', 'gdrive', 'mediafire', 'dropbox', 'pixeldrain')", name=op.f('ck_external_link_host')),
+    sa.CheckConstraint("status IN ('pending', 'downloading', 'downloaded', 'failed', 'skipped', 'dead')", name=op.f('ck_external_link_status')),
+    sa.ForeignKeyConstraint(['artist_id'], ['artist.id'], name=op.f('fk_external_link_artist_id_artist'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['attachment_id'], ['post_attachment.id'], name=op.f('fk_external_link_attachment_id_post_attachment'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['post_id'], ['post.id'], name=op.f('fk_external_link_post_id_post'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_external_link'))
+    )
+    op.create_index(op.f('ix_external_link_artist_id'), 'external_link', ['artist_id'], unique=False)
+    op.create_index('ix_external_link_attachment_id', 'external_link', ['attachment_id'], unique=False)
+    op.create_index('ix_external_link_status', 'external_link', ['status'], unique=False)
+    op.create_index('uq_external_link_post_url', 'external_link', ['post_id', 'url'], unique=True)
+    op.create_table('gpu_job',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('image_record_id', sa.Integer(), nullable=False),
+    sa.Column('task', sa.String(length=32), nullable=False),
+    sa.Column('status', sa.String(length=16), server_default='pending', nullable=False),
+    sa.Column('lease_token', sa.String(length=64), nullable=True),
+    sa.Column('leased_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('lease_expires_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('attempts', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('error', sa.Text(), nullable=True),
+    sa.Column('triage_status', sa.String(length=16), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['image_record_id'], ['image_record.id'], name=op.f('fk_gpu_job_image_record_id_image_record'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_gpu_job'))
+    )
+    op.create_index(op.f('ix_gpu_job_image_record_id'), 'gpu_job', ['image_record_id'], unique=False)
+    op.create_index('ix_gpu_job_leased_expires', 'gpu_job', ['lease_expires_at'], unique=False, postgresql_where=sa.text("status = 'leased'"))
+    op.create_index('ix_gpu_job_pending', 'gpu_job', ['id'], unique=False, postgresql_where=sa.text("status = 'pending'"))
+    op.create_index(op.f('ix_gpu_job_status'), 'gpu_job', ['status'], unique=False)
+    op.create_table('image_provenance',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('image_record_id', sa.Integer(), nullable=False),
+    sa.Column('post_id', sa.Integer(), nullable=False),
+    sa.Column('source_id', sa.Integer(), nullable=True),
+    sa.Column('from_attachment_id', sa.Integer(), nullable=True),
+    sa.Column('captured_metadata', sa.JSON(), nullable=True),
+    sa.Column('captured_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['from_attachment_id'], ['post_attachment.id'], name='fk_image_provenance_from_attachment', ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['image_record_id'], ['image_record.id'], name=op.f('fk_image_provenance_image_record_id_image_record'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['post_id'], ['post.id'], name=op.f('fk_image_provenance_post_id_post'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['source_id'], ['source.id'], name=op.f('fk_image_provenance_source_id_source'), ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_image_provenance')),
+    sa.UniqueConstraint('image_record_id', 'post_id', name='uq_image_provenance_image_post')
+    )
+    op.create_index(op.f('ix_image_provenance_from_attachment_id'), 'image_provenance', ['from_attachment_id'], unique=False)
+    op.create_index(op.f('ix_image_provenance_image_record_id'), 'image_provenance', ['image_record_id'], unique=False)
+    op.create_index(op.f('ix_image_provenance_post_id'), 'image_provenance', ['post_id'], unique=False)
+    op.create_index(op.f('ix_image_provenance_source_id'), 'image_provenance', ['source_id'], unique=False)
+    op.create_table('image_region',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('image_record_id', sa.Integer(), nullable=False),
+    sa.Column('kind', sa.String(length=16), nullable=False),
+    sa.Column('frame_time', sa.Float(), nullable=True),
+    sa.Column('rx', sa.Float(), nullable=False),
+    sa.Column('ry', sa.Float(), nullable=False),
+    sa.Column('rw', sa.Float(), nullable=False),
+    sa.Column('rh', sa.Float(), nullable=False),
+    sa.Column('score', sa.Float(), nullable=True),
+    sa.Column('detector_version', sa.String(length=64), nullable=True),
+    sa.Column('crop_version', sa.String(length=64), nullable=True),
+    sa.Column('embedding_version', sa.String(length=128), nullable=True),
+    sa.Column('ccip_embedding', pgvector.sqlalchemy.vector.VECTOR(dim=768), nullable=True),
+    sa.Column('siglip_embedding', pgvector.sqlalchemy.vector.VECTOR(dim=1152), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['image_record_id'], ['image_record.id'], name=op.f('fk_image_region_image_record_id_image_record'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_image_region'))
+    )
+    op.create_index(op.f('ix_image_region_image_record_id'), 'image_region', ['image_record_id'], unique=False)
+    op.create_table('image_tag',
+    sa.Column('image_record_id', sa.Integer(), nullable=False),
+    sa.Column('tag_id', sa.Integer(), nullable=False),
+    sa.Column('source', sa.String(length=32), server_default='manual', nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['image_record_id'], ['image_record.id'], name=op.f('fk_image_tag_image_record_id_image_record'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['tag_id'], ['tag.id'], name=op.f('fk_image_tag_tag_id_tag'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('image_record_id', 'tag_id', name=op.f('pk_image_tag'))
+    )
+    op.create_index('ix_image_tag_tag_id', 'image_tag', ['tag_id'], unique=False)
+    op.create_table('import_task',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('batch_id', sa.Integer(), nullable=False),
+    sa.Column('source_path', sa.Text(), nullable=False),
+    sa.Column('task_type', sa.String(length=16), nullable=False),
+    sa.Column('status', sa.String(length=16), server_default='pending', nullable=False),
+    sa.Column('recovery_count', sa.Integer(), server_default='0', nullable=False),
+    sa.Column('refetched', sa.Boolean(), server_default='false', nullable=False),
+    sa.Column('result_image_id', sa.Integer(), nullable=True),
+    sa.Column('error', sa.Text(), nullable=True),
+    sa.Column('size_bytes', sa.BigInteger(), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('started_at', sa.DateTime(timezone=True), nullable=True),
+    sa.Column('finished_at', sa.DateTime(timezone=True), nullable=True),
+    sa.ForeignKeyConstraint(['batch_id'], ['import_batch.id'], name=op.f('fk_import_task_batch_id_import_batch'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['result_image_id'], ['image_record.id'], name=op.f('fk_import_task_result_image_id_image_record'), ondelete='SET NULL'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_import_task'))
+    )
+    op.create_index(op.f('ix_import_task_batch_id'), 'import_task', ['batch_id'], unique=False)
+    op.create_index('ix_import_task_created_at_desc', 'import_task', [sa.literal_column('created_at DESC')], unique=False)
+    op.create_index('ix_import_task_result_image_id', 'import_task', ['result_image_id'], unique=False)
+    op.create_index(op.f('ix_import_task_status'), 'import_task', ['status'], unique=False)
+    op.create_table('presentation_review',
+    sa.Column('image_record_id', sa.Integer(), nullable=False),
+    sa.Column('tag_id', sa.Integer(), nullable=False),
+    sa.Column('conflict_tag_id', sa.Integer(), nullable=True),
+    sa.Column('conflict_score', sa.Float(), nullable=False),
+    sa.Column('mode', sa.String(length=16), server_default='chrome', nullable=False),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('resolved_at', sa.DateTime(timezone=True), nullable=True),
+    sa.ForeignKeyConstraint(['conflict_tag_id'], ['tag.id'], name=op.f('fk_presentation_review_conflict_tag_id_tag'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['image_record_id'], ['image_record.id'], name=op.f('fk_presentation_review_image_record_id_image_record'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['tag_id'], ['tag.id'], name=op.f('fk_presentation_review_tag_id_tag'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('image_record_id', 'tag_id', name=op.f('pk_presentation_review'))
+    )
+    op.create_index('ix_presentation_review_conflict_tag_id', 'presentation_review', ['conflict_tag_id'], unique=False)
+    op.create_index('ix_presentation_review_resolved_at', 'presentation_review', ['resolved_at'], unique=False)
+    op.create_index('ix_presentation_review_tag_id', 'presentation_review', ['tag_id'], unique=False)
+    op.create_table('series_page',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('series_tag_id', sa.Integer(), nullable=False),
+    sa.Column('image_id', sa.Integer(), nullable=False),
+    sa.Column('status', sa.String(length=16), server_default='placed', nullable=False),
+    sa.Column('page_number', sa.Integer(), nullable=True),
+    sa.Column('stated_page', sa.Integer(), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['image_id'], ['image_record.id'], name=op.f('fk_series_page_image_id_image_record'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['series_tag_id'], ['tag.id'], name=op.f('fk_series_page_series_tag_id_tag'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_series_page')),
+    sa.UniqueConstraint('image_id', name='uq_series_page_image')
+    )
+    op.create_index(op.f('ix_series_page_series_tag_id'), 'series_page', ['series_tag_id'], unique=False)
+    op.create_table('tag_positive_confirmation',
+    sa.Column('image_record_id', sa.Integer(), nullable=False),
+    sa.Column('tag_id', sa.Integer(), nullable=False),
+    sa.Column('confirmed_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['image_record_id'], ['image_record.id'], name=op.f('fk_tag_positive_confirmation_image_record_id_image_record'), ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['tag_id'], ['tag.id'], name=op.f('fk_tag_positive_confirmation_tag_id_tag'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('image_record_id', 'tag_id', name=op.f('pk_tag_positive_confirmation'))
+    )
+    op.create_index(op.f('ix_tag_positive_confirmation_tag_id'), 'tag_positive_confirmation', ['tag_id'], unique=False)
+    op.create_table('tag_suggestion_rejection',
+    sa.Column('image_record_id', sa.Integer(), nullable=False),
+    sa.Column('tag_id', sa.Integer(), nullable=False),
+    sa.Column('rejected_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['image_record_id'], ['image_record.id'], name='fk_tsr_image_record_id_image_record', ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['tag_id'], ['tag.id'], name='fk_tsr_tag_id_tag', ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('image_record_id', 'tag_id', name=op.f('pk_tag_suggestion_rejection'))
+    )
+    op.create_index('ix_tag_suggestion_rejection_tag', 'tag_suggestion_rejection', ['tag_id'], unique=False)
+    op.create_table('character_prototype',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('tag_id', sa.Integer(), nullable=False),
+    sa.Column('ccip_embedding', pgvector.sqlalchemy.vector.VECTOR(dim=768), nullable=False),
+    sa.Column('region_id', sa.Integer(), nullable=True),
+    sa.ForeignKeyConstraint(['region_id'], ['image_region.id'], name=op.f('fk_character_prototype_region_id_image_region'), ondelete='SET NULL'),
+    sa.ForeignKeyConstraint(['tag_id'], ['tag.id'], name=op.f('fk_character_prototype_tag_id_tag'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_character_prototype'))
+    )
+    op.create_index(op.f('ix_character_prototype_region_id'), 'character_prototype', ['region_id'], unique=False)
+    op.create_index(op.f('ix_character_prototype_tag_id'), 'character_prototype', ['tag_id'], unique=False)
+    op.create_table('series_chapter',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('series_tag_id', sa.Integer(), nullable=False),
+    sa.Column('anchor_page_id', sa.Integer(), nullable=False),
+    sa.Column('title', sa.Text(), nullable=True),
+    sa.Column('stated_part', sa.Integer(), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
+    sa.ForeignKeyConstraint(['anchor_page_id'], ['series_page.id'], name='fk_series_chapter_anchor_page', ondelete='CASCADE'),
+    sa.ForeignKeyConstraint(['series_tag_id'], ['tag.id'], name=op.f('fk_series_chapter_series_tag_id_tag'), ondelete='CASCADE'),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_series_chapter')),
+    sa.UniqueConstraint('anchor_page_id', name='uq_series_chapter_anchor_page')
+    )
+    op.create_index(op.f('ix_series_chapter_series_tag_id'), 'series_chapter', ['series_tag_id'], unique=False)
+
+    # The singleton settings rows. NOT schema — see the note above; the app
+    # reads these with scalar_one() and never creates them, so a fresh
+    # install without these two rows raises NoResultFound on first use.
+    # From 0002 and 0003.
+    op.execute("INSERT INTO import_settings (id) VALUES (1)")
+    op.execute("INSERT INTO ml_settings (id) VALUES (1)")
+
+    # The three hygiene system tags, from 0075. These are PRODUCT data, not
+    # operator configuration — 0075's own docstring says so: "the fix keys on
+    # SYSTEM tags the product ships". The presentation and process auto-apply
+    # sweeps look them up with scalar_one(), so without these rows those
+    # features raise NoResultFound rather than degrading.
+    #
+    # 0075 adopted an existing same-name general tag before inserting, because
+    # an operator might already have tagged `wip` by hand. That cannot happen
+    # on the empty database this file runs against, but the guard is kept: it
+    # costs nothing and makes the statement safe to re-run.
+    for _name in ("wip", "banner", "editor screenshot"):
+        op.execute(
+            sa.text(
+                "INSERT INTO tag (name, kind, is_system) "
+                "SELECT :name, 'general', true WHERE NOT EXISTS ("
+                "  SELECT 1 FROM tag WHERE lower(name) = lower(:name)"
+                ")"
+            ).bindparams(name=_name)
+        )
+
+
+def downgrade() -> None:
+    """Deliberately not implemented.
+
+    Downgrading a baseline means dropping every table in the database. That is
+    not a migration, and offering it as one invites someone to run it. Restore
+    from a backup instead.
+    """
+    raise NotImplementedError(
+        "0089 is the baseline; there is nothing below it. Restore from a backup."
+    )

alembic/versions/0090_service_seen.py

@@ -0,0 +1,64 @@
+"""service_seen — the learned roster that makes a stopped part observable.
+
+Milestone 365. Nothing in FabledCurator knew what was SUPPOSED to be running:
+`celery inspect` reports the workers that answer, so a dead worker was a
+shorter list rather than a red light, and the only surface that could tell an
+operator otherwise was Portainer. This table is the memory that turns an
+absence into something the app can see.
+
+Keyed on the queue set for a celery role and on agent_id for the GPU agent —
+NOT on the celery worker name, which here is `celery@<container id>` and is
+minted fresh on every deploy. See the model docstring for why that choice is
+the whole design.
+
+## First migration on the collapsed baseline
+
+0089 is the single generated baseline that replaced revisions 0001..0089
+(milestone 328). This is the first revision written on top of it, so it is
+also the first evidence that the chain steps forward from the collapse rather
+than merely reproducing the schema — which nothing had demonstrated yet.
+
+An existing install is at 0089 because it ran the real 0089; a fresh one is at
+0089 because it ran the baseline. Both arrive here identically, which was the
+property the collapse was designed around.
+
+Revision ID: 0090
+Revises: 0089
+Create Date: 2026-09-02
+
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "0090"
+down_revision: Union[str, None] = "0089"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "service_seen",
+        sa.Column("key", sa.String(length=128), nullable=False),
+        sa.Column("kind", sa.String(length=16), nullable=False),
+        sa.Column("display_name", sa.String(length=64), nullable=False),
+        sa.Column(
+            "first_seen_at", sa.DateTime(timezone=True),
+            server_default=sa.text("now()"), nullable=False,
+        ),
+        sa.Column(
+            "last_seen_at", sa.DateTime(timezone=True),
+            server_default=sa.text("now()"), nullable=False,
+        ),
+        sa.Column("details", sa.JSON(), nullable=False),
+        sa.PrimaryKeyConstraint("key", name=op.f("pk_service_seen")),
+    )
+    # No secondary indexes, deliberately: one row per moving part means every
+    # read is a handful of rows and an index would be write cost buying
+    # nothing (#3301 removed seven of exactly that shape).
+
+
+def downgrade() -> None:
+    op.drop_table("service_seen")

backend/app/__init__.py

@@ -34,6 +34,23 @@ def create_app() -> Quart:
     app = Quart(__name__)
     app.secret_key = cfg.secret_key
 
+    # Stream files in 4 MiB chunks instead of Quart's 8 KiB default. The image
+    # library lives on a CIFS/SMB share (mounted rsize=4 MiB), so 8 KiB reads
+    # meant ~19k network round-trips for one large original — 30–58s downloads
+    # that starved both the GPU agent and the browser (operator-flagged
+    # 2026-07-01). 4 MiB matches the mount's read size → one round-trip per read,
+    # ~500× fewer. buffer_size is the MAX read, so small thumbnails still read in
+    # a single gulp, and Range/mime/ETag/conditional handling lives on Response,
+    # so this keeps all of it. Guarded so a future Quart-internal change can't
+    # break boot — worst case we fall back to the slow default.
+    try:
+        from quart.wrappers.response import FileBody
+        FileBody.buffer_size = 4 * 1024 * 1024
+    except Exception:
+        logging.getLogger(__name__).warning(
+            "could not raise FileBody.buffer_size — file serving stays on 8 KiB chunks"
+        )
+
     for bp in all_blueprints():
         app.register_blueprint(bp)
     # Registered last so /api/* routes win over the SPA catch-all.

backend/app/api/__init__.py

@@ -16,7 +16,6 @@ api_bp.add_url_rule("/health", view_func=health.get_health, methods=["GET"])
 def all_blueprints() -> list[Blueprint]:
     from .admin import admin_bp
     from .aliases import aliases_bp
-    from .allowlist import allowlist_bp
     from .artist import artist_bp
     from .artists import artists_bp
     from .attachments import attachments_bp
@@ -39,7 +38,7 @@ def all_blueprints() -> list[Blueprint]:
     from .suggestions import suggestions_bp
     from .system_activity import system_activity_bp
     from .system_backup import system_backup_bp
-    from .tag_eval import tag_eval_bp
+    from .system_health import system_health_bp
     from .tags import tags_bp
     from .thumbnails import thumbnails_bp
     return [
@@ -53,14 +52,13 @@ def all_blueprints() -> list[Blueprint]:
         showcase_bp,
         settings_bp,
         system_activity_bp,
+        system_health_bp,
         system_backup_bp,
         admin_bp,
         cleanup_bp,
         import_admin_bp,
         suggestions_bp,
-        allowlist_bp,
         aliases_bp,
-        tag_eval_bp,
         heads_bp,
         gpu_bp,
         ccip_bp,

backend/app/api/admin.py

@@ -1,13 +1,13 @@
 """FC-3k: /api/admin — destructive admin actions.
 
-Five action surfaces:
+Action surfaces:
   POST   /api/admin/artists/<slug>/cascade-delete  (Tier C)
   POST   /api/admin/images/bulk-delete             (Tier C)
   DELETE /api/admin/tags/<int:tag_id>              (Tier B)
   POST   /api/admin/tags/<int:dest_id>/merge       (Tier B)
   POST   /api/admin/tags/prune-unused              (Tier A)
   POST   /api/admin/posts/prune-bare               (Tier A)
-  POST   /api/admin/tags/purge-legacy              (Tier A)
+  POST   /api/admin/posts/refetch-external         (Tier A)
   GET    /api/admin/tags/<int:tag_id>/usage-count  (helper)
 
 Tier-C ops take a dry_run body flag (returns projection inline,
@@ -23,7 +23,7 @@ from quart import Blueprint, jsonify, request
 from sqlalchemy import select, text
 
 from ..extensions import get_session
-from ..models import Artist
+from ..models import Artist, Post
 from ..services.cleanup_service import project_artist_cascade, project_bulk_image_delete
 from ._responses import error_response as _bad
 
@@ -156,6 +156,10 @@ async def tag_delete(tag_id: int):
             )
         except LookupError:
             return _bad("not_found", status=404)
+        except ValueError as exc:
+            # System tags (#128) — the training-hygiene machinery keys on
+            # these rows.
+            return _bad("system_tag", detail=str(exc))
     return jsonify(result)
 
 
@@ -277,31 +281,86 @@ async def posts_reconcile_duplicates():
     return await _run_dry_run_op(reconcile_duplicate_posts, source_id=source_id)
 
 
-@admin_bp.route("/tags/purge-legacy", methods=["POST"])
-async def tags_purge_legacy():
-    """Tier-A: delete legacy IR-migration tags — archive/post/artist
-    kinds (e.g. `BlenderKnight:Hannah_BJ_Loops`) PLUS general tags with
-    a legacy name prefix (`source:*`, from IR's source kind that fell
-    back to general). dry-run preview returns per-kind + per-prefix
-    counts + a sample so the UI shows exactly what'll go before the
-    operator confirms with dry_run=false."""
-    from ..services.cleanup_service import purge_legacy_tags
+@admin_bp.route("/posts/refetch-external", methods=["POST"])
+async def posts_refetch_external():
+    """Surgical re-fetch of a post's external file-host links (operator
+    2026-07-03): the normal cadence never re-walks deep back-catalogue posts,
+    so a deleted external file only comes back by resetting its ExternalLink
+    row(s) — this endpoint does that per post and dispatches the fetches.
+    Sha-dedupe discards payload files that still exist, so only what's
+    missing lands. Body: {external_post_id: str, source_id?: int (to
+    disambiguate the same external id across sources)}."""
+    from ..services.external_links import refetch_links_for_post
 
-    return await _run_dry_run_op(purge_legacy_tags)
+    body = await request.get_json(silent=True) or {}
+    ext_id = str(body.get("external_post_id") or "").strip()
+    if not ext_id:
+        return _bad("missing_external_post_id",
+                    detail="external_post_id is required")
+    raw_source = body.get("source_id")
+    try:
+        source_id = int(raw_source) if raw_source is not None else None
+    except (TypeError, ValueError):
+        return _bad("invalid_source_id", detail="source_id must be an integer")
+
+    async with get_session() as session:
+        stmt = select(Post.id).where(Post.external_post_id == ext_id)
+        if source_id is not None:
+            stmt = stmt.where(Post.source_id == source_id)
+        post_ids = (await session.execute(stmt)).scalars().all()
+        if not post_ids:
+            return _bad("post_not_found", status=404,
+                        detail=f"no post with external_post_id {ext_id!r}")
+        results = {}
+        for pid in post_ids:
+            results[str(pid)] = await session.run_sync(
+                lambda s, p=pid: refetch_links_for_post(s, p)
+            )
+    return jsonify({"posts": results})
+
+
+def _reset_content_confirm_token(projection: dict) -> str:
+    """Stable 8-hex token derived from the live counts (mirrors the Tier-C
+    bulk-delete token): it changes whenever the data changes, so the apply can
+    only ever run against numbers the operator just previewed."""
+    canon = f"reset-content:{projection.get('count')}:{projection.get('applications')}"
+    return hashlib.sha256(canon.encode("utf-8")).hexdigest()[:8]
 
 
 @admin_bp.route("/tags/reset-content", methods=["POST"])
 async def tags_reset_content():
-    """Tier-A: delete ALL general + character tags (the Camie-suggestable
-    content vocabulary) so the operator can re-tag from scratch via
-    auto-suggest. fandom + series tags + series_page ordering are preserved,
-    and image_prediction rows are untouched so suggestions repopulate.
-    dry-run preview returns per-kind counts + applications + a sample so the
-    UI shows exactly what'll go before the operator confirms (dry_run=false).
-    Irreversible except via DB backup restore."""
+    """Full-instance reset of the CONTENT vocabulary: deletes ALL general +
+    character tags and their image applications — INCLUDING the examples the
+    tagging heads learned from. Suggestions do NOT repopulate on their own
+    (the Camie predictions that once did are long retired): the operator
+    re-tags from scratch and the heads retrain from the new signal. fandom +
+    series tags + series_page ordering are preserved.
+
+    Deliberately Tier-C-gated despite the Tier-A shape (operator 2026-07-02:
+    the full reset stays, but behind extra steps): dry_run returns the
+    projection + a `confirm` token derived from the live counts; the apply
+    must echo that token back or it is rejected."""
     from ..services.cleanup_service import reset_content_tagging
 
-    return await _run_dry_run_op(reset_content_tagging)
+    body = await request.get_json(silent=True) or {}
+    dry_run = bool(body.get("dry_run", False))
+    async with get_session() as session:
+        projection = await session.run_sync(
+            lambda s: reset_content_tagging(s, dry_run=True)
+        )
+        token = _reset_content_confirm_token(projection)
+        if dry_run:
+            projection["confirm"] = token
+            return jsonify(projection)
+        if str(body.get("confirm", "")) != token:
+            return _bad(
+                "confirm_mismatch",
+                detail="run a fresh preview and echo its confirm token",
+            )
+        result = await session.run_sync(
+            lambda s: reset_content_tagging(s, dry_run=False)
+        )
+    return jsonify(result)
 
 
 @admin_bp.route("/tags/normalize", methods=["POST"])
@@ -400,6 +459,22 @@ async def trigger_prune_missing_files():
     return _queued(async_result)
 
 
+@admin_bp.route("/maintenance/reclaim-attachments", methods=["POST"])
+async def trigger_reclaim_attachments():
+    """Reclaim orphaned attachments (#3068). Body {"dry_run": bool}: dry_run
+    (the DEFAULT here) projects the orphan rows and unreferenced store blobs
+    without touching either; dry_run=false deletes the rows then unlinks every
+    blob no surviving row references. Maintenance queue; operator-triggered
+    only — never an unattended sweep, since the apply unlinks files. Returns the
+    Celery task id — poll /maintenance/task-result/<id> for the summary."""
+    from ..tasks.admin import reclaim_orphaned_attachments_task
+
+    body = await request.get_json(silent=True) or {}
+    dry_run = bool(body.get("dry_run", True))  # default to the SAFE preview
+    async_result = reclaim_orphaned_attachments_task.delay(dry_run=dry_run)
+    return _queued(async_result)
+
+
 @admin_bp.route("/maintenance/dedup-videos", methods=["POST"])
 async def trigger_dedup_videos():
     """Tier-1 video dedup (#871). Body {"dry_run": bool}: dry_run=true previews

backend/app/api/allowlist.py

@@ -1,84 +0,0 @@
-"""Allowlist API: list, adjust threshold, remove."""
-
-from quart import Blueprint, jsonify, request
-
-from ..extensions import get_session
-from ..models import TagAllowlist
-from ..services.ml.allowlist import AllowlistService
-
-allowlist_bp = Blueprint("allowlist", __name__, url_prefix="/api")
-
-
-@allowlist_bp.route("/allowlist", methods=["GET"])
-async def list_allowlist():
-    async with get_session() as session:
-        rows = await AllowlistService(session).list_all()
-    return jsonify(
-        [
-            {
-                "tag_id": r.tag_id,
-                "tag_name": r.tag_name,
-                "tag_kind": r.tag_kind,
-                "min_confidence": r.min_confidence,
-                "applied_count": r.applied_count,
-                "coverage_count": r.coverage_count,
-            }
-            for r in rows
-        ]
-    )
-
-
-@allowlist_bp.route("/tags/<int:tag_id>/allowlist/coverage", methods=["GET"])
-async def coverage(tag_id: int):
-    """Live "at threshold T, a sweep would cover ~N images" projection for the
-    allowlist tuning dashboard. Defaults to the tag's stored threshold."""
-    raw = request.args.get("threshold")
-    async with get_session() as session:
-        svc = AllowlistService(session)
-        if raw is not None:
-            try:
-                threshold = float(raw)
-            except ValueError:
-                return jsonify({"error": "threshold must be a float"}), 400
-            if not (0 < threshold <= 1):
-                return jsonify({"error": "threshold must be in (0, 1]"}), 400
-        else:
-            row = await session.get(TagAllowlist, tag_id)
-            if row is None:
-                return jsonify({"error": "not on allowlist"}), 404
-            threshold = row.min_confidence
-        count = await svc.coverage(tag_id, threshold)
-    return jsonify({"count": count, "threshold": threshold})
-
-
-@allowlist_bp.route("/tags/<int:tag_id>/allowlist", methods=["GET"])
-async def get_one(tag_id: int):
-    async with get_session() as session:
-        row = await session.get(TagAllowlist, tag_id)
-    if row is None:
-        return jsonify({"error": "not on allowlist"}), 404
-    return jsonify(
-        {"min_confidence": row.min_confidence, "added_at": row.added_at.isoformat()}
-    )
-
-
-@allowlist_bp.route("/tags/<int:tag_id>/allowlist", methods=["PATCH"])
-async def patch_threshold(tag_id: int):
-    body = await request.get_json()
-    if not body or "min_confidence" not in body:
-        return jsonify({"error": "min_confidence required"}), 400
-    mc = float(body["min_confidence"])
-    if not (0 < mc <= 1):
-        return jsonify({"error": "min_confidence must be in (0, 1]"}), 400
-    async with get_session() as session:
-        await AllowlistService(session).update_threshold(tag_id, mc)
-        await session.commit()
-    return "", 204
-
-
-@allowlist_bp.route("/tags/<int:tag_id>/allowlist", methods=["DELETE"])
-async def remove(tag_id: int):
-    async with get_session() as session:
-        await AllowlistService(session).remove(tag_id)
-        await session.commit()
-    return "", 204

backend/app/api/artists.py

@@ -31,6 +31,24 @@ async def create_or_get():
     }), 201
 
 
+@artists_bp.route("/<int:artist_id>", methods=["PATCH"])
+async def rename(artist_id: int):
+    """Rename an artist's DISPLAY NAME (#130). Name only — the slug and every
+    on-disk path stay put, so this is instant and safe. Name is non-unique."""
+    body = await request.get_json()
+    if not isinstance(body, dict) or not isinstance(body.get("name"), str):
+        return jsonify({"error": "invalid_body"}), 400
+    async with get_session() as session:
+        svc = ArtistService(session)
+        try:
+            artist = await svc.rename(artist_id, body["name"])
+        except ValueError as exc:
+            return jsonify({"error": "empty_name", "detail": str(exc)}), 400
+        if artist is None:
+            return jsonify({"error": "not_found"}), 404
+        return jsonify({"id": artist.id, "name": artist.name, "slug": artist.slug})
+
+
 @artists_bp.route("/autocomplete", methods=["GET"])
 async def autocomplete():
     q = request.args.get("q") or ""

backend/app/api/extension.py

@@ -6,12 +6,14 @@ from __future__ import annotations
 
 import asyncio
 import hashlib
+import hmac
 import re
 from pathlib import Path
 
 from quart import Blueprint, jsonify, request
 from sqlalchemy import select
 
+from ..build_info import FC_CHANNEL as _FC_CHANNEL
 from ..extensions import get_session
 from ..models import AppSetting
 from ..services.extension_service import (
@@ -30,6 +32,15 @@ XPI_DIR = Path("/app/frontend/dist/extension")
 
 _XPI_VERSION_RE = re.compile(r"fabledcurator-(?P<version>[\w.-]+)\.xpi$")
 
+# Which channel this image belongs to — "dev" or "main" — baked in at build
+# time (milestone 271 step 7). Read from build_info rather than the environment
+# a second time: /api/health reports the same value, and two independent
+# `os.environ.get` calls are two things that can drift.
+#
+# Still bound as a module-level name here, so tests monkeypatch
+# `extension.FC_CHANNEL` exactly as they did before, same as XPI_DIR above.
+FC_CHANNEL = _FC_CHANNEL
+
 
 async def _ext_key_required(session) -> bool:
     """Unlike /api/credentials (which accepts the browser path with no
@@ -41,7 +52,15 @@ async def _ext_key_required(session) -> bool:
     stored = (await session.execute(
         select(AppSetting.value).where(AppSetting.key == "extension_api_key")
     )).scalar_one_or_none()
-    return stored is not None and supplied == stored
+    if stored is None:
+        return False
+    # compare_digest, not `==`: the stored key is a shared secret, and a
+    # short-circuiting compare leaks its prefix through timing. Costs nothing
+    # here — it is not that this route is exposed (#3072). Compared as BYTES:
+    # compare_digest's str form rejects non-ASCII with TypeError, and this
+    # header is attacker-supplied, so a str compare would turn a junk key into
+    # a 500 instead of a 403.
+    return hmac.compare_digest(supplied.encode("utf-8"), stored.encode("utf-8"))
 
 
 def _extract_version(xpi_name: str) -> str:
@@ -84,11 +103,15 @@ async def quick_add_source():
     if not isinstance(url, str) or not url.strip():
         return _bad("invalid_body", detail="url is required")
 
+    from .credentials import _get_crypto
+
     async with get_session() as session:
         if not await _ext_key_required(session):
             return _bad("unauthorized", status=401)
         try:
-            result = await ExtensionService(session).quick_add_source(url)
+            # crypto lets a pixiv add resolve the artist's display name via the
+            # stored OAuth token (else it falls back to the numeric id). #130.
+            result = await ExtensionService(session, _get_crypto()).quick_add_source(url)
         except UnknownPlatformError as exc:
             return _bad(
                 "unknown_platform",
@@ -120,13 +143,30 @@ def _read_manifest_sync() -> dict | None:
         return None
     versioned.sort(key=lambda p: p.stat().st_mtime)
     latest = versioned[-1]
-    return {
+    info = {
         "installed": True,
         "version": _extract_version(latest.name),
         "xpi_url": f"/extension/{latest.name}",
         "latest_url": "/extension/fabledcurator-latest.xpi",
         "sha256": _sha256(latest),
     }
+    # The channel goes BESIDE the version, never inside it. A `-dev` suffix is
+    # what silently disabled the dev channel in the sibling project this design
+    # comes from: the comparator returned nothing for a non-integer segment, so
+    # every dev version compared equal and "no update available" became
+    # indistinguishable from "I cannot read this version".
+    #
+    # Omitted rather than defaulted when unset. Absence already has a meaning
+    # every reader must handle — an image built before this field existed says
+    # exactly the same thing by not having the key — so a blank channel reuses
+    # that path instead of inventing a second "unknown" spelling.
+    #
+    # Reported verbatim, not validated against {"dev", "main"}: if an image
+    # declares something else, showing what it actually claims is more useful
+    # to whoever is debugging it than dropping the value on the floor.
+    if FC_CHANNEL:
+        info["channel"] = FC_CHANNEL
+    return info
 
 
 @extension_bp.route("/manifest", methods=["GET"])

backend/app/api/gallery.py

@@ -3,9 +3,18 @@
 from datetime import UTC, datetime, timedelta
 
 from quart import Blueprint, jsonify, request
+from sqlalchemy import delete, select, update
+from sqlalchemy.orm import aliased
 
 from ..extensions import get_session
-from ..services.gallery_service import GalleryService
+from ..models import (
+    ImageRecord,
+    PresentationReview,
+    Tag,
+    TagSuggestionRejection,
+)
+from ..models.tag import image_tag
+from ..services.gallery_service import GalleryService, image_url, thumbnail_url
 
 gallery_bp = Blueprint("gallery", __name__, url_prefix="/api/gallery")
 
@@ -44,7 +53,8 @@ def _parse_filters():
       the image must match at least one tag from EACH group (groups ANDed).
     - `tag_not` is a comma-separated exclude list (image must carry none).
 
-    `media` is image|video; `sort` is newest|oldest; `platform` selects one
+    `media` is image|video; `sort` is newest|oldest|posted_new|posted_old
+    (default posted_new); `platform` selects one
     platform (or the UNSOURCED_PLATFORM sentinel); `untagged`/`no_artist` are
     boolean flags; `date_from`/`date_to` are inclusive calendar-day bounds
     (date_to is widened by a day so the whole day is covered by the service's
@@ -67,11 +77,18 @@ def _parse_filters():
     artist_id = int(artist_id_raw) if artist_id_raw else None
     media = request.args.get("media")
     media_type = media if media in ("image", "video") else None
+    # newest/oldest key off effective_date (primary post / download); posted_new/
+    # posted_old off earliest_post_date (original publish across all posts). The
+    # default is posted_new so the grid leads with original publish date, not the
+    # download/repost the primary post points at (operator-flagged 2026-07-01).
     sort = request.args.get("sort")
-    sort = sort if sort in ("newest", "oldest") else "newest"
+    sort = sort if sort in ("newest", "oldest", "posted_new", "posted_old") else "posted_new"
     platform = request.args.get("platform") or None
     untagged = request.args.get("untagged") in ("1", "true", "yes")
     no_artist = request.args.get("no_artist") in ("1", "true", "yes")
+    # Show the presentation chrome (banner / editor screenshot) that the default
+    # gallery hides — the Hidden view sets this (milestone 141).
+    include_hidden = request.args.get("include_hidden") in ("1", "true", "yes")
     date_from = _parse_date(request.args.get("date_from"))
     date_to = _parse_date(request.args.get("date_to"))
     if date_to is not None:
@@ -83,6 +100,7 @@ def _parse_filters():
         "platform": platform,
         "untagged": untagged, "no_artist": no_artist,
         "date_from": date_from, "date_to": date_to,
+        "include_hidden": include_hidden,
     }
     return filters, sort
 
@@ -127,12 +145,32 @@ async def similar():
         filters, _sort = _parse_filters()
     except (KeyError, ValueError):
         return jsonify({"error": "similar_to query param required"}), 400
+    # Explore passes exclude_wip=1 to also drop work-in-progress from the
+    # rabbit-hole; the gallery's own "similar" button omits it (keeps wip, #1274).
+    exclude_wip = request.args.get("exclude_wip") in ("1", "true", "True")
+    # Explore reach (#1476): 0 = nearest (gallery default), →1 reaches into farther
+    # distance bands so the walk can escape a dense cluster. exclude_ids = the
+    # breadcrumb, so already-walked images aren't re-served as neighbours.
+    try:
+        reach = max(0.0, min(1.0, float(request.args.get("reach", "0"))))
+    except ValueError:
+        reach = 0.0
+    exclude_ids = [
+        int(x) for x in request.args.get("exclude_ids", "").split(",")
+        if x.strip().isdigit()
+    ] or None
     # post_id is the exclusive post-detail view — not a similarity scope.
-    scope = {k: v for k, v in filters.items() if k != "post_id"}
+    # include_hidden is a gallery-browse flag; similar() has its OWN presentation
+    # exclusion (a similarity-quality concern, #1274), so drop it here (#141).
+    scope = {
+        k: v for k, v in filters.items() if k not in ("post_id", "include_hidden")
+    }
     async with get_session() as session:
         svc = GalleryService(session)
         try:
-            images = await svc.similar(image_id=similar_to, limit=limit, **scope)
+            images = await svc.similar(
+                image_id=similar_to, limit=limit, exclude_wip=exclude_wip,
+                reach=reach, exclude_ids=exclude_ids, **scope)
         except ValueError as exc:
             return jsonify({"error": str(exc)}), 400
     if images is None:
@@ -206,6 +244,101 @@ async def jump():
     return jsonify({"cursor": cursor})
 
 
+# -- Hidden-view review (#141): auto-hidden chrome flagged "also looks like
+#    content", surfaced in the gallery's Show-hidden review strip. -----------
+@gallery_bp.route("/hidden-review", methods=["GET"])
+async def hidden_review():
+    """Unresolved system-tag auto-apply review flags (chrome + process, #1464),
+    most-concerning first (highest content score) — for the review strip. `mode`
+    tells the client whether the flagged tag hid the image ('chrome') or left it
+    visible ('process'), which decides the resolve labels (un-hide vs remove-tag)."""
+    ptag = aliased(Tag)
+    ctag = aliased(Tag)
+    async with get_session() as session:
+        rows = (await session.execute(
+            select(
+                PresentationReview.image_record_id,
+                PresentationReview.tag_id,
+                PresentationReview.conflict_tag_id,
+                PresentationReview.conflict_score,
+                PresentationReview.mode,
+                ImageRecord.path, ImageRecord.thumbnail_path,
+                ImageRecord.sha256, ImageRecord.mime,
+                ptag.name.label("tag_name"),
+                ctag.name.label("conflict_name"),
+            )
+            .join(ImageRecord, ImageRecord.id == PresentationReview.image_record_id)
+            .join(ptag, ptag.id == PresentationReview.tag_id)
+            .outerjoin(ctag, ctag.id == PresentationReview.conflict_tag_id)
+            .where(PresentationReview.resolved_at.is_(None))
+            .order_by(PresentationReview.conflict_score.desc())
+        )).all()
+    return jsonify({"items": [
+        {
+            "image_id": r.image_record_id,
+            "tag_id": r.tag_id,
+            "tag_name": r.tag_name,
+            "conflict_tag_id": r.conflict_tag_id,
+            "conflict_name": r.conflict_name,
+            "conflict_score": r.conflict_score,
+            "mode": r.mode,
+            "thumbnail_url": thumbnail_url(r.thumbnail_path, r.sha256, r.mime),
+            "image_url": image_url(r.path),
+        }
+        for r in rows
+    ]})
+
+
+@gallery_bp.route(
+    "/hidden-review/<int:image_id>/<int:tag_id>/keep", methods=["POST"]
+)
+async def hidden_review_keep(image_id, tag_id):
+    """Keep the auto-hide: resolve the flag; the tag stays applied (#141)."""
+    async with get_session() as session:
+        await session.execute(
+            update(PresentationReview)
+            .where(
+                PresentationReview.image_record_id == image_id,
+                PresentationReview.tag_id == tag_id,
+            )
+            .values(resolved_at=datetime.now(UTC))
+        )
+        await session.commit()
+    return "", 204
+
+
+@gallery_bp.route(
+    "/hidden-review/<int:image_id>/<int:tag_id>/unhide", methods=["POST"]
+)
+async def hidden_review_unhide(image_id, tag_id):
+    """Un-hide: remove the presentation tag (image returns to the gallery), record
+    a rejection so the head LEARNS it misfired, and resolve the flag (#141)."""
+    from sqlalchemy.dialects.postgresql import insert as pg_insert
+
+    async with get_session() as session:
+        await session.execute(
+            delete(image_tag).where(
+                image_tag.c.image_record_id == image_id,
+                image_tag.c.tag_id == tag_id,
+            )
+        )
+        await session.execute(
+            pg_insert(TagSuggestionRejection)
+            .values(image_record_id=image_id, tag_id=tag_id)
+            .on_conflict_do_nothing()
+        )
+        await session.execute(
+            update(PresentationReview)
+            .where(
+                PresentationReview.image_record_id == image_id,
+                PresentationReview.tag_id == tag_id,
+            )
+            .values(resolved_at=datetime.now(UTC))
+        )
+        await session.commit()
+    return "", 204
+
+
 @gallery_bp.route("/image/<int:image_id>", methods=["GET"])
 async def image_detail(image_id: int):
     async with get_session() as session:

backend/app/api/gpu.py

@@ -9,20 +9,26 @@ homelab admin.
 """
 
 import secrets
+from pathlib import Path
 
 from quart import Blueprint, jsonify, request
-from sqlalchemy import func, select
+from sqlalchemy import func, or_, select, update
 from sqlalchemy.dialects.postgresql import insert as pg_insert
 
 from ..extensions import get_session
 from ..models import AppSetting, GpuJob, ImageRecord, MLSettings
 from ..services.gallery_service import image_url
-from ..services.ml.embedder import MODEL_NAME as EMBED_MODEL_NAME
-from ..services.ml.gpu_jobs import GpuJobService
+from ..services.ml.gpu_jobs import GpuJobService, error_dedupe_statements
+from ..services.ml.gpu_triage import classify_reason, recover_defective_image
 from ..services.ml.regions import RegionService
+from ..services.service_roster import touch_service
 
 gpu_bp = Blueprint("gpu", __name__, url_prefix="/api/gpu")
 
+# Same container mount the maintenance tasks use (tasks/admin.py) — recovery
+# deletes the defective original + thumbnail under it.
+_IMAGES_ROOT = Path("/images")
+
 _TOKEN_KEY = "gpu_agent_token"
 
 
@@ -91,12 +97,152 @@ async def backfill():
     """Enqueue a job for every image that doesn't already have one for `task`."""
     body = await request.get_json(silent=True) or {}
     task = str(body.get("task") or "ccip")
-    from ..tasks.ml import enqueue_gpu_backfill
+    from ..tasks.gpu_queue import enqueue_gpu_backfill
 
     r = enqueue_gpu_backfill.delay(task)
     return jsonify({"celery_task_id": r.id, "task": task}), 202
 
 
+@gpu_bp.route("/reprocess", methods=["POST"])
+async def reprocess():
+    """Reset every done/error job of `task` back to pending so the agent re-runs
+    the WHOLE library under the current pipeline (e.g. after adding crop
+    detectors). Heavy — the back-catalogue is otherwise skipped by the backfills."""
+    body = await request.get_json(silent=True) or {}
+    task = str(body.get("task") or "ccip")
+    from ..tasks.gpu_queue import reprocess_gpu_jobs
+
+    r = reprocess_gpu_jobs.delay(task)
+    return jsonify({"celery_task_id": r.id, "task": task}), 202
+
+
+@gpu_bp.route("/retry_errors", methods=["POST"])
+async def retry_errors():
+    """Requeue every ERRORED job (all task types) back to pending — the scoped
+    recovery after an agent-side fix (e.g. the short-video sampler), where
+    /reprocess would needlessly re-run the whole done library too. Attempts and
+    the stored error reset so each job gets its full retry budget under the
+    fixed pipeline. Stale tombstones are pruned FIRST (loop-era duplicates and
+    rows a later success made moot — the same statements the backfills run), so
+    one failing file requeues as ONE job, never a fan-out of duplicates. Small
+    row count (errors only) → inline statements; the response carries the
+    counts for the UI toast. Triage-confirmed defects are NOT requeued (see
+    the WHERE below) — they stay on the recovery surface."""
+    async with get_session() as session:
+        pruned = 0
+        for stmt in error_dedupe_statements():
+            pruned += (await session.execute(stmt)).rowcount or 0
+        res = await session.execute(
+            update(GpuJob)
+            .where(
+                GpuJob.status == "error",
+                # Triage-confirmed DEFECTS stay errored: the integrity probe
+                # already proved the FILE is bad, so re-running the job just
+                # burns agent time re-minting the same tombstone — those go
+                # through /errors/<id>/recover instead.
+                or_(GpuJob.triage_status.is_(None),
+                    GpuJob.triage_status != "defect"),
+            )
+            .values(
+                status="pending", attempts=0, error=None, lease_token=None,
+                leased_at=None, lease_expires_at=None, triage_status=None,
+                updated_at=func.now(),
+            )
+        )
+        kept = (
+            await session.execute(
+                select(func.count()).select_from(GpuJob)
+                .where(GpuJob.status == "error")
+            )
+        ).scalar_one()
+        await session.commit()
+    return jsonify({
+        "requeued": res.rowcount or 0, "pruned": pruned, "defects_kept": kept,
+    })
+
+
+# --- Failure triage + recovery (#125) ------------------------------------
+
+@gpu_bp.route("/errors", methods=["GET"])
+async def errors():
+    """The triage view of the error tombstones: every errored job joined with
+    its image's integrity verdict, bucketed by reason for the overview. The
+    probe sweep (triage_gpu_errors, 15-min beat) fills triage_status; 'defect'
+    rows are the recovery surface's list."""
+    async with get_session() as session:
+        rows = (
+            await session.execute(
+                select(
+                    GpuJob.id, GpuJob.image_record_id, GpuJob.task,
+                    GpuJob.error, GpuJob.triage_status, GpuJob.updated_at,
+                    ImageRecord.integrity_status, ImageRecord.mime,
+                    ImageRecord.path, ImageRecord.thumbnail_path,
+                )
+                .join(ImageRecord, ImageRecord.id == GpuJob.image_record_id)
+                .where(GpuJob.status == "error")
+                .order_by(GpuJob.updated_at.desc())
+                .limit(500)
+            )
+        ).all()
+        total = (
+            await session.execute(
+                select(func.count()).select_from(GpuJob)
+                .where(GpuJob.status == "error")
+            )
+        ).scalar_one()
+    by_class: dict[str, int] = {}
+    triage = {"defect": 0, "file_ok": 0, "unclassified": 0}
+    items = []
+    for r in rows:
+        cls = classify_reason(r.error)
+        by_class[cls] = by_class.get(cls, 0) + 1
+        bucket = r.triage_status or "unclassified"
+        triage[bucket] = triage.get(bucket, 0) + 1
+        items.append({
+            "job_id": r.id,
+            "image_id": r.image_record_id,
+            "task": r.task,
+            "error": r.error,
+            "reason_class": cls,
+            "triage_status": r.triage_status,
+            "integrity_status": r.integrity_status,
+            "mime": r.mime,
+            "image_url": image_url(r.path),
+            "thumbnail_url": (
+                image_url(r.thumbnail_path) if r.thumbnail_path else None
+            ),
+            "updated_at": r.updated_at.isoformat() if r.updated_at else None,
+        })
+    return jsonify({
+        "total": total, "by_class": by_class, "triage": triage, "items": items,
+    })
+
+
+@gpu_bp.route("/errors/triage", methods=["POST"])
+async def errors_triage():
+    """Run the probe sweep NOW (the card's button) instead of waiting out the
+    15-minute beat cadence."""
+    from ..tasks.maintenance import triage_gpu_errors
+
+    r = triage_gpu_errors.delay()
+    return jsonify({"celery_task_id": r.id}), 202
+
+
+@gpu_bp.route("/errors/<int:image_id>/recover", methods=["POST"])
+async def errors_recover(image_id: int):
+    """Recover a defect-triaged original: delete the bad copy + record and
+    re-poll its subscription Source (a fresh fetch re-imports the file, which
+    re-enters the GPU pipeline). Returns status 'no_source' when nothing
+    pollable resolves — the file needs manual replacement there."""
+    async with get_session() as session:
+        result = await session.run_sync(
+            lambda s: recover_defective_image(
+                s, image_id, images_root=_IMAGES_ROOT,
+            )
+        )
+    return jsonify(result)
+
+
 # --- Agent (bearer token): lease / submit / heartbeat / fail ------------
 
 @gpu_bp.route("/jobs/lease", methods=["POST"])
@@ -111,9 +257,19 @@ async def lease():
         if not await _agent_authed(session):
             return jsonify({"error": "unauthorized"}), 401
         jobs = await GpuJobService(session).lease(agent_id, batch_size=batch)
-        ml = (
-            await session.execute(select(MLSettings).where(MLSettings.id == 1))
-        ).scalar_one()
+        # The agent cannot be polled — it is HTTP-only and pulls from here, so
+        # web never dials it. A lease IS the check-in, and until milestone 365
+        # it was thrown away: an agent sitting idle with nothing to lease left
+        # no trace at all and was indistinguishable from one switched off a
+        # week ago. Recorded on the call that was already happening.
+        await touch_service(
+            session,
+            key=f"agent:{agent_id}",
+            kind="agent",
+            display_name="GPU agent" if agent_id == "agent" else f"GPU agent ({agent_id})",
+            details={"agent_id": agent_id, "last_call": "lease", "leased": len(jobs)},
+        )
+        ml = await MLSettings.load(session)
         # image rows for url/mime in one shot
         ids = [j.image_record_id for j in jobs]
         imgs = {
@@ -124,6 +280,33 @@ async def lease():
             ).scalars()
         } if ids else {}
         await session.commit()
+        # Crop-proposer config, announced FROM THE SETTING like embed_model_name
+        # (#134): the agent builds its detectors from this, rebuilding live when
+        # it changes — so tuning is a DB/UI edit, never an agent restart. Same
+        # block for every job in the batch (it's global), built once. An enabled
+        # toggle off is carried through so the agent skips that proposer.
+        detectors = {
+            "person": {
+                "enabled": ml.detector_person_enabled,
+                "weights": ml.detector_person_weights,
+                "conf": ml.detector_person_conf,
+            },
+            "anatomy": {
+                "enabled": ml.detector_anatomy_enabled,
+                "weights": ml.detector_anatomy_weights,
+                "conf": ml.detector_anatomy_conf,
+            },
+            "panel": {
+                "enabled": ml.detector_panel_enabled,
+                "weights": ml.detector_panel_weights,
+                "conf": ml.detector_panel_conf,
+            },
+            "max_figures": ml.detector_max_figures,
+            "max_components": ml.detector_max_components,
+            "max_panels": ml.detector_max_panels,
+            "max_regions": ml.detector_max_regions,
+            "dedupe_iou": ml.detector_dedupe_iou,
+        }
         out = []
         for j in jobs:
             img = imgs.get(j.image_record_id)
@@ -138,12 +321,14 @@ async def lease():
                 # For video/animated: the agent samples at this cadence.
                 "frame_interval_seconds": ml.video_frame_interval_seconds,
                 "max_frames": ml.video_max_frames,
-                # The embedding model the agent must use for concept crops, so
-                # its region vectors land in the SAME space the heads trained in.
-                # Server-announced → the agent stays model-agnostic; a swap is a
-                # server setting + a re-embed migration, never an agent change.
-                "embed_model_name": EMBED_MODEL_NAME,
+                # The embedding model the agent must use for concept crops + the
+                # whole-image 'embed' task, so its vectors land in the SAME space
+                # the heads trained in. Server-announced FROM THE SETTING → the
+                # agent stays model-agnostic; an operator swap is a setting + a
+                # re-embed, never an agent change.
+                "embed_model_name": ml.embedder_model_name,
                 "embed_version": ml.embedder_model_version,
+                "detectors": detectors,
             })
     return jsonify({"jobs": out})
 
@@ -157,6 +342,13 @@ async def heartbeat():
         if not await _agent_authed(session):
             return jsonify({"error": "unauthorized"}), 401
         n = await GpuJobService(session).heartbeat(agent_id, job_ids)
+        await touch_service(
+            session,
+            key=f"agent:{agent_id}",
+            kind="agent",
+            display_name="GPU agent" if agent_id == "agent" else f"GPU agent ({agent_id})",
+            details={"agent_id": agent_id, "last_call": "heartbeat", "extended": n},
+        )
         await session.commit()
     return jsonify({"extended": n})
 
@@ -188,6 +380,34 @@ async def submit():
     return jsonify({"ok": True, "stored": len(regions)})
 
 
+@gpu_bp.route("/jobs/submit_embedding", methods=["POST"])
+async def submit_embedding():
+    """Store a whole-image SigLIP embedding (the 'embed' task) on image_record +
+    close the job. Body: {agent_id, job_id, embedding:[...], embedding_version}.
+    This is how the GPU agent re-embeds the library under a new model (#1190) —
+    much faster than the CPU ml-worker at higher resolutions."""
+    body = await request.get_json(silent=True) or {}
+    agent_id = str(body.get("agent_id") or "agent")
+    job_id = body.get("job_id")
+    embedding = body.get("embedding")
+    version = body.get("embedding_version")
+    if job_id is None or not embedding or not version:
+        return jsonify({"error": "job_id, embedding, embedding_version required"}), 400
+    async with get_session() as session:
+        if not await _agent_authed(session):
+            return jsonify({"error": "unauthorized"}), 401
+        job = await session.get(GpuJob, int(job_id))
+        if job is None or job.status != "leased" or job.lease_token != agent_id:
+            return jsonify({"error": "lease_invalid"}), 409
+        img = await session.get(ImageRecord, job.image_record_id)
+        if img is not None:
+            img.siglip_embedding = embedding
+            img.siglip_model_version = version
+        await GpuJobService(session).complete(agent_id, int(job_id))
+        await session.commit()
+    return jsonify({"ok": True})
+
+
 @gpu_bp.route("/jobs/fail", methods=["POST"])
 async def fail():
     body = await request.get_json(silent=True) or {}