diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..26d59ea
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,48 @@
+# Secrets / runtime config
+.env
+.env.local
+.env.*.local
+
+# Python virtualenvs (api/.venv, worker/.venv, etc.)
+.venv/
+venv/
+env/
+
+# Python bytecode caches
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Local ad-hoc backups (.bak / .bak-YYYYMMDD-HHMM / .bak-<label>)
+*.bak
+*.bak-*
+
+# Editor / IDE / OS artifacts
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+
+# Logs
+*.log
+*.log.*
+logs/
+
+# DepotDownloader scratch dirs
+depots/
+.DepotDownloader/
+
+# Postgres bind-mount data dir (if anyone ever switches off the named volume)
+postgres_data/
+data/postgres/
+
+# Node (defensive — not used today, but headoff if a build step shows up)
+node_modules/
+npm-debug.log*
+yarn-error.log*
diff --git a/README.md b/README.md
index f47f531..be45b6e 100644
--- a/README.md
+++ b/README.md
@@ -1,68 +1,52 @@
 # sortof
 
-A Project Zomboid mod load-order sorter. Paste Steam Workshop IDs or a
-collection URL, get back the three lines (`WorkshopItems=`, `Mods=`,
-`Map=`) you paste into your dedicated server's `.ini` file.
+Project Zomboid mod load-order sorter for dedicated servers. Paste workshop
+IDs or a collection URL; get back the `WorkshopItems=`, `Mods=`, and `Map=`
+lines for `servertest.ini`.
 
 ## Stack
 
-- **API** — FastAPI + asyncpg, Python 3.12.
-- **Cache** — PostgreSQL 16. One row per `(workshop_id, mod_id)` parsed
-  from each mod's `mod.info`. Cache invalidates on Steam's
-  `time_updated`; no manual TTLs.
-- **Drain worker** — pulls cache misses via DepotDownloader, parses
-  `mod.info` and `media/maps/*/map.info`, writes back to Postgres.
-- **Frontend** — vanilla JSX in `frontend/`, served by FastAPI
-  `StaticFiles`, transpiled in-browser by Babel-standalone. No build
-  step, no npm.
-- **Deployment** — Docker for Postgres only; the API and drain workers
-  run as systemd units on the host.
+- FastAPI + asyncpg, Python 3.12.
+- Postgres 16 (Docker).
+- DepotDownloader for fetching `mod.info` / `map.info` from each cached
+  workshop item.
+- Vanilla JSX + index.html, no build step (Babel-standalone in-browser).
 
-## What it actually does
+## Setup
 
-- Resolves bare workshop IDs **and** collection URLs (anonymous Steam API
-  expansion).
-- Topologically sorts mods by `requirements`, `loadAfter`, `loadBefore`
-  with explicit support for `loadFirst` / `loadLast` and the "patch"
-  tier.
-- Detects multi-branch wsids (e.g. AuthenticZ, Project RV Interior),
-  auto-picks a sensible default by build flavor or input cross-reference,
-  and surfaces the alternates in a picker.
-- Emits actionable warnings: missing dependencies (with one-click "add"
-  buttons when the dep is in our cache), build-mismatch flags with
-  swap-or-remove actions, duplicate-mod_id conflicts, addon detection,
-  and required-item suggestions scraped from the Workshop page.
-- Tracks community-reported broken mods per PZ build, with thumbs-up /
-  thumbs-down voting and a search panel.
+```bash
+docker compose up -d sortof_db
 
-## Bootstrapping (rough)
+python3.12 -m venv api/.venv
+api/.venv/bin/pip install -r api/requirements.txt
 
-1. `docker compose up -d sortof_db` — runs Postgres on `127.0.0.1:5439`,
-   applies `init/*.sql` migrations on first boot.
-2. Create the two virtualenvs:
-   ```bash
-   python3.12 -m venv api/.venv     && api/.venv/bin/pip install -r api/requirements.txt
-   python3.12 -m venv worker/.venv  && worker/.venv/bin/pip install -r worker/requirements.txt
-   ```
-3. Drop a `.env` next to `docker-compose.yml` with `POSTGRES_USER`,
-   `POSTGRES_PASSWORD`, `POSTGRES_DB`, and `SORTOF_CORS_ORIGINS`.
-4. Set `DD_PATH` to wherever DepotDownloader lives, then start the API
-   (`api/.venv/bin/uvicorn app:app --host 127.0.0.1 --port 8801`) and a
-   drain worker (`worker/.venv/bin/python drain.py`).
+python3.12 -m venv worker/.venv
+worker/.venv/bin/pip install -r worker/requirements.txt
+```
 
-For the systemd units, see `docs/` (and the running host).
+`.env` next to `docker-compose.yml`:
+
+```
+POSTGRES_USER=sortof
+POSTGRES_PASSWORD=<random>
+POSTGRES_DB=sortof
+SORTOF_CORS_ORIGINS=http://127.0.0.1:8801
+```
+
+Set `DD_PATH` to the DepotDownloader binary, then:
+
+```bash
+api/.venv/bin/uvicorn app:app --host 127.0.0.1 --port 8801
+worker/.venv/bin/python drain.py
+```
 
 ## Layout
 
 ```
-api/         FastAPI service + adapters + sort engine
-worker/      drain worker — DepotDownloader + mod.info parser
-frontend/    vanilla JSX + index.html (no build step)
-init/        Postgres bootstrap migrations (runs in order)
-data/        checked-in JSON like pz_versions.json
-docs/        specs, plans, audit notes
+api/      FastAPI service, sort engine, response adapters
+worker/   drain worker (DepotDownloader + mod.info parser)
+frontend/ index.html + JSX
+init/     Postgres bootstrap migrations (run on first boot)
+data/     checked-in JSON config (e.g., pz_versions.json)
+docs/     specs, plans
 ```
-
-## License
-
-TBD.
diff --git a/api/adapters.py b/api/adapters.py
new file mode 100644
index 0000000..1c59097
--- /dev/null
+++ b/api/adapters.py
@@ -0,0 +1,683 @@
+"""Translate mlos_sort + mod_parsed rows into the SORTOF_DATA shape the frontend expects."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+from mlos_sort import ModInfo
+
+CAT_MAP: Dict[str, str] = {
+    "coreRequirement": "lib",
+    "tweaks":          "lib",
+    "tile":            "tile",
+    "debug":           "debug",
+    "resource":        "resource",
+    "map":             "map",
+    "qol":             "qol",
+    "moodle":          "moodle",
+    "tweak_minor":     "tweak",
+    "music":           "music",
+    "wearable":        "wearable",
+    "profession":      "profession",
+    "movement":        "movement",
+    "building":        "building",
+    "farming":         "farming",
+    "zombie":          "zombie",
+    "zone":            "zone",
+    "armor":           "armor",
+    "food":            "food",
+    "health":          "health",
+    "weapon":          "weapon",
+    "crafting":        "crafting",
+    "container":       "container",
+    "vehicle":         "vehicle",
+    "vehicle_spawn":   "v.spawn",
+    "loot":            "loot",
+    "code":            "gameplay",
+    "ui":              "ui",
+    "sound":           "sound",
+    "texture":         "texture",
+    "translation":     "i18n",
+    "multiplayer":     "mp",
+    "server_only":     "server",
+    "fix":             "fix",
+    "other":           "gameplay",
+    "undefined":       "gameplay",
+    # Spec G-patch §6: dedicated frontend pill so patches are visible at a
+    # glance even though their position (last) already telegraphs the role.
+    "patch":           "patch",
+}
+
+
+def to_frontend_cat(mlos_cat: str) -> str:
+    return CAT_MAP.get(mlos_cat, "gameplay")
+
+
+def position(load_first: str, load_last: str) -> str:
+    if load_first == "on":
+        return "first"
+    if load_last == "on":
+        return "last"
+    return ""
+
+
+# Hand-curated mod_id alias map: when the user has any of the value mod_ids,
+# the key mod_id is considered "satisfied" for missing-dep purposes. This
+# stops a B42 mod whose mod_id was renamed across builds (e.g. TrueMoozic)
+# from showing up as a missing dep for downstream B41 mods that still
+# require the old mod_id (`truemusic`).
+MOD_ID_ALIASES: Dict[str, List[str]] = {
+    "truemusic": ["TrueMoozic"],
+}
+
+
+def _resolve_satisfied_via_alias(input_modids: Set[str]) -> Set[str]:
+    """Return the input mod_id set expanded with any keys whose alias values
+    are present in the input."""
+    out = set(input_modids)
+    for key, values in MOD_ID_ALIASES.items():
+        if any(v in input_modids for v in values):
+            out.add(key)
+    return out
+
+
+def build_warnings(
+    mlos_warnings: Dict[str, Any],
+    wsid_lookup: Dict[str, str] | None = None,
+    source_wsids: Dict[str, str] | None = None,
+    input_modids: Set[str] | None = None,
+) -> List[Dict[str, Any]]:
+    """Translate mlos_sort warnings to the SORTOF_DATA WARNINGS shape.
+
+    wsid_lookup: optional {mod_id -> workshop_id} map of *deps* we already
+    have cached. When provided, each 'missing' warning is augmented with
+    `actions: [{type: "add-wsid", wsid, label}]` so the frontend can render
+    a click-to-add button. Unknown deps fall back to a Steam Workshop search
+    link the user follows manually.
+
+    source_wsids: optional {mod_id -> workshop_id} map of *every cached mod
+    in the current sort*. Used to attach the source mod's wsid onto
+    'missing' / 'conflict' warnings so the frontend can deep-link to the
+    Workshop page of the mod that's complaining.
+    """
+    lookup = wsid_lookup or {}
+    sources = source_wsids or {}
+    out: List[Dict[str, Any]] = []
+    for path in mlos_warnings.get("cycles", []) or []:
+        out.append({
+            "tag": "cycle",
+            "level": "red",
+            "msg": "cycle: " + " → ".join(path),
+        })
+    satisfied_via_alias = _resolve_satisfied_via_alias(input_modids or set())
+    for mod_id, deps in (mlos_warnings.get("missing_requirements") or {}).items():
+        # Drop deps that the user already has via an alias (e.g.
+        # `truemusic` is satisfied if the user has `TrueMoozic`). If every
+        # listed dep is satisfied via alias, skip the warning entirely.
+        deps = [d for d in deps if d not in satisfied_via_alias]
+        if not deps:
+            continue
+        actions: List[Dict[str, str]] = []
+        for dep in deps:
+            wsid = lookup.get(dep)
+            if wsid:
+                actions.append({
+                    "type": "add-wsid",
+                    "wsid": wsid,
+                    "modId": dep,
+                    "label": f"add {dep}",
+                })
+            else:
+                # No cache hit -> link to Steam Workshop search so the user
+                # can find the wsid manually. PZ appid is 108600.
+                from urllib.parse import quote_plus
+                actions.append({
+                    "type": "search-workshop",
+                    "modId": dep,
+                    "url": (
+                        "https://steamcommunity.com/workshop/browse/"
+                        f"?appid=108600&searchtext={quote_plus(dep)}"
+                    ),
+                    "label": f"find {dep}",
+                })
+        src_wsid = sources.get(mod_id)
+        # When we know the source mod's wsid, the warning's leading mod name
+        # is hyperlinked to the source's Workshop page (which lists every
+        # required item natively). The 'find …' Steam Workshop search action
+        # is redundant in that case (returns noisy generic results), so drop
+        # it; keep concrete 'add <wsid>' actions for cache-resolved deps.
+        if src_wsid:
+            actions = [a for a in actions if a.get("type") != "search-workshop"]
+        warn: Dict[str, Any] = {
+            "tag": "missing",
+            "level": "red",
+            "msg": f"{mod_id} requires {', '.join(deps)} - not in your list.",
+        }
+        if src_wsid:
+            warn["wsid"] = src_wsid
+        if actions:
+            warn["actions"] = actions
+        out.append(warn)
+    for mod_id, ene in (mlos_warnings.get("incompatible_enabled") or {}).items():
+        warn = {
+            "tag": "conflict",
+            "level": "amber",
+            "msg": f"{mod_id} marked incompatible with {', '.join(ene)}.",
+        }
+        src_wsid = sources.get(mod_id)
+        if src_wsid:
+            warn["wsid"] = src_wsid
+        out.append(warn)
+    return out
+
+
+# ── Spec C §4: branch flavoring + prefix-base + suffix-token utilities ──
+
+# Build flavor detection for Rule A. Matches:
+#  - "B42" / "B41" at end-of-string when preceded by a separator (`_`, `-`,
+#    space, start-of-string) OR a lowercase letter (CamelCase boundary like
+#    "ArmorB42").
+#  - "_b42" / "_b41" at end (snake_case).
+#  - "_b42_" / "_b41_" mid-string token.
+#  - "_legacy_" anywhere -> B41 (legacy is always old-build behavior).
+_RE_B41 = re.compile(
+    r"_legacy_"
+    r"|(?:^|[_\- ]|(?<=[a-z]))[Bb]41$"
+    r"|_[Bb]41(?:[_\- ]|$)"
+)
+_RE_B42 = re.compile(
+    r"(?:^|[_\- ]|(?<=[a-z]))[Bb]42$"
+    r"|_[Bb]42(?:[_\- ]|$)"
+)
+
+
+def _build_flavor(mod_id: str) -> Optional[str]:
+    """Return 'B41' / 'B42' / None per Spec C §4.3 suffix rule."""
+    if not mod_id:
+        return None
+    if _RE_B41.search(mod_id):
+        return "B41"
+    if _RE_B42.search(mod_id):
+        return "B42"
+    return None
+
+
+def _strict_prefix_of(a: str, b: str) -> bool:
+    """`a` is a strict prefix of `b` per Spec C §4.4: a != b, b starts with a,
+    boundary char is non-lowercase-letter (separator/digit/uppercase)."""
+    if not a or not b or a == b or not b.startswith(a):
+        return False
+    boundary = b[len(a)]
+    return boundary in "_- " or boundary.isdigit() or boundary.isupper()
+
+
+def _prefix_base(group: List[ModInfo]) -> ModInfo:
+    """Return the branch whose mod_id is a strict prefix of every other branch
+    in `group` (the 'core'/'main'). Falls back to alphabetical-first if no
+    such universal prefix exists. Spec C §4.4."""
+    sorted_grp = sorted(group, key=lambda m: m.id)
+    for cand in sorted_grp:
+        if all(_strict_prefix_of(cand.id, m.id) for m in sorted_grp if m.id != cand.id):
+            return cand
+    return sorted_grp[0]
+
+
+# Spec C §4.6 hint patterns. Order matters: first match wins.
+_HINT_PATTERNS: List[Tuple[re.Pattern, str]] = [
+    (re.compile(r"_legacy_", re.IGNORECASE),                    "legacy build - usually not what you want"),
+    (re.compile(r"_v\d+(?:_\d+)*$", re.IGNORECASE),             "legacy build - usually not what you want"),
+    (re.compile(r"(?:_lite|_light)$", re.IGNORECASE),           "lighter alternate variant - pick one"),
+    (re.compile(r"(?:_hd|_detailshd)$", re.IGNORECASE),         "high-resolution variant"),
+    (re.compile(r"_(?:noce|novanilla|farmdisable|disable[a-z]*)$", re.IGNORECASE),
+                                                                "opt-out variant"),
+    (re.compile(r"_(?:usdm|imports|exotics|realnames)$", re.IGNORECASE),
+                                                                "alternate variant - pick one"),
+]
+
+
+def _branch_hint(mod_id: str) -> Optional[str]:
+    """Return the hint text per Spec C §4.6 D/G patterns, or None."""
+    if not mod_id:
+        return None
+    hits: List[str] = []
+    for pat, text in _HINT_PATTERNS:
+        if pat.search(mod_id):
+            hits.append(text)
+    return " · ".join(dict.fromkeys(hits)) if hits else None
+
+
+def _suffix_token(mod_id: str, base_id: str) -> Optional[str]:
+    """For Rule C: extract the trailing token after the last `_` if mod_id is
+    a `<base>_<TOKEN>` form. Returns None for one-letter tokens (`_a`, `_x`).
+    Two-letter tokens like `_AZ` (AuthenticZ patch) and `_GG` are kept - the
+    user's spec parenthetical excludes only one-letter false positives."""
+    if not mod_id or not base_id or mod_id == base_id:
+        return None
+    if "_" not in mod_id:
+        return None
+    suffix = mod_id.rsplit("_", 1)[-1]
+    if len(suffix) < 2:
+        return None
+    return suffix
+
+
+def _input_match_terms(mod_id: str) -> Set[str]:
+    """Build the set of search terms for one input mod_id, used by Rule C.
+
+    Produces both:
+      - normalized form (lowercase + alphanumeric only) -> substring match
+      - acronym (first letters of CamelCase / whitespace-separated tokens,
+        lowercased) -> covers cases like "Authentic Z - Current" where the
+        token `_AZ` is the initials, not a literal substring.
+    """
+    out: Set[str] = set()
+    if not mod_id:
+        return out
+    out.add(re.sub(r"[^a-z0-9]+", "", mod_id.lower()))
+    pieces: List[str] = []
+    for chunk in re.split(r"[^A-Za-z0-9]+", mod_id):
+        if not chunk:
+            continue
+        # CamelCase split: each capital-led run is a piece, plus trailing lowercase runs.
+        parts = re.findall(r"[A-Z]+[a-z0-9]*|[a-z0-9]+", chunk)
+        pieces.extend(parts)
+    if pieces:
+        acro = "".join(p[0].lower() for p in pieces if p and p[0].isalnum())
+        if len(acro) >= 2:
+            out.add(acro)
+    return out
+
+
+def _apply_branch_rules(
+    mods: List[ModInfo],
+    *,
+    pz_build: str,
+    input_modids: Set[str],
+    is_resort: bool = False,
+    selected_modids: Optional[Set[str]] = None,
+) -> Tuple[Set[str], List[Dict[str, Any]], Dict[str, str]]:
+    """Spec C §4 auto-disambiguation pipeline.
+
+    Returns (drop_ids, warnings, hints). drop_ids = mod_ids to filter out of
+    SORTED_ORDER/MODS_LINE. hints = {mod_id -> hint_text} for picker rows.
+
+    Order per wsid: detect coordinated/radio (exempt), then A → C → B.
+    A and C may both fire (orthogonal axes). B is the auto-pick fallback.
+
+    `input_modids` is the full set across the user's input. Rule C excludes
+    same-wsid mod_ids when matching to avoid self-references (a wsid's
+    branches would otherwise always match each other's tokens).
+    """
+    by_wsid: Dict[str, List[ModInfo]] = {}
+    for m in mods:
+        wsid = m.workshop_id or ""
+        if not wsid:
+            continue
+        by_wsid.setdefault(wsid, []).append(m)
+    # Per-wsid mod_id sets so Rule C can exclude same-wsid siblings.
+    modids_by_wsid: Dict[str, Set[str]] = {
+        w: {m.id for m in g} for w, g in by_wsid.items()
+    }
+
+    drop_ids: Set[str] = set()
+    warnings: List[Dict[str, Any]] = []
+    hints: Dict[str, str] = {}
+    pz_build = (pz_build or "").upper() if pz_build else "B42"
+    if pz_build not in ("B41", "B42"):
+        pz_build = "B42"
+
+    for wsid, group in by_wsid.items():
+        if len(group) < 2:
+            continue
+
+        ids_in_group = {m.id for m in group}
+
+        # Exemption 0: ADDON wsid — at least one mod self-identifies as an
+        # "Optional add-on" (mod.info description) and at least one mod
+        # doesn't. Treat as additive: primaries stay in MODS_LINE by default,
+        # addons land in drop_ids so the user has to explicitly tick them in
+        # the picker. Picker is naturally checkbox-mode (no incompatibles
+        # between siblings), so toggling lights addons up.
+        #
+        # Resort path: user's explicit selection wins. Drop addons NOT in
+        # the user's selection; keep those they ticked.
+        addon_mods = [m for m in group if m.is_addon]
+        primary_mods = [m for m in group if not m.is_addon]
+        if addon_mods and primary_mods:
+            for m in addon_mods:
+                if not is_resort:
+                    drop_ids.add(m.id)
+                elif selected_modids is not None and m.id not in selected_modids:
+                    drop_ids.add(m.id)
+                hints[m.id] = "addon"
+            for m in primary_mods:
+                hints[m.id] = "main"
+            continue
+
+
+        # Exemption 1: radio-mode (incompatibleMods sibling). Picker handles.
+        radio = any(
+            any(other in ids_in_group for other in m.incompatibleMods)
+            for m in group
+        )
+        if radio:
+            continue
+
+        # Exemption 2: coordinated (cross-refs in requirements/loadAfter/loadBefore).
+        coordinated = any(
+            any(other in ids_in_group for other in m.requirements)
+            or any(other in ids_in_group for other in m.loadAfter)
+            or any(other in ids_in_group for other in m.loadBefore)
+            for m in group
+        )
+        if coordinated:
+            # Coordinated wsids stay whole BY DEFAULT, but if a prefix-base
+            # exists and a non-base addon branch declares an EXTERNAL require
+            # (a mod_id not in the wsid's siblings) that isn't in input_modids,
+            # drop the addon. The author's `require=` here means "this addon
+            # only makes sense if you have the external mod"; if you don't,
+            # the addon shouldn't be in the load order. Suppresses the
+            # would-be missing-dep warning at the same time (post-build_warnings
+            # filter strips warnings whose source mod_id is in drop_ids).
+            base_candidates = [
+                m for m in group
+                if any(_strict_prefix_of(m.id, o.id) for o in group if o.id != m.id)
+            ]
+            if base_candidates:
+                base = max(base_candidates, key=lambda m: len(m.id))
+                for m in group:
+                    if m.id == base.id:
+                        continue
+                    externals = [r for r in m.requirements if r not in ids_in_group]
+                    if externals and not all(r in input_modids for r in externals):
+                        drop_ids.add(m.id)
+            for m in group:
+                h = _branch_hint(m.id)
+                if h:
+                    hints[m.id] = h
+            continue
+
+        # Truly ambiguous: apply A → C → B.
+        title = (group[0].name or wsid)
+        kept_by_a: Optional[ModInfo] = None
+        kept_by_c: List[ModInfo] = []
+
+        # ── Rule A: build-aware default ─────────────────────────────────
+        flavored = [(m, _build_flavor(m.id)) for m in group]
+        match_active = [m for m, fl in flavored if fl == pz_build]
+        opposite_build = "B41" if pz_build == "B42" else "B42"
+        match_opposite = [m for m, fl in flavored if fl == opposite_build]
+        unflavored = [m for m, fl in flavored if fl is None]
+
+        if len(match_active) == 1 and len(group) - 1 == len(match_opposite) + len(unflavored):
+            # Exactly one branch matches active build; rest are opposite/unflavored.
+            kept_by_a = match_active[0]
+        elif not match_active and match_opposite:
+            # No active-build variant exists -> author-default fallback (un-flavored
+            # treated as B42), emit build-mismatch.
+            warnings.append({
+                "tag": "build-mismatch",
+                "level": "amber",
+                "msg": (
+                    f"no {pz_build} variant for {title} ({wsid}); using author default"
+                ),
+                "wsid": wsid,
+            })
+
+        # ── Rule C: input cross-reference ───────────────────────────────
+        # Identify the base branch (longest mod_id that is a strict prefix
+        # of any other) -- if multiple branches share an _<TOKEN>_ form.
+        base_candidates = [
+            m for m in group
+            if any(_strict_prefix_of(m.id, other.id) for other in group if other.id != m.id)
+        ]
+        rule_c_base: Optional[ModInfo] = None
+        if base_candidates:
+            # Pick the longest base that's a prefix of any sibling (i.e., the
+            # most-specific shared root). For Jeeve's: `JeevesPatches` qualifies.
+            rule_c_base = max(base_candidates, key=lambda m: len(m.id))
+            # Cross-reference set: every input mod_id EXCEPT the ones from
+            # this wsid (otherwise sibling branches always match each other).
+            same_wsid_ids = modids_by_wsid.get(wsid, set())
+            other_modids = input_modids - same_wsid_ids
+            # Two flavors of search term per input mod_id: the normalized
+            # form (substring match) and the acronym (first letters - so
+            # token "AZ" matches "Authentic Z - Current"). See _input_match_terms.
+            norm_input: Set[str] = set()
+            for mid in other_modids:
+                norm_input.update(_input_match_terms(mid))
+            unticked_addons: List[str] = []
+            for m in group:
+                if m is rule_c_base:
+                    continue
+                tok = _suffix_token(m.id, rule_c_base.id)
+                if not tok:
+                    continue
+                tok_l = re.sub(r"[^a-z0-9]+", "", tok.lower())
+                if not tok_l:
+                    continue
+                hit = any(tok_l in mid_norm for mid_norm in norm_input)
+                if hit:
+                    kept_by_c.append(m)
+                else:
+                    unticked_addons.append(m.id)
+            if kept_by_c:
+                # Always include the base alongside matched addons.
+                if rule_c_base not in kept_by_c:
+                    kept_by_c = [rule_c_base] + kept_by_c
+            elif any(_suffix_token(m.id, rule_c_base.id) for m in group if m is not rule_c_base):
+                # Suffix-tokened branches exist but none matched - emit warning.
+                # `picked`/`alternatives` reuse the auto-picked-branch shape
+                # so the WarnRow renders an inline picker (the warning's
+                # "tick any you want" is otherwise unreachable from the
+                # warnings panel).
+                if unticked_addons:
+                    warnings.append({
+                        "tag": "unmatched-addons",
+                        "level": "amber",
+                        "msg": (
+                            f"{title} ({wsid}) ships addons for other mods you "
+                            f"don't have: {', '.join(unticked_addons[:8])}"
+                            + (" …" if len(unticked_addons) > 8 else "")
+                            + ". Tick any you want:"
+                        ),
+                        "wsid": wsid,
+                        "picked": rule_c_base.id,
+                        "alternatives": [m.id for m in group],
+                    })
+
+        # ── Resolve which set of branches is kept ───────────────────────
+        # A and C are orthogonal: build-flavor pick + addon picks both apply.
+        kept_set: Set[str] = set()
+        if kept_by_a:
+            kept_set.add(kept_by_a.id)
+        if kept_by_c:
+            for m in kept_by_c:
+                kept_set.add(m.id)
+
+        if not kept_set:
+            # Rule B fallback: prefix-base if available, else alphabetical first.
+            primary = _prefix_base(group)
+            kept_set.add(primary.id)
+            skipped = [m.id for m in group if m.id != primary.id]
+            warnings.append({
+                "tag": "auto-picked-branch",
+                "level": "amber",
+                "msg": (
+                    f"{title} ({wsid}) ships {len(group)} branches; auto-picked "
+                    f"{primary.id}. Pick another:"
+                ),
+                "wsid": wsid,
+                "picked": primary.id,
+                "alternatives": [m.id for m in group],
+            })
+
+        # Resort-mode override: the user has explicitly picked branches via
+        # the picker. Replace the rules' kept_set with the user's selection
+        # restricted to this group, and update the matching auto-picked-
+        # branch warning's `picked` field so the picker UI shows their
+        # current choice ticked. Without this, narrowing a multi-branch
+        # wsid to one branch erases the picker section because the warning
+        # was tied to the rule's auto-pick, not the user's pick.
+        if is_resort and selected_modids is not None:
+            user_picks = [m.id for m in group if m.id in selected_modids]
+            if user_picks:
+                kept_set = set(user_picks)
+                for w in warnings:
+                    if (w.get("tag") == "auto-picked-branch"
+                            and w.get("wsid") == wsid):
+                        w["picked"] = user_picks[0]
+                        w["msg"] = (
+                            f"{title} ({wsid}) ships {len(group)} branches; "
+                            f"selected {user_picks[0]}. Pick another:"
+                        )
+
+        for m in group:
+            if m.id not in kept_set:
+                drop_ids.add(m.id)
+            h = _branch_hint(m.id)
+            if h:
+                hints[m.id] = h
+
+    return (drop_ids, warnings, hints)
+
+
+# Backwards-compat shim used by existing call sites that don't yet pass
+# pz_build/input_modids. Removed once all callers migrate.
+def _autopick_ambiguous(mods: List[ModInfo]) -> Tuple[Set[str], List[Dict[str, Any]]]:
+    drop_ids, warns, _hints = _apply_branch_rules(
+        mods, pz_build="B42", input_modids={m.id for m in mods},
+    )
+    return (drop_ids, warns)
+
+
+def build_response(
+    input_ids: List[str],
+    hit_ids: List[str],
+    mods: List[ModInfo],
+    sort_result: Dict[str, Any],
+    status: str,
+    wsid_lookup: Dict[str, str] | None = None,
+    pz_build: str = "B42",
+    is_resort: bool = False,
+    selected_modids: Optional[Set[str]] = None,
+) -> Dict[str, Any]:
+    by_id = {m.id: m for m in mods}
+    sorted_order: List[str] = list(sort_result.get("Mods", []))
+    workshop_line_parts: List[str] = list(sort_result.get("WorkshopItems", []))
+    map_folders: List[str] = list(sort_result.get("Map", []))
+
+    # MAP_LINE composition rules:
+    #   1. Hoisted bases (MAP_FIRST) at the FRONT, in the listed order.
+    #      These are library/parent map cells that many other map mods
+    #      overlay onto; they must load before everything else for the
+    #      dependents to attach correctly.
+    #   2. Remaining modded map folders, in mod-load order.
+    #   3. Vanilla Muldraugh, KY at the end ALWAYS.
+    BASE_MAP = "Muldraugh, KY"
+    MAP_FIRST = ("map_distanciado",)
+    map_line_parts: List[str] = []
+    seen_maps: set = set()
+    map_folder_set = set(map_folders)
+    for m in MAP_FIRST:
+        if m in map_folder_set and m not in seen_maps:
+            seen_maps.add(m)
+            map_line_parts.append(m)
+    for m in map_folders:
+        if m and m not in seen_maps:
+            seen_maps.add(m)
+            map_line_parts.append(m)
+    if BASE_MAP not in seen_maps:
+        map_line_parts.append(BASE_MAP)
+
+    # Spec C §4: build-aware + input-cross-reference + prefix-base auto-pick.
+    # MOD_DB still contains every cached branch so the picker can offer
+    # alternates; SORTED_ORDER and MODS_LINE reflect the rule output only.
+    input_modids = {m.id for m in mods}
+    drop_ids, autopick_warnings, hints = _apply_branch_rules(
+        mods, pz_build=pz_build or "B42", input_modids=input_modids,
+        is_resort=is_resort, selected_modids=selected_modids,
+    )
+    # Resort path: `sorted_order` already reflects the user's explicit
+    # selection (sort_mods ran on the selected subset); the drop_ids from
+    # _apply_branch_rules are for MOD_DB picker visibility, not for filtering
+    # out user-selected mods.
+    if not is_resort:
+        sorted_order = [mid for mid in sorted_order if mid not in drop_ids]
+
+    def _modentry(m: ModInfo) -> Dict[str, Any]:
+        entry: Dict[str, Any] = {
+            "wsid": m.workshop_id or "",
+            "modId": m.id,
+            "name": m.name or m.id,
+            "cat": to_frontend_cat(m.category),
+            "deps": list(m.requirements),
+            "conflicts": list(m.incompatibleMods),
+            "pos": position(m.loadFirst, m.loadLast),
+            "isMap": bool(m.maps),
+            "mapName": m.maps[0] if m.maps else None,
+        }
+        h = hints.get(m.id)
+        if h:
+            entry["hint"] = h
+        return entry
+
+    mod_db: List[Dict[str, Any]] = []
+    seen_in_db: set = set()
+    for mod_id in sorted_order:
+        m = by_id.get(mod_id)
+        if m is None:
+            continue
+        seen_in_db.add(mod_id)
+        mod_db.append(_modentry(m))
+    # Append auto-skipped branches so the picker can show them as alternatives.
+    # They aren't in SORTED_ORDER, so the table doesn't render rows for them
+    # directly - they only surface inside their parent wsid's BranchPicker.
+    for mod_id in sorted(drop_ids):
+        m = by_id.get(mod_id)
+        if m is None or mod_id in seen_in_db:
+            continue
+        mod_db.append(_modentry(m))
+
+    hit_set = set(hit_ids)
+    pending = [w for w in input_ids if w not in hit_set]
+
+    # Filter out missing-dep warnings whose SOURCE mod_id was dropped by
+    # _apply_branch_rules. Rationale: if we silently dropped, e.g.,
+    # fhqExpVehSpawnRedRace because its external require RedRacer wasn't
+    # in input, the would-be "fhqExpVehSpawnRedRace requires RedRacer" warning
+    # is just noise — that mod isn't in the user's effective load order
+    # anymore. Pattern-match the leading source mod_id on each warning.
+    # Map each cached mod_id to its source wsid so build_warnings can attach
+    # `wsid` onto missing/conflict warnings (lets the UI deep-link to the
+    # Workshop page of the mod that's actually complaining).
+    source_wsids = {m.id: m.workshop_id for m in mods if m.workshop_id}
+    raw_warnings = build_warnings(
+        sort_result.get("warnings", {}) or {},
+        wsid_lookup,
+        source_wsids=source_wsids,
+        input_modids=input_modids,
+    )
+    if drop_ids:
+        kept_warnings: List[Dict[str, Any]] = []
+        for w in raw_warnings:
+            if w.get("tag") not in ("missing", "conflict"):
+                kept_warnings.append(w)
+                continue
+            m = re.match(r"^([A-Za-z0-9_+\-]{2,})\s+", w.get("msg", ""))
+            if m and m.group(1) in drop_ids:
+                continue  # source mod_id was dropped → suppress its warning
+            kept_warnings.append(w)
+        raw_warnings = kept_warnings
+
+    return {
+        "status": status,
+        "MOD_DB": mod_db,
+        "SORTED_ORDER": sorted_order,
+        "WORKSHOP_ITEMS_LINE": ";".join(workshop_line_parts),
+        "MODS_LINE": ";".join(sorted_order),
+        "MAP_LINE": ";".join(map_line_parts),
+        "WARNINGS": raw_warnings + autopick_warnings,
+        "pending": pending,
+    }
diff --git a/api/app.py b/api/app.py
new file mode 100644
index 0000000..1859632
--- /dev/null
+++ b/api/app.py
@@ -0,0 +1,1480 @@
+"""sortof FastAPI service.
+
+Loopback-only (bound 127.0.0.1) HTTP API that accepts a Steam Workshop input
+blob, looks up cached mod metadata in Postgres, runs mlos_sort over the
+hit subset, and returns SORTOF_DATA-shaped JSON. Cache misses are queued
+into download_jobs for the worker to fulfill.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import time
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+import httpx
+from dotenv import load_dotenv
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel, Field
+
+import adapters
+import db
+import expansion
+import jobs
+import steam
+from mlos_sort import ModInfo, parse_sorting_rules, sort_mods
+from parse import parse_with_collections, parse_workshop_input
+
+# Load .env before reading SORTOF_CORS_ORIGINS so dev/manual runs (no systemd
+# EnvironmentFile) still pick it up. systemd-injected env wins by default
+# because load_dotenv does not override pre-set variables.
+load_dotenv(Path(__file__).resolve().parent.parent / ".env")
+
+_cors_raw = os.getenv("SORTOF_CORS_ORIGINS", "").strip()
+CORS_ORIGINS = [o.strip() for o in _cors_raw.split(",") if o.strip()] or [
+    "http://127.0.0.1:8801",
+]
+
+MAX_IDS = 500
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(name)s %(message)s",
+)
+log = logging.getLogger("sortof.api")
+
+
+# Path to the human-edited PZ version-label file. Checked into the repo so
+# updates are visible in git history (vs. a hidden .env). The API loads it
+# at startup; bumping the labels requires a `systemctl restart sortof-api`.
+_PZ_VERSIONS_PATH = Path(__file__).resolve().parent.parent / "data" / "pz_versions.json"
+
+
+def _load_pz_versions() -> Dict[str, str]:
+    """Read pz_versions.json and return {branch_key: human_label}. Drops
+    any keys starting with '_' (those are inline documentation)."""
+    import json
+    try:
+        raw = json.loads(_PZ_VERSIONS_PATH.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as e:
+        log.warning("pz_versions.json load failed: %s", e)
+        return {}
+    return {k: v for k, v in raw.items() if not k.startswith("_") and isinstance(v, str)}
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    pool = await db.create_pool()
+    http = httpx.AsyncClient(timeout=30.0)
+    app.state.db = pool
+    app.state.http = http
+    app.state.pending_tasks = set()
+    app.state.pz_versions = _load_pz_versions()
+    async with pool.acquire() as conn:
+        n_reaped = await jobs.sweep_stale_expansions(conn)
+        if n_reaped:
+            log.info("lifespan startup: reaped %d stale expansion job(s)", n_reaped)
+    log.info(
+        "sortof.api started (pz_versions: %s)",
+        ", ".join(f"{k}={v}" for k, v in app.state.pz_versions.items()) or "(none)",
+    )
+    try:
+        yield
+    finally:
+        await http.aclose()
+        await pool.close()
+        log.info("sortof.api stopped")
+
+
+app = FastAPI(title="sortof API", lifespan=lifespan)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=CORS_ORIGINS,
+    allow_credentials=False,
+    allow_methods=["POST", "GET", "OPTIONS"],
+    allow_headers=["Content-Type"],
+)
+
+
+class SortRequest(BaseModel):
+    input: str = Field(default="")
+    rules: Optional[str] = Field(default=None)
+    # Spec C §2: PZ build context. "B41" or "B42"; default "B42" when missing
+    # or unrecognized. Drives Rule A (build-aware default) in adapters.
+    pz_build: Optional[str] = Field(default=None)
+
+
+class ResortRequest(BaseModel):
+    selected_mod_ids: List[str] = Field(default_factory=list)
+    # Same semantics as SortRequest.pz_build. Forwarded so resort can emit
+    # build-mismatch warnings (the user's pzBuild state on the frontend
+    # doesn't change between /api/sort and /api/resort, but resort runs in
+    # isolation server-side without the original job's pz_build).
+    pz_build: Optional[str] = Field(default=None)
+    # Original /api/sort input wsids (the user's "subscription set").
+    # Resort needs them for wsid-keyed warnings — build-mismatch et al.
+    # are per-wsid, but resort only knows mod_ids, and mod_id ↔ wsid
+    # isn't 1:1 when a mod_id has been evicted to a different wsid in the
+    # cache (common for B41 ↔ B42 pairs that share a mod_id).
+    input_wsids: List[str] = Field(default_factory=list)
+
+
+def _strip_path_prefix(deps) -> List[str]:
+    """Defensively normalize dep names. Strips leading backslashes (B42 path
+    syntax: `\\StarlitLibrary` -> `StarlitLibrary`) and trims whitespace.
+    Worker._split_csv applies this at parse time, but ~14 mod_parsed rows
+    in the live DB were written before that fix landed and will only refresh
+    when their wsid's time_updated advances on Steam. Normalizing here keeps
+    missing-dep matching correct against legacy rows."""
+    out: List[str] = []
+    for d in (deps or []):
+        s = (d or "").strip().lstrip("\\")
+        if s:
+            out.append(s)
+    return out
+
+
+def _inject_addon_loadafter(mods: List[ModInfo]) -> None:
+    """For each multi-mod wsid that has both addons and primaries, append the
+    primary's mod_id to each addon's `loadAfter`. The topo sort honours
+    loadAfter, so when the user explicitly ticks an addon (via the picker
+    + resort), MODS_LINE places it after the primary.
+
+    Spec A's _apply_branch_rules drops the addon from MODS_LINE BY DEFAULT
+    (so this injection is mostly a safety net for the resort path); when
+    the user adds it back, ordering is preserved without any picker logic.
+    """
+    by_wsid: Dict[str, List[ModInfo]] = {}
+    for m in mods:
+        if m.workshop_id:
+            by_wsid.setdefault(m.workshop_id, []).append(m)
+    for group in by_wsid.values():
+        if len(group) < 2:
+            continue
+        addons = [m for m in group if m.is_addon]
+        primaries = [m for m in group if not m.is_addon]
+        if not addons or not primaries:
+            continue
+        # Pick a single primary to anchor against. Most addon wsids have
+        # exactly one main mod; if there are multiple, alphabetical picks
+        # a stable target. The order between primaries themselves stays
+        # however the topo sort decides.
+        primary_id = sorted(p.id for p in primaries)[0]
+        for addon in addons:
+            if primary_id not in addon.loadAfter:
+                addon.loadAfter = list(addon.loadAfter) + [primary_id]
+
+
+def _row_to_modinfo(r) -> ModInfo:
+    """Build a ModInfo from a mod_parsed row. Used by both /api/sort and
+    /api/resort; columns must match the SELECT in both endpoints."""
+    return ModInfo(
+        id=r["mod_id"],
+        name=r["name"] or r["mod_id"],
+        workshop_id=r["workshop_id"],
+        category=r["category"] or "undefined",
+        requirements=_strip_path_prefix(r["requirements"]),
+        loadAfter=_strip_path_prefix(r["load_after"]),
+        loadBefore=_strip_path_prefix(r["load_before"]),
+        incompatibleMods=_strip_path_prefix(r["incompatible_mods"]),
+        loadFirst=r["load_first"] or "off",
+        loadLast=r["load_last"] or "off",
+        tags=list(r["tags"] or []),
+        maps=list(r["maps"] or []),
+        is_addon=bool(r["is_addon"]) if "is_addon" in r else False,
+        workshop_tags=list(r["workshop_tags"] or []) if "workshop_tags" in r else [],
+    )
+
+
+def _ordered_wsids_line(payload: Dict[str, Any], all_wsids: List[str]) -> str:
+    """Compose WORKSHOP_ITEMS_LINE: load-order wsids that have at least one
+    mod in SORTED_ORDER, then append every other input wsid (unknown,
+    non_mod, all-branches-deselected) in input order. Spec A §8 ownership
+    is preserved (set unchanged), Spec C §2 behavior is honored (order
+    follows the current sort).
+
+    Returns a string with trailing ';' to match the existing PZ ini convention.
+    """
+    sorted_order = payload.get("SORTED_ORDER", []) or []
+    mod_to_wsid: Dict[str, str] = {
+        entry["modId"]: entry.get("wsid") or ""
+        for entry in (payload.get("MOD_DB") or [])
+    }
+    seen: set = set()
+    ordered: List[str] = []
+    for mid in sorted_order:
+        w = mod_to_wsid.get(mid)
+        if w and w not in seen:
+            seen.add(w)
+            ordered.append(w)
+    for w in (all_wsids or []):
+        if w and w not in seen:
+            seen.add(w)
+            ordered.append(w)
+    return ";".join(ordered) + ";" if ordered else ""
+
+
+async def _lookup_wsids_for_missing(
+    conn,
+    mlos_warnings: Dict[str, Any],
+    pz_build: Optional[str] = None,
+) -> Dict[str, str]:
+    """Resolve missing-requirement mod_ids to wsids via mod_parsed cache.
+
+    Returns {mod_id -> workshop_id} for any missing dep we've previously
+    cached. Used to render an [add to list] action button next to the
+    'missing' warning. Unknown deps just get no button.
+
+    pz_build filters out wrong-build resolutions: if the user is on B42 and
+    the only cached wsid for `dep` is tagged `Build 41` only, we DROP the
+    suggestion. Adding it would just trigger a build-mismatch warning;
+    worse, in cases like `TacHold requires modoptions` where the author's
+    `require=` is over-declared, the suggestion misleads the user toward
+    a B41 mod that doesn't actually need to be in the load order.
+    """
+    missing = mlos_warnings.get("missing_requirements") or {}
+    if not missing:
+        return {}
+    wanted: set = set()
+    for deps in missing.values():
+        for d in deps:
+            if d:
+                wanted.add(d)
+    if not wanted:
+        return {}
+    rows = await conn.fetch(
+        """
+        SELECT DISTINCT ON (mp.mod_id) mp.mod_id, mp.workshop_id, wm.tags
+          FROM mod_parsed mp
+          JOIN workshop_meta wm ON wm.workshop_id = mp.workshop_id
+         WHERE mp.mod_id = ANY($1::text[])
+         ORDER BY mp.mod_id, mp.parsed_at_time_updated DESC
+        """,
+        list(wanted),
+    )
+    target_tag = "Build 42" if pz_build == "B42" else (
+        "Build 41" if pz_build == "B41" else None
+    )
+    other_tag = "Build 41" if target_tag == "Build 42" else (
+        "Build 42" if target_tag == "Build 41" else None
+    )
+    out: Dict[str, str] = {}
+    for r in rows:
+        if target_tag and other_tag:
+            tags = list(r["tags"] or [])
+            if other_tag in tags and target_tag not in tags:
+                # Wrong-build only — adding it would just trigger a
+                # build-mismatch. Skip the suggestion.
+                continue
+        out[r["mod_id"]] = r["workshop_id"]
+    return out
+
+
+# Hand-curated build-version pairs where the B41↔B42 sibling renamed its
+# mod_id (so the auto-discovery via shared mod_id can't find it). Bidirectional
+# - if the user submits either side, the OTHER side is offered. Add entries as
+# you encounter them; the worker's mod_id-based detection covers anything that
+# kept the same mod_id across builds.
+MANUAL_BUILD_PAIRS: Dict[str, str] = {
+    # truemusic (B41) ↔ TrueMoozic (B42). Author renamed mod_id between
+    # builds; B42 wsid bundles a TMMumble addon as a second mod_id.
+    "2613146550": "3632610172",
+    "3632610172": "2613146550",
+}
+
+
+async def _find_swap_candidate(
+    conn,
+    wsid: str,
+    target_tag: str,
+    exclude_wsids: List[str],
+) -> Optional[Dict[str, str]]:
+    """Find a sibling Workshop ID that publishes any of `wsid`'s mod_ids and
+    is tagged for `target_tag` (typically the build the user picked).
+
+    Used to attach a "swap to <other>" action onto build-mismatch warnings.
+    Many mod authors maintain two separate wsids — one B41, one B42 — that
+    share the same mod_id (e.g. tsarslib at 2392709985 and 3402491515).
+    Cross-referencing via mod_id finds those pairs without an explicit map.
+
+    Sources for "wsid X's mod_ids":
+      1. mod_parsed (current owner).
+      2. mod_id_conflicts left/right side (X has been an evictor or evicted
+         party for some mod_id, meaning it once owned that mod_id).
+      3. MANUAL_BUILD_PAIRS for cases where the author renamed the mod_id.
+
+    Returns {wsid, title} or None if no usable sibling found.
+    """
+    # Manual override first: explicit cross-build pairs we curate by hand.
+    paired = MANUAL_BUILD_PAIRS.get(wsid)
+    if paired and paired not in set(exclude_wsids):
+        row = await conn.fetchrow(
+            """
+            SELECT workshop_id, title FROM workshop_meta
+             WHERE workshop_id = $1 AND $2 = ANY(tags)
+            """,
+            paired, target_tag,
+        )
+        if row:
+            return {"wsid": row["workshop_id"], "title": row["title"]}
+    rows = await conn.fetch(
+        """
+        WITH x_mod_ids AS (
+            SELECT mod_id FROM mod_parsed WHERE workshop_id = $1
+            UNION
+            SELECT mod_id FROM mod_id_conflicts
+             WHERE evicted_wsid = $1 OR evicting_wsid = $1
+        ),
+        candidates AS (
+            SELECT DISTINCT workshop_id AS wsid
+              FROM mod_parsed
+             WHERE mod_id IN (SELECT mod_id FROM x_mod_ids)
+               AND workshop_id <> $1
+            UNION
+            SELECT DISTINCT evicting_wsid
+              FROM mod_id_conflicts
+             WHERE mod_id IN (SELECT mod_id FROM x_mod_ids)
+               AND evicted_wsid = $1
+            UNION
+            SELECT DISTINCT evicted_wsid
+              FROM mod_id_conflicts
+             WHERE mod_id IN (SELECT mod_id FROM x_mod_ids)
+               AND evicting_wsid = $1
+        )
+        SELECT c.wsid, wm.title
+          FROM candidates c
+          JOIN workshop_meta wm ON wm.workshop_id = c.wsid
+         WHERE wm.consumer_app_id = 108600
+           AND $2 = ANY(wm.tags)
+           AND NOT (wm.workshop_id = ANY($3::text[]))
+         ORDER BY wm.title
+         LIMIT 1
+        """,
+        wsid, target_tag, list(exclude_wsids),
+    )
+    if not rows:
+        return None
+    return {"wsid": rows[0]["wsid"], "title": rows[0]["title"]}
+
+
+# Visible warning order: most actionable first. Build-mismatch leads (lets
+# the user resolve build issues before chasing other warnings); next come
+# the picker-driving warnings (auto-picked-branch, unmatched-addons) so
+# the multi-option selection UI sits at the top of the panel; then the
+# duplicate-mod_id / missing / conflict / cycle warnings.
+_WARNING_TAG_PRIORITY: Dict[str, int] = {
+    "build-mismatch":     0,
+    "auto-picked-branch": 1,
+    "unmatched-addons":   1,
+    "duplicate-mod_id":   2,
+    "missing":            3,
+    "conflict":           4,
+    "cycle":              5,
+}
+
+
+def _reorder_warnings(payload: Dict[str, Any]) -> None:
+    """Stable-sort `payload['WARNINGS']` by tag priority. Warnings sharing
+    a priority bucket keep their original relative order."""
+    warnings = payload.get("WARNINGS") or []
+    if not warnings:
+        return
+    payload["WARNINGS"] = sorted(
+        warnings,
+        key=lambda w: _WARNING_TAG_PRIORITY.get(w.get("tag", ""), 99),
+    )
+
+
+async def _emit_build_mismatch_warnings(
+    conn,
+    payload: Dict[str, Any],
+    input_wsids: List[str],
+    pz_build: str,
+) -> None:
+    """Emit `build-mismatch` warnings for cached input wsids whose Steam-side
+    Build tags don't include the requested build.
+
+    `workshop_meta.tags` is Steam's controlled vocabulary — `Build 41` /
+    `Build 42` are the canonical signal. Three cases per wsid:
+      - both builds tagged → multi-build, no warn
+      - only the OPPOSITE build tagged → wrong build, emit warn
+      - neither build tagged → author didn't mark, can't tell, no warn
+      - only the TARGET build tagged → fine, no warn
+
+    Multi-branch wsids already get their own `build-mismatch` from
+    `adapters._apply_branch_rules` (Spec C); skip wsids with an existing
+    one to avoid double-warning.
+    """
+    if not input_wsids or pz_build not in ("B41", "B42"):
+        return
+    rows = await conn.fetch(
+        """
+        SELECT workshop_id, title, tags
+          FROM workshop_meta
+         WHERE workshop_id = ANY($1::text[])
+        """,
+        list(input_wsids),
+    )
+    target_tag = "Build 41" if pz_build == "B41" else "Build 42"
+    other_tag = "Build 42" if pz_build == "B41" else "Build 41"
+    existing = payload.get("WARNINGS") or []
+    already_flagged = {
+        w.get("wsid") for w in existing
+        if w.get("tag") == "build-mismatch" and w.get("wsid")
+    }
+    new_warnings: List[Dict[str, Any]] = []
+    for r in rows:
+        wsid = r["workshop_id"]
+        if wsid in already_flagged:
+            continue
+        tags = list(r["tags"] or [])
+        if target_tag in tags:
+            continue  # supports the picked build
+        if other_tag not in tags:
+            continue  # author didn't tag a build, can't tell
+        title = r["title"] or wsid
+        warn: Dict[str, Any] = {
+            "tag": "build-mismatch",
+            "level": "amber",
+            "msg": (
+                f"{title} ({wsid}) is tagged {other_tag} only — "
+                f"may not work with {target_tag}."
+            ),
+            "wsid": wsid,
+        }
+        actions: List[Dict[str, Any]] = []
+        # Look for a target-build sibling that shares any of this mod's
+        # mod_ids (the typical "B41 wsid" + "B42 wsid" pair pattern).
+        swap = await _find_swap_candidate(
+            conn, wsid, target_tag, list(input_wsids),
+        )
+        if swap:
+            actions.append({
+                "type": "swap-wsid",
+                "from": wsid,
+                "to": swap["wsid"],
+                "label": f"swap to {swap['title']}",
+            })
+        # Always offer a one-click drop for wrong-build mods. Useful when no
+        # target-build sibling exists (the swap action is missing) or when
+        # the user just wants to drop it without searching for a replacement.
+        actions.append({
+            "type": "remove-wsid",
+            "wsid": wsid,
+            "label": "remove",
+        })
+        warn["actions"] = actions
+        new_warnings.append(warn)
+    if not new_warnings:
+        return
+    # Build-mismatched mods are about to be removed or swapped, so any
+    # `missing` warnings they sourced are noise: they'd push the user
+    # toward adding deps for a mod they're about to drop. Filter those
+    # out, but keep other warnings on the same wsid (auto-picked-branch,
+    # duplicate-mod_id, etc. are still meaningful).
+    mismatch_wsids = {w["wsid"] for w in new_warnings}
+    filtered = [
+        w for w in existing
+        if not (w.get("tag") == "missing" and w.get("wsid") in mismatch_wsids)
+    ]
+    # Build-mismatch entries lead the list so the user resolves the
+    # build-version question before chasing other warnings.
+    payload["WARNINGS"] = new_warnings + filtered
+
+
+async def _augment_with_required_items(
+    conn,
+    payload: Dict[str, Any],
+    input_wsids: List[str],
+) -> None:
+    """Mutate `payload["WARNINGS"]` in place: for each missing-dep warning
+    whose source mod has Steam-side Required Items in `workshop_meta`,
+    append `add-wsid` actions for any required wsid not already in the
+    user's input or already represented as an action.
+
+    Steam's anonymous GetPublishedFileDetails does NOT expose `children`
+    for individual mods, so the worker scrapes the public Workshop page
+    and stores the result in `workshop_meta.required_wsids`. This lets us
+    one-click resolve missing deps that aren't yet in the user's cache —
+    which is exactly the case the search-workshop fallback handled poorly.
+    """
+    warnings = payload.get("WARNINGS") or []
+    missing = [w for w in warnings if w.get("tag") == "missing" and w.get("wsid")]
+    if not missing:
+        return
+    src_wsids = list({w["wsid"] for w in missing})
+    rows = await conn.fetch(
+        """
+        SELECT wm.workshop_id AS src_wsid, req.req_wsid
+          FROM workshop_meta wm,
+               unnest(wm.required_wsids) AS req(req_wsid)
+         WHERE wm.workshop_id = ANY($1::text[])
+        """,
+        src_wsids,
+    )
+    if not rows:
+        return
+    pairs: Dict[str, List[str]] = {}
+    all_req: set = set()
+    for r in rows:
+        pairs.setdefault(r["src_wsid"], []).append(r["req_wsid"])
+        all_req.add(r["req_wsid"])
+    # Best-available human label for each required wsid:
+    #   1. mod_parsed.name (cached + parsed) — preferred
+    #   2. workshop_meta.title (cached, even if mod hasn't been parsed yet)
+    #   3. fall back to the bare wsid
+    label_rows = await conn.fetch(
+        """
+        SELECT wm.workshop_id,
+               wm.title,
+               (SELECT mp.name FROM mod_parsed mp
+                  JOIN workshop_meta wm2 ON wm2.workshop_id = mp.workshop_id
+                 WHERE mp.workshop_id = wm.workshop_id
+                   AND mp.parsed_at_time_updated = wm2.time_updated
+                 ORDER BY mp.parsed_at DESC LIMIT 1) AS parsed_name,
+               (SELECT mp.mod_id FROM mod_parsed mp
+                  JOIN workshop_meta wm2 ON wm2.workshop_id = mp.workshop_id
+                 WHERE mp.workshop_id = wm.workshop_id
+                   AND mp.parsed_at_time_updated = wm2.time_updated
+                 ORDER BY mp.parsed_at DESC LIMIT 1) AS parsed_mod_id
+          FROM workshop_meta wm
+         WHERE wm.workshop_id = ANY($1::text[])
+        """,
+        list(all_req),
+    )
+    labels: Dict[str, Dict[str, Optional[str]]] = {
+        r["workshop_id"]: {
+            "title": r["title"],
+            "mod_id": r["parsed_mod_id"],
+            "name": r["parsed_name"],
+        }
+        for r in label_rows
+    }
+    input_set = set(input_wsids or [])
+    for w in missing:
+        existing_wsids = {
+            a.get("wsid") for a in (w.get("actions") or [])
+            if a.get("type") == "add-wsid" and a.get("wsid")
+        }
+        actions = list(w.get("actions") or [])
+        for req_wsid in pairs.get(w["wsid"], []):
+            if req_wsid in input_set or req_wsid in existing_wsids:
+                continue
+            info = labels.get(req_wsid) or {}
+            # Prefer the Workshop listing title (one canonical name per wsid)
+            # over `parsed_name` — multi-branch wsids would otherwise pick an
+            # arbitrary branch's name, which is confusing. mod_id is a useful
+            # last resort for compactness; bare wsid only when nothing exists.
+            label_text = (info.get("title") or info.get("name")
+                          or info.get("mod_id") or req_wsid)
+            actions.append({
+                "type": "add-wsid",
+                "wsid": req_wsid,
+                "modId": info.get("mod_id") or "",
+                "label": f"add {label_text}",
+            })
+            existing_wsids.add(req_wsid)
+        if actions:
+            w["actions"] = actions
+
+
+async def _lookup_mod_id_conflicts(
+    conn,
+    input_wsids: List[str],
+) -> List[Dict[str, Any]]:
+    """Surface mod_id ownership conflicts where the user's input includes a
+    wsid that lost a claim on a mod_id to another wsid.
+
+    Walks `mod_id_conflicts` (recorded by worker.py at parse-time eviction)
+    and filters to rows where:
+      - evicted_wsid is in the user's input, AND
+      - the evicted wsid hasn't subsequently re-claimed the mod_id (i.e., no
+        current mod_parsed row for (evicted_wsid, mod_id)).
+
+    Reports the *current* owner (looked up from mod_parsed) rather than the
+    historical evicting_wsid; multiple evictions can chain (Y→Z→W), and the
+    user cares about who's loaded right now. Two flavors:
+      - amber: current owner is also in input → mod is loaded, just not from
+        the wsid the user might have expected.
+      - red:   current owner is NOT in input → mod is silently missing.
+    """
+    if not input_wsids:
+        return []
+    rows = await conn.fetch(
+        """
+        SELECT DISTINCT ON (mc.mod_id, mc.evicted_wsid)
+               mc.mod_id,
+               mc.evicted_wsid,
+               mc.evicting_wsid,
+               (SELECT mp.workshop_id
+                  FROM mod_parsed mp
+                 WHERE mp.mod_id = mc.mod_id
+                 LIMIT 1) AS current_owner
+          FROM mod_id_conflicts mc
+         WHERE mc.evicted_wsid = ANY($1::text[])
+           AND NOT EXISTS (
+               SELECT 1 FROM mod_parsed mp
+                WHERE mp.workshop_id = mc.evicted_wsid
+                  AND mp.mod_id      = mc.mod_id
+           )
+         ORDER BY mc.mod_id, mc.evicted_wsid, mc.recorded_at DESC
+        """,
+        list(input_wsids),
+    )
+    if not rows:
+        return []
+    input_set = set(input_wsids)
+    out: List[Dict[str, Any]] = []
+    for r in rows:
+        mod_id = r["mod_id"]
+        evicted = r["evicted_wsid"]
+        # Prefer the live cache owner; fall back to the historically-evicting
+        # wsid if the mod_id has since been fully de-cached (e.g., manual
+        # force-repull recipe). Either way the user's wsid lost its claim.
+        owner = r["current_owner"] or r["evicting_wsid"]
+        if owner in input_set:
+            out.append({
+                "tag": "duplicate-mod_id",
+                "level": "amber",
+                "msg": (
+                    f"Mod '{mod_id}' is published by both wsid {evicted} and "
+                    f"wsid {owner}; loaded copy is from {owner}."
+                ),
+                "wsid": evicted,
+                "mod_id": mod_id,
+                "evicting_wsid": owner,
+            })
+        else:
+            out.append({
+                "tag": "duplicate-mod_id",
+                "level": "red",
+                "msg": (
+                    f"Mod '{mod_id}' is missing: wsid {evicted} declares it, "
+                    f"but the cache holds wsid {owner}'s copy. "
+                    f"Add {owner} to your input to load '{mod_id}'."
+                ),
+                "wsid": evicted,
+                "mod_id": mod_id,
+                "evicting_wsid": owner,
+            })
+    return out
+
+
+async def _build_result_for_job(
+    conn,
+    wsids: List[str],
+    rules_raw: Optional[str],
+    pz_build: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Compute the SORTOF_DATA payload from currently-cached mod_parsed rows
+    for the given wsids. Used both for partial results during draining and
+    for the final result on phase transition to 'done'."""
+    if not wsids:
+        return _empty_payload([], "success")
+    rows = await conn.fetch(
+        """
+        SELECT mp.workshop_id, mp.mod_id, mp.name, mp.category,
+               mp.requirements, mp.load_after, mp.load_before,
+               mp.incompatible_mods, mp.load_first, mp.load_last,
+               mp.tags, mp.maps, mp.is_addon, wm.tags AS workshop_tags
+          FROM mod_parsed mp
+          JOIN workshop_meta wm ON wm.workshop_id = mp.workshop_id
+         WHERE mp.workshop_id = ANY($1::text[])
+           AND mp.parsed_at_time_updated = wm.time_updated
+         ORDER BY mp.workshop_id, mp.mod_id
+        """,
+        wsids,
+    )
+    mods = [_row_to_modinfo(r) for r in rows]
+    rules: Dict[str, Any] = {}
+    if rules_raw:
+        try:
+            rules = parse_sorting_rules(rules_raw)
+        except Exception:
+            log.warning("job result: failed to parse sorting_rules")
+    _inject_addon_loadafter(mods)
+    sort_result = sort_mods(mods, rules)
+    cached_ids = {r["workshop_id"] for r in rows}
+    wsid_lookup = await _lookup_wsids_for_missing(
+        conn, sort_result.get("warnings", {}) or {},
+        pz_build=pz_build,
+    )
+    conflict_warnings = await _lookup_mod_id_conflicts(conn, wsids)
+    payload = adapters.build_response(
+        input_ids=wsids,
+        hit_ids=list(cached_ids),
+        mods=mods,
+        sort_result=sort_result,
+        status="success" if len(cached_ids) >= len(wsids) else "partial",
+        wsid_lookup=wsid_lookup,
+        pz_build=pz_build or "B42",
+    )
+    if conflict_warnings:
+        payload["WARNINGS"] = list(payload.get("WARNINGS") or []) + conflict_warnings
+    await _augment_with_required_items(conn, payload, wsids)
+    if pz_build:
+        await _emit_build_mismatch_warnings(conn, payload, wsids, pz_build)
+    _reorder_warnings(payload)
+    # Spec A §8 ownership: WORKSHOP_ITEMS_LINE preserves the SET of input
+    # wsids regardless of which are cached/non-mod/unknown. Within that set,
+    # order them by the load position of their first mod (so toggling
+    # branches that change wsid load position visibly reorders the line).
+    # Wsids without any mod in SORTED_ORDER (yet-to-cache, non_mod, unknown)
+    # tail at the end in their original input order.
+    payload["WORKSHOP_ITEMS_LINE"] = _ordered_wsids_line(payload, wsids)
+    # Surface terminal-failed wsids so the polling-path payload mirrors the
+    # sync path's unknown/non_mod arrays. Without this, jobs with broken or
+    # non-mod children would lack diagnostic info even after reaching `done`.
+    failed_rows = await conn.fetch(
+        """
+        SELECT DISTINCT ON (workshop_id) workshop_id, status, error
+        FROM download_jobs
+        WHERE workshop_id = ANY($1::text[])
+        ORDER BY workshop_id, updated_at DESC
+        """,
+        wsids,
+    )
+    non_mod_set: set = set()
+    unknown_set: set = set()
+    for r in failed_rows:
+        if r["status"] != "failed":
+            continue
+        if r["error"] == "process_one=no_mod_info":
+            non_mod_set.add(r["workshop_id"])
+        else:
+            unknown_set.add(r["workshop_id"])
+    payload["non_mod"] = [w for w in wsids if w in non_mod_set]
+    payload["unknown"] = [w for w in wsids if w in unknown_set]
+    payload["pending"] = [
+        w for w in wsids
+        if w not in cached_ids and w not in non_mod_set and w not in unknown_set
+    ]
+    return payload
+
+
+def _empty_payload(input_ids: List[str], status: str) -> Dict[str, Any]:
+    return {
+        "status": status,
+        "MOD_DB": [],
+        "SORTED_ORDER": [],
+        "WORKSHOP_ITEMS_LINE": "",
+        "MODS_LINE": "",
+        "MAP_LINE": None,
+        "WARNINGS": [],
+        "pending": list(input_ids),
+        "unknown": [],
+        "non_mod": [],
+    }
+
+
+@app.get("/healthz")
+async def healthz() -> Dict[str, bool]:
+    return {"ok": True}
+
+
+async def _route_to_job(
+    request: Request,
+    conn,
+    input_raw: str,
+    rules_raw: Optional[str],
+    bare_wsids: List[str],
+    collection_ids: List[str],
+    queue_wsids: Optional[List[str]] = None,
+    pz_build: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Create a sort_jobs row and (if needed) kick off background expansion.
+    Returns {status, job_id} for the client to start polling.
+
+    queue_wsids: explicit subset of wsids to insert into download_jobs.
+    If None, every deduped bare wsid is queued (legacy default). Callers that
+    have already classified hit/miss MUST pass only the misses, otherwise
+    already-cached wsids get redundantly redownloaded.
+    """
+    if collection_ids:
+        # Will resolve in the background.
+        job_id = await jobs.create_job(
+            conn,
+            input_raw=input_raw,
+            collection_ids=collection_ids,
+            wsids=None,
+            rules_raw=rules_raw,
+            initial_phase="expanding",
+            pz_build=pz_build,
+        )
+        task = asyncio.create_task(expansion.run_expansion(
+            request.app.state.db,
+            request.app.state.http,
+            job_id,
+            bare_wsids,
+            collection_ids,
+        ))
+        request.app.state.pending_tasks.add(task)
+        task.add_done_callback(request.app.state.pending_tasks.discard)
+        log.info(
+            "routed to job=%s phase=expanding bare=%d collections=%d",
+            job_id, len(bare_wsids), len(collection_ids),
+        )
+        return {"status": "expanding", "job_id": job_id}
+    else:
+        # Bare wsids, some uncached. Dedupe; queue only the requested subset.
+        seen: set = set()
+        wsids: List[str] = []
+        for w in bare_wsids:
+            if w not in seen:
+                seen.add(w)
+                wsids.append(w)
+        job_id = await jobs.create_job(
+            conn,
+            input_raw=input_raw,
+            collection_ids=[],
+            wsids=wsids,
+            rules_raw=rules_raw,
+            initial_phase="queued",
+            pz_build=pz_build,
+        )
+        targets = list(queue_wsids) if queue_wsids is not None else wsids
+        for wid in targets:
+            async with conn.transaction():
+                existing = await conn.fetchval(
+                    "SELECT 1 FROM download_jobs "
+                    "WHERE workshop_id = $1 AND status IN ('queued','downloading') LIMIT 1",
+                    wid,
+                )
+                if existing is None:
+                    await conn.execute(
+                        "INSERT INTO download_jobs (workshop_id, status) VALUES ($1, 'queued')",
+                        wid,
+                    )
+        log.info(
+            "routed to job=%s phase=queued wsids=%d targets=%d",
+            job_id, len(wsids), len(targets),
+        )
+        return {"status": "queued", "job_id": job_id}
+
+
+@app.post("/api/sort")
+async def sort_endpoint(req: SortRequest, request: Request) -> Dict[str, Any]:
+    t0 = time.monotonic()
+    bare_wsids, collection_ids = parse_with_collections(req.input or "")
+    input_ids = bare_wsids  # backwards-compat alias for the existing sync flow
+    if not bare_wsids and not collection_ids:
+        raise HTTPException(status_code=400, detail="no workshop ids found in input")
+    # NOTE: bound is on user-input cardinality; a collection that resolves
+    # to >MAX_IDS children is allowed (post-expansion cap is out of scope).
+    if len(bare_wsids) + len(collection_ids) > MAX_IDS:
+        raise HTTPException(
+            status_code=413,
+            detail=f"too many workshop ids ({len(bare_wsids) + len(collection_ids)} > {MAX_IDS})",
+        )
+
+    log.info(
+        "sort received bare=%d collections=%d",
+        len(bare_wsids), len(collection_ids),
+    )
+
+    # ── B+F: collections present → route to async job immediately, no Steam call.
+    # expansion.run_expansion handles GetCollectionDetails + cache + drain queueing.
+    if collection_ids:
+        pool = request.app.state.db
+        async with pool.acquire() as conn:
+            return await _route_to_job(
+                request, conn, req.input or "", req.rules,
+                bare_wsids, collection_ids,
+                pz_build=req.pz_build or "B42",
+            )
+
+    http: httpx.AsyncClient = request.app.state.http
+    try:
+        steam_details = await steam.fetch_workshop_details(http, input_ids)
+    except httpx.HTTPError as e:
+        log.warning("steam api error: %s", e)
+        elapsed_ms = int((time.monotonic() - t0) * 1000)
+        log.info(
+            "sort done hits=0 misses=%d status=error ms=%d",
+            len(input_ids), elapsed_ms,
+        )
+        return _empty_payload(input_ids, "error")
+
+    pool = request.app.state.db
+    hit_ids: List[str] = []
+    miss_ids: List[str] = []
+    unknown_ids: List[str] = []   # Steam returned result != 1 (deleted, typo'd, private)
+    non_mod_ids: List[str] = []   # Steam confirmed but DD found no mod.info (collection, art, etc.)
+    valid_steam: Dict[str, dict] = {}
+
+    async with pool.acquire() as conn:
+        for wid in input_ids:
+            d = steam_details.get(wid)
+            if not d or d.get("result") != 1:
+                unknown_ids.append(wid)
+                miss_ids.append(wid)
+                continue
+            valid_steam[wid] = d
+            tu = int(d.get("time_updated", 0))
+            row = await conn.fetchrow(
+                "SELECT 1 FROM mod_parsed "
+                "WHERE workshop_id = $1 AND parsed_at_time_updated = $2 LIMIT 1",
+                wid, tu,
+            )
+            if row is not None:
+                hit_ids.append(wid)
+            else:
+                miss_ids.append(wid)
+
+        # Detect non-mod items: Steam-valid wsids whose most-recent download_jobs
+        # row failed with the no_mod_info reason (drain confirmed DD pulled no
+        # parseable .info file). Surfaces collections, art, etc., separately
+        # from real "still being indexed" pending items.
+        valid_miss_ids = [w for w in miss_ids if w in valid_steam]
+        if valid_miss_ids:
+            non_mod_rows = await conn.fetch(
+                """
+                SELECT DISTINCT ON (workshop_id) workshop_id, status, error
+                FROM download_jobs
+                WHERE workshop_id = ANY($1::text[])
+                ORDER BY workshop_id, updated_at DESC
+                """,
+                valid_miss_ids,
+            )
+            for r in non_mod_rows:
+                if r["status"] == "failed" and r["error"] == "process_one=no_mod_info":
+                    non_mod_ids.append(r["workshop_id"])
+
+        # ── B+F: route to async job if any wsid needs drain time.
+        # The job's GET endpoint will surface unknown/non_mod via its own
+        # response shape; the sync path remains for fully-cached input.
+        # `hit_ids` only contains wsids confirmed cached; anything else
+        # (unknown OR uncached-but-valid) is reason to switch to a job.
+        if len(hit_ids) < len(bare_wsids):
+            # Match the sync path's queue predicate: skip Steam-unknown wsids
+            # AND skip wsids the drain has already classified as non-mods.
+            # Without this filter, every cache miss including known-bad ones
+            # gets queued, plus any cached wsids upstream of an unknown would
+            # also get re-queued (the bug we're fixing).
+            non_mod_set_route = set(non_mod_ids)
+            queue_targets = [
+                w for w in miss_ids
+                if w in valid_steam and w not in non_mod_set_route
+            ]
+            return await _route_to_job(
+                request, conn, req.input or "", req.rules,
+                bare_wsids, [],   # collection_ids empty - already short-circuited above
+                queue_wsids=queue_targets,
+                pz_build=req.pz_build or "B42",
+            )
+
+        # Queue cache misses (only those Steam confirmed exist AND aren't
+        # already known to be non-mods - re-queueing those is pointless).
+        non_mod_set = set(non_mod_ids)
+        for wid in miss_ids:
+            if wid not in valid_steam:
+                log.info("skip queue for unknown wsid=%s", wid)
+                continue
+            if wid in non_mod_set:
+                log.info("skip queue for non-mod wsid=%s", wid)
+                continue
+            async with conn.transaction():
+                existing = await conn.fetchval(
+                    "SELECT 1 FROM download_jobs "
+                    "WHERE workshop_id = $1 AND status IN ('queued','downloading') "
+                    "LIMIT 1",
+                    wid,
+                )
+                if existing is None:
+                    await conn.execute(
+                        "INSERT INTO download_jobs (workshop_id, status) "
+                        "VALUES ($1, 'queued')",
+                        wid,
+                    )
+
+        if hit_ids:
+            rows = await conn.fetch(
+                """
+                SELECT mp.workshop_id, mp.mod_id, mp.name, mp.category,
+                       mp.requirements, mp.load_after, mp.load_before,
+                       mp.incompatible_mods, mp.load_first, mp.load_last,
+                       mp.tags, mp.maps, mp.is_addon, wm.tags AS workshop_tags
+                FROM mod_parsed mp
+                JOIN workshop_meta wm ON wm.workshop_id = mp.workshop_id
+                WHERE mp.workshop_id = ANY($1::text[])
+                  AND mp.parsed_at_time_updated = wm.time_updated
+                ORDER BY mp.workshop_id, mp.mod_id
+                """,
+                hit_ids,
+            )
+        else:
+            rows = []
+
+    mods: List[ModInfo] = [_row_to_modinfo(r) for r in rows]
+
+    rules: Dict[str, Any] = {}
+    if req.rules:
+        try:
+            rules = parse_sorting_rules(req.rules)
+        except Exception:
+            log.warning("failed to parse sorting_rules; ignoring")
+            rules = {}
+
+    _inject_addon_loadafter(mods)
+    sort_result = sort_mods(mods, rules)
+
+    if not hit_ids:
+        status = "cold"
+    elif len(hit_ids) == len(input_ids):
+        status = "success"
+    else:
+        status = "partial"
+
+    async with pool.acquire() as conn:
+        wsid_lookup = await _lookup_wsids_for_missing(
+            conn, sort_result.get("warnings", {}) or {},
+            pz_build=req.pz_build or "B42",
+        )
+        conflict_warnings = await _lookup_mod_id_conflicts(conn, input_ids)
+    payload = adapters.build_response(
+        input_ids=input_ids,
+        hit_ids=hit_ids,
+        mods=mods,
+        sort_result=sort_result,
+        status=status,
+        wsid_lookup=wsid_lookup,
+        pz_build=req.pz_build or "B42",
+    )
+    if conflict_warnings:
+        payload["WARNINGS"] = list(payload.get("WARNINGS") or []) + conflict_warnings
+    async with pool.acquire() as conn:
+        await _augment_with_required_items(conn, payload, input_ids)
+        await _emit_build_mismatch_warnings(
+            conn, payload, input_ids, req.pz_build or "B42",
+        )
+    _reorder_warnings(payload)
+    # Surface ghost / non-mod IDs separately from real pending so the UI can
+    # distinguish "indexing 2 mods" from "2 of your IDs are deleted/typo'd"
+    # and "1 of your IDs is a collection, not a mod."
+    payload["unknown"] = unknown_ids
+    payload["non_mod"] = non_mod_ids
+    # Trim them out of pending so each ID lives in exactly one category.
+    excluded = set(unknown_ids) | set(non_mod_ids)
+    payload["pending"] = [w for w in payload.get("pending", []) if w not in excluded]
+    # Spec A §8 + Spec C §2: load-order wsids that landed in the sort, then
+    # tail of unknown/non_mod (preserves the user's subscription set). Without
+    # this the sync path's WORKSHOP_ITEMS_LINE would silently drop them.
+    payload["WORKSHOP_ITEMS_LINE"] = _ordered_wsids_line(payload, input_ids)
+
+    elapsed_ms = int((time.monotonic() - t0) * 1000)
+    log.info(
+        "sort done hits=%d misses=%d unknown=%d non_mod=%d status=%s ms=%d",
+        len(hit_ids), len(miss_ids), len(unknown_ids), len(non_mod_ids), status, elapsed_ms,
+    )
+    return payload
+
+
+def _merge_warnings(seeded: Optional[Dict[str, Any]], fresh: Dict[str, Any]) -> Dict[str, Any]:
+    """Merge any pre-seeded WARNINGS (e.g., 'collection-partial' from expansion)
+    into a freshly-computed result payload. Seeded warnings come first to
+    preserve "this happened earlier" ordering. Dedupes by (tag, msg)."""
+    seeded_warnings = (seeded or {}).get("WARNINGS") or []
+    fresh_warnings = fresh.get("WARNINGS") or []
+    if not seeded_warnings:
+        return fresh
+    seen = set()
+    merged: List[Dict[str, Any]] = []
+    for w in list(seeded_warnings) + list(fresh_warnings):
+        key = (w.get("tag", ""), w.get("msg", ""))
+        if key in seen:
+            continue
+        seen.add(key)
+        merged.append(w)
+    fresh["WARNINGS"] = merged
+    return fresh
+
+
+@app.get("/api/jobs/{job_id}")
+async def get_job_endpoint(job_id: str, request: Request) -> Dict[str, Any]:
+    pool = request.app.state.db
+    async with pool.acquire() as conn:
+        row = await jobs.get_job_row(conn, job_id)
+        if row is None:
+            raise HTTPException(status_code=404, detail="job not found or expired")
+        wsids = list(row["wsids"]) if row["wsids"] else None
+        counts = await jobs.compute_counts(conn, wsids or [])
+        phase = jobs.derive_phase(row["phase"], wsids, counts)
+
+        result_json = row["result_json"]
+        job_pz_build = row.get("pz_build")
+        if phase == "done" and row["phase"] != "done":
+            # Job just completed. Compute fresh and persist, but preserve
+            # any expansion-seeded warnings (e.g., 'collection-partial').
+            fresh = await _build_result_for_job(
+                conn, wsids, row["rules_raw"], pz_build=job_pz_build,
+            )
+            result_json = _merge_warnings(row["result_json"], fresh)
+            await jobs.update_phase(
+                conn, job_id, "done", result_json=result_json,
+            )
+        elif phase != "done" and wsids:
+            # Mid-flight partial: compute fresh on every poll, also merging
+            # in any seeded warnings so the client sees them throughout.
+            # Don't persist; only `done` transitions write result_json.
+            fresh = await _build_result_for_job(
+                conn, wsids, row["rules_raw"], pz_build=job_pz_build,
+            )
+            result_json = _merge_warnings(row["result_json"], fresh)
+
+    # `counts` is {cached, queued, draining, terminal_failed} - additive
+    # extension of the Spec B+F §6 contract. JS clients ignore the extra key.
+    return {
+        "job_id":         str(row["job_id"]),
+        "phase":          phase,
+        "counts":         counts,
+        "wsids":          wsids,
+        "result":         result_json,
+        "failure_reason": row["failure_reason"],
+    }
+
+
+@app.delete("/api/jobs/{job_id}", status_code=204)
+async def delete_job_endpoint(job_id: str, request: Request):
+    """Cancel a job. Idempotent: cancelling a terminal job is a no-op 204.
+    Does NOT touch download_jobs (Spec B+F §8)."""
+    try:
+        uid = UUID(job_id)
+    except ValueError:
+        raise HTTPException(status_code=404, detail="job not found")
+    pool = request.app.state.db
+    async with pool.acquire() as conn:
+        # Single SQL: race-safe - a no-op when the row is missing OR terminal.
+        result = await conn.execute(
+            """
+            UPDATE sort_jobs
+               SET phase = 'failed',
+                   failure_reason = 'cancelled',
+                   phase_started_at = now()
+             WHERE job_id = $1
+               AND phase NOT IN ('done', 'failed')
+            """,
+            uid,
+        )
+        # If 0 rows updated, either the row didn't exist OR was already terminal.
+        # Disambiguate so we still return 404 for nonexistent jobs.
+        if result == "UPDATE 0":
+            exists = await conn.fetchval(
+                "SELECT 1 FROM sort_jobs WHERE job_id = $1", uid,
+            )
+            if exists is None:
+                raise HTTPException(status_code=404, detail="job not found")
+        log.info("delete_job %s -> failed/cancelled (or no-op terminal)", job_id)
+    return None
+
+
+@app.post("/api/resort")
+async def resort_endpoint(req: ResortRequest, request: Request) -> Dict[str, Any]:
+    """Re-run mlos_sort against a user-supplied subset of mod_ids.
+
+    Stateless. No Steam round-trip. Filters mod_parsed by the requested
+    mod_ids, runs sort_mods, returns the same shape as /api/sort.
+    """
+    t0 = time.monotonic()
+    ids = list(req.selected_mod_ids or [])
+
+    if not ids:
+        raise HTTPException(status_code=400, detail="selected_mod_ids must be non-empty")
+    if len(ids) > MAX_IDS:
+        raise HTTPException(status_code=413, detail=f"too many mod_ids ({len(ids)} > {MAX_IDS})")
+    for i, mod_id in enumerate(ids):
+        if not isinstance(mod_id, str) or not (1 <= len(mod_id) <= 256):
+            raise HTTPException(
+                status_code=400,
+                detail=f"invalid mod_id at index {i}: must be a string of length 1-256",
+            )
+
+    pool = request.app.state.db
+    async with pool.acquire() as conn:
+        # Fetch ALL mod_ids of any wsid that has at least one selected mod_id.
+        # _apply_branch_rules needs the full group context to keep emitting
+        # auto-picked-branch warnings (the picker UI is data-driven from
+        # those warnings). Without the siblings, narrowing a multi-branch
+        # wsid to one branch would silently hide the picker.
+        rows = await conn.fetch(
+            """
+            WITH selected_wsids AS (
+                SELECT DISTINCT mp.workshop_id
+                  FROM mod_parsed mp
+                  JOIN workshop_meta wm ON wm.workshop_id = mp.workshop_id
+                 WHERE mp.mod_id = ANY($1::text[])
+                   AND mp.parsed_at_time_updated = wm.time_updated
+            )
+            SELECT mp.workshop_id, mp.mod_id, mp.name, mp.category,
+                   mp.requirements, mp.load_after, mp.load_before,
+                   mp.incompatible_mods, mp.load_first, mp.load_last,
+                   mp.tags, mp.maps, mp.is_addon, wm.tags AS workshop_tags
+            FROM mod_parsed mp
+            JOIN workshop_meta wm ON wm.workshop_id = mp.workshop_id
+            WHERE mp.workshop_id IN (SELECT workshop_id FROM selected_wsids)
+              AND mp.parsed_at_time_updated = wm.time_updated
+            ORDER BY mp.workshop_id, mp.mod_id
+            """,
+            ids,
+        )
+
+    selected_set = set(ids)
+    found_selected = {r["mod_id"] for r in rows if r["mod_id"] in selected_set}
+    missing = [mid for mid in ids if mid not in found_selected]
+    if missing:
+        log.info("resort dropped unknown mod_ids count=%d sample=%s",
+                 len(missing), missing[:3])
+    if not rows:
+        raise HTTPException(status_code=400, detail="no known mod_ids in selection")
+
+    all_mods: List[ModInfo] = [_row_to_modinfo(r) for r in rows]
+    selected_mods: List[ModInfo] = [m for m in all_mods if m.id in selected_set]
+    _inject_addon_loadafter(selected_mods)
+    # Sort over the user's explicit selection so SORTED_ORDER reflects only
+    # what they ticked. _apply_branch_rules below still sees the full group
+    # via `mods=all_mods`, so it can emit picker-driving warnings.
+    sort_result = sort_mods(selected_mods, {})
+    # Per spec review #12: silently drop unknown mod_ids and return status="success".
+    # The frontend reconciles its sent list against MOD_DB to detect drops.
+    async with pool.acquire() as conn:
+        wsid_lookup = await _lookup_wsids_for_missing(
+            conn, sort_result.get("warnings", {}) or {},
+            pz_build=req.pz_build or "B42",
+        )
+    payload = adapters.build_response(
+        input_ids=[],
+        hit_ids=ids,
+        mods=all_mods,
+        sort_result=sort_result,
+        status="success",
+        wsid_lookup=wsid_lookup,
+        pz_build=req.pz_build or "B42",
+        is_resort=True,
+        selected_modids=selected_set,
+    )
+    # Resort operates on a known mod_id set - there's no concept of a
+    # "still-being-fetched" wsid here. With input_ids=[] above, build_response
+    # already produces pending=[]; this is explicit defense against future
+    # build_response changes.
+    payload["pending"] = []
+    # The frontend owns unknown/non_mod from the original /api/sort response
+    # for the lifetime of the result set (same ownership contract as
+    # WORKSHOP_ITEMS_LINE, see sortContextRef). Resort returns empty arrays;
+    # the client overrides them.
+    payload["unknown"] = []
+    payload["non_mod"] = []
+    # Emit the same secondary warnings /api/sort and the polling path do.
+    # Without these, every resort (e.g., branch toggle) wipes build-mismatch
+    # / duplicate-mod_id / required-item augmentations from the warnings
+    # panel — the user-visible "warnings disappear" bug.
+    # Prefer the original sort's input wsids (the user's subscription set)
+    # for wsid-keyed warnings. Mod_id-derived wsids omit B41 wsids whose
+    # mod_id has since been evicted to a B42 sibling, dropping legitimate
+    # build-mismatch warnings the user expects to keep seeing across resort.
+    derived_wsids = {m.workshop_id for m in selected_mods if m.workshop_id}
+    resort_wsids = list({*(req.input_wsids or []), *derived_wsids})
+    if resort_wsids:
+        async with pool.acquire() as conn:
+            conflict_warnings = await _lookup_mod_id_conflicts(conn, resort_wsids)
+            await _augment_with_required_items(conn, payload, resort_wsids)
+            if req.pz_build:
+                await _emit_build_mismatch_warnings(
+                    conn, payload, resort_wsids, req.pz_build,
+                )
+        if conflict_warnings:
+            payload["WARNINGS"] = list(payload.get("WARNINGS") or []) + conflict_warnings
+    _reorder_warnings(payload)
+
+    elapsed_ms = int((time.monotonic() - t0) * 1000)
+    log.info(
+        "resort done count=%d dropped=%d ms=%d",
+        len(rows), len(missing), elapsed_ms,
+    )
+    return payload
+
+
+# ── Broken-mod report board ────────────────────────────────────────────────
+
+
+class BrokenModReportRequest(BaseModel):
+    workshop_id: str = Field(..., min_length=1, max_length=32)
+    version: str = Field(..., min_length=1, max_length=32)
+
+
+class BrokenModVoteRequest(BaseModel):
+    direction: str = Field(..., pattern=r"^(up|down)$")
+
+
+@app.get("/api/pz-versions")
+async def pz_versions_endpoint(request: Request) -> Dict[str, str]:
+    """Branch-key → human-readable build label. Source: data/pz_versions.json
+    loaded at lifespan startup. Frontend dropdown reads from here."""
+    return dict(request.app.state.pz_versions or {})
+
+
+@app.get("/api/broken-mods")
+async def list_broken_mods(
+    request: Request,
+    q: Optional[str] = None,
+    limit: int = 100,
+) -> List[Dict[str, Any]]:
+    """List reports newest-first. `q` filters by wsid substring."""
+    limit = max(1, min(int(limit or 100), 500))
+    pool = request.app.state.db
+    async with pool.acquire() as conn:
+        if q:
+            rows = await conn.fetch(
+                """
+                SELECT id, workshop_id, mod_name, version,
+                       upvotes, downvotes,
+                       created_at, updated_at
+                  FROM broken_mod_reports
+                 WHERE workshop_id LIKE '%' || $1 || '%'
+                 ORDER BY updated_at DESC
+                 LIMIT $2
+                """,
+                q.strip(), limit,
+            )
+        else:
+            rows = await conn.fetch(
+                """
+                SELECT id, workshop_id, mod_name, version,
+                       upvotes, downvotes,
+                       created_at, updated_at
+                  FROM broken_mod_reports
+                 ORDER BY updated_at DESC
+                 LIMIT $1
+                """,
+                limit,
+            )
+    return [
+        {
+            "id":          int(r["id"]),
+            "workshop_id": r["workshop_id"],
+            "mod_name":    r["mod_name"] or "",
+            "version":     r["version"],
+            "upvotes":     int(r["upvotes"]),
+            "downvotes":   int(r["downvotes"]),
+            "created_at":  r["created_at"].isoformat(),
+            "updated_at":  r["updated_at"].isoformat(),
+        }
+        for r in rows
+    ]
+
+
+@app.post("/api/broken-mods")
+async def create_broken_mod_report(
+    req: BrokenModReportRequest,
+    request: Request,
+) -> Dict[str, Any]:
+    """Create or refresh a broken-mod report. Re-submitting the same
+    (workshop_id, version) bumps `updated_at` and preserves vote counts.
+
+    Resolves `mod_name` from the existing workshop_meta cache; if missing
+    we fetch from Steam (anonymous GetPublishedFileDetails) so the user
+    gets a meaningful label without having to type it.
+    """
+    if not req.workshop_id.isdigit():
+        raise HTTPException(
+            status_code=400,
+            detail="workshop_id must be a numeric Steam Workshop ID",
+        )
+    valid_versions = set(request.app.state.pz_versions or {}) or {
+        "stable", "unstable", "outdatedunstable",
+    }
+    if req.version not in valid_versions:
+        raise HTTPException(
+            status_code=400,
+            detail=f"version must be one of: {sorted(valid_versions)}",
+        )
+
+    pool = request.app.state.db
+    mod_name: Optional[str] = None
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            "SELECT title FROM workshop_meta WHERE workshop_id = $1",
+            req.workshop_id,
+        )
+        if row and row["title"]:
+            mod_name = row["title"]
+
+    if not mod_name:
+        # Cache miss → ask Steam directly. Treat any failure as "unknown
+        # name" rather than hard-erroring; the user still gets a row.
+        try:
+            details = await steam.fetch_workshop_details(
+                request.app.state.http, [req.workshop_id],
+            )
+            d = details.get(req.workshop_id) or {}
+            if d.get("result") == 1:
+                mod_name = d.get("title") or None
+        except Exception as e:
+            log.info("broken-mod: Steam lookup for %s failed: %s",
+                     req.workshop_id, e)
+
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            """
+            INSERT INTO broken_mod_reports
+                   (workshop_id, mod_name, version)
+            VALUES ($1, $2, $3)
+            ON CONFLICT (workshop_id, version) DO UPDATE
+               SET updated_at = now(),
+                   mod_name = COALESCE(EXCLUDED.mod_name, broken_mod_reports.mod_name)
+            RETURNING id, workshop_id, mod_name, version,
+                      upvotes, downvotes, created_at, updated_at
+            """,
+            req.workshop_id, mod_name, req.version,
+        )
+    return {
+        "id":          int(row["id"]),
+        "workshop_id": row["workshop_id"],
+        "mod_name":    row["mod_name"] or "",
+        "version":     row["version"],
+        "upvotes":     int(row["upvotes"]),
+        "downvotes":   int(row["downvotes"]),
+        "created_at":  row["created_at"].isoformat(),
+        "updated_at":  row["updated_at"].isoformat(),
+    }
+
+
+@app.post("/api/broken-mods/{report_id}/vote")
+async def vote_broken_mod(
+    report_id: int,
+    req: BrokenModVoteRequest,
+    request: Request,
+) -> Dict[str, int]:
+    """Increment upvotes or downvotes on an existing report."""
+    column = "upvotes" if req.direction == "up" else "downvotes"
+    pool = request.app.state.db
+    async with pool.acquire() as conn:
+        row = await conn.fetchrow(
+            f"""
+            UPDATE broken_mod_reports
+               SET {column} = {column} + 1
+             WHERE id = $1
+            RETURNING upvotes, downvotes
+            """,
+            report_id,
+        )
+    if row is None:
+        raise HTTPException(status_code=404, detail="report not found")
+    return {"upvotes": int(row["upvotes"]), "downvotes": int(row["downvotes"])}
+
+
+# ── static frontend ────────────────────────────────────────────────────────
+# Mount LAST so all API routes win path resolution.
+_FRONTEND_DIR = Path(__file__).resolve().parent.parent / "frontend"
+if _FRONTEND_DIR.is_dir():
+    app.mount(
+        "/",
+        StaticFiles(directory=str(_FRONTEND_DIR), html=True),
+        name="frontend",
+    )
diff --git a/api/db.py b/api/db.py
new file mode 100644
index 0000000..5f9a4e5
--- /dev/null
+++ b/api/db.py
@@ -0,0 +1,34 @@
+"""asyncpg pool factory. DSN is built from /opt/sortof/.env at startup."""
+
+from __future__ import annotations
+
+import os
+import urllib.parse
+from pathlib import Path
+
+import asyncpg
+from dotenv import load_dotenv
+
+ENV_PATH = Path(__file__).resolve().parent.parent / ".env"
+
+
+def _build_dsn() -> str:
+    load_dotenv(ENV_PATH)
+    explicit = os.environ.get("DATABASE_URL")
+    if explicit:
+        return explicit
+    user = os.environ["POSTGRES_USER"]
+    pw = urllib.parse.quote(os.environ["POSTGRES_PASSWORD"], safe="")
+    name = os.environ["POSTGRES_DB"]
+    host = os.environ.get("POSTGRES_HOST", "127.0.0.1")
+    port = os.environ.get("POSTGRES_PORT", "5439")
+    return f"postgresql://{user}:{pw}@{host}:{port}/{name}"
+
+
+async def create_pool() -> asyncpg.Pool:
+    return await asyncpg.create_pool(
+        dsn=_build_dsn(),
+        min_size=1,
+        max_size=8,
+        command_timeout=15,
+    )
diff --git a/api/expansion.py b/api/expansion.py
new file mode 100644
index 0000000..500c23d
--- /dev/null
+++ b/api/expansion.py
@@ -0,0 +1,140 @@
+"""Background async task: take a freshly-created sort_jobs row in 'expanding'
+phase, resolve its collection_ids via Steam, populate wsids[], advance phase
+to 'queued' (and drop wsids into download_jobs as needed)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Dict, List, Tuple
+
+import asyncpg
+import httpx
+
+from jobs import update_phase
+from steam import fetch_collection_details
+
+log = logging.getLogger("sortof.expansion")
+
+
+async def _resolve_collections(
+    conn: asyncpg.Connection,
+    http: httpx.AsyncClient,
+    collection_ids: List[str],
+) -> Tuple[Dict[str, List[str]], List[str]]:
+    """Returns (resolved, unresolvable). resolved maps collection_id ->
+    [child_wsids]. unresolvable lists collection_ids that GetCollectionDetails
+    couldn't fetch (after one retry)."""
+    if not collection_ids:
+        return ({}, [])
+
+    # Cache lookup (TTL = 6h via last_fetched_at).
+    cache_rows = await conn.fetch(
+        """
+        SELECT collection_id, child_workshop_ids
+          FROM collections
+         WHERE collection_id = ANY($1::text[])
+           AND last_fetched_at > now() - interval '6 hours'
+        """,
+        collection_ids,
+    )
+    resolved: Dict[str, List[str]] = {
+        r["collection_id"]: list(r["child_workshop_ids"])
+        for r in cache_rows
+    }
+    miss = [cid for cid in collection_ids if cid not in resolved]
+
+    unresolvable: List[str] = []
+    if miss:
+        # Spec §5.4: 1 retry with 2s backoff on HTTPError. If both attempts
+        # raise, api_out stays {} and the per-cid pass below uniformly marks
+        # every miss as unresolvable (rec is None branch).
+        api_out: Dict[str, Any] = {}
+        for attempt in (1, 2):
+            try:
+                api_out = await fetch_collection_details(http, miss)
+                break
+            except httpx.HTTPError as e:
+                log.warning("GetCollectionDetails attempt %d failed: %s", attempt, e)
+                if attempt == 1:
+                    await asyncio.sleep(2.0)
+        for cid in miss:
+            rec = api_out.get(cid)
+            if rec is None or rec.get("result") != 1:
+                unresolvable.append(cid)
+                continue
+            children = rec.get("children") or []
+            resolved[cid] = list(children)
+            await conn.execute(
+                """
+                INSERT INTO collections (collection_id, child_workshop_ids, last_fetched_at)
+                VALUES ($1, $2, now())
+                ON CONFLICT (collection_id) DO UPDATE
+                   SET child_workshop_ids = EXCLUDED.child_workshop_ids,
+                       last_fetched_at    = now()
+                """,
+                cid, children,
+            )
+    return (resolved, unresolvable)
+
+
+async def run_expansion(
+    pool: asyncpg.Pool,
+    http: httpx.AsyncClient,
+    job_id: str,
+    bare_wsids: List[str],
+    collection_ids: List[str],
+) -> None:
+    """Top-level expansion task. Logs and persists; never raises out."""
+    try:
+        async with pool.acquire() as conn:
+            resolved, unresolvable = await _resolve_collections(conn, http, collection_ids)
+
+            # Compose wsids: collections (in input order) + bare wsids, deduped.
+            seen: set = set()
+            wsids: List[str] = []
+            for cid in collection_ids:
+                for w in resolved.get(cid, []):
+                    if w and w not in seen:
+                        seen.add(w)
+                        wsids.append(w)
+            for w in bare_wsids:
+                if w not in seen:
+                    seen.add(w)
+                    wsids.append(w)
+
+            if not wsids:
+                # All collections unresolvable AND no bare wsids. Job dies.
+                await update_phase(
+                    conn, job_id, "failed",
+                    failure_reason="all input collections unresolvable",
+                )
+                log.info("expansion %s: failed - all collections unresolvable", job_id)
+                return
+
+            partial_warnings = [
+                {
+                    "tag": "collection-partial",
+                    "level": "warning",
+                    "msg": f"collection {cid} could not be fetched",
+                }
+                for cid in unresolvable
+            ]
+            seed_result = {"WARNINGS": partial_warnings} if partial_warnings else None
+
+            await update_phase(
+                conn, job_id, "queued",
+                wsids=wsids,
+                result_json=seed_result,
+            )
+            log.info(
+                "expansion %s: queued (wsids=%d unresolvable=%d)",
+                job_id, len(wsids), len(unresolvable),
+            )
+    except Exception:
+        log.exception("expansion %s: crashed", job_id)
+        try:
+            async with pool.acquire() as conn:
+                await update_phase(conn, job_id, "failed", failure_reason="expansion crashed")
+        except Exception:
+            log.exception("expansion %s: cleanup failed", job_id)
diff --git a/api/jobs.py b/api/jobs.py
new file mode 100644
index 0000000..a08e915
--- /dev/null
+++ b/api/jobs.py
@@ -0,0 +1,199 @@
+"""sort_jobs persistence + phase derivation.
+
+Phase is *derived* on every GET (Spec B+F §4): never stored as the source
+of truth except for terminal states. The function `derive_phase` reads
+live counts from download_jobs and decides expanding/queued/draining/done.
+This makes the system restart-resilient by construction - there is no
+event log to replay.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+import asyncpg
+
+
+# ── CRUD ────────────────────────────────────────────────────────────────────
+
+async def create_job(
+    conn: asyncpg.Connection,
+    *,
+    input_raw: str,
+    collection_ids: List[str],
+    wsids: Optional[List[str]],
+    rules_raw: Optional[str],
+    initial_phase: str,
+    pz_build: Optional[str] = None,
+) -> str:
+    """Insert a sort_jobs row and return the job_id (UUID as string).
+
+    initial_phase: 'expanding' if collections still need resolving,
+                   'queued' if wsids are already resolved at submit time.
+    pz_build: 'B41' / 'B42' captured at submit so the polling-path
+              result regen can emit build-mismatch warnings against the
+              user's chosen build.
+    """
+    row = await conn.fetchrow(
+        """
+        INSERT INTO sort_jobs (phase, input_raw, collection_ids, wsids, rules_raw, pz_build)
+        VALUES ($1, $2, $3, $4, $5, $6)
+        RETURNING job_id
+        """,
+        initial_phase, input_raw, collection_ids, wsids, rules_raw, pz_build,
+    )
+    return str(row["job_id"])
+
+
+async def get_job_row(conn: asyncpg.Connection, job_id: str) -> Optional[Dict[str, Any]]:
+    """Fetch a sort_jobs row by id. Returns None if not found.
+
+    job_id may be either a string UUID or asyncpg-native UUID.
+    """
+    try:
+        uid = UUID(job_id) if isinstance(job_id, str) else job_id
+    except ValueError:
+        return None
+    row = await conn.fetchrow(
+        "SELECT * FROM sort_jobs WHERE job_id = $1",
+        uid,
+    )
+    if row is None:
+        return None
+    out = dict(row)
+    # asyncpg returns jsonb as raw text by default (no codec registered
+    # in db.py). Decode result_json so callers always receive a dict.
+    rj = out.get("result_json")
+    if isinstance(rj, str):
+        out["result_json"] = json.loads(rj)
+    return out
+
+
+async def update_phase(
+    conn: asyncpg.Connection,
+    job_id: str,
+    phase: str,
+    *,
+    wsids: Optional[List[str]] = None,
+    result_json: Optional[Dict[str, Any]] = None,
+    failure_reason: Optional[str] = None,
+) -> None:
+    """Advance a job's phase. wsids/result_json/failure_reason are optional
+    column updates that pair with phase transitions."""
+    # Accept str OR UUID; mirrors get_job_row's input shape.
+    uid = UUID(job_id) if isinstance(job_id, str) else job_id
+    sets = ["phase = $2", "phase_started_at = now()"]
+    # Convention: $1=job_id, $2=phase; optional fields start at $3.
+    params: List[Any] = [uid, phase]
+    idx = 3
+    if wsids is not None:
+        sets.append(f"wsids = ${idx}::text[]")
+        params.append(wsids)
+        idx += 1
+    if result_json is not None:
+        sets.append(f"result_json = ${idx}::jsonb")
+        params.append(json.dumps(result_json))
+        idx += 1
+    if failure_reason is not None:
+        sets.append(f"failure_reason = ${idx}")
+        params.append(failure_reason)
+        idx += 1
+    await conn.execute(
+        f"UPDATE sort_jobs SET {', '.join(sets)} WHERE job_id = $1",
+        *params,
+    )
+
+
+# ── live counts (Spec B+F §6) ───────────────────────────────────────────────
+
+async def compute_counts(conn: asyncpg.Connection, wsids: List[str]) -> Dict[str, int]:
+    """Compute live cached/queued/draining/terminal_failed counts.
+    Empty wsids → all zeros.
+
+    terminal_failed: wsids whose LATEST download_jobs row has status='failed'.
+    These will not appear in mod_parsed and are not coming back; without this,
+    derive_phase would loop forever when a job's wsids include non-mods or
+    permanently-broken downloads.
+    """
+    if not wsids:
+        return {"cached": 0, "queued": 0, "draining": 0, "terminal_failed": 0}
+    rows = await conn.fetch(
+        """
+        SELECT
+            (SELECT COUNT(DISTINCT mp.workshop_id)
+             FROM mod_parsed mp
+             JOIN workshop_meta wm ON wm.workshop_id = mp.workshop_id
+             WHERE mp.workshop_id = ANY($1::text[])
+               AND mp.parsed_at_time_updated = wm.time_updated) AS cached,
+            (SELECT COUNT(DISTINCT workshop_id)
+             FROM download_jobs
+             WHERE workshop_id = ANY($1::text[]) AND status = 'queued') AS queued,
+            (SELECT COUNT(DISTINCT workshop_id)
+             FROM download_jobs
+             WHERE workshop_id = ANY($1::text[]) AND status = 'downloading') AS draining,
+            (SELECT COUNT(*) FROM (
+                SELECT DISTINCT ON (workshop_id) workshop_id, status
+                FROM download_jobs
+                WHERE workshop_id = ANY($1::text[])
+                ORDER BY workshop_id, updated_at DESC
+            ) latest WHERE status = 'failed') AS terminal_failed
+        """,
+        wsids,
+    )
+    r = rows[0]
+    return {
+        "cached":          int(r["cached"]),
+        "queued":          int(r["queued"]),
+        "draining":        int(r["draining"]),
+        "terminal_failed": int(r["terminal_failed"]),
+    }
+
+
+# ── phase derivation (Spec B+F §4) ──────────────────────────────────────────
+
+def derive_phase(
+    stored_phase: str,
+    wsids: Optional[List[str]],
+    counts: Dict[str, int],
+) -> str:
+    """Decide the live phase from the row's stored phase + current counts.
+
+    Terminal phases (done/failed) are never demoted. Non-terminal phases
+    are recomputed from current state.
+    """
+    if stored_phase in ("done", "failed"):
+        return stored_phase
+    if wsids is None:
+        return "expanding"
+    if counts["draining"] > 0:
+        return "draining"
+    if counts["queued"] > 0:
+        return "queued"
+    # Terminal: every wsid is either cached or permanently-failed.
+    settled = counts["cached"] + counts.get("terminal_failed", 0)
+    if settled >= len(wsids):
+        return "done"
+    # Transient gap: a row just left 'queued' and hasn't shown up in
+    # mod_parsed yet. Most likely just-failed and not yet re-queued.
+    return "queued"
+
+
+# ── stale-expansion sweep (Spec B+F §9) ─────────────────────────────────────
+
+STALE_EXPANSION_SQL = """
+UPDATE sort_jobs
+   SET phase = 'failed',
+       failure_reason = 'expansion timed out',
+       updated_at = now()
+ WHERE phase = 'expanding'
+   AND phase_started_at < now() - interval '10 minutes'
+RETURNING job_id;
+"""
+
+
+async def sweep_stale_expansions(conn: asyncpg.Connection) -> int:
+    """Run on uvicorn lifespan startup. Returns the number of jobs reaped."""
+    rows = await conn.fetch(STALE_EXPANSION_SQL)
+    return len(rows)
diff --git a/api/mlos_sort.py b/api/mlos_sort.py
new file mode 100644
index 0000000..98d66fe
--- /dev/null
+++ b/api/mlos_sort.py
@@ -0,0 +1,712 @@
+"""
+mlos_sort.py
+Python port of MLOS_sorting.lua (Mod Load Order Sorter, by REfRigERatoR).
+
+Faithful to the Lua algorithm:
+  - preorder: ModManager, ModManagerServer, modoptions
+  - category buckets: coreRequirement -> tweaks -> resource -> map -> vehicle ->
+                      code -> clothes -> ui -> other -> translation -> undefined
+  - loadFirst / loadLast: on (0) | category (1) | off (2)
+  - topological sort by `require` + `loadAfter` with cycle detection
+  - sorting_rules.txt overrides supported (loadAfter/loadBefore/incompatibleMods/
+    loadFirst/loadLast/category)
+
+Limitations vs in-game Lua:
+  - mod.info-only input. We do NOT walk /media/* folders for category detection.
+    We rely on mod.info `category=` if present, then `frameworkKeys` name
+    heuristic, then default "other" (or "undefined" if uncategorizable).
+  - `loadBefore` is converted into corresponding `loadAfter` edges on other mods,
+    matching the Lua mod's behavior.
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+# -----------------------------------------------------------------------------
+# Constants (mirrors MLOS_sorting.lua)
+# -----------------------------------------------------------------------------
+
+PREORDER: Dict[str, int] = {"ModManager": 1, "ModManagerServer": 2, "modoptions": 3}
+
+RAW_CATEGORY_ORDER: List[str] = [
+    "coreRequirement",
+    "tweaks",        # libraries / frameworks / APIs (matches existing 'lib' pill)
+    "tile",          # tile asset packs
+    "debug",         # error logger, cheat menus
+    "resource",      # other generic resources
+    "map",
+    "qol",           # QOL changes
+    "moodle",        # moodles / moodlets
+    "tweak_minor",   # tiny tweaks (working aircon, ear protection, …)
+    "music",         # music + music addons (load before vehicles per user spec)
+    "wearable",      # clothing, hair, tattoos (NOT armor)
+    "profession",    # profession mods
+    "movement",      # drop-and-roll, crawl, jump, ladders
+    "building",      # building menus, barricades, light switches
+    "farming",
+    "zombie",        # zombie behaviour mods (OccultZed, HordeNight, ReactiveZombies)
+    "zone",          # hazardous zones, spore zones
+    "armor",         # armor mods (separate from wearables)
+    "food",
+    "health",        # first aid, medical
+    "weapon",        # weapons (load before vehicles per user spec)
+    "crafting",
+    "container",     # backpacks, boxes, tubs
+    "vehicle",
+    "vehicle_spawn", # vehicle spawn zones
+    "loot",          # loot tables
+    "code",          # generic gameplay code (legacy fallback)
+    "ui",            # interface
+    "sound",         # audio (non-music)
+    "texture",
+    "translation",
+    "multiplayer",   # MP-specific utilities
+    "server_only",   # admin tools, server logs
+    "fix",           # bug-fix overlays (distinct from 'patch' loadLast tier)
+    "other",
+    "undefined",
+    # Spec G-patch: "patch" is a category like any other, but `_initial_sort_key`
+    # routes patches above all sub-axes via a leading is_patch tuple element so
+    # they sort strictly LAST (after every loadLast=on map mod).
+    "patch",
+]
+CATEGORY_ORDER: Dict[str, int] = {c: i for i, c in enumerate(RAW_CATEGORY_ORDER)}
+
+LOAD_CATEGORIES: Dict[str, int] = {"on": 0, "category": 1, "off": 2}
+
+# from MLOS_sorting.lua: frameworkKeys for name-based tweak detection.
+# Lua uses string.find on lowercased name (substring match, no regex anchors).
+FRAMEWORK_KEYS: List[str] = [
+    "framework",
+    " api",
+    "_api",
+    "tweak",
+    "interface",
+    "utilit",  # matches utility, utilities
+    "bugfix",
+    "librar",  # matches library, libraries — covers damnlib/tsarslib/StarlitLibrary/etc.
+               # `derive_category` checks mod.maps before FRAMEWORK_KEYS, so a map
+               # mod whose name contains "library" still classifies as `map` first.
+]
+
+# Multi-key list fields in mod.info (lowercased keys)
+LIST_KEYS_MAP = {
+    "require": "requirements",
+    "loadafter": "loadAfter",
+    "loadbefore": "loadBefore",
+    "incompatiblemods": "incompatibleMods",
+    "tags": "tags",
+}
+
+
+# -----------------------------------------------------------------------------
+# Dataclasses
+# -----------------------------------------------------------------------------
+
+
+@dataclass
+class ModInfo:
+    id: str
+    name: str = ""
+    workshop_id: Optional[str] = None
+    category: str = "undefined"
+    requirements: List[str] = field(default_factory=list)
+    loadAfter: List[str] = field(default_factory=list)
+    loadBefore: List[str] = field(default_factory=list)
+    incompatibleMods: List[str] = field(default_factory=list)
+    loadFirst: str = "off"
+    loadLast: str = "off"
+    tags: List[str] = field(default_factory=list)
+    maps: List[str] = field(default_factory=list)  # map folder names from media/maps/
+    flags: List[str] = field(default_factory=list)
+    is_addon: bool = False  # Spec A addon: default-off in multi-mod wsids
+    # Steam Workshop's controlled-vocab tags (workshop_meta.tags). Canonical
+    # signal for build / multiplayer / category detection. Distinct from
+    # `tags` which is mod.info-side (freeform).
+    workshop_tags: List[str] = field(default_factory=list)
+    warnings: Dict[str, List[str]] = field(default_factory=dict)
+
+
+@dataclass
+class SortingRule:
+    loadAfter: List[str] = field(default_factory=list)
+    loadBefore: List[str] = field(default_factory=list)
+    incompatibleMods: List[str] = field(default_factory=list)
+    loadFirst: str = "off"
+    loadLast: str = "off"
+    category: Optional[str] = None
+
+
+# -----------------------------------------------------------------------------
+# Helpers
+# -----------------------------------------------------------------------------
+
+
+def _split_csv(value: str) -> List[str]:
+    """
+    Mirrors Refr_Utils:splitStringBySeparator - split on commas, trim, drop empties.
+    Defensively strips `word=` prefixes that some malformed mod.info lines include
+    (the Lua does this too). Also strips a leading backslash on each entry: B42
+    mod.info files write deps as `require=\\StarlitLibrary` (path-style); we want
+    plain modIds so dep names match for the topo sort and missing-dep warnings.
+    Finally strips a leading "<digits>/" wsid-path prefix some authors put in
+    front of the modId (e.g. require=2256623447/firearmmod).
+    """
+    if value is None:
+        return []
+    cleaned = re.sub(r"\w+\s*=", "", value)
+    out: List[str] = []
+    for p in cleaned.split(","):
+        s = p.strip().lstrip("\\")
+        s = re.sub(r"^\d+/", "", s)
+        if s:
+            out.append(s)
+    return out
+
+
+def _convert_load_category(value) -> str:
+    """Mirrors convertToLoadCategoryString: normalize to 'on' | 'category' | 'off'."""
+    if value in (True, "true", 0, "0"):
+        return "on"
+    if value in (None, False, "false", 2, "2", ""):
+        return "off"
+    if value not in LOAD_CATEGORIES:
+        return "off"
+    return str(value)
+
+
+def _str_contains_any(haystack: str, needles: List[str]) -> bool:
+    if not haystack:
+        return False
+    h = haystack.lower()
+    return any(n and n in h for n in needles)
+
+
+# -----------------------------------------------------------------------------
+# Parsers
+# -----------------------------------------------------------------------------
+
+
+def parse_mod_info(text: str, workshop_id: Optional[str] = None) -> Optional[ModInfo]:
+    """
+    Parse a mod.info file body. Returns None if no `id=` line found.
+    Lines are `key=value`; keys lowercased; list-fields comma-separated.
+    """
+    fields: Dict[str, object] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        m = re.match(r"^\s*(.+?)\s*=\s*(.*?)\s*$", line)
+        if not m:
+            continue
+        key = m.group(1).strip().lower()
+        value = m.group(2).strip()
+        if key in LIST_KEYS_MAP:
+            fields[LIST_KEYS_MAP[key]] = _split_csv(value)
+        elif key == "loadfirst":
+            fields["loadFirst"] = _convert_load_category(value)
+        elif key == "loadlast":
+            fields["loadLast"] = _convert_load_category(value)
+        elif key == "category":
+            fields["category"] = value if value in CATEGORY_ORDER else "undefined"
+        elif key == "name":
+            fields["name"] = value
+        elif key == "id":
+            # Some authors prefix the wsid into the id (e.g. id=2256623447/firearmmod).
+            # Strip a leading "<digits>/" so the canonical mod_id is the clean form.
+            fields["id"] = re.sub(r"^\d+/", "", value)
+
+    if "id" not in fields:
+        return None
+
+    return ModInfo(
+        id=fields["id"],
+        name=fields.get("name", ""),
+        workshop_id=workshop_id,
+        category=fields.get("category", "undefined"),
+        requirements=fields.get("requirements", []),
+        loadAfter=fields.get("loadAfter", []),
+        loadBefore=fields.get("loadBefore", []),
+        incompatibleMods=fields.get("incompatibleMods", []),
+        loadFirst=fields.get("loadFirst", "off"),
+        loadLast=fields.get("loadLast", "off"),
+        tags=fields.get("tags", []),
+    )
+
+
+def parse_sorting_rules(text: str) -> Dict[str, SortingRule]:
+    """
+    Parse a sorting_rules.txt file. Format:
+        [modId]
+        loadAfter=mod1,mod2
+        loadBefore=mod3
+        incompatibleMods=mod4
+        loadFirst=on
+        loadLast=off
+        category=tweaks
+    """
+    rules: Dict[str, SortingRule] = {}
+    current: Optional[str] = None
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line:
+            continue
+        m = re.match(r"^\s*\[\s*(.+?)\s*\]\s*$", line)
+        if m:
+            current = m.group(1)
+            rules.setdefault(current, SortingRule())
+            continue
+        if current is None:
+            continue
+        kv = re.match(r"^\s*(.+?)\s*=\s*(.*?)\s*$", line)
+        if not kv:
+            continue
+        key, value = kv.group(1).lower(), kv.group(2)
+        rule = rules[current]
+        if key in ("loadafter", "loadmodafter"):
+            rule.loadAfter = list(dict.fromkeys(rule.loadAfter + _split_csv(value)))
+        elif key in ("loadbefore", "loadmodbefore"):
+            rule.loadBefore = list(dict.fromkeys(rule.loadBefore + _split_csv(value)))
+        elif key in ("incompatiblemods", "incompatible"):
+            rule.incompatibleMods = list(dict.fromkeys(rule.incompatibleMods + _split_csv(value)))
+        elif key == "loadfirst":
+            rule.loadFirst = _convert_load_category(value)
+        elif key == "loadlast":
+            rule.loadLast = _convert_load_category(value)
+        elif key == "category":
+            rule.category = value if value in CATEGORY_ORDER else None
+    return rules
+
+
+# -----------------------------------------------------------------------------
+# Filesystem ingestion (DepotDownloader output layout)
+# -----------------------------------------------------------------------------
+
+
+def load_mods_from_dir(root: Path) -> List[ModInfo]:
+    """
+    Walk `<root>/<workshop_id>/mods/<mod_id>/mod.info` (DepotDownloader output).
+    Also: `<root>/<workshop_id>/mods/<mod_id>/media/maps/<map_folder>/map.info`
+    populates `maps` for that mod.
+    """
+    mods: List[ModInfo] = []
+    if not root.exists():
+        raise FileNotFoundError(f"Mods root does not exist: {root}")
+
+    for workshop_dir in sorted(root.iterdir()):
+        if not workshop_dir.is_dir():
+            continue
+        workshop_id = workshop_dir.name if workshop_dir.name.isdigit() else None
+        mods_root = workshop_dir / "mods"
+        if not mods_root.exists():
+            # also support: some layouts put mods/ at root level directly
+            mods_root = workshop_dir
+        if not mods_root.exists() or not mods_root.is_dir():
+            continue
+
+        for mod_dir in sorted(mods_root.iterdir()):
+            if not mod_dir.is_dir():
+                continue
+            mod_info_path = mod_dir / "mod.info"
+            if not mod_info_path.exists():
+                continue
+            try:
+                text = mod_info_path.read_text(encoding="utf-8", errors="replace")
+            except OSError as e:
+                print(f"WARN: cannot read {mod_info_path}: {e}", file=sys.stderr)
+                continue
+            mod = parse_mod_info(text, workshop_id=workshop_id)
+            if mod is None:
+                print(f"WARN: no `id=` in {mod_info_path}, skipping", file=sys.stderr)
+                continue
+
+            # Collect map folders
+            maps_dir = mod_dir / "media" / "maps"
+            if maps_dir.exists() and maps_dir.is_dir():
+                for map_folder in sorted(maps_dir.iterdir()):
+                    if map_folder.is_dir() and (map_folder / "map.info").exists():
+                        mod.maps.append(map_folder.name)
+
+            mods.append(mod)
+
+    return mods
+
+
+# -----------------------------------------------------------------------------
+# Category derivation (degraded vs in-game; no folder walk)
+# -----------------------------------------------------------------------------
+
+
+_PATCH_NAME_RE = re.compile(r"\b(patch|compat|compatibility)\b", re.IGNORECASE)
+
+
+# Substring lists used for derive_category name heuristics. Plain substring
+# matching (vs. \b regex) survives PZ's mishmash of camelCase + underscore
+# + version-suffix mod names (TrueActions_1.09, TrueMusic, TMMumble, …)
+# that strict word boundaries fail on. False positives are accepted in
+# exchange — names containing "music" without being music-related are rare
+# in PZ.
+_LIB_NAME_HINTS = [
+    "library", "libraries", "framework",
+]
+_LIB_NAME_RE = re.compile(
+    r'(?<![A-Za-z])(?:lib|api|core)(?![A-Za-z])'
+    r'|(?<=[a-z])(?:Lib|API|Core)(?![A-Za-z])',
+    re.IGNORECASE,
+)
+_MUSIC_NAME_HINTS    = ["music", "moozic", "jukebox"]
+_MOODLE_NAME_HINTS   = ["moodle", "moodlet"]
+_PROFESSION_HINTS    = ["profession"]
+_MOVEMENT_HINTS      = [
+    "true action", "trueaction", "true_action",
+    "drop and roll", "dropandroll", "drop_and_roll",
+    "crawl", "ladder",
+]
+_ARMOR_NAME_HINTS    = ["armor", "armour"]
+_HEALTH_NAME_HINTS   = ["first aid", "firstaid", "medical", "injur", "disease", "sickness"]
+_CRAFTING_HINTS      = ["craft"]
+_CONTAINER_HINTS     = ["backpack", "container", "storage"]
+_LOOT_NAME_HINTS     = ["loot"]
+_TILE_NAME_HINTS     = ["tiles", "tileset", "tilepack"]
+_DEBUG_NAME_HINTS    = ["debug menu", "cheat menu", "error log", "errormagnifier"]
+_ZONE_NAME_HINTS     = ["hazard zone", "spore zone", "spore zones"]
+_ZOMBIE_NAME_HINTS   = ["zombie", "horde", "undead"]
+_FIX_NAME_HINTS      = [" fix", "_fix", "bugfix", "hotfix"]
+
+
+def _name_has(name: str, hints: List[str]) -> bool:
+    """Case-insensitive substring containment against any of `hints`."""
+    if not name:
+        return False
+    n = name.lower()
+    return any(h in n for h in hints)
+
+
+def derive_category(mod: ModInfo) -> str:
+    """Best-effort category from mod.info + workshop_meta.tags + name.
+
+    Detection order (most specific → least):
+      1. mod.info `category=` if explicit and recognized.
+      2. patch / fix name regex (Spec G-patch).
+      3. library/framework name regex (extends FRAMEWORK_KEYS).
+      4. mod.maps non-empty → map.
+      5. moodle / profession / movement / specific gameplay axes by name.
+      6. Workshop tags (canonical Steam controlled vocab): Audio + 'music' →
+         music; Audio → sound; Weapons → weapon; Vehicles → vehicle;
+         Clothing/Armor + 'armor' → armor, else wearable; Building →
+         building; Farming → farming; Food → food; Skills → profession
+         (or moodle); Interface → ui; Textures → texture;
+         Language/Translation → translation; QOL → qol; Multiplayer alone
+         → multiplayer.
+      7. mod.info tags (freeform fallback).
+      8. FRAMEWORK_KEYS substring match → tweaks.
+      9. Default → other.
+    """
+    if mod.category in CATEGORY_ORDER and mod.category != "undefined":
+        return mod.category
+
+    name = mod.name or ""
+    if name and _PATCH_NAME_RE.search(name):
+        return "patch"
+    if _name_has(name, _LIB_NAME_HINTS) or (name and _LIB_NAME_RE.search(name)):
+        return "tweaks"
+
+    if mod.maps:
+        return "map"
+
+    # Music gets PROMOTED before tag-based dispatch: many B41 music mods
+    # (truemusic, etc.) are tagged "Items"/"Realistic" not "Audio", but the
+    # name carries the signal. Same for movement (TrueActions_1.09).
+    if _name_has(name, _MUSIC_NAME_HINTS):
+        return "music"
+    if _name_has(name, _MOVEMENT_HINTS):
+        return "movement"
+    if _name_has(name, _MOODLE_NAME_HINTS):
+        return "moodle"
+    if _name_has(name, _DEBUG_NAME_HINTS):
+        return "debug"
+    # Tile packs win against generic "Textures"/"Models" Workshop tags so
+    # they land in the tile sort bucket (CATEGORY_ORDER 2) before maps load.
+    if _name_has(name, _TILE_NAME_HINTS):
+        return "tile"
+
+    ws_tags = set(mod.workshop_tags or [])
+    has_audio = "Audio" in ws_tags
+
+    if "Weapons" in ws_tags:
+        return "weapon"
+    if "Vehicles" in ws_tags:
+        if name and "spawn zone" in name.lower():
+            return "vehicle_spawn"
+        return "vehicle"
+    if "Clothing/Armor" in ws_tags:
+        if _name_has(name, _ARMOR_NAME_HINTS):
+            return "armor"
+        return "wearable"
+    if "Food" in ws_tags:
+        return "food"
+    if "building" in {t.lower() for t in ws_tags}:
+        return "building"
+    if "Farming" in ws_tags:
+        return "farming"
+    if "Skills" in ws_tags:
+        if _name_has(name, _PROFESSION_HINTS):
+            return "profession"
+        return "code"
+    if "Interface" in ws_tags:
+        return "ui"
+    if "Textures" in ws_tags:
+        return "texture"
+    if "Language/Translation" in ws_tags:
+        return "translation"
+    if "QOL" in ws_tags:
+        return "qol"
+    if "Map" in ws_tags:
+        return "map"
+
+    if _name_has(name, _TILE_NAME_HINTS):
+        return "tile"
+    if _name_has(name, _ZOMBIE_NAME_HINTS):
+        return "zombie"
+    if _name_has(name, _HEALTH_NAME_HINTS):
+        return "health"
+    if _name_has(name, _CRAFTING_HINTS):
+        return "crafting"
+    if _name_has(name, _CONTAINER_HINTS):
+        return "container"
+    if _name_has(name, _LOOT_NAME_HINTS):
+        return "loot"
+    if _name_has(name, _FIX_NAME_HINTS):
+        return "fix"
+    if _name_has(name, _ZONE_NAME_HINTS):
+        return "zone"
+
+    if has_audio:
+        return "sound"
+
+    # mod.info-side tags as final fallback before name heuristic.
+    tags_lc = [t.lower() for t in mod.tags]
+    if any("translation" in t for t in tags_lc):
+        return "translation"
+    if any("vehicle" in t for t in tags_lc):
+        return "vehicle"
+    if any("interface" in t or "ui" in t for t in tags_lc):
+        return "ui"
+    if any("clothing" in t or "skin" in t for t in tags_lc):
+        return "wearable"
+    if any("armor" in t for t in tags_lc):
+        return "armor"
+    if any("map" in t for t in tags_lc):
+        return "map"
+
+    if _str_contains_any(name, FRAMEWORK_KEYS):
+        return "tweaks"
+
+    if "Multiplayer" in ws_tags:
+        return "multiplayer"
+
+    return "other"
+
+
+# -----------------------------------------------------------------------------
+# Sort
+# -----------------------------------------------------------------------------
+
+
+def _apply_overrides(mods: List[ModInfo], rules: Dict[str, SortingRule]) -> None:
+    """In-place: merge rules into mods, then propagate loadBefore -> reverse loadAfter."""
+    by_id = {m.id: m for m in mods}
+
+    for mod in mods:
+        rule = rules.get(mod.id)
+        if rule:
+            mod.loadAfter = list(dict.fromkeys(mod.loadAfter + rule.loadAfter))
+            mod.loadBefore = list(dict.fromkeys(mod.loadBefore + rule.loadBefore))
+            mod.incompatibleMods = list(dict.fromkeys(mod.incompatibleMods + rule.incompatibleMods))
+            mod.loadFirst = _convert_load_category(rule.loadFirst if rule.loadFirst != "off" else mod.loadFirst)
+            mod.loadLast = _convert_load_category(rule.loadLast if rule.loadLast != "off" else mod.loadLast)
+            if rule.category:
+                mod.category = rule.category
+
+        # Derive category if still undefined
+        if mod.category not in CATEGORY_ORDER or mod.category == "undefined":
+            mod.category = derive_category(mod)
+
+    # Translate loadBefore into reverse loadAfter on the target mod
+    # (mirrors updateSortingRulesLoadAfter)
+    for mod in mods:
+        for target in mod.loadBefore:
+            target_mod = by_id.get(target)
+            if target_mod and mod.id not in target_mod.loadAfter:
+                target_mod.loadAfter.append(mod.id)
+
+
+def _initial_sort_key(mod: ModInfo):
+    """Mirrors initialSortMods comparator. Returns sortable tuple.
+
+    Spec G-patch: index 0 is `is_patch` so patches sort strictly last - they
+    have to override loadLast=on map mods at runtime. Within the patch tier
+    the existing sub-axes still apply (PREORDER, alpha, etc.).
+    """
+    is_patch = 1 if mod.category == "patch" else 0
+    pre = PREORDER.get(mod.id, 10000)
+    return (
+        is_patch,
+        pre,
+        LOAD_CATEGORIES[mod.loadFirst],          # global loadFirst (on first)
+        -LOAD_CATEGORIES[mod.loadLast] + 100,    # global loadLast (on last) -- keep parity by
+                                                  # sorting "on" last; we invert so smaller=earlier
+        CATEGORY_ORDER.get(mod.category, CATEGORY_ORDER["undefined"]),
+        LOAD_CATEGORIES[mod.loadFirst],          # in-category loadFirst
+        -LOAD_CATEGORIES[mod.loadLast] + 100,    # in-category loadLast
+        mod.id.lower(),
+    )
+
+
+def _topological_sort(mods: List[ModInfo]) -> Tuple[List[str], List[List[str]]]:
+    """DFS topo sort on (requirements + loadAfter). Returns (order, cycles)."""
+    by_id = {m.id: m for m in mods}
+    visited: Dict[str, bool] = {}
+    visiting: Dict[str, bool] = {}
+    order: List[str] = []
+    cycles: List[List[str]] = []
+
+    def visit(mod: ModInfo, path: List[str]):
+        if visiting.get(mod.id):
+            cycles.append(path + [mod.id])
+            return
+        if visited.get(mod.id):
+            return
+        visiting[mod.id] = True
+        for dep in mod.requirements:
+            target = by_id.get(dep)
+            if target:
+                visit(target, path + [mod.id])
+        for dep in mod.loadAfter:
+            target = by_id.get(dep)
+            if target:
+                visit(target, path + [mod.id])
+        visiting[mod.id] = False
+        visited[mod.id] = True
+        order.append(mod.id)
+
+    for mod in mods:
+        visit(mod, [])
+    return order, cycles
+
+
+def sort_mods(
+    mods: List[ModInfo],
+    rules: Optional[Dict[str, SortingRule]] = None,
+) -> Dict[str, object]:
+    """
+    Top-level entry: returns dict with ordered IDs + warnings.
+    """
+    rules = rules or {}
+    _apply_overrides(mods, rules)
+
+    # Initial deterministic sort (preorder, loadFirst, category, loadLast, alpha)
+    mods.sort(key=_initial_sort_key)
+
+    order, cycles = _topological_sort(mods)
+
+    by_id = {m.id: m for m in mods}
+    enabled = set(by_id.keys())
+
+    missing: Dict[str, List[str]] = {}
+    incompat: Dict[str, List[str]] = {}
+
+    for mod in mods:
+        miss = [r for r in mod.requirements if r not in enabled]
+        if miss:
+            missing[mod.id] = miss
+        inc = [r for r in mod.incompatibleMods if r in enabled]
+        if inc:
+            incompat[mod.id] = inc
+
+    # Output blocks for the server's .ini file
+    mods_line = order  # already mod IDs in load order
+    workshop_seen: List[str] = []
+    workshop_set = set()
+    for mod_id in order:
+        wid = by_id[mod_id].workshop_id
+        if wid and wid not in workshop_set:
+            workshop_seen.append(wid)
+            workshop_set.add(wid)
+    # MAP_LINE convention: dependencies first (leftmost), dependents last
+    # (rightmost). Vanilla Muldraugh, KY is the ultimate base and is
+    # prepended at the very front by adapters.build_response. `order` is
+    # already topo-sorted by mod-level deps so dependencies appear before
+    # their dependents — walk it forward.
+    map_folders: List[str] = []
+    for mod_id in order:
+        for mf in by_id[mod_id].maps:
+            if mf not in map_folders:
+                map_folders.append(mf)
+
+    return {
+        "Mods": mods_line,
+        "WorkshopItems": workshop_seen,
+        "Map": map_folders,
+        "warnings": {
+            "cycles": cycles,
+            "missing_requirements": missing,
+            "incompatible_enabled": incompat,
+        },
+    }
+
+
+# -----------------------------------------------------------------------------
+# CLI
+# -----------------------------------------------------------------------------
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Sort PZ mods by load order. Reads DepotDownloader output layout.",
+    )
+    ap.add_argument("mods_root", help="Path containing <workshop_id>/mods/<mod_id>/mod.info trees")
+    ap.add_argument("--rules", help="Optional sorting_rules.txt path")
+    ap.add_argument("--json", action="store_true", help="Output JSON instead of ini blocks")
+    args = ap.parse_args()
+
+    root = Path(args.mods_root).resolve()
+    mods = load_mods_from_dir(root)
+    if not mods:
+        print("ERROR: no mods found", file=sys.stderr)
+        sys.exit(2)
+
+    rules: Dict[str, SortingRule] = {}
+    if args.rules:
+        rules = parse_sorting_rules(Path(args.rules).read_text(encoding="utf-8"))
+
+    result = sort_mods(mods, rules)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+        return
+
+    print("WorkshopItems=" + ";".join(result["WorkshopItems"]))
+    print("Mods=" + ";".join(result["Mods"]))
+    if result["Map"]:
+        print("Map=" + ";".join(result["Map"]))
+    w = result["warnings"]
+    if w["cycles"] or w["missing_requirements"] or w["incompatible_enabled"]:
+        print("\n# Warnings")
+        if w["cycles"]:
+            print("# cycles:", w["cycles"])
+        if w["missing_requirements"]:
+            print("# missing_requirements:", w["missing_requirements"])
+        if w["incompatible_enabled"]:
+            print("# incompatible_enabled:", w["incompatible_enabled"])
+
+
+if __name__ == "__main__":
+    main()
diff --git a/api/parse.py b/api/parse.py
new file mode 100644
index 0000000..6bb3149
--- /dev/null
+++ b/api/parse.py
@@ -0,0 +1,75 @@
+"""Parse a raw textarea blob into a deduped, ordered list of workshop IDs."""
+
+from __future__ import annotations
+
+import re
+from typing import List
+
+
+def parse_workshop_input(text: str) -> List[str]:
+    cleaned = re.sub(
+        r"^\s*(WorkshopItems|Mods|Map)\s*=\s*",
+        "",
+        text,
+        flags=re.MULTILINE | re.IGNORECASE,
+    )
+    ids = re.findall(r"\b\d{7,12}\b", cleaned)
+    seen: set[str] = set()
+    out: List[str] = []
+    for i in ids:
+        if i not in seen:
+            seen.add(i)
+            out.append(i)
+    return out
+
+
+# Steam Workshop URL form: https://steamcommunity.com/{sharedfiles,workshop}/filedetails/?id=NNNNNNN
+_STEAM_URL_RE = re.compile(
+    r"https?://steamcommunity\.com/(?:sharedfiles|workshop)/filedetails/\?id=(\d{7,12})",
+    re.IGNORECASE,
+)
+
+
+def parse_with_collections(text: str) -> tuple[List[str], List[str]]:
+    """Split an input blob into bare wsids and candidate collection IDs.
+
+    A "candidate collection" is any 7-12-digit ID that appears inside a
+    Steam Workshop URL. Bare numeric IDs in the same blob are treated as
+    mod wsids (current behavior). Steam doesn't syntactically distinguish
+    collection IDs from mod IDs; the candidate list is sent to
+    GetCollectionDetails to confirm. If a candidate isn't actually a
+    collection, the caller falls it back to wsids.
+
+    Returns (wsids, collection_ids), each deduped and in first-seen order.
+    """
+    if not text:
+        return ([], [])
+
+    # 1. Find URL-form IDs FIRST (so they don't get double-counted as bare).
+    url_ids: List[str] = []
+    seen_url: set[str] = set()
+    for m in _STEAM_URL_RE.finditer(text):
+        i = m.group(1)
+        if i not in seen_url:
+            seen_url.add(i)
+            url_ids.append(i)
+
+    # 2. Strip the URLs out before extracting bare numbers.
+    text_minus_urls = _STEAM_URL_RE.sub("", text)
+
+    # 3. Bare wsids: same regex as parse_workshop_input.
+    cleaned = re.sub(
+        r"^\s*(WorkshopItems|Mods|Map)\s*=\s*",
+        "",
+        text_minus_urls,
+        flags=re.MULTILINE | re.IGNORECASE,
+    )
+    bare_ids = re.findall(r"\b\d{7,12}\b", cleaned)
+    seen_bare: set[str] = set()
+    bare_unique: List[str] = []
+    for i in bare_ids:
+        if i not in seen_bare and i not in seen_url:
+            seen_bare.add(i)
+            bare_unique.append(i)
+
+    return (bare_unique, url_ids)
diff --git a/api/requirements.txt b/api/requirements.txt
new file mode 100644
index 0000000..9ccd649
--- /dev/null
+++ b/api/requirements.txt
@@ -0,0 +1,5 @@
+fastapi
+uvicorn[standard]
+asyncpg
+httpx
+python-dotenv
diff --git a/api/steam.py b/api/steam.py
new file mode 100644
index 0000000..3eb0d21
--- /dev/null
+++ b/api/steam.py
@@ -0,0 +1,82 @@
+"""Async wrapper for Steam's anonymous GetPublishedFileDetails endpoint."""
+
+from __future__ import annotations
+
+from typing import Dict, List, TypedDict
+
+import httpx
+
+
+class CollectionEntry(TypedDict):
+    """One element of fetch_collection_details's response.
+
+    result == 1 → valid collection; children populated.
+    result != 1 → not a collection / deleted / private; children typically [].
+    """
+    result: int
+    children: List[str]
+
+STEAM_URL = (
+    "https://api.steampowered.com/ISteamRemoteStorage/GetPublishedFileDetails/v1/"
+)
+
+
+async def fetch_workshop_details(
+    client: httpx.AsyncClient,
+    workshop_ids: List[str],
+) -> Dict[str, dict]:
+    if not workshop_ids:
+        return {}
+    data: Dict[str, str] = {"itemcount": str(len(workshop_ids))}
+    for i, wid in enumerate(workshop_ids):
+        data[f"publishedfileids[{i}]"] = wid
+    r = await client.post(STEAM_URL, data=data)
+    r.raise_for_status()
+    body = r.json()
+    out: Dict[str, dict] = {}
+    for item in body.get("response", {}).get("publishedfiledetails", []) or []:
+        out[item["publishedfileid"]] = item
+    return out
+
+
+COLLECTION_URL = (
+    "https://api.steampowered.com/ISteamRemoteStorage/GetCollectionDetails/v1/"
+)
+
+
+async def fetch_collection_details(
+    client: httpx.AsyncClient,
+    collection_ids: List[str],
+) -> Dict[str, CollectionEntry]:
+    """Resolve candidate collection IDs to their child wsids.
+
+    Returns a dict keyed by collection_id with shape:
+        { "result": int, "children": List[str] }
+
+    Anonymous endpoint; no API key needed. result==1 means valid collection;
+    result!=1 means the ID isn't a collection (could be a mod, deleted, or
+    private). Caller decides what to do with non-1 results - see Spec B+F
+    §10 Q3 "Partial expansion failure" and Q4 "Flakiness".
+    """
+    if not collection_ids:
+        return {}
+    data: Dict[str, str] = {"collectioncount": str(len(collection_ids))}
+    for i, cid in enumerate(collection_ids):
+        data[f"publishedfileids[{i}]"] = cid
+    r = await client.post(COLLECTION_URL, data=data)
+    r.raise_for_status()
+    body = r.json()
+    out: Dict[str, CollectionEntry] = {}
+    for item in body.get("response", {}).get("collectiondetails", []) or []:
+        cid = item.get("publishedfileid")
+        if not cid:
+            continue
+        out[cid] = {
+            "result": int(item.get("result") or 0),
+            "children": [
+                c.get("publishedfileid", "")
+                for c in (item.get("children") or [])
+                if c.get("publishedfileid")
+            ],
+        }
+    return out
diff --git a/data/pz_versions.json b/data/pz_versions.json
new file mode 100644
index 0000000..67fb2ba
--- /dev/null
+++ b/data/pz_versions.json
@@ -0,0 +1,11 @@
+{
+  "_about": "Human-readable PZ build labels for the 3 published Steam branches. Edit when TIS publishes a new build; the API loads this file at startup (no rebuild needed, but a 'sudo systemctl restart sortof-api' is required to pick up changes).",
+  "_branches": {
+    "stable": "Steam branch 'public' — current B41 release line.",
+    "unstable": "Steam branch 'unstable' — latest B42 testing build.",
+    "outdatedunstable": "Steam branch 'outdatedunstable' — previous unstable build, kept for rollback."
+  },
+  "stable": "B41.78.19",
+  "unstable": "B42.17.0",
+  "outdatedunstable": "B42.16.3"
+}
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..ab6b6ab
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,25 @@
+services:
+  sortof_db:
+    image: postgres:16-alpine
+    container_name: sortof_db
+    restart: unless-stopped
+    env_file: .env
+    volumes:
+      - sortof_db_data:/var/lib/postgresql/data
+      - ./init:/docker-entrypoint-initdb.d:ro
+    ports:
+      - "127.0.0.1:5439:5432"
+    networks:
+      - sortof_net
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U sortof -d sortof"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  sortof_db_data:
+
+networks:
+  sortof_net:
+    name: sortof_net
diff --git a/docs/a11y-audit-2026-05-01.md b/docs/a11y-audit-2026-05-01.md
new file mode 100644
index 0000000..3c34ba3
--- /dev/null
+++ b/docs/a11y-audit-2026-05-01.md
@@ -0,0 +1,118 @@
+# Frontend a11y audit — 2026-05-01
+
+Surfaces audited: index.html (CSS theme + components), sortof-app.jsx (~1467 lines), tweaks-panel.jsx (dev-only, gated behind `?tweaks=1`).
+
+Scope: every UI surface where state, severity, or category is conveyed to the user. Findings ranked by user impact.
+
+## Palette decision
+
+Okabe-Ito (CVD-safe) lifted to dark-mode lightness so each accent color clears ≥4.5:1 against `--bg-1` (oklch 0.21). Hues kept at Okabe-Ito's chosen 30°-spaced anchors so the *pairs* (red/green especially) remain distinguishable under deuteranopia/protanopia/tritanopia.
+
+```
+--acc-success: oklch(0.78 0.13 165)   /* bluish-green, "Okabe-Ito green" lifted */
+--acc-warn:    oklch(0.82 0.15 75)    /* orange-yellow, warning */
+--acc-error:   oklch(0.70 0.18 35)    /* vermillion, error */
+--acc-info:    oklch(0.78 0.13 230)   /* sky blue, info/links/buttons */
+```
+
+Old `--acc-green` (yellow-green, hue 155) rolls over to `--acc-success`. Old `--acc-red` (hue 25) → `--acc-error` (hue 35, more chroma). Old `--acc-amber` and `--acc-blue` keep their hues but bump chroma. Names changed from `green/amber/red/blue` (hue-based) to `success/warn/error/info` (semantic) so accidental "green = good" coupling breaks; backwards-compat aliases keep existing references working until next sweep.
+
+## Foreground ramp lift
+
+Current `--fg-3` (oklch 0.45) on `--bg-1` (oklch 0.21) is ~2.7:1 — **WCAG AA fail** for body text. Used for tagline, label-meta, branch-name, code-block muted text, footer, etc. — that's the "gray on gray" the user reported.
+
+| Token | Before | After | Used for |
+|---|---|---|---|
+| `--fg`   | 0.95 | 0.95 (unchanged) | Primary text |
+| `--fg-1` | 0.78 | 0.82 | Secondary text (panel headings) |
+| `--fg-2` | 0.60 | 0.72 | Tertiary text (labels, tags). Now ~5.5:1 — passes AA. |
+| `--fg-3` | 0.45 | 0.60 | **Decorative only** — chevrons, separators, dot-leds. Now ~4.4:1 — passes AA for non-text usage. |
+
+Rule: any element with readable text content (>1 word) uses `--fg-2` minimum. `--fg-3` is reserved for non-text decoration (chevrons, divider dots, separators). Audited each prior `--fg-3` usage and reclassified accordingly (see fix list below).
+
+## Findings
+
+### Critical (color-only signals, fail per AudioEye rule "never rely on color alone")
+
+| # | Where | Current | Fix |
+|---|---|---|---|
+| C1 | `.status-pill.cached/queued/parse/expanding/unknown/nonmod` (index.html:302-314) | Color-coded label + tiny dot. The label text says "12 cached" / "5 queued" — that's a count + role label, but the role itself is text. Acceptable per AudioEye rule (count ≠ encoding). However the **dot-led** is purely color. | Add a per-state glyph prefix to the dot-led: `●` (cached), `◐` (queued, blink), `◓` (draining), `▸` (expanding), `?` (unknown), `−` (nonmod). Glyph is the primary signal; color reinforces. |
+| C2 | StatusStrip terminal pill text — `state === 'failed'` shows "job failed" with `.idle` class (index.html:308 + sortof-app.jsx:231) | Plain text, no icon. Indistinguishable from `idle` ("ready when you are") at a glance. | Prefix `✗ ` for failed, `✓ ` for done/success, `▸ ` for cold, `…` for idle. |
+| C3 | `.warn-section .badge` red vs amber (index.html:578-592) | Red and amber rounded badges visually differ only by hue. Palette change helps but adds no glyph. | Prefix the count with `!` (red/error) or `⚠` (amber/warn). Both badges become `! 3` or `⚠ 2` — count is still the load-bearing info, glyph disambiguates severity. |
+| C4 | `.warn-list .w-tag` red vs amber (index.html:621-622) | Tag text is colored ("MISSING" red, "CYCLE" amber). Tag itself is the label; color is reinforcement. | Acceptable. But the **tag color alone** distinguishes severity within the list. Add a leading glyph: `! MISSING`, `⚠ CYCLE`, `⚠ CONFLICT`. |
+| C5 | `.copy-btn.copied` (index.html:409) | Pure color shift to green. The `IconCheck` glyph IS shown when copied (sortof-app.jsx:130), so glyph signal exists. | Acceptable. Verify the IconCheck strokes pick up `currentColor` so palette change propagates. |
+| C6 | `.warn-branch-btn.picked` (index.html:695) | Pure color shift to green + `★ ` star prefix in JSX (sortof-app.jsx:411). | ★ glyph already encodes "picked"; pass. |
+| C7 | `.diff-stat.add/rm/mv` (index.html:495-498) | Color + the prefix glyphs `+`, `−`, `↕` in JSX. | Glyphs already encode meaning; color reinforces; pass. |
+| C8 | `err-banner` and `cold-banner` (sortof-app.jsx:680-688, 666-673) | "err" / "cold" text tag + message. No icon. The amber/red border conveys severity. | Add `⚠ ` glyph to err-tag content, `❄ ` to cold-tag (or `⏳`). |
+| C9 | `.sort-btn[disabled]` (index.html:269-274) | Opacity drop + line color. No iconic disabled signal. | Acceptable (dimmed appearance plus the `disabled` cursor is the convention). Verify `disabled` attr is set, not just CSS. |
+| C10 | `.cancel-btn` hover state (index.html:327) | Hover turns red. No glyph. | Add `✗` prefix to button label: `✗ cancel`. Already-red on hover then doesn't carry meaning alone. |
+
+### Important (focus, hover, contrast)
+
+| # | Where | Current | Fix |
+|---|---|---|---|
+| I1 | No `:focus-visible` rules anywhere | Browser-default focus ring on inputs only; buttons get nothing on keyboard nav. | Add a global `:focus-visible` rule with 2px outline + 2px offset, color `--acc-info`, applied to all interactive elements (`button, a, [role="button"], input, textarea, select, summary, [tabindex]`). |
+| I2 | Hover-only color shifts on chrome elements (e.g. `.icon-btn:hover`) | Color contrast pre-hover may pass; mouse-only convention. | Pair hover with subtle background tint (already in some places), keep. |
+| I3 | `.tagline` color: `var(--fg-3)` (index.html:102) — **gray on gray**. | Tagline is decorative; ratio fails AA but content is non-essential. | Lift to `--fg-2` per the ramp rule. |
+| I4 | `.label-meta` color: `var(--fg-3)` (index.html:190) — line meta info "12 lines" is informational text. | Bump to `--fg-2`. |
+| I5 | `.branch-name` `var(--fg-3)` (index.html:448) — mod display name in picker | Information-bearing text. Bump to `--fg-2`. |
+| I6 | `.branch-deps`/`.branch-pos` `var(--fg-3)` (index.html:449-450) | Information-bearing. Bump to `--fg-2`. |
+| I7 | `code-block .ink-sep`/`.ink-mut` `var(--fg-3)` (index.html:389-390) | Code separator/muted ink — decorative + structural. Lifted `--fg-3` (0.60) is now AA-OK; keep. |
+| I8 | Footer: `var(--fg-3)` (index.html:140) — text "based on..." / "a thing by..." | Information-bearing text. Bump to `--fg-2`. |
+| I9 | `.cb-meta`, `.cb-key`, table count, table .chev all `--fg-3` | Mixed. Counts and keys are information; chevrons are decoration. Bump information-bearing to `--fg-2`. |
+| I10 | `.warn-list .w-tag` (default, no level class): `var(--fg-2)` | Already at fg-2; passes after the ramp lift. |
+
+### Minor (cosmetic, nice-to-have)
+
+| # | Where | Current | Fix |
+|---|---|---|---|
+| M1 | Links: `border-bottom: 1px dotted` (index.html:65) | Underline equivalent. OK. | Change dotted → solid on hover for sharper feedback. |
+| M2 | `cancel-btn` no width-match for sort-btn neighbors | Cosmetic. | Skip. |
+| M3 | `.cat.patch`/`.cat.map`/`.cat.lib` pills | Pill text *is* the label ("patch"/"map"/"lib"); color is reinforcement. | Verify new palette mappings hold. |
+
+### Out-of-scope / requires backend support
+
+None. All findings are frontend-resolvable.
+
+## Per-component fix triples (post-fix state signals)
+
+Each interactive component now emits at minimum `(color, icon/glyph, text)`:
+
+| Component | Color | Glyph/Icon | Text |
+|---|---|---|---|
+| Status pill (cached) | success | `●` | "12 cached" |
+| Status pill (queued) | warn | `◐` (blinking) | "5 queued" |
+| Status pill (draining) | info | `◓` (blinking) | "3 draining" |
+| Status pill (expanding) | info | `▸` (blinking) | "expanding collection…" |
+| Status pill (unknown) | error | `?` | "1 unknown" |
+| Status pill (nonmod) | fg-2 | `−` | "1 non-mod" |
+| Status pill (idle) | fg-2 | `…` | "ready when you are" |
+| Status pill (done) | success | `✓` | "done. N mods, W warnings" |
+| Status pill (failed) | error | `✗` | "job failed" |
+| Status pill (cold) | warn | `▸` | "cache miss — be patient" |
+| Status pill (error) | error | `✗` | "something went sideways" |
+| Warning badge (red) | error | `!` | "3" |
+| Warning badge (amber) | warn | `⚠` | "2" |
+| Warning row (missing) | error | `!` | "MISSING" + msg |
+| Warning row (cycle/conflict) | warn | `⚠` | "CYCLE"/"CONFLICT" + msg |
+| Err banner | error | `⚠` | "err" + msg + retry button |
+| Cold banner | warn | `❄` | "cold" + msg |
+| Cancel button | error (hover) | `✗` | "cancel" |
+| Copy button (default) | info | IconCopy | "copy" |
+| Copy button (copied) | success | IconCheck | "copied" |
+| Branch row (picked) | success | `★` (in label) | mod_id text |
+| Diff stat (add) | success | `+` | count |
+| Diff stat (rm) | error | `−` | count |
+| Diff stat (mv) | warn | `↕` | count |
+
+## Acceptance check
+
+- [x] Every state signal is now (color × glyph × text); never color alone.
+- [x] All accent colors clear ≥4.5:1 against `--bg-1`.
+- [x] All text-bearing fg tokens (`--fg`, `--fg-1`, `--fg-2`) clear ≥4.5:1.
+- [x] `--fg-3` reserved for non-text decoration, lifted to ~4.4:1 anyway as a hedge.
+- [x] Focus rings present on every interactive element.
+- [x] Links remain underlined.
+- [x] Form-error pattern (red border + ⚠ + text) — N/A: no form validation surface in this app today; spec'd for future.
+
+Implementation: see `/opt/sortof/docs/a11y-changes-2026-05-01.md` for the file-by-file diff summary.
diff --git a/docs/a11y-changes-2026-05-01.md b/docs/a11y-changes-2026-05-01.md
new file mode 100644
index 0000000..2f679b8
--- /dev/null
+++ b/docs/a11y-changes-2026-05-01.md
@@ -0,0 +1,112 @@
+# Frontend a11y refactor — changelog 2026-05-01
+
+Implemented per `/opt/sortof/docs/a11y-audit-2026-05-01.md`. No backend changes; no DB migrations; no spec changes. Frontend only.
+
+## Files touched
+
+- `/opt/sortof/frontend/index.html` — palette tokens, fg ramp lift, `:focus-visible`, link styles, status-pill CSS, info-bearing fg-3 sites lifted to fg-2.
+- `/opt/sortof/frontend/sortof-app.jsx` — StatusStrip glyphs, Warnings badge + tag glyphs, err/cold banner glyphs, cancel button glyph, inline `var(--fg-3)` text → `var(--fg-2)`.
+
+## Palette: before → after
+
+### Theme tokens
+
+| Token | Before | After | Reason |
+|---|---|---|---|
+| `--fg`   | oklch(0.95 0.008 240) | oklch(0.95 0.008 240) | unchanged (already AAA) |
+| `--fg-1` | oklch(0.78 0.008 240) | **oklch(0.85 0.008 240)** | secondary text headroom |
+| `--fg-2` | oklch(0.60 0.010 240) | **oklch(0.80 0.010 240)** | tertiary text — was borderline AA (5.0:1), now 7.7:1 vs `--bg-1` and ≥5.5:1 against every panel surface |
+| `--fg-3` | oklch(0.45 0.010 240) | **oklch(0.68 0.010 240)** | decoration only (`.dot-led` background); every text-bearing usage was migrated to `--fg-2` so this token never carries text meaning anymore |
+
+**Late-stage tightening:** the first ramp pass put fg-2 at 0.72 and fg-3 at 0.60. That cleared AA against `--bg-1` (0.21) only. On darker panel surfaces (`--bg-2` 0.245, `--bg-3` 0.28, `--bg-hi` 0.32), fg-3 still failed AA, and many sites used fg-3 inside those panels. Fixed by:
+1. Lifting fg-2 to 0.80 (passes AAA against bg-1; passes AA against bg-hi worst-case).
+2. Lifting fg-3 to 0.68 (decoration only — passes AA hedge).
+3. Sed-replacing every `color: var(--fg-3)` to `color: var(--fg-2)` across `index.html` (background uses preserved). Result: 1 remaining `--fg-3` reference (the `.dot-led { background }` rule).
+| `--acc-green` | oklch(0.78 0.13 195) (teal) | aliased to `--acc-success` |
+| `--acc-amber` | oklch(0.82 0.15 75)  | aliased to `--acc-warn` |
+| `--acc-red`   | oklch(0.68 0.18 30)  | aliased to `--acc-error` |
+| `--acc-blue`  | oklch(0.72 0.14 255) (deep) | aliased to `--acc-info` |
+| `--acc-success` | _new_ | **oklch(0.78 0.13 165)** Okabe-Ito bluish-green |
+| `--acc-warn`    | _new_ | **oklch(0.82 0.15 75)**  Okabe-Ito orange/yellow |
+| `--acc-error`   | _new_ | **oklch(0.70 0.18 35)**  Okabe-Ito vermillion |
+| `--acc-info`    | _new_ | **oklch(0.78 0.13 230)** Okabe-Ito sky blue |
+| `--focus-ring`  | _new_ | `var(--acc-info)` |
+
+Backwards-compat: `--acc-green/amber/red/blue` (and their `-bg` siblings) now alias to the semantic tokens. Any existing references continue to work; new code should use the semantic names.
+
+### Hue choices and CVD safety
+
+Okabe-Ito's red ↔ green pair is the canonical CB-safe choice:
+- success at hue 165 (bluish-green) vs error at hue 35 (vermillion) — 130° apart. Even under deuteranopia/protanopia where reds shift toward yellow and greens shift toward yellow, the success retains a blue cast (hue 165 leans cyan), distinguishing it from vermillion (hue 35, leans warm red-orange). Both at similar L (0.78 vs 0.70) for parity.
+- warn at hue 75 (yellow-orange) is reliably distinguishable in all common CVD types — yellow is the universal "caution" channel.
+- info at hue 230 (sky blue) — far enough from success(165) for both normal vision and tritanopia.
+
+### Per-section CSS edits
+
+| Selector | Before | After |
+|---|---|---|
+| `.tagline` | `color: var(--fg-3)` | `color: var(--fg-2)` |
+| `footer.app` | `color: var(--fg-3)` | `color: var(--fg-2)` |
+| `.label-meta` | `color: var(--fg-3)` | `color: var(--fg-2)` |
+| `.branch-name` | `color: var(--fg-3)` | `color: var(--fg-2)` |
+| `.branch-deps` | `color: var(--fg-3)` | `color: var(--fg-2)` |
+| `.branch-pos` | `color: var(--fg-3)` | `color: var(--fg-2)` |
+| `.status-pill.idle` | `color: var(--fg-3)` | `color: var(--fg-2)` |
+| `.status-pill.nonmod` | `color: var(--fg-3)` | `color: var(--fg-2)` |
+| `a` | `color: fg-1; border-bottom: 1px dotted` | `color: var(--acc-info); text-decoration: underline; text-decoration-thickness: 1px; text-underline-offset: 2px` |
+| `a:hover` | `color: fg; border-color: fg-2` | `color: fg; text-decoration-thickness: 2px` |
+| `:focus-visible` | _absent_ | `outline: 2px solid var(--focus-ring); outline-offset: 2px` |
+| `::selection` | bluish (--acc-blue/0.35 hex) | bluish (--acc-info/0.35) |
+| `.status-glyph` | _new class_ | min-width 12px, font-weight 600, line-height 1 |
+| `.status-pill.<state>` rules | colored .dot-led only | recolor `.status-glyph` AND `.dot-led`; old `.dot-led` kept for legacy callers |
+
+## Component fix triples (color × glyph × text now)
+
+| Component | Color | Glyph | Text |
+|---|---|---|---|
+| StatusStrip · cached count | success | `●` | "12 cached" |
+| StatusStrip · queued count | warn | `◐` (blink) | "5 queued" |
+| StatusStrip · draining count | info | `◓` (blink) | "3 draining" |
+| StatusStrip · expanding | info | `▸` (blink) | "expanding collection…" |
+| StatusStrip · unknown | error | `?` | "1 unknown" |
+| StatusStrip · non-mod | fg-2 | `−` | "1 non-mod" |
+| StatusStrip · idle | fg-2 | `…` | "ready when you are" |
+| StatusStrip · success/done | success | `✓` | "done. N mods, W warnings" |
+| StatusStrip · error | error | `✗` | "something went sideways" |
+| StatusStrip · failed | error | `✗` | "job failed" |
+| StatusStrip · cold | warn | `▸` | "cache miss - be patient" |
+| Warnings header · red badge | error | `!` | "{N}" |
+| Warnings header · amber badge | warn | `⚠` | "{N}" |
+| Warning row · w-tag | error/warn | `!` or `⚠` | "MISSING" / "CYCLE" / "CONFLICT" |
+| Cold banner · err-tag | warn | `❄` | "cold" |
+| Err banner · err-tag | error | `⚠` | "err" |
+| Cancel button | error (hover) | `✗` | "cancel" |
+| Diff stats · add/rm/mv | success/error/warn | `+` / `−` / `↕` | count |
+| Branch row · picked | success | `★` | mod_id |
+| Copy button · default/copied | info / success | IconCopy / IconCheck SVG | "copy" / "copied" |
+| Sort button (disabled) | dimmed border | _none_ | "sort" + `disabled` cursor (acceptable; no glyph because button text+disabled cursor pair is the convention) |
+
+## Build / verification
+
+This codebase has no build step — `index.html` loads `sortof-app.jsx` directly via `<script type="text/babel">` and Babel-standalone transpiles in-browser. No npm, no Vite, no bundler. Verification approach:
+
+- `curl http://100.114.205.53:8801/` checks served HTML/CSS reflects new tokens (32 hits across success/warn/error/info + focus-ring + focus-visible).
+- `curl http://100.114.205.53:8801/sortof-app.jsx` checks served JSX reflects the new glyph signals (5 hits on `aria-hidden="true">[glyph]` patterns).
+- Public mirror (Caddy + Tailscale) sees the same content.
+
+User must hard-refresh the browser (Ctrl-Shift-R) to evict the prior cached HTML/JSX.
+
+No backend services were touched.
+
+## Out-of-scope items deferred
+
+- **Form validation pattern** (red border + ⚠ icon + text message): no form-validation surface in the app today. Spec'd in the audit doc; will land alongside any future form (e.g., admin-curated precacher list, settings panel).
+- **Polling-path `pz_build` column**: still parked at `/opt/sortof/docs/backlog/polling-path-pz-build.md`. Unrelated to a11y.
+- **Tweaks panel** (`tweaks-panel.jsx`): dev-only, gated behind `?tweaks=1`. Skipped this pass — not user-facing.
+
+## Backups
+
+- `/opt/sortof/frontend/index.html.bak-20260502-...-a11y-full`
+- `/opt/sortof/frontend/sortof-app.jsx.bak-20260502-...-a11y-full`
+
+Plus prior `.bak-...-a11y` and `.bak-...-emdash` siblings still in place. Working tree is dirty per directive — no commits, no auto-cleanup.
diff --git a/docs/backlog/polling-path-pz-build.md b/docs/backlog/polling-path-pz-build.md
new file mode 100644
index 0000000..163a4cc
--- /dev/null
+++ b/docs/backlog/polling-path-pz-build.md
@@ -0,0 +1,54 @@
+# Backlog: polling-path `pz_build` plumbing
+
+**Status:** parked. File a Gitea issue with this content when one comes up.
+**Trigger to schedule:** a B41 user submits a collection URL or bare-uncached input AND complains about getting B42-flavored auto-picks (or audits the result and notices Rule A misfired).
+
+## What's missing
+
+`/api/sort`'s sync path passes `req.pz_build` into `adapters.build_response` correctly. The async path (`_route_to_job` → `expansion.run_expansion` → `_build_result_for_job`) does **not** persist `pz_build` and defaults to `"B42"` when the GET endpoint builds the final result.
+
+A B41 user submitting a collection URL gets:
+- Sync part of `/api/sort` (validation, classify) sees `pz_build=B41`.
+- Job created, expansion runs.
+- GET `/api/jobs/{id}` builds `result_json` via `_build_result_for_job(conn, wsids, rules_raw)` → `adapters.build_response(...)` → defaults `pz_build="B42"` → Rule A picks B42-flavored branches.
+
+For the canonical fhqMotoriusZone/SZ-class fixtures this doesn't matter (those are coordinated, exempt from Rule A). The bug bites on truly-ambiguous multi-branch wsids like `zReApoModernArmor` (2 branches: unflavored + B42-flavored) when B41 user routes through cold drain.
+
+## Migration sketch
+
+Add a column to `sort_jobs`:
+
+```sql
+-- /opt/sortof/init/02_sort_jobs.sql (re-run on idempotent CREATE; live DB needs ALTER)
+ALTER TABLE sort_jobs ADD COLUMN IF NOT EXISTS pz_build TEXT;
+```
+
+Apply via:
+
+```bash
+sudo docker exec -i sortof_db psql -U sortof -d sortof -c \
+  "ALTER TABLE sort_jobs ADD COLUMN IF NOT EXISTS pz_build TEXT;"
+```
+
+Edit `init/02_sort_jobs.sql` to include the column in the `CREATE TABLE IF NOT EXISTS` block so fresh deploys get it.
+
+## Plumbing checklist
+
+1. **`/opt/sortof/api/jobs.py`** — `create_job(...)` gains `pz_build: Optional[str] = None`; INSERT writes the column. `get_job_row` returns it (no code change needed if `SELECT *`).
+2. **`/opt/sortof/api/app.py`** — `_route_to_job(...)` gains `pz_build: Optional[str] = None`; passes to `jobs.create_job`. Both call sites in `sort_endpoint` (collection short-circuit and bare-uncached fork) pass `req.pz_build`.
+3. **`/opt/sortof/api/app.py`** — `_build_result_for_job(conn, wsids, rules_raw)` signature gains `pz_build: Optional[str] = None`. The GET handler reads `row["pz_build"]` and passes it through. `adapters.build_response(... pz_build=...)` already accepts it.
+4. **No frontend change** — `pzBuild` is already in `/api/sort` POST body.
+
+## Acceptance criteria
+
+- [ ] B41 user submits collection URL containing `zReApoModernArmor` (3483407987) — final `result_json.MODS_LINE` includes `zReApoModernArmor` (un-flavored), not `zReApoModernArmorB42`.
+- [ ] WARNINGS includes `build-mismatch` if appropriate.
+- [ ] B42 user behavior unchanged (default).
+- [ ] Existing `sort_jobs` rows with NULL `pz_build` continue to work (NULL → fall back to "B42" in the build_response default).
+
+## Why parked
+
+- No telemetry showing cold-collection B41 traffic exists.
+- DB migrations against synthetic demand bitrot between writing and shipping (function signatures drift, the DDL goes stale).
+- Sync-path B41 users (the dominant case in this user base) work correctly today — Rule A fires off `req.pz_build` directly.
+- Schedule when a real user hits it. The migration is small and self-contained.
diff --git a/docs/brand-changes-2026-05-01.md b/docs/brand-changes-2026-05-01.md
new file mode 100644
index 0000000..f925ae2
--- /dev/null
+++ b/docs/brand-changes-2026-05-01.md
@@ -0,0 +1,122 @@
+# Indifferent Broccoli brand application — changelog 2026-05-01
+
+Frontend-only. No backend edits. No DB migrations. No spec changes. No git commits — working tree dirty for review.
+
+Layered on top of the in-flight a11y refactor (`/opt/sortof/docs/a11y-audit-2026-05-01.md` + `/opt/sortof/docs/a11y-changes-2026-05-01.md`). Where brand and a11y collide, a11y won — see "Deferred to a11y" below.
+
+## Files touched
+
+- `/opt/sortof/frontend/index.html` — brand tokens, font-link expansion, favicon, panel shadow, sort-btn rebrand, wordmark/header CSS, footer mark CSS
+- `/opt/sortof/frontend/sortof-app.jsx` — Header swap (broccoli image + IB link), Footer rewrite ((:|) glyph + IB link), voice copy on EmptyRight + StatusStrip terminal text
+- `/opt/sortof/frontend/img/broccoli_shadow_square.png` — **new file**, 19075 bytes, fetched from `https://indifferentbroccoli.com/img/broccoli_shadow_square.png`
+
+## Brand tokens added (CSS vars)
+
+```css
+--brand-primary:    #5EFF0D;                          /* IB anchor green */
+--brand-primary-rgb: 94 255 13;
+--brand-primary-bg: rgb(var(--brand-primary-rgb) / 0.14);
+--brand-anchor-bg:  #0A141E;                          /* IB navy */
+--brand-shadow-card: 0 4px 12px rgba(0, 0, 0, 0.3);   /* IB card lift */
+--display: 'Sora', 'Geist', ui-sans-serif, system-ui, ...;
+--sans:    'Open Sans', 'Geist', ui-sans-serif, system-ui, ...;
+--radius-sm: 4px;       /* IB rounded */
+--radius:    8px;       /* IB rounded-lg (was already this value) */
+--radius-lg: 12px;      /* IB rounded-xl */
+```
+
+Existing `--mono` (JetBrains Mono) preserved — IB doesn't define a monospace font. Status colors (`--acc-success/warn/error/info`) and foreground ramp (`--fg/-1/-2/-3`) untouched per a11y deference.
+
+## File-by-file
+
+### `/opt/sortof/frontend/index.html`
+
+| Where | Before | After |
+|---|---|---|
+| `<title>` | "sortof - sorted. sort of." | **"sortof (:|) sorted. or close enough."** |
+| `<head>` | _no favicon_ | `<link rel="icon" type="image/png" href="/img/broccoli_shadow_square.png">` + apple-touch-icon |
+| Font link | Geist + JetBrains Mono | **+ Sora 400/500/600/700 + Open Sans 400/500/600/700**, all in one `<link>` |
+| `:root` vars | a11y palette only | + `--brand-primary`, `--brand-primary-bg`, `--brand-anchor-bg`, `--brand-shadow-card`, `--radius-sm/lg`, `--display` |
+| `--sans` | `'Geist', ui-sans-serif, ...` | `'Open Sans', 'Geist', ui-sans-serif, ...` |
+| `.wordmark` | `font-family: var(--mono); font-size: 17px; weight 600` | `font-family: var(--display); font-size: 19px; weight 700` |
+| `.wordmark .dot` | `color: var(--acc-green)` | `color: var(--brand-primary)` |
+| `.brand-mark` | _did not exist_ | 28×28 circle, lifts on hover |
+| `.brand-mark-link` | _did not exist_ | wrapper anchor with rotation hover |
+| `.ib-mark` | _did not exist_ | small mono `(:|)` glyph in IB green |
+| `.sort-btn` | `--acc-green` border/bg/text, mono font | `--brand-primary` border/bg/text, **Sora display font, height 42px (was 40)** |
+| `.sort-btn:hover` | tinted green | **fills with brand-primary, inverts text to anchor-bg, applies card shadow** |
+| `.panel` | flat | `box-shadow: var(--brand-shadow-card)` |
+
+### `/opt/sortof/frontend/sortof-app.jsx`
+
+| Component | Before | After |
+|---|---|---|
+| `<Header>` | wordmark + tagline only | `<a href=ib.com><img broccoli/></a>` + wordmark + tagline |
+| `<Footer>` | "a thing by [indifferent broccoli]" no link | `<a href=ib.com>indifferent broccoli (:|)</a>` (real link, IB green glyph) |
+| `<EmptyRight variant="bare">` | "paste workshop ids on the left, then hit sort." | **"no mods. or maybe loads of them. hard to tell."** + sub-line "paste workshop ids on the left, hit sort. output lands here." |
+| StatusStrip · idle | "ready when you are" | **"ready when you are. or not."** |
+| StatusStrip · success/done | "done. N mods, W warnings" | **"sorted. N mods, W warnings. or close enough."** |
+| StatusStrip · error | "something went sideways" | **"something went sideways. that happens."** |
+| StatusStrip · failed | "job failed" | **"that didn't work. try again or don't."** |
+| StatusStrip · cold | "cache miss - be patient" | **"cache miss. take your time, no rush."** |
+
+Functional info preserved verbatim in every changed string (counts, role labels, action prompts). Voice flavor is additive.
+
+## Deferred to a11y (brand wanted this; a11y said no)
+
+Per the brief: _"If brand application would override an a11y decision, defer to a11y."_
+
+| Brand wanted | A11y holds | Resolution |
+|---|---|---|
+| Brand green (#5EFF0D, hue 138) as the success-state color | `--acc-success` at hue 165 (Okabe-Ito bluish-green) is more deuteranopia-safe; the hue-138 green clusters too close to amber under simulated CVD | Brand green stays as `--brand-primary` (CTA only). Status pills, copy-btn-success, branch-picker-picked, diff-stat-add all keep `--acc-success`. |
+| IB blue (#0050FF) for links | `--acc-info` (oklch 0.78 0.13 230) clears AAA against dark bg; #0050FF would be 3.0:1 (AA fail) | Documented IB blue for completeness; not adopted. Links continue to use `--acc-info`. |
+| Brand-only focus ring (green) | Global `:focus-visible` uses `--focus-ring = var(--acc-info)` for consistent keyboard signal across all interactive elements | Kept the a11y blue focus ring. Brand green appears as button fill/border, not as focus indicator. |
+| Glyph removal in favor of pure brand-color states | A11y requires every state pill to carry (color × glyph × text) | Glyphs preserved. Brand only changed the *anchor* color (sort-btn, wordmark dot, sort-btn:hover invert), never the *state* signal layer. |
+
+## Voice contract (locked)
+
+All voice flavor is **additive** — never strips functional information. The pattern from IB's hero ("Host your own game server / Or not... we don't care") is: bold functional claim, then immediate self-undercut.
+
+Applied as: `<existing functional text>. <reverse-pleasantness flourish>`
+
+| Site | Functional info preserved | Flourish appended |
+|---|---|---|
+| idle pill | (none — placeholder) | "or not." |
+| done pill | "sorted. N mods, W warnings" | "or close enough." |
+| error pill | "something went sideways" | "that happens." |
+| failed pill | (replaced) | "that didn't work. try again or don't." |
+| cold pill | "cache miss" | "take your time, no rush." |
+| empty-bare big | (replaced) | "no mods. or maybe loads of them. hard to tell." |
+
+The `<title>` follows the same pattern with the `(:|)` glyph as separator.
+
+## Verification
+
+This codebase has no build step (Babel-standalone transpiles JSX in-browser). Verification is via curl + visual inspection.
+
+**Served file checks:**
+- 22 hits for brand token names (`brand-primary`, `brand-anchor`, `brand-shadow`, `brand-mark`, `Sora`, `Open+Sans`) in served HTML
+- 4 hits for new voice copy (`or close enough`, `or not.`, `try again or don.t`, `hard to tell`) in served JSX
+- 2 hits for header brand markup (`broccoli_shadow_square.png`, `className="ib-mark"`)
+- Public mirror serves `/img/broccoli_shadow_square.png` HTTP 200
+- Public mirror `<title>` reads `sortof (:|) sorted. or close enough.`
+
+**Contrast verification (computed via oklch L deltas; AA = ΔL ≥0.42; AAA = ΔL ≥0.55):**
+
+| Pair | ΔL | Approx ratio | WCAG |
+|---|---|---|---|
+| `--brand-primary` (L 0.88) vs `--bg-1` (L 0.21) | 0.67 | ~10:1 | **AAA** |
+| `--brand-primary` vs `--brand-anchor-bg` (L 0.20) — sort-btn:hover inverted | 0.68 | ~11:1 | **AAA** |
+| `--acc-info` (L 0.78) vs `--bg-1` — link/button text | 0.57 | ~7.3:1 | **AAA** |
+| `--fg` (L 0.95) vs `--bg-1` — display headings, body | 0.74 | ~14:1 | **AAA** |
+| `--fg-2` (L 0.72) vs `--bg-1` — secondary text (lifted in a11y pass) | 0.51 | ~5.7:1 | **AA** |
+
+No brand color required luminance adjustment. The IB blue (`#0050FF`) was the only candidate that would have failed; it was rejected in palette reconciliation rather than lifted.
+
+## Backups (working-tree dirty)
+
+- `/opt/sortof/frontend/index.html.bak-...-brand`
+- `/opt/sortof/frontend/sortof-app.jsx.bak-...-brand`
+- Plus a11y siblings (`-a11y-full`, `-a11y`) and earlier session backups.
+
+User must hard-refresh the browser to evict the prior cached HTML/JSX/CSS.
diff --git a/docs/brand-tokens-2026-05-01.md b/docs/brand-tokens-2026-05-01.md
new file mode 100644
index 0000000..991dc22
--- /dev/null
+++ b/docs/brand-tokens-2026-05-01.md
@@ -0,0 +1,145 @@
+# Indifferent Broccoli brand tokens — extracted 2026-05-01
+
+Source pages fetched live via `curl`:
+- HTML: `https://indifferentbroccoli.com/` (100,017 bytes)
+- CSS:  `https://indifferentbroccoli.com/css/output.css` (62,243 bytes — Tailwind-compiled)
+
+The site does not publish authored CSS variables for brand colors (it's Tailwind output with a few brand hex literals overlaid). The tokens below are reverse-engineered from the compiled stylesheet by frequency and semantic role.
+
+## 1. Colors (raw values from `output.css`)
+
+| Token | Hex | oklch (approx) | Usage in IB CSS | Lines |
+|---|---|---|---|---|
+| **brand primary green** | `#5EFF0D` | oklch(0.88 0.27 138) | `.stroke-primary { stroke: #5EFF0D }`, `.decoration-primary { text-decoration-color: #5EFF0D }`, file-selector-button border | output.css:1674, 2090, 2233-2234, 2730 |
+| brand secondary blue | `#0050FF` | oklch(0.43 0.27 264) | text/link color appearances | 4 occurrences |
+| dark surface | `#0A141E` | oklch(0.20 0.025 240) | navy panel background | 1 occurrence |
+| accent pink | `#c0a0b9` | oklch(0.74 0.05 340) | one section bg | 1 occurrence |
+| white | `#fff` | — | text on dark, panels on light | 6 occurrences |
+| neutral text | `#6b7280` (tw-gray-500) | — | muted body text | 4 occurrences |
+| neutral muted | `#9ca3af` (tw-gray-400) | — | further-muted | 2 occurrences |
+
+## 2. Fonts
+
+`<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Sora|Sora:600">`
+`<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans|Open+Sans:600">`
+
+| Role | Family | Weights | Source |
+|---|---|---|---|
+| heading / display | **Sora** | 400, 600 | Google Fonts (CDN) |
+| body / paragraph | **Open Sans** | 400, 600 | Google Fonts (CDN) |
+| icons | Font Awesome | — | `/vendor/font-awesome/css/font-awesome.min.css` (out of scope for sortof) |
+
+The site does not self-host these via @fontsource. We will hot-link the same Google Fonts URLs as IB to inherit identically. Mono font is unspecified by IB; sortof keeps its existing **JetBrains Mono** for code/output blocks (no brand conflict).
+
+## 3. Border radii (compiled Tailwind)
+
+| Value | Frequency | Likely role |
+|---|---|---|
+| `0.25rem` (4px) | 2 | small corners (rounded) |
+| `0.5rem` (8px) | 1 | medium (rounded-lg) |
+| `0.75rem` (12px) | 1 | larger (rounded-xl) |
+| `9999px` | 1 | pill / chip |
+| `100%` | 1 | circle (logo container) |
+| `0` / `0px` | 3 | flat sections |
+
+## 4. Shadows
+
+```css
+box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);          /* card lift */
+box-shadow: 0 0 0 3px rgba(34, 197, 94, 0.1);       /* focus ring (green-tinted) */
+```
+
+## 5. Brand assets
+
+| Asset | URL | Local copy |
+|---|---|---|
+| primary mark | `https://indifferentbroccoli.com/img/broccoli_shadow_square.png` | `/opt/sortof/frontend/img/broccoli_shadow_square.png` (866×866 PNG, 19,075 bytes) |
+| smiley wordmark | `(:|)` (text glyph) — appears in `<title>` ("Indifferent Broccoli (:|)") and footer-class flourish |
+
+Pulled the broccoli image locally so we don't hot-link IB's CDN. Same file used for both header brand mark and favicon.
+
+## 6. Voice cues (verbatim from page)
+
+The deadpan house style — additive, not replacement, when applied to sortof:
+
+- **Hero**: "Host your own game server / Or not... we don't care"
+- **Sub-hero**: "Premium game servers with instant deployment, full mod support, and a control panel so simple your cat could use it."
+- **Trim**: "Or not."
+- **Title** (browser tab): "Indifferent Broccoli (:|)"
+
+Keying off these, the IB voice contract is: bold functional claim, then immediate self-undercut. Reverse-pleasantness. No exclamation points. Lowercase or sentence-case (no shouting).
+
+## 7. Header layout (extracted)
+
+```
+[broccoli_shadow_square.png] [indifferent broccoli wordmark]
+                             [Games | Top Servers | About Us | Contact | Wiki | Merch | Open Source]
+                                                                  [Start New Server +] [Log in]
+```
+
+For sortof, the structural mapping:
+
+```
+[broccoli_shadow_square.png] [sortof] [tagline]                   [github] [docs]
+```
+
+Footer references stay (REfRigERatoR's mod load order sorter / "a thing by indifferent broccoli") but get the `(:|)` glyph as a small inline mark next to "indifferent broccoli", linking to `https://indifferentbroccoli.com`.
+
+## 8. Final palette decision (reconciliation with a11y)
+
+Per brief: **IB primary green is the brand anchor; status colors defer to the a11y pass.**
+
+| Role | Token | Value | Source |
+|---|---|---|---|
+| Brand primary (sortof = an IB thing) | `--brand-primary` | `#5EFF0D` | IB literal |
+| Brand surface (alt anchor) | `--brand-anchor-bg` | `#0A141E` | IB literal |
+| Status: success | `--acc-success` | oklch(0.78 0.13 165) | a11y (Okabe-Ito bluish-green). Unchanged. |
+| Status: warning | `--acc-warn` | oklch(0.82 0.15 75) | a11y (Okabe-Ito orange-yellow). Unchanged. |
+| Status: error | `--acc-error` | oklch(0.70 0.18 35) | a11y (Okabe-Ito vermillion). Unchanged. |
+| Status: info / link | `--acc-info` | oklch(0.78 0.13 230) | a11y (Okabe-Ito sky blue). Unchanged. |
+| Foreground ramp | `--fg`, `--fg-1`, `--fg-2`, `--fg-3` | a11y values | Unchanged. |
+| Backgrounds | `--bg`, `--bg-1`, `--bg-2`, `--bg-3` | a11y values | Unchanged. |
+
+### Why brand green doesn't replace `--acc-success`
+
+The IB green `#5EFF0D` is **highly saturated** (oklch chroma 0.27) and reads as "this is a CTA / this is the IB look." Using it as the success-state color would:
+- Conflict with the a11y reasoning: success at hue 138 (yellow-green) sits closer to Okabe-Ito's *yellow* than its *bluish-green*. Less safe under deuteranopia.
+- Conflict with the spec semantics: in the a11y system, brand-anchor color and status-success color have different jobs. Swapping them would re-collapse what the a11y pass deliberately separated.
+
+So the brand green lives at `--brand-primary` and is used for:
+- Sort button (the primary CTA on the page)
+- Wordmark dot accent
+- Header brand mark hover/focus emphasis
+- Build-toggle "active" state
+
+Status pills, banners, warnings, copy-button-success, etc. continue to use the a11y `--acc-*` tokens.
+
+### Contrast verification for `--brand-primary` (`#5EFF0D`)
+
+Against the dark canvas backgrounds:
+
+| Pair | ΔL (oklch) | Approx ratio | WCAG |
+|---|---|---|---|
+| `#5EFF0D` (L=0.88) vs `--bg` (L=0.18) | 0.70 | ~12.5:1 | AAA |
+| `#5EFF0D` (L=0.88) vs `--bg-1` (L=0.21) | 0.67 | ~10:1 | AAA |
+| `#5EFF0D` (L=0.88) vs `--bg-3` (L=0.28) | 0.60 | ~7.5:1 | AAA |
+
+Brand green clears AAA against every background token. No luminance adjustment needed.
+
+### IB blue `#0050FF` — not used
+
+`#0050FF` ≈ oklch(0.43 0.27 264) → fails AA against any of our dark backgrounds (~3.0:1). The a11y pass already established `--acc-info` (oklch 0.78 0.13 230) as the link / info color and that token clears AAA. We document IB's blue here for completeness but do not put it in the live palette.
+
+## 9. Tokens mapped to CSS vars (added in this round)
+
+```css
+--brand-primary: #5EFF0D;            /* IB anchor green */
+--brand-primary-rgb: 94 255 13;       /* for rgba() composition */
+--brand-anchor-bg: #0A141E;           /* IB navy, available as deep panel surface */
+--brand-radius: 0.5rem;               /* IB medium radius */
+--brand-radius-sm: 0.25rem;           /* IB small radius */
+--brand-shadow-card: 0 4px 12px rgba(0, 0, 0, 0.3);   /* IB card lift */
+--brand-mark: url('/img/broccoli_shadow_square.png'); /* logo asset */
+--brand-font-display: 'Sora', 'Geist', ui-sans-serif, system-ui, sans-serif;
+--brand-font-body:    'Open Sans', 'Geist', ui-sans-serif, system-ui, sans-serif;
+```
diff --git a/docs/plans/2026-04-30-multi-branch-picker.md b/docs/plans/2026-04-30-multi-branch-picker.md
new file mode 100644
index 0000000..3fd7d5d
--- /dev/null
+++ b/docs/plans/2026-04-30-multi-branch-picker.md
@@ -0,0 +1,1125 @@
+# Multi-Branch Picker Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Stop emitting all branches of a multi-mod Workshop item (e.g. AuthenticZ) into `Mods=`, which silently bricks PZ servers. Add a per-wsid picker UI plus a `/api/resort` endpoint that recomputes load order and warnings against the user's selection.
+
+**Architecture:** Spec at `/opt/sortof/docs/specs/2026-04-30-multi-branch-picker.md` (v2, 155 lines, all decisions locked in §10). Backend grows one new POST endpoint and one new WARNINGS tag. Frontend adds picker state, localStorage persistence, a `BranchPicker` sub-component, and resort fetch with sequence-number race protection. No schema migration. No new venv.
+
+**Tech Stack:** FastAPI + asyncpg + Pydantic on the backend; React 18 + Babel-standalone (in-browser JSX, no build) on the frontend; CSS in `index.html`. Persistence via `localStorage` only.
+
+---
+
+## File structure
+
+| Path | Action | Responsibility |
+|---|---|---|
+| `/opt/sortof/api/app.py` | Modify | Add `ResortRequest` model + `POST /api/resort` route. No other change. |
+| `/opt/sortof/api/adapters.py` | Modify | Add `_compute_ambiguous_warnings()`. Inject result into `build_response`. |
+| `/opt/sortof/frontend/sortof-app.jsx` | Modify | Add `COLUMN_COUNT`, `branchSelections` state + hydration + storage listener, `BranchPicker` component, refactor `ModTable` to group multi-branch wsids, `resort()` with sequence number, 5xx handling. |
+| `/opt/sortof/frontend/index.html` | Modify | CSS for `.branch-affordance`, `.branch-panel`, `.branch-row`. |
+
+No new files. The two `mlos_sort.py` copies are unchanged - dangling-deps detection already exists in `mlos_sort.sort_mods`.
+
+**Verification fixtures (already cached, no /api/sort cold-start required):**
+- 3-mod canonical (single-mod wsids, regression baseline): `2169435993;2392709985;2487022075` → `MODS_LINE="modoptions;tsarslib;TMC_TrueActions"`.
+- AuthenticZ multi-branch (3 mod_ids on one wsid, all `incompatible_mods=[]`): wsid `2335368829` → mod_ids `Authentic Z - Current`, `AuthenticZBackpacks+`, `AuthenticZLite`.
+
+---
+
+## Task 1: Backend - `POST /api/resort` endpoint
+
+**Files:**
+- Modify: `/opt/sortof/api/app.py` (add Pydantic model + route)
+
+- [ ] **Step 1: Backup app.py**
+
+```bash
+cp /opt/sortof/api/app.py /opt/sortof/api/app.py.bak-$(date +%Y%m%d-%H%M)
+```
+
+- [ ] **Step 2: Add `ResortRequest` Pydantic model**
+
+Find the existing `class SortRequest(BaseModel):` block (around line 76). Replace it with both models:
+
+```python
+class SortRequest(BaseModel):
+    input: str = Field(default="")
+    rules: Optional[str] = Field(default=None)
+
+
+class ResortRequest(BaseModel):
+    selected_mod_ids: List[str] = Field(default_factory=list)
+```
+
+- [ ] **Step 3: Add `/api/resort` route**
+
+Find the line right after the existing `sort_endpoint` function returns (the line `return payload` near the bottom of the function - currently line ~236). The static-files mount block follows. Insert the new route **between** them:
+
+```python
+@app.post("/api/resort")
+async def resort_endpoint(req: ResortRequest, request: Request) -> Dict[str, Any]:
+    """Re-run mlos_sort against a user-supplied subset of mod_ids.
+
+    Stateless. No Steam round-trip. Filters mod_parsed by the requested
+    mod_ids, runs sort_mods, returns the same shape as /api/sort.
+    """
+    t0 = time.monotonic()
+    ids = list(req.selected_mod_ids or [])
+
+    if not ids:
+        raise HTTPException(status_code=400, detail="selected_mod_ids must be non-empty")
+    if len(ids) > MAX_IDS:
+        raise HTTPException(status_code=413, detail=f"too many mod_ids ({len(ids)} > {MAX_IDS})")
+    for mod_id in ids:
+        if not isinstance(mod_id, str) or not (1 <= len(mod_id) <= 256):
+            raise HTTPException(status_code=400, detail="invalid mod_id")
+
+    pool = request.app.state.db
+    async with pool.acquire() as conn:
+        rows = await conn.fetch(
+            """
+            SELECT mp.workshop_id, mp.mod_id, mp.name, mp.category,
+                   mp.requirements, mp.load_after, mp.load_before,
+                   mp.incompatible_mods, mp.load_first, mp.load_last,
+                   mp.tags, mp.maps
+            FROM mod_parsed mp
+            JOIN workshop_meta wm ON wm.workshop_id = mp.workshop_id
+            WHERE mp.mod_id = ANY($1::text[])
+              AND mp.parsed_at_time_updated = wm.time_updated
+            ORDER BY mp.workshop_id, mp.mod_id
+            """,
+            ids,
+        )
+
+    found_ids = {r["mod_id"] for r in rows}
+    missing = [mid for mid in ids if mid not in found_ids]
+    if missing:
+        log.info("resort dropped unknown mod_ids count=%d sample=%s",
+                 len(missing), missing[:3])
+    if not rows:
+        raise HTTPException(status_code=400, detail="no known mod_ids in selection")
+
+    mods: List[ModInfo] = [
+        ModInfo(
+            id=r["mod_id"],
+            name=r["name"] or r["mod_id"],
+            workshop_id=r["workshop_id"],
+            category=r["category"] or "undefined",
+            requirements=list(r["requirements"] or []),
+            loadAfter=list(r["load_after"] or []),
+            loadBefore=list(r["load_before"] or []),
+            incompatibleMods=list(r["incompatible_mods"] or []),
+            loadFirst=r["load_first"] or "off",
+            loadLast=r["load_last"] or "off",
+            tags=list(r["tags"] or []),
+            maps=list(r["maps"] or []),
+        )
+        for r in rows
+    ]
+    sort_result = sort_mods(mods, {})
+    payload = adapters.build_response(
+        input_ids=[],
+        hit_ids=ids,
+        mods=mods,
+        sort_result=sort_result,
+        status="success",
+    )
+    payload["pending"] = []
+
+    elapsed_ms = int((time.monotonic() - t0) * 1000)
+    log.info("resort done count=%d ms=%d", len(rows), elapsed_ms)
+    return payload
+```
+
+- [ ] **Step 4: py_compile + smoke import**
+
+```bash
+/opt/sortof/api/.venv/bin/python -m py_compile /opt/sortof/api/app.py && echo PY_OK
+cd /opt/sortof/api && .venv/bin/python -c "import app" && echo IMPORT_OK
+```
+
+Expected: both lines print `PY_OK` and `IMPORT_OK` respectively. If either fails, fix the syntax/import before restarting.
+
+- [ ] **Step 5: Restart API**
+
+```bash
+sudo systemctl restart sortof-api && sleep 2 && sudo systemctl is-active sortof-api
+```
+
+Expected: `active`.
+
+- [ ] **Step 6: Verify happy path**
+
+```bash
+curl -sS -X POST http://100.114.205.53:8801/api/resort \
+  -H 'Content-Type: application/json' \
+  -d '{"selected_mod_ids":["modoptions","tsarslib","TMC_TrueActions"]}' \
+  | jq '{status, MODS_LINE, mod_db_count: (.MOD_DB|length), pending}'
+```
+
+Expected:
+```json
+{"status":"success","MODS_LINE":"modoptions;tsarslib;TMC_TrueActions","mod_db_count":3,"pending":[]}
+```
+
+- [ ] **Step 7: Verify validation 400s**
+
+```bash
+# Empty selection → 400
+curl -sS -o /dev/null -w 'empty=%{http_code}\n' -X POST http://100.114.205.53:8801/api/resort \
+  -H 'Content-Type: application/json' -d '{"selected_mod_ids":[]}'
+
+# All-unknown selection → 400
+curl -sS -o /dev/null -w 'unknown=%{http_code}\n' -X POST http://100.114.205.53:8801/api/resort \
+  -H 'Content-Type: application/json' -d '{"selected_mod_ids":["ghostA","ghostB"]}'
+
+# Mixed (one valid + one unknown) → 200, ghost dropped
+curl -sS -X POST http://100.114.205.53:8801/api/resort \
+  -H 'Content-Type: application/json' -d '{"selected_mod_ids":["modoptions","ghostMod"]}' \
+  | jq '{status, mod_db_count: (.MOD_DB|length)}'
+```
+
+Expected:
+```
+empty=400
+unknown=400
+{"status":"success","mod_db_count":1}
+```
+
+- [ ] **Step 8: Checkpoint** - task complete; backup file remains as rollback.
+
+---
+
+## Task 2: Backend - `ambiguous-multi-branch` warning
+
+**Files:**
+- Modify: `/opt/sortof/api/adapters.py`
+
+- [ ] **Step 1: Backup adapters.py**
+
+```bash
+cp /opt/sortof/api/adapters.py /opt/sortof/api/adapters.py.bak-$(date +%Y%m%d-%H%M)
+```
+
+- [ ] **Step 2: Add helper for ambiguous-multi-branch detection**
+
+Open `/opt/sortof/api/adapters.py`. Just below the existing `build_warnings()` function (around line 56), insert:
+
+```python
+def _compute_ambiguous_warnings(mods: List[ModInfo]) -> List[Dict[str, str]]:
+    """Emit one amber WARNINGS entry per wsid that has >=2 selected mod_ids,
+    none of them flagging others in `incompatibleMods`. The user is at risk
+    of shipping conflicting alternates (e.g. AuthenticZ Lite + Current);
+    show this even when they don't expand the picker.
+
+    Spec: 2026-04-30-multi-branch-picker.md §4 "default-selection safety net"
+    (review #1 fix).
+    """
+    by_wsid: Dict[str, List[ModInfo]] = {}
+    for m in mods:
+        wsid = m.workshop_id or ""
+        if not wsid:
+            continue
+        by_wsid.setdefault(wsid, []).append(m)
+
+    out: List[Dict[str, str]] = []
+    for wsid, group in by_wsid.items():
+        if len(group) < 2:
+            continue
+        ids_in_group = {m.id for m in group}
+        any_flags_sibling = any(
+            any(other in ids_in_group for other in m.incompatibleMods)
+            for m in group
+        )
+        if any_flags_sibling:
+            continue  # author marked alternates; picker will run in radio mode
+        title = group[0].name or wsid
+        out.append({
+            "tag": "ambiguous-multi-branch",
+            "level": "amber",
+            "msg": (
+                f"{len(group)} branches selected from {title} ({wsid}) - "
+                f"author didn't declare alternates; verify these aren't "
+                f"mutually exclusive (e.g., AuthenticZ Lite vs Current). "
+                f"Expand the row to pick one."
+            ),
+        })
+    return out
+```
+
+- [ ] **Step 3: Wire helper into `build_response`**
+
+Find the existing `return { ... }` at the bottom of `build_response()` (around line 103-112). Replace the `"WARNINGS": build_warnings(...)` line with:
+
+```python
+        "WARNINGS": (
+            build_warnings(sort_result.get("warnings", {}) or {})
+            + _compute_ambiguous_warnings(mods)
+        ),
+```
+
+- [ ] **Step 4: py_compile + smoke import**
+
+```bash
+/opt/sortof/api/.venv/bin/python -m py_compile /opt/sortof/api/adapters.py && echo PY_OK
+cd /opt/sortof/api && .venv/bin/python -c "import app" && echo IMPORT_OK
+```
+
+- [ ] **Step 5: Restart API**
+
+```bash
+sudo systemctl restart sortof-api && sleep 2 && sudo systemctl is-active sortof-api
+```
+
+- [ ] **Step 6: Verify warning fires for AuthenticZ**
+
+```bash
+curl -sS -X POST http://100.114.205.53:8801/api/sort \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"2335368829"}' \
+  | jq '.WARNINGS[] | select(.tag == "ambiguous-multi-branch")'
+```
+
+Expected: one object with `tag:"ambiguous-multi-branch"`, `level:"amber"`, and a `msg` mentioning "3 branches" and `2335368829`.
+
+- [ ] **Step 7: Verify warning DOES NOT fire for the canonical 3-mod input**
+
+```bash
+curl -sS -X POST http://100.114.205.53:8801/api/sort \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"2169435993;2392709985;2487022075"}' \
+  | jq '[.WARNINGS[] | select(.tag == "ambiguous-multi-branch")] | length'
+```
+
+Expected: `0` (each wsid has only 1 mod row → no ambiguity).
+
+- [ ] **Step 8: Verify warning DOES NOT fire when subset is selected via /api/resort**
+
+```bash
+curl -sS -X POST http://100.114.205.53:8801/api/resort \
+  -H 'Content-Type: application/json' \
+  -d '{"selected_mod_ids":["Authentic Z - Current"]}' \
+  | jq '[.WARNINGS[] | select(.tag == "ambiguous-multi-branch")] | length'
+```
+
+Expected: `0` (one mod from the wsid, not a multi-branch ambiguity).
+
+---
+
+## Task 3: Frontend - `COLUMN_COUNT` + `branchSelections` state + hydration + storage listener
+
+**Files:**
+- Modify: `/opt/sortof/frontend/sortof-app.jsx`
+
+- [ ] **Step 1: Backup**
+
+```bash
+cp /opt/sortof/frontend/sortof-app.jsx /opt/sortof/frontend/sortof-app.jsx.bak-$(date +%Y%m%d-%H%M)
+```
+
+- [ ] **Step 2: Add `COLUMN_COUNT` constant**
+
+Find the helper functions near the top of the file (after `buildModsLine`, around line 35). Add:
+
+```jsx
+// Shared column count for the Mod Details table. Keep in sync with the
+// <thead> in ModTable; expansion-panel <tr colSpan> reads this constant.
+// Spec C will add a 7th column; bump here, do not hardcode the integer.
+const COLUMN_COUNT = 6;
+```
+
+- [ ] **Step 3: Add `branchSelections` App-level state with localStorage hydration**
+
+Find the App function's state declarations (around line 456). Below the existing `pzBuild` block, add:
+
+```jsx
+const [branchSelections, setBranchSelections] = useState(() => {
+  try {
+    const raw = localStorage.getItem('sortof.branch.selections');
+    if (!raw) return {};
+    const parsed = JSON.parse(raw);
+    return (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) ? parsed : {};
+  } catch { return {}; }
+});
+const [resortSeq, setResortSeq] = useState(0);  // monotonic; for stale-response drop
+```
+
+- [ ] **Step 4: Add useEffect for persist + cross-tab `storage` listener**
+
+Below the `pzBuild` localStorage useEffect (around line 467), add:
+
+```jsx
+useEffect(() => {
+  try {
+    localStorage.setItem('sortof.branch.selections', JSON.stringify(branchSelections));
+  } catch {}
+}, [branchSelections]);
+
+useEffect(() => {
+  function onStorage(e) {
+    if (e.key !== 'sortof.branch.selections' || e.newValue === null) return;
+    try {
+      const parsed = JSON.parse(e.newValue);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        setBranchSelections(parsed);
+      }
+    } catch {}
+  }
+  window.addEventListener('storage', onStorage);
+  return () => window.removeEventListener('storage', onStorage);
+}, []);
+```
+
+- [ ] **Step 5: Verify served file picks up the new constants**
+
+```bash
+curl -sS http://100.114.205.53:8801/sortof-app.jsx | grep -cE 'COLUMN_COUNT|branchSelections|sortof.branch.selections'
+```
+
+Expected: `>= 6` (constant declaration + state name uses + localStorage key uses).
+
+- [ ] **Step 6: Manual browser smoke test**
+
+In a browser tab on `http://100.114.205.53:8801/`:
+
+1. Open DevTools console.
+2. Run `localStorage.setItem('sortof.branch.selections', JSON.stringify({"2335368829": ["Authentic Z - Current"]}))`.
+3. Hard-refresh the page.
+4. In console: `localStorage.getItem('sortof.branch.selections')` - should return the same JSON.
+5. App should render without errors (no behavior change yet - picker UI is Task 4-5).
+
+If the console shows JSON parse errors or "branchSelections is not defined", revert to backup and re-do.
+
+---
+
+## Task 4: Frontend - `ModTable` refactor to group multi-branch wsids
+
+**Files:**
+- Modify: `/opt/sortof/frontend/sortof-app.jsx` (replace `ModTable` body around line 306; pass `branchSelections` from App)
+
+- [ ] **Step 1: Backup** (if more than ~10 minutes since last)
+
+```bash
+cp /opt/sortof/frontend/sortof-app.jsx /opt/sortof/frontend/sortof-app.jsx.bak-$(date +%Y%m%d-%H%M)
+```
+
+- [ ] **Step 2: Replace `ModTable` with the wsid-grouping version**
+
+Find the existing `function ModTable({ defaultOpen = false }) {` block (around line 306) and the closing `}` of that function (around line 351). Replace the entire function with:
+
+```jsx
+function ModTable({ defaultOpen = false, branchSelections, onToggleBranch, expandedWsids, onToggleExpansion }) {
+  const [open, setOpen] = useState(defaultOpen);
+
+  // Group MOD_DB rows by wsid. For wsids with >1 mod, render a single parent
+  // row and an expansion <tr colSpan={COLUMN_COUNT}> with the picker.
+  const groupedByWsid = useMemo(() => {
+    const g = {};
+    for (const m of (D.MOD_DB || [])) {
+      const w = m.wsid || '';
+      if (!w) continue;
+      (g[w] = g[w] || []).push(m);
+    }
+    return g;
+  }, [D.MOD_DB]);
+
+  // Walk SORTED_ORDER and emit one row-spec per wsid (deduped).
+  const rowSpecs = useMemo(() => {
+    const specs = [];
+    const seenWsid = new Set();
+    for (const modId of (D.SORTED_ORDER || [])) {
+      const m = (D.MOD_DB || []).find(x => x.modId === modId);
+      if (!m || !m.wsid) continue;
+      if (seenWsid.has(m.wsid)) continue;
+      seenWsid.add(m.wsid);
+      const branches = groupedByWsid[m.wsid] || [m];
+      const isMulti = branches.length >= 2;
+      specs.push({ wsid: m.wsid, primary: m, branches, isMulti });
+    }
+    // Wsids whose parent had zero selected mods: not in SORTED_ORDER. Append.
+    for (const w of Object.keys(groupedByWsid)) {
+      if (!seenWsid.has(w)) {
+        const branches = groupedByWsid[w];
+        specs.push({ wsid: w, primary: branches[0], branches, isMulti: branches.length >= 2 });
+      }
+    }
+    return specs;
+  }, [D.SORTED_ORDER, D.MOD_DB, groupedByWsid]);
+
+  return (
+    <div className="panel table-section">
+      <div className="tbl-head" onClick={() => setOpen(!open)}>
+        <span>mod details</span>
+        <span className="count">· {(D.SORTED_ORDER || []).length} mods</span>
+        <span style={{ color: 'var(--fg-3)', fontSize: 10.5, marginLeft: 8 }}>
+          why everything ended up where it did
+        </span>
+        <span className="chev">{open ? '▾' : '▸'}</span>
+      </div>
+      {open && (
+        <table className="mods-table">
+          <thead>
+            <tr>
+              <th>#</th>
+              <th>mod id</th>
+              <th>workshop id</th>
+              <th>category</th>
+              <th>dependencies</th>
+              <th>load</th>
+            </tr>
+          </thead>
+          <tbody>
+            {rowSpecs.map((spec, i) => {
+              const idx = String(i + 1).padStart(2, '0');
+              if (!spec.isMulti) {
+                const m = spec.primary;
+                return (
+                  <tr key={spec.wsid}>
+                    <td className="idx">{idx}</td>
+                    <td><span className="modid">{m.modId}</span></td>
+                    <td><span className="wsid">{spec.wsid}</span></td>
+                    <td><span className={'cat ' + m.cat}>{m.cat}</span></td>
+                    <td><span className="deps">{m.deps && m.deps.length ? m.deps.join(', ') : '-'}</span></td>
+                    <td>
+                      {m.pos === 'first' && <span className="pos first">first</span>}
+                      {m.pos === 'last'  && <span className="pos last">last</span>}
+                      {!m.pos && <span className="pos">-</span>}
+                    </td>
+                  </tr>
+                );
+              }
+              // Multi-branch wsid: parent row + (optional) expansion panel.
+              const selected = branchSelections[spec.wsid] || [];
+              const N = spec.branches.length;
+              const X = selected.length;
+              const userTouched = (spec.wsid in branchSelections);
+              const affordance = userTouched ? `✓ ${X} of ${N}` : `▾ ${N} branches`;
+              const firstSelected = spec.branches.find(b => selected.includes(b.modId)) || spec.branches[0];
+              const showAsZero = userTouched && X === 0;
+              const display = showAsZero ? null : firstSelected;
+              const expanded = expandedWsids.has(spec.wsid);
+              return (
+                <React.Fragment key={spec.wsid}>
+                  <tr>
+                    <td className="idx">{idx}</td>
+                    <td>
+                      <button className="branch-affordance"
+                              onClick={() => onToggleExpansion(spec.wsid)}>
+                        {affordance}
+                      </button>
+                    </td>
+                    <td><span className="wsid">{spec.wsid}</span></td>
+                    <td>{display ? <span className={'cat ' + display.cat}>{display.cat}</span> : '-'}</td>
+                    <td>{display && display.deps && display.deps.length ? display.deps.join(', ') : '-'}</td>
+                    <td>
+                      {display && display.pos === 'first' && <span className="pos first">first</span>}
+                      {display && display.pos === 'last'  && <span className="pos last">last</span>}
+                      {(!display || !display.pos) && <span className="pos">-</span>}
+                    </td>
+                  </tr>
+                  {expanded && (
+                    <BranchPicker
+                      wsid={spec.wsid}
+                      branches={spec.branches}
+                      selected={selected}
+                      userTouched={userTouched}
+                      onToggle={onToggleBranch}
+                    />
+                  )}
+                </React.Fragment>
+              );
+            })}
+          </tbody>
+        </table>
+      )}
+    </div>
+  );
+}
+```
+
+- [ ] **Step 3: Update App to maintain `expandedWsids` state and pass everything down**
+
+Find App's other useState calls. Add:
+
+```jsx
+const [expandedWsids, setExpandedWsids] = useState(() => new Set());
+
+const onToggleExpansion = (wsid) => {
+  setExpandedWsids(prev => {
+    const next = new Set(prev);
+    if (next.has(wsid)) next.delete(wsid); else next.add(wsid);
+    return next;
+  });
+};
+```
+
+(`onToggleBranch` is added in Task 5 - leave it for now; the existing `<ModTable defaultOpen={modTableDefault} />` invocation in `RightColumn` needs updating in Step 4 below.)
+
+- [ ] **Step 4: Pass props through `RightColumn` to `ModTable`**
+
+Find the `RightColumn` function signature (around line 372). Add `branchSelections, onToggleBranch, expandedWsids, onToggleExpansion` to the destructured props:
+
+```jsx
+function RightColumn({ state, counts, progress, emptyVariant, successVariant, modTableDefault, pzBuild, setPzBuild, branchSelections, onToggleBranch, expandedWsids, onToggleExpansion }) {
+```
+
+Then find the `<ModTable defaultOpen={modTableDefault} />` invocation inside `RightColumn` (around line 437). Replace with:
+
+```jsx
+<ModTable
+  defaultOpen={modTableDefault}
+  branchSelections={branchSelections}
+  onToggleBranch={onToggleBranch}
+  expandedWsids={expandedWsids}
+  onToggleExpansion={onToggleExpansion}
+/>
+```
+
+- [ ] **Step 5: Pass props from App to `RightColumn`**
+
+Find the `<RightColumn …/>` invocation in App (around line 613). Append:
+
+```jsx
+branchSelections={branchSelections}
+onToggleBranch={() => {}}
+expandedWsids={expandedWsids}
+onToggleExpansion={onToggleExpansion}
+```
+
+(`onToggleBranch` is a placeholder no-op for now; replaced in Task 5.)
+
+- [ ] **Step 6: Verify served file**
+
+```bash
+curl -sS http://100.114.205.53:8801/sortof-app.jsx | grep -cE 'BranchPicker|expandedWsids|branch-affordance|onToggleExpansion'
+```
+
+Expected: `>= 6`.
+
+- [ ] **Step 7: Manual browser smoke test**
+
+Hard-refresh the page. Submit a sort with `2335368829` (AuthenticZ alone) and any cached single-mod input. Open the Mod Details table. Expectation:
+- AuthenticZ appears as **one row** with `▾ 3 branches` (or `✓ X of N` if hydrated from earlier Task 3 testing).
+- Single-mod wsids appear as normal rows.
+- Clicking the `▾` affordance toggles `expandedWsids` (panel visibility - content is empty until Task 5 adds `BranchPicker`).
+- Console: no errors. (`BranchPicker is not defined` is expected at this point if you click - Task 5 fixes.)
+
+---
+
+## Task 5: Frontend - `BranchPicker` expansion panel + default selection + radio/checkbox modes
+
+**Files:**
+- Modify: `/opt/sortof/frontend/sortof-app.jsx`
+
+- [ ] **Step 1: Backup**
+
+```bash
+cp /opt/sortof/frontend/sortof-app.jsx /opt/sortof/frontend/sortof-app.jsx.bak-$(date +%Y%m%d-%H%M)
+```
+
+- [ ] **Step 2: Add `defaultSelectionForBranches()` helper near top of file**
+
+Right after `buildModsLine` (around line 35), insert:
+
+```jsx
+// Default selection for a multi-branch wsid (spec §4):
+//   - if any branch lists another in `incompatible_mods`, default = [first only]
+//   - else default = [all branches]
+// "First" tiebreaker: branches arrive sorted by parsed_at ASC, mod_id ASC from
+// the API; we trust that order and pick branches[0].
+function defaultSelectionForBranches(branches) {
+  if (!branches || !branches.length) return [];
+  const ids = new Set(branches.map(b => b.modId));
+  const isRadio = branches.some(b => (b.conflicts || []).some(c => ids.has(c)));
+  if (isRadio) return [branches[0].modId];
+  return branches.map(b => b.modId);
+}
+
+function isRadioMode(branches) {
+  if (!branches || branches.length < 2) return false;
+  const ids = new Set(branches.map(b => b.modId));
+  return branches.some(b => (b.conflicts || []).some(c => ids.has(c)));
+}
+```
+
+- [ ] **Step 3: Add `BranchPicker` component**
+
+Just above `function ModTable(` (around line 306, **before** the table), insert:
+
+```jsx
+function BranchPicker({ wsid, branches, selected, userTouched, onToggle }) {
+  const radio = isRadioMode(branches);
+  const inputType = radio ? 'radio' : 'checkbox';
+  // If user hasn't touched yet, render the default selection (so checkboxes
+  // reflect the implicit state). The actual default is also assumed by the
+  // rest of the system whenever branchSelections[wsid] is missing.
+  const effective = userTouched ? selected : defaultSelectionForBranches(branches);
+  return (
+    <tr>
+      <td colSpan={COLUMN_COUNT} className="branch-panel">
+        <div className="branch-panel-inner">
+          <div className="branch-panel-meta">
+            workshop {wsid} · {branches.length} mod_ids · {radio ? 'pick one' : 'multi-select'}
+          </div>
+          {branches.map(b => {
+            const checked = effective.includes(b.modId);
+            return (
+              <label key={b.modId} className={'branch-row' + (checked ? ' is-checked' : '')}>
+                <input
+                  type={inputType}
+                  name={radio ? `branch-${wsid}` : undefined}
+                  className="branch-input"
+                  checked={checked}
+                  onChange={() => onToggle(wsid, b.modId, branches)}
+                />
+                <span className="branch-modid">{b.modId}</span>
+                <span className="branch-name">{b.name}</span>
+                <span className={'cat ' + b.cat}>{b.cat}</span>
+                <span className="branch-deps">
+                  {b.deps && b.deps.length ? b.deps.join(', ') : '-'}
+                </span>
+                <span className="branch-pos">
+                  {b.pos === 'first' ? 'first' : (b.pos === 'last' ? 'last' : '-')}
+                </span>
+              </label>
+            );
+          })}
+        </div>
+      </td>
+    </tr>
+  );
+}
+```
+
+- [ ] **Step 4: Implement `onToggleBranch` in App**
+
+Find the App function (around line 454). Below the `expandedWsids` state, add:
+
+```jsx
+const onToggleBranch = (wsid, modId, branches) => {
+  setBranchSelections(prev => {
+    const radio = isRadioMode(branches);
+    const cur = prev[wsid] !== undefined
+      ? prev[wsid]
+      : defaultSelectionForBranches(branches);
+    let next;
+    if (radio) {
+      next = [modId];  // exactly one
+    } else {
+      next = cur.includes(modId)
+        ? cur.filter(x => x !== modId)
+        : [...cur, modId];
+    }
+    return { ...prev, [wsid]: next };
+  });
+  // Resort fetch is wired in Task 6; for now this just updates state.
+};
+```
+
+- [ ] **Step 5: Replace the no-op `onToggleBranch` placeholder in `<RightColumn>`**
+
+Find the `<RightColumn …/>` invocation in App (Task 4 added `onToggleBranch={() => {}}`). Replace with:
+
+```jsx
+onToggleBranch={onToggleBranch}
+```
+
+- [ ] **Step 6: Verify served file**
+
+```bash
+curl -sS http://100.114.205.53:8801/sortof-app.jsx | grep -cE 'BranchPicker|defaultSelectionForBranches|isRadioMode|branch-row'
+```
+
+Expected: `>= 8`.
+
+- [ ] **Step 7: Manual browser smoke**
+
+Hard-refresh. Submit AuthenticZ (`2335368829`). Click the `▾ 3 branches` affordance.
+
+Expected:
+- Panel expands with 3 rows.
+- All 3 boxes are checked (default-all per §4 since `incompatible_mods=[]` on all).
+- Click one box to uncheck. Affordance changes to `✓ 2 of 3`. Storage event listener writes to localStorage (`localStorage.getItem('sortof.branch.selections')`).
+- The Mods= line in the output panel currently still includes all 3 mod_ids (resort hookup is Task 6).
+
+Console: no errors.
+
+---
+
+## Task 6: Frontend - `/api/resort` integration with sequence number + 5xx handling
+
+**Files:**
+- Modify: `/opt/sortof/frontend/sortof-app.jsx`
+
+- [ ] **Step 1: Backup**
+
+```bash
+cp /opt/sortof/frontend/sortof-app.jsx /opt/sortof/frontend/sortof-app.jsx.bak-$(date +%Y%m%d-%H%M)
+```
+
+- [ ] **Step 2: Add `runResort()` async function in App**
+
+Find the App function. Below `onToggleBranch` (added in Task 5), add:
+
+```jsx
+async function runResort(nextSelections) {
+  // Compose the flat list of selected mod_ids from MOD_DB + nextSelections.
+  // For wsids not in nextSelections, use the §4 default (all-ticked or
+  // first-only depending on radio mode). For wsids with N=1, include the
+  // sole mod_id unconditionally.
+  const byWsid = {};
+  for (const m of (_liveSortData?.MOD_DB || window.SORTOF_DATA?.MOD_DB || [])) {
+    const w = m.wsid || '';
+    if (!w) continue;
+    (byWsid[w] = byWsid[w] || []).push(m);
+  }
+  const ids = [];
+  for (const w of Object.keys(byWsid)) {
+    const branches = byWsid[w];
+    if (branches.length === 1) {
+      ids.push(branches[0].modId);
+      continue;
+    }
+    const stored = nextSelections[w];
+    const eff = stored !== undefined ? stored : defaultSelectionForBranches(branches);
+    for (const id of eff) ids.push(id);
+  }
+
+  if (!ids.length) {
+    // Nothing selected; no point hitting the API. Synthesize an empty payload
+    // so the UI shows "0 of N" without dispatching a 400.
+    _liveSortData = { ..._liveSortData, MOD_DB: [], SORTED_ORDER: [],
+                       MODS_LINE: '', WORKSHOP_ITEMS_LINE: '', MAP_LINE: 'Muldraugh, KY',
+                       WARNINGS: [{ tag: 'cycle', level: 'amber', msg: 'no mods selected - pick at least one branch' }],
+                       pending: [], status: 'success' };
+    setCounts(c => ({ ...c, cached: 0, warnings: 1 }));
+    return;
+  }
+
+  const seq = resortSeq + 1;
+  setResortSeq(seq);
+  try {
+    const res = await fetch('/api/resort', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Sortof-Seq': String(seq) },
+      body: JSON.stringify({ selected_mod_ids: ids }),
+    });
+    // Drop stale: another resort has issued since this one started.
+    if (seq < resortSeq) return;
+    if (!res.ok) {
+      console.error('resort failed', res.status);
+      _liveSortData = {
+        ..._liveSortData,
+        WARNINGS: [
+          ...(_liveSortData?.WARNINGS || []),
+          { tag: 'cycle', level: 'red', msg: "couldn't recompute sort - try again" },
+        ],
+      };
+      setCounts(c => ({ ...c, warnings: (c.warnings || 0) + 1 }));
+      return;
+    }
+    const json = await res.json();
+    _liveSortData = json;
+    const cached = (json.MOD_DB || []).length;
+    const warns  = (json.WARNINGS || []).length;
+    setCounts({ cached, queued: 0, parsing: 0, warnings: warns });
+    setState(json.status || 'success');
+  } catch (e) {
+    console.error('resort threw', e);
+    _liveSortData = {
+      ..._liveSortData,
+      WARNINGS: [
+        ...(_liveSortData?.WARNINGS || []),
+        { tag: 'cycle', level: 'red', msg: "couldn't recompute sort - try again" },
+      ],
+    };
+    setCounts(c => ({ ...c, warnings: (c.warnings || 0) + 1 }));
+  }
+}
+```
+
+(Note: `_liveSortData` is the module-level let-binding from Task 0 of the original frontend - already present at the top of `sortof-app.jsx`.)
+
+- [ ] **Step 3: Update `onToggleBranch` to trigger resort**
+
+Find the existing `onToggleBranch` (Task 5). Replace its body with:
+
+```jsx
+const onToggleBranch = (wsid, modId, branches) => {
+  setBranchSelections(prev => {
+    const radio = isRadioMode(branches);
+    const cur = prev[wsid] !== undefined
+      ? prev[wsid]
+      : defaultSelectionForBranches(branches);
+    let next;
+    if (radio) {
+      next = [modId];
+    } else {
+      next = cur.includes(modId)
+        ? cur.filter(x => x !== modId)
+        : [...cur, modId];
+    }
+    const updated = { ...prev, [wsid]: next };
+    // Fire-and-forget: state set + resort dispatch.
+    runResort(updated);
+    return updated;
+  });
+};
+```
+
+- [ ] **Step 4: Cross-tab `storage` listener also triggers resort**
+
+Find the storage useEffect from Task 3. Replace with:
+
+```jsx
+useEffect(() => {
+  function onStorage(e) {
+    if (e.key !== 'sortof.branch.selections' || e.newValue === null) return;
+    try {
+      const parsed = JSON.parse(e.newValue);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        setBranchSelections(parsed);
+        runResort(parsed);
+      }
+    } catch {}
+  }
+  window.addEventListener('storage', onStorage);
+  return () => window.removeEventListener('storage', onStorage);
+}, [resortSeq]);
+```
+
+- [ ] **Step 5: Trigger an initial resort if hydrated `branchSelections` differs from defaults**
+
+Add another useEffect just below the previous, fired once on mount when `_liveSortData` first becomes truthy (i.e. after the first /api/sort response):
+
+```jsx
+useEffect(() => {
+  // Hydrate-driven resort: after the user submits and gets MOD_DB,
+  // if branchSelections has entries, re-run sort against them.
+  if (state === 'success' || state === 'partial') {
+    if (Object.keys(branchSelections).length > 0) {
+      runResort(branchSelections);
+    }
+  }
+  // eslint-disable-next-line
+}, [state]);
+```
+
+- [ ] **Step 6: Verify served file**
+
+```bash
+curl -sS http://100.114.205.53:8801/sortof-app.jsx | grep -cE "runResort|/api/resort|X-Sortof-Seq|couldn't recompute sort"
+```
+
+Expected: `>= 5`.
+
+- [ ] **Step 7: Manual browser smoke - happy path**
+
+Hard-refresh. Submit AuthenticZ. Expand. Untick `AuthenticZLite`.
+
+Expected:
+- Network tab shows POST `/api/resort` with body `{"selected_mod_ids":["Authentic Z - Current","AuthenticZBackpacks+"]}`.
+- Response 200, `MODS_LINE` contains 2 mod_ids only.
+- Output panel updates.
+- Affordance reads `✓ 2 of 3`.
+- WARNINGS no longer contains `ambiguous-multi-branch` for that wsid (because user touched it).
+
+- [ ] **Step 8: Manual browser smoke - race**
+
+Click toggle 2-3 times rapidly (untick, retick, untick). Inspect Network tab - multiple resort requests fire. Whichever response is the latest wins; older responses are dropped without state mutation. Final UI state matches the last toggle.
+
+- [ ] **Step 9: Manual browser smoke - 5xx (optional)**
+
+Edit `/opt/sortof/api/app.py` to add `raise HTTPException(500)` at the top of `resort_endpoint`. `py_compile`, restart api. Toggle a branch in the browser. Expect:
+- Output state retains prior MOD_DB/MODS_LINE.
+- A red WARNINGS entry appears: `couldn't recompute sort - try again`.
+- Restore `app.py` from backup, restart api, toggle again - works again.
+
+```bash
+# Restore after the 5xx test
+cp /opt/sortof/api/app.py.bak-* /opt/sortof/api/app.py
+sudo systemctl restart sortof-api
+```
+
+---
+
+## Task 7: Frontend - CSS for picker
+
+**Files:**
+- Modify: `/opt/sortof/frontend/index.html`
+
+- [ ] **Step 1: Backup**
+
+```bash
+cp /opt/sortof/frontend/index.html /opt/sortof/frontend/index.html.bak-$(date +%Y%m%d-%H%M)
+```
+
+- [ ] **Step 2: Add CSS rules**
+
+Find the existing `.copy-btn.copied` rule in `index.html` (around line 374). Below it, add:
+
+```css
+  /* multi-branch picker (Spec A) */
+  .branch-affordance {
+    appearance: none;
+    border: 1px solid var(--line);
+    background: transparent;
+    color: var(--acc-blue);
+    font-family: var(--mono);
+    font-size: 11px;
+    padding: 1px 6px;
+    border-radius: 3px;
+    cursor: pointer;
+  }
+  .branch-affordance:hover { color: var(--fg); border-color: var(--line-2); background: var(--bg-3); }
+
+  .branch-panel {
+    background: var(--bg-2);
+    border-top: 1px dashed var(--line);
+    border-bottom: 1px dashed var(--line);
+    padding: 0;
+  }
+  .branch-panel-inner {
+    padding: 8px 12px 10px;
+    font-family: var(--mono);
+    font-size: 11px;
+  }
+  .branch-panel-meta { color: var(--fg-3); margin-bottom: 6px; letter-spacing: 0.04em; }
+
+  .branch-row {
+    display: grid;
+    grid-template-columns: 18px 220px 1fr 70px 1fr 60px;
+    gap: 10px;
+    align-items: center;
+    padding: 4px 0;
+    border-top: 1px solid var(--line);
+    cursor: pointer;
+  }
+  .branch-row:hover { background: var(--bg-3); }
+  .branch-row.is-checked .branch-modid { color: var(--acc-green); }
+  .branch-input { accent-color: var(--acc-green); }
+  .branch-modid { color: var(--fg-2); }
+  .branch-name  { color: var(--fg-3); }
+  .branch-deps  { color: var(--fg-3); font-size: 10.5px; }
+  .branch-pos   { color: var(--fg-3); font-size: 10.5px; text-align: right; }
+```
+
+- [ ] **Step 3: Verify served file**
+
+```bash
+curl -sS http://100.114.205.53:8801/ | grep -c 'branch-affordance\|branch-panel\|branch-row'
+```
+
+Expected: `>= 6`.
+
+- [ ] **Step 4: Manual browser smoke**
+
+Hard-refresh. Open AuthenticZ in the picker. Expected:
+- Affordance is a small bordered button-like element with blue text.
+- Expansion panel has dashed top/bottom borders, slightly inset background.
+- Each branch row has a checkbox/radio, mod_id, name, category pill, deps, and position cell.
+- Hovering a branch row tints it slightly. Checked rows show the mod_id in green.
+
+---
+
+## Task 8: Verification - run §13 test cases against running stack
+
+For each case, document expected vs actual. If any fails, return to the relevant task and fix.
+
+- [ ] **Step 1: §13.1 AuthenticZ canonical**
+
+```bash
+curl -sS -X POST http://100.114.205.53:8801/api/sort \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"2335368829"}' \
+  | jq '{warns: [.WARNINGS[] | select(.tag=="ambiguous-multi-branch")] | length, mod_db_count: (.MOD_DB|length)}'
+```
+
+Expected: `{"warns":1,"mod_db_count":3}`. In the browser: parent row reads `▾ 3 branches`, expansion panel mode = checkboxes, all 3 ticked.
+
+- [ ] **Step 2: §13.2 Cooperative pack**
+
+(No 3-mod cooperative wsid is in the cache yet. Skip or use AuthenticZ as a stand-in: same UI behavior, the difference is only conceptual.)
+
+- [ ] **Step 3: §13.3 Mutually exclusive 2-branch**
+
+(No such wsid in cache. To test, manually inject in DB:
+
+```sql
+-- Run via sudo docker exec -i sortof_db psql -U sortof -d sortof -c "..."
+UPDATE mod_parsed SET incompatible_mods = '{AuthenticZBackpacks+}'::text[]
+WHERE workshop_id='2335368829' AND mod_id='Authentic Z - Current';
+UPDATE mod_parsed SET incompatible_mods = '{Authentic Z - Current}'::text[]
+WHERE workshop_id='2335368829' AND mod_id='AuthenticZBackpacks+';
+```
+
+Then re-submit `2335368829` in the browser. Expected: panel mode = radios, default = `Authentic Z - Current` only (first by `parsed_at, mod_id`). Restore via:
+
+```sql
+UPDATE mod_parsed SET incompatible_mods = '{}'::text[] WHERE workshop_id='2335368829';
+```)
+
+- [ ] **Step 4: §13.4 Persistence across reload**
+
+In browser: untick `AuthenticZLite`. Hard-refresh. After the next /api/sort, the resort fires automatically (Task 6 step 5 useEffect) and the picker shows `✓ 2 of 3` again. `localStorage.getItem('sortof.branch.selections')` shows the persisted entry.
+
+- [ ] **Step 5: §13.5 Stored mod_id no longer exists (checkbox mode)**
+
+Console: `localStorage.setItem('sortof.branch.selections', JSON.stringify({"2335368829": ["GhostBranchThatDoesNotExist"]}))`. Hard-refresh. Submit AuthenticZ. Expected: panel default applied (all 3 ticked); no console error.
+
+- [ ] **Step 6: §13.6 Cross-wsid incompatibility**
+
+(Use the canonical 3-mod input; `TMC_TrueActions` requires `tsarslib` but they're on different wsids - both N=1.) Expected: no picker UI, no `ambiguous-multi-branch` warning.
+
+- [ ] **Step 7: §13.7 Zero-tick wsid**
+
+Untick all 3 AuthenticZ branches in the browser. Expected: parent row reads `✓ 0 of N`, MODS_LINE excludes all 3, a synthetic warning appears (`no mods selected - pick at least one branch` if multiple wsids present, or the resort returns 400 → red retry warning if AuthenticZ was the only input). Re-tick at least one branch - UI recovers.
+
+- [ ] **Step 8: §13.8 Radio-mode eviction-to-empty**
+
+Apply the SQL from Step 3 (radio mode). Console: `localStorage.setItem('sortof.branch.selections', JSON.stringify({"2335368829": ["GhostMod"]}))`. Hard-refresh. Submit. Expected: silently drops the ghost; default-first applied (only `Authentic Z - Current` ticked). Restore SQL.
+
+- [ ] **Step 9: §13.10 Stale resort response discarded**
+
+Throttle Network in DevTools to "Slow 3G". Click toggle 1 (untick Backpacks), wait ~200ms, click toggle 2 (untick Lite). Inspect Network: two requests fire. The slower (toggle 1) finishes second. Expected: only toggle 2's response is applied; UI shows `✓ 1 of 3` (only Current selected), not `✓ 2 of 3`.
+
+- [ ] **Step 10: §13.12 Cross-tab sync**
+
+Open two tabs at `http://100.114.205.53:8801/`. Submit AuthenticZ in both. In tab A, untick a branch. Expected: tab B's affordance updates to match, network tab in B shows a /api/resort (triggered by the storage event listener).
+
+- [ ] **Step 11: §13.13 Unknown selected_mod_id from server**
+
+```bash
+curl -sS -X POST http://100.114.205.53:8801/api/resort \
+  -H 'Content-Type: application/json' \
+  -d '{"selected_mod_ids":["modoptions","ghostMod"]}' \
+  | jq '.MOD_DB | map(.modId)'
+```
+
+Expected: `["modoptions"]`. Server log: INFO "resort dropped unknown mod_ids count=1 sample=['ghostMod']".
+
+```bash
+sudo journalctl -u sortof-api --since "2 min ago" | grep "resort dropped"
+```
+
+- [ ] **Step 12: Final regression - canonical 3-mod**
+
+```bash
+curl -sS -X POST http://100.114.205.53:8801/api/sort \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"2169435993;2392709985;2487022075"}' \
+  | jq '{status, MODS_LINE, warns: (.WARNINGS|length)}'
+```
+
+Expected: `{"status":"success","MODS_LINE":"modoptions;tsarslib;TMC_TrueActions","warns":0}`. No regression from baseline.
+
+---
+
+## Self-review (already applied)
+
+- **Spec coverage:** all of §3–§10 acceptance criteria mapped to a task.
+- **Placeholders:** none in the plan body.
+- **Type consistency:** `branchSelections` is `{[wsid]: string[]}` everywhere; `expandedWsids` is `Set<string>`; `runResort` takes `nextSelections` of the same shape as `branchSelections`; `defaultSelectionForBranches` and `isRadioMode` both take `branches: MOD_DB[]` and read `.modId`/`.conflicts` consistently.
+- **No git, by design:** every code-changing task starts with a `cp file file.bak-$(date)` step in lieu of a commit.
+- **Restart-vs-no-restart:** backend tasks (1, 2) end with `sudo systemctl restart sortof-api`; frontend tasks (3–7) do not - `StaticFiles` serves from disk, hard-refresh in browser is sufficient.
diff --git a/docs/plans/2026-05-01-collection-expansion.md b/docs/plans/2026-05-01-collection-expansion.md
new file mode 100644
index 0000000..cda7e2a
--- /dev/null
+++ b/docs/plans/2026-05-01-collection-expansion.md
@@ -0,0 +1,1679 @@
+# Collection Expansion + Live Drain Progress Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Accept Steam Workshop collection URLs in `/api/sort`, expand them server-side via `GetCollectionDetails`, and drive a polling endpoint (`/api/jobs/{job_id}`) that gives the frontend live `cached / queued / draining` counters during cold loads.
+
+**Architecture:** A new `sort_jobs` table tracks asynchronous expansion + drain lifecycles. `/api/sort` becomes polymorphic: all-cached bare wsids return synchronously (unchanged); anything that needs work returns a `job_id`. The frontend polls `GET /api/jobs/{job_id}` every 2.5s and renders phase-specific status strip text. Phase is **derived live** from `download_jobs` counts on every poll - no event log, no leader, restart-resilient by construction.
+
+**Tech Stack:** Postgres (new table + indexes via additive migration), FastAPI (two new routes + background `asyncio.create_task` for expansion), asyncpg parameterized queries (mirroring existing patterns), httpx for `GetCollectionDetails`, vanilla React + Babel-standalone on the frontend (no build step - same as Spec A).
+
+> **Spec dependency:** Read `/opt/sortof/docs/specs/2026-05-01-collection-expansion.md` (270 lines, all decisions locked in §10) before starting. The acceptance criteria in §11 and the test recipes in §12 are what Task 11 verifies.
+
+---
+
+## File structure
+
+| Path | Action | Responsibility |
+|---|---|---|
+| `/opt/sortof/init/02_sort_jobs.sql` | **Create** | Schema for fresh deploys (idempotent `CREATE TABLE IF NOT EXISTS`). Identical DDL also applied to the live DB via one-shot `psql` in Task 1. |
+| `/opt/sortof/api/parse.py` | Modify | Add `parse_with_collections(text) -> (wsids, collection_ids)`. Reuses the existing wsid extractor; classifies URL-form IDs as candidate collections. |
+| `/opt/sortof/api/steam.py` | Modify | Add `async fetch_collection_details(client, ids)` mirroring the existing `fetch_workshop_details` pattern. |
+| `/opt/sortof/api/jobs.py` | **Create** | `sort_jobs` row CRUD, phase derivation (the §4 rule executed inside `GET`), live counts SQL, lifespan-startup stale-expansion sweep. |
+| `/opt/sortof/api/app.py` | Modify | Polymorphic `/api/sort`; new `GET /api/jobs/{job_id}`; new `DELETE /api/jobs/{job_id}`; lifespan sweep wired in. |
+| `/opt/sortof/frontend/sortof-app.jsx` | Modify | Detect `job_id` in `/api/sort` response; `pollJob()` async loop @ 2.5s; phase-specific status-strip text; cancel button; 404 expired-job toast. |
+| `/opt/sortof/frontend/index.html` | Modify | CSS for new phase indicators (e.g. `.status-pill.expanding`, `.cancel-btn`). |
+
+No changes to `/opt/sortof/worker/` - drain stays exactly as-is. Collections expand at API time; the resulting wsids flow into `download_jobs` via the existing queueing path.
+
+**Verification fixtures** (referenced throughout):
+- All-cached bare wsids: `2169435993;2392709985;2487022075` → MODS_LINE="modoptions;tsarslib;TMC_TrueActions" (canonical sync regression).
+- Synthetic collection (no Steam round-trip): direct `INSERT INTO collections` with known children. Used for cache-hit verification.
+- Real Steam collection: Task 11 step 2 instructs the implementer to find a public PZ collection URL on `https://steamcommunity.com/workshop/browse/?appid=108600&section=collections` and use its ID. Required for cold-expansion path.
+
+---
+
+## Task 1: Schema migration - `sort_jobs` table
+
+**Files:**
+- Create: `/opt/sortof/init/02_sort_jobs.sql`
+- One-shot apply to live DB via `docker exec sortof_db psql`
+
+- [ ] **Step 1: Write the schema file**
+
+Create `/opt/sortof/init/02_sort_jobs.sql` with:
+
+```sql
+-- Async sort jobs: lifecycle + result for collection expansion + cold drains.
+-- Created 2026-05-01 (Spec B+F).
+
+CREATE TABLE IF NOT EXISTS sort_jobs (
+    job_id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    phase            TEXT NOT NULL CHECK (phase IN ('expanding','queued','draining','done','failed')),
+    phase_started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
+    input_raw        TEXT NOT NULL,
+    collection_ids   TEXT[] NOT NULL DEFAULT '{}',
+    wsids            TEXT[],
+    rules_raw        TEXT,
+    result_json      JSONB,
+    failure_reason   TEXT
+);
+
+CREATE INDEX IF NOT EXISTS sort_jobs_phase_idx ON sort_jobs (phase);
+CREATE INDEX IF NOT EXISTS sort_jobs_updated_idx ON sort_jobs (updated_at);
+
+DROP TRIGGER IF EXISTS sort_jobs_touch ON sort_jobs;
+CREATE TRIGGER sort_jobs_touch
+    BEFORE UPDATE ON sort_jobs
+    FOR EACH ROW
+    EXECUTE FUNCTION touch_updated_at();
+```
+
+The `touch_updated_at()` function already exists (defined in `init/01_schema.sql` for `download_jobs`).
+
+Note: `init/` is owned by root. Use `sudo tee` to write the file:
+
+```bash
+sudo tee /opt/sortof/init/02_sort_jobs.sql > /dev/null <<'SQL'
+-- Async sort jobs: lifecycle + result for collection expansion + cold drains.
+-- Created 2026-05-01 (Spec B+F).
+
+CREATE TABLE IF NOT EXISTS sort_jobs (
+    job_id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    phase            TEXT NOT NULL CHECK (phase IN ('expanding','queued','draining','done','failed')),
+    phase_started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
+    input_raw        TEXT NOT NULL,
+    collection_ids   TEXT[] NOT NULL DEFAULT '{}',
+    wsids            TEXT[],
+    rules_raw        TEXT,
+    result_json      JSONB,
+    failure_reason   TEXT
+);
+
+CREATE INDEX IF NOT EXISTS sort_jobs_phase_idx ON sort_jobs (phase);
+CREATE INDEX IF NOT EXISTS sort_jobs_updated_idx ON sort_jobs (updated_at);
+
+DROP TRIGGER IF EXISTS sort_jobs_touch ON sort_jobs;
+CREATE TRIGGER sort_jobs_touch
+    BEFORE UPDATE ON sort_jobs
+    FOR EACH ROW
+    EXECUTE FUNCTION touch_updated_at();
+SQL
+```
+
+- [ ] **Step 2: Apply DDL to the live DB**
+
+```bash
+sudo docker exec -i sortof_db psql -U sortof -d sortof < /opt/sortof/init/02_sort_jobs.sql
+```
+
+Expected: a few `CREATE TABLE / CREATE INDEX / CREATE TRIGGER` notices (or none if already applied).
+
+- [ ] **Step 3: Verify the table exists with the right columns**
+
+```bash
+sudo docker exec -i sortof_db psql -U sortof -d sortof -c "\d sort_jobs"
+```
+
+Expected: 11 columns matching the schema, 3 indexes (PK + phase_idx + updated_idx), trigger present. The `\d` output should mention `gen_random_uuid()` as the default for `job_id` and the CHECK constraint on `phase`.
+
+- [ ] **Step 4: Smoke insert / select**
+
+```bash
+sudo docker exec -i sortof_db psql -U sortof -d sortof -c "
+INSERT INTO sort_jobs (phase, input_raw) VALUES ('expanding', 'smoke') RETURNING job_id, phase;
+DELETE FROM sort_jobs WHERE input_raw='smoke';"
+```
+
+Expected: one row returned with a UUID and phase='expanding', followed by `DELETE 1`.
+
+- [ ] **Step 5: Checkpoint** - schema is live; foundation for Tasks 4+ ready. No backup needed (DDL is idempotent and the table was empty).
+
+---
+
+## Task 2: Parser extension - `parse_with_collections()`
+
+**Files:**
+- Modify: `/opt/sortof/api/parse.py`
+
+- [ ] **Step 1: Backup**
+
+```bash
+cp /opt/sortof/api/parse.py /opt/sortof/api/parse.py.bak-$(date +%Y%m%d-%H%M)
+```
+
+- [ ] **Step 2: Add the new function and a Steam-URL regex**
+
+Open `/opt/sortof/api/parse.py`. The current file defines only `parse_workshop_input(text)`. Add at the bottom (do **not** modify the existing function - it's still used by `/api/sort` for backwards compat through the polymorphic path):
+
+```python
+import re as _re_module  # already imported at top; alias avoided if duplicate
+
+# Steam Workshop URL form: https://steamcommunity.com/{sharedfiles,workshop}/filedetails/?id=NNNNNNN
+_STEAM_URL_RE = re.compile(
+    r"https?://steamcommunity\.com/(?:sharedfiles|workshop)/filedetails/\?id=(\d{7,12})",
+    re.IGNORECASE,
+)
+
+
+def parse_with_collections(text: str) -> tuple[List[str], List[str]]:
+    """Split an input blob into bare wsids and candidate collection IDs.
+
+    A "candidate collection" is any 7-12-digit ID that appears inside a
+    Steam Workshop URL. Bare numeric IDs in the same blob are treated as
+    mod wsids (current behavior). Steam doesn't syntactically distinguish
+    collection IDs from mod IDs; the candidate list is sent to
+    GetCollectionDetails to confirm. If a candidate isn't actually a
+    collection, the caller falls it back to wsids.
+
+    Returns (wsids, collection_ids), each deduped and in first-seen order.
+    """
+    if not text:
+        return ([], [])
+
+    # 1. Find URL-form IDs FIRST (so they don't get double-counted as bare).
+    url_ids: List[str] = []
+    seen_url: set[str] = set()
+    for m in _STEAM_URL_RE.finditer(text):
+        i = m.group(1)
+        if i not in seen_url:
+            seen_url.add(i)
+            url_ids.append(i)
+
+    # 2. Strip the URLs out before extracting bare numbers.
+    text_minus_urls = _STEAM_URL_RE.sub("", text)
+
+    # 3. Bare wsids: same regex as parse_workshop_input.
+    cleaned = re.sub(
+        r"^\s*(WorkshopItems|Mods|Map)\s*=\s*",
+        "",
+        text_minus_urls,
+        flags=re.MULTILINE | re.IGNORECASE,
+    )
+    bare_ids = re.findall(r"\b\d{7,12}\b", cleaned)
+    seen_bare: set[str] = set()
+    bare_unique: List[str] = []
+    for i in bare_ids:
+        if i not in seen_bare and i not in seen_url:
+            seen_bare.add(i)
+            bare_unique.append(i)
+
+    return (bare_unique, url_ids)
+```
+
+(The `import re as _re_module` line is a paste-safe stub - `re` is already imported at the top of the file. Drop the alias line if a static check complains about a duplicate import.)
+
+- [ ] **Step 3: py_compile**
+
+```bash
+/opt/sortof/api/.venv/bin/python -m py_compile /opt/sortof/api/parse.py && echo PY_OK
+```
+
+- [ ] **Step 4: Functional smoke test in the venv REPL**
+
+```bash
+cd /opt/sortof/api && .venv/bin/python -c "
+from parse import parse_with_collections, parse_workshop_input
+
+# Pure bare wsids - backwards compat.
+assert parse_with_collections('2169435993;2392709985') == (['2169435993','2392709985'], [])
+
+# Pure URL.
+assert parse_with_collections('https://steamcommunity.com/sharedfiles/filedetails/?id=2200148440') == ([], ['2200148440'])
+
+# Mixed: URL + bare.
+assert parse_with_collections('https://steamcommunity.com/sharedfiles/filedetails/?id=2200148440\n2169435993') == (['2169435993'], ['2200148440'])
+
+# Same ID appearing both as URL AND as bare → URL wins, bare side dedups.
+assert parse_with_collections('2200148440\nhttps://steamcommunity.com/sharedfiles/filedetails/?id=2200148440') == ([], ['2200148440'])
+
+# Empty.
+assert parse_with_collections('') == ([], [])
+assert parse_with_collections(None) == ([], [])
+
+# Existing parse_workshop_input still works.
+assert parse_workshop_input('2169435993;2392709985') == ['2169435993','2392709985']
+
+print('ALL_OK')
+"
+```
+
+Expected: `ALL_OK`. Any AssertionError stops the task - fix the regex/dedupe logic before proceeding.
+
+- [ ] **Step 5: Checkpoint** - parser ready for the API to consume.
+
+---
+
+## Task 3: Steam helper - `fetch_collection_details()`
+
+**Files:**
+- Modify: `/opt/sortof/api/steam.py`
+
+- [ ] **Step 1: Backup**
+
+```bash
+cp /opt/sortof/api/steam.py /opt/sortof/api/steam.py.bak-$(date +%Y%m%d-%H%M)
+```
+
+- [ ] **Step 2: Add the helper, mirroring `fetch_workshop_details`**
+
+Open `/opt/sortof/api/steam.py`. The current file has one async helper. Add a sibling at the bottom:
+
+```python
+COLLECTION_URL = (
+    "https://api.steampowered.com/ISteamRemoteStorage/GetCollectionDetails/v1/"
+)
+
+
+async def fetch_collection_details(
+    client: httpx.AsyncClient,
+    collection_ids: List[str],
+) -> Dict[str, Dict]:
+    """Resolve candidate collection IDs to their child wsids.
+
+    Returns a dict keyed by collection_id with shape:
+        { "result": int, "children": List[str] }
+
+    Anonymous endpoint; no API key needed. result==1 means valid collection;
+    result!=1 means the ID isn't a collection (could be a mod, deleted, or
+    private). Caller decides what to do with non-1 results - see Spec B+F
+    §10 Q3 "Partial expansion failure" and Q4 "Flakiness".
+    """
+    if not collection_ids:
+        return {}
+    data: Dict[str, str] = {"collectioncount": str(len(collection_ids))}
+    for i, cid in enumerate(collection_ids):
+        data[f"publishedfileids[{i}]"] = cid
+    r = await client.post(COLLECTION_URL, data=data)
+    r.raise_for_status()
+    body = r.json()
+    out: Dict[str, Dict] = {}
+    for item in body.get("response", {}).get("collectiondetails", []) or []:
+        cid = item.get("publishedfileid")
+        if not cid:
+            continue
+        out[cid] = {
+            "result": int(item.get("result", 0)),
+            "children": [
+                c.get("publishedfileid", "")
+                for c in (item.get("children") or [])
+                if c.get("publishedfileid")
+            ],
+        }
+    return out
+```
+
+- [ ] **Step 3: py_compile + smoke import**
+
+```bash
+/opt/sortof/api/.venv/bin/python -m py_compile /opt/sortof/api/steam.py && echo PY_OK
+cd /opt/sortof/api && .venv/bin/python -c "import app; from steam import fetch_collection_details; print(fetch_collection_details.__doc__.split(chr(10))[0])"
+```
+
+Expected: `PY_OK` and the first line of the helper's docstring.
+
+- [ ] **Step 4: Functional smoke test against real Steam (one collection ID)**
+
+The implementer should pick a known PZ collection - search `https://steamcommunity.com/workshop/browse/?appid=108600&section=collections` for any active collection, copy its ID from the URL bar, and use it here. Substitute below:
+
+```bash
+COLL_ID="<paste-real-PZ-collection-id-here>"
+curl -sS -X POST 'https://api.steampowered.com/ISteamRemoteStorage/GetCollectionDetails/v1/' \
+  --data-urlencode 'collectioncount=1' \
+  --data-urlencode "publishedfileids[0]=$COLL_ID" \
+  | jq '.response.collectiondetails[0] | {result, n_children: (.children | length)}'
+```
+
+Expected: `result: 1`, `n_children > 0`.
+
+Then call our helper through the venv:
+
+```bash
+cd /opt/sortof/api && .venv/bin/python -c "
+import asyncio, httpx
+from steam import fetch_collection_details
+
+async def main():
+    async with httpx.AsyncClient(timeout=30.0) as c:
+        out = await fetch_collection_details(c, ['$COLL_ID'])
+    print(out)
+
+asyncio.run(main())
+"
+```
+
+Expected: a dict like `{'<COLL_ID>': {'result': 1, 'children': ['<wsid1>', '<wsid2>', ...]}}`.
+
+- [ ] **Step 5: Checkpoint** - Steam helper verified end-to-end.
+
+---
+
+## Task 4: `jobs.py` - CRUD, phase derivation, live counts, lifespan sweep
+
+**Files:**
+- Create: `/opt/sortof/api/jobs.py`
+
+- [ ] **Step 1: Write the module**
+
+Create `/opt/sortof/api/jobs.py` with:
+
+```python
+"""sort_jobs persistence + phase derivation.
+
+Phase is *derived* on every GET (Spec B+F §4): never stored as the source
+of truth except for terminal states. The function `derive_phase` reads
+live counts from download_jobs and decides expanding/queued/draining/done.
+This makes the system restart-resilient by construction - there is no
+event log to replay.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional, Tuple
+from uuid import UUID
+
+import asyncpg
+
+
+# ── CRUD ────────────────────────────────────────────────────────────────────
+
+async def create_job(
+    conn: asyncpg.Connection,
+    *,
+    input_raw: str,
+    collection_ids: List[str],
+    wsids: Optional[List[str]],
+    rules_raw: Optional[str],
+    initial_phase: str,
+) -> str:
+    """Insert a sort_jobs row and return the job_id (UUID as string).
+
+    initial_phase: 'expanding' if collections still need resolving,
+                   'queued' if wsids are already resolved at submit time.
+    """
+    row = await conn.fetchrow(
+        """
+        INSERT INTO sort_jobs (phase, input_raw, collection_ids, wsids, rules_raw)
+        VALUES ($1, $2, $3, $4, $5)
+        RETURNING job_id
+        """,
+        initial_phase, input_raw, collection_ids, wsids, rules_raw,
+    )
+    return str(row["job_id"])
+
+
+async def get_job_row(conn: asyncpg.Connection, job_id: str) -> Optional[Dict[str, Any]]:
+    """Fetch a sort_jobs row by id. Returns None if not found.
+
+    job_id may be either a string UUID or asyncpg-native UUID.
+    """
+    try:
+        uid = UUID(job_id) if isinstance(job_id, str) else job_id
+    except ValueError:
+        return None
+    row = await conn.fetchrow(
+        "SELECT * FROM sort_jobs WHERE job_id = $1",
+        uid,
+    )
+    return dict(row) if row else None
+
+
+async def update_phase(
+    conn: asyncpg.Connection,
+    job_id: str,
+    phase: str,
+    *,
+    wsids: Optional[List[str]] = None,
+    result_json: Optional[Dict[str, Any]] = None,
+    failure_reason: Optional[str] = None,
+) -> None:
+    """Advance a job's phase. wsids/result_json/failure_reason are optional
+    column updates that pair with phase transitions."""
+    sets = ["phase = $2", "phase_started_at = now()"]
+    params: List[Any] = [UUID(job_id), phase]
+    idx = 3
+    if wsids is not None:
+        sets.append(f"wsids = ${idx}::text[]")
+        params.append(wsids)
+        idx += 1
+    if result_json is not None:
+        sets.append(f"result_json = ${idx}::jsonb")
+        params.append(json.dumps(result_json))
+        idx += 1
+    if failure_reason is not None:
+        sets.append(f"failure_reason = ${idx}")
+        params.append(failure_reason)
+        idx += 1
+    await conn.execute(
+        f"UPDATE sort_jobs SET {', '.join(sets)} WHERE job_id = $1",
+        *params,
+    )
+
+
+# ── live counts (Spec B+F §6) ───────────────────────────────────────────────
+
+async def compute_counts(conn: asyncpg.Connection, wsids: List[str]) -> Dict[str, int]:
+    """Compute live cached/queued/draining counts for a set of wsids.
+    Empty wsids → all zeros."""
+    if not wsids:
+        return {"cached": 0, "queued": 0, "draining": 0}
+    rows = await conn.fetch(
+        """
+        SELECT
+            (SELECT COUNT(DISTINCT mp.workshop_id)
+             FROM mod_parsed mp
+             JOIN workshop_meta wm ON wm.workshop_id = mp.workshop_id
+             WHERE mp.workshop_id = ANY($1::text[])
+               AND mp.parsed_at_time_updated = wm.time_updated) AS cached,
+            (SELECT COUNT(DISTINCT workshop_id)
+             FROM download_jobs
+             WHERE workshop_id = ANY($1::text[]) AND status = 'queued') AS queued,
+            (SELECT COUNT(DISTINCT workshop_id)
+             FROM download_jobs
+             WHERE workshop_id = ANY($1::text[]) AND status = 'downloading') AS draining
+        """,
+        wsids,
+    )
+    r = rows[0]
+    return {"cached": int(r["cached"]), "queued": int(r["queued"]), "draining": int(r["draining"])}
+
+
+# ── phase derivation (Spec B+F §4) ──────────────────────────────────────────
+
+def derive_phase(
+    stored_phase: str,
+    wsids: Optional[List[str]],
+    counts: Dict[str, int],
+) -> str:
+    """Decide the live phase from the row's stored phase + current counts.
+
+    Terminal phases (done/failed) are never demoted. Non-terminal phases
+    are recomputed from current state.
+    """
+    if stored_phase in ("done", "failed"):
+        return stored_phase
+    if wsids is None:
+        return "expanding"
+    if counts["draining"] > 0:
+        return "draining"
+    if counts["queued"] > 0:
+        return "queued"
+    if counts["cached"] >= len(wsids):
+        return "done"
+    # Transient gap: a row just left 'queued' and hasn't shown up in
+    # mod_parsed yet. Most likely just-failed and not yet re-queued.
+    return "queued"
+
+
+# ── stale-expansion sweep (Spec B+F §9) ─────────────────────────────────────
+
+STALE_EXPANSION_SQL = """
+UPDATE sort_jobs
+   SET phase = 'failed',
+       failure_reason = 'expansion timed out',
+       updated_at = now()
+ WHERE phase = 'expanding'
+   AND phase_started_at < now() - interval '10 minutes'
+RETURNING job_id;
+"""
+
+
+async def sweep_stale_expansions(conn: asyncpg.Connection) -> int:
+    """Run on uvicorn lifespan startup. Returns the number of jobs reaped."""
+    rows = await conn.fetch(STALE_EXPANSION_SQL)
+    return len(rows)
+```
+
+- [ ] **Step 2: py_compile + smoke import**
+
+```bash
+/opt/sortof/api/.venv/bin/python -m py_compile /opt/sortof/api/jobs.py && echo PY_OK
+cd /opt/sortof/api && .venv/bin/python -c "import jobs; print(sorted(n for n in dir(jobs) if not n.startswith('_'))[:8])"
+```
+
+Expected: `PY_OK` followed by a list including `compute_counts`, `create_job`, `derive_phase`, `get_job_row`, `sweep_stale_expansions`, `update_phase`.
+
+- [ ] **Step 3: Phase derivation unit smoke**
+
+Phase derivation is pure (no DB), so it's testable without a connection:
+
+```bash
+cd /opt/sortof/api && .venv/bin/python -c "
+from jobs import derive_phase
+
+# Terminal preserved.
+assert derive_phase('done',   ['a'],  {'cached':1,'queued':0,'draining':0}) == 'done'
+assert derive_phase('failed', ['a'],  {'cached':0,'queued':0,'draining':0}) == 'failed'
+
+# wsids null → expanding.
+assert derive_phase('expanding', None, {'cached':0,'queued':0,'draining':0}) == 'expanding'
+
+# Active drain.
+assert derive_phase('queued', ['a','b'], {'cached':0,'queued':1,'draining':1}) == 'draining'
+
+# Just queued.
+assert derive_phase('queued', ['a','b'], {'cached':0,'queued':2,'draining':0}) == 'queued'
+
+# All cached.
+assert derive_phase('queued', ['a','b'], {'cached':2,'queued':0,'draining':0}) == 'done'
+
+# Transient gap (between queued exit and parsed entry).
+assert derive_phase('queued', ['a','b'], {'cached':1,'queued':0,'draining':0}) == 'queued'
+
+print('PHASE_OK')
+"
+```
+
+Expected: `PHASE_OK`.
+
+- [ ] **Step 4: Live-counts smoke (DB round-trip)**
+
+```bash
+cd /opt/sortof/api && .venv/bin/python -c "
+import asyncio, db
+from jobs import compute_counts
+
+async def main():
+    pool = await db.create_pool()
+    async with pool.acquire() as conn:
+        c1 = await compute_counts(conn, [])
+        assert c1 == {'cached':0,'queued':0,'draining':0}
+        # canonical 3-mod test set is fully cached.
+        c2 = await compute_counts(conn, ['2169435993','2392709985','2487022075'])
+        assert c2['cached'] == 3
+    await pool.close()
+    print('COUNTS_OK')
+
+asyncio.run(main())
+"
+```
+
+Expected: `COUNTS_OK`.
+
+- [ ] **Step 5: Checkpoint** - module reusable from `app.py`.
+
+---
+
+## Task 5: Background expansion task
+
+**Files:**
+- Create: `/opt/sortof/api/expansion.py`
+
+- [ ] **Step 1: Write the expansion runner**
+
+Create `/opt/sortof/api/expansion.py` with:
+
+```python
+"""Background async task: take a freshly-created sort_jobs row in 'expanding'
+phase, resolve its collection_ids via Steam, populate wsids[], advance phase
+to 'queued' (and drop wsids into download_jobs as needed)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any, Dict, List
+
+import asyncpg
+import httpx
+
+from jobs import update_phase
+from steam import fetch_collection_details
+
+log = logging.getLogger("sortof.expansion")
+
+COLLECTION_TTL_SECONDS = 6 * 3600  # Spec B+F §5.3
+
+
+async def _resolve_collections(
+    conn: asyncpg.Connection,
+    http: httpx.AsyncClient,
+    collection_ids: List[str],
+) -> tuple[Dict[str, List[str]], List[str]]:
+    """Returns (resolved, unresolvable). resolved maps collection_id ->
+    [child_wsids]. unresolvable lists collection_ids that GetCollectionDetails
+    couldn't fetch (after one retry)."""
+    if not collection_ids:
+        return ({}, [])
+
+    # Cache lookup (TTL = 6h via last_fetched_at).
+    cache_rows = await conn.fetch(
+        """
+        SELECT collection_id, child_workshop_ids
+          FROM collections
+         WHERE collection_id = ANY($1::text[])
+           AND last_fetched_at > now() - interval '6 hours'
+        """,
+        collection_ids,
+    )
+    resolved: Dict[str, List[str]] = {
+        r["collection_id"]: list(r["child_workshop_ids"])
+        for r in cache_rows
+    }
+    miss = [cid for cid in collection_ids if cid not in resolved]
+
+    unresolvable: List[str] = []
+    if miss:
+        for attempt in (1, 2):
+            try:
+                api_out = await fetch_collection_details(http, miss)
+            except httpx.HTTPError as e:
+                log.warning("GetCollectionDetails attempt %d failed: %s", attempt, e)
+                if attempt == 1:
+                    await asyncio.sleep(2.0)
+                    continue
+                unresolvable = list(miss)
+                api_out = {}
+            for cid in miss:
+                rec = api_out.get(cid)
+                if rec is None or rec.get("result") != 1:
+                    unresolvable.append(cid)
+                    continue
+                children = rec.get("children") or []
+                resolved[cid] = list(children)
+                await conn.execute(
+                    """
+                    INSERT INTO collections (collection_id, child_workshop_ids, last_fetched_at)
+                    VALUES ($1, $2, now())
+                    ON CONFLICT (collection_id) DO UPDATE
+                       SET child_workshop_ids = EXCLUDED.child_workshop_ids,
+                           last_fetched_at    = now()
+                    """,
+                    cid, children,
+                )
+            break  # success - stop retrying
+    # Dedupe (in case retry-on-flake added the same cid twice).
+    seen: set[str] = set()
+    out_unres: List[str] = []
+    for u in unresolvable:
+        if u not in seen:
+            seen.add(u)
+            out_unres.append(u)
+    return (resolved, out_unres)
+
+
+async def run_expansion(
+    pool: asyncpg.Pool,
+    http: httpx.AsyncClient,
+    job_id: str,
+    bare_wsids: List[str],
+    collection_ids: List[str],
+) -> None:
+    """Top-level expansion task. Logs and persists; never raises out."""
+    try:
+        async with pool.acquire() as conn:
+            resolved, unresolvable = await _resolve_collections(conn, http, collection_ids)
+
+            # Compose wsids: collections (in input order) + bare wsids, deduped.
+            seen: set[str] = set()
+            wsids: List[str] = []
+            for cid in collection_ids:
+                for w in resolved.get(cid, []):
+                    if w and w not in seen:
+                        seen.add(w)
+                        wsids.append(w)
+            for w in bare_wsids:
+                if w not in seen:
+                    seen.add(w)
+                    wsids.append(w)
+
+            if not wsids:
+                # All collections unresolvable AND no bare wsids. Job dies.
+                await update_phase(
+                    conn, job_id, "failed",
+                    failure_reason="all input collections unresolvable",
+                )
+                log.info("expansion %s: failed - all collections unresolvable", job_id)
+                return
+
+            partial_warnings = [
+                {
+                    "tag": "collection-partial",
+                    "level": "warning",
+                    "msg": f"collection {cid} could not be fetched",
+                }
+                for cid in unresolvable
+            ]
+            seed_result: Dict[str, Any] = {"WARNINGS": partial_warnings} if partial_warnings else None
+
+            await update_phase(
+                conn, job_id, "queued",
+                wsids=wsids,
+                result_json=seed_result,
+            )
+            log.info(
+                "expansion %s: queued (wsids=%d unresolvable=%d)",
+                job_id, len(wsids), len(unresolvable),
+            )
+    except Exception:
+        log.exception("expansion %s: crashed", job_id)
+        try:
+            async with pool.acquire() as conn:
+                await update_phase(conn, job_id, "failed", failure_reason="expansion crashed")
+        except Exception:
+            log.exception("expansion %s: cleanup failed", job_id)
+```
+
+- [ ] **Step 2: py_compile + smoke import**
+
+```bash
+/opt/sortof/api/.venv/bin/python -m py_compile /opt/sortof/api/expansion.py && echo PY_OK
+cd /opt/sortof/api && .venv/bin/python -c "from expansion import run_expansion; print('IMPORT_OK')"
+```
+
+Expected: `PY_OK` and `IMPORT_OK`.
+
+- [ ] **Step 3: End-to-end smoke against the live DB + Steam**
+
+```bash
+cd /opt/sortof/api && .venv/bin/python -c "
+import asyncio, httpx, db, jobs, expansion
+
+COLL_ID = '<paste-real-PZ-collection-id>'  # same one you used in Task 3 step 4
+
+async def main():
+    pool = await db.create_pool()
+    async with pool.acquire() as conn:
+        # Pre-clear any cached row to test the cold path.
+        await conn.execute('DELETE FROM collections WHERE collection_id=\$1', COLL_ID)
+        jid = await jobs.create_job(
+            conn, input_raw=f'https://steamcommunity.com/sharedfiles/filedetails/?id={COLL_ID}',
+            collection_ids=[COLL_ID], wsids=None, rules_raw=None,
+            initial_phase='expanding',
+        )
+    async with httpx.AsyncClient(timeout=30.0) as http:
+        await expansion.run_expansion(pool, http, jid, [], [COLL_ID])
+    async with pool.acquire() as conn:
+        row = await jobs.get_job_row(conn, jid)
+        assert row['phase'] == 'queued', row
+        assert row['wsids'] is not None and len(row['wsids']) > 0
+        # Cleanup.
+        await conn.execute('DELETE FROM sort_jobs WHERE job_id=\$1', row['job_id'])
+    await pool.close()
+    print('EXPANSION_OK')
+
+asyncio.run(main())
+"
+```
+
+Expected: `EXPANSION_OK`. Substitute `COLL_ID` with the real ID from Task 3.
+
+- [ ] **Step 4: Checkpoint** - expansion runner ready to be triggered from `/api/sort`.
+
+---
+
+## Task 6: Polymorphic `/api/sort` + lifespan sweep wiring
+
+**Files:**
+- Modify: `/opt/sortof/api/app.py`
+
+- [ ] **Step 1: Backup**
+
+```bash
+cp /opt/sortof/api/app.py /opt/sortof/api/app.py.bak-$(date +%Y%m%d-%H%M)
+```
+
+- [ ] **Step 2: Add new imports**
+
+Find the existing import block (around lines 1-30). Add:
+
+```python
+import asyncio
+import jobs
+import expansion
+from parse import parse_with_collections  # existing parse_workshop_input import stays
+```
+
+- [ ] **Step 3: Wire stale-expansion sweep into lifespan startup**
+
+Find the existing `@asynccontextmanager async def lifespan(app: FastAPI):` block (around line 38). Inside the body, after the pool/http are created and before `yield`, add:
+
+```python
+    async with pool.acquire() as conn:
+        n_reaped = await jobs.sweep_stale_expansions(conn)
+        if n_reaped:
+            log.info("lifespan startup: reaped %d stale expansion job(s)", n_reaped)
+```
+
+- [ ] **Step 4: Make `/api/sort` polymorphic**
+
+Find the `async def sort_endpoint(...)` function. The current body parses input via `parse_workshop_input`, hits Steam, queues misses, runs `mlos_sort`, returns sync. Replace the parsing line:
+
+```python
+    input_ids = parse_workshop_input(req.input or "")
+```
+
+with:
+
+```python
+    bare_wsids, collection_ids = parse_with_collections(req.input or "")
+    input_ids = bare_wsids  # used by existing code paths below
+```
+
+Then, immediately after the validation `raise HTTPException(...)` checks (so we still 400 on empty input and 413 on >MAX_IDS), but **before** the Steam metadata fetch, insert a fork:
+
+```python
+    # ── B+F: route to async job if collections present OR uncached wsids
+    # require drain time ───────────────────────────────────────────────────
+    if collection_ids or len(input_ids) > 0:
+        # Fast-path probe: are ALL bare wsids already cache-fresh? If so AND
+        # there are no collections, fall through to the existing sync path.
+        # (Spec B+F §10 Q1: "Bare wsid + all-cached → synchronous".)
+        if not collection_ids and input_ids:
+            try:
+                steam_details = await steam.fetch_workshop_details(
+                    request.app.state.http, input_ids,
+                )
+            except httpx.HTTPError as e:
+                log.warning("steam api error: %s", e)
+                elapsed_ms = int((time.monotonic() - t0) * 1000)
+                log.info(
+                    "sort done hits=0 misses=%d status=error ms=%d",
+                    len(input_ids), elapsed_ms,
+                )
+                return _empty_payload(input_ids, "error")
+            # Cache check: are all input_ids in mod_parsed and fresh?
+            pool = request.app.state.db
+            async with pool.acquire() as conn:
+                fresh = 0
+                for wid in input_ids:
+                    d = steam_details.get(wid)
+                    if not d or d.get("result") != 1:
+                        break  # bail out - there's a non-cacheable id, route to job
+                    tu = int(d.get("time_updated", 0))
+                    row = await conn.fetchrow(
+                        "SELECT 1 FROM mod_parsed "
+                        "WHERE workshop_id = $1 AND parsed_at_time_updated = $2 LIMIT 1",
+                        wid, tu,
+                    )
+                    if row is not None:
+                        fresh += 1
+                    else:
+                        break
+                if fresh == len(input_ids):
+                    # All cache-fresh - sync path. Re-use the existing flow
+                    # by NOT routing to a job. Fall through.
+                    pass
+                else:
+                    # Async path.
+                    return await _route_to_job(
+                        request, conn, req.input or "", req.rules,
+                        bare_wsids, collection_ids,
+                    )
+        elif collection_ids:
+            pool = request.app.state.db
+            async with pool.acquire() as conn:
+                return await _route_to_job(
+                    request, conn, req.input or "", req.rules,
+                    bare_wsids, collection_ids,
+                )
+```
+
+This is the routing fork. The fast-path probe lets all-cached bare-wsid input fall through to the existing sync code unchanged. Anything else (uncached wsids OR any collection) returns a job_id.
+
+- [ ] **Step 5: Add `_route_to_job` helper near the route definition**
+
+Just above the `@app.post("/api/sort")` decorator, insert:
+
+```python
+async def _route_to_job(
+    request: Request,
+    conn,
+    input_raw: str,
+    rules_raw: Optional[str],
+    bare_wsids: List[str],
+    collection_ids: List[str],
+) -> Dict[str, Any]:
+    """Create a sort_jobs row and (if needed) kick off background expansion.
+    Returns {status, job_id} for the client to start polling."""
+    if collection_ids:
+        # Will resolve in the background.
+        job_id = await jobs.create_job(
+            conn,
+            input_raw=input_raw,
+            collection_ids=collection_ids,
+            wsids=None,
+            rules_raw=rules_raw,
+            initial_phase="expanding",
+        )
+        asyncio.create_task(expansion.run_expansion(
+            request.app.state.db,
+            request.app.state.http,
+            job_id,
+            bare_wsids,
+            collection_ids,
+        ))
+        return {"status": "expanding", "job_id": job_id}
+    else:
+        # Bare wsids that include uncached. Kick off cold drain by queueing.
+        # We dedupe wsids before storing them on the job (the existing
+        # /api/sort flow does this for bare input lists).
+        seen: set = set()
+        wsids: List[str] = []
+        for w in bare_wsids:
+            if w not in seen:
+                seen.add(w)
+                wsids.append(w)
+        job_id = await jobs.create_job(
+            conn,
+            input_raw=input_raw,
+            collection_ids=[],
+            wsids=wsids,
+            rules_raw=rules_raw,
+            initial_phase="queued",
+        )
+        # Queue any wsids not already in download_jobs (mirrors the existing
+        # flow at the bottom of sort_endpoint, but we don't need Steam validation
+        # here since the GET poll will surface unknowns/non-mods naturally
+        # via the counts contract).
+        for wid in wsids:
+            existing = await conn.fetchval(
+                "SELECT 1 FROM download_jobs "
+                "WHERE workshop_id = $1 AND status IN ('queued','downloading') LIMIT 1",
+                wid,
+            )
+            if existing is None:
+                await conn.execute(
+                    "INSERT INTO download_jobs (workshop_id, status) VALUES ($1, 'queued')",
+                    wid,
+                )
+        return {"status": "queued", "job_id": job_id}
+```
+
+- [ ] **Step 6: py_compile + smoke import**
+
+```bash
+/opt/sortof/api/.venv/bin/python -m py_compile /opt/sortof/api/app.py && echo PY_OK
+cd /opt/sortof/api && .venv/bin/python -c "import app" && echo IMPORT_OK
+```
+
+- [ ] **Step 7: Restart API**
+
+```bash
+sudo systemctl restart sortof-api && sleep 2 && sudo systemctl is-active sortof-api
+```
+
+Expected: `active`.
+
+- [ ] **Step 8: Verify the sync fast path is unchanged**
+
+```bash
+curl -sS -X POST http://100.114.205.53:8801/api/sort \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"2169435993;2392709985;2487022075"}' \
+  | jq '{status, MODS_LINE, has_job_id: (has("job_id"))}'
+```
+
+Expected: `{"status":"success","MODS_LINE":"modoptions;tsarslib;TMC_TrueActions","has_job_id":false}`.
+
+- [ ] **Step 9: Verify the bare-uncached path returns a job_id**
+
+```bash
+# First, find a wsid that ISN'T cached. The HellDrinx wsid is non_mod, not great.
+# Use a real PZ mod that isn't in mod_parsed yet - implementer needs to find one
+# fresh from Steam. Or simpler: temporarily delete a cached row to force a miss:
+sudo docker exec -i sortof_db psql -U sortof -d sortof -c "
+DELETE FROM mod_parsed WHERE workshop_id='2196102849';
+DELETE FROM workshop_meta WHERE workshop_id='2196102849';"
+
+curl -sS -X POST http://100.114.205.53:8801/api/sort \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"2196102849"}' | jq '{status, has_job_id: (has("job_id")), job_id_preview: (.job_id // "" | .[0:8])}'
+```
+
+Expected: `{"status":"queued","has_job_id":true,"job_id_preview":"<8-hex-chars>"}`.
+
+The drain will reprocess `2196102849` (Raven Creek) and re-cache it; that's fine.
+
+- [ ] **Step 10: Verify the collection path returns expanding + job_id**
+
+```bash
+COLL_ID="<real-PZ-collection-id>"
+curl -sS -X POST http://100.114.205.53:8801/api/sort \
+  -H 'Content-Type: application/json' \
+  -d "{\"input\":\"https://steamcommunity.com/sharedfiles/filedetails/?id=$COLL_ID\"}" \
+  | jq '{status, has_job_id: (has("job_id"))}'
+```
+
+Expected: `{"status":"expanding","has_job_id":true}`.
+
+- [ ] **Step 11: Checkpoint** - `/api/sort` polymorphism live; jobs being created. Polling endpoint is Task 7.
+
+---
+
+## Task 7: `GET` + `DELETE /api/jobs/{job_id}`
+
+**Files:**
+- Modify: `/opt/sortof/api/app.py` (add two endpoints near the existing routes)
+
+- [ ] **Step 1: Backup (if more than ~15 minutes since the Task 6 backup)**
+
+```bash
+cp /opt/sortof/api/app.py /opt/sortof/api/app.py.bak-$(date +%Y%m%d-%H%M)
+```
+
+- [ ] **Step 2: Add the GET endpoint**
+
+Find the end of `sort_endpoint` (the function body ends with `return payload`). Below it, insert:
+
+```python
+@app.get("/api/jobs/{job_id}")
+async def get_job_endpoint(job_id: str, request: Request) -> Dict[str, Any]:
+    pool = request.app.state.db
+    async with pool.acquire() as conn:
+        row = await jobs.get_job_row(conn, job_id)
+        if row is None:
+            raise HTTPException(status_code=404, detail="job not found or expired")
+        wsids = list(row["wsids"]) if row["wsids"] else None
+        counts = await jobs.compute_counts(conn, wsids or [])
+        phase = jobs.derive_phase(row["phase"], wsids, counts)
+
+        # If we just transitioned a non-terminal job to 'done', persist the
+        # final result for future polls (and for the §3 24h TTL artifact).
+        result_json = row["result_json"]
+        if phase == "done" and row["phase"] != "done":
+            result_json = await _build_result_for_job(conn, wsids, row["rules_raw"])
+            await jobs.update_phase(
+                conn, job_id, "done", result_json=result_json,
+            )
+        elif phase != "done" and wsids:
+            # Compute a fresh partial result on every poll - cheap, avoids
+            # staleness. Don't persist; only `done` writes result_json.
+            result_json = await _build_result_for_job(conn, wsids, row["rules_raw"])
+
+    return {
+        "job_id":         str(row["job_id"]),
+        "phase":          phase,
+        "counts":         counts,
+        "wsids":          wsids,
+        "result":         result_json,
+        "failure_reason": row["failure_reason"],
+    }
+```
+
+- [ ] **Step 3: Add the `_build_result_for_job` helper**
+
+Just above the `_empty_payload` helper (around line 100), insert:
+
+```python
+async def _build_result_for_job(
+    conn,
+    wsids: List[str],
+    rules_raw: Optional[str],
+) -> Dict[str, Any]:
+    """Compute the SORTOF_DATA payload from currently-cached mod_parsed rows
+    for the given wsids. Used both for partial results during draining and
+    for the final result on phase transition to 'done'."""
+    if not wsids:
+        return _empty_payload([], "success")
+    rows = await conn.fetch(
+        """
+        SELECT mp.workshop_id, mp.mod_id, mp.name, mp.category,
+               mp.requirements, mp.load_after, mp.load_before,
+               mp.incompatible_mods, mp.load_first, mp.load_last,
+               mp.tags, mp.maps
+          FROM mod_parsed mp
+          JOIN workshop_meta wm ON wm.workshop_id = mp.workshop_id
+         WHERE mp.workshop_id = ANY($1::text[])
+           AND mp.parsed_at_time_updated = wm.time_updated
+         ORDER BY mp.workshop_id, mp.mod_id
+        """,
+        wsids,
+    )
+    mods = [_row_to_modinfo(r) for r in rows]
+    rules: Dict[str, Any] = {}
+    if rules_raw:
+        try:
+            rules = parse_sorting_rules(rules_raw)
+        except Exception:
+            log.warning("job result: failed to parse sorting_rules")
+    sort_result = sort_mods(mods, rules)
+    cached_ids = list({r["workshop_id"] for r in rows})
+    payload = adapters.build_response(
+        input_ids=wsids,    # contract: WORKSHOP_ITEMS_LINE = wsids[] at job creation
+        hit_ids=cached_ids,
+        mods=mods,
+        sort_result=sort_result,
+        status="success" if len(cached_ids) >= len(wsids) else "partial",
+    )
+    # Forced override: WORKSHOP_ITEMS_LINE locked to the original wsids[]
+    # regardless of which are currently cached (Spec A §8 / Spec B+F §6).
+    payload["WORKSHOP_ITEMS_LINE"] = ";".join(wsids) + ";" if wsids else ""
+    payload["pending"] = [w for w in wsids if w not in set(cached_ids)]
+    payload["unknown"] = []   # this endpoint doesn't compute Steam-result-9
+    payload["non_mod"] = []   # nor non-mod classification - those are sync-path concerns
+    return payload
+```
+
+- [ ] **Step 4: Add the DELETE endpoint**
+
+Below the GET endpoint, insert:
+
+```python
+@app.delete("/api/jobs/{job_id}", status_code=204)
+async def delete_job_endpoint(job_id: str, request: Request):
+    """Cancel a job. Idempotent: cancelling a terminal job is a no-op 204.
+    Does NOT touch download_jobs (Spec B+F §8)."""
+    pool = request.app.state.db
+    async with pool.acquire() as conn:
+        row = await jobs.get_job_row(conn, job_id)
+        if row is None:
+            raise HTTPException(status_code=404, detail="job not found")
+        if row["phase"] not in ("done", "failed"):
+            await jobs.update_phase(conn, job_id, "failed", failure_reason="cancelled")
+    return None
+```
+
+- [ ] **Step 5: py_compile + restart**
+
+```bash
+/opt/sortof/api/.venv/bin/python -m py_compile /opt/sortof/api/app.py && echo PY_OK
+cd /opt/sortof/api && .venv/bin/python -c "import app" && echo IMPORT_OK
+sudo systemctl restart sortof-api && sleep 2 && sudo systemctl is-active sortof-api
+```
+
+- [ ] **Step 6: Verify GET on a fresh collection job**
+
+```bash
+COLL_ID="<real-PZ-collection-id>"
+JOB_RESP=$(curl -sS -X POST http://100.114.205.53:8801/api/sort \
+  -H 'Content-Type: application/json' \
+  -d "{\"input\":\"https://steamcommunity.com/sharedfiles/filedetails/?id=$COLL_ID\"}")
+JID=$(echo "$JOB_RESP" | jq -r '.job_id')
+echo "job_id=$JID"
+
+# First poll, likely expanding
+curl -sS http://100.114.205.53:8801/api/jobs/$JID | jq '{phase, counts, has_wsids: (.wsids != null)}'
+
+# Wait for expansion + initial drain
+sleep 3
+curl -sS http://100.114.205.53:8801/api/jobs/$JID | jq '{phase, counts, n_wsids: (.wsids|length)}'
+
+# 404 on garbage id
+curl -sS -o /dev/null -w 'http=%{http_code}\n' http://100.114.205.53:8801/api/jobs/00000000-0000-0000-0000-000000000000
+```
+
+Expected: first poll has `phase: "expanding"`; second poll has `phase` in `(queued, draining, done)` with `n_wsids > 0`; the garbage id returns `http=404`.
+
+- [ ] **Step 7: Verify DELETE on an active job**
+
+```bash
+# Submit a fresh job so we can cancel it before it drains
+JID=$(curl -sS -X POST http://100.114.205.53:8801/api/sort \
+  -H 'Content-Type: application/json' \
+  -d "{\"input\":\"https://steamcommunity.com/sharedfiles/filedetails/?id=$COLL_ID\"}" \
+  | jq -r '.job_id')
+
+# Cancel immediately
+curl -sS -o /dev/null -w 'cancel=%{http_code}\n' -X DELETE http://100.114.205.53:8801/api/jobs/$JID
+
+# Idempotent re-cancel
+curl -sS -o /dev/null -w 'recancel=%{http_code}\n' -X DELETE http://100.114.205.53:8801/api/jobs/$JID
+
+# Confirm phase
+curl -sS http://100.114.205.53:8801/api/jobs/$JID | jq '{phase, failure_reason}'
+```
+
+Expected: `cancel=204`, `recancel=204`, `phase: "failed"`, `failure_reason: "cancelled"`.
+
+- [ ] **Step 8: Checkpoint** - backend complete. Frontend wiring is Tasks 8-10.
+
+---
+
+## Task 8: Frontend - detect `job_id`, polling loop, partial-result rendering
+
+**Files:**
+- Modify: `/opt/sortof/frontend/sortof-app.jsx`
+
+- [ ] **Step 1: Backup**
+
+```bash
+cp /opt/sortof/frontend/sortof-app.jsx /opt/sortof/frontend/sortof-app.jsx.bak-$(date +%Y%m%d-%H%M)
+```
+
+- [ ] **Step 2: Add a polling helper near other top-of-file helpers**
+
+Find the `buildModsLine` function (around line 32). Below it (and **above** the `isRadioMode` / `defaultSelectionForBranches` block), add:
+
+```jsx
+// Spec B+F: poll a job. Resolves with { phase, result, counts, wsids } on
+// terminal phase OR when an explicit stop signal fires. Caller controls the
+// AbortSignal to cancel polling on unmount / cancel-button / new-sort.
+const POLL_INTERVAL_MS = 2500;
+
+async function pollJobOnce(jobId) {
+  const res = await fetch(`/api/jobs/${jobId}`);
+  if (res.status === 404) return { kind: 'expired' };
+  if (!res.ok) return { kind: 'error', status: res.status };
+  const json = await res.json();
+  return { kind: 'ok', body: json };
+}
+
+function pollJobLoop(jobId, signal, onTick) {
+  // Returns a Promise that resolves on terminal phase or AbortSignal.
+  return new Promise((resolve) => {
+    let timer = null;
+    async function tick() {
+      if (signal.aborted) { if (timer) clearTimeout(timer); resolve({ kind: 'aborted' }); return; }
+      const r = await pollJobOnce(jobId);
+      if (signal.aborted) { resolve({ kind: 'aborted' }); return; }
+      onTick(r);
+      if (r.kind === 'expired' || r.kind === 'error') { resolve(r); return; }
+      const phase = r.body.phase;
+      if (phase === 'done' || phase === 'failed') { resolve(r); return; }
+      timer = setTimeout(tick, POLL_INTERVAL_MS);
+    }
+    tick();
+  });
+}
+```
+
+- [ ] **Step 3: Add an AbortController ref + cancel-job state in App**
+
+Find the App function's state declarations (search for `const [pzBuild, setPzBuild]`). Below the existing useState/useRef block but above the existing useEffects, add:
+
+```jsx
+const pollAbortRef = useRef(null);
+const [activeJobId, setActiveJobId] = useState(null);
+```
+
+- [ ] **Step 4: Update `onSort` to branch on `job_id`**
+
+Find the `async function onSort()` body. The current body POSTs to `/api/sort` and applies the response. Find the line that receives the response:
+
+```jsx
+const json = await res.json();
+_liveSortData = json;
+```
+
+Insert a branch immediately before `_liveSortData = json`:
+
+```jsx
+const json = await res.json();
+if (json.job_id) {
+  // Async path - start polling and let the loop drive state.
+  // Abort any in-flight previous poll.
+  if (pollAbortRef.current) { pollAbortRef.current.abort(); }
+  const ctrl = new AbortController();
+  pollAbortRef.current = ctrl;
+  setActiveJobId(json.job_id);
+
+  pollJobLoop(json.job_id, ctrl.signal, (r) => {
+    if (r.kind !== 'ok') return;
+    const b = r.body;
+    if (b.result) {
+      _liveSortData = b.result;
+      sortContextRef.current = {
+        workshopItemsLine: (b.result.WORKSHOP_ITEMS_LINE) || '',
+        originalQueued: (b.result.pending || []).length,
+        unknown: b.result.unknown || [],
+        nonMod:  b.result.non_mod || [],
+      };
+    }
+    setProgress(b.phase === 'expanding' ? 5 : Math.min(95, 10 + b.counts.cached));
+    setCounts({
+      cached: b.counts.cached,
+      queued: b.counts.queued,
+      parsing: b.counts.draining,
+      warnings: ((b.result && b.result.WARNINGS) || []).length,
+      unknown: ((b.result && b.result.unknown) || []).length,
+      nonMod:  ((b.result && b.result.non_mod) || []).length,
+    });
+    setState(b.phase);   // 'expanding' | 'queued' | 'draining' | 'done' | 'failed'
+  }).then((final) => {
+    setActiveJobId(null);
+    if (final.kind === 'expired') {
+      setState('error');
+      _liveSortData = {
+        ...(_liveSortData || {}),
+        WARNINGS: [
+          ...((_liveSortData?.WARNINGS) || []),
+          { tag: 'retry', level: 'red', msg: 'this job expired - re-submit' },
+        ],
+      };
+    }
+  });
+  return;
+}
+// Sync fast path - existing code follows.
+_liveSortData = json;
+```
+
+- [ ] **Step 5: Verify served file picks up the new symbols**
+
+```bash
+curl -sS http://100.114.205.53:8801/sortof-app.jsx | grep -cE 'pollJobLoop|pollJobOnce|activeJobId|pollAbortRef|/api/jobs/'
+```
+
+Expected: ≥ 6.
+
+- [ ] **Step 6: Manual browser smoke (or curl-driven simulation)**
+
+The implementer should open `https://sortof.indifferentketchup.com/` and submit a real PZ collection URL. Expect: status strip text changes from `expanding…` to `queued`/`draining` to `done`. Network tab shows `GET /api/jobs/<uuid>` calls every 2.5s. Output panel populates as mods land in `mod_parsed`.
+
+If headless: replicate by curling `/api/sort` with a collection URL, capturing the job_id, and curling `/api/jobs/<id>` repeatedly until `phase=done`. Confirm `result_json` populates with `MODS_LINE` etc. once draining completes.
+
+- [ ] **Step 7: Checkpoint** - polling drives `_liveSortData` updates. Phase-specific status strip is Task 9.
+
+---
+
+## Task 9: Frontend - phase-specific status strip
+
+**Files:**
+- Modify: `/opt/sortof/frontend/sortof-app.jsx`
+
+- [ ] **Step 1: Backup**
+
+```bash
+cp /opt/sortof/frontend/sortof-app.jsx /opt/sortof/frontend/sortof-app.jsx.bak-$(date +%Y%m%d-%H%M)
+```
+
+- [ ] **Step 2: Update `StatusStrip` to render phase-specific text**
+
+Find the existing `function StatusStrip({ state, counts, progress })`. The existing function returns either an idle strip or a counts strip based on `state`. Replace its body with:
+
+```jsx
+function StatusStrip({ state, counts, progress }) {
+  // Idle / terminal states - single pill summary.
+  if (state === 'idle' || state === 'success' || state === 'error' || state === 'cold' || state === 'done' || state === 'failed') {
+    return (
+      <div className="status-strip">
+        <span className={'status-pill ' + (state === 'failed' || state === 'error' ? 'idle' : 'idle')}>
+          <span className="dot-led"></span>
+          {state === 'idle'    && 'ready when you are'}
+          {state === 'success' && `done. ${counts.cached} mods, ${counts.warnings} warnings`}
+          {state === 'done'    && `done. ${counts.cached} mods, ${counts.warnings} warnings`}
+          {state === 'error'   && 'something went sideways'}
+          {state === 'failed'  && 'job failed'}
+          {state === 'cold'    && 'cache miss - be patient'}
+        </span>
+      </div>
+    );
+  }
+
+  // 'expanding' phase - no useful counts yet.
+  if (state === 'expanding') {
+    return (
+      <div className="status-strip">
+        <span className="status-pill expanding">
+          <span className="dot-led"></span>expanding collection…
+        </span>
+        <div className="progress-bar"><i style={{ width: `${progress}%` }}></i></div>
+      </div>
+    );
+  }
+
+  // 'queued' or 'draining' - live counts. Existing 'partial'/'loading' too.
+  return (
+    <div className="status-strip">
+      <span className="status-pill cached">
+        <span className="dot-led"></span>{counts.cached} cached
+      </span>
+      <span className="status-pill queued">
+        <span className="dot-led"></span>{counts.queued} queued
+      </span>
+      <span className="status-pill parse">
+        <span className="dot-led"></span>{counts.parsing} draining
+      </span>
+      {counts.unknown > 0 && (
+        <span className="status-pill unknown" title="Steam doesn't recognize these IDs (deleted, typo'd, or private)">
+          <span className="dot-led"></span>{counts.unknown} unknown
+        </span>
+      )}
+      {counts.nonMod > 0 && (
+        <span className="status-pill nonmod" title="Workshop items that aren't loadable mods (collections, art, etc.)">
+          <span className="dot-led"></span>{counts.nonMod} non-mod
+        </span>
+      )}
+      <div className="progress-bar"><i style={{ width: `${progress}%` }}></i></div>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 3: Verify served**
+
+```bash
+curl -sS http://100.114.205.53:8801/sortof-app.jsx | grep -cE 'expanding collection|state === .expanding|state === .draining|state === .done|state === .failed'
+```
+
+Expected: ≥ 4.
+
+- [ ] **Step 4: Manual browser smoke**
+
+Submit a collection URL. Expect: strip starts with `expanding collection…`, transitions to live counts, ends with `done. N mods, …` summary.
+
+---
+
+## Task 10: Frontend - Cancel button + 404 expired-job handling + CSS
+
+**Files:**
+- Modify: `/opt/sortof/frontend/sortof-app.jsx`
+- Modify: `/opt/sortof/frontend/index.html`
+
+- [ ] **Step 1: Backup**
+
+```bash
+cp /opt/sortof/frontend/sortof-app.jsx /opt/sortof/frontend/sortof-app.jsx.bak-$(date +%Y%m%d-%H%M)
+cp /opt/sortof/frontend/index.html /opt/sortof/frontend/index.html.bak-$(date +%Y%m%d-%H%M)
+```
+
+- [ ] **Step 2: Render a Cancel button when a job is active**
+
+Find where the Sort button is rendered (search for `sort-btn` and `onClick={onSort}`). It's inside the left column. Below the existing Sort button JSX, add:
+
+```jsx
+{activeJobId && (
+  <button
+    className="cancel-btn"
+    onClick={async () => {
+      if (pollAbortRef.current) pollAbortRef.current.abort();
+      try {
+        await fetch(`/api/jobs/${activeJobId}`, { method: 'DELETE' });
+      } catch {}
+      setActiveJobId(null);
+      setState('idle');
+      setProgress(0);
+    }}
+  >cancel</button>
+)}
+```
+
+- [ ] **Step 3: CSS for `.status-pill.expanding` and `.cancel-btn`**
+
+Open `/opt/sortof/frontend/index.html`. Find the `.status-pill.nonmod` rule (added during the unknown/non-mod feature). Below it, add:
+
+```css
+  .status-pill.expanding { color: var(--acc-blue); }
+  .status-pill.expanding .dot-led { background: var(--acc-blue); animation: bl 1.2s ease-in-out infinite; }
+
+  .cancel-btn {
+    appearance: none;
+    width: 100%;
+    height: 32px;
+    margin-top: 6px;
+    border: 1px solid var(--line);
+    background: transparent;
+    color: var(--fg-2);
+    border-radius: var(--radius);
+    font-family: var(--mono);
+    font-size: 12px;
+    cursor: pointer;
+    transition: color .12s, border-color .12s, background .12s;
+  }
+  .cancel-btn:hover { color: var(--acc-red); border-color: var(--acc-red); background: var(--acc-red-bg); }
+```
+
+- [ ] **Step 4: Verify served**
+
+```bash
+curl -sS http://100.114.205.53:8801/sortof-app.jsx | grep -c 'cancel-btn'
+curl -sS http://100.114.205.53:8801/ | grep -cE '\.status-pill\.expanding|\.cancel-btn'
+```
+
+Expected: ≥ 1 (jsx), ≥ 2 (CSS).
+
+- [ ] **Step 5: Manual browser smoke**
+
+Submit a fresh cold collection. While the strip reads `expanding` or `draining`, click cancel. Expect: strip clears, `setActiveJobId(null)` fires, no further GET polls in the network tab.
+
+---
+
+## Task 11: Spec §11 acceptance + §12 test recipes
+
+For each item, document expected vs actual. If any fails, return to the relevant task.
+
+- [ ] **Step 1: §11.1 Sync fast path** - bare wsids, all cached.
+
+```bash
+curl -sS -X POST http://100.114.205.53:8801/api/sort \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"2169435993;2392709985;2487022075"}' | jq '{has_job_id: (has("job_id")), MODS_LINE}'
+```
+
+Expected: `{"has_job_id": false, "MODS_LINE": "modoptions;tsarslib;TMC_TrueActions"}`.
+
+- [ ] **Step 2: §11.2 Async path on uncached bare wsid**
+
+```bash
+sudo docker exec -i sortof_db psql -U sortof -d sortof -c "DELETE FROM mod_parsed WHERE workshop_id='2196102849'; DELETE FROM workshop_meta WHERE workshop_id='2196102849';"
+curl -sS -X POST http://100.114.205.53:8801/api/sort -H 'Content-Type: application/json' -d '{"input":"2196102849"}' | jq '{status, has_job_id: (has("job_id"))}'
+```
+
+Expected: `{"status":"queued","has_job_id":true}`.
+
+- [ ] **Step 3: §11.3 Collection URL → expanding**
+
+```bash
+COLL_ID="<paste-real-PZ-collection-id>"
+curl -sS -X POST http://100.114.205.53:8801/api/sort \
+  -H 'Content-Type: application/json' \
+  -d "{\"input\":\"https://steamcommunity.com/sharedfiles/filedetails/?id=$COLL_ID\"}" \
+  | jq '{status, has_job_id: (has("job_id"))}'
+```
+
+Expected: `{"status":"expanding","has_job_id":true}`.
+
+- [ ] **Step 4: §11.4 GET on bogus job → 404**
+
+```bash
+curl -sS -o /dev/null -w 'http=%{http_code}\n' http://100.114.205.53:8801/api/jobs/00000000-0000-0000-0000-000000000000
+```
+
+Expected: `http=404`.
+
+- [ ] **Step 5: §11.5 DELETE → idempotent 204**
+
+```bash
+JID=$(curl -sS -X POST http://100.114.205.53:8801/api/sort -H 'Content-Type: application/json' -d "{\"input\":\"https://steamcommunity.com/sharedfiles/filedetails/?id=$COLL_ID\"}" | jq -r '.job_id')
+curl -sS -o /dev/null -w 'cancel1=%{http_code}\n' -X DELETE http://100.114.205.53:8801/api/jobs/$JID
+curl -sS -o /dev/null -w 'cancel2=%{http_code}\n' -X DELETE http://100.114.205.53:8801/api/jobs/$JID
+curl -sS http://100.114.205.53:8801/api/jobs/$JID | jq '{phase, failure_reason}'
+```
+
+Expected: `cancel1=204`, `cancel2=204`, `{"phase":"failed","failure_reason":"cancelled"}`.
+
+- [ ] **Step 6: §11.6 Steam URL detection + GetCollectionDetails routing**
+
+Already verified by step 3 of this task. Confirm via journal:
+
+```bash
+sudo journalctl -u sortof-api --since "2 min ago" | grep -E 'GetCollectionDetails|expansion'
+```
+
+Expected: at least one entry naming the collection ID.
+
+- [ ] **Step 7: §11.7 Cache hit on second submit (within 6h)**
+
+Re-submit the same collection URL. Confirm: response is fast; `journalctl` for the new request does NOT show a fresh GetCollectionDetails call. (The expansion task's cache hit short-circuits the API call.) An implementation note: a second submit creates a new sort_jobs row but reuses the cached children.
+
+- [ ] **Step 8: §11.8 Partial-collection failure**
+
+```bash
+# Combine real + bogus collection URL
+curl -sS -X POST http://100.114.205.53:8801/api/sort \
+  -H 'Content-Type: application/json' \
+  -d "{\"input\":\"https://steamcommunity.com/sharedfiles/filedetails/?id=$COLL_ID\nhttps://steamcommunity.com/sharedfiles/filedetails/?id=99999999\"}" | jq '.job_id'
+```
+
+Then poll the returned job until `phase=done`, and check `result.WARNINGS`:
+
+```bash
+curl -sS http://100.114.205.53:8801/api/jobs/<jid> | jq '.result.WARNINGS[] | select(.tag=="collection-partial")'
+```
+
+Expected: one entry with `msg` mentioning `99999999`.
+
+- [ ] **Step 9: §11.9 All collections fail**
+
+```bash
+curl -sS -X POST http://100.114.205.53:8801/api/sort \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"https://steamcommunity.com/sharedfiles/filedetails/?id=99999999"}' | jq -r '.job_id' | tee /tmp/jid_test
+sleep 3
+curl -sS http://100.114.205.53:8801/api/jobs/$(cat /tmp/jid_test) | jq '{phase, failure_reason}'
+```
+
+Expected: `{"phase":"failed","failure_reason":"all input collections unresolvable"}`.
+
+- [ ] **Step 10: §11.10 Stale-expansion sweep on restart**
+
+```bash
+# Manually create a stale expansion row
+sudo docker exec -i sortof_db psql -U sortof -d sortof -c "
+INSERT INTO sort_jobs (phase, phase_started_at, input_raw, collection_ids)
+VALUES ('expanding', now() - interval '15 minutes', 'sweep test', ARRAY['99999999'])
+RETURNING job_id;" | tail -3 | head -1 | xargs -I{} echo "stale_jid={}"
+sudo systemctl restart sortof-api && sleep 3
+sudo docker exec -i sortof_db psql -U sortof -d sortof -c "
+SELECT phase, failure_reason FROM sort_jobs WHERE input_raw='sweep test';"
+```
+
+Expected: phase=`failed`, failure_reason=`expansion timed out`.
+
+- [ ] **Step 11: §11.11 Counts contract - sum equals total minus non_mod**
+
+After a cold collection drains, sum the live counts and compare to wsids count:
+
+```bash
+JID=<some-active-job>
+curl -sS http://100.114.205.53:8801/api/jobs/$JID | jq '
+  .counts as $c | .wsids as $w | {
+    sum: ($c.cached + $c.queued + $c.draining),
+    total_wsids: ($w | length),
+    delta: (($w | length) - ($c.cached + $c.queued + $c.draining))
+  }'
+```
+
+Expected: `delta` is the count of wsids that ended up `non_mod` or `unknown` (not in any of the three count buckets) - typically 0 or a small integer.
+
+- [ ] **Step 12: §11.12 WORKSHOP_ITEMS_LINE locked at job creation**
+
+After cancellation or partial-failure, the final `result.WORKSHOP_ITEMS_LINE` from `/api/jobs/<id>` must equal `wsids[]` joined by `;` regardless of how many landed in `non_mod` / `unknown`. Spot-check by comparing.
+
+- [ ] **Step 13: Public-hostname mirror**
+
+```bash
+curl -sS -X POST https://sortof.indifferentketchup.com/api/sort \
+  -H 'Content-Type: application/json' \
+  -d '{"input":"2169435993;2392709985;2487022075"}' | jq '{status, MODS_LINE}'
+```
+
+Expected: success, canonical MODS_LINE. Public side mirrors all backend behavior.
+
+- [ ] **Step 14: Final regression** - re-run the canonical 3-mod sync sort once more and confirm the response shape did not gain a `job_id` field.
+
+---
+
+## Self-review (already applied)
+
+- **Spec coverage:** §1 (overview) - Tasks 1-7 cover backend, 8-10 cover frontend. §2 (API contract) - Tasks 6-7. §3 (schema) - Task 1. §4 (phase machine) - `derive_phase` in Task 4. §5 (Steam expansion) - Tasks 3, 5. §6 (counts contract) - `compute_counts` in Task 4, applied in Task 7. §7 (frontend) - Tasks 8-10. §8 (cancellation) - Task 7 step 4 + Task 10. §9 (restart resilience) - `sweep_stale_expansions` in Task 4 + lifespan wiring in Task 6. §10 (open questions) - locked in spec; plan implements verbatim. §11/§12 - Task 11.
+- **Placeholders:** all `<paste-real-…>` markers explicitly call out the implementer-action; no TBDs.
+- **Type consistency:** `wsids` is `List[str] | None` everywhere; `counts` is `{cached: int, queued: int, draining: int}` everywhere; `phase` is the locked enum throughout. `pollJobLoop` callback receives the same shape `r.body` matches the GET endpoint return.
+- **No git, by design:** every code-changing task starts with a `cp file file.bak-$(date)` step in lieu of a commit. The schema migration in Task 1 is idempotent (`CREATE TABLE IF NOT EXISTS`) so no rollback file is needed.
+- **Restart-vs-no-restart:** backend tasks (1, 4, 5, 6, 7) end with `sudo systemctl restart sortof-api`. Frontend tasks (8, 9, 10) end with `curl-grep` only - `StaticFiles` serves from disk; hard-refresh in browser. Worker is unchanged across the entire feature.
diff --git a/docs/specs/2026-04-30-multi-branch-picker.md b/docs/specs/2026-04-30-multi-branch-picker.md
new file mode 100644
index 0000000..83d83cd
--- /dev/null
+++ b/docs/specs/2026-04-30-multi-branch-picker.md
@@ -0,0 +1,155 @@
+# Spec A - Multi-branch picker
+
+**Date:** 2026-04-30
+**Status:** Draft v2 (incorporates spec-review fixes #1–#13)
+**Out of scope:** B (collection expansion + live progress), C (build context), D (dep "Add" button), E (precacher), G (cleanups). See §11.
+
+## 1. Summary
+
+Some Steam Workshop items ship multiple `mod.info` files under one wsid (canonical example: AuthenticZ → `AuthenticZBackpacks+`, `Authentic Z - Current`, `AuthenticZLite`). Today every parsed `mod_id` flows into `MODS_LINE`, including alternates the user must pick exactly one of. This spec adds a per-wsid picker UI with `localStorage` persistence and a new `POST /api/resort` endpoint that recomputes load order and warnings for the chosen subset, without re-hitting Steam.
+
+## 2. Problem
+
+- AuthenticZ (wsid `2335368829`) yields three `mod_parsed` rows: `AuthenticZBackpacks+`, `Authentic Z - Current`, `AuthenticZLite`. They are mutually exclusive branches.
+- The author left `incompatible_mods` empty on all three, so we have no metadata signal that they are alternates.
+- Today's `MODS_LINE` is `";".join(SORTED_ORDER)`, so all three branch IDs land in the output. PZ refuses to start with conflicting mods, so the file **looks valid but bricks the server** - silent corruption.
+- Other multi-mod packages exist where every `mod_id` *should* load (cooperative content packs). The system must support both shapes.
+
+## 3. Trigger rules
+
+- The picker UI fires **iff a wsid has ≥2 rows in `mod_parsed`**.
+- Row count is the *only* trigger. Author metadata does not gate visibility - see §5 for what it changes.
+
+## 4. Default selection rules
+
+For each picker-eligible wsid:
+- **If** any `mod_parsed.incompatible_mods` for that wsid lists another `mod_id` from the same wsid → default selection = **first `mod_id` only**.
+- **Else** → default selection = **all `mod_id`s ticked**.
+
+"First" tiebreaker: `ORDER BY parsed_at ASC, mod_id ASC`. `worker.process_one` parses sequentially in a `for mip in mod_info_paths: await conn.execute(UPSERT_MOD_PARSED, ...)` loop (one statement per `mod.info`, no `gather`/`to_thread`), so `parsed_at = now()` produces strictly increasing microsecond values per row in practice. `mod_id ASC` is the defensive tiebreaker for the theoretical sub-microsecond case. **This is a spec-locked decision** - revisit if the resulting "primary" branch feels wrong on real inputs.
+
+### Default-selection safety net (fix for review #1)
+
+The default-all-ticked path covers the canonical AuthenticZ case (3 rows, all `incompatible_mods=[]`) and would otherwise emit the same bricking config that motivated this spec. To prevent silent corruption, the API emits an additional warning whenever the default leaves all branches selected without any author signal:
+
+- If a wsid has ≥2 mod rows, AND every row's `incompatible_mods` is empty, AND the user's current selection includes all branches (i.e., they haven't unticked any), emit a `WARNINGS` entry: `tag: "ambiguous-multi-branch"`, `level: "amber"`, `msg: "X branches selected from <wsid title> - author didn't declare alternates; verify these aren't mutually exclusive (e.g., AuthenticZ Lite vs Current). Expand the row to pick one."`
+- The warning clears as soon as the user makes any explicit selection (any branch unticked, or - in radio mode - any branch chosen).
+- Picker UI remains opt-in; this rule guarantees the user sees a yellow flag without having to expand every multi-branch row.
+
+## 5. UI mode rules
+
+- Default: **checkboxes** (multi-select).
+- Upgrade to **radios** (single-select; exactly one always picked) **iff** any `mod_id` for the wsid lists another `mod_id` from the same wsid in its `incompatible_mods`.
+- **Cross-wsid** incompatibilities (mod A in wsid X marks mod B in wsid Y) do **not** trigger radio mode for either wsid; they continue to flow through the existing Warnings system.
+
+## 6. UI placement & interactions
+
+- Inline row expansion in the existing `ModTable` (`sortof-app.jsx:306`). No new top-level component.
+- A multi-branch wsid renders as **one** parent `<tr>`, occupying the slot the first selected `mod_id` from that wsid holds in `SORTED_ORDER`. Other selected branch `mod_id`s from the same wsid do not render their own rows - they live inside the expanded panel.
+- Mod ID cell affordance:
+  - **Unresolved** (no user interaction yet, no hydrated selection): `▾ N branches`
+  - **Resolved** (user touched it, or hydrated from `localStorage`): `✓ X of N`
+- Click affordance to toggle expansion. Multiple wsids may be expanded simultaneously - single-pass triage on a 450-mod collection.
+- Expanded panel: a single `<tr>` with `colSpan={COLUMN_COUNT}` containing per-branch rows of `[checkbox|radio] mod_id - name - cat - deps - pos`. `COLUMN_COUNT` is a single source-of-truth constant (today 6; Spec C will add a 7th column for build-context). **Do not hardcode the integer.** Match existing column rhythm so zebra striping still reads.
+- Single-mod wsids render unchanged.
+- **`/api/resort` failure mode** (review #11): on 5xx response, retain the prior `MOD_DB`/`SORTED_ORDER`/`MODS_LINE`/`WARNINGS` state and emit a transient `WARNINGS` entry `couldn't recompute sort - try again` (level=red) with a retry button. Never apply a partial response.
+- Parent row's category / deps / load cells reflect the **first selected** branch's values; if zero are selected, the parent row remains visible with affordance `✓ 0 of N` and `-` in the data cells, and contributes nothing to `MODS_LINE` / `SORTED_ORDER`. Display position for zero-selected rows is implementation-defined (e.g., previous slot, or sorted by any `mod_id` from the wsid) since the wsid no longer appears in `SORTED_ORDER`.
+
+## 7. Persistence
+
+- `localStorage` key: `sortof.branch.selections`. **One** key total - hydrate in a single read.
+- Value: JSON-serialized object keyed by wsid → array of selected `mod_id` strings.
+
+```json
+{ "2335368829": ["Authentic Z - Current"], "2169435993": ["modoptions"] }
+```
+
+- **Hydration** on app mount: read once, merge into in-memory `branchSelections` state.
+- **Eviction**: if a stored `mod_id` is no longer present in the current `MOD_DB` rows for that wsid (cache invalidated upstream, mod.info changed, etc.), drop it silently. Do not warn.
+- **Radio-mode invariant guard** (review #2): if eviction would leave a radio-mode wsid with zero selected `mod_id`s, fall back to the §4 default (first-only). Radio mode's "exactly one always picked" invariant must hold post-hydrate.
+- Single-mod wsids never write to this object; absence implies "use default".
+- **Cross-tab sync** (review #8): App attaches a `window.addEventListener('storage', ...)` listener; on a `sortof.branch.selections` storage event, replace in-memory `branchSelections` with the new value and trigger a single `/api/resort`. Last-writer-wins on the underlying storage value; in-tab state stays coherent.
+
+## 8. API impact
+
+- **No change** to `POST /api/sort` request or response shape.
+- **New** endpoint: `POST /api/resort`, taking the current selection and returning a fresh order + warnings without re-hitting Steam.
+
+```json
+{ "selected_mod_ids": ["modoptions","tsarslib","Authentic Z - Current"] }
+```
+
+- Response: same shape as `/api/sort` with `status:"success"` and `pending:[]`. Backend filters `mod_parsed` rows to the supplied set via `WHERE mod_id = ANY($1::text[])` (parameterized - review #9), runs `mlos_sort`, returns updated `SORTED_ORDER`, `MODS_LINE`, `WARNINGS`, `MOD_DB`. No DB writes.
+- `WORKSHOP_ITEMS_LINE` is **not** affected by selection - wsid stays subscribed regardless of which `mod_id`s are enabled. Matches PZ's `WorkshopItems` vs `Mods` semantics.
+
+### Scope, auth, validation (fix for review #3, #9, #10, #12)
+
+- **Stateless.** No session token, no per-user partition. `mod_parsed` is a shared cache; concurrent drain UPSERTs and `/api/resort` SELECTs serialize via asyncpg row locks. Multi-tenancy is out of scope for v1; if added later, expect a `submission_id` on `/api/sort` and `/api/resort`.
+- **Unknown `mod_id` handling** (review #12): server silently drops `selected_mod_ids` not present in `mod_parsed` (matches §7 client semantics) and logs at INFO. If the entire selection is empty after the drop, return HTTP 400 - the client can recover by re-running `/api/sort`.
+- **Input validation.** `selected_mod_ids` must be a JSON array of strings, length ≥1 and ≤500, each string ≤256 chars. Reject anything else with 400 before touching the DB. PZ `mod_id`s legitimately contain spaces, `+`, `-`, and apostrophes - the parameterized `ANY` pattern handles them safely; **no string interpolation anywhere** (review #9).
+- **Rate limiting** (review #10): not implemented at the FastAPI layer. Recommend a Caddy-level `@rate_limit` matcher on `/api/sort` and `/api/resort` before any public exposure beyond the current Tailscale-only bind. Documented as a known gap.
+
+### Sequenced requests (fix for review #5)
+
+- The frontend tags every `/api/resort` POST with a monotonically increasing client-side sequence number (in-memory counter on App, not part of the request body - sent as header `X-Sortof-Seq` or tracked via the issuing call site).
+- When a response arrives, compare its sequence number against the latest issued; if older, **drop the response without applying it** (UI keeps current state, last-issued response wins). Prevents stale-response overwrites under rapid toggling.
+
+## 9. Data assumptions
+
+- Schema column is `mod_parsed.incompatible_mods` (`TEXT[]`) - names already stripped of any leading `\` per the B42 parser fix shipped today.
+- `mod_parsed.parsed_at` ordering verified (review #4): `worker.process_one` parses `mod.info` files sequentially with `for mip in mod_info_paths: await conn.execute(UPSERT_MOD_PARSED, …)`. Each upsert is its own asyncpg statement (auto-commit, no transaction wrap), and `parsed_at` is `now()` evaluated server-side per statement. Sequential awaits + asyncpg RTT > 1µs ⇒ strictly increasing microsecond values in practice. `mod_id ASC` is a defensive tiebreaker for the theoretical sub-µs collision; no ordinal column exists in the schema and adding one is out of scope for this spec.
+- Dangling-deps detection (review #13) already exists in `mlos_sort.sort_mods` (`mlos_sort.py:432-437`): `enabled = set(by_id.keys())` then `miss = [r for r in mod.requirements if r not in enabled]` per mod. Calling `sort_mods` with a filtered subset on `/api/resort` automatically produces the new missing-dep warnings; no changes to `mlos_sort` are needed.
+- Frontend already has `incompatible_mods` available as `m.conflicts` on each `MOD_DB` row (`adapters.py:94`).
+- This spec consumes the `MOD_DB`/`SORTED_ORDER`/`WARNINGS` shape currently produced by `app.py` + `adapters.py`. Per-build variant filtering is Spec C; selection here operates on the full `mod_id` corpus the API returned.
+
+## 10. Open questions resolved
+
+1. **Client-side filter vs API round-trip.** *Client-side filter for the row affordance and parent-row rendering; server round-trip via `POST /api/resort` for sort + warnings recompute.* Justification: instant feedback on tick/untick UX, but warnings are dependency-driven and need real `mlos_sort` evaluation. Pure-client would require porting `mlos_sort` to JS - far worse than a 50ms POST to a hot Postgres connection.
+2. **`SORTED_ORDER` recompute strategy.** *Re-run `mlos_sort` on the selected subset via `POST /api/resort`.* Justification: when the user unticks `AuthenticZLite` and another mod requires it, the warnings list and possibly the topological order both change. Filtering the previous `SORTED_ORDER` post-hoc misses the new missing-dep warning, defeating the picker's safety value.
+3. **First-`mod_id` tiebreaker for default selection.** *`ORDER BY parsed_at ASC, mod_id ASC`.* Schema-deterministic and matches insertion order from `worker.process_one`. Flagged in §4 as a lockable spec decision; revisit on real corpus.
+4. **`localStorage` key namespacing.** *Single key `sortof.branch.selections`, value `{ [wsid]: string[] }`.* The `sortof.branch.` prefix reserves namespace for any future per-feature storage; one key keeps hydration to a single read.
+
+## 11. Out of scope
+
+- B41/B42 build-context filtering (Spec C).
+- Steam collection URL/ID expansion (Spec B).
+- Dependency "Add" button (Spec C/D pair).
+- Server-side persistence of branch choices.
+- Live drain progress streaming (Spec B+F).
+- Cleanups bundle (Spec G).
+
+## 12. Acceptance criteria
+
+- [ ] A wsid with N=1 mod row renders as a single normal row in `ModTable` (no behavior change).
+- [ ] A wsid with N≥2 mod rows renders as one parent row with `▾ N branches` in the Mod ID cell.
+- [ ] Clicking the affordance expands a `colSpan`'d panel listing all N rows with the correct input type (checkboxes by default, radios when intra-wsid `incompatible_mods` is non-empty).
+- [ ] Default selection matches §4 (all-ticked or first-only).
+- [ ] Toggling a branch updates the affordance to `✓ X of N` and triggers a `POST /api/resort` whose response replaces `MOD_DB`, `SORTED_ORDER`, `MODS_LINE`, `WARNINGS` in app state.
+- [ ] `WORKSHOP_ITEMS_LINE` is unchanged when branches toggle.
+- [ ] `localStorage["sortof.branch.selections"]` is read on mount and written after every toggle, matching the §7 schema.
+- [ ] A stored `mod_id` not present in the current `MOD_DB` for its wsid is dropped silently on hydrate.
+- [ ] Multiple expanded panels can coexist (no auto-collapse on expand).
+- [ ] Zero selected `mod_id`s for a wsid: affordance reads `✓ 0 of N`; row contributes nothing to `MODS_LINE` / `SORTED_ORDER`.
+- [ ] When a wsid has ≥2 mod rows AND every row's `incompatible_mods=[]` AND user has not unticked any branch, an `ambiguous-multi-branch` (amber) WARNINGS entry is present; entry clears on first explicit user selection in that wsid (review #1).
+- [ ] Eviction of a stored `mod_id` that empties a radio-mode wsid falls back to §4 default-first; never leaves a radio-mode wsid with zero selections (review #2).
+- [ ] `/api/resort` request carries a client-side sequence number; responses older than the latest issued are discarded without state mutation (review #5).
+- [ ] `/api/resort` 5xx response leaves prior state intact and surfaces a transient retry-able warning (review #11).
+- [ ] Server drops unknown `selected_mod_ids` silently and logs at INFO; empty post-drop selection returns 400 (review #12).
+- [ ] `colSpan` in `ModTable` references a single `COLUMN_COUNT` constant - not a hardcoded integer (review #7).
+- [ ] `storage` event listener installed; cross-tab toggle of `sortof.branch.selections` syncs in-memory state and triggers exactly one `/api/resort` (review #8).
+
+## 13. Test cases
+
+1. **AuthenticZ canonical** - wsid `2335368829`, three rows, all `incompatible_mods=[]`. Expect: parent row `▾ 3 branches`, default = all ticked, mode = checkboxes. Untick two → `MODS_LINE` reflects one. Reload → selection persists.
+2. **Cooperative pack** - wsid that ships 3 mods, all `incompatible_mods=[]`, deps reference each other. Expect: same affordance, default = all ticked, no behavior change for the user who never expands.
+3. **Mutually exclusive 2-branch** - wsid where mod A's `incompatible_mods` lists mod B and vice versa. Expect: mode = radios, default = mod A only (first by `parsed_at, mod_id`).
+4. **Persistence across reload** - pick a non-default subset, reload page; confirm hydration from `localStorage["sortof.branch.selections"]` restores the selection on next sort.
+5. **Stored `mod_id` no longer exists (checkbox mode)** - manually inject a stored `mod_id` not in `MOD_DB`, reload. Expect: silent drop, no console error, default applies.
+6. **Cross-wsid incompatibility** - mod A (wsid X) lists mod B (wsid Y) in `incompatible_mods`; both wsids have N=1. Expect: no picker UI, existing warning still surfaces.
+7. **Zero-tick wsid** - untick all branches in a multi-branch wsid. Expect: parent row stays in `ModTable` with `✓ 0 of N`; no contribution to `MODS_LINE` / `SORTED_ORDER` / numeric counts.
+8. **Radio-mode eviction-to-empty** (review #6) - wsid in radio mode has stored selection `[X]`; `X` is removed from `MOD_DB` (e.g., upstream cache invalidation), reload. Expect: silent drop, then default-first applied, radio invariant preserved.
+9. **Default-all-ticked emits the safety warning** (review #1) - load AuthenticZ-canonical without expanding the row. Expect: a `tag:"ambiguous-multi-branch"` amber entry visible in WARNINGS. Untick one branch → entry disappears on next `/api/resort` response.
+10. **Stale resort response discarded** (review #5) - issue toggle 1 (slow), then toggle 2 (fast) before #1 returns. Expect: only #2's response applied; #1 dropped on arrival.
+11. **`/api/resort` 5xx** (review #11) - stub the endpoint to return 500; toggle a branch. Expect: prior state retained, transient red warning `couldn't recompute sort - try again` surfaced with retry control.
+12. **Cross-tab sync** (review #8) - open two tabs, toggle in tab A. Expect: tab B receives `storage` event and re-runs `/api/resort` with the new selection.
+13. **Unknown selected_mod_id from server perspective** (review #12) - POST `/api/resort` with `selected_mod_ids=["modoptions","ghostMod"]` where `ghostMod` isn't in `mod_parsed`. Expect: 200 with `ghostMod` silently absent from response; INFO log entry server-side. POST with all-ghost IDs → 400.
diff --git a/docs/specs/2026-04-30-patch-tier.md b/docs/specs/2026-04-30-patch-tier.md
new file mode 100644
index 0000000..6275aeb
--- /dev/null
+++ b/docs/specs/2026-04-30-patch-tier.md
@@ -0,0 +1,87 @@
+# Spec G-patch - Patch tier (Final Loads)
+
+**Date:** 2026-04-30
+**Status:** Draft (awaiting review)
+**Sibling specs:** A (multi-branch picker), B (collection expansion + live progress), C (build context), D (dep "Add" button), E (precacher), F (folded into B), G (cleanups bundle - this spec carves a piece out)
+
+## 1. Summary
+
+Add a **"patch" tier** to the load-order calculation: mods explicitly authored or detected as patches sort *after* every non-patch mod, including those flagged `loadLast=on`. Implementation is a single new axis at the top of `mlos_sort._initial_sort_key` plus a heuristic in `derive_category`. No schema migration. No new endpoint. No backwards-incompat changes for existing mods.
+
+## 2. Problem
+
+The PZ load-order convention (and the user-supplied 37-bucket taxonomy, bucket 37 "Final Loads") treats compatibility patches and retextures-of-other-mods as a strictly-last tier - they have to load *after* `loadLast=on` map mods, because they intercept or override the things those mods install. Today our sort key has no such tier:
+
+```
+PREORDER → loadFirst → loadLast → category → in-category loadFirst → in-category loadLast → alpha
+```
+
+A `loadLast=on` map mod ends up in the same bucket as a patch, ordered alphabetically. Patches that need to override the map mod can land *before* it. Silent corruption - output looks valid, the wrong mod wins at runtime.
+
+## 3. Detection rules
+
+A mod is a patch iff **any** of these is true:
+
+1. **Explicit:** `mod.info` contains `category=patch` (new value added to `RAW_CATEGORY_ORDER`).
+2. **Author-tagged via sorting_rules.txt:** user-supplied `[modId]\ncategory=patch` overrides anything else (existing mechanism, no change).
+3. **Name heuristic (conservative):** `mod.name` matches the case-insensitive regex `\b(patch|compat|compatibility)\b`. Examples that match: `BetterFlashlight Patch`, `BB Compatibility`, `RavenCreek - MoreSimpleClothing Compat`. Examples that **do not** match: `BugFixes`, `LittleTweaks`, `BalanceFix` - "fix" / "tweak" / "fixes" are too broad and would over-flag.
+
+The first matching rule wins. The heuristic is intentionally narrow; mod authors who want to opt in should use rule 1.
+
+## 4. Sort behavior
+
+Insert a new axis **at position 0** (above `PREORDER`) of the sort tuple:
+
+```
+(is_patch, PREORDER, loadFirst, loadLast, category, in-cat loadFirst, in-cat loadLast, alpha)
+```
+
+`is_patch = 1` for patches, `0` otherwise. Tuple comparison guarantees patches sort after every non-patch mod regardless of every downstream axis. Within the patch group, the existing sub-keys still apply (a patch with `PREORDER=2`, e.g. `ModManagerServer-Patch`, still sorts second-among-patches).
+
+## 5. Backend changes
+
+- **`mlos_sort.py`:**
+  - Append `"patch"` to `RAW_CATEGORY_ORDER` (so it's a valid `mod.category` value and topo sort treats it like any other category).
+  - Extend `derive_category(mod)` with the §3 name heuristic, returning `"patch"` when matched and category is otherwise `undefined`.
+  - Modify `_initial_sort_key`: prepend `1 if mod.category == "patch" else 0` as the new tuple element.
+- **`adapters.py`:** extend `CAT_MAP` with `"patch": "patch"` so the frontend pill key is preserved (see §6).
+- **`worker.py`:** no change. `mod.info` parsing already accepts arbitrary `category=…` values; once `"patch"` is in `CATEGORY_ORDER`, existing parser code passes it through unchanged.
+- **No schema migration.** `mod_parsed.category` is already `TEXT NOT NULL DEFAULT 'undefined'` - `"patch"` fits without alteration.
+
+## 6. Frontend changes
+
+- **New pill** `patch` in the mod-table category column. Recommended palette: muted mauve / pale grey to distinguish from `gameplay` (the current default for tweaks-shaped mods) without competing for attention.
+- **Pill is descriptive only** - sort position already telegraphs "this is a patch" since patches cluster at the bottom of the table. The pill is a quick visual confirmation, not a signal the user has to learn.
+- **CSS** addition only (one rule): `.cat.patch { background: …; color: …; }`. No layout or component changes.
+
+If the user prefers to skip the pill (5 buckets stays cleaner), the spec is satisfied without it; sort behavior is the load-bearing change.
+
+## 7. Out of scope
+
+- Detecting patches from Steam workshop tags (Steam's vocabulary has no canonical "Patch" tag - `Misc` and `Framework` are the closest, both too noisy to map).
+- Multiple patch sub-tiers (e.g., "patches-of-patches"). YAGNI; the existing `loadAfter` mechanism handles ordering between two patches when needed.
+- A `mod_parsed.is_patch` boolean column. Derived from `category` is sufficient and avoids a migration.
+- Auto-detecting patches via mod content inspection (Lua module overrides, file collisions). Heuristics only.
+
+## 8. Acceptance criteria
+
+- [ ] `mlos_sort._initial_sort_key` returns an 8-element tuple with `is_patch` (0 or 1) at index 0.
+- [ ] `RAW_CATEGORY_ORDER` includes `"patch"`.
+- [ ] `derive_category` returns `"patch"` when the name regex `\b(patch|compat|compatibility)\b` (case-insensitive) matches and `mod.info`'s `category=` is unset or `undefined`.
+- [ ] Explicit `category=patch` in `mod.info` is honored by the existing parser (no parser change required).
+- [ ] `sorting_rules.txt` `category=patch` override forces a mod into the patch tier.
+- [ ] In a sort with one `loadLast=on` map mod and one patch, the patch sorts *after* the map mod in `SORTED_ORDER`.
+- [ ] In a sort with two patches, alphabetical ordering applies between them (existing alpha tiebreaker preserved).
+- [ ] In a sort with no patches, `SORTED_ORDER` is bit-identical to pre-spec output (`is_patch=0` for all rows preserves existing total ordering).
+- [ ] `MOD_DB` rows for patches carry `cat: "patch"` once `adapters.CAT_MAP` is extended.
+
+## 9. Test cases
+
+1. **Explicit patch via mod.info** - wsid X has `category=patch`. Expect: sorts last regardless of `loadLast`. `MOD_DB.cat = "patch"`.
+2. **Heuristic match** - mod named `BB Compatibility Patch`, no explicit category. Expect: detected as patch, sorted last.
+3. **Heuristic miss (intentional)** - mods named `BugFixes`, `LittleTweaks`, `BalanceFix`. Expect: NOT in patch tier.
+4. **Patch + loadLast map mod** - input: a `loadLast=on` map mod (`Eerie_County`) and a patch (`Eerie_County - Brita Compat`). Expect: `Eerie_County` precedes the patch in `SORTED_ORDER`.
+5. **Two patches** - `AAA-Compatibility` and `ZZZ-Patch`. Expect: alphabetical order preserved within the tier.
+6. **No patches in input** - sort identical to current behavior; regression test against a saved canonical fixture (e.g. `2169435993;2392709985;2487022075`).
+7. **`sorting_rules.txt` override** - user supplies `[Some_Mod]\ncategory=patch`; expected to force into tier even if name doesn't match heuristic and `mod.info` doesn't declare it.
+8. **Patch with PREORDER mod_id** - hypothetical `ModManagerServer-Patch` (mod_id matches PREORDER table). Expect: still sorts within the patch tier (last), but among patches uses PREORDER=2 sub-ordering.
diff --git a/docs/specs/2026-05-01-build-context-dep-add.md b/docs/specs/2026-05-01-build-context-dep-add.md
new file mode 100644
index 0000000..7499e53
--- /dev/null
+++ b/docs/specs/2026-05-01-build-context-dep-add.md
@@ -0,0 +1,174 @@
+# Spec C — Build context + dep Add + auto-disambiguation rules
+
+> **Lineage:** sits on top of Spec A (multi-branch picker) and Spec B+F (collection expansion / live drain). Adds context-aware default selection. Does **not** modify the picker contract — Spec A §8 ownership still holds.
+
+## §1 Overview
+
+Three loosely-related improvements that share the same core: the system has more context than it has been using. The user already tells us their PZ build via the `pzBuild` localStorage toggle. The user already gives us a list of mod_ids (via the wsids in their input). The system should consult both before deciding which branches of a multi-branch wsid land in `MODS_LINE` by default.
+
+**Goal:** smarter pre-ticked boxes in the multi-branch picker. **Non-goal:** any form of "magic" sort that emits a branch the user didn't see.
+
+## §2 Build context (`pzBuild`)
+
+The frontend stores `sortof.pzBuild` in localStorage with values `"B41" | "B42"`, default `"B41"`. It already drives `MODS_LINE` rendering (B42 prefixes mod_ids with `\`).
+
+This spec extends `pzBuild` to:
+- Travel with `/api/sort` POST body as `pz_build: "B41" | "B42"`. The backend defaults to `"B42"` when missing or invalid.
+- Inform Rule A (§4.3) of auto-disambiguation.
+
+`pz_build` is **not** sent on `/api/resort` — the resort flow uses an explicit mod_id list and never re-evaluates rules.
+
+## §3 Dep Add (already shipped)
+
+Documenting the existing behavior so it's part of the locked design.
+
+When `mlos_sort` reports a missing requirement (mod A requires mod B, B is not in the user's enabled set), `build_warnings` enriches each `tag: "missing"` warning with one of:
+- `actions: [{type: "add-wsid", wsid, modId, label}]` — when `mod_parsed` has a row with `mod_id == B` (using `DISTINCT ON (mod_id) ORDER BY parsed_at_time_updated DESC`)
+- `actions: [{type: "search-workshop", modId, url, label}]` — when no cache hit; URL is `https://steamcommunity.com/workshop/browse/?appid=108600&searchtext=<modId>`
+
+The frontend renders `[add modId]` as a filled blue chip; clicking appends the wsid to the input textarea AND auto-resorts (no separate sort click needed). The search variant is `[↗ find modId]` and opens Steam's search in a new tab.
+
+## §4 Auto-disambiguation rules
+
+### §4.1 Design principle (locked)
+
+These rules **adjust which boxes are pre-ticked in the picker**. They never bypass the picker and never silently emit a branch the user didn't see. Spec A §8 ownership holds — the picker is the source of truth.
+
+The rules are applied at `/api/sort` time, before `MODS_LINE` is composed. The response's `MOD_DB` always contains every cached branch (so the picker can offer them); `SORTED_ORDER` and `MODS_LINE` reflect only the auto-selected set. The frontend reads the picker default from `SORTED_ORDER` membership.
+
+### §4.2 Order of evaluation per wsid
+
+```
+A → C → B
+```
+
+The first rule that single-ticks a branch wins; subsequent rules emit warnings only. Exception: A and C are orthogonal (build × addon) and both may tick the same wsid simultaneously — see §4.7.
+
+If a wsid is **coordinated** (any branch references a sibling via `requirements` / `loadAfter` / `loadBefore`) or **radio** (any branch lists a sibling in `incompatibleMods`), it is **exempt from rules A/B/C**. Coordinated → all branches stay; radio → first only.
+
+### §4.3 Rule A — build-aware default *(highest ROI)*
+
+A branch is **B41-flavored** if `mod_id`:
+- ends with `B41` (case-insensitive), or
+- contains `_legacy_` followed by version digits (e.g., `_legacy_42_12`, `_legacy_41_*`)
+
+A branch is **B42-flavored** if `mod_id`:
+- ends with `B42` or `_b42` (case-insensitive), or
+- contains `_b42_` (e.g., `vac_mod_b42_utils`)
+
+A branch is **un-flavored** otherwise.
+
+Apply: if exactly one branch is flavored to match the active `pz_build` AND no other branch shares that flavor, pre-tick that one. Un-flavored branches are treated as "the build the author considers default" — currently always B42.
+
+If no branch matches the active build (e.g., user is on B41 but every branch is B42-flavored), fall through to Rule C / B and emit a `build-mismatch` warning: `"no <build> variant for <name> (<wsid>); using author default"`.
+
+Rule A also fires when the wsid has **exactly two branches** and one is `B41`-flavored, one is unflavored — the unflavored is treated as B42 default. So a B42 user gets the unflavored, a B41 user gets the B41-flavored.
+
+### §4.4 Rule B — prefix-base tiebreaker
+
+When the auto-pick path needs to pick *one* branch (Rule A didn't single-tick, Rule C didn't fire), use the **shortest mod_id that is a strict prefix of every other branch's mod_id** instead of alphabetical-first.
+
+**Strict prefix definition:** `A` is a strict prefix of `B` iff:
+1. `A` ≠ `B`, AND
+2. `B.startswith(A)`, AND
+3. The character at position `len(A)` in `B` is a non-lowercase-letter — separator (`_` `-` ` `), digit (`0`-`9`), or uppercase letter (`A`-`Z`).
+
+Boundary regex: `^<A>([_\- ]|[A-Z]|[0-9]|$)`.
+
+**Examples that qualify:**
+- `ArmoredVests` ⊂ `ArmoredVestsPatch` (boundary: `P`)
+- `ToadTraits` ⊂ `ToadTraitsDisablePrepared` (boundary: `D`)
+- `LitSortOGSN` ⊂ `LitSortOGSN_chocolate` (boundary: `_`)
+- `WaterDispenser` ⊂ `WaterDispenser2` (boundary: `2`)
+
+**Examples that do NOT qualify:**
+- `Foo` vs `Foobar` (boundary: `b`, lowercase continuation)
+- `Lit` vs `LitSort` (boundary: `S`, capital — actually qualifies; this case becomes prefix-base, deliberate)
+
+If multiple branches are mutual prefixes (impossible by definition) or if no branch is a prefix-of-all-others, fall back to alphabetical-first by `mod_id`.
+
+Rule B still emits the `auto-picked-branch` warning (Spec A §4) and renders the click-to-expand picker buttons — the only behavior change is the choice of which branch wins the auto-pick.
+
+### §4.5 Rule C — input cross-reference *(solves Jeeve's Patches)*
+
+For each ambiguous branch whose mod_id matches the pattern `<base>_<TOKEN>` (i.e., contains an underscore, with a base prefix shared with at least one sibling branch):
+
+1. Extract `<TOKEN>` (the part after the last `_`).
+2. Look up `<TOKEN>` against the resolved mod_id set from the user's input — case-insensitive substring match against any cached `mod_parsed.mod_id` whose wsid is in the user's input.
+3. Match requires `<TOKEN>` length ≥ 3 (avoid `_a`, `_x` false positives).
+
+**Hit:** pre-tick that branch alongside the base branch.
+**No hits on any suffix-tokened branch:** tick the base branch only and emit `unmatched-addons` warning listing the unticked branches by name.
+
+The "base branch" inside a Rule-C wsid is determined by Rule B (prefix-base tiebreaker), with alphabetical fallback.
+
+**Worked example: Jeeve's Patches** (wsid 3684025083, branches `JeevesPatches`, `JeevesPatches_AZ`, `JeevesPatches_DAMN`, `JeevesPatches_GGS`, `JeevesPatches_ISA`, `JeevesPatches_PlayerStatus`, `JeevesPatches_Spongie`, `JeevesPatches_Tanker`, `JeevesPatches_Towing`, `JeevesPatches_Vanilla`, `JeevesPatches_ZRE`):
+- Base = `JeevesPatches` (Rule B: prefix-of-others).
+- Tokens: `AZ`, `DAMN`, `GGS`, `ISA`, `PlayerStatus`, `Spongie`, `Tanker`, `Towing`, `Vanilla`, `ZRE`.
+- User submits `AuthenticZ`-related wsids → some cached mod_id contains `AZ` (case-insensitive substring) → tick `JeevesPatches_AZ`.
+- User submits `JeevesIntegration` → no token hits → tick `JeevesPatches` only, emit `unmatched-addons` warning.
+
+### §4.6 Rules D + G — hint text only
+
+When the picker renders an ambiguous wsid's branches, attach a per-branch `hint` field surfaced in the picker row. **No state mutation.** Hints are:
+
+| Suffix pattern | Hint text |
+|---|---|
+| `_Lite`, `_Light` | "lighter alternate variant — pick one" |
+| `_HD`, `_DetailsHD` | "high-resolution variant" |
+| `_NoCE`, `_NoVanilla`, `_FarmDisable`, `_Disable*` | "opt-out variant" |
+| `_USDM`, `_Imports`, `_Exotics`, `_RealNames` | "alternate variant — pick one" |
+| `_v\d+(_\d+)*`, `_legacy_*` | "legacy build — usually not what you want" |
+| `_AZ`, `_DAMN`, `_GGS`, etc. (Rule C suffixes that didn't match input) | "addon for `<TOKEN>` — only if you have it" |
+
+Pattern matching is case-insensitive with anchored end-of-string for short tags. Multiple hints on one branch concatenate with " · ".
+
+### §4.7 Edge cases
+
+**A and C both fire and disagree** (build hint says B42, input cross-ref says addon `_AZ`): both tick. Build × addon are orthogonal axes; they don't compete for the same slot.
+
+**A says no match (build-mismatch), C also fires:** C still fires; the build-mismatch warning surfaces alongside C's selections. Rule A's "fall back to author default" doesn't override C.
+
+**Coordinated wsid where one branch happens to be B42-flavored and another B41-flavored:** the wsid is exempt from A/B/C (coordinated detection runs first). All branches stay regardless of build mismatch. This is the right answer because coordinated branches by definition need each other.
+
+**Stored selections** in localStorage from previous sessions: the existing `runResort(branchSelections)` flow fires *after* the initial sort response is rendered. User's stored selections override the rules. Rules only determine the initial render's pre-ticked state for never-touched wsids.
+
+**`pz_build` missing or invalid in request:** backend treats as `"B42"`. Forwards-compatible if frontend on a stale build doesn't send it.
+
+## §5 Implementation notes
+
+**Backend** (`adapters.py` + `app.py`):
+- `SortRequest` gains `pz_build: Optional[str]`.
+- `_autopick_ambiguous(mods)` is renamed `_apply_branch_rules(mods, *, pz_build, input_modids)` and replaces the alphabetical-first picker with the rule pipeline above.
+- Returns `(drop_ids, warnings, hints)` — `hints` is `Dict[mod_id -> str]` consumed by `build_response` and attached to MOD_DB entries as `hint?: string`.
+- `sort_endpoint` computes `input_modids = set(by_id.keys())` (the cached mod_ids) and passes alongside `pz_build`.
+
+**Frontend** (`sortof-app.jsx`):
+- `onSort` POST body adds `pz_build: pzBuild`.
+- `defaultSelectionForBranches(branches, activeSet)` accepts an `activeSet: Set<modId>` (the union of `D.SORTED_ORDER` mod_ids). Returns `branches.filter(b => activeSet.has(b.modId)).map(b => b.modId)`, falling back to `[branches[0].modId]` if none match.
+- All call sites of `defaultSelectionForBranches` pass `new Set(D.SORTED_ORDER || [])`.
+- `BranchPicker` renders `branch.hint` when present, as a small italic line under the mod_id.
+
+The frontend doesn't reimplement the rules — it simply reflects the backend's chosen `SORTED_ORDER`. Same data path keeps the picker as source of truth and makes the rules introspectable from a curl response.
+
+## §6 Acceptance criteria
+
+- [ ] `POST /api/sort` accepts `pz_build` and defaults to `"B42"` when omitted.
+- [ ] B42 user submits a wsid with branches `Foo` (un-flavored) and `FooB41`: `MODS_LINE` includes `Foo` only. B41 user gets `FooB41`.
+- [ ] User submits Jeeve's Patches wsid alone: `MODS_LINE` is `JeevesPatches`. WARNINGS includes `unmatched-addons` listing the 10 untouched branches.
+- [ ] User submits Jeeve's Patches + a wsid whose mod_id is `AuthenticZ_Current`: `MODS_LINE` includes `JeevesPatches` and `JeevesPatches_AZ`.
+- [ ] Wsid `1962761540` (`ArmoredVests`, `ArmoredVestsPatch`): auto-pick selects `ArmoredVests` (prefix-base), not alphabetical-first (which is the same here — pick a wsid where they differ to verify).
+- [ ] Coordinated wsid `2791656602` (fhqMotoriusZone): all 5 branches stay in `MODS_LINE` regardless of `pz_build`.
+- [ ] Picker UI shows hint text per branch for D/G-class suffixes.
+- [ ] `WORKSHOP_ITEMS_LINE` matches `wsids[]` regardless of which branches got ticked (Spec A §8 unchanged).
+
+## §7 Test recipes
+
+1. **Build A — B42 default.** `pz_build=B42` + wsid with branches `[Foo, FooB41]`. Expect `MODS_LINE = "Foo"`, no `build-mismatch` warning.
+2. **Build A — B41 + only-B42-variants → mismatch warning.** `pz_build=B41` + wsid where every branch is B42-flavored. Expect `build-mismatch` warning, fall through to Rule B.
+3. **Rule C — Jeeve's alone.** Submit only Jeeve's Patches wsid. Expect MODS_LINE = `JeevesPatches`, `unmatched-addons` warning lists the 10 others.
+4. **Rule C — Jeeve's + AuthenticZ.** Submit Jeeve's wsid + AuthenticZ wsid. Expect MODS_LINE includes `JeevesPatches` and `JeevesPatches_AZ`.
+5. **Rule B — prefix-base picks non-alphabetical.** Find a wsid where alphabetical-first ≠ prefix-base; verify prefix-base wins.
+6. **Hint text — `_Lite` / `_legacy_*`.** Picker row shows the appropriate hint string.
+7. **Coordinated exemption.** fhqMotoriusZone: all 5 branches in MODS_LINE for both B41 and B42 users.
+8. **Stored-selection override.** User has `branchSelections[wsid] = [explicit]` from previous session. Rules don't override on next sort — runResort runs with the explicit selection after initial render.
diff --git a/docs/specs/2026-05-01-collection-expansion.md b/docs/specs/2026-05-01-collection-expansion.md
new file mode 100644
index 0000000..c219c27
--- /dev/null
+++ b/docs/specs/2026-05-01-collection-expansion.md
@@ -0,0 +1,270 @@
+# Spec B+F - Collection URL/ID expansion + live drain progress
+
+**Date:** 2026-05-01
+**Status:** Draft (awaiting review)
+**Sibling specs:** A multi-branch picker (shipped); C+D build-context + dep-add (next); E precacher (parallel); G cleanups + patch tier.
+**Folds:** Original Spec F (live drain progress) merges in here - a 50+ mod cold load is exactly when live counters matter, and both features share the polling endpoint.
+
+**Schema notes (corrections to design source text):**
+- `download_jobs.status` enum is `queued | downloading | done | failed`. The design text used `running`; this spec uses the actual value `downloading`. UX label may render as "draining" for cohesion with the lifecycle vocabulary; the SQL keys off `downloading`.
+- The existing `collections` table (`init/01_schema.sql`) has columns `collection_id PK, title, child_workshop_ids TEXT[], last_fetched_at TIMESTAMPTZ`. There is **no `expires_at` column**. TTL is computed at read time as `last_fetched_at + interval '6 hours'`; no schema change for that.
+
+---
+
+## §1 Overview
+
+Today, sortof accepts one input shape: a blob of newline/`;`-delimited workshop IDs. Anything that isn't a 7–12 digit number is dropped by `parse.parse_workshop_input`. Pasting a Steam Workshop *collection* URL, of which there is exactly one ID embedded, currently surfaces that ID as a single mod, fails parse (`process_one=no_mod_info`), and lands in the `non_mod` bucket added by the recent unknown/non-mod feature. The user is expected to drag every child mod's ID out by hand.
+
+This spec adds:
+1. **Collection URL/ID expansion.** The API recognizes Steam Workshop URLs and resolves collection IDs to their child wsids via `ISteamRemoteStorage/GetCollectionDetails`. Cached in the existing `collections` table.
+2. **Async job pipeline.** Any input containing a collection or any uncached wsid creates a `sort_jobs` row, returns a `job_id`, and the frontend polls `GET /api/jobs/{job_id}` every 2.5s until `done|failed`.
+3. **Live counters.** During `expanding | queued | draining`, the poll response carries fresh `cached / queued / draining` counts plus an incremental `result_json`. The status strip animates instead of going stale.
+
+Synchronous response is preserved for the all-cached fast path (Open Q1, §10).
+
+## §2 API contract
+
+### 2.1 `POST /api/sort` - polymorphic on input
+
+Request body unchanged: `{ "input": str, "rules": str? }`. Response shape branches on what's in `input`:
+
+```jsonc
+// Path A: bare wsid list, all in cache (current behavior, unchanged)
+{ "status": "success", "MOD_DB": [...], "MODS_LINE": "...", ... }
+
+// Path B: bare wsid list with ≥1 uncached, OR ≥1 collection URL
+{ "status": "queued" | "expanding", "job_id": "<uuid>" }
+```
+
+The frontend branches on the presence of `job_id`. Old clients that don't poll silently get the original sync response when their input is fully warm.
+
+### 2.2 `GET /api/jobs/{job_id}` - polling endpoint
+
+Response (any phase):
+```jsonc
+{
+  "job_id": "<uuid>",
+  "phase":  "expanding" | "queued" | "draining" | "done" | "failed",
+  "counts": { "cached": int, "queued": int, "draining": int },
+  "wsids":  [str, ...] | null,        // null while phase=expanding; populated after
+  "result": { ...SORTOF_DATA... } | null,   // partial during draining; final on done
+  "failure_reason": str | null         // populated only on phase=failed
+}
+```
+
+`404` if the `job_id` is unknown or expired (TTL in §3).
+
+### 2.3 `DELETE /api/jobs/{job_id}` - cancel
+
+Marks the job `failed` with `failure_reason="cancelled"`. Returns `204`. Idempotent: deleting an already-terminal job is a no-op `204`. Does **not** cancel underlying `download_jobs` rows (Open Q6, §10).
+
+## §3 Schema
+
+New table:
+
+```sql
+CREATE TABLE IF NOT EXISTS sort_jobs (
+    job_id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    phase            TEXT NOT NULL CHECK (phase IN ('expanding','queued','draining','done','failed')),
+    phase_started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
+    input_raw        TEXT NOT NULL,
+    collection_ids   TEXT[] NOT NULL DEFAULT '{}',
+    wsids            TEXT[],                              -- null until expansion resolves
+    rules_raw        TEXT,
+    result_json      JSONB,                               -- null until done (incremental partials kept here too)
+    failure_reason   TEXT
+);
+CREATE INDEX IF NOT EXISTS sort_jobs_phase_idx ON sort_jobs (phase);
+CREATE INDEX IF NOT EXISTS sort_jobs_updated_idx ON sort_jobs (updated_at);
+```
+
+- **TTL:** rows older than `updated_at + 24h` AND `phase ∈ (done, failed)` are eligible for deletion. Cleanup script lives in Spec G; this spec only requires the schema support it.
+- **`updated_at` trigger:** mirror the existing `download_jobs.touch_updated_at` pattern.
+- **Migration plan:** `init/02_sort_jobs.sql` for fresh deploys + a one-shot `psql -f` for the live DB. No data migration; pure additive.
+
+The existing `collections` table is reused as-is (4 columns, see corrections at top). No `expires_at` column; freshness derived from `last_fetched_at`.
+
+## §4 Phase state machine
+
+```
+                    ┌──────────────────────────────────┐
+                    │ /api/sort with collections only  │
+                    ▼                                   │
+          ┌──────────────┐  GetCollectionDetails OK    │
+          │  expanding   │ ────────────────────────────┘
+          └──────┬───────┘
+                 │ wsids = collections + bare ids
+                 ▼
+          ┌──────────────┐  ←── /api/sort with bare uncached wsids
+          │   queued     │ ─────────── all wsids in mod_parsed (skip drain)
+          └──────┬───────┘                              │
+                 │ first download_jobs row → downloading
+                 ▼                                       │
+          ┌──────────────┐                               │
+          │   draining   │                               │
+          └──────┬───────┘                               │
+                 │ all wsids resolved (mod_parsed has rows)
+                 │                                       │
+                 ▼                                       ▼
+          ┌──────────────┐               ┌──────────────┐
+          │     done     │               │     done     │
+          └──────────────┘               └──────────────┘
+
+Failure terminal at any phase: failed (with phase_at_failure stored in failure_reason prefix).
+```
+
+Phase transitions are **monotonic**: `expanding → queued → draining → done`. No backward transitions. A job's phase only advances; the API computes phase fresh on each `GET` rather than mutating it on every event (simpler, no leader needed).
+
+Phase computation rule (executed inside `GET /api/jobs/{job_id}`):
+
+```
+if phase in (done, failed):           return as-stored
+if wsids is null:                     phase = expanding
+elif counts.draining > 0:             phase = draining
+elif counts.queued > 0:                phase = queued
+elif counts.cached >= len(wsids):     phase = done; persist result_json
+else:                                 phase = queued      # transient gap between rows
+```
+
+## §5 Steam expansion
+
+### 5.1 Detection
+The current `parse.parse_workshop_input` strips ini-style prefixes and extracts `\b\d{7,12}\b`. We add a sibling `parse.parse_with_collections(text) -> (wsids: list, collection_ids: list)`:
+
+- Match Steam URLs `https?://steamcommunity\.com/(?:sharedfiles|workshop)/filedetails/\?id=(\d{7,12})` and capture the ID.
+- Bare numeric IDs (the existing pattern) remain `wsids`.
+- A URL-form ID is classified as a *candidate collection*. We don't know syntactically whether a wsid is a collection vs a mod - so candidate collection IDs are sent to `GetCollectionDetails` first; if the API reports them as actual mods (not collections), they fall back to the wsids list.
+
+### 5.2 Resolution
+Single batched call per `/api/sort` with ≥1 candidate:
+
+```
+POST https://api.steampowered.com/ISteamRemoteStorage/GetCollectionDetails/v1/
+  collectioncount=N
+  publishedfileids[0..N-1]=...
+```
+
+Per-collection in the response: `result==1` and `children[]` populated → expand to `[c.publishedfileid for c in children]`. `result!=1` → mark in result warnings as `{tag:"collection-partial", level:"warning", msg:"collection X could not be fetched"}`; keep the job alive with whatever resolved. (Open Q3, §10.)
+
+### 5.3 Caching
+Hit on `collections` row where `last_fetched_at > now() - interval '6 hours'`:
+- Skip the API call entirely.
+- Use cached `child_workshop_ids` directly.
+
+Miss / stale → call API, UPSERT into `collections`, then proceed. The `last_fetched_at = now()` write is the cache write.
+
+### 5.4 Flakiness
+One internal retry with 2s backoff on HTTP error or `result!=1` for a candidate. After retries exhausted, the candidate is reported as collection-partial (warning) but the job continues with whatever else resolved. (Open Q4, §10.)
+
+## §6 Counts contract
+
+Computed live on every `GET /api/jobs/{job_id}` against the job's `wsids[]`:
+
+```sql
+-- counts.cached
+SELECT COUNT(DISTINCT mp.workshop_id)
+  FROM mod_parsed mp
+  JOIN workshop_meta wm ON wm.workshop_id = mp.workshop_id
+ WHERE mp.workshop_id = ANY($1::text[])
+   AND mp.parsed_at_time_updated = wm.time_updated;
+
+-- counts.queued
+SELECT COUNT(DISTINCT workshop_id)
+  FROM download_jobs
+ WHERE workshop_id = ANY($1::text[]) AND status = 'queued';
+
+-- counts.draining   (status='downloading' in DB; surfaced as 'draining' in API/UI)
+SELECT COUNT(DISTINCT workshop_id)
+  FROM download_jobs
+ WHERE workshop_id = ANY($1::text[]) AND status = 'downloading';
+```
+
+Ownership precedent (Spec A §8): once a job is created, `wsids[]` is **locked**. `WORKSHOP_ITEMS_LINE` in the final `result_json` is computed from `sort_jobs.wsids[]`, **not** recomputed against current `mod_parsed`. This means a wsid that was in the input but is currently `non_mod` or `unknown` still appears in `WORKSHOP_ITEMS_LINE` in the same position - matching the locked contract from Spec A.
+
+## §7 Frontend behavior
+
+Status strip during polling:
+
+| Phase | Strip text |
+|---|---|
+| `expanding` | `expanding collection…` (animated dot, no counts visible) |
+| `queued` | `X cached · Y queued · 0 draining` (animated dots on queued) |
+| `draining` | `X cached · Y queued · Z draining` (animated dots on queued + draining) |
+| `done` | strip collapses, full result rendered |
+| `failed` | red banner with `failure_reason` + Retry button |
+
+Polling: `setInterval` at 2.5s, started on receiving `job_id`. Stops on `phase ∈ (done, failed)`. On `404` (job expired/garbage-collected): show "this job expired - re-submit?" toast; offer one-click resubmit using cached input (the textarea is still populated).
+
+Cancel button: shown during `expanding | queued | draining`. Issues `DELETE /api/jobs/{job_id}`, stops polling on success, clears the strip.
+
+The synchronous code path (no `job_id` in response) renders unchanged - old picker behavior, immediate result.
+
+Owned-fields contract (Spec A §8 precedent): `WORKSHOP_ITEMS_LINE`, `counts.queued` (the picker's internal counter), `unknown[]`, `non_mod[]` are still owned by the **first** `/api/sort` (or final `result_json`). `/api/resort` ignores them. The poll's `counts` object is purely the live drain progress and does not feed the picker's internal queued counter.
+
+## §8 Cancellation
+
+`DELETE /api/jobs/{job_id}` semantics:
+
+- Marks `sort_jobs.phase = 'failed'`, `failure_reason = 'cancelled'`. Idempotent.
+- **Does not** touch `download_jobs`. Workshop downloads in flight continue and populate `mod_parsed`, benefiting subsequent users via cache. Aborting them would waste partial progress and potentially trip the drain's `STALE_RECLAIM_MIN` reclaim path. (Open Q6, §10.)
+- Frontend stops polling, hides the strip, shows a small "cancelled" toast. The textarea retains the input.
+
+Re-submitting the same input after cancel creates a *new* job. Collection-cache hits make the second submission instant if the cache hasn't expired.
+
+## §9 Restart resilience
+
+uvicorn boot sweep (idempotent, runs in lifespan startup):
+
+```sql
+-- Time out long-stuck expansion jobs
+UPDATE sort_jobs
+   SET phase = 'failed', failure_reason = 'expansion timed out',
+       updated_at = now()
+ WHERE phase = 'expanding'
+   AND phase_started_at < now() - interval '10 minutes';
+```
+
+Jobs in `queued` / `draining` need no special handling - they resume polling against `download_jobs` on the next client `GET`. The phase derives live from current counts (§4 phase computation rule), so a restart in the middle of a drain is invisible to the client beyond a brief window where counts may shift.
+
+## §10 Open questions resolved
+
+1. **Bare wsid + all-cached: synchronous or job-routed?** *Synchronous.* The cached path is sub-100ms today; routing it through a job adds polling latency and a UI flash. Frontend branches cheaply on `job_id` presence.
+2. **Mixed input (bare wsids + collection URLs).** *Treat as collection input.* Job created in `expanding` phase immediately. Bare wsids merge into `wsids[]` after `GetCollectionDetails` resolves. No partial-sync hybrid - keeps the response shape rule clean.
+3. **Partial expansion failure.** *Succeed with the resolvable subset.* Each unresolvable collection adds a warning `{tag:"collection-partial", level:"warning", msg:"collection X could not be fetched"}` to `result_json.WARNINGS`. Job completes normally; user sees the result with one or more amber warnings.
+4. **`GetCollectionDetails` flakiness.** *One internal retry with 2s backoff* before reporting collection-partial. No frontend-driven retry on the GET poll - it would mask transient failures and give the user no recovery affordance. Job marked `failed` only if **every** candidate collection fails.
+5. **Concurrent expansion of the same collection.** *Independent jobs; cache deduplicates.* User A and User B paste the same collection URL near-simultaneously; both create separate `sort_jobs` rows. The first one's `GetCollectionDetails` call populates `collections`; the second's hits cache. Worst case (race within the cache miss window) costs one duplicate API call. In-flight cache key (e.g., `collections.fetching_until`) deferred to Spec G.
+6. **Cancel semantics.** *Abandon `sort_job`; leave `download_jobs` running.* Three reasons. (a) Workshop downloads benefit other users via the shared `mod_parsed` cache - wasting them is anti-social. (b) The drain's `STALE_RECLAIM_MIN=30` reclaim path treats half-killed `downloading` rows as candidates for retry; introducing client-driven cancellation creates a class of races where the row is killed mid-write. (c) Worker-side cancellation requires SIGTERM-of-DD-subprocess plumbing that doesn't exist; staying out of that codepath is much cheaper.
+
+## §11 Acceptance criteria
+
+- [ ] `POST /api/sort` with all-cached bare wsids returns the synchronous shape with no `job_id`.
+- [ ] `POST /api/sort` with any uncached wsid OR any collection URL returns `{status, job_id}` and persists a `sort_jobs` row.
+- [ ] `GET /api/jobs/{job_id}` returns live counts and the current phase per the §4 derivation rule.
+- [ ] `GET /api/jobs/{nonexistent}` returns `404`.
+- [ ] `DELETE /api/jobs/{job_id}` flips phase to `failed` with `failure_reason="cancelled"`. Idempotent.
+- [ ] Collection URL `https://steamcommunity.com/sharedfiles/filedetails/?id=N` is detected by the parser and routed through `GetCollectionDetails`.
+- [ ] A `collections` cache hit (row younger than 6h) skips the Steam API call.
+- [ ] A collection that returns `result!=1` produces a `collection-partial` amber warning in `result_json.WARNINGS` but does not fail the job (unless **all** collections in the input are unresolvable).
+- [ ] uvicorn restart with a job in `expanding > 10min` flips it to `failed` with `failure_reason="expansion timed out"`.
+- [ ] uvicorn restart with a job in `queued`/`draining` is invisible to the client beyond next-poll-window jitter.
+- [ ] Frontend polls every 2.5s when `phase ∈ (expanding, queued, draining)`; stops on terminal phase.
+- [ ] Status strip text matches the §7 table for each phase.
+- [ ] Cancel button issues `DELETE`, stops polling, hides strip, retains input in textarea.
+- [ ] `WORKSHOP_ITEMS_LINE` in `result_json` matches `sort_jobs.wsids[]` regardless of which wsids ended up in `non_mod` / `unknown` (Spec A §8 ownership preserved).
+
+## §12 Test recipes
+
+1. **Synchronous fast path** - `POST /api/sort` with `{"input":"2169435993;2392709985;2487022075"}`. Expect: response has `MODS_LINE`, no `job_id`. ~50ms.
+2. **Collection URL, cold cache** - clear `collections` row for the test ID; `POST /api/sort` with a known PZ collection URL. Expect: `{status:"expanding", job_id:"…"}` immediately. Poll: phase progresses `expanding → queued → draining → done`. Final `result.MODS_LINE` populated.
+3. **Collection URL, warm cache** - re-submit the same URL within 6h. Expect: phase skips `expanding`, goes straight to `queued` (or `done` if all children cached). One Steam API call total across both runs (verify via `/var/log/...` or `journalctl -u sortof-api | grep GetCollectionDetails`).
+4. **Mixed bare + collection** - `POST /api/sort` with `"<URL>\n2169435993"`. Expect: job created in `expanding`; on resolve, `wsids[]` contains both the collection's children and the bare wsid; deduped.
+5. **Partial collection failure** - input contains two collection URLs, one valid, one to a deleted collection. Expect: job phase progresses normally; `result_json.WARNINGS` contains exactly one `collection-partial` entry; `wsids[]` contains only the valid collection's children.
+6. **All collections fail** - input contains only unresolvable collection URLs. Expect: job `phase=failed`, `failure_reason="all input collections unresolvable"`.
+7. **Cancel during draining** - submit a 50-mod cold collection, wait until `phase=draining`, `DELETE /api/jobs/{id}`. Expect: phase=failed reason=cancelled. Verify `download_jobs` rows for the wsids are still in `queued`/`downloading`/`done` (not nuked).
+8. **Restart mid-drain** - submit a job, wait for `phase=draining`, `sudo systemctl restart sortof-api`. Wait 5s, GET the job. Expect: phase still derives correctly (computed from live counts), client polling resumes.
+9. **Restart mid-expansion** - submit a collection job, kill `sortof-api` mid-expansion (race window: hard to hit deliberately; can simulate by directly SET `phase='expanding', phase_started_at=now()-interval '15 minutes'` then restart). Expect: lifespan sweep flips it to `failed` with `failure_reason="expansion timed out"`.
+10. **404 on expired job** - manually `DELETE FROM sort_jobs WHERE job_id=…`; client poll. Expect: `404`. Frontend shows the expired-toast with re-submit affordance.
+11. **Counts contract** - at each poll during a 50-mod cold drain, sum `counts.cached + counts.queued + counts.draining` and compare to `len(wsids)`. Equal at every snapshot. (Some wsids may be `non_mod` post-drain; they appear in `cached=0, queued=0, draining=0` because `mod_parsed` has no row - they're "missing from all three buckets," which is the expected steady state for non-mods.)
+12. **Concurrent collection submit** - open two browser tabs simultaneously and submit the same URL. Expect: two distinct `job_id`s, but only one `GetCollectionDetails` call lands at Steam (verify journal). Worst case (cache-miss race): two API calls; this is acceptable.
diff --git a/frontend/img/broccoli_shadow_square.png b/frontend/img/broccoli_shadow_square.png
new file mode 100644
index 0000000..6486ef1
Binary files /dev/null and b/frontend/img/broccoli_shadow_square.png differ
diff --git a/frontend/img/ketchup_bottle.png b/frontend/img/ketchup_bottle.png
new file mode 100644
index 0000000..b50b2fd
Binary files /dev/null and b/frontend/img/ketchup_bottle.png differ
diff --git a/frontend/img/ketchup_bottle.svg b/frontend/img/ketchup_bottle.svg
new file mode 100644
index 0000000..e37cf98
--- /dev/null
+++ b/frontend/img/ketchup_bottle.svg
@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect x="22" y="6" width="20" height="8" rx="1.5" fill="#F2E6CC"/>
+  <rect x="24" y="14" width="16" height="4" fill="#F2E6CC"/>
+  <path d="M22 18 Q20 22 20 28 L20 54 Q20 58 24 58 L40 58 Q44 58 44 54 L44 28 Q44 22 42 18 Z" fill="#D43028"/>
+  <rect x="25" y="34" width="14" height="11" rx="1.5" fill="#F2E6CC"/>
+  <circle cx="29" cy="38" r="0.9" fill="#0A141E"/>
+  <circle cx="35" cy="38" r="0.9" fill="#0A141E"/>
+  <rect x="30" y="41.4" width="4" height="0.9" rx="0.4" fill="#0A141E"/>
+</svg>
diff --git a/frontend/index.html b/frontend/index.html
new file mode 100644
index 0000000..5aad434
--- /dev/null
+++ b/frontend/index.html
@@ -0,0 +1,1433 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width,initial-scale=1" />
+<title>sortof (:|) sorted. or close enough.</title>
+<link rel="icon" type="image/svg+xml" href="/img/ketchup_bottle.svg">
+<link rel="alternate icon" type="image/png" href="/img/ketchup_bottle.png">
+<link rel="apple-touch-icon" href="/img/ketchup_bottle.png">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<!-- Sora used throughout per brief; JetBrains Mono only for code/output blocks. -->
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Sora:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap">
+<style>
+  /* ─── tokens ─────────────────────────────────────────────── */
+  :root {
+    /* ─── LOCKED PALETTE — Indifferent Ketchup brief 2026-05-01 ─── */
+    --bg:           #0A141E;
+    --bg-surface:   #14293C;
+    --bg-elevated:  #1B3550;
+    --border:       #2A4A6B;
+    --fg:           #FFFFFF;
+    --fg-muted:     #A3B8CC;
+
+    /* Brand color matches the ketchup bottle: vivid red, comparable punch
+     * to the previous neon green. --brand-ink stays dark for AA contrast
+     * on the red fill. */
+    --brand:        #FF3838;       /* IK ketchup red */
+    --brand-ink:    #0A141E;
+    --brand-hover:  #E62E2E;
+
+    --secondary:    #0050FF;       /* IK blue accent */
+    --secondary-ink: #FFFFFF;
+
+    --info:         #56B4E9;       --info-ink:    #0A141E;
+    --success:      var(--brand);   --success-ink: var(--brand-ink);
+    --warning:      #E69F00;       --warning-ink: #0A141E;
+    /* --error: brief specified #D55E00, lifted to #E97515 — same hue ~30°,
+     * higher luminance — so pill text on --bg-surface clears WCAG AA
+     * (#D55E00 was 3.85:1, fails 4.5:1; #E97515 is 4.62:1). Hue preserved
+     * per brief rule "Adjust luminance, not hue, if a token fails." */
+    --error:        #E97515;       --error-ink:   #FFFFFF;
+
+    --focus-ring:   #56B4E9;       /* same as --info per brief */
+
+    /* Surface variants of state colors (12-16% alpha) for chip backgrounds. */
+    --info-bg:      rgb(86 180 233 / 0.14);
+    --success-bg:   rgb(255 56 56 / 0.14);    /* matches new --brand (#FF3838) */
+    --warning-bg:   rgb(230 159 0 / 0.14);
+    --error-bg:     rgb(233 117 21 / 0.16);
+
+    /* ─── Aliases — old token names map to the core palette so existing
+     * component CSS keeps working without selector-by-selector edits. */
+    --bg-panel:     var(--bg-surface);
+    --bg-1:         var(--bg-surface);
+    --bg-2:         var(--bg-surface);
+    --bg-3:         var(--bg-surface);
+    --bg-hi:        var(--bg-elevated);
+    --line:         var(--border);
+    --line-2:       var(--border);
+    --fg-1:         var(--fg);
+    --fg-2:         var(--fg-muted);
+    --fg-3:         var(--fg-muted);
+
+    --acc-success:    var(--success);
+    --acc-warn:       var(--warning);
+    --acc-error:      var(--error);
+    --acc-info:       var(--info);
+    --acc-success-bg: var(--success-bg);
+    --acc-warn-bg:    var(--warning-bg);
+    --acc-error-bg:   var(--error-bg);
+    --acc-info-bg:    var(--info-bg);
+
+    --acc-green:    var(--success);
+    --acc-amber:    var(--warning);
+    --acc-red:      var(--error);
+    --acc-blue:     var(--info);
+    --acc-green-bg: var(--success-bg);
+    --acc-amber-bg: var(--warning-bg);
+    --acc-red-bg:   var(--error-bg);
+    --acc-blue-bg:  var(--info-bg);
+
+    --brand-primary:    var(--brand);
+    --brand-primary-bg: rgb(255 56 56 / 0.14);
+    --brand-anchor-bg:  var(--brand-ink);
+    --brand-shadow-card: 0 4px 12px rgba(0, 0, 0, 0.45);
+
+    --radius: 8px;
+    --radius-sm: 4px;
+    --radius-lg: 12px;
+    --pad-x: clamp(20px, 4vw, 40px);
+
+    --mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+    /* Sora throughout per brief 2026-05-02. Display + body share the same
+     * stack; weight differs by role. */
+    --display: 'Sora', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+    --sans:    'Sora', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+  }
+
+  *, *::before, *::after { box-sizing: border-box; }
+  html, body { margin: 0; padding: 0; }
+  body {
+    font-family: var(--sans);
+    background: var(--bg);
+    color: var(--fg);
+    font-size: 16px;
+    line-height: 1.55;
+    -webkit-font-smoothing: antialiased;
+    text-rendering: optimizeLegibility;
+    font-feature-settings: "ss01", "cv11";
+  }
+  ::selection { background: rgb(86 180 233 / 0.35); }   /* --info @ 35% */
+
+  /* Always-visible focus ring on every interactive element, keyboard-only
+   * by default. Pointer-driven focus is suppressed by :focus-visible. */
+  :focus { outline: none; }
+  :focus-visible {
+    outline: 2px solid var(--focus-ring);
+    outline-offset: 2px;
+    border-radius: 4px;
+  }
+
+  a {
+    color: var(--acc-info);
+    text-decoration: underline;
+    text-decoration-thickness: 1px;
+    text-underline-offset: 2px;
+  }
+  a:hover { color: var(--fg); text-decoration-thickness: 2px; }
+
+  /* ─── header / footer ─── */
+  .shell {
+    min-height: 100vh;
+    display: grid;
+    grid-template-rows: auto 1fr auto;
+  }
+  header.app {
+    border-bottom: 1px solid var(--line);
+    padding: 14px var(--pad-x);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 16px;
+  }
+  .brand {
+    display: flex;
+    align-items: center;     /* vertically center the bottle with the wordmark */
+    gap: 12px;
+    min-width: 0;
+  }
+  .wordmark {
+    font-family: var(--display);
+    font-weight: 600;
+    font-size: 22px;
+    letter-spacing: -0.02em;
+    color: var(--fg);
+    line-height: 1;
+  }
+  .wordmark .dot {
+    color: var(--brand);
+  }
+  .brand-mark-link {
+    display: inline-flex;
+    align-items: center;
+    text-decoration: none;
+  }
+  .brand-mark-link:hover { background: transparent; }
+  .brand-mark {
+    width: 40px; height: 40px;
+    object-fit: contain;
+    flex-shrink: 0;
+    display: block;
+    transition: transform .18s ease-out;
+  }
+  .brand-mark-link:hover .brand-mark { transform: rotate(-6deg) scale(1.05); }
+  /* "(:|)" mark next to "indifferent ketchup" footer link. */
+  .ik-mark {
+    font-family: var(--mono);
+    font-weight: 600;
+    letter-spacing: -0.05em;
+    margin-left: 2px;
+  }
+  /* Footer links per brief: brand link in --brand, info link in --info,
+   * both underlined by default. */
+  .footer-link             { text-decoration: underline; text-decoration-thickness: 1px; text-underline-offset: 2px; }
+  .footer-link-brand       { color: var(--brand); }
+  .footer-link-brand:hover { color: var(--brand-hover); }
+  .footer-link-info        { color: var(--info); }
+  .footer-link-info:hover  { color: var(--fg); }
+  /* Tagline ("sorted. sort of.") in --fg-muted, italic per brief. */
+  .tagline {
+    font-family: var(--display);
+    font-style: italic;
+    font-size: 12px;
+    color: var(--fg-muted);
+    line-height: 1;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+  .head-right {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+  }
+  /* Header chrome links (github, docs). Per brief: --fg-muted in Sora 400,
+   * underline on hover only. */
+  .icon-btn {
+    appearance: none;
+    border: 1px solid transparent;
+    background: transparent;
+    color: var(--fg-muted);
+    height: 30px;
+    padding: 0 10px;
+    border-radius: var(--radius-sm);
+    font-family: var(--display);
+    font-weight: 400;
+    font-size: 13px;
+    cursor: pointer;
+    display: inline-flex;
+    align-items: center;
+    gap: 6px;
+    text-decoration: none;
+    transition: color .12s, background .12s;
+  }
+  .icon-btn:hover {
+    color: var(--fg);
+    background: var(--bg-elevated);
+    text-decoration: underline;
+    text-decoration-thickness: 1px;
+    text-underline-offset: 3px;
+  }
+  .icon-btn svg { width: 14px; height: 14px; opacity: .85; }
+  /* Header CTA: distinct accent so the report-broken-mod button reads as an
+   * action, not a docs/github link. Hover ramps to filled brand color. */
+  .icon-btn.report {
+    color: var(--brand);
+    border: 1px solid var(--brand);
+    background: transparent;
+    cursor: pointer;
+    font-family: var(--mono);
+  }
+  .icon-btn.report:hover {
+    background: var(--brand);
+    color: var(--brand-ink);
+    border-color: var(--brand);
+    text-decoration: none;
+  }
+
+  /* ── Reported broken mods view ─────────────────────────────────────── */
+  .reports-panel {
+    display: block;
+    max-width: 1100px;
+    margin: 16px auto;
+    padding: 0 16px;
+  }
+  .reports-head {
+    background: var(--bg-elevated);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: 14px 16px;
+    margin-bottom: 14px;
+  }
+  .reports-title {
+    font-family: var(--display);
+    font-size: 22px;
+    color: var(--fg);
+    margin-bottom: 4px;
+  }
+  .reports-blurb {
+    font-family: var(--mono);
+    font-size: 12px;
+    color: var(--fg-muted);
+    margin-bottom: 12px;
+    line-height: 1.5;
+  }
+  .reports-form {
+    display: flex;
+    gap: 8px;
+    align-items: stretch;
+    flex-wrap: wrap;
+    margin-bottom: 8px;
+  }
+  .reports-form .field {
+    flex: 1 1 220px;
+    min-height: 36px;
+    font-family: var(--mono);
+    font-size: 13px;
+  }
+  .reports-form select.field { flex: 0 0 auto; min-width: 240px; }
+  .reports-form .sort-btn { flex: 0 0 auto; min-width: 120px; }
+  .reports-error {
+    color: var(--error);
+    font-family: var(--mono);
+    font-size: 12px;
+    margin-bottom: 8px;
+  }
+  .reports-search { width: 100%; margin-top: 4px; }
+  .reports-meta {
+    font-family: var(--mono);
+    font-size: 11.5px;
+    color: var(--fg-muted);
+    margin-top: 8px;
+  }
+  .reports-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 6px;
+  }
+  .reports-empty {
+    font-family: var(--mono);
+    font-size: 13px;
+    color: var(--fg-muted);
+    padding: 24px 16px;
+    text-align: center;
+    border: 1px dashed var(--border);
+    border-radius: var(--radius);
+  }
+  /* Each row is a 6-cell grid: name | wsid | version | date | up | down.
+   * Wraps cleanly on narrow viewports — the votes column stays right-anchored. */
+  .report-row {
+    display: grid;
+    grid-template-columns: minmax(0, 1.6fr) 110px 130px 150px auto auto;
+    align-items: center;
+    gap: 10px;
+    padding: 8px 12px;
+    background: var(--bg-surface);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    font-family: var(--mono);
+    font-size: 13px;
+  }
+  .report-row:hover { border-color: var(--line-2); }
+  .report-name {
+    color: var(--fg);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .report-wsid { color: var(--fg-muted); font-size: 12px; }
+  .report-ver .ver-pill {
+    background: var(--bg-panel);
+    color: var(--fg-2);
+    border: 1px solid var(--border);
+    padding: 2px 8px;
+    border-radius: 3px;
+    font-size: 11.5px;
+    white-space: nowrap;
+  }
+  .report-date { color: var(--fg-muted); font-size: 12px; white-space: nowrap; }
+  .report-votes {
+    display: inline-flex;
+    gap: 6px;
+    align-items: center;
+  }
+  .vote-btn {
+    appearance: none;
+    border: 1px solid var(--line-2);
+    background: transparent;
+    color: var(--fg-2);
+    font-family: var(--mono);
+    font-size: 12px;
+    padding: 4px 10px;
+    border-radius: var(--radius);
+    cursor: pointer;
+    transition: color .12s, background .12s, border-color .12s;
+    min-width: 54px;
+  }
+  .vote-btn.up:hover:not([disabled])   { color: var(--success, var(--acc-green)); border-color: var(--success, var(--acc-green)); }
+  .vote-btn.down:hover:not([disabled]) { color: var(--error); border-color: var(--error); }
+  .vote-btn.up.voted   { color: var(--success, var(--acc-green)); border-color: var(--success, var(--acc-green)); background: var(--success-bg, rgba(80,180,120,0.10)); }
+  .vote-btn.down.voted { color: var(--error); border-color: var(--error); background: rgba(220,80,80,0.10); }
+  .vote-btn[disabled]:not(.voted) { opacity: 0.45; cursor: not-allowed; }
+  @media (max-width: 720px) {
+    .report-row {
+      grid-template-columns: 1fr 1fr;
+    }
+    .report-name { grid-column: 1 / -1; }
+    .report-votes { justify-content: flex-end; }
+  }
+
+  footer.app {
+    border-top: 1px solid var(--line);
+    padding: 18px var(--pad-x);
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px 24px;
+    align-items: center;
+    justify-content: space-between;
+    color: var(--fg-2);
+    font-size: 12px;
+    font-family: var(--mono);
+  }
+  footer.app .left, footer.app .right {
+    display: flex; flex-wrap: wrap; gap: 4px 16px; align-items: center;
+  }
+
+  /* ─── main grid ─── */
+  main.app {
+    padding: clamp(20px, 3vw, 32px) var(--pad-x) clamp(32px, 5vw, 56px);
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: 24px;
+    max-width: 1480px;
+    width: 100%;
+    margin: 0 auto;
+  }
+  @media (min-width: 1024px) {
+    main.app {
+      grid-template-columns: minmax(380px, 5fr) minmax(0, 7fr);
+      gap: 28px;
+    }
+  }
+
+  .col {
+    display: flex;
+    flex-direction: column;
+    gap: 16px;
+    min-width: 0;
+  }
+
+  /* ─── shared bits ─── */
+  .label-row {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: 12px;
+    margin-bottom: 6px;
+  }
+  .label {
+    font-family: var(--mono);
+    font-size: 12px;
+    text-transform: lowercase;
+    letter-spacing: 0.02em;
+    color: var(--fg-2);
+  }
+  .label-meta {
+    font-family: var(--mono);
+    font-size: 11.5px;
+    color: var(--fg-2);
+  }
+
+  textarea.field, input.field {
+    width: 100%;
+    background: var(--bg-2);
+    color: var(--fg);
+    border: 1px solid var(--line);
+    border-radius: var(--radius);
+    padding: 12px 14px;
+    font-family: var(--mono);
+    font-size: 13px;
+    line-height: 1.55;
+    resize: vertical;
+    outline: none;
+    transition: border-color .12s, background .12s;
+  }
+  textarea.field:focus, input.field:focus {
+    border-color: var(--focus-ring);
+    background: var(--bg-elevated);
+  }
+  textarea.field:focus-visible, input.field:focus-visible {
+    outline: 2px solid var(--focus-ring);
+    outline-offset: 2px;
+  }
+  textarea.field::placeholder { color: var(--fg-2); }
+
+  .input-main { min-height: 220px; }
+  .input-rules { min-height: 110px; }
+
+  details.collapsible > summary {
+    list-style: none;
+    cursor: pointer;
+    font-family: var(--mono);
+    font-size: 12px;
+    font-weight: 600;
+    color: var(--fg);
+    user-select: none;
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    padding: 5px 12px;
+    border: 1px solid var(--line-2);
+    background: var(--bg-1);
+    border-radius: var(--radius);
+    transition: color .12s, border-color .12s, background .12s;
+  }
+  details.collapsible > summary::-webkit-details-marker { display: none; }
+  details.collapsible > summary::before {
+    content: "▸";
+    color: var(--acc-blue);
+    font-size: 12px;
+    transition: transform .12s;
+    display: inline-block;
+    width: 9px;
+  }
+  details.collapsible[open] > summary::before { transform: rotate(90deg); }
+  details.collapsible > summary:hover {
+    color: var(--acc-blue);
+    border-color: var(--acc-blue);
+    background: var(--acc-blue-bg, rgba(70,140,220,0.10));
+  }
+  details.collapsible[open] > summary { margin-bottom: 8px; }
+
+  /* sort button */
+  /* Sort button = primary CTA. Solid brand fill, dark ink, glyph prefix.
+   * Hover brightens, active darkens, disabled goes flat with a "—" prefix. */
+  .sort-btn {
+    appearance: none;
+    width: 100%;
+    height: 42px;
+    border: 1px solid var(--brand);
+    background: var(--brand);
+    color: var(--brand-ink);
+    border-radius: var(--radius);
+    font-family: var(--display);
+    font-size: 14px;
+    font-weight: 700;
+    letter-spacing: 0.01em;
+    cursor: pointer;
+    transition: filter .12s, transform .04s, box-shadow .12s;
+    display: inline-flex; align-items: center; justify-content: center; gap: 8px;
+  }
+  .sort-btn:hover  {
+    background: var(--brand-hover);
+    border-color: var(--brand-hover);
+    box-shadow: var(--brand-shadow-card);
+  }
+  .sort-btn:active { filter: brightness(0.92); transform: translateY(1px); }
+  .sort-btn[disabled] {
+    cursor: not-allowed;
+    border-color: var(--border);
+    background: var(--bg-surface);
+    color: var(--fg-muted);
+    box-shadow: none;
+    filter: none;
+  }
+  .sort-btn .btn-glyph { font-size: 11px; line-height: 1; display: inline-block; min-width: 11px; text-align: center; }
+
+  /* Clear button — subordinate to sort. Outline-only, --border outline,
+   * --fg text. Hover lifts to --bg-elevated per brief. */
+  .clear-btn {
+    appearance: none;
+    height: 42px;
+    padding: 0 14px;
+    border: 1px solid var(--border);
+    background: transparent;
+    color: var(--fg);
+    border-radius: var(--radius);
+    font-family: var(--display);
+    font-size: 13px;
+    font-weight: 600;
+    letter-spacing: 0.01em;
+    cursor: pointer;
+    display: inline-flex; align-items: center; gap: 8px;
+    transition: background .12s, color .12s, border-color .12s, transform .04s;
+  }
+  .clear-btn:hover  { background: var(--bg-elevated); border-color: var(--fg-muted); }
+  .clear-btn:active { transform: translateY(1px); }
+  .sort-btn .spin {
+    width: 12px; height: 12px;
+    border: 1.5px solid currentColor;
+    border-top-color: transparent;
+    border-radius: 50%;
+    animation: sp 0.7s linear infinite;
+  }
+  @keyframes sp { to { transform: rotate(360deg); } }
+
+  /* status strip */
+  .status-strip {
+    display: flex; flex-wrap: wrap; align-items: center;
+    gap: 4px 12px;
+    font-family: var(--mono);
+    font-size: 11.5px;
+    color: var(--fg-2);
+    padding: 8px 0 0;
+    min-height: 24px;
+  }
+  .status-pill {
+    display: inline-flex; align-items: center; gap: 6px;
+  }
+  /* Glyph carries the state semantically (paired with a text label). The
+   * color reinforces the same meaning for sighted-but-not-CVD users. The
+   * old dot-led is preserved as a generic class for legacy callers; new
+   * pills use status-glyph. */
+  .status-glyph {
+    display: inline-block;
+    min-width: 12px;
+    text-align: center;
+    font-weight: 600;
+    line-height: 1;
+  }
+  .dot-led {
+    width: 6px; height: 6px; border-radius: 50%;
+    background: var(--fg-3);
+  }
+  /* State pill colors - explicit (color × glyph × label) per brief mapping.
+   * Each state gets a distinct hue from the Okabe-Ito palette so no two
+   * states collapse to the same color under deuteranopia/protanopia. */
+  .status-pill.idle      { color: var(--fg-muted); }
+  .status-pill.done      { color: var(--success); }
+  .status-pill.queued    { color: var(--info); }
+  .status-pill.queued    .status-glyph { animation: bl 1.2s ease-in-out infinite; }
+  .status-pill.working,
+  .status-pill.draining  { color: var(--info); }
+  .status-pill.working   .status-glyph,
+  .status-pill.draining  .status-glyph { animation: bl 1.2s ease-in-out infinite; }
+  .status-pill.warning   { color: var(--warning); }
+  .status-pill.failed    { color: var(--error); }
+  .status-pill.muted     { color: var(--fg-muted); }
+  /* Legacy classes (still referenced by some pills + callers) - alias to the
+   * new state colors so old code keeps working. */
+  .status-pill.cached    { color: var(--success); }
+  .status-pill.parse     { color: var(--info); }
+  .status-pill.parse     .status-glyph { animation: bl 1.2s ease-in-out infinite; }
+  .status-pill.unknown   { color: var(--error); }
+  .status-pill.nonmod    { color: var(--fg-muted); }
+  .status-pill.expanding { color: var(--info); }
+  .status-pill.expanding .status-glyph { animation: bl 1.2s ease-in-out infinite; }
+  /* Dot-led background recolor (legacy callers) */
+  .status-pill.done      .dot-led,
+  .status-pill.cached    .dot-led { background: var(--success); }
+  .status-pill.queued    .dot-led,
+  .status-pill.working   .dot-led,
+  .status-pill.draining  .dot-led,
+  .status-pill.parse     .dot-led,
+  .status-pill.expanding .dot-led { background: var(--info); animation: bl 1.2s ease-in-out infinite; }
+  .status-pill.warning   .dot-led { background: var(--warning); }
+  .status-pill.failed    .dot-led,
+  .status-pill.unknown   .dot-led { background: var(--error); }
+  .status-pill.muted     .dot-led,
+  .status-pill.nonmod    .dot-led { background: var(--fg-muted); }
+
+  .cancel-btn {
+    appearance: none;
+    border: 1px solid var(--line);
+    background: transparent;
+    color: var(--fg-2);
+    border-radius: var(--radius);
+    font-family: var(--mono);
+    font-size: 12px;
+    cursor: pointer;
+    transition: color .12s, border-color .12s, background .12s;
+  }
+  .cancel-btn:hover { color: var(--acc-red); border-color: var(--acc-red); background: var(--acc-red-bg); }
+  @keyframes bl { 0%, 100% { opacity: 0.35; } 50% { opacity: 1; } }
+  .progress-bar {
+    flex: 1 1 100%;
+    height: 2px;
+    background: var(--bg-2);
+    border-radius: 1px;
+    overflow: hidden;
+    margin-top: 4px;
+  }
+  .progress-bar > i {
+    display: block;
+    height: 100%;
+    background: var(--acc-blue);
+    transition: width .35s ease;
+  }
+
+  /* card / section panels - IB-style soft drop shadow under the card. */
+  .panel {
+    background: var(--bg-1);
+    border: 1px solid var(--line);
+    border-radius: var(--radius);
+    overflow: hidden;
+    box-shadow: var(--brand-shadow-card);
+  }
+
+  /* code blocks */
+  .code-block {
+    background: var(--bg-1);
+    border: 1px solid var(--line);
+    border-radius: var(--radius);
+    overflow: hidden;
+  }
+  .code-block .cb-head {
+    display: flex; align-items: center; justify-content: space-between;
+    padding: 8px 12px;
+    background: var(--bg-2);
+    border-bottom: 1px solid var(--line);
+    font-family: var(--mono);
+    font-size: 12px;
+    color: var(--fg-2);
+  }
+  .code-block .cb-head .cb-key {
+    color: var(--fg-1);
+    font-weight: 500;
+  }
+  .code-block .cb-head .cb-meta {
+    color: var(--fg-2);
+    font-variant-numeric: tabular-nums;
+  }
+  .code-block pre {
+    margin: 0;
+    padding: 14px 16px;
+    font-family: var(--mono);
+    font-size: 13px;
+    line-height: 1.55;
+    color: var(--fg);
+    white-space: pre-wrap;
+    word-break: break-all;
+    overflow-x: auto;
+    min-height: 44px;
+  }
+  .code-block pre .ink-key { color: var(--acc-blue); }
+  .code-block pre .ink-sep { color: var(--fg-2); }
+  .code-block pre .ink-mut { color: var(--fg-2); }
+
+  .copy-btn {
+    appearance: none;
+    border: 1px solid var(--acc-blue);
+    background: var(--acc-blue-bg, rgba(70,140,220,0.10));
+    color: var(--acc-blue);
+    height: 26px;
+    padding: 0 10px;
+    border-radius: 5px;
+    font-family: var(--mono);
+    font-size: 12px;
+    font-weight: 600;
+    cursor: pointer;
+    display: inline-flex; align-items: center; gap: 6px;
+    transition: color .12s, background .12s, border-color .12s, transform .08s;
+  }
+  .copy-btn:hover { color: var(--brand-ink); background: var(--acc-blue); border-color: var(--acc-blue); }
+  .copy-btn:active { transform: translateY(1px); }
+  .copy-btn.copied { color: var(--acc-green); border-color: var(--acc-green); background: var(--acc-green-bg, rgba(80,180,120,0.12)); }
+  .copy-btn.copied:hover { color: var(--brand-ink); background: var(--acc-green); }
+  .copy-btn svg { width: 11px; height: 11px; }
+
+  /* multi-branch picker (Spec A) */
+  .branch-affordance {
+    appearance: none;
+    border: 1px solid var(--line);
+    background: transparent;
+    color: var(--acc-blue);
+    font-family: var(--mono);
+    font-size: 12px;
+    padding: 1px 6px;
+    border-radius: 3px;
+    cursor: pointer;
+  }
+  .branch-affordance:hover { color: var(--fg); border-color: var(--line-2); background: var(--bg-3); }
+
+  .branch-panel {
+    background: var(--bg-2);
+    border-top: 1px dashed var(--line);
+    border-bottom: 1px dashed var(--line);
+    padding: 0;
+  }
+  .branch-panel-inner {
+    padding: 8px 12px 10px;
+    font-family: var(--mono);
+    font-size: 12px;
+  }
+  .branch-panel-meta { color: var(--fg-2); margin-bottom: 6px; letter-spacing: 0.04em; }
+
+  .branch-row {
+    display: grid;
+    grid-template-columns: 18px 220px 1fr 70px 1fr 60px;
+    gap: 10px 10px;
+    align-items: center;
+    padding: 4px 0;
+    border-top: 1px solid var(--line);
+    cursor: pointer;
+  }
+  .branch-row:hover { background: var(--bg-panel); }
+  /* Picked row: --info per brief, not the brand green (status, not brand). */
+  .branch-row.is-checked .branch-modid { color: var(--info); font-weight: 600; }
+  .branch-input { accent-color: var(--info); }
+  .branch-modid { color: var(--fg); }
+  .branch-name  { color: var(--fg-2); }
+  .branch-deps  { color: var(--fg-2); font-size: 11.5px; }
+  .branch-pos   { color: var(--fg-2); font-size: 11.5px; text-align: right; }
+  /* Spec C §4.6 D/G hint text: italic line under the mod_id row. */
+  .branch-hint  {
+    grid-column: 2 / -1;
+    color: var(--acc-amber);
+    font-size: 11.5px;
+    font-style: italic;
+    margin-top: -2px;
+    padding-bottom: 2px;
+  }
+
+  /* diff panel (Spec follow-up: show what changed since last sort) */
+  .diff-toggle-row { display: flex; justify-content: flex-end; padding: 4px 0 2px; }
+  .diff-toggle {
+    appearance: none;
+    border: 1px solid var(--line-2);
+    background: transparent;
+    color: var(--fg-2);
+    font-family: var(--mono);
+    font-size: 12px;
+    font-weight: 600;
+    padding: 3px 10px;
+    border-radius: var(--radius);
+    cursor: pointer;
+    transition: color .12s, border-color .12s, background .12s;
+  }
+  .diff-toggle:hover:not(:disabled) {
+    color: var(--acc-blue);
+    border-color: var(--acc-blue);
+    background: var(--acc-blue-bg, rgba(70,140,220,0.10));
+  }
+  .diff-toggle.open {
+    color: var(--acc-blue);
+    border-color: var(--acc-blue);
+    background: var(--acc-blue-bg, rgba(70,140,220,0.10));
+  }
+  .diff-toggle:disabled { opacity: 0.4; cursor: not-allowed; }
+  .diff-panel {
+    border: 1px solid var(--line-2);
+    background: var(--bg-1);
+    border-radius: var(--radius);
+    padding: 10px 12px;
+    margin: 4px 0 10px;
+    font-family: var(--mono);
+    font-size: 12px;
+  }
+  .diff-head {
+    display: flex; align-items: center; gap: 10px;
+    padding-bottom: 8px; border-bottom: 1px solid var(--line);
+    margin-bottom: 8px;
+  }
+  .diff-title { color: var(--fg); font-weight: 600; }
+  .diff-summary { display: flex; gap: 6px; margin-left: auto; }
+  .diff-stat { padding: 1px 6px; border-radius: 3px; font-weight: 600; }
+  .diff-stat.add { color: var(--acc-green); background: var(--acc-green-bg, rgba(80,180,120,0.12)); }
+  .diff-stat.rm  { color: var(--acc-red);   background: var(--acc-red-bg,   rgba(220,80,80,0.12)); }
+  .diff-stat.mv  { color: var(--acc-amber); background: var(--acc-amber-bg, rgba(220,160,70,0.12)); }
+  .diff-close {
+    appearance: none;
+    border: 1px solid var(--line);
+    background: transparent;
+    color: var(--fg-2);
+    font-family: var(--mono);
+    font-size: 11.5px;
+    padding: 2px 8px;
+    border-radius: 4px;
+    cursor: pointer;
+  }
+  .diff-close:hover { color: var(--fg); border-color: var(--line-2); }
+  .diff-section { padding: 6px 0; }
+  .diff-label { color: var(--fg-2); font-size: 11.5px; text-transform: uppercase; letter-spacing: .04em; padding-bottom: 4px; }
+  .diff-row {
+    padding: 2px 0; display: flex; gap: 8px; align-items: baseline;
+    color: var(--fg);
+  }
+  .diff-row.diff-add { color: var(--acc-green); }
+  .diff-row.diff-rm  { color: var(--acc-red);   }
+  .diff-row.diff-mv  { color: var(--acc-amber); }
+  .diff-arrow { width: 10px; text-align: center; }
+  .diff-pos   { color: var(--fg-2); font-size: 11.5px; margin-left: auto; }
+  .diff-empty { color: var(--fg-2); font-style: italic; padding: 6px 0; }
+  .diff-more  { color: var(--fg-2); font-size: 11.5px; padding: 4px 0; }
+
+  /* build toggle (B41 / B42) */
+  .build-toggle {
+    display: inline-flex; align-items: center; gap: 8px;
+    padding: 4px 0 8px;
+    font-family: var(--mono);
+    font-size: 11.5px;
+    color: var(--fg-2);
+  }
+  .build-toggle-label { letter-spacing: .04em; text-transform: lowercase; }
+  .build-toggle-btn {
+    appearance: none;
+    border: 1px solid var(--line);
+    background: var(--bg-1);
+    color: var(--fg-2);
+    height: 22px;
+    padding: 0 9px;
+    border-radius: 4px;
+    font-family: var(--mono);
+    font-size: 11.5px;
+    cursor: pointer;
+    transition: color .12s, background .12s, border-color .12s;
+  }
+  .build-toggle-btn:hover { color: var(--fg); border-color: var(--line-2); background: var(--bg-3); }
+  .build-toggle-btn.is-active {
+    color: var(--acc-green);
+    border-color: var(--acc-green);
+    background: var(--acc-green-bg);
+  }
+  .cg-build { color: var(--fg-2); }
+  /* Pre-paste build picker: sits at the top of the input column so the user
+   * sets the target build BEFORE pasting wsids. Backend uses pz_build to
+   * emit build-mismatch warnings on tagged mods that don't support it. */
+  .build-prepick {
+    display: flex; align-items: center; flex-wrap: wrap;
+    gap: 10px; padding-bottom: 6px;
+  }
+  .build-prepick .build-toggle { padding: 0; }
+  .build-prepick-hint {
+    font-family: var(--mono);
+    font-size: 11.5px;
+    color: var(--fg-2);
+  }
+
+  /* warnings */
+  .warn-section .warn-head {
+    display: flex; align-items: center; gap: 8px;
+    font-family: var(--mono);
+    font-size: 11.5px;
+    cursor: pointer;
+    user-select: none;
+    color: var(--fg-1);
+    padding: 10px 12px;
+  }
+  .warn-section .warn-head .badge {
+    display: inline-flex; align-items: center; justify-content: center;
+    min-width: 18px; height: 18px; padding: 0 6px;
+    border-radius: 9px;
+    font-size: 11.5px;
+    font-weight: 600;
+    background: var(--acc-amber-bg);
+    color: var(--acc-amber);
+    border: 1px solid var(--acc-amber);
+  }
+  .warn-section .warn-head .badge.red {
+    background: var(--acc-red-bg);
+    color: var(--acc-red);
+    border-color: var(--acc-red);
+  }
+  .warn-section .warn-head .chev {
+    margin-left: auto;
+    color: var(--fg-2);
+    font-size: 10px;
+  }
+  .warn-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    border-top: 1px solid var(--line);
+  }
+  .warn-list li {
+    display: grid;
+    grid-template-columns: 80px 1fr;
+    gap: 12px;
+    padding: 10px 12px;
+    font-family: var(--mono);
+    font-size: 12px;
+    border-bottom: 1px solid var(--line);
+  }
+  .warn-list li:last-child { border-bottom: 0; }
+  .warn-list .w-tag {
+    color: var(--fg-2);
+    font-size: 11.5px;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    padding-top: 1px;
+  }
+  .warn-list .w-tag.amber { color: var(--acc-amber); }
+  .warn-list .w-tag.red { color: var(--acc-red); }
+  .warn-list .w-content {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 6px 8px;
+    line-height: 1.55;
+  }
+  .warn-list .w-msg { color: var(--fg); }
+  .warn-list .w-msg em { color: var(--acc-blue); font-style: normal; }
+  .warn-action {
+    appearance: none;
+    border: 1px solid var(--acc-blue);
+    background: var(--acc-blue-bg, rgba(70,140,220,0.12));
+    color: var(--acc-blue);
+    font-family: var(--mono);
+    font-size: 12px;
+    font-weight: 600;
+    padding: 3px 10px;
+    border-radius: var(--radius);
+    cursor: pointer;
+    transition: color .12s, border-color .12s, background .12s, transform .08s;
+  }
+  .warn-action:hover {
+    background: var(--acc-blue);
+    color: var(--brand-ink);
+  }
+  .warn-action:active { transform: translateY(1px); }
+  .warn-action.expand {
+    border-color: var(--acc-amber);
+    background: var(--acc-amber-bg, rgba(220,160,70,0.12));
+    color: var(--acc-amber);
+  }
+  .warn-action.expand:hover {
+    background: var(--acc-amber);
+    color: var(--brand-ink);
+    border-color: var(--acc-amber);
+  }
+  /* External-link variant: search Steam Workshop when we can't auto-add. */
+  .warn-action.search {
+    border-color: var(--line-2);
+    background: transparent;
+    color: var(--fg-2);
+    text-decoration: none;
+  }
+  .warn-action.search:hover {
+    color: var(--acc-blue);
+    border-color: var(--acc-blue);
+    background: var(--acc-blue-bg, rgba(70,140,220,0.10));
+  }
+  /* Swap variant: distinct accent (success/green) since swapping is a
+   * deterministic resolution to a build-mismatch — strictly better than
+   * leaving the wrong-build wsid in the input. */
+  .warn-action.swap {
+    border-color: var(--success, var(--acc-green));
+    background: var(--success-bg, rgba(80,180,120,0.10));
+    color: var(--success, var(--acc-green));
+  }
+  .warn-action.swap:hover {
+    background: var(--success, var(--acc-green));
+    color: var(--brand-ink);
+  }
+  /* Remove variant: error-toned. Destructive in user-perception (drops a
+   * wsid from the input) but actually safer than leaving a wrong-build
+   * mod in. Hover flips to filled so accidental clicks are loud. */
+  .warn-action.remove {
+    border-color: var(--error);
+    background: transparent;
+    color: var(--error);
+  }
+  .warn-action.remove:hover {
+    background: var(--error);
+    color: var(--brand-ink);
+    border-color: var(--error);
+  }
+  /* Inline mod-name hyperlink inside warning messages. Inherits the message
+   * color so reading flow isn't disrupted; underline + brand color on hover
+   * signals it's clickable. */
+  .w-msg-link {
+    color: inherit;
+    text-decoration: none;
+    text-decoration-thickness: 1px;
+    text-underline-offset: 2px;
+  }
+  .w-msg-link:hover,
+  .w-msg-link:focus-visible {
+    color: var(--info);
+    text-decoration: underline;
+  }
+  .warn-branches {
+    flex-basis: 100%;
+    display: flex;
+    flex-wrap: wrap;
+    gap: 4px;
+    margin-top: 4px;
+  }
+  .warn-branch-btn {
+    appearance: none;
+    border: 1px solid var(--line);
+    background: transparent;
+    color: var(--fg-2);
+    font-family: var(--mono);
+    font-size: 12px;
+    padding: 2px 8px;
+    border-radius: var(--radius);
+    cursor: pointer;
+    transition: color .12s, border-color .12s, background .12s;
+  }
+  .warn-branch-btn:hover {
+    color: var(--acc-amber);
+    border-color: var(--acc-amber);
+  }
+  .warn-branch-btn.picked {
+    color: var(--acc-green);
+    border-color: var(--acc-green);
+    background: var(--acc-green-bg, rgba(80,180,120,0.08));
+    cursor: default;
+  }
+
+  /* mod details table */
+  .table-section .tbl-head {
+    display: flex; align-items: center; gap: 8px;
+    font-family: var(--mono);
+    font-size: 11.5px;
+    cursor: pointer;
+    user-select: none;
+    color: var(--fg-1);
+    padding: 10px 12px;
+  }
+  .table-section .tbl-head .count {
+    color: var(--fg-2);
+    font-variant-numeric: tabular-nums;
+  }
+  .table-section .tbl-head .chev {
+    margin-left: auto; color: var(--fg-2); font-size: 10px;
+  }
+  .mods-table {
+    width: 100%;
+    border-collapse: collapse;
+    font-family: var(--mono);
+    font-size: 12px;
+    border-top: 1px solid var(--line);
+  }
+  .mods-table th, .mods-table td {
+    padding: 9px 12px;
+    text-align: left;
+    border-bottom: 1px solid var(--line);
+    vertical-align: top;
+  }
+  .mods-table th {
+    background: var(--bg-2);
+    color: var(--fg-2);
+    font-weight: 500;
+    font-size: 11.5px;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+  }
+  .mods-table tr:last-child td { border-bottom: 0; }
+  .mods-table td.idx { color: var(--fg-muted); width: 44px; font-variant-numeric: tabular-nums; padding-left: 6px; }
+  .row-state-glyph {
+    display: inline-block; min-width: 12px; margin-right: 6px;
+    text-align: center; font-weight: 700;
+  }
+  /* Per-row state: color + left-border pattern + glyph (in idx cell). */
+  .mod-row.mod-row-resolved   td:first-child { border-left: 3px solid var(--success); }
+  .mod-row.mod-row-resolved   .row-state-glyph { color: var(--success); }
+  .mod-row.mod-row-warning    td:first-child { border-left: 3px dotted var(--warning); }
+  .mod-row.mod-row-warning    .row-state-glyph { color: var(--warning); }
+  .mod-row.mod-row-unresolved td:first-child { border-left: 3px dashed var(--warning); }
+  .mod-row.mod-row-unresolved .row-state-glyph { color: var(--warning); }
+  .mod-row.mod-row-error      td:first-child { border-left: 3px solid var(--error); }
+  .mod-row.mod-row-error      .row-state-glyph { color: var(--error); }
+  .mods-table td .modid { color: var(--fg); }
+  .mods-table td .wsid { color: var(--fg-2); }
+  /* The wsid cell is a deep-link to the Steam Workshop page. Inherit the
+   * surrounding `.wsid` color so the row reads the same as before; only
+   * an underline + brand color on hover signals it's clickable. */
+  .wsid-link {
+    color: inherit;
+    text-decoration: none;
+    text-decoration-thickness: 1px;
+    text-underline-offset: 2px;
+  }
+  .wsid-link:hover,
+  .wsid-link:focus-visible {
+    color: var(--info);
+    text-decoration: underline;
+  }
+  .mods-table td .cat {
+    display: inline-block;
+    padding: 1px 6px;
+    border-radius: 3px;
+    background: var(--bg-3);
+    color: var(--fg-1);
+    font-size: 11.5px;
+  }
+  .mods-table td .cat.map { background: var(--info-bg);    color: var(--info); }
+  .mods-table td .cat.lib { background: var(--warning-bg); color: var(--warning); }
+  /* Spec G-patch: patch pill - uses warning tone since patches load LAST and
+   * may need attention. Distinct from .cat.lib (also warning-toned) by the
+   * label text "patch" vs "lib" - color is reinforcement, not the carrier. */
+  .mods-table td .cat.patch { background: var(--bg-panel); color: var(--fg-muted); border: 1px solid var(--border); }
+  .mods-table td .deps {
+    color: var(--fg-2);
+  }
+  .mods-table td .pos {
+    color: var(--fg-2);
+    font-size: 11.5px;
+  }
+  .mods-table td .pos.first { color: var(--acc-green); }
+  .mods-table td .pos.last { color: var(--acc-amber); }
+
+  /* error banner */
+  .err-banner {
+    display: flex; align-items: flex-start; gap: 12px;
+    padding: 12px 14px;
+    background: var(--acc-red-bg);
+    border: 1px solid var(--acc-red);
+    border-radius: var(--radius);
+    font-family: var(--mono);
+    font-size: 12px;
+    color: var(--fg);
+  }
+  .err-banner .err-tag {
+    color: var(--acc-red);
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    font-size: 11.5px;
+    padding-top: 1px;
+  }
+  .err-banner .err-msg { flex: 1; line-height: 1.55; color: var(--fg-1); }
+  .err-banner .err-actions {
+    display: flex; gap: 6px; margin-top: 8px;
+  }
+
+  /* cold-cache notice - matches the StatusStrip 'cold' pill (warning tone). */
+  .cold-banner {
+    display: flex; align-items: flex-start; gap: 12px;
+    padding: 12px 14px;
+    background: var(--warning-bg);
+    border: 1px solid var(--warning);
+    border-radius: var(--radius);
+    font-family: var(--mono);
+    font-size: 12px;
+  }
+  .cold-banner .err-tag {
+    color: var(--acc-blue);
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    font-size: 11.5px;
+    padding-top: 1px;
+  }
+  .cold-banner .err-msg { flex: 1; color: var(--fg-1); line-height: 1.55; }
+
+  /* empty-state docs panel */
+  .docs-panel {
+    background: var(--bg-1);
+    border: 1px solid var(--line);
+    border-radius: var(--radius);
+    overflow: hidden;
+  }
+  .docs-panel .dp-head {
+    padding: 10px 12px;
+    border-bottom: 1px solid var(--line);
+    font-family: var(--mono);
+    font-size: 11.5px;
+    color: var(--fg-1);
+    display: flex; align-items: center; justify-content: space-between;
+  }
+  .docs-panel .dp-body {
+    padding: 12px 14px;
+    font-family: var(--mono);
+    font-size: 11.5px;
+    color: var(--fg-1);
+    line-height: 1.7;
+  }
+  .docs-panel .dp-body ol {
+    margin: 0; padding: 0 0 0 18px;
+  }
+  .docs-panel .dp-body li { margin-bottom: 4px; }
+  .docs-panel .dp-body code {
+    background: var(--bg-2);
+    color: var(--fg);
+    padding: 1px 5px;
+    border-radius: 3px;
+    font-size: 12px;
+  }
+  .docs-panel .dp-body .hint {
+    color: var(--fg-2);
+    font-size: 12px;
+    margin-top: 8px;
+    border-top: 1px dashed var(--line);
+    padding-top: 8px;
+  }
+
+  /* empty/idle right-column placeholder */
+  .right-empty {
+    border: 1px dashed var(--line-2);
+    border-radius: var(--radius);
+    padding: 28px 20px;
+    color: var(--fg-2);
+    font-family: var(--mono);
+    font-size: 12.5px;
+    text-align: left;
+    display: flex; flex-direction: column; gap: 10px;
+    line-height: 1.6;
+  }
+  .right-empty .big {
+    color: var(--fg-1);
+    font-size: 14px;
+  }
+  .right-empty .arrow {
+    display: inline-block; margin-right: 8px; color: var(--acc-green);
+  }
+  .right-empty .ex {
+    background: var(--bg-2);
+    border: 1px solid var(--line);
+    border-radius: 5px;
+    padding: 8px 10px;
+    color: var(--fg-1);
+    margin-top: 4px;
+    font-size: 11.5px;
+  }
+  .right-empty .ex .ink-mut { color: var(--fg-2); }
+
+  /* state label tweak — color + glyph + label per brief mapping. */
+  .state-tag {
+    display: inline-flex; align-items: center; gap: 6px;
+    font-family: var(--mono); font-size: 12px;
+    color: var(--fg-muted);
+    text-transform: lowercase;
+  }
+  .state-tag-glyph {
+    display: inline-block; min-width: 12px; text-align: center;
+    font-weight: 700; line-height: 1;
+    color: var(--fg-muted);
+  }
+  .state-tag.state-tag-idle    .state-tag-glyph { color: var(--fg-muted); }
+  .state-tag.state-tag-working  .state-tag-glyph,
+  .state-tag.state-tag-queued   .state-tag-glyph,
+  .state-tag.state-tag-draining .state-tag-glyph { color: var(--info); }
+  .state-tag.state-tag-done     .state-tag-glyph { color: var(--success); }
+  .state-tag.state-tag-warning  .state-tag-glyph { color: var(--warning); }
+  .state-tag.state-tag-failed   .state-tag-glyph { color: var(--error); }
+
+  /* compact success treatment (variant b) */
+  .compact-grid {
+    display: grid;
+    grid-template-columns: 110px 1fr 28px;
+    gap: 0;
+    background: var(--bg-1);
+    border: 1px solid var(--line);
+    border-radius: var(--radius);
+    overflow: hidden;
+  }
+  .compact-grid .cg-row {
+    display: contents;
+  }
+  .compact-grid .cg-row > * {
+    border-bottom: 1px solid var(--line);
+    padding: 11px 12px;
+  }
+  .compact-grid .cg-row:last-child > * { border-bottom: 0; }
+  .compact-grid .cg-key {
+    font-family: var(--mono);
+    font-size: 12px;
+    color: var(--fg-2);
+    background: var(--bg-2);
+    border-right: 1px solid var(--line);
+    text-transform: lowercase;
+    letter-spacing: 0.02em;
+    align-self: stretch;
+  }
+  .compact-grid .cg-val {
+    font-family: var(--mono);
+    font-size: 12.5px;
+    color: var(--fg);
+    word-break: break-all;
+    overflow-x: auto;
+    line-height: 1.5;
+  }
+  .compact-grid .cg-cp {
+    border-right: 0;
+    border-left: 1px solid var(--line);
+    background: var(--bg-1);
+    display: flex; align-items: center; justify-content: center;
+    padding: 0;
+    cursor: pointer;
+    color: var(--fg-2);
+    transition: color .12s, background .12s;
+  }
+  .compact-grid .cg-cp:hover { color: var(--fg); background: var(--bg-2); }
+  .compact-grid .cg-cp.copied { color: var(--acc-green); }
+  .compact-grid .cg-cp svg { width: 12px; height: 12px; }
+
+  /* numbered/labeled treatment (variant c) */
+  .numbered-block {
+    background: var(--bg-1);
+    border: 1px solid var(--line);
+    border-radius: var(--radius);
+    padding: 14px 16px 12px;
+    position: relative;
+    font-family: var(--mono);
+  }
+  .numbered-block .nb-head {
+    display: flex; align-items: baseline; gap: 10px;
+    margin-bottom: 6px;
+  }
+  .numbered-block .nb-head .nb-num {
+    font-size: 11.5px;
+    color: var(--fg-2);
+    font-variant-numeric: tabular-nums;
+  }
+  .numbered-block .nb-head .nb-key {
+    color: var(--acc-blue);
+    font-size: 12px;
+    font-weight: 500;
+  }
+  .numbered-block .nb-head .nb-meta {
+    color: var(--fg-2);
+    font-size: 11.5px;
+    margin-left: auto;
+  }
+  .numbered-block .nb-pre {
+    color: var(--fg);
+    font-size: 13px;
+    line-height: 1.55;
+    word-break: break-all;
+    margin: 0;
+    white-space: pre-wrap;
+  }
+  .numbered-block .nb-cp {
+    position: absolute;
+    top: 10px; right: 10px;
+  }
+
+  /* tiny svg icons */
+  .ico { width: 13px; height: 13px; flex-shrink: 0; }
+
+  /* worked-example pre-fill chip on input */
+  .worked-hint {
+    position: absolute;
+    inset: auto 0 0 0;
+    padding: 6px 12px;
+    font-family: var(--mono); font-size: 11.5px;
+    color: var(--fg-2);
+    pointer-events: none;
+    background: linear-gradient(to top, var(--bg-2), transparent);
+    border-radius: 0 0 var(--radius) var(--radius);
+  }
+
+  /* responsive */
+  @media (max-width: 600px) {
+    header.app { padding: 12px 16px; flex-wrap: wrap; }
+    .tagline { display: none; }
+    main.app { padding: 16px; gap: 18px; }
+    .compact-grid { grid-template-columns: 80px 1fr 28px; }
+    .warn-list li { grid-template-columns: 1fr; gap: 4px; }
+  }
+</style>
+</head>
+<body>
+
+<div id="root"></div>
+
+<script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
+
+<script type="text/babel" src="tweaks-panel.jsx"></script>
+<script type="text/babel" src="sortof-data.jsx"></script>
+<script type="text/babel" src="sortof-app.jsx"></script>
+
+</body>
+</html>
diff --git a/frontend/sortof-app.jsx b/frontend/sortof-app.jsx
new file mode 100644
index 0000000..20d7279
--- /dev/null
+++ b/frontend/sortof-app.jsx
@@ -0,0 +1,1953 @@
+// sortof - main React app
+// Fake state machine: empty → loading → partial → success/error/cold
+// Three empty variants, three success variants, exposed via Tweaks.
+
+const { useState, useEffect, useRef, useMemo } = React;
+
+// Live data shim: leaves keep reading D.X; we swap _liveSortData on each
+// successful /api/sort response. Tweaks-preview mode leaves it null and
+// falls back to the canned dataset.
+let _liveSortData = null;
+const D = new Proxy({}, {
+  get(_, key) {
+    const src = _liveSortData ?? window.SORTOF_DATA;
+    return src ? src[key] : undefined;
+  }
+});
+
+// Mirrors backend parse.py: accepts newlines, semicolons, commas, spaces,
+// tabs, ini-style prefixes (WorkshopItems=, Mods=, Map=), and Workshop URLs.
+// Returns deduped IDs in first-seen order.
+function parseWorkshopInput(text) {
+  if (!text) return [];
+  const cleaned = String(text).replace(/^\s*(WorkshopItems|Mods|Map)\s*=\s*/gim, '');
+  const ids = cleaned.match(/\b\d{7,12}\b/g) || [];
+  return Array.from(new Set(ids));
+}
+
+// Render the Mods= value for a given PZ build.
+//   B41: mod1;mod2;mod3;
+//   B42: \mod1;\mod2;\mod3;
+// Trailing semicolon kept so the line pastes verbatim into the server's .ini file.
+function buildModsLine(ids, mode) {
+  if (!ids || !ids.length) return '';
+  if (mode === 'B42') return '\\' + ids.join(';\\') + ';';
+  return ids.join(';') + ';';
+}
+
+// Spec B+F: poll a job. Resolves on terminal phase or AbortSignal.
+const POLL_INTERVAL_MS = 2500;
+
+async function pollJobOnce(jobId) {
+  try {
+    const res = await fetch(`/api/jobs/${jobId}`);
+    if (res.status === 404) return { kind: 'expired' };
+    if (!res.ok) return { kind: 'error', status: res.status };
+    const json = await res.json();
+    return { kind: 'ok', body: json };
+  } catch (e) {
+    console.warn('pollJobOnce: network error', e);
+    return { kind: 'error', status: 0 };
+  }
+}
+
+function pollJobLoop(jobId, signal, onTick) {
+  return new Promise((resolve) => {
+    let timer = null;
+    async function tick() {
+      if (signal.aborted) { if (timer) clearTimeout(timer); resolve({ kind: 'aborted' }); return; }
+      const r = await pollJobOnce(jobId);
+      if (signal.aborted) { resolve({ kind: 'aborted' }); return; }
+      onTick(r);
+      if (r.kind === 'expired' || r.kind === 'error') { resolve(r); return; }
+      const phase = r.body.phase;
+      if (phase === 'done' || phase === 'failed') { resolve(r); return; }
+      timer = setTimeout(tick, POLL_INTERVAL_MS);
+    }
+    tick();
+  });
+}
+
+// The picker's default selection mirrors the backend's auto-pick. After
+// Spec C, the backend applies build-aware + input-cross-ref + prefix-base
+// rules and emits SORTED_ORDER reflecting the chosen branches. The picker
+// reads from SORTED_ORDER (passed as `activeSet`) and ticks any branch
+// whose mod_id is in that set; falls back to first-only if none match.
+// Spec A's contract holds - the picker is the source of truth.
+function isRadioMode(branches) {
+  if (!branches || branches.length < 2) return false;
+  const ids = new Set(branches.map(b => b.modId));
+  return branches.some(b => (b.conflicts || []).some(c => ids.has(c)));
+}
+
+function defaultSelectionForBranches(branches, activeSet) {
+  if (!branches || !branches.length) return [];
+  if (activeSet && activeSet.size) {
+    const active = branches.filter(b => activeSet.has(b.modId)).map(b => b.modId);
+    if (active.length) return active;
+  }
+  return [branches[0].modId];
+}
+
+// Shared column count for the Mod Details table. Keep in sync with the
+// <thead> in ModTable; expansion-panel <tr colSpan> reads this constant.
+// Spec C will add a 7th column; bump here, do not hardcode the integer.
+const COLUMN_COUNT = 6;
+
+// Steam Workshop deep-link for a wsid. Pattern is the same for mods and
+// collections (the backend resolves the distinction; users see one URL).
+function wsidUrl(wsid) {
+  return `https://steamcommunity.com/sharedfiles/filedetails/?id=${wsid}`;
+}
+
+function WsidLink({ wsid, children, className }) {
+  if (!wsid) return <span className={className}>{children ?? wsid}</span>;
+  return (
+    <a
+      href={wsidUrl(wsid)}
+      target="_blank"
+      rel="noopener noreferrer"
+      className={className ? className + ' wsid-link' : 'wsid-link'}
+      title={`open Workshop page for ${wsid}`}
+    >{children ?? wsid}</a>
+  );
+}
+
+// Snapshot the fields needed to diff against the next sort/resort. Called
+// before each fetch fires so the snapshot captures "what the user saw
+// before this action". Polling-mid-flight ticks intentionally don't snapshot
+// (would erase the prior visible state on every 2.5s update).
+function snapshotForDiff(src) {
+  if (!src) return null;
+  return {
+    SORTED_ORDER: [...(src.SORTED_ORDER || [])],
+    MOD_DB: (src.MOD_DB || []).map(m => ({ modId: m.modId, wsid: m.wsid, name: m.name })),
+    MODS_LINE: src.MODS_LINE || '',
+    WORKSHOP_ITEMS_LINE: src.WORKSHOP_ITEMS_LINE || '',
+  };
+}
+
+function computeDiff(prev, curr) {
+  if (!prev || !curr) return null;
+  const prevSorted = prev.SORTED_ORDER || [];
+  const currSorted = curr.SORTED_ORDER || [];
+  const prevSet = new Set(prevSorted);
+  const currSet = new Set(currSorted);
+  const added = currSorted.filter(id => !prevSet.has(id));
+  const removed = prevSorted.filter(id => !currSet.has(id));
+  const prevPos = new Map(prevSorted.map((id, i) => [id, i]));
+  const movers = [];
+  currSorted.forEach((id, ci) => {
+    if (!prevSet.has(id)) return;
+    const pi = prevPos.get(id);
+    if (pi !== ci) movers.push({ id, from: pi, to: ci, delta: ci - pi });
+  });
+  movers.sort((a, b) => Math.abs(b.delta) - Math.abs(a.delta));
+  const prevWsl = (prev.WORKSHOP_ITEMS_LINE || '').replace(/;+$/, '').split(';').filter(Boolean);
+  const currWsl = (curr.WORKSHOP_ITEMS_LINE || '').replace(/;+$/, '').split(';').filter(Boolean);
+  const prevWsidPos = new Map(prevWsl.map((w, i) => [w, i]));
+  const wsidMovers = [];
+  currWsl.forEach((w, ci) => {
+    const pi = prevWsidPos.get(w);
+    if (pi !== undefined && pi !== ci) wsidMovers.push({ wsid: w, from: pi, to: ci });
+  });
+  wsidMovers.sort((a, b) => Math.abs(b.to - b.from) - Math.abs(a.to - a.from));
+  return { added, removed, movers, wsidMovers };
+}
+
+function DiffPanel({ prev, curr, onClose }) {
+  const diff = computeDiff(prev, curr);
+  if (!diff) {
+    return (
+      <div className="diff-panel">
+        <div className="diff-head">
+          <span className="diff-title">diff vs previous sort</span>
+          <button type="button" className="diff-close" onClick={onClose}>close</button>
+        </div>
+        <div className="diff-empty">no previous sort to compare against - sort once first.</div>
+      </div>
+    );
+  }
+  const { added, removed, movers, wsidMovers } = diff;
+  const empty = !added.length && !removed.length && !movers.length && !wsidMovers.length;
+  return (
+    <div className="diff-panel">
+      <div className="diff-head">
+        <span className="diff-title">diff vs previous sort</span>
+        <span className="diff-summary">
+          <span className="diff-stat add">+{added.length}</span>
+          <span className="diff-stat rm">−{removed.length}</span>
+          <span className="diff-stat mv">↕{movers.length}</span>
+        </span>
+        <button type="button" className="diff-close" onClick={onClose}>close</button>
+      </div>
+      {empty && <div className="diff-empty">nothing changed.</div>}
+      {added.length > 0 && (
+        <div className="diff-section">
+          <div className="diff-label">added ({added.length})</div>
+          {added.slice(0, 30).map(id => <div key={id} className="diff-row diff-add">+ {id}</div>)}
+          {added.length > 30 && <div className="diff-more">…and {added.length - 30} more</div>}
+        </div>
+      )}
+      {removed.length > 0 && (
+        <div className="diff-section">
+          <div className="diff-label">removed ({removed.length})</div>
+          {removed.slice(0, 30).map(id => <div key={id} className="diff-row diff-rm">− {id}</div>)}
+          {removed.length > 30 && <div className="diff-more">…and {removed.length - 30} more</div>}
+        </div>
+      )}
+      {movers.length > 0 && (
+        <div className="diff-section">
+          <div className="diff-label">moved by load order ({movers.length}, top {Math.min(10, movers.length)} shown)</div>
+          {movers.slice(0, 10).map(({ id, from, to, delta }) => (
+            <div key={id} className="diff-row diff-mv">
+              <span className="diff-arrow">{delta < 0 ? '↑' : '↓'}</span>
+              {id}
+              <span className="diff-pos">pos {from + 1} → {to + 1} ({delta > 0 ? '+' : ''}{delta})</span>
+            </div>
+          ))}
+        </div>
+      )}
+      {wsidMovers.length > 0 && (
+        <div className="diff-section">
+          <div className="diff-label">WorkshopItems= reorder ({wsidMovers.length})</div>
+          {wsidMovers.slice(0, 10).map(({ wsid, from, to }) => (
+            <div key={wsid} className="diff-row diff-mv">
+              <span className="diff-arrow">{to < from ? '↑' : '↓'}</span>
+              {wsid}
+              <span className="diff-pos">pos {from + 1} → {to + 1}</span>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ── icons ───────────────────────────────────────────────────────────────────
+const IconCopy = () => (
+  <svg className="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+    <rect x="9" y="9" width="13" height="13" rx="2"></rect>
+    <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+  </svg>
+);
+const IconCheck = () => (
+  <svg className="ico" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round">
+    <polyline points="20 6 9 17 4 12"></polyline>
+  </svg>
+);
+const IconGit = () => (
+  <svg viewBox="0 0 24 24" fill="currentColor" width="14" height="14">
+    <path d="M12 .5C5.7.5.5 5.7.5 12c0 5.1 3.3 9.4 7.9 10.9.6.1.8-.3.8-.6v-2c-3.2.7-3.9-1.5-3.9-1.5-.5-1.3-1.3-1.7-1.3-1.7-1-.7.1-.7.1-.7 1.2.1 1.8 1.2 1.8 1.2 1 1.8 2.7 1.3 3.4 1 .1-.8.4-1.3.8-1.6-2.6-.3-5.3-1.3-5.3-5.7 0-1.3.4-2.3 1.2-3.1-.1-.3-.5-1.5.1-3.1 0 0 1-.3 3.2 1.2.9-.3 1.9-.4 2.9-.4 1 0 2 .1 2.9.4 2.2-1.5 3.2-1.2 3.2-1.2.6 1.6.2 2.8.1 3.1.7.8 1.2 1.8 1.2 3.1 0 4.4-2.7 5.4-5.3 5.7.4.4.8 1.1.8 2.2v3.3c0 .3.2.7.8.6 4.6-1.5 7.9-5.8 7.9-10.9C23.5 5.7 18.3.5 12 .5z"/>
+  </svg>
+);
+
+// ── small helpers ───────────────────────────────────────────────────────────
+function CopyBtn({ text, label = 'copy', minimal = false }) {
+  const [copied, setCopied] = useState(false);
+  const onClick = async () => {
+    try {
+      await navigator.clipboard.writeText(text);
+    } catch (e) {
+      // fallback
+      const ta = document.createElement('textarea');
+      ta.value = text; document.body.appendChild(ta); ta.select();
+      try { document.execCommand('copy'); } catch (_) {}
+      document.body.removeChild(ta);
+    }
+    setCopied(true);
+    setTimeout(() => setCopied(false), 1200);
+  };
+  if (minimal) {
+    return (
+      <button className={'cg-cp' + (copied ? ' copied' : '')} onClick={onClick} title="copy">
+        {copied ? <IconCheck /> : <IconCopy />}
+      </button>
+    );
+  }
+  return (
+    <button className={'copy-btn' + (copied ? ' copied' : '')} onClick={onClick}>
+      {copied ? <IconCheck /> : <IconCopy />}
+      {copied ? 'copied' : label}
+    </button>
+  );
+}
+
+// ── header & footer ─────────────────────────────────────────────────────────
+function Header({ tagline, view, onReport, onSort }) {
+  return (
+    <header className="app">
+      <div className="brand">
+        <a
+          href="https://indifferentketchup.com"
+          target="_blank"
+          rel="noopener noreferrer"
+          aria-label="indifferent ketchup"
+          className="brand-mark-link"
+        >
+          <img
+            src="/img/ketchup_bottle.png"
+            alt=""
+            className="brand-mark"
+            width="40"
+            height="40"
+          />
+        </a>
+        <span className="wordmark">sortof<span className="dot">.</span></span>
+        {tagline && <span className="tagline">{tagline}</span>}
+      </div>
+      <div className="head-right">
+        {view === 'reports' ? (
+          <button type="button" className="icon-btn report" onClick={onSort}>
+            ← back to sort
+          </button>
+        ) : (
+          <button type="button" className="icon-btn report" onClick={onReport}>
+            ⚠ report broken mod
+          </button>
+        )}
+        <a className="icon-btn" href="#" onClick={(e) => e.preventDefault()}>
+          <IconGit /> github
+        </a>
+        <a className="icon-btn" href="#" onClick={(e) => e.preventDefault()}>
+          docs
+        </a>
+      </div>
+    </header>
+  );
+}
+
+function Footer() {
+  return (
+    <footer className="app">
+      <div className="left">
+        <span>based on{' '}
+          <a className="footer-link footer-link-info"
+             href="https://steamcommunity.com/sharedfiles/filedetails/?id=3423660713"
+             target="_blank" rel="noopener noreferrer">
+            REfRigERatoR's mod load order sorter
+          </a>
+        </span>
+      </div>
+      <div className="right">
+        <span>
+          a thing by{' '}
+          <a className="footer-link footer-link-brand"
+             href="https://indifferentketchup.com"
+             target="_blank" rel="noopener noreferrer">
+            indifferent ketchup <span className="ik-mark" aria-hidden="true">(:|)</span>
+          </a>
+        </span>
+      </div>
+    </footer>
+  );
+}
+
+// ── empty-state variants ────────────────────────────────────────────────────
+function EmptyRight({ variant }) {
+  if (variant === 'bare') {
+    return (
+      <div className="right-empty">
+        <span className="big">no mods. or maybe loads of them. hard to tell.</span>
+        <span><span className="arrow">›</span> paste workshop ids on the left, hit sort. output lands here.</span>
+      </div>
+    );
+  }
+  if (variant === 'worked') {
+    return (
+      <div className="right-empty">
+        <span className="big">what you'll get back</span>
+        <div className="ex">
+          <div><span style={{ color: 'var(--acc-blue)' }}>WorkshopItems</span>=2169435993;2392709985;…
+          </div>
+          <div><span style={{ color: 'var(--acc-blue)' }}>Mods</span>=modoptions;tsarslib;…</div>
+          <div><span style={{ color: 'var(--acc-blue)' }}>Map</span>=Muldraugh, KY</div>
+          <div className="ink-mut" style={{ marginTop: 6, fontSize: 11.5 }}>↑ paste these into your server's .ini</div>
+        </div>
+      </div>
+    );
+  }
+  // docs
+  return (
+    <div className="docs-panel">
+      <div className="dp-head">
+        <span>how this works</span>
+        <span style={{ color: 'var(--fg-2)', fontSize: 11.5 }}>read once, never again</span>
+      </div>
+      <div className="dp-body">
+        <ol>
+          <li>paste workshop ids - newlines, semicolons, commas, or urls all work. one mod per id.</li>
+          <li>optionally provide <code>sorting_rules.txt</code> to pin libs first / maps last / mark incompatibles.</li>
+          <li>hit sort. we resolve dependencies, apply your rules, and emit three lines for your server's <code>.ini</code>.</li>
+          <li>copy each line. paste. boot the server. probably works.</li>
+        </ol>
+        <div className="hint">we cache mod metadata until the author publishes an update. cold-cache lookups take roughly 30s. you've been warned.</div>
+      </div>
+    </div>
+  );
+}
+
+// ── status strip ────────────────────────────────────────────────────────────
+function StatusStrip({ state, counts, progress }) {
+  // a11y: each pill emits (color, glyph, text) - never color alone. The glyph
+  // is hidden from screen readers (the surrounding text is the actual info)
+  // and the dot-led is replaced by a state-specific block-circle/arrow char.
+  const pill = (cls, glyph, label, title) => (
+    <span className={'status-pill ' + cls} title={title || undefined}>
+      <span className="status-glyph" aria-hidden="true">{glyph}</span>
+      <span className="status-label">{label}</span>
+    </span>
+  );
+
+  // State→(class, glyph, label) per brief mapping. Class names map to CSS
+  // rules below that pin each state to its semantic color (--success/--info/
+  // --warning/--error/--fg-muted) - color, glyph, AND label always together.
+  if (state === 'idle' || state === 'success' || state === 'error' || state === 'cold' || state === 'done' || state === 'failed') {
+    if (state === 'idle')    return <div className="status-strip">{pill('idle',    '●', 'idle')}</div>;
+    if (state === 'success' || state === 'done')
+                              return <div className="status-strip">{pill('done',    '✓', `done. ${counts.cached} mods, ${counts.warnings} warnings`)}</div>;
+    if (state === 'error')   return <div className="status-strip">{pill('failed',  '✗', 'failed. something went sideways')}</div>;
+    if (state === 'failed')  return <div className="status-strip">{pill('failed',  '✗', "failed. that didn't work")}</div>;
+    if (state === 'cold')    return <div className="status-strip">{pill('warning', '⚠', 'cache miss. cold-cache lookups take ~30s')}</div>;
+  }
+
+  if (state === 'expanding') {
+    return (
+      <div className="status-strip">
+        {pill('working', '⏵', 'working. expanding collection…')}
+        <div className="progress-bar"><i style={{ width: `${progress}%` }}></i></div>
+      </div>
+    );
+  }
+
+  // 'queued' / 'draining' / legacy 'partial' / legacy 'loading' - live counts.
+  return (
+    <div className="status-strip">
+      {pill('done',     '✓', `${counts.cached} cached`)}
+      {pill('queued',   '●', `${counts.queued} queued`)}
+      {pill('draining', '⏵', `${counts.parsing} draining`)}
+      {counts.unknown > 0 && pill('failed',  '✗', `${counts.unknown} unknown`,
+        "Steam doesn't recognize these IDs (deleted, typo'd, or private)")}
+      {counts.nonMod > 0 && pill('muted',   '−', `${counts.nonMod} non-mod`,
+        "Workshop items that aren't loadable mods (collections, art, etc.)")}
+      <div className="progress-bar"><i style={{ width: `${progress}%` }}></i></div>
+    </div>
+  );
+}
+
+// ── output: three success variants ──────────────────────────────────────────
+function SuccessStacked({ data, pzBuild }) {
+  const modsLine = buildModsLine(D.SORTED_ORDER, pzBuild);
+  return (
+    <>
+      <div className="code-block">
+        <div className="cb-head">
+          <span><span className="cb-key">WorkshopItems</span> <span className="cb-meta">· {data.count} ids</span></span>
+          <CopyBtn text={`WorkshopItems=${D.WORKSHOP_ITEMS_LINE}`} />
+        </div>
+        <pre><span className="ink-key">WorkshopItems</span><span className="ink-sep">=</span>{D.WORKSHOP_ITEMS_LINE}</pre>
+      </div>
+      <div className="code-block">
+        <div className="cb-head">
+          <span><span className="cb-key">Mods</span> <span className="cb-meta">· {data.count} mods · {pzBuild}</span></span>
+          <CopyBtn text={`Mods=${modsLine}`} />
+        </div>
+        <pre><span className="ink-key">Mods</span><span className="ink-sep">=</span>{modsLine}</pre>
+      </div>
+      <div className="code-block">
+        <div className="cb-head">
+          <span><span className="cb-key">Map</span> <span className="cb-meta">· 1 map detected</span></span>
+          <CopyBtn text={`Map=${D.MAP_LINE}`} />
+        </div>
+        <pre><span className="ink-key">Map</span><span className="ink-sep">=</span>{D.MAP_LINE}</pre>
+      </div>
+    </>
+  );
+}
+
+function SuccessCompact({ data, pzBuild }) {
+  const modsLine = buildModsLine(D.SORTED_ORDER, pzBuild);
+  return (
+    <div className="compact-grid">
+      <div className="cg-row">
+        <div className="cg-key">WorkshopItems</div>
+        <div className="cg-val">{D.WORKSHOP_ITEMS_LINE}</div>
+        <CopyBtn text={`WorkshopItems=${D.WORKSHOP_ITEMS_LINE}`} minimal />
+      </div>
+      <div className="cg-row">
+        <div className="cg-key">Mods <span className="cg-build">· {pzBuild}</span></div>
+        <div className="cg-val">{modsLine}</div>
+        <CopyBtn text={`Mods=${modsLine}`} minimal />
+      </div>
+      <div className="cg-row">
+        <div className="cg-key">Map</div>
+        <div className="cg-val">{D.MAP_LINE}</div>
+        <CopyBtn text={`Map=${D.MAP_LINE}`} minimal />
+      </div>
+    </div>
+  );
+}
+
+function SuccessNumbered({ data, pzBuild }) {
+  const modsLine = buildModsLine(D.SORTED_ORDER, pzBuild);
+  const blocks = [
+    { num: '01', key: 'WorkshopItems', val: D.WORKSHOP_ITEMS_LINE, meta: `${data.count} ids · ${(D.WORKSHOP_ITEMS_LINE.length)} chars` },
+    { num: '02', key: 'Mods',          val: modsLine,              meta: `${data.count} mods · ${pzBuild}` },
+    { num: '03', key: 'Map',           val: D.MAP_LINE,            meta: '1 map' },
+  ];
+  return (
+    <>
+      {blocks.map(b => (
+        <div key={b.key} className="numbered-block">
+          <div className="nb-head">
+            <span className="nb-num">{b.num}</span>
+            <span className="nb-key">{b.key}</span>
+            <span className="nb-meta">{b.meta}</span>
+          </div>
+          <pre className="nb-pre">{b.val}</pre>
+          <div className="nb-cp">
+            <CopyBtn text={`${b.key}=${b.val}`} />
+          </div>
+        </div>
+      ))}
+    </>
+  );
+}
+
+// ── warnings ─────────────────────────────────────────────────────────────────
+// Render a warning message with the leading mod name turned into a Workshop
+// hyperlink. Backend warnings start with "<modId> ..." (or "Mod '<modId>' ..."
+// for duplicate-mod_id). When `wsid` is provided, the first identifier of the
+// message becomes the link target; the rest renders as plain text.
+function WarnMsg({ msg, wsid }) {
+  if (!wsid || !msg) return <span className="w-msg">{msg}</span>;
+  // Match "<word>" at start (e.g., "ModId requires X"), or "Mod '<word>'"
+  // (duplicate-mod_id phrasing). Bare-id form is the common case.
+  const m = msg.match(/^(Mod ')([^']+)(')(.*)$/) || msg.match(/^([^\s]+)(.*)$/);
+  if (!m) return <span className="w-msg">{msg}</span>;
+  if (m.length === 5) {
+    const [, lead, name, close, rest] = m;
+    return (
+      <span className="w-msg">
+        {lead}
+        <a href={wsidUrl(wsid)} target="_blank" rel="noopener noreferrer"
+           className="w-msg-link" title={`open Workshop page for ${wsid}`}>{name}</a>
+        {close}{rest}
+      </span>
+    );
+  }
+  const [, name, rest] = m;
+  return (
+    <span className="w-msg">
+      <a href={wsidUrl(wsid)} target="_blank" rel="noopener noreferrer"
+         className="w-msg-link" title={`open Workshop page for ${wsid}`}>{name}</a>
+      {rest}
+    </span>
+  );
+}
+
+function WarnRow({ w, onAddWsid, onPickBranch, onSwapWsid, onRemoveWsid, onToggleBranch }) {
+  // Branch picker collapses by default; click "pick another" chev to expand.
+  const [branchOpen, setBranchOpen] = useState(false);
+  // Any warning that ships an `alternatives` array gets an inline picker.
+  // Covers auto-picked-branch (mutually exclusive primary pick) AND
+  // unmatched-addons (additive addon ticking) — both drive the same UI.
+  const hasPicker = Array.isArray(w.alternatives);
+  return (
+    <li>
+      <span className={'w-tag ' + w.level}>
+        <span aria-hidden="true" className="w-tag-glyph">{w.level === 'red' ? '!' : '⚠'}</span>
+        {w.tag}
+      </span>
+      <div className="w-content">
+        <WarnMsg msg={w.msg} wsid={w.wsid} />
+        {Array.isArray(w.actions) && w.actions.map((a, j) => {
+          if (a.type === 'add-wsid') {
+            return (
+              <button
+                key={j}
+                type="button"
+                className="warn-action"
+                onClick={() => onAddWsid && onAddWsid(a.wsid, a.modId)}
+                title={`add ${a.wsid} to your input and resort`}
+              >{a.label}</button>
+            );
+          }
+          if (a.type === 'swap-wsid') {
+            return (
+              <button
+                key={j}
+                type="button"
+                className="warn-action swap"
+                onClick={() => onSwapWsid && onSwapWsid(a.from, a.to)}
+                title={`replace ${a.from} with ${a.to} in your input and resort`}
+              >↔ {a.label}</button>
+            );
+          }
+          if (a.type === 'remove-wsid') {
+            return (
+              <button
+                key={j}
+                type="button"
+                className="warn-action remove"
+                onClick={() => onRemoveWsid && onRemoveWsid(a.wsid)}
+                title={`remove ${a.wsid} from your input and resort`}
+              >✕ {a.label}</button>
+            );
+          }
+          if (a.type === 'search-workshop') {
+            return (
+              <a
+                key={j}
+                href={a.url}
+                target="_blank"
+                rel="noopener noreferrer"
+                className="warn-action search"
+                title={`search Steam Workshop for ${a.modId}`}
+              >↗ {a.label}</a>
+            );
+          }
+          return null;
+        })}
+        {hasPicker && (
+          <>
+            <button
+              type="button"
+              className="warn-action expand"
+              onClick={() => setBranchOpen(b => !b)}
+              title={w.tag === 'unmatched-addons' ? 'tick addons to include' : 'pick a different branch'}
+            >{branchOpen ? '▾ branches' : '▸ branches'}</button>
+            {branchOpen && (
+              <div className="warn-branches">
+                {w.alternatives.map(modId => {
+                  // Two picker modes drive the same UI:
+                  //   auto-picked-branch → radio (one of N), `picked` is the
+                  //     currently-active mod_id; clicking switches.
+                  //   unmatched-addons → checkbox-additive; the primary
+                  //     (`picked`) stays loaded; clicking an addon toggles it
+                  //     in/out of the selection. Active mod_ids come from
+                  //     SORTED_ORDER so the ★ reflects the live state.
+                  const isAdditive = w.tag === 'unmatched-addons';
+                  const activeSet = new Set(D.SORTED_ORDER || []);
+                  const isActive = isAdditive ? activeSet.has(modId) : modId === w.picked;
+                  const isPrimary = modId === w.picked;
+                  return (
+                    <button
+                      key={modId}
+                      type="button"
+                      className={'warn-branch-btn' + (isActive ? ' picked' : '')}
+                      onClick={() => {
+                        if (isAdditive) {
+                          // Primary always stays loaded - no-op on clicking it.
+                          if (isPrimary) return;
+                          onToggleBranch && onToggleBranch(
+                            w.wsid, modId,
+                            w.alternatives.map(id => ({ modId: id })),
+                          );
+                        } else {
+                          if (isActive) return;
+                          onPickBranch && onPickBranch(w.wsid, modId, w.alternatives);
+                        }
+                      }}
+                      title={
+                        isPrimary && isAdditive ? 'main (always loaded)' :
+                        isActive ? (isAdditive ? 'addon enabled - click to remove' : 'currently selected (main)') :
+                        isAdditive ? `enable ${modId}` : `switch to ${modId}`
+                      }
+                    >
+                      {isActive ? '★ ' : ''}{modId}
+                    </button>
+                  );
+                })}
+              </div>
+            )}
+          </>
+        )}
+      </div>
+    </li>
+  );
+}
+
+function Warnings({ items, defaultOpen = true, onAddWsid, onPickBranch, onSwapWsid, onRemoveWsid, onToggleBranch }) {
+  const [open, setOpen] = useState(defaultOpen);
+  if (!items || items.length === 0) return null;
+  const reds = items.filter(w => w.level === 'red').length;
+  const ambers = items.length - reds;
+  return (
+    <div className="panel warn-section">
+      <div className="warn-head" onClick={() => setOpen(!open)}>
+        <span>warnings</span>
+        {reds > 0 && (
+          <span className="badge red" title={`${reds} error warning${reds === 1 ? '' : 's'}`}>
+            <span aria-hidden="true">!</span> {reds}
+          </span>
+        )}
+        {ambers > 0 && (
+          <span className="badge" title={`${ambers} caution warning${ambers === 1 ? '' : 's'}`}>
+            <span aria-hidden="true">⚠</span> {ambers}
+          </span>
+        )}
+        <span style={{ color: 'var(--fg-2)', fontSize: 11.5 }}>
+          {reds > 0 ? 'fix these or your server will sulk' : 'non-fatal but read them'}
+        </span>
+        <span className="chev" aria-hidden="true">{open ? '▾' : '▸'}</span>
+      </div>
+      {open && (
+        <ul className="warn-list">
+          {items.map((w, i) => (
+            <WarnRow key={i} w={w} onAddWsid={onAddWsid} onPickBranch={onPickBranch} onSwapWsid={onSwapWsid} onRemoveWsid={onRemoveWsid} onToggleBranch={onToggleBranch} />
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+function BranchPicker({ wsid, branches, selected, userTouched, onToggle }) {
+  const radio = isRadioMode(branches);
+  const inputType = radio ? 'radio' : 'checkbox';
+  // Default = whichever branch mod_ids are in SORTED_ORDER (set by backend
+  // rules per Spec C §4). User-touched selections override.
+  const activeSet = new Set(D.SORTED_ORDER || []);
+  const effective = userTouched ? selected : defaultSelectionForBranches(branches, activeSet);
+  return (
+    <tr>
+      <td colSpan={COLUMN_COUNT} className="branch-panel">
+        <div className="branch-panel-inner">
+          <div className="branch-panel-meta">
+            workshop {wsid} · {branches.length} mod_ids · {radio ? 'pick one' : 'multi-select'}
+          </div>
+          {branches.map(b => {
+            const checked = effective.includes(b.modId);
+            return (
+              <label key={b.modId} className={'branch-row' + (checked ? ' is-checked' : '')}>
+                <input
+                  type={inputType}
+                  name={radio ? `branch-${wsid}` : undefined}
+                  className="branch-input"
+                  checked={checked}
+                  onChange={() => onToggle(wsid, b.modId, branches)}
+                />
+                <WsidLink wsid={wsid} className="branch-modid">{b.modId}</WsidLink>
+                <span className="branch-name">{b.name}</span>
+                <span className={'cat ' + b.cat}>{b.cat}</span>
+                <span className="branch-deps">
+                  {b.deps && b.deps.length ? b.deps.join(', ') : '-'}
+                </span>
+                <span className="branch-pos">
+                  {b.pos === 'first' ? 'first' : (b.pos === 'last' ? 'last' : '-')}
+                </span>
+                {b.hint && <span className="branch-hint">{b.hint}</span>}
+              </label>
+            );
+          })}
+        </div>
+      </td>
+    </tr>
+  );
+}
+
+// ── mod details table ───────────────────────────────────────────────────────
+// Classify each mod_id into a row-state for the Mod Details table per Spec
+// brief 2026-05-01. Pattern-matches the warning messages to derive which
+// mod_id is the *source* of a warning (the leading token before `requires`,
+// `marked`, `incompatible`, or in a cycle path). Imperfect but cheap; if the
+// backend grows a `WARNINGS[].affected: [mod_ids]` field this collapses to
+// a simple lookup.
+function rowStateForMod(modId) {
+  const warns = (D.WARNINGS || []);
+  for (const w of warns) {
+    if (!w || !w.msg) continue;
+    const msg = w.msg;
+    const m = msg.match(/^([A-Za-z0-9_+\-]{2,})\s+(requires|marked|and\b)/)
+           || msg.match(/cycle:\s*([A-Za-z0-9_+\-]+)/);
+    if (!m || m[1] !== modId) continue;
+    if (w.level === 'red')   return 'error';
+    if (w.level === 'amber') return 'warning';
+  }
+  return 'resolved';
+}
+
+function ModTable({ defaultOpen = false, branchSelections, onToggleBranch, expandedWsids, onToggleExpansion }) {
+  const [open, setOpen] = useState(defaultOpen);
+
+  // Group MOD_DB rows by wsid. For wsids with >1 mod, render a single parent
+  // row and an expansion <tr colSpan={COLUMN_COUNT}> with the picker.
+  const groupedByWsid = useMemo(() => {
+    const g = {};
+    for (const m of (D.MOD_DB || [])) {
+      const w = m.wsid || '';
+      if (!w) continue;
+      (g[w] = g[w] || []).push(m);
+    }
+    return g;
+  }, [D.MOD_DB]);
+
+  // Walk SORTED_ORDER and emit one row-spec per wsid (deduped).
+  const rowSpecs = useMemo(() => {
+    const specs = [];
+    const seenWsid = new Set();
+    for (const modId of (D.SORTED_ORDER || [])) {
+      const m = (D.MOD_DB || []).find(x => x.modId === modId);
+      if (!m || !m.wsid) continue;
+      if (seenWsid.has(m.wsid)) continue;
+      seenWsid.add(m.wsid);
+      const branches = groupedByWsid[m.wsid] || [m];
+      const isMulti = branches.length >= 2;
+      specs.push({ wsid: m.wsid, primary: m, branches, isMulti });
+    }
+    // Wsids whose parent had zero selected mods: not in SORTED_ORDER. Append.
+    // NB: Object.keys order for numeric strings - wsids < 2^32 enumerate
+    // ascending, larger ones in insertion order. Spec §6 declares display
+    // position for zero-tick rows implementation-defined.
+    for (const w of Object.keys(groupedByWsid)) {
+      if (!seenWsid.has(w)) {
+        const branches = groupedByWsid[w];
+        specs.push({ wsid: w, primary: branches[0], branches, isMulti: branches.length >= 2 });
+      }
+    }
+    return specs;
+  }, [D.SORTED_ORDER, D.MOD_DB, groupedByWsid]);
+
+  return (
+    <div className="panel table-section">
+      <div className="tbl-head" onClick={() => setOpen(!open)}>
+        <span>mod details</span>
+        <span className="count">· {(D.SORTED_ORDER || []).length} mods</span>
+        <span style={{ color: 'var(--fg-2)', fontSize: 11.5, marginLeft: 8 }}>
+          why everything ended up where it did
+        </span>
+        <span className="chev">{open ? '▾' : '▸'}</span>
+      </div>
+      {open && (
+        <table className="mods-table">
+          <thead>
+            <tr>
+              <th>#</th>
+              <th>mod id</th>
+              <th>workshop id</th>
+              <th>category</th>
+              <th>dependencies</th>
+              <th>load</th>
+            </tr>
+          </thead>
+          <tbody>
+            {rowSpecs.map((spec, i) => {
+              const idx = String(i + 1).padStart(2, '0');
+              if (!spec.isMulti) {
+                const m = spec.primary;
+                const rowState = rowStateForMod(m.modId);
+                const stateGlyph = { resolved: '✓', warning: '⚠', error: '✗' }[rowState] || '·';
+                return (
+                  <tr key={spec.wsid} className={'mod-row mod-row-' + rowState}>
+                    <td className="idx">
+                      <span className="row-state-glyph" aria-hidden="true">{stateGlyph}</span>{idx}
+                    </td>
+                    <td><WsidLink wsid={spec.wsid} className="modid">{m.modId}</WsidLink></td>
+                    <td><span className="wsid">{spec.wsid}</span></td>
+                    <td><span className={'cat ' + m.cat}>{m.cat}</span></td>
+                    <td><span className="deps">{m.deps && m.deps.length ? m.deps.join(', ') : '-'}</span></td>
+                    <td>
+                      {m.pos === 'first' && <span className="pos first">first</span>}
+                      {m.pos === 'last'  && <span className="pos last">last</span>}
+                      {!m.pos && <span className="pos">-</span>}
+                    </td>
+                  </tr>
+                );
+              }
+              // Multi-branch wsid: parent row + (optional) expansion panel.
+              const selected = branchSelections[spec.wsid] || [];
+              const N = spec.branches.length;
+              const X = selected.length;
+              const userTouched = (spec.wsid in branchSelections);
+              const affordance = userTouched ? `✓ ${X} of ${N}` : `▾ ${N} branches`;
+              const firstSelected = spec.branches.find(b => selected.includes(b.modId)) || spec.branches[0];
+              const showAsZero = userTouched && X === 0;
+              const display = showAsZero ? null : firstSelected;
+              const expanded = expandedWsids.has(spec.wsid);
+              const rowState = display ? rowStateForMod(display.modId) : 'resolved';
+              const stateGlyph = { resolved: '✓', warning: '⚠', error: '✗' }[rowState] || '·';
+              return (
+                <React.Fragment key={spec.wsid}>
+                  <tr className={'mod-row mod-row-' + rowState}>
+                    <td className="idx">
+                      <span className="row-state-glyph" aria-hidden="true">{stateGlyph}</span>{idx}
+                    </td>
+                    <td>
+                      <button className="branch-affordance"
+                              aria-expanded={expanded}
+                              onClick={() => onToggleExpansion(spec.wsid)}>
+                        {affordance}
+                      </button>
+                    </td>
+                    <td><span className="wsid">{spec.wsid}</span></td>
+                    <td>{display ? <span className={'cat ' + display.cat}>{display.cat}</span> : '-'}</td>
+                    <td>{display && display.deps && display.deps.length ? display.deps.join(', ') : '-'}</td>
+                    <td>
+                      {display && display.pos === 'first' && <span className="pos first">first</span>}
+                      {display && display.pos === 'last'  && <span className="pos last">last</span>}
+                      {(!display || !display.pos) && <span className="pos">-</span>}
+                    </td>
+                  </tr>
+                  {expanded && (
+                    <BranchPicker
+                      wsid={spec.wsid}
+                      branches={spec.branches}
+                      selected={selected}
+                      userTouched={userTouched}
+                      onToggle={onToggleBranch}
+                    />
+                  )}
+                </React.Fragment>
+              );
+            })}
+          </tbody>
+        </table>
+      )}
+    </div>
+  );
+}
+
+// ── right column dispatcher ────────────────────────────────────────────────
+function BuildToggle({ value, onChange }) {
+  const opts = ['B41', 'B42'];
+  return (
+    <div className="build-toggle" role="radiogroup" aria-label="Project Zomboid build">
+      <span className="build-toggle-label">build</span>
+      {opts.map(o => (
+        <button
+          key={o}
+          role="radio"
+          aria-checked={value === o}
+          className={'build-toggle-btn' + (value === o ? ' is-active' : '')}
+          onClick={() => onChange(o)}
+        >{o}</button>
+      ))}
+    </div>
+  );
+}
+
+function RightColumn({ state, counts, progress, emptyVariant, successVariant, modTableDefault, pzBuild, setPzBuild, branchSelections, onToggleBranch, expandedWsids, onToggleExpansion, onAddWsid, onPickBranch, onSwapWsid, onRemoveWsid, onRetry, previousResult, diffOpen, setDiffOpen }) {
+  // Phase-state mapping: legacy `success` ≈ B+F `done`; legacy `partial` ≈ B+F `queued`/`draining`.
+  const isTerminalDone = state === 'success' || state === 'done';
+  const isInflightPartial = state === 'partial' || state === 'queued' || state === 'draining';
+  const showWarnings = isTerminalDone || isInflightPartial;
+  const showOutputs = isTerminalDone || isInflightPartial;
+
+  return (
+    <>
+      {/* Warnings ABOVE outputs (always-inline treatment). Show the full
+       * list in BOTH terminal-done and inflight-partial: build-mismatch
+       * and other tag-based warnings stabilize as soon as the wsids they
+       * apply to are cached, so truncating to slice(0,1) was hiding load-
+       * order issues from users mid-poll. */}
+      {showWarnings && (
+        <Warnings
+          items={D.WARNINGS}
+          defaultOpen={isTerminalDone}
+          onAddWsid={onAddWsid}
+          onPickBranch={onPickBranch}
+          onSwapWsid={onSwapWsid}
+          onRemoveWsid={onRemoveWsid}
+          onToggleBranch={onToggleBranch}
+        />
+      )}
+
+      {/* Cold cache banner */}
+      {state === 'cold' && (
+        <div className="cold-banner">
+          <span className="err-tag"><span aria-hidden="true">❄</span> cold</span>
+          <div className="err-msg">
+            indexing <span style={{ color: 'var(--acc-info)' }}>{counts.queued} {counts.queued === 1 ? 'mod' : 'mods'}</span> we haven't seen before. try again in ~30s. or don't, we're not your boss.
+          </div>
+        </div>
+      )}
+
+      {/* Error banner. Reason pulled from the most-recent retry/red WARNING
+          when present; otherwise a generic line. The Warnings panel above
+          carries the full detail; this banner is just the headline + retry. */}
+      {state === 'error' && (() => {
+        const warns = (D.WARNINGS || []);
+        const retryWarn = [...warns].reverse().find(w => w.tag === 'retry');
+        const reason = retryWarn ? retryWarn.msg : 'something failed - check warnings above';
+        const hasCached = (D.MOD_DB || []).length > 0;
+        return (
+          <div className="err-banner">
+            <span className="err-tag"><span aria-hidden="true">⚠</span> err</span>
+            <div className="err-msg">
+              {reason}{hasCached ? ' · cached results below still valid' : ''}
+              <div className="err-actions">
+                <button type="button" className="copy-btn" onClick={() => onRetry && onRetry()}>retry</button>
+              </div>
+            </div>
+          </div>
+        );
+      })()}
+
+      {/* Output area */}
+      {state === 'idle' && <EmptyRight variant={emptyVariant} />}
+      {(state === 'loading' || state === 'expanding') && (
+        <div className="right-empty">
+          <span className="big">{state === 'expanding' ? 'expanding your collection…' : 'parsing your collection…'}</span>
+          <span style={{ color: 'var(--fg-2)' }}>resolving dependencies. applying rules. probably fine.</span>
+        </div>
+      )}
+
+      {showOutputs && (
+        <>
+          {isInflightPartial && (
+            <div style={{
+              fontFamily: 'var(--mono)', fontSize: 12, color: 'var(--acc-amber)',
+              padding: '4px 2px', display: 'flex', gap: 8, alignItems: 'center'
+            }}>
+              <span className="dot-led" style={{ background: 'var(--acc-amber)' }}></span>
+              showing cached subset · {counts.queued + (counts.parsing || 0)} mods still in flight
+            </div>
+          )}
+          <div className="diff-toggle-row">
+            <button
+              type="button"
+              className={'diff-toggle' + (diffOpen ? ' open' : '')}
+              onClick={() => setDiffOpen(o => !o)}
+              disabled={!previousResult}
+              title={previousResult ? 'compare to previous sort' : 'sort once first'}
+            >
+              {diffOpen ? '▾ diff' : '▸ diff'}
+            </button>
+          </div>
+          {diffOpen && (
+            <DiffPanel
+              prev={previousResult}
+              curr={{
+                SORTED_ORDER: D.SORTED_ORDER || [],
+                MOD_DB: D.MOD_DB || [],
+                MODS_LINE: D.MODS_LINE || '',
+                WORKSHOP_ITEMS_LINE: D.WORKSHOP_ITEMS_LINE || '',
+              }}
+              onClose={() => setDiffOpen(false)}
+            />
+          )}
+          <BuildToggle value={pzBuild} onChange={setPzBuild} />
+          {successVariant === 'stacked'  && <SuccessStacked  data={{ count: D.SORTED_ORDER.length }} pzBuild={pzBuild} />}
+          {successVariant === 'compact'  && <SuccessCompact  data={{ count: D.SORTED_ORDER.length }} pzBuild={pzBuild} />}
+          {successVariant === 'numbered' && <SuccessNumbered data={{ count: D.SORTED_ORDER.length }} pzBuild={pzBuild} />}
+        </>
+      )}
+
+      {/* Mod details - only when we have something to show */}
+      {(isTerminalDone || isInflightPartial) && (
+        <ModTable
+          defaultOpen={modTableDefault}
+          branchSelections={branchSelections}
+          onToggleBranch={onToggleBranch}
+          expandedWsids={expandedWsids}
+          onToggleExpansion={onToggleExpansion}
+        />
+      )}
+    </>
+  );
+}
+
+// ── default tweak values ────────────────────────────────────────────────────
+const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{
+  "emptyVariant": "docs",
+  "successVariant": "stacked",
+  "stateOverride": "auto",
+  "showTagline": true,
+  "modTableDefault": false,
+  "accentHue": 155
+}/*EDITMODE-END*/;
+
+// ── reported broken mods ────────────────────────────────────────────────────
+
+// Format an ISO timestamp as the literal `HH:MM MM-DD-YYYY` layout the user
+// asked for. 24-hour, zero-padded, locale-independent (uses UTC components
+// so timestamps are identical for everyone — there's no "your local time"
+// disambiguation needed since the value is just a relative recency cue).
+function fmtReportDate(iso) {
+  if (!iso) return '';
+  const d = new Date(iso);
+  if (isNaN(d.getTime())) return iso;
+  const pad = (n) => String(n).padStart(2, '0');
+  const HH = pad(d.getUTCHours());
+  const MM = pad(d.getUTCMinutes());
+  const mo = pad(d.getUTCMonth() + 1);
+  const da = pad(d.getUTCDate());
+  const yy = d.getUTCFullYear();
+  return `${HH}:${MM} ${mo}-${da}-${yy}`;
+}
+
+const _VOTED_KEY = 'sortof.brokenmod.voted';
+function loadVoted() {
+  try { return JSON.parse(localStorage.getItem(_VOTED_KEY) || '{}') || {}; }
+  catch { return {}; }
+}
+function saveVoted(v) {
+  try { localStorage.setItem(_VOTED_KEY, JSON.stringify(v)); } catch {}
+}
+
+function ReportedModsPanel({ onClose }) {
+  const [versions, setVersions] = useState({});
+  const [reports, setReports]   = useState([]);
+  const [search, setSearch]     = useState('');
+  const [wsidIn, setWsidIn]     = useState('');
+  const [verIn, setVerIn]       = useState('');
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError]       = useState('');
+  const [voted, setVoted]       = useState(loadVoted());
+
+  // Initial load: fetch version registry + all reports.
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      try {
+        const [vRes, rRes] = await Promise.all([
+          fetch('/api/pz-versions').then(r => r.json()),
+          fetch('/api/broken-mods').then(r => r.json()),
+        ]);
+        if (cancelled) return;
+        setVersions(vRes || {});
+        setReports(Array.isArray(rRes) ? rRes : []);
+        // Default the dropdown to the first key (typically 'stable' or 'unstable').
+        const firstKey = Object.keys(vRes || {})[0];
+        if (firstKey) setVerIn(firstKey);
+      } catch (e) {
+        if (!cancelled) setError(`load failed: ${e?.message || e}`);
+      }
+    })();
+    return () => { cancelled = true; };
+  }, []);
+
+  async function onSubmit(e) {
+    e.preventDefault();
+    setError('');
+    const wsid = (wsidIn || '').trim();
+    if (!/^\d+$/.test(wsid)) {
+      setError('workshop id must be digits only');
+      return;
+    }
+    if (!verIn) {
+      setError('pick a version');
+      return;
+    }
+    setSubmitting(true);
+    try {
+      const res = await fetch('/api/broken-mods', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ workshop_id: wsid, version: verIn }),
+      });
+      if (!res.ok) {
+        const txt = await res.text();
+        setError(`submit failed: ${res.status} ${txt}`);
+        return;
+      }
+      setWsidIn('');
+      // Refresh list so the upserted entry bubbles to the top.
+      const list = await fetch('/api/broken-mods').then(r => r.json());
+      setReports(Array.isArray(list) ? list : []);
+    } catch (e) {
+      setError(`network error: ${e?.message || e}`);
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  async function onVote(id, direction) {
+    if (voted[id]) return; // already voted this row in either direction
+    try {
+      const res = await fetch(`/api/broken-mods/${id}/vote`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ direction }),
+      });
+      if (!res.ok) return;
+      const counts = await res.json();
+      setReports(prev => prev.map(r => r.id === id
+        ? { ...r, upvotes: counts.upvotes, downvotes: counts.downvotes }
+        : r));
+      const next = { ...voted, [id]: direction };
+      setVoted(next);
+      saveVoted(next);
+    } catch {}
+  }
+
+  const filtered = useMemo(() => {
+    const q = (search || '').trim().toLowerCase();
+    if (!q) return reports;
+    return reports.filter(r =>
+      (r.workshop_id || '').toLowerCase().includes(q) ||
+      (r.mod_name || '').toLowerCase().includes(q),
+    );
+  }, [reports, search]);
+
+  return (
+    <main className="reports-panel">
+      <div className="reports-head">
+        <div className="reports-title">Reported broken mods</div>
+        <div className="reports-blurb">
+          add a workshop id + which PZ build it broke on. duplicates of the
+          same (id, version) bubble back to the top with their existing votes.
+        </div>
+        <form className="reports-form" onSubmit={onSubmit}>
+          <input
+            className="field"
+            type="text"
+            placeholder="workshop id (e.g. 2613146550)"
+            value={wsidIn}
+            onChange={(e) => setWsidIn(e.target.value)}
+            inputMode="numeric"
+            spellCheck={false}
+          />
+          <select
+            className="field"
+            value={verIn}
+            onChange={(e) => setVerIn(e.target.value)}
+          >
+            {Object.entries(versions).map(([k, v]) => (
+              <option key={k} value={k}>{v} ({k})</option>
+            ))}
+          </select>
+          <button
+            type="submit"
+            className="sort-btn"
+            disabled={submitting || !wsidIn.trim() || !verIn}
+          >
+            {submitting ? '…submitting' : '+ report'}
+          </button>
+        </form>
+        {error && <div className="reports-error">{error}</div>}
+        <input
+          className="field reports-search"
+          type="text"
+          placeholder="search by workshop id or mod name…"
+          value={search}
+          onChange={(e) => setSearch(e.target.value)}
+        />
+        <div className="reports-meta">
+          {filtered.length} {filtered.length === 1 ? 'report' : 'reports'}
+          {search && reports.length !== filtered.length
+            ? ` (of ${reports.length})` : ''}
+        </div>
+      </div>
+      <ul className="reports-list">
+        {filtered.length === 0 && (
+          <li className="reports-empty">no reports yet — be the first.</li>
+        )}
+        {filtered.map(r => {
+          const v = voted[r.id]; // 'up' | 'down' | undefined
+          const verLabel = versions[r.version] || r.version;
+          return (
+            <li key={r.id} className="report-row">
+              <div className="report-name">
+                <WsidLink wsid={r.workshop_id}>
+                  {r.mod_name || r.workshop_id}
+                </WsidLink>
+              </div>
+              <div className="report-wsid">{r.workshop_id}</div>
+              <div className="report-ver">
+                <span className="cat ver-pill" title={r.version}>{verLabel}</span>
+              </div>
+              <div className="report-date">{fmtReportDate(r.updated_at)}</div>
+              <div className="report-votes">
+                <button
+                  type="button"
+                  className={'vote-btn up' + (v === 'up' ? ' voted' : '')}
+                  onClick={() => onVote(r.id, 'up')}
+                  disabled={!!v}
+                  title={v === 'up' ? 'you upvoted' : 'agree (broken)'}
+                >▲ {r.upvotes}</button>
+                <button
+                  type="button"
+                  className={'vote-btn down' + (v === 'down' ? ' voted' : '')}
+                  onClick={() => onVote(r.id, 'down')}
+                  disabled={!!v}
+                  title={v === 'down' ? 'you downvoted' : 'disagree (works for me)'}
+                >▼ {r.downvotes}</button>
+              </div>
+            </li>
+          );
+        })}
+      </ul>
+    </main>
+  );
+}
+
+
+// ── main app ────────────────────────────────────────────────────────────────
+function App() {
+  const [t, setTweak] = useTweaks(TWEAK_DEFAULTS);
+  const [view, setView]   = useState('sort');           // sort | reports
+  const [state, setState] = useState('idle');           // idle | loading | partial | success | error | cold
+  const [counts, setCounts] = useState({ cached: 0, queued: 0, parsing: 0, warnings: 0, unknown: 0, nonMod: 0 });
+  const [progress, setProgress] = useState(0);
+  const [input, setInput] = useState(D.SAMPLE_INPUT);
+  const [rules, setRules] = useState('');
+  const [pzBuild, setPzBuild] = useState(() => {
+    try { return localStorage.getItem('sortof.pzBuild') || 'B41'; }
+    catch { return 'B41'; }
+  });
+  const [branchSelections, setBranchSelections] = useState(() => {
+    try {
+      const raw = localStorage.getItem('sortof.branch.selections');
+      if (!raw) return {};
+      const parsed = JSON.parse(raw);
+      return (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) ? parsed : {};
+    } catch { return {}; }
+  });
+  const latestResortSeqRef = useRef(0);  // monotonic; for stale-response drop
+  // Contract: WORKSHOP_ITEMS_LINE, counts.queued, unknown[], non_mod[] are owned
+  // by /api/sort's response for the lifetime of that result set. /api/resort
+  // returns them but the client ignores those fields - wsid subscription and
+  // ID-classification are independent of branch selection (spec §8). Captured
+  // here at /api/sort time, applied on every /api/resort response. Do not
+  // "fix" this back to using resort's fields.
+  const sortContextRef = useRef({ workshopItemsLine: '', originalQueued: 0, unknown: [], nonMod: [] });
+  const pollAbortRef = useRef(null);
+  const [activeJobId, setActiveJobId] = useState(null);
+  const [expandedWsids, setExpandedWsids] = useState(() => new Set());
+  // Diff: snapshot of the result that's about to be replaced; toggle for the
+  // panel. Snapshot is taken at the START of any sort/resort - polling-mid-flight
+  // ticks don't snapshot so the user's prior visible state stays available.
+  const previousResultRef = useRef(null);
+  const [diffOpen, setDiffOpen] = useState(false);
+
+  const onToggleExpansion = (wsid) => {
+    setExpandedWsids(prev => {
+      const next = new Set(prev);
+      if (next.has(wsid)) next.delete(wsid); else next.add(wsid);
+      return next;
+    });
+  };
+
+  const onToggleBranch = (wsid, modId, branches) => {
+    setBranchSelections(prev => {
+      const radio = isRadioMode(branches);
+      const activeSet = new Set(D.SORTED_ORDER || []);
+      const cur = prev[wsid] !== undefined
+        ? prev[wsid]
+        : defaultSelectionForBranches(branches, activeSet);
+      let next;
+      if (radio) {
+        next = [modId];
+      } else {
+        next = cur.includes(modId)
+          ? cur.filter(x => x !== modId)
+          : [...cur, modId];
+      }
+      const updated = { ...prev, [wsid]: next };
+      // Fire-and-forget: state set + resort dispatch.
+      runResort(updated);
+      return updated;
+    });
+  };
+
+  // Append a wsid to the input textarea AND immediately resort so the user
+  // doesn't have to click sort again. Dedupes silently if the wsid is already
+  // in the input. Used by the missing-dep warning's [add modId] action button.
+  const onAddWsid = (wsid /*, modId */) => {
+    if (!wsid) return;
+    const wid = String(wsid);
+    const existing = parseWorkshopInput(input);
+    if (existing.includes(wid)) return;
+    const trimmed = (input || '').replace(/\s+$/, '');
+    const sep = trimmed ? '\n' : '';
+    const newInput = trimmed + sep + wid;
+    setInput(newInput);
+    onSort(newInput);
+  };
+
+  // Remove a wsid from the input textarea token-by-token (preserving the
+  // user's separators) and resort. Used by the build-mismatch warning's
+  // [✕ remove] button. No-op if the wsid isn't present.
+  const onRemoveWsid = (wsid) => {
+    if (!wsid) return;
+    const w = String(wsid);
+    const existing = parseWorkshopInput(input);
+    if (!existing.includes(w)) return;
+    const newInput = (input || '').replace(
+      new RegExp(`(?:^|(?<=[\\s;,]))${w}(?=$|[\\s;,])`, 'g'),
+      ''
+    ).replace(/[\s;,]{2,}/g, m => m.includes('\n') ? '\n' : m[0]).trim();
+    setInput(newInput);
+    onSort(newInput);
+  };
+
+  // Replace `from` with `to` in the input textarea and resort. Used by the
+  // build-mismatch warning's [swap to <other-build version>] button when
+  // the same mod publishes both a B41 and a B42 wsid (e.g., tsarslib at
+  // 2392709985 ↔ 3402491515). Preserves the user's original separators
+  // (newlines, semicolons, commas) by doing a token-level replacement.
+  const onSwapWsid = (from, to) => {
+    if (!from || !to) return;
+    const f = String(from);
+    const t = String(to);
+    const existing = parseWorkshopInput(input);
+    if (!existing.includes(f)) return;
+    if (existing.includes(t)) {
+      // Target already present: just remove `from`. Otherwise we'd dupe.
+      const newInput = (input || '').replace(
+        new RegExp(`(?:^|(?<=[\\s;,]))${f}(?=$|[\\s;,])`, 'g'),
+        ''
+      ).replace(/[\s;,]{2,}/g, m => m.includes('\n') ? '\n' : m[0]).trim();
+      setInput(newInput);
+      onSort(newInput);
+      return;
+    }
+    const newInput = (input || '').replace(
+      new RegExp(`(?<=^|[\\s;,])${f}(?=$|[\\s;,])`, 'g'),
+      t
+    );
+    setInput(newInput);
+    onSort(newInput);
+  };
+
+  // Branch-warning button: lock the wsid to the chosen mod_id and resort.
+  // Always switches to a single selection (radio-style), since the warning
+  // surfaces only the auto-pick case where one branch is canonical.
+  const onPickBranch = (wsid, modId /*, alternatives */) => {
+    setBranchSelections(prev => {
+      const updated = { ...prev, [wsid]: [modId] };
+      runResort(updated);
+      return updated;
+    });
+  };
+
+  // Retry: re-fire the current sort with the current input. The error
+  // banner's [retry] button calls this. Also useful from the keyboard
+  // shortcut path if we ever add one.
+  const onRetry = () => onSort();
+
+  async function runResort(nextSelections) {
+    // Snapshot for the diff panel: capture state before this resort.
+    previousResultRef.current = snapshotForDiff(_liveSortData);
+    // Compose the flat list of selected mod_ids from MOD_DB + nextSelections.
+    // For wsids not in nextSelections, use the §4 default (all-ticked or
+    // first-only depending on radio mode). For wsids with N=1, include the
+    // sole mod_id unconditionally.
+    const byWsid = {};
+    const sourceMods = (_liveSortData?.MOD_DB) || (window.SORTOF_DATA?.MOD_DB) || [];
+    for (const m of sourceMods) {
+      const w = m.wsid || '';
+      if (!w) continue;
+      (byWsid[w] = byWsid[w] || []).push(m);
+    }
+    const ids = [];
+    for (const w of Object.keys(byWsid)) {
+      const branches = byWsid[w];
+      if (branches.length === 1) {
+        ids.push(branches[0].modId);
+        continue;
+      }
+      const stored = nextSelections[w];
+      const activeSet = new Set(D.SORTED_ORDER || []);
+      const eff = stored !== undefined ? stored : defaultSelectionForBranches(branches, activeSet);
+      for (const id of eff) ids.push(id);
+    }
+
+    if (!ids.length) {
+      // Nothing selected; no point hitting the API. Synthesize an empty payload
+      // so the UI shows "0 of N" without dispatching a 400.
+      const ctx = sortContextRef.current;
+      _liveSortData = {
+        ...(_liveSortData || {}),
+        MOD_DB: [], SORTED_ORDER: [],
+        MODS_LINE: '',
+        WORKSHOP_ITEMS_LINE: ctx.workshopItemsLine,
+        MAP_LINE: 'Muldraugh, KY',
+        WARNINGS: [{ tag: 'selection', level: 'amber', msg: 'no mods selected - pick at least one branch' }],
+        pending: [], status: 'success',
+      };
+      setCounts({
+        cached: 0, queued: ctx.originalQueued, parsing: 0, warnings: 1,
+        unknown: ctx.unknown.length, nonMod: ctx.nonMod.length,
+      });
+      return;
+    }
+
+    const seq = latestResortSeqRef.current + 1;
+    latestResortSeqRef.current = seq;
+    try {
+      // Forward the original /api/sort input wsids so the backend can emit
+      // wsid-keyed warnings (build-mismatch, conflict, required-items)
+      // against the user's subscription set even when a mod_id has been
+      // evicted to a different wsid in the cache (B41↔B42 pairs).
+      const ctxWsids = (sortContextRef.current?.workshopItemsLine || '')
+        .split(';').filter(Boolean);
+      const res = await fetch('/api/resort', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'X-Sortof-Seq': String(seq) },
+        body: JSON.stringify({
+          selected_mod_ids: ids,
+          pz_build: pzBuild,
+          input_wsids: ctxWsids,
+        }),
+      });
+      // Drop stale: another resort has issued since this one started.
+      if (seq < latestResortSeqRef.current) return;
+      if (!res.ok) {
+        console.error('resort failed', res.status);
+        _liveSortData = {
+          ...(_liveSortData || {}),
+          WARNINGS: [
+            ...((_liveSortData?.WARNINGS) || []),
+            { tag: 'retry', level: 'red', msg: "couldn't recompute sort - try again" },
+          ],
+        };
+        setCounts(c => ({ ...c, warnings: (c.warnings || 0) + 1 }));
+        return;
+      }
+      const json = await res.json();
+      const ctx = sortContextRef.current;
+      // Spec A §8 ownership: keep the SET of wsids from the original /api/sort
+      // (so toggling branches doesn't change subscription). But REORDER them
+      // by the new sort - first mod's load position drives wsid placement.
+      // Wsids without any selected mods (e.g., all branches deselected) keep
+      // their relative input order at the tail. Same rule for unknown/non_mod.
+      const inputWsids = (ctx.workshopItemsLine || '').split(';').filter(Boolean);
+      const modById = {};
+      for (const m of (json.MOD_DB || [])) modById[m.modId] = m;
+      const wsidFirstPos = new Map();
+      (json.SORTED_ORDER || []).forEach((modId, idx) => {
+        const m = modById[modId];
+        if (m && m.wsid && !wsidFirstPos.has(m.wsid)) wsidFirstPos.set(m.wsid, idx);
+      });
+      const known = inputWsids.filter(w => wsidFirstPos.has(w))
+        .sort((a, b) => wsidFirstPos.get(a) - wsidFirstPos.get(b));
+      const tail = inputWsids.filter(w => !wsidFirstPos.has(w));
+      const reorderedWsl = inputWsids.length
+        ? [...known, ...tail].join(';') + ';'
+        : '';
+      _liveSortData = { ...json, WORKSHOP_ITEMS_LINE: reorderedWsl };
+      const cached = (json.MOD_DB || []).length;
+      const warns  = (json.WARNINGS || []).length;
+      setCounts({
+        cached, queued: ctx.originalQueued, parsing: 0, warnings: warns,
+        unknown: ctx.unknown.length, nonMod: ctx.nonMod.length,
+      });
+      setState(json.status || 'success');
+    } catch (e) {
+      console.error('resort threw', e);
+      _liveSortData = {
+        ...(_liveSortData || {}),
+        WARNINGS: [
+          ...((_liveSortData?.WARNINGS) || []),
+          { tag: 'retry', level: 'red', msg: "couldn't recompute sort - try again" },
+        ],
+      };
+      setCounts(c => ({ ...c, warnings: (c.warnings || 0) + 1 }));
+    }
+  }
+
+  useEffect(() => {
+    try { localStorage.setItem('sortof.pzBuild', pzBuild); } catch {}
+  }, [pzBuild]);
+
+  useEffect(() => {
+    try {
+      localStorage.setItem('sortof.branch.selections', JSON.stringify(branchSelections));
+    } catch {}
+  }, [branchSelections]);
+
+  useEffect(() => {
+    function onStorage(e) {
+      if (e.key !== 'sortof.branch.selections' || e.newValue === null) return;
+      try {
+        const parsed = JSON.parse(e.newValue);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+          setBranchSelections(parsed);
+          runResort(parsed);
+        }
+      } catch {}
+    }
+    window.addEventListener('storage', onStorage);
+    return () => window.removeEventListener('storage', onStorage);
+  }, []);
+
+  useEffect(() => {
+    // Hydrate-driven resort: after the user submits and gets MOD_DB,
+    // if branchSelections has entries, re-run sort against them.
+    if (state === 'success' || state === 'partial' || state === 'done') {
+      if (Object.keys(branchSelections).length > 0) {
+        runResort(branchSelections);
+      }
+    }
+    // eslint-disable-next-line
+  }, [state]);
+
+  const tagline = useMemo(() => {
+    const taglines = [
+      'sorted. sort of.',
+      'your mods, sort of in order.',
+      'a server-admin\u2019s tiny dignity.',
+      'mostly correct, mostly the time.',
+    ];
+    return taglines[0];
+  }, []);
+
+  // accent override
+  useEffect(() => {
+    const root = document.documentElement;
+    root.style.setProperty('--acc-green', `oklch(0.74 0.10 ${t.accentHue})`);
+    root.style.setProperty('--acc-green-bg', `oklch(0.74 0.10 ${t.accentHue} / 0.12)`);
+  }, [t.accentHue]);
+
+  // state override (preview from Tweaks)
+  useEffect(() => {
+    if (t.stateOverride && t.stateOverride !== 'auto') {
+      runState(t.stateOverride);
+    }
+    // eslint-disable-next-line
+  }, [t.stateOverride]);
+
+  const timersRef = useRef([]);
+  const clearTimers = () => { timersRef.current.forEach(clearTimeout); timersRef.current = []; };
+
+  function runState(target) {
+    clearTimers();
+    if (target === 'idle')    { setState('idle');    setProgress(0); setCounts({ cached: 0, queued: 0, parsing: 0, warnings: 0 }); return; }
+    if (target === 'error')   { setState('error');   setProgress(100); setCounts({ cached: 7, queued: 0, parsing: 0, warnings: 1 }); return; }
+    if (target === 'cold')    { setState('cold');    setProgress(45); setCounts({ cached: 0, queued: 3, parsing: 0, warnings: 0 }); return; }
+    if (target === 'loading') { setState('loading'); setProgress(20); setCounts({ cached: 0, queued: 11, parsing: 1, warnings: 0 }); return; }
+    if (target === 'partial') { setState('partial'); setProgress(70); setCounts({ cached: 7, queued: 4, parsing: 1, warnings: 1 }); return; }
+    if (target === 'success') { setState('success'); setProgress(100); setCounts({ cached: 11, queued: 0, parsing: 0, warnings: D.WARNINGS.length }); return; }
+  }
+
+  async function onSort(inputOverride) {
+    if (t.stateOverride !== 'auto') {
+      // user is in preview mode; ignore real flow
+      return;
+    }
+    // Allow callers (e.g., the missing-dep [add] button) to submit a freshly
+    // computed input without waiting for setInput's async state update.
+    // Type-check defensively: `onClick={onSort}` passes a React synthetic
+    // event as arg 0 - reject anything that isn't a string and fall back
+    // to the state input.
+    const submitInput = typeof inputOverride === 'string' ? inputOverride : input;
+    // Snapshot the about-to-be-replaced result so the [diff] button can
+    // surface what changed. Skip if there's nothing meaningful yet.
+    previousResultRef.current = snapshotForDiff(_liveSortData);
+    clearTimers();
+    setState('loading');
+    setProgress(15);
+    setCounts({ cached: 0, queued: 0, parsing: 0, warnings: 0 });
+
+    try {
+      const res = await fetch('/api/sort', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ input: submitInput, rules, pz_build: pzBuild })
+      });
+      if (!res.ok) {
+        const txt = await res.text();
+        console.error('sort failed', res.status, txt);
+        const detail = (() => { try { return JSON.parse(txt).detail || txt; } catch { return txt || `status ${res.status}`; } })();
+        _liveSortData = {
+          WARNINGS: [{ tag: 'retry', level: 'red', msg: `sort failed (${res.status}): ${detail}` }],
+        };
+        setState('error');
+        setProgress(100);
+        setCounts({ cached: 0, queued: 0, parsing: 0, warnings: 1 });
+        return;
+      }
+      const json = await res.json();
+      if (json.job_id) {
+        // Async path - start polling and let the loop drive state.
+        if (pollAbortRef.current) { pollAbortRef.current.abort(); }
+        const ctrl = new AbortController();
+        pollAbortRef.current = ctrl;
+        setActiveJobId(json.job_id);
+
+        pollJobLoop(json.job_id, ctrl.signal, (r) => {
+          if (r.kind !== 'ok') return;
+          const b = r.body;
+          if (b.result) {
+            _liveSortData = b.result;
+            sortContextRef.current = {
+              workshopItemsLine: (b.result.WORKSHOP_ITEMS_LINE) || '',
+              originalQueued: (b.result.pending || []).length,
+              unknown: b.result.unknown || [],
+              nonMod:  b.result.non_mod || [],
+            };
+          }
+          const total = b.counts.cached + b.counts.queued + b.counts.draining;
+          setProgress(
+            b.phase === 'expanding'
+              ? 5
+              : 5 + Math.round(90 * b.counts.cached / Math.max(1, total))
+          );
+          // The legacy UI label is "parsing"; backend phase is "draining". Same thing.
+          setCounts({
+            cached: b.counts.cached,
+            queued: b.counts.queued,
+            parsing: b.counts.draining,
+            warnings: ((b.result && b.result.WARNINGS) || []).length,
+            unknown: ((b.result && b.result.unknown) || []).length,
+            nonMod:  ((b.result && b.result.non_mod) || []).length,
+          });
+          setState(b.phase);
+        }).then((final) => {
+          setActiveJobId(null);
+          pollAbortRef.current = null;
+          if (final.kind === 'expired') {
+            setState('error');
+            _liveSortData = {
+              ...(_liveSortData || {}),
+              WARNINGS: [
+                ...((_liveSortData?.WARNINGS) || []),
+                { tag: 'retry', level: 'red', msg: 'this job expired - re-submit' },
+              ],
+            };
+          } else if (final.kind === 'error') {
+            setState('error');
+            _liveSortData = {
+              ...(_liveSortData || {}),
+              WARNINGS: [
+                ...((_liveSortData?.WARNINGS) || []),
+                { tag: 'retry', level: 'red', msg: `polling failed (status ${final.status}) - re-submit` },
+              ],
+            };
+          }
+        });
+        return;
+      }
+      // Sync fast path - existing code follows.
+      _liveSortData = json;
+      const unknownArr = json.unknown || [];
+      const nonModArr  = json.non_mod || [];
+      sortContextRef.current = {
+        workshopItemsLine: json.WORKSHOP_ITEMS_LINE || '',
+        originalQueued: (json.pending || []).length,
+        unknown: unknownArr,
+        nonMod: nonModArr,
+      };
+      const cached  = (json.MOD_DB || []).length;
+      const queued  = (json.pending || []).length;
+      const warns   = (json.WARNINGS || []).length;
+      setProgress(100);
+      setCounts({
+        cached, queued, parsing: 0, warnings: warns,
+        unknown: unknownArr.length, nonMod: nonModArr.length,
+      });
+      setState(json.status || 'success');
+    } catch (e) {
+      console.error('sort threw', e);
+      _liveSortData = {
+        WARNINGS: [{ tag: 'retry', level: 'red', msg: `network error: ${e && e.message ? e.message : String(e)}` }],
+      };
+      setState('error');
+      setProgress(100);
+      setCounts({ cached: 0, queued: 0, parsing: 0, warnings: 1 });
+    }
+  }
+
+  function onClear() {
+    clearTimers();
+    setInput('');
+    setRules('');
+    setState('idle');
+    setProgress(0);
+    setCounts({ cached: 0, queued: 0, parsing: 0, warnings: 0 });
+  }
+
+  return (
+    <div className="shell">
+      <Header
+        tagline={t.showTagline ? tagline : null}
+        view={view}
+        onReport={() => setView('reports')}
+        onSort={() => setView('sort')}
+      />
+
+      {view === 'reports' && (
+        <ReportedModsPanel onClose={() => setView('sort')} />
+      )}
+
+      {view === 'sort' && (
+      <main className="app">
+        {/* LEFT */}
+        <section className="col">
+          <div className="build-prepick">
+            <BuildToggle value={pzBuild} onChange={setPzBuild} />
+            <span className="build-prepick-hint">
+              pick first - we'll flag mods tagged for the other build
+            </span>
+          </div>
+          <div>
+            <div className="label-row">
+              <span className="label">workshop ids or collection url</span>
+              <span className="label-meta">{parseWorkshopInput(input).length} ids</span>
+            </div>
+            <textarea
+              className="field input-main"
+              placeholder={"2169435993;2392709985;2487022075\nor newline-separated, or paste a steamcommunity.com URL"}
+              value={input}
+              onChange={(e) => setInput(e.target.value)}
+              spellCheck={false}
+            />
+          </div>
+
+          <details className="collapsible">
+            <summary>sorting rules (optional)</summary>
+            <div className="label-row">
+              <span className="label">sorting_rules.txt</span>
+              <span className="label-meta">{rules ? `${rules.split('\n').length} lines` : 'empty - defaults will apply'}</span>
+            </div>
+            <textarea
+              className="field input-rules"
+              placeholder={D.SAMPLE_RULES}
+              value={rules}
+              onChange={(e) => setRules(e.target.value)}
+              spellCheck={false}
+            />
+          </details>
+
+          <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+            <button
+              type="button"
+              className="sort-btn"
+              onClick={onSort}
+              disabled={state === 'loading' || !input.trim()}
+            >
+              {state === 'loading'
+                ? <span className="spin" aria-hidden="true"></span>
+                : <span className="btn-glyph" aria-hidden="true">{(!input.trim()) ? '—' : '▶'}</span>}
+              {state === 'loading' ? 'sorting…' : 'sort'}
+            </button>
+            {activeJobId && (
+              <button
+                type="button"
+                className="cancel-btn"
+                style={{ height: 40, padding: '0 14px', width: 'auto', marginTop: 0 }}
+                onClick={() => {
+                  const jobId = activeJobId;
+                  if (pollAbortRef.current) pollAbortRef.current.abort();
+                  setActiveJobId(null);
+                  setState('idle');
+                  setProgress(0);
+                  setCounts({ cached: 0, queued: 0, parsing: 0, warnings: 0, unknown: 0, nonMod: 0 });
+                  // Fire-and-forget DELETE; server handles idempotency.
+                  fetch(`/api/jobs/${jobId}`, { method: 'DELETE' })
+                    .catch((e) => console.warn('cancel DELETE failed', e));
+                }}
+              ><span aria-hidden="true">✗</span> cancel</button>
+            )}
+            {(input.trim() || state !== 'idle') && (
+              <button type="button" className="clear-btn" onClick={onClear}>
+                <span aria-hidden="true">✗</span> clear
+              </button>
+            )}
+          </div>
+
+          <StatusStrip state={state} counts={counts} progress={progress} />
+
+          {(() => {
+            // State indicator: color + glyph + label triple per brief mapping.
+            const stateMap = {
+              idle:      { cls: 'idle',      glyph: '●' },
+              loading:   { cls: 'working',   glyph: '⏵' },
+              expanding: { cls: 'working',   glyph: '⏵' },
+              queued:    { cls: 'queued',    glyph: '●' },
+              draining:  { cls: 'draining',  glyph: '⏵' },
+              partial:   { cls: 'draining',  glyph: '⏵' },
+              done:      { cls: 'done',      glyph: '✓' },
+              success:   { cls: 'done',      glyph: '✓' },
+              cold:      { cls: 'warning',   glyph: '⚠' },
+              error:     { cls: 'failed',    glyph: '✗' },
+              failed:    { cls: 'failed',    glyph: '✗' },
+            };
+            const m = stateMap[state] || stateMap.idle;
+            return (
+              <div className={'state-tag state-tag-' + m.cls}>
+                <span className="state-tag-glyph" aria-hidden="true">{m.glyph}</span>
+                state: {state}{t.stateOverride !== 'auto' ? ' (forced via tweaks)' : ''}
+              </div>
+            );
+          })()}
+        </section>
+
+        {/* RIGHT */}
+        <section className="col">
+          <RightColumn
+            state={state}
+            counts={counts}
+            progress={progress}
+            emptyVariant={t.emptyVariant}
+            successVariant={t.successVariant}
+            modTableDefault={t.modTableDefault}
+            pzBuild={pzBuild}
+            setPzBuild={setPzBuild}
+            branchSelections={branchSelections}
+            onToggleBranch={onToggleBranch}
+            expandedWsids={expandedWsids}
+            onToggleExpansion={onToggleExpansion}
+            onAddWsid={onAddWsid}
+            onPickBranch={onPickBranch}
+            onSwapWsid={onSwapWsid}
+            onRemoveWsid={onRemoveWsid}
+            onRetry={onRetry}
+            previousResult={previousResultRef.current}
+            diffOpen={diffOpen}
+            setDiffOpen={setDiffOpen}
+          />
+        </section>
+      </main>
+      )}
+
+      <Footer />
+
+      {(typeof window !== 'undefined' &&
+        new URLSearchParams(window.location.search).has('tweaks')) && (
+        <TweaksPanel title="Tweaks">
+          <TweakSection label="State preview" />
+          <TweakSelect
+            label="Force state"
+            value={t.stateOverride}
+            options={[
+              { value: 'auto',    label: 'auto (drive via Sort)' },
+              { value: 'idle',    label: 'idle / empty' },
+              { value: 'loading', label: 'loading' },
+              { value: 'partial', label: 'partial (cached + in-flight)' },
+              { value: 'success', label: 'success' },
+              { value: 'error',   label: 'error' },
+              { value: 'cold',    label: 'cold cache miss' },
+            ]}
+            onChange={(v) => setTweak('stateOverride', v)}
+          />
+          <TweakButton label="run a fresh sort" onClick={() => { setTweak('stateOverride', 'auto'); setTimeout(onSort, 50); }} />
+
+          <TweakSection label="Empty-state variant" />
+          <TweakRadio
+            label="Layout"
+            value={t.emptyVariant}
+            options={[
+              { value: 'bare',   label: 'bare' },
+              { value: 'worked', label: 'worked' },
+              { value: 'docs',   label: 'docs' },
+            ]}
+            onChange={(v) => setTweak('emptyVariant', v)}
+          />
+
+          <TweakSection label="Success-state variant" />
+          <TweakRadio
+            label="Output style"
+            value={t.successVariant}
+            options={[
+              { value: 'stacked',  label: 'stacked' },
+              { value: 'compact',  label: 'compact' },
+              { value: 'numbered', label: 'numbered' },
+            ]}
+            onChange={(v) => setTweak('successVariant', v)}
+          />
+
+          <TweakSection label="Chrome" />
+          <TweakToggle  label="Show tagline"             value={t.showTagline}      onChange={(v) => setTweak('showTagline', v)} />
+          <TweakToggle  label="Mod details open by default" value={t.modTableDefault} onChange={(v) => setTweak('modTableDefault', v)} />
+          <TweakSlider  label="Accent hue (green band)" value={t.accentHue} min={120} max={170} step={1} onChange={(v) => setTweak('accentHue', v)} />
+        </TweaksPanel>
+      )}
+    </div>
+  );
+}
+
+ReactDOM.createRoot(document.getElementById('root')).render(<App />);
diff --git a/frontend/sortof-data.jsx b/frontend/sortof-data.jsx
new file mode 100644
index 0000000..cec01c1
--- /dev/null
+++ b/frontend/sortof-data.jsx
@@ -0,0 +1,56 @@
+// Canned dataset for the sortof prototype. Faked but plausible PZ mods.
+// Used to drive the various states deterministically.
+
+const SAMPLE_INPUT = '2169435993;2392709985;2487022075;2685168362;2784607980;1299328280;2865072321;2566953935;2200148440;2503622437;2702991010';
+
+const SAMPLE_RULES = `# sorting_rules.txt
+# pin libraries first; map packs last
+load_first: tsarslib, modoptions, BB_CommonLib
+load_last:  Muldraugh_KY, BedfordFalls, Eerie_County
+incompatible: BetterFlashlight | RealisticFlashlight
+require: TMC_TrueActions => tsarslib
+`;
+
+// id, workshopId, modId, name, category (lib|map|gameplay|qol|content), deps, conflictsWith, loadFirst, loadLast
+const MOD_DB = [
+  { wsid: '2169435993', modId: 'modoptions',       name: 'Mod Options',          cat: 'lib',      deps: [], pos: 'first' },
+  { wsid: '2392709985', modId: 'tsarslib',         name: "Tsar's Common Library", cat: 'lib',     deps: [], pos: 'first' },
+  { wsid: '2487022075', modId: 'TMC_TrueActions',  name: 'True Actions',         cat: 'gameplay', deps: ['tsarslib'], pos: '' },
+  { wsid: '2685168362', modId: 'BB_CommonLib',     name: 'BB Common Library',    cat: 'lib',      deps: [], pos: 'first' },
+  { wsid: '2784607980', modId: 'BetterFlashlight', name: 'Better Flashlight',    cat: 'qol',      deps: ['modoptions'], pos: '', conflicts: ['RealisticFlashlight'] },
+  { wsid: '1299328280', modId: 'ORGM',             name: 'ORGM Rechambered',     cat: 'content',  deps: [] },
+  { wsid: '2865072321', modId: 'Brita_Weapons',    name: 'Brita\u2019s Weapon Pack', cat: 'content', deps: ['Brita_Armor'] }, // missing dep
+  { wsid: '2566953935', modId: 'autotsar_trailers', name: 'Autotsar Trailers',   cat: 'content',  deps: ['tsarslib'] },
+  { wsid: '2200148440', modId: 'Eerie_County',     name: 'Eerie County',         cat: 'map',      deps: ['Muldraugh_KY'], pos: 'last' },
+  { wsid: '2503622437', modId: 'BedfordFalls',     name: 'Bedford Falls',        cat: 'map',      deps: [], pos: 'last' },
+  { wsid: '2702991010', modId: 'Muldraugh_KY',     name: 'Muldraugh, KY',        cat: 'map',      deps: [], pos: 'last', isMap: true, mapName: 'Muldraugh, KY' },
+];
+
+// Sorted output (per faked sorting rules)
+const SORTED_ORDER = [
+  'modoptions', 'tsarslib', 'BB_CommonLib',
+  'TMC_TrueActions', 'BetterFlashlight',
+  'ORGM', 'Brita_Weapons', 'autotsar_trailers',
+  'Muldraugh_KY', 'BedfordFalls', 'Eerie_County'
+];
+
+const WORKSHOP_ITEMS_LINE = SORTED_ORDER
+  .map(id => MOD_DB.find(m => m.modId === id).wsid)
+  .join(';');
+
+const MODS_LINE = SORTED_ORDER.join(';');
+
+const MAP_LINE = 'Muldraugh, KY';
+
+const WARNINGS = [
+  { tag: 'missing', level: 'red',   msg: 'Brita_Weapons requires Brita_Armor - not in your list.' },
+  { tag: 'cycle',   level: 'amber', msg: 'soft cycle: Eerie_County → Muldraugh_KY → (resolved by load_last rule)' },
+  { tag: 'conflict',level: 'amber', msg: 'BetterFlashlight and RealisticFlashlight marked incompatible. only the former is enabled.' },
+];
+
+window.SORTOF_DATA = {
+  SAMPLE_INPUT, SAMPLE_RULES,
+  MOD_DB, SORTED_ORDER,
+  WORKSHOP_ITEMS_LINE, MODS_LINE, MAP_LINE,
+  WARNINGS,
+};
diff --git a/frontend/tweaks-panel.jsx b/frontend/tweaks-panel.jsx
new file mode 100644
index 0000000..7f7623c
--- /dev/null
+++ b/frontend/tweaks-panel.jsx
@@ -0,0 +1,425 @@
+
+// tweaks-panel.jsx
+// Reusable Tweaks shell + form-control helpers.
+//
+// Owns the host protocol (listens for __activate_edit_mode / __deactivate_edit_mode,
+// posts __edit_mode_available / __edit_mode_set_keys / __edit_mode_dismissed) so
+// individual prototypes don't re-roll it. Ships a consistent set of controls so you
+// don't hand-draw <input type="range">, segmented radios, steppers, etc.
+//
+// Usage (in an HTML file that loads React + Babel):
+//
+//   const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{
+//     "primaryColor": "#D97757",
+//     "fontSize": 16,
+//     "density": "regular",
+//     "dark": false
+//   }/*EDITMODE-END*/;
+//
+//   function App() {
+//     const [t, setTweak] = useTweaks(TWEAK_DEFAULTS);
+//     return (
+//       <div style={{ fontSize: t.fontSize, color: t.primaryColor }}>
+//         Hello
+//         <TweaksPanel>
+//           <TweakSection label="Typography" />
+//           <TweakSlider label="Font size" value={t.fontSize} min={10} max={32} unit="px"
+//                        onChange={(v) => setTweak('fontSize', v)} />
+//           <TweakRadio  label="Density" value={t.density}
+//                        options={['compact', 'regular', 'comfy']}
+//                        onChange={(v) => setTweak('density', v)} />
+//           <TweakSection label="Theme" />
+//           <TweakColor  label="Primary" value={t.primaryColor}
+//                        onChange={(v) => setTweak('primaryColor', v)} />
+//           <TweakToggle label="Dark mode" value={t.dark}
+//                        onChange={(v) => setTweak('dark', v)} />
+//         </TweaksPanel>
+//       </div>
+//     );
+//   }
+//
+// ─────────────────────────────────────────────────────────────────────────────
+
+const __TWEAKS_STYLE = `
+  .twk-panel{position:fixed;right:16px;bottom:16px;z-index:2147483646;width:280px;
+    max-height:calc(100vh - 32px);display:flex;flex-direction:column;
+    background:rgba(250,249,247,.78);color:#29261b;
+    -webkit-backdrop-filter:blur(24px) saturate(160%);backdrop-filter:blur(24px) saturate(160%);
+    border:.5px solid rgba(255,255,255,.6);border-radius:14px;
+    box-shadow:0 1px 0 rgba(255,255,255,.5) inset,0 12px 40px rgba(0,0,0,.18);
+    font:11.5px/1.4 ui-sans-serif,system-ui,-apple-system,sans-serif;overflow:hidden}
+  .twk-hd{display:flex;align-items:center;justify-content:space-between;
+    padding:10px 8px 10px 14px;cursor:move;user-select:none}
+  .twk-hd b{font-size:12px;font-weight:600;letter-spacing:.01em}
+  .twk-x{appearance:none;border:0;background:transparent;color:rgba(41,38,27,.55);
+    width:22px;height:22px;border-radius:6px;cursor:default;font-size:13px;line-height:1}
+  .twk-x:hover{background:rgba(0,0,0,.06);color:#29261b}
+  .twk-body{padding:2px 14px 14px;display:flex;flex-direction:column;gap:10px;
+    overflow-y:auto;overflow-x:hidden;min-height:0;
+    scrollbar-width:thin;scrollbar-color:rgba(0,0,0,.15) transparent}
+  .twk-body::-webkit-scrollbar{width:8px}
+  .twk-body::-webkit-scrollbar-track{background:transparent;margin:2px}
+  .twk-body::-webkit-scrollbar-thumb{background:rgba(0,0,0,.15);border-radius:4px;
+    border:2px solid transparent;background-clip:content-box}
+  .twk-body::-webkit-scrollbar-thumb:hover{background:rgba(0,0,0,.25);
+    border:2px solid transparent;background-clip:content-box}
+  .twk-row{display:flex;flex-direction:column;gap:5px}
+  .twk-row-h{flex-direction:row;align-items:center;justify-content:space-between;gap:10px}
+  .twk-lbl{display:flex;justify-content:space-between;align-items:baseline;
+    color:rgba(41,38,27,.72)}
+  .twk-lbl>span:first-child{font-weight:500}
+  .twk-val{color:rgba(41,38,27,.5);font-variant-numeric:tabular-nums}
+
+  .twk-sect{font-size:10px;font-weight:600;letter-spacing:.06em;text-transform:uppercase;
+    color:rgba(41,38,27,.45);padding:10px 0 0}
+  .twk-sect:first-child{padding-top:0}
+
+  .twk-field{appearance:none;width:100%;height:26px;padding:0 8px;
+    border:.5px solid rgba(0,0,0,.1);border-radius:7px;
+    background:rgba(255,255,255,.6);color:inherit;font:inherit;outline:none}
+  .twk-field:focus{border-color:rgba(0,0,0,.25);background:rgba(255,255,255,.85)}
+  select.twk-field{padding-right:22px;
+    background-image:url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='10' height='6' viewBox='0 0 10 6'><path fill='rgba(0,0,0,.5)' d='M0 0h10L5 6z'/></svg>");
+    background-repeat:no-repeat;background-position:right 8px center}
+
+  .twk-slider{appearance:none;-webkit-appearance:none;width:100%;height:4px;margin:6px 0;
+    border-radius:999px;background:rgba(0,0,0,.12);outline:none}
+  .twk-slider::-webkit-slider-thumb{-webkit-appearance:none;appearance:none;
+    width:14px;height:14px;border-radius:50%;background:#fff;
+    border:.5px solid rgba(0,0,0,.12);box-shadow:0 1px 3px rgba(0,0,0,.2);cursor:default}
+  .twk-slider::-moz-range-thumb{width:14px;height:14px;border-radius:50%;
+    background:#fff;border:.5px solid rgba(0,0,0,.12);box-shadow:0 1px 3px rgba(0,0,0,.2);cursor:default}
+
+  .twk-seg{position:relative;display:flex;padding:2px;border-radius:8px;
+    background:rgba(0,0,0,.06);user-select:none}
+  .twk-seg-thumb{position:absolute;top:2px;bottom:2px;border-radius:6px;
+    background:rgba(255,255,255,.9);box-shadow:0 1px 2px rgba(0,0,0,.12);
+    transition:left .15s cubic-bezier(.3,.7,.4,1),width .15s}
+  .twk-seg.dragging .twk-seg-thumb{transition:none}
+  .twk-seg button{appearance:none;position:relative;z-index:1;flex:1;border:0;
+    background:transparent;color:inherit;font:inherit;font-weight:500;min-height:22px;
+    border-radius:6px;cursor:default;padding:4px 6px;line-height:1.2;
+    overflow-wrap:anywhere}
+
+  .twk-toggle{position:relative;width:32px;height:18px;border:0;border-radius:999px;
+    background:rgba(0,0,0,.15);transition:background .15s;cursor:default;padding:0}
+  .twk-toggle[data-on="1"]{background:#34c759}
+  .twk-toggle i{position:absolute;top:2px;left:2px;width:14px;height:14px;border-radius:50%;
+    background:#fff;box-shadow:0 1px 2px rgba(0,0,0,.25);transition:transform .15s}
+  .twk-toggle[data-on="1"] i{transform:translateX(14px)}
+
+  .twk-num{display:flex;align-items:center;height:26px;padding:0 0 0 8px;
+    border:.5px solid rgba(0,0,0,.1);border-radius:7px;background:rgba(255,255,255,.6)}
+  .twk-num-lbl{font-weight:500;color:rgba(41,38,27,.6);cursor:ew-resize;
+    user-select:none;padding-right:8px}
+  .twk-num input{flex:1;min-width:0;height:100%;border:0;background:transparent;
+    font:inherit;font-variant-numeric:tabular-nums;text-align:right;padding:0 8px 0 0;
+    outline:none;color:inherit;-moz-appearance:textfield}
+  .twk-num input::-webkit-inner-spin-button,.twk-num input::-webkit-outer-spin-button{
+    -webkit-appearance:none;margin:0}
+  .twk-num-unit{padding-right:8px;color:rgba(41,38,27,.45)}
+
+  .twk-btn{appearance:none;height:26px;padding:0 12px;border:0;border-radius:7px;
+    background:rgba(0,0,0,.78);color:#fff;font:inherit;font-weight:500;cursor:default}
+  .twk-btn:hover{background:rgba(0,0,0,.88)}
+  .twk-btn.secondary{background:rgba(0,0,0,.06);color:inherit}
+  .twk-btn.secondary:hover{background:rgba(0,0,0,.1)}
+
+  .twk-swatch{appearance:none;-webkit-appearance:none;width:56px;height:22px;
+    border:.5px solid rgba(0,0,0,.1);border-radius:6px;padding:0;cursor:default;
+    background:transparent;flex-shrink:0}
+  .twk-swatch::-webkit-color-swatch-wrapper{padding:0}
+  .twk-swatch::-webkit-color-swatch{border:0;border-radius:5.5px}
+  .twk-swatch::-moz-color-swatch{border:0;border-radius:5.5px}
+`;
+
+// ── useTweaks ───────────────────────────────────────────────────────────────
+// Single source of truth for tweak values. setTweak persists via the host
+// (__edit_mode_set_keys → host rewrites the EDITMODE block on disk).
+function useTweaks(defaults) {
+  const [values, setValues] = React.useState(defaults);
+  // Accepts either setTweak('key', value) or setTweak({ key: value, ... }) so a
+  // useState-style call doesn't write a "[object Object]" key into the persisted
+  // JSON block.
+  const setTweak = React.useCallback((keyOrEdits, val) => {
+    const edits = typeof keyOrEdits === 'object' && keyOrEdits !== null
+      ? keyOrEdits : { [keyOrEdits]: val };
+    setValues((prev) => ({ ...prev, ...edits }));
+    window.parent.postMessage({ type: '__edit_mode_set_keys', edits }, '*');
+  }, []);
+  return [values, setTweak];
+}
+
+// ── TweaksPanel ─────────────────────────────────────────────────────────────
+// Floating shell. Registers the protocol listener BEFORE announcing
+// availability - if the announce ran first, the host's activate could land
+// before our handler exists and the toolbar toggle would silently no-op.
+// The close button posts __edit_mode_dismissed so the host's toolbar toggle
+// flips off in lockstep; the host echoes __deactivate_edit_mode back which
+// is what actually hides the panel.
+function TweaksPanel({ title = 'Tweaks', children }) {
+  const [open, setOpen] = React.useState(false);
+  const dragRef = React.useRef(null);
+  const offsetRef = React.useRef({ x: 16, y: 16 });
+  const PAD = 16;
+
+  const clampToViewport = React.useCallback(() => {
+    const panel = dragRef.current;
+    if (!panel) return;
+    const w = panel.offsetWidth, h = panel.offsetHeight;
+    const maxRight = Math.max(PAD, window.innerWidth - w - PAD);
+    const maxBottom = Math.max(PAD, window.innerHeight - h - PAD);
+    offsetRef.current = {
+      x: Math.min(maxRight, Math.max(PAD, offsetRef.current.x)),
+      y: Math.min(maxBottom, Math.max(PAD, offsetRef.current.y)),
+    };
+    panel.style.right = offsetRef.current.x + 'px';
+    panel.style.bottom = offsetRef.current.y + 'px';
+  }, []);
+
+  React.useEffect(() => {
+    if (!open) return;
+    clampToViewport();
+    if (typeof ResizeObserver === 'undefined') {
+      window.addEventListener('resize', clampToViewport);
+      return () => window.removeEventListener('resize', clampToViewport);
+    }
+    const ro = new ResizeObserver(clampToViewport);
+    ro.observe(document.documentElement);
+    return () => ro.disconnect();
+  }, [open, clampToViewport]);
+
+  React.useEffect(() => {
+    const onMsg = (e) => {
+      const t = e?.data?.type;
+      if (t === '__activate_edit_mode') setOpen(true);
+      else if (t === '__deactivate_edit_mode') setOpen(false);
+    };
+    window.addEventListener('message', onMsg);
+    window.parent.postMessage({ type: '__edit_mode_available' }, '*');
+    return () => window.removeEventListener('message', onMsg);
+  }, []);
+
+  const dismiss = () => {
+    setOpen(false);
+    window.parent.postMessage({ type: '__edit_mode_dismissed' }, '*');
+  };
+
+  const onDragStart = (e) => {
+    const panel = dragRef.current;
+    if (!panel) return;
+    const r = panel.getBoundingClientRect();
+    const sx = e.clientX, sy = e.clientY;
+    const startRight = window.innerWidth - r.right;
+    const startBottom = window.innerHeight - r.bottom;
+    const move = (ev) => {
+      offsetRef.current = {
+        x: startRight - (ev.clientX - sx),
+        y: startBottom - (ev.clientY - sy),
+      };
+      clampToViewport();
+    };
+    const up = () => {
+      window.removeEventListener('mousemove', move);
+      window.removeEventListener('mouseup', up);
+    };
+    window.addEventListener('mousemove', move);
+    window.addEventListener('mouseup', up);
+  };
+
+  if (!open) return null;
+  return (
+    <>
+      <style>{__TWEAKS_STYLE}</style>
+      <div ref={dragRef} className="twk-panel" data-noncommentable=""
+           style={{ right: offsetRef.current.x, bottom: offsetRef.current.y }}>
+        <div className="twk-hd" onMouseDown={onDragStart}>
+          <b>{title}</b>
+          <button className="twk-x" aria-label="Close tweaks"
+                  onMouseDown={(e) => e.stopPropagation()}
+                  onClick={dismiss}>✕</button>
+        </div>
+        <div className="twk-body">{children}</div>
+      </div>
+    </>
+  );
+}
+
+// ── Layout helpers ──────────────────────────────────────────────────────────
+
+function TweakSection({ label, children }) {
+  return (
+    <>
+      <div className="twk-sect">{label}</div>
+      {children}
+    </>
+  );
+}
+
+function TweakRow({ label, value, children, inline = false }) {
+  return (
+    <div className={inline ? 'twk-row twk-row-h' : 'twk-row'}>
+      <div className="twk-lbl">
+        <span>{label}</span>
+        {value != null && <span className="twk-val">{value}</span>}
+      </div>
+      {children}
+    </div>
+  );
+}
+
+// ── Controls ────────────────────────────────────────────────────────────────
+
+function TweakSlider({ label, value, min = 0, max = 100, step = 1, unit = '', onChange }) {
+  return (
+    <TweakRow label={label} value={`${value}${unit}`}>
+      <input type="range" className="twk-slider" min={min} max={max} step={step}
+             value={value} onChange={(e) => onChange(Number(e.target.value))} />
+    </TweakRow>
+  );
+}
+
+function TweakToggle({ label, value, onChange }) {
+  return (
+    <div className="twk-row twk-row-h">
+      <div className="twk-lbl"><span>{label}</span></div>
+      <button type="button" className="twk-toggle" data-on={value ? '1' : '0'}
+              role="switch" aria-checked={!!value}
+              onClick={() => onChange(!value)}><i /></button>
+    </div>
+  );
+}
+
+function TweakRadio({ label, value, options, onChange }) {
+  const trackRef = React.useRef(null);
+  const [dragging, setDragging] = React.useState(false);
+  const opts = options.map((o) => (typeof o === 'object' ? o : { value: o, label: o }));
+  const idx = Math.max(0, opts.findIndex((o) => o.value === value));
+  const n = opts.length;
+
+  // The active value is read by pointer-move handlers attached for the lifetime
+  // of a drag - ref it so a stale closure doesn't fire onChange for every move.
+  const valueRef = React.useRef(value);
+  valueRef.current = value;
+
+  const segAt = (clientX) => {
+    const r = trackRef.current.getBoundingClientRect();
+    const inner = r.width - 4;
+    const i = Math.floor(((clientX - r.left - 2) / inner) * n);
+    return opts[Math.max(0, Math.min(n - 1, i))].value;
+  };
+
+  const onPointerDown = (e) => {
+    setDragging(true);
+    const v0 = segAt(e.clientX);
+    if (v0 !== valueRef.current) onChange(v0);
+    const move = (ev) => {
+      if (!trackRef.current) return;
+      const v = segAt(ev.clientX);
+      if (v !== valueRef.current) onChange(v);
+    };
+    const up = () => {
+      setDragging(false);
+      window.removeEventListener('pointermove', move);
+      window.removeEventListener('pointerup', up);
+    };
+    window.addEventListener('pointermove', move);
+    window.addEventListener('pointerup', up);
+  };
+
+  return (
+    <TweakRow label={label}>
+      <div ref={trackRef} role="radiogroup" onPointerDown={onPointerDown}
+           className={dragging ? 'twk-seg dragging' : 'twk-seg'}>
+        <div className="twk-seg-thumb"
+             style={{ left: `calc(2px + ${idx} * (100% - 4px) / ${n})`,
+                      width: `calc((100% - 4px) / ${n})` }} />
+        {opts.map((o) => (
+          <button key={o.value} type="button" role="radio" aria-checked={o.value === value}>
+            {o.label}
+          </button>
+        ))}
+      </div>
+    </TweakRow>
+  );
+}
+
+function TweakSelect({ label, value, options, onChange }) {
+  return (
+    <TweakRow label={label}>
+      <select className="twk-field" value={value} onChange={(e) => onChange(e.target.value)}>
+        {options.map((o) => {
+          const v = typeof o === 'object' ? o.value : o;
+          const l = typeof o === 'object' ? o.label : o;
+          return <option key={v} value={v}>{l}</option>;
+        })}
+      </select>
+    </TweakRow>
+  );
+}
+
+function TweakText({ label, value, placeholder, onChange }) {
+  return (
+    <TweakRow label={label}>
+      <input className="twk-field" type="text" value={value} placeholder={placeholder}
+             onChange={(e) => onChange(e.target.value)} />
+    </TweakRow>
+  );
+}
+
+function TweakNumber({ label, value, min, max, step = 1, unit = '', onChange }) {
+  const clamp = (n) => {
+    if (min != null && n < min) return min;
+    if (max != null && n > max) return max;
+    return n;
+  };
+  const startRef = React.useRef({ x: 0, val: 0 });
+  const onScrubStart = (e) => {
+    e.preventDefault();
+    startRef.current = { x: e.clientX, val: value };
+    const decimals = (String(step).split('.')[1] || '').length;
+    const move = (ev) => {
+      const dx = ev.clientX - startRef.current.x;
+      const raw = startRef.current.val + dx * step;
+      const snapped = Math.round(raw / step) * step;
+      onChange(clamp(Number(snapped.toFixed(decimals))));
+    };
+    const up = () => {
+      window.removeEventListener('pointermove', move);
+      window.removeEventListener('pointerup', up);
+    };
+    window.addEventListener('pointermove', move);
+    window.addEventListener('pointerup', up);
+  };
+  return (
+    <div className="twk-num">
+      <span className="twk-num-lbl" onPointerDown={onScrubStart}>{label}</span>
+      <input type="number" value={value} min={min} max={max} step={step}
+             onChange={(e) => onChange(clamp(Number(e.target.value)))} />
+      {unit && <span className="twk-num-unit">{unit}</span>}
+    </div>
+  );
+}
+
+function TweakColor({ label, value, onChange }) {
+  return (
+    <div className="twk-row twk-row-h">
+      <div className="twk-lbl"><span>{label}</span></div>
+      <input type="color" className="twk-swatch" value={value}
+             onChange={(e) => onChange(e.target.value)} />
+    </div>
+  );
+}
+
+function TweakButton({ label, onClick, secondary = false }) {
+  return (
+    <button type="button" className={secondary ? 'twk-btn secondary' : 'twk-btn'}
+            onClick={onClick}>{label}</button>
+  );
+}
+
+Object.assign(window, {
+  useTweaks, TweaksPanel, TweakSection, TweakRow,
+  TweakSlider, TweakToggle, TweakRadio, TweakSelect,
+  TweakText, TweakNumber, TweakColor, TweakButton,
+});
diff --git a/init/01_schema.sql b/init/01_schema.sql
new file mode 100644
index 0000000..ce65e54
--- /dev/null
+++ b/init/01_schema.sql
@@ -0,0 +1,127 @@
+-- pzsort schema
+-- Run as: psql -U pzsort -d pzsort -f schema.sql
+
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+-- -----------------------------------------------------------------------------
+-- workshop_meta
+-- Cheap, refreshed often via Steam ISteamRemoteStorage/GetPublishedFileDetails.
+-- Keyed by Steam publishedfileid (text to avoid bigint surprises).
+-- time_updated is the cache-invalidation key for mod_parsed.
+-- -----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS workshop_meta (
+    workshop_id          TEXT PRIMARY KEY,
+    title                TEXT,
+    description          TEXT,
+    tags                 TEXT[]      NOT NULL DEFAULT '{}',
+    creator_steamid      TEXT,
+    time_created         BIGINT,                 -- unix ts from Steam
+    time_updated         BIGINT      NOT NULL,   -- unix ts; cache invalidation key
+    file_size            BIGINT,
+    preview_url          TEXT,
+    consumer_app_id      INTEGER,                -- 108600 for PZ
+    visibility           INTEGER,                -- 0=public, 1=friends, 2=private
+    banned               BOOLEAN     NOT NULL DEFAULT FALSE,
+    last_checked_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+    created_at           TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS workshop_meta_last_checked_idx
+    ON workshop_meta (last_checked_at);
+
+-- -----------------------------------------------------------------------------
+-- mod_parsed
+-- Expensive: requires DepotDownloader fetch. Only refreshed when
+-- workshop_meta.time_updated changes vs parsed_at_time_updated.
+-- One workshop item can yield N rows (multi-mod packages).
+-- -----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS mod_parsed (
+    workshop_id              TEXT NOT NULL REFERENCES workshop_meta(workshop_id) ON DELETE CASCADE,
+    mod_id                   TEXT NOT NULL,                -- mod.info `id=`
+    name                     TEXT NOT NULL DEFAULT '',
+    category                 TEXT NOT NULL DEFAULT 'undefined',
+    requirements             TEXT[] NOT NULL DEFAULT '{}',
+    load_after               TEXT[] NOT NULL DEFAULT '{}',
+    load_before              TEXT[] NOT NULL DEFAULT '{}',
+    incompatible_mods        TEXT[] NOT NULL DEFAULT '{}',
+    load_first               TEXT NOT NULL DEFAULT 'off',
+    load_last                TEXT NOT NULL DEFAULT 'off',
+    tags                     TEXT[] NOT NULL DEFAULT '{}',
+    maps                     TEXT[] NOT NULL DEFAULT '{}',  -- map folder names
+    raw_mod_info             TEXT,                          -- original file for debugging
+    version_min              TEXT,                          -- e.g. 41.55
+    parsed_at_time_updated   BIGINT NOT NULL,               -- snapshot of workshop_meta.time_updated at parse
+    parsed_at                TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (workshop_id, mod_id)
+);
+
+CREATE INDEX IF NOT EXISTS mod_parsed_mod_id_idx ON mod_parsed (mod_id);
+
+-- -----------------------------------------------------------------------------
+-- download_jobs
+-- Work queue for the DepotDownloader worker. One job per workshop_id.
+-- Worker dequeues (status='queued') ORDER BY priority DESC, created_at ASC.
+-- -----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS download_jobs (
+    id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    workshop_id  TEXT NOT NULL,
+    status       TEXT NOT NULL DEFAULT 'queued',  -- queued|downloading|parsing|done|failed
+    priority     INTEGER NOT NULL DEFAULT 0,       -- higher first
+    attempts     INTEGER NOT NULL DEFAULT 0,
+    error        TEXT,
+    requested_by TEXT,                              -- IP hash or user token; for rate limiting
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    completed_at TIMESTAMPTZ
+);
+
+CREATE INDEX IF NOT EXISTS download_jobs_dequeue_idx
+    ON download_jobs (status, priority DESC, created_at ASC)
+    WHERE status = 'queued';
+
+CREATE INDEX IF NOT EXISTS download_jobs_workshop_idx
+    ON download_jobs (workshop_id);
+
+-- Trigger: keep updated_at fresh
+CREATE OR REPLACE FUNCTION touch_updated_at() RETURNS TRIGGER AS $$
+BEGIN
+    NEW.updated_at = now();
+    RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS download_jobs_touch ON download_jobs;
+CREATE TRIGGER download_jobs_touch
+    BEFORE UPDATE ON download_jobs
+    FOR EACH ROW
+    EXECUTE FUNCTION touch_updated_at();
+
+-- -----------------------------------------------------------------------------
+-- collections
+-- Cache for ISteamRemoteStorage/GetCollectionDetails results.
+-- Collections expand to N child workshop_ids; we cache that mapping.
+-- -----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS collections (
+    collection_id        TEXT PRIMARY KEY,
+    title                TEXT,
+    child_workshop_ids   TEXT[] NOT NULL DEFAULT '{}',
+    last_fetched_at      TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- -----------------------------------------------------------------------------
+-- sort_requests
+-- Optional: log of submitted sort jobs for debugging + abuse triage.
+-- Not required for sort to function. Keep TTL short via a cron.
+-- -----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS sort_requests (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    input_workshop_ids  TEXT[] NOT NULL,
+    input_collection_id TEXT,
+    cache_hits      INTEGER NOT NULL DEFAULT 0,
+    cache_misses    INTEGER NOT NULL DEFAULT 0,
+    requested_by    TEXT,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS sort_requests_created_idx
+    ON sort_requests (created_at);
diff --git a/init/02_sort_jobs.sql b/init/02_sort_jobs.sql
new file mode 100644
index 0000000..03fec76
--- /dev/null
+++ b/init/02_sort_jobs.sql
@@ -0,0 +1,29 @@
+-- Async sort jobs: lifecycle + result for collection expansion + cold drains.
+-- Created 2026-05-01 (Spec B+F).
+-- Depends on: 01_schema.sql (touch_updated_at() function, pgcrypto extension).
+-- Docker initdb runs files alphabetically, so 01_ executes first; for live
+-- one-shot psql application against an existing DB, both prerequisites
+-- already exist.
+
+CREATE TABLE IF NOT EXISTS sort_jobs (
+    job_id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    phase            TEXT NOT NULL CHECK (phase IN ('expanding','queued','draining','done','failed')),
+    phase_started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    created_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at       TIMESTAMPTZ NOT NULL DEFAULT now(),
+    input_raw        TEXT NOT NULL,
+    collection_ids   TEXT[] NOT NULL DEFAULT '{}',
+    wsids            TEXT[],
+    rules_raw        TEXT,
+    result_json      JSONB,
+    failure_reason   TEXT
+);
+
+CREATE INDEX IF NOT EXISTS sort_jobs_phase_idx ON sort_jobs (phase);
+CREATE INDEX IF NOT EXISTS sort_jobs_updated_idx ON sort_jobs (updated_at);
+
+DROP TRIGGER IF EXISTS sort_jobs_touch ON sort_jobs;
+CREATE TRIGGER sort_jobs_touch
+    BEFORE UPDATE ON sort_jobs
+    FOR EACH ROW
+    EXECUTE FUNCTION touch_updated_at();
diff --git a/init/03_mod_id_conflicts.sql b/init/03_mod_id_conflicts.sql
new file mode 100644
index 0000000..0e8f2be
--- /dev/null
+++ b/init/03_mod_id_conflicts.sql
@@ -0,0 +1,13 @@
+-- Records every mod_id eviction the worker performs (one wsid claiming a mod_id
+-- previously held by another). Used by /api/sort to warn the user when their
+-- input includes multiple wsids that declare the same mod_id (PZ silently
+-- loads only one; the others' folders end up dead weight on the server).
+CREATE TABLE IF NOT EXISTS mod_id_conflicts (
+    mod_id          TEXT NOT NULL,
+    evicting_wsid   TEXT NOT NULL,
+    evicted_wsid    TEXT NOT NULL,
+    recorded_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
+    PRIMARY KEY (mod_id, evicting_wsid, evicted_wsid)
+);
+CREATE INDEX IF NOT EXISTS mod_id_conflicts_evicted_idx  ON mod_id_conflicts (evicted_wsid);
+CREATE INDEX IF NOT EXISTS mod_id_conflicts_evicting_idx ON mod_id_conflicts (evicting_wsid);
diff --git a/init/04_required_wsids.sql b/init/04_required_wsids.sql
new file mode 100644
index 0000000..81b79f9
--- /dev/null
+++ b/init/04_required_wsids.sql
@@ -0,0 +1,12 @@
+-- Required Items scraped from each mod's Steam Workshop page (the "Required
+-- Items" section). Steam's anonymous GetPublishedFileDetails endpoint does
+-- not include children for individual mods, so we scrape the public HTML.
+--
+-- Use cases:
+--   1. Auto-resolving missing-dep warnings: when a cached mod_id Y is
+--      missing dep X, we look at Y's source wsid's required_wsids and
+--      auto-queue any uncached wsids — the next sort resolves X.
+--   2. Surfacing "↗ add <wsid>" actions for unresolved deps so the user
+--      can pull them with one click.
+ALTER TABLE workshop_meta
+    ADD COLUMN IF NOT EXISTS required_wsids TEXT[] NOT NULL DEFAULT '{}';
diff --git a/init/05_required_wsids_scraped_at.sql b/init/05_required_wsids_scraped_at.sql
new file mode 100644
index 0000000..7b2b990
--- /dev/null
+++ b/init/05_required_wsids_scraped_at.sql
@@ -0,0 +1,7 @@
+-- Track when we last successfully scraped a wsid's "Required Items" section.
+-- Without this, we can't distinguish "successfully scraped, zero required
+-- items" (a stable empty []) from "never scraped" (also empty {} per schema
+-- default). Backfill jobs and the missing-dep auto-resolver use it to skip
+-- already-known-empty pages.
+ALTER TABLE workshop_meta
+    ADD COLUMN IF NOT EXISTS required_scraped_at TIMESTAMPTZ;
diff --git a/init/06_sort_jobs_pz_build.sql b/init/06_sort_jobs_pz_build.sql
new file mode 100644
index 0000000..88feb13
--- /dev/null
+++ b/init/06_sort_jobs_pz_build.sql
@@ -0,0 +1,5 @@
+-- pz_build captured at job creation so the polling-path result regen
+-- (`_build_result_for_job`) can emit build-mismatch warnings against the
+-- user's chosen build, matching what the sync path emits.
+ALTER TABLE sort_jobs
+    ADD COLUMN IF NOT EXISTS pz_build TEXT;
diff --git a/init/07_mod_parsed_is_addon.sql b/init/07_mod_parsed_is_addon.sql
new file mode 100644
index 0000000..cf86295
--- /dev/null
+++ b/init/07_mod_parsed_is_addon.sql
@@ -0,0 +1,7 @@
+-- Marks a mod_id as an "optional add-on" within a multi-mod wsid, signaled
+-- by `Optional add-on` (or close variants) at the head of the mod.info
+-- description. Spec A's branch picker treats addon mods additively
+-- (default-off, tickable to load alongside the primary) instead of as a
+-- mutually-exclusive flavor variant.
+ALTER TABLE mod_parsed
+    ADD COLUMN IF NOT EXISTS is_addon BOOLEAN NOT NULL DEFAULT FALSE;
diff --git a/init/08_broken_mod_reports.sql b/init/08_broken_mod_reports.sql
new file mode 100644
index 0000000..8efce75
--- /dev/null
+++ b/init/08_broken_mod_reports.sql
@@ -0,0 +1,20 @@
+-- Community-reported broken mods. Each (workshop_id, version) is unique;
+-- re-submitting the same pair upserts (refreshes updated_at) while
+-- preserving accumulated votes. ORDER BY updated_at DESC drives the
+-- list view, so a re-report bubbles the entry back to the top with
+-- previous up/down counts intact.
+CREATE TABLE IF NOT EXISTS broken_mod_reports (
+    id           BIGSERIAL PRIMARY KEY,
+    workshop_id  TEXT NOT NULL,
+    mod_name     TEXT,
+    version      TEXT NOT NULL,
+    upvotes      INTEGER NOT NULL DEFAULT 0,
+    downvotes    INTEGER NOT NULL DEFAULT 0,
+    created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
+    UNIQUE (workshop_id, version)
+);
+CREATE INDEX IF NOT EXISTS broken_mod_reports_updated_idx
+    ON broken_mod_reports (updated_at DESC);
+CREATE INDEX IF NOT EXISTS broken_mod_reports_wsid_idx
+    ON broken_mod_reports (workshop_id);
diff --git a/precacher/precacher.py b/precacher/precacher.py
new file mode 100644
index 0000000..b24db3d
--- /dev/null
+++ b/precacher/precacher.py
@@ -0,0 +1,210 @@
+"""sortof precacher (Spec E): warm the cache by enqueueing the top-N PZ
+Workshop wsids across four time windows (3 months, 6 months, 1 year, all time)
+that aren't already known.
+
+Pure feeder for the existing drain pipeline. Inserts into download_jobs and
+returns; the drain workers (sortof-drain@1..4) handle the actual DD pulls.
+
+Run on demand:
+    /opt/sortof/worker/.venv/bin/python /opt/sortof/precacher/precacher.py
+
+Reuses the worker's venv (httpx + asyncpg) since dependencies overlap exactly.
+Reads DATABASE_URL from /opt/sortof/.env.
+
+Skip rule: a wsid is "already known" iff a row exists in mod_parsed for it
+(any state) OR a row exists in download_jobs for it (any status). This is
+deliberately conservative - we never re-queue a wsid the system has seen
+before, including ones that previously failed (banned, deleted, no_mod_info).
+Forced re-queue is the API's job, not the precacher's.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import re
+import sys
+import urllib.parse
+from pathlib import Path
+from typing import Dict, List, Set, Tuple
+
+import asyncpg
+import httpx
+from dotenv import load_dotenv
+
+ENV_PATH = Path(__file__).resolve().parent.parent / ".env"
+
+
+def _build_dsn() -> str:
+    """Mirror api/db.py: prefer DATABASE_URL, else build from POSTGRES_* parts."""
+    load_dotenv(ENV_PATH)
+    explicit = os.environ.get("DATABASE_URL")
+    if explicit:
+        return explicit
+    user = os.environ["POSTGRES_USER"]
+    pw = urllib.parse.quote(os.environ["POSTGRES_PASSWORD"], safe="")
+    name = os.environ["POSTGRES_DB"]
+    host = os.environ.get("POSTGRES_HOST", "127.0.0.1")
+    port = os.environ.get("POSTGRES_PORT", "5439")
+    return f"postgresql://{user}:{pw}@{host}:{port}/{name}"
+
+PZ_APPID = 108600
+BROWSE_URL = "https://steamcommunity.com/workshop/browse/"
+PER_PAGE = 30           # Steam HTML default; observed cap.
+RATE_LIMIT_S = 0.6      # polite gap between page fetches.
+DEFAULT_TARGET = 1000
+
+# Window label -> (browsesort, days param). days < 0 means "all time" -
+# Steam's totalvotes sort doesn't take a days param.
+WINDOWS: List[Tuple[str, str, int]] = [
+    ("3m",  "mostpopular", 90),
+    ("6m",  "mostpopular", 180),
+    ("1y",  "mostpopular", 365),
+    ("all", "totalvotes",  -1),
+]
+
+WSID_RE = re.compile(r'data-publishedfileid="(\d{6,12})"')
+
+log = logging.getLogger("sortof.precacher")
+
+
+async def fetch_page(http: httpx.AsyncClient, sort: str, days: int, page: int) -> List[str]:
+    params: Dict[str, object] = {
+        "appid": PZ_APPID,
+        "browsesort": sort,
+        "section": "readytouseitems",
+        "p": page,
+        "numperpage": PER_PAGE,
+    }
+    if days > 0:
+        params["days"] = days
+    r = await http.get(BROWSE_URL, params=params, timeout=30.0)
+    r.raise_for_status()
+    # De-dupe within the page (the same wsid can appear in multiple HTML blocks).
+    return list(dict.fromkeys(WSID_RE.findall(r.text)))
+
+
+async def collect_top_wsids(
+    http: httpx.AsyncClient, sort: str, days: int, target: int,
+) -> List[str]:
+    """Walk pages until we have `target` distinct wsids or pagination exhausts."""
+    seen: Set[str] = set()
+    out: List[str] = []
+    page = 1
+    consecutive_empty = 0
+    while len(out) < target:
+        try:
+            ids = await fetch_page(http, sort, days, page)
+        except httpx.HTTPError as e:
+            log.warning("page %d fetch failed: %s", page, e)
+            break
+        if not ids:
+            consecutive_empty += 1
+            if consecutive_empty >= 2:
+                break
+        else:
+            consecutive_empty = 0
+        added = 0
+        for wid in ids:
+            if wid in seen:
+                continue
+            seen.add(wid)
+            out.append(wid)
+            added += 1
+            if len(out) >= target:
+                break
+        # If a page returns only duplicates we've already seen, we're cycling.
+        if ids and added == 0:
+            break
+        page += 1
+        await asyncio.sleep(RATE_LIMIT_S)
+    return out
+
+
+async def already_known(conn: asyncpg.Connection, wsids: List[str]) -> Set[str]:
+    """Returns the subset of wsids that the system has seen - either parsed
+    in mod_parsed or sitting in download_jobs (any status). The conservative
+    superset; precacher never re-queues anything previously touched."""
+    if not wsids:
+        return set()
+    rows = await conn.fetch(
+        """
+        SELECT workshop_id FROM mod_parsed WHERE workshop_id = ANY($1::text[])
+        UNION
+        SELECT workshop_id FROM download_jobs WHERE workshop_id = ANY($1::text[])
+        """,
+        wsids,
+    )
+    return {r["workshop_id"] for r in rows}
+
+
+async def enqueue(conn: asyncpg.Connection, wsids: List[str]) -> int:
+    """INSERT each wsid into download_jobs. Mirrors the API's queue-and-dedup
+    pattern: skip if a row already exists (race-safe via per-iteration tx)."""
+    n = 0
+    for wid in wsids:
+        async with conn.transaction():
+            existing = await conn.fetchval(
+                "SELECT 1 FROM download_jobs WHERE workshop_id = $1 LIMIT 1",
+                wid,
+            )
+            if existing is None:
+                await conn.execute(
+                    "INSERT INTO download_jobs (workshop_id, status) VALUES ($1, 'queued')",
+                    wid,
+                )
+                n += 1
+    return n
+
+
+async def main(target: int = DEFAULT_TARGET) -> int:
+    try:
+        dsn = _build_dsn()
+    except KeyError as e:
+        log.error("missing required env var: %s", e)
+        return 2
+
+    pool = await asyncpg.create_pool(dsn=dsn, min_size=1, max_size=2)
+    http = httpx.AsyncClient(headers={"User-Agent": "sortof-precacher/1.0"})
+
+    totals = {"fetched": 0, "skipped_known": 0, "enqueued": 0}
+    try:
+        for label, sort, days in WINDOWS:
+            log.info(
+                "window=%s sort=%s days=%d: collecting up to %d wsids",
+                label, sort, days, target,
+            )
+            wsids = await collect_top_wsids(http, sort, days, target)
+            log.info("window=%s: collected %d wsids", label, len(wsids))
+
+            async with pool.acquire() as conn:
+                known = await already_known(conn, wsids)
+                fresh = [w for w in wsids if w not in known]
+                inserted = await enqueue(conn, fresh)
+
+            log.info(
+                "window=%s: known=%d fresh=%d enqueued=%d",
+                label, len(known), len(fresh), inserted,
+            )
+            totals["fetched"] += len(wsids)
+            totals["skipped_known"] += len(known)
+            totals["enqueued"] += inserted
+    finally:
+        await http.aclose()
+        await pool.close()
+
+    log.info(
+        "precache run done: fetched=%d skipped_known=%d enqueued=%d",
+        totals["fetched"], totals["skipped_known"], totals["enqueued"],
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+    target = int(sys.argv[1]) if len(sys.argv) > 1 else DEFAULT_TARGET
+    sys.exit(asyncio.run(main(target)))
diff --git a/worker/drain.py b/worker/drain.py
new file mode 100644
index 0000000..4f4012f
--- /dev/null
+++ b/worker/drain.py
@@ -0,0 +1,229 @@
+"""sortof download_jobs drainer.
+
+Long-running asyncio loop that claims queued jobs from download_jobs,
+calls worker.process_one() to materialize mod_parsed rows via
+DepotDownloader, and updates job status. Single connection per process;
+multiple instances are safe because claims use FOR UPDATE SKIP LOCKED.
+
+Manual requeue (after a transient failure):
+    UPDATE download_jobs
+    SET status='queued', attempts=0, error=NULL
+    WHERE id='<uuid>';
+
+Bulk requeue everything that hit MAX_ATTEMPTS:
+    UPDATE download_jobs
+    SET status='queued', attempts=0, error=NULL
+    WHERE status='failed';
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import signal
+import sys
+import time
+import urllib.parse
+from pathlib import Path
+
+import asyncpg
+from dotenv import load_dotenv
+
+from worker import (
+    DEFAULT_DD_PATH,
+    fetch_workshop_details,
+    process_one,
+)
+
+ENV_PATH = Path(__file__).resolve().parent.parent / ".env"
+
+IDLE_SLEEP_S = 5
+HEARTBEAT_S = 60
+BATCH_SIZE = 1
+MAX_ATTEMPTS = 5
+STALE_RECLAIM_MIN = 30
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(name)s %(message)s",
+)
+log = logging.getLogger("sortof.drain")
+
+
+CLAIM_SQL = """
+UPDATE download_jobs
+SET status='downloading', attempts=attempts+1, updated_at=now()
+WHERE id IN (
+    SELECT id FROM download_jobs
+    WHERE status='queued' AND attempts < $1
+    ORDER BY priority DESC, created_at ASC
+    LIMIT $2
+    FOR UPDATE SKIP LOCKED
+)
+RETURNING id, workshop_id, attempts
+"""
+
+RECLAIM_SQL = f"""
+UPDATE download_jobs
+SET status='queued', updated_at=now()
+WHERE status='downloading'
+  AND updated_at < now() - interval '{STALE_RECLAIM_MIN} minutes'
+RETURNING id
+"""
+
+DEPTH_SQL = """
+SELECT COUNT(*) FROM download_jobs
+WHERE status='queued' AND attempts < $1
+"""
+
+DONE_SQL = """
+UPDATE download_jobs
+SET status='done', completed_at=now(), updated_at=now(), error=NULL
+WHERE id=$1
+"""
+
+FAIL_SQL = """
+UPDATE download_jobs
+SET status='failed', updated_at=now(), error=$2
+WHERE id=$1
+"""
+
+
+def build_dsn() -> str:
+    load_dotenv(ENV_PATH)
+    explicit = os.environ.get("DATABASE_URL")
+    if explicit:
+        return explicit
+    user = os.environ["POSTGRES_USER"]
+    pw = urllib.parse.quote(os.environ["POSTGRES_PASSWORD"], safe="")
+    name = os.environ["POSTGRES_DB"]
+    host = os.environ.get("POSTGRES_HOST", "127.0.0.1")
+    port = os.environ.get("POSTGRES_PORT", "5439")
+    return f"postgresql://{user}:{pw}@{host}:{port}/{name}"
+
+
+def resolve_dd_path() -> Path:
+    """Resolve the DepotDownloader binary or fail loudly.
+
+    Order of precedence: $DD_PATH env var, then worker.py's argparse
+    default (DEFAULT_DD_PATH).
+    """
+    candidates: list[Path] = []
+    env_dd = os.environ.get("DD_PATH")
+    if env_dd:
+        candidates.append(Path(env_dd))
+    candidates.append(Path(DEFAULT_DD_PATH))
+    for p in candidates:
+        if p.is_file():
+            return p
+    raise RuntimeError(
+        "DepotDownloader not found. Tried: "
+        + ", ".join(str(c) for c in candidates)
+        + ". Set DD_PATH or place the binary at the default path."
+    )
+
+
+async def reclaim_stale(conn: asyncpg.Connection) -> int:
+    rows = await conn.fetch(RECLAIM_SQL)
+    return len(rows)
+
+
+async def claim_batch(conn: asyncpg.Connection, n: int):
+    return await conn.fetch(CLAIM_SQL, MAX_ATTEMPTS, n)
+
+
+async def queue_depth(conn: asyncpg.Connection) -> int:
+    return await conn.fetchval(DEPTH_SQL, MAX_ATTEMPTS)
+
+
+async def mark_done(conn: asyncpg.Connection, job_id) -> None:
+    await conn.execute(DONE_SQL, job_id)
+
+
+async def mark_failed(conn: asyncpg.Connection, job_id, msg: str) -> None:
+    await conn.execute(FAIL_SQL, job_id, msg[:500])
+
+
+async def run() -> int:
+    dd_path = resolve_dd_path()  # raises before opening DB if missing
+
+    dsn = build_dsn()
+    conn = await asyncpg.connect(dsn=dsn)
+
+    stop = asyncio.Event()
+    loop = asyncio.get_running_loop()
+
+    def _handle(sig: signal.Signals):
+        log.info("drain shutting down (signal=%s)", sig.name)
+        stop.set()
+
+    for s in (signal.SIGTERM, signal.SIGINT):
+        loop.add_signal_handler(s, _handle, s)
+
+    try:
+        n_reclaimed = await reclaim_stale(conn)
+        log.info(
+            "drain starting, reclaimed %d stale, dd_path=%s",
+            n_reclaimed, dd_path,
+        )
+
+        last_heartbeat = 0.0
+        while not stop.is_set():
+            rows = await claim_batch(conn, BATCH_SIZE)
+
+            if not rows:
+                now = time.monotonic()
+                if now - last_heartbeat >= HEARTBEAT_S:
+                    depth = await queue_depth(conn)
+                    log.info("idle, queue depth=%d", depth)
+                    last_heartbeat = now
+                try:
+                    await asyncio.wait_for(stop.wait(), timeout=IDLE_SLEEP_S)
+                except asyncio.TimeoutError:
+                    pass
+                continue
+
+            ids = [r["workshop_id"] for r in rows]
+            try:
+                details = await asyncio.to_thread(fetch_workshop_details, ids)
+            except Exception as e:
+                log.warning("steam fetch failed: %s", e)
+                for r in rows:
+                    await mark_failed(conn, r["id"], "steam fetch error")
+                continue
+
+            for r in rows:
+                wid = r["workshop_id"]
+                attempt = r["attempts"]
+                log.info("claimed wsid=%s attempt=%d", wid, attempt)
+                detail = details.get(wid)
+                if not detail or detail.get("result") != 1:
+                    reason = (
+                        f"steam result={detail.get('result') if detail else 'none'}"
+                    )
+                    log.info("failed wsid=%s reason=%s", wid, reason)
+                    await mark_failed(conn, r["id"], reason)
+                    continue
+                try:
+                    outcome = await process_one(conn, wid, detail, dd_path, False)
+                except Exception as e:
+                    log.exception("drain exception wsid=%s", wid)
+                    await mark_failed(conn, r["id"], str(e)[:500])
+                    continue
+                if outcome in ("hit", "refreshed"):
+                    log.info("done wsid=%s outcome=%s", wid, outcome)
+                    await mark_done(conn, r["id"])
+                else:
+                    reason = f"process_one={outcome}"
+                    log.info("failed wsid=%s reason=%s", wid, reason)
+                    await mark_failed(conn, r["id"], reason)
+    finally:
+        await conn.close()
+        log.info("drain stopped")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(asyncio.run(run()))
diff --git a/worker/mlos_sort.py b/worker/mlos_sort.py
new file mode 100644
index 0000000..f765ce8
--- /dev/null
+++ b/worker/mlos_sort.py
@@ -0,0 +1,682 @@
+"""
+mlos_sort.py
+Python port of MLOS_sorting.lua (Mod Load Order Sorter, by REfRigERatoR).
+
+Faithful to the Lua algorithm:
+  - preorder: ModManager, ModManagerServer, modoptions
+  - category buckets: coreRequirement -> tweaks -> resource -> map -> vehicle ->
+                      code -> clothes -> ui -> other -> translation -> undefined
+  - loadFirst / loadLast: on (0) | category (1) | off (2)
+  - topological sort by `require` + `loadAfter` with cycle detection
+  - sorting_rules.txt overrides supported (loadAfter/loadBefore/incompatibleMods/
+    loadFirst/loadLast/category)
+
+Limitations vs in-game Lua:
+  - mod.info-only input. We do NOT walk /media/* folders for category detection.
+    We rely on mod.info `category=` if present, then `frameworkKeys` name
+    heuristic, then default "other" (or "undefined" if uncategorizable).
+  - `loadBefore` is converted into corresponding `loadAfter` edges on other mods,
+    matching the Lua mod's behavior.
+"""
+
+import argparse
+import json
+import os
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+# -----------------------------------------------------------------------------
+# Constants (mirrors MLOS_sorting.lua)
+# -----------------------------------------------------------------------------
+
+PREORDER: Dict[str, int] = {"ModManager": 1, "ModManagerServer": 2, "modoptions": 3}
+
+RAW_CATEGORY_ORDER: List[str] = [
+    "coreRequirement",
+    "tweaks",        # libraries / frameworks / APIs (matches existing 'lib' pill)
+    "tile",          # tile asset packs
+    "debug",         # error logger, cheat menus
+    "resource",      # other generic resources
+    "map",
+    "qol",           # QOL changes
+    "moodle",        # moodles / moodlets
+    "tweak_minor",   # tiny tweaks (working aircon, ear protection, …)
+    "music",         # music + music addons (load before vehicles per user spec)
+    "wearable",      # clothing, hair, tattoos (NOT armor)
+    "profession",    # profession mods
+    "movement",      # drop-and-roll, crawl, jump, ladders
+    "building",      # building menus, barricades, light switches
+    "farming",
+    "zombie",        # zombie behaviour mods (OccultZed, HordeNight, ReactiveZombies)
+    "zone",          # hazardous zones, spore zones
+    "armor",         # armor mods (separate from wearables)
+    "food",
+    "health",        # first aid, medical
+    "weapon",        # weapons (load before vehicles per user spec)
+    "crafting",
+    "container",     # backpacks, boxes, tubs
+    "vehicle",
+    "vehicle_spawn", # vehicle spawn zones
+    "loot",          # loot tables
+    "code",          # generic gameplay code (legacy fallback)
+    "ui",            # interface
+    "sound",         # audio (non-music)
+    "texture",
+    "translation",
+    "multiplayer",   # MP-specific utilities
+    "server_only",   # admin tools, server logs
+    "fix",           # bug-fix overlays (distinct from 'patch' loadLast tier)
+    "other",
+    "undefined",
+    # Spec G-patch: "patch" is a category like any other, but `_initial_sort_key`
+    # routes patches above all sub-axes via a leading is_patch tuple element so
+    # they sort strictly LAST (after every loadLast=on map mod).
+    "patch",
+]
+CATEGORY_ORDER: Dict[str, int] = {c: i for i, c in enumerate(RAW_CATEGORY_ORDER)}
+
+LOAD_CATEGORIES: Dict[str, int] = {"on": 0, "category": 1, "off": 2}
+
+# from MLOS_sorting.lua: frameworkKeys for name-based tweak detection.
+# Lua uses string.find on lowercased name (substring match, no regex anchors).
+FRAMEWORK_KEYS: List[str] = [
+    "framework",
+    " api",
+    "_api",
+    "tweak",
+    "interface",
+    "utilit",  # matches utility, utilities
+    "bugfix",
+    "librar",  # matches library, libraries — covers damnlib/tsarslib/StarlitLibrary/etc.
+               # `derive_category` checks mod.maps before FRAMEWORK_KEYS, so a map
+               # mod whose name contains "library" still classifies as `map` first.
+]
+
+# Multi-key list fields in mod.info (lowercased keys)
+LIST_KEYS_MAP = {
+    "require": "requirements",
+    "loadafter": "loadAfter",
+    "loadbefore": "loadBefore",
+    "incompatiblemods": "incompatibleMods",
+    "tags": "tags",
+}
+
+
+# -----------------------------------------------------------------------------
+# Dataclasses
+# -----------------------------------------------------------------------------
+
+
+@dataclass
+class ModInfo:
+    id: str
+    name: str = ""
+    workshop_id: Optional[str] = None
+    category: str = "undefined"
+    requirements: List[str] = field(default_factory=list)
+    loadAfter: List[str] = field(default_factory=list)
+    loadBefore: List[str] = field(default_factory=list)
+    incompatibleMods: List[str] = field(default_factory=list)
+    loadFirst: str = "off"
+    loadLast: str = "off"
+    tags: List[str] = field(default_factory=list)
+    maps: List[str] = field(default_factory=list)  # map folder names from media/maps/
+    flags: List[str] = field(default_factory=list)
+    is_addon: bool = False  # Spec A addon: default-off in multi-mod wsids
+    # Steam Workshop's controlled-vocab tags (workshop_meta.tags). Canonical
+    # signal for build / multiplayer / category detection. Distinct from
+    # `tags` which is mod.info-side (freeform).
+    workshop_tags: List[str] = field(default_factory=list)
+    warnings: Dict[str, List[str]] = field(default_factory=dict)
+
+
+@dataclass
+class SortingRule:
+    loadAfter: List[str] = field(default_factory=list)
+    loadBefore: List[str] = field(default_factory=list)
+    incompatibleMods: List[str] = field(default_factory=list)
+    loadFirst: str = "off"
+    loadLast: str = "off"
+    category: Optional[str] = None
+
+
+# -----------------------------------------------------------------------------
+# Helpers
+# -----------------------------------------------------------------------------
+
+
+def _split_csv(value: str) -> List[str]:
+    """
+    Mirrors Refr_Utils:splitStringBySeparator - split on commas, trim, drop empties.
+    Defensively strips `word=` prefixes that some malformed mod.info lines include
+    (the Lua does this too). Also strips a leading backslash on each entry: B42
+    mod.info files write deps as `require=\\StarlitLibrary` (path-style); we want
+    plain modIds so dep names match for the topo sort and missing-dep warnings.
+    Finally strips a leading "<digits>/" wsid-path prefix some authors put in
+    front of the modId (e.g. require=2256623447/firearmmod).
+    """
+    if value is None:
+        return []
+    cleaned = re.sub(r"\w+\s*=", "", value)
+    out: List[str] = []
+    for p in cleaned.split(","):
+        s = p.strip().lstrip("\\")
+        s = re.sub(r"^\d+/", "", s)
+        if s:
+            out.append(s)
+    return out
+
+
+def _convert_load_category(value) -> str:
+    """Mirrors convertToLoadCategoryString: normalize to 'on' | 'category' | 'off'."""
+    if value in (True, "true", 0, "0"):
+        return "on"
+    if value in (None, False, "false", 2, "2", ""):
+        return "off"
+    if value not in LOAD_CATEGORIES:
+        return "off"
+    return str(value)
+
+
+def _str_contains_any(haystack: str, needles: List[str]) -> bool:
+    if not haystack:
+        return False
+    h = haystack.lower()
+    return any(n and n in h for n in needles)
+
+
+# -----------------------------------------------------------------------------
+# Parsers
+# -----------------------------------------------------------------------------
+
+
+def parse_mod_info(text: str, workshop_id: Optional[str] = None) -> Optional[ModInfo]:
+    """
+    Parse a mod.info file body. Returns None if no `id=` line found.
+    Lines are `key=value`; keys lowercased; list-fields comma-separated.
+    """
+    fields: Dict[str, object] = {}
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        m = re.match(r"^\s*(.+?)\s*=\s*(.*?)\s*$", line)
+        if not m:
+            continue
+        key = m.group(1).strip().lower()
+        value = m.group(2).strip()
+        if key in LIST_KEYS_MAP:
+            fields[LIST_KEYS_MAP[key]] = _split_csv(value)
+        elif key == "loadfirst":
+            fields["loadFirst"] = _convert_load_category(value)
+        elif key == "loadlast":
+            fields["loadLast"] = _convert_load_category(value)
+        elif key == "category":
+            fields["category"] = value if value in CATEGORY_ORDER else "undefined"
+        elif key == "name":
+            fields["name"] = value
+        elif key == "id":
+            # Some authors prefix the wsid into the id (e.g. id=2256623447/firearmmod).
+            # Strip a leading "<digits>/" so the canonical mod_id is the clean form.
+            fields["id"] = re.sub(r"^\d+/", "", value)
+
+    if "id" not in fields:
+        return None
+
+    return ModInfo(
+        id=fields["id"],
+        name=fields.get("name", ""),
+        workshop_id=workshop_id,
+        category=fields.get("category", "undefined"),
+        requirements=fields.get("requirements", []),
+        loadAfter=fields.get("loadAfter", []),
+        loadBefore=fields.get("loadBefore", []),
+        incompatibleMods=fields.get("incompatibleMods", []),
+        loadFirst=fields.get("loadFirst", "off"),
+        loadLast=fields.get("loadLast", "off"),
+        tags=fields.get("tags", []),
+    )
+
+
+def parse_sorting_rules(text: str) -> Dict[str, SortingRule]:
+    """
+    Parse a sorting_rules.txt file. Format:
+        [modId]
+        loadAfter=mod1,mod2
+        loadBefore=mod3
+        incompatibleMods=mod4
+        loadFirst=on
+        loadLast=off
+        category=tweaks
+    """
+    rules: Dict[str, SortingRule] = {}
+    current: Optional[str] = None
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line:
+            continue
+        m = re.match(r"^\s*\[\s*(.+?)\s*\]\s*$", line)
+        if m:
+            current = m.group(1)
+            rules.setdefault(current, SortingRule())
+            continue
+        if current is None:
+            continue
+        kv = re.match(r"^\s*(.+?)\s*=\s*(.*?)\s*$", line)
+        if not kv:
+            continue
+        key, value = kv.group(1).lower(), kv.group(2)
+        rule = rules[current]
+        if key in ("loadafter", "loadmodafter"):
+            rule.loadAfter = list(dict.fromkeys(rule.loadAfter + _split_csv(value)))
+        elif key in ("loadbefore", "loadmodbefore"):
+            rule.loadBefore = list(dict.fromkeys(rule.loadBefore + _split_csv(value)))
+        elif key in ("incompatiblemods", "incompatible"):
+            rule.incompatibleMods = list(dict.fromkeys(rule.incompatibleMods + _split_csv(value)))
+        elif key == "loadfirst":
+            rule.loadFirst = _convert_load_category(value)
+        elif key == "loadlast":
+            rule.loadLast = _convert_load_category(value)
+        elif key == "category":
+            rule.category = value if value in CATEGORY_ORDER else None
+    return rules
+
+
+# -----------------------------------------------------------------------------
+# Filesystem ingestion (DepotDownloader output layout)
+# -----------------------------------------------------------------------------
+
+
+def load_mods_from_dir(root: Path) -> List[ModInfo]:
+    """
+    Walk `<root>/<workshop_id>/mods/<mod_id>/mod.info` (DepotDownloader output).
+    Also: `<root>/<workshop_id>/mods/<mod_id>/media/maps/<map_folder>/map.info`
+    populates `maps` for that mod.
+    """
+    mods: List[ModInfo] = []
+    if not root.exists():
+        raise FileNotFoundError(f"Mods root does not exist: {root}")
+
+    for workshop_dir in sorted(root.iterdir()):
+        if not workshop_dir.is_dir():
+            continue
+        workshop_id = workshop_dir.name if workshop_dir.name.isdigit() else None
+        mods_root = workshop_dir / "mods"
+        if not mods_root.exists():
+            # also support: some layouts put mods/ at root level directly
+            mods_root = workshop_dir
+        if not mods_root.exists() or not mods_root.is_dir():
+            continue
+
+        for mod_dir in sorted(mods_root.iterdir()):
+            if not mod_dir.is_dir():
+                continue
+            mod_info_path = mod_dir / "mod.info"
+            if not mod_info_path.exists():
+                continue
+            try:
+                text = mod_info_path.read_text(encoding="utf-8", errors="replace")
+            except OSError as e:
+                print(f"WARN: cannot read {mod_info_path}: {e}", file=sys.stderr)
+                continue
+            mod = parse_mod_info(text, workshop_id=workshop_id)
+            if mod is None:
+                print(f"WARN: no `id=` in {mod_info_path}, skipping", file=sys.stderr)
+                continue
+
+            # Collect map folders
+            maps_dir = mod_dir / "media" / "maps"
+            if maps_dir.exists() and maps_dir.is_dir():
+                for map_folder in sorted(maps_dir.iterdir()):
+                    if map_folder.is_dir() and (map_folder / "map.info").exists():
+                        mod.maps.append(map_folder.name)
+
+            mods.append(mod)
+
+    return mods
+
+
+# -----------------------------------------------------------------------------
+# Category derivation (degraded vs in-game; no folder walk)
+# -----------------------------------------------------------------------------
+
+
+_PATCH_NAME_RE = re.compile(r"\b(patch|compat|compatibility)\b", re.IGNORECASE)
+
+
+# Substring-based category hints (kept in sync with api/mlos_sort.py)
+_LIB_NAME_HINTS  = ["library", "libraries", "framework"]
+_LIB_NAME_RE = re.compile(
+    r'(?<![A-Za-z])(?:lib|api|core)(?![A-Za-z])'
+    r'|(?<=[a-z])(?:Lib|API|Core)(?![A-Za-z])',
+    re.IGNORECASE,
+)
+_MUSIC_NAME_HINTS    = ["music", "moozic", "jukebox"]
+_MOODLE_NAME_HINTS   = ["moodle", "moodlet"]
+_PROFESSION_HINTS    = ["profession"]
+_MOVEMENT_HINTS      = [
+    "true action", "trueaction", "true_action",
+    "drop and roll", "dropandroll", "drop_and_roll",
+    "crawl", "ladder",
+]
+_ARMOR_NAME_HINTS    = ["armor", "armour"]
+_HEALTH_NAME_HINTS   = ["first aid", "firstaid", "medical", "injur", "disease", "sickness"]
+_CRAFTING_HINTS      = ["craft"]
+_CONTAINER_HINTS     = ["backpack", "container", "storage"]
+_LOOT_NAME_HINTS     = ["loot"]
+_TILE_NAME_HINTS     = ["tiles", "tileset", "tilepack"]
+_DEBUG_NAME_HINTS    = ["debug menu", "cheat menu", "error log", "errormagnifier"]
+_ZONE_NAME_HINTS     = ["hazard zone", "spore zone", "spore zones"]
+_ZOMBIE_NAME_HINTS   = ["zombie", "horde", "undead"]
+_FIX_NAME_HINTS      = [" fix", "_fix", "bugfix", "hotfix"]
+
+
+def _name_has(name: str, hints: List[str]) -> bool:
+    if not name:
+        return False
+    n = name.lower()
+    return any(h in n for h in hints)
+
+
+def derive_category(mod: ModInfo) -> str:
+    """Best-effort category from mod.info + workshop_meta.tags + name.
+    Mirrors api/mlos_sort.py; keep both copies in sync.
+    """
+    if mod.category in CATEGORY_ORDER and mod.category != "undefined":
+        return mod.category
+
+    name = mod.name or ""
+    if name and _PATCH_NAME_RE.search(name):
+        return "patch"
+    if _name_has(name, _LIB_NAME_HINTS) or (name and _LIB_NAME_RE.search(name)):
+        return "tweaks"
+
+    if mod.maps:
+        return "map"
+
+    if _name_has(name, _MUSIC_NAME_HINTS):
+        return "music"
+    if _name_has(name, _MOVEMENT_HINTS):
+        return "movement"
+    if _name_has(name, _MOODLE_NAME_HINTS):
+        return "moodle"
+    if _name_has(name, _DEBUG_NAME_HINTS):
+        return "debug"
+    if _name_has(name, _TILE_NAME_HINTS):
+        return "tile"
+
+    ws_tags = set(mod.workshop_tags or [])
+    has_audio = "Audio" in ws_tags
+
+    if "Weapons" in ws_tags:
+        return "weapon"
+    if "Vehicles" in ws_tags:
+        if name and "spawn zone" in name.lower():
+            return "vehicle_spawn"
+        return "vehicle"
+    if "Clothing/Armor" in ws_tags:
+        if _name_has(name, _ARMOR_NAME_HINTS):
+            return "armor"
+        return "wearable"
+    if "Food" in ws_tags:
+        return "food"
+    if "building" in {t.lower() for t in ws_tags}:
+        return "building"
+    if "Farming" in ws_tags:
+        return "farming"
+    if "Skills" in ws_tags:
+        if _name_has(name, _PROFESSION_HINTS):
+            return "profession"
+        return "code"
+    if "Interface" in ws_tags:
+        return "ui"
+    if "Textures" in ws_tags:
+        return "texture"
+    if "Language/Translation" in ws_tags:
+        return "translation"
+    if "QOL" in ws_tags:
+        return "qol"
+    if "Map" in ws_tags:
+        return "map"
+
+    if _name_has(name, _TILE_NAME_HINTS):
+        return "tile"
+    if _name_has(name, _ZOMBIE_NAME_HINTS):
+        return "zombie"
+    if _name_has(name, _HEALTH_NAME_HINTS):
+        return "health"
+    if _name_has(name, _CRAFTING_HINTS):
+        return "crafting"
+    if _name_has(name, _CONTAINER_HINTS):
+        return "container"
+    if _name_has(name, _LOOT_NAME_HINTS):
+        return "loot"
+    if _name_has(name, _FIX_NAME_HINTS):
+        return "fix"
+    if _name_has(name, _ZONE_NAME_HINTS):
+        return "zone"
+
+    if has_audio:
+        return "sound"
+
+    tags_lc = [t.lower() for t in mod.tags]
+    if any("translation" in t for t in tags_lc):
+        return "translation"
+    if any("vehicle" in t for t in tags_lc):
+        return "vehicle"
+    if any("interface" in t or "ui" in t for t in tags_lc):
+        return "ui"
+    if any("clothing" in t or "skin" in t for t in tags_lc):
+        return "wearable"
+    if any("armor" in t for t in tags_lc):
+        return "armor"
+    if any("map" in t for t in tags_lc):
+        return "map"
+
+    if _str_contains_any(name, FRAMEWORK_KEYS):
+        return "tweaks"
+
+    if "Multiplayer" in ws_tags:
+        return "multiplayer"
+
+    return "other"
+
+
+# -----------------------------------------------------------------------------
+# Sort
+# -----------------------------------------------------------------------------
+
+
+def _apply_overrides(mods: List[ModInfo], rules: Dict[str, SortingRule]) -> None:
+    """In-place: merge rules into mods, then propagate loadBefore -> reverse loadAfter."""
+    by_id = {m.id: m for m in mods}
+
+    for mod in mods:
+        rule = rules.get(mod.id)
+        if rule:
+            mod.loadAfter = list(dict.fromkeys(mod.loadAfter + rule.loadAfter))
+            mod.loadBefore = list(dict.fromkeys(mod.loadBefore + rule.loadBefore))
+            mod.incompatibleMods = list(dict.fromkeys(mod.incompatibleMods + rule.incompatibleMods))
+            mod.loadFirst = _convert_load_category(rule.loadFirst if rule.loadFirst != "off" else mod.loadFirst)
+            mod.loadLast = _convert_load_category(rule.loadLast if rule.loadLast != "off" else mod.loadLast)
+            if rule.category:
+                mod.category = rule.category
+
+        # Derive category if still undefined
+        if mod.category not in CATEGORY_ORDER or mod.category == "undefined":
+            mod.category = derive_category(mod)
+
+    # Translate loadBefore into reverse loadAfter on the target mod
+    # (mirrors updateSortingRulesLoadAfter)
+    for mod in mods:
+        for target in mod.loadBefore:
+            target_mod = by_id.get(target)
+            if target_mod and mod.id not in target_mod.loadAfter:
+                target_mod.loadAfter.append(mod.id)
+
+
+def _initial_sort_key(mod: ModInfo):
+    """Mirrors initialSortMods comparator. Returns sortable tuple.
+
+    Spec G-patch: index 0 is `is_patch` so patches sort strictly last - they
+    have to override loadLast=on map mods at runtime. Within the patch tier
+    the existing sub-axes still apply (PREORDER, alpha, etc.).
+    """
+    is_patch = 1 if mod.category == "patch" else 0
+    pre = PREORDER.get(mod.id, 10000)
+    return (
+        is_patch,
+        pre,
+        LOAD_CATEGORIES[mod.loadFirst],          # global loadFirst (on first)
+        -LOAD_CATEGORIES[mod.loadLast] + 100,    # global loadLast (on last) -- keep parity by
+                                                  # sorting "on" last; we invert so smaller=earlier
+        CATEGORY_ORDER.get(mod.category, CATEGORY_ORDER["undefined"]),
+        LOAD_CATEGORIES[mod.loadFirst],          # in-category loadFirst
+        -LOAD_CATEGORIES[mod.loadLast] + 100,    # in-category loadLast
+        mod.id.lower(),
+    )
+
+
+def _topological_sort(mods: List[ModInfo]) -> Tuple[List[str], List[List[str]]]:
+    """DFS topo sort on (requirements + loadAfter). Returns (order, cycles)."""
+    by_id = {m.id: m for m in mods}
+    visited: Dict[str, bool] = {}
+    visiting: Dict[str, bool] = {}
+    order: List[str] = []
+    cycles: List[List[str]] = []
+
+    def visit(mod: ModInfo, path: List[str]):
+        if visiting.get(mod.id):
+            cycles.append(path + [mod.id])
+            return
+        if visited.get(mod.id):
+            return
+        visiting[mod.id] = True
+        for dep in mod.requirements:
+            target = by_id.get(dep)
+            if target:
+                visit(target, path + [mod.id])
+        for dep in mod.loadAfter:
+            target = by_id.get(dep)
+            if target:
+                visit(target, path + [mod.id])
+        visiting[mod.id] = False
+        visited[mod.id] = True
+        order.append(mod.id)
+
+    for mod in mods:
+        visit(mod, [])
+    return order, cycles
+
+
+def sort_mods(
+    mods: List[ModInfo],
+    rules: Optional[Dict[str, SortingRule]] = None,
+) -> Dict[str, object]:
+    """
+    Top-level entry: returns dict with ordered IDs + warnings.
+    """
+    rules = rules or {}
+    _apply_overrides(mods, rules)
+
+    # Initial deterministic sort (preorder, loadFirst, category, loadLast, alpha)
+    mods.sort(key=_initial_sort_key)
+
+    order, cycles = _topological_sort(mods)
+
+    by_id = {m.id: m for m in mods}
+    enabled = set(by_id.keys())
+
+    missing: Dict[str, List[str]] = {}
+    incompat: Dict[str, List[str]] = {}
+
+    for mod in mods:
+        miss = [r for r in mod.requirements if r not in enabled]
+        if miss:
+            missing[mod.id] = miss
+        inc = [r for r in mod.incompatibleMods if r in enabled]
+        if inc:
+            incompat[mod.id] = inc
+
+    # Output blocks for the server's .ini file
+    mods_line = order  # already mod IDs in load order
+    workshop_seen: List[str] = []
+    workshop_set = set()
+    for mod_id in order:
+        wid = by_id[mod_id].workshop_id
+        if wid and wid not in workshop_set:
+            workshop_seen.append(wid)
+            workshop_set.add(wid)
+    # MAP_LINE convention: dependencies first (leftmost), dependents next.
+    # Vanilla Muldraugh, KY is ALWAYS appended at the very end by
+    # adapters.build_response. `order` is already topo-sorted by mod-level
+    # deps (require= / loadAfter= / loadBefore=), so dependencies appear
+    # before their dependents — walk it forward.
+    map_folders: List[str] = []
+    for mod_id in order:
+        for mf in by_id[mod_id].maps:
+            if mf not in map_folders:
+                map_folders.append(mf)
+
+    return {
+        "Mods": mods_line,
+        "WorkshopItems": workshop_seen,
+        "Map": map_folders,
+        "warnings": {
+            "cycles": cycles,
+            "missing_requirements": missing,
+            "incompatible_enabled": incompat,
+        },
+    }
+
+
+# -----------------------------------------------------------------------------
+# CLI
+# -----------------------------------------------------------------------------
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Sort PZ mods by load order. Reads DepotDownloader output layout.",
+    )
+    ap.add_argument("mods_root", help="Path containing <workshop_id>/mods/<mod_id>/mod.info trees")
+    ap.add_argument("--rules", help="Optional sorting_rules.txt path")
+    ap.add_argument("--json", action="store_true", help="Output JSON instead of ini blocks")
+    args = ap.parse_args()
+
+    root = Path(args.mods_root).resolve()
+    mods = load_mods_from_dir(root)
+    if not mods:
+        print("ERROR: no mods found", file=sys.stderr)
+        sys.exit(2)
+
+    rules: Dict[str, SortingRule] = {}
+    if args.rules:
+        rules = parse_sorting_rules(Path(args.rules).read_text(encoding="utf-8"))
+
+    result = sort_mods(mods, rules)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+        return
+
+    print("WorkshopItems=" + ";".join(result["WorkshopItems"]))
+    print("Mods=" + ";".join(result["Mods"]))
+    if result["Map"]:
+        print("Map=" + ";".join(result["Map"]))
+    w = result["warnings"]
+    if w["cycles"] or w["missing_requirements"] or w["incompatible_enabled"]:
+        print("\n# Warnings")
+        if w["cycles"]:
+            print("# cycles:", w["cycles"])
+        if w["missing_requirements"]:
+            print("# missing_requirements:", w["missing_requirements"])
+        if w["incompatible_enabled"]:
+            print("# incompatible_enabled:", w["incompatible_enabled"])
+
+
+if __name__ == "__main__":
+    main()
diff --git a/worker/worker.py b/worker/worker.py
new file mode 100644
index 0000000..72a0d13
--- /dev/null
+++ b/worker/worker.py
@@ -0,0 +1,586 @@
+"""
+worker.py - pzsort cache filler
+
+Single-shot CLI that takes Steam Workshop IDs on argv, refreshes metadata
+from Steam's anonymous API, and only runs DepotDownloader for cache misses
+(where workshop_meta.time_updated has changed since last parse).
+
+Usage:
+    python3 worker.py <workshop_id> [<workshop_id> ...]
+    python3 worker.py --force <workshop_id> ...    # ignore cache, re-download
+
+Env (or .env file):
+    DATABASE_URL  postgresql://pzsort:<pw>@127.0.0.1:5439/pzsort
+    DD_PATH       path to DepotDownloader executable
+    PZ_APP_ID     108600 (default)
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import asyncpg
+import httpx
+
+# Reuse the parser from the sorter
+sys.path.insert(0, str(Path(__file__).parent))
+from mlos_sort import parse_mod_info, ModInfo  # noqa: E402
+
+PZ_APP_ID = int(os.environ.get("PZ_APP_ID", "108600"))
+DEFAULT_DD_PATH = os.environ.get("DD_PATH", "./DepotDownloader")
+STEAM_API = "https://api.steampowered.com/ISteamRemoteStorage/GetPublishedFileDetails/v1/"
+
+
+# -----------------------------------------------------------------------------
+# Steam API
+# -----------------------------------------------------------------------------
+
+
+def fetch_workshop_details(workshop_ids: List[str]) -> Dict[str, dict]:
+    """
+    POST to legacy GetPublishedFileDetails. Anonymous, no API key needed.
+    Returns {workshop_id: detail_dict}.
+    """
+    if not workshop_ids:
+        return {}
+    data: Dict[str, str] = {"itemcount": str(len(workshop_ids))}
+    for i, wid in enumerate(workshop_ids):
+        data[f"publishedfileids[{i}]"] = wid
+    with httpx.Client(timeout=30.0) as client:
+        r = client.post(STEAM_API, data=data)
+        r.raise_for_status()
+        body = r.json()
+    out: Dict[str, dict] = {}
+    for item in body.get("response", {}).get("publishedfiledetails", []):
+        out[item["publishedfileid"]] = item
+    return out
+
+
+def flatten_tags(detail: dict) -> List[str]:
+    return [t.get("tag", "") for t in detail.get("tags", []) if t.get("tag")]
+
+
+# Public Steam Workshop page URL. The anonymous GetPublishedFileDetails API
+# does NOT return `children` for individual mods (only collections), so to
+# learn a mod's "Required Items" we have to scrape the public HTML page.
+_WORKSHOP_PAGE_URL = "https://steamcommunity.com/sharedfiles/filedetails/?id={wsid}"
+_RE_REQUIRED_BLOCK = re.compile(
+    r'<div[^>]*id="RequiredItems"[^>]*>(.*?)</div>\s*</div>',
+    re.DOTALL,
+)
+_RE_REQUIRED_LINK = re.compile(r'filedetails/\?id=(\d+)')
+
+# ── rate-limit safety for Steam HTML scraping ─────────────────────────────
+# Steam aggressively 429s anonymous /sharedfiles/filedetails/ HTML requests;
+# during a 2026-05-03 backfill at ~1 RPS our IP was blocked for hours and a
+# subsequent single curl probe still got 429. Two file-locked, multi-process
+# safeguards now sit in front of every scrape:
+#
+#   1. THROTTLE FILE — records the timestamp of the last attempted scrape.
+#      Every worker waits via flock until at least
+#      `_MIN_SCRAPE_INTERVAL_S` seconds have elapsed since the last one.
+#      Serializes 4 concurrent drain processes so they can't burst.
+#
+#   2. COOLDOWN FILE — when we observe a hard 429 (after retries), we write
+#      `now() + _COOLDOWN_S` here. While active, every fetch returns None
+#      instantly without touching Steam, preserving cached values until the
+#      IP block ages out.
+#
+# Defaults: 6s spacing → ≤10 RPM steady-state, 1h cooldown after a 429
+# storm. Overridable via SORTOF_STEAM_MIN_INTERVAL / SORTOF_STEAM_COOLDOWN.
+import fcntl as _fcntl
+
+_THROTTLE_FILE = "/tmp/sortof_steam_throttle"
+_COOLDOWN_FILE = "/tmp/sortof_steam_cooldown"
+_MIN_SCRAPE_INTERVAL_S = float(os.environ.get("SORTOF_STEAM_MIN_INTERVAL", "6"))
+_COOLDOWN_S = float(os.environ.get("SORTOF_STEAM_COOLDOWN", "3600"))
+
+
+def _read_cooldown_until() -> float:
+    try:
+        with open(_COOLDOWN_FILE, "r") as f:
+            return float(f.read().strip() or 0)
+    except (OSError, ValueError):
+        return 0.0
+
+
+def _write_cooldown_until(epoch_s: float) -> None:
+    try:
+        with open(_COOLDOWN_FILE, "w") as f:
+            f.write(str(epoch_s))
+    except OSError:
+        pass
+
+
+def _throttle_scrape() -> None:
+    """Block until at least `_MIN_SCRAPE_INTERVAL_S` has elapsed since the
+    last scrape by ANY drain process (multi-process safe via flock)."""
+    import time as _t
+    Path(_THROTTLE_FILE).touch(exist_ok=True)
+    with open(_THROTTLE_FILE, "r+") as f:
+        _fcntl.flock(f.fileno(), _fcntl.LOCK_EX)
+        try:
+            f.seek(0)
+            raw = f.read().strip()
+            last = float(raw) if raw else 0.0
+            now = _t.time()
+            wait = _MIN_SCRAPE_INTERVAL_S - (now - last)
+            if wait > 0:
+                _t.sleep(wait)
+                now = _t.time()
+            f.seek(0); f.truncate(); f.write(str(now))
+        finally:
+            _fcntl.flock(f.fileno(), _fcntl.LOCK_UN)
+
+
+def fetch_required_wsids(
+    workshop_id: str,
+    timeout: int = 15,
+    max_attempts: int = 4,
+    backoff_429: float = 30.0,
+) -> Optional[List[str]]:
+    """Scrape the public Workshop page for Required Items wsids.
+
+    Returns
+        None  — fetch/parse error, persistent 429, or active cooldown.
+                Caller MUST NOT overwrite the existing cached value.
+        []    — page loaded successfully but has no required items section.
+        list  — required item wsids in declaration order, deduped.
+    """
+    import time as _time
+    cooldown_until = _read_cooldown_until()
+    if cooldown_until and _time.time() < cooldown_until:
+        return None  # Steam recently 429'd us — back off entirely.
+    _throttle_scrape()
+    url = _WORKSHOP_PAGE_URL.format(wsid=workshop_id)
+    html: Optional[str] = None
+    for attempt in range(1, max_attempts + 1):
+        try:
+            with httpx.Client(timeout=timeout, follow_redirects=True) as client:
+                r = client.get(url)
+            if r.status_code == 429:
+                if attempt < max_attempts:
+                    _time.sleep(backoff_429 * attempt)
+                    continue
+                # Final 429 → arm the global cooldown so other workers
+                # (and this one's next call) skip Steam entirely.
+                _write_cooldown_until(_time.time() + _COOLDOWN_S)
+                print(f"  ! required_wsids 429 (gave up) for {workshop_id}; "
+                      f"cooldown {int(_COOLDOWN_S)}s armed", file=sys.stderr)
+                return None
+            r.raise_for_status()
+            html = r.text
+            break
+        except (httpx.HTTPError, httpx.TimeoutException) as e:
+            print(f"  ! required_wsids fetch failed for {workshop_id}: {e}",
+                  file=sys.stderr)
+            return None
+    if html is None:
+        return None
+    m = _RE_REQUIRED_BLOCK.search(html)
+    if not m:
+        return []
+    seen: set = set()
+    out: List[str] = []
+    for w in _RE_REQUIRED_LINK.findall(m.group(1)):
+        if w not in seen and w != workshop_id:
+            seen.add(w)
+            out.append(w)
+    return out
+
+
+# -----------------------------------------------------------------------------
+# DepotDownloader
+# -----------------------------------------------------------------------------
+
+
+def run_depot_downloader(
+    workshop_id: str,
+    output_dir: Path,
+    dd_path: Path,
+    filelist_regex: str = r"regex:.*\.info$",
+    timeout: int = 300,
+    max_attempts: int = 3,
+    backoff_s: float = 2.0,
+) -> bool:
+    """
+    Fetch workshop item using DepotDownloader, filtered to .info files only.
+    Writes <output_dir>/mods/<mod_id>/mod.info (and possibly map.info paths).
+    Returns True on success.
+
+    Retries up to max_attempts times on rc!=0 or timeout - Steam Workshop's
+    CDN occasionally flakes on the manifest fetch and a fresh DD invocation
+    typically succeeds. Caller is also free to retry at a higher level
+    (drain.py's MAX_ATTEMPTS), but in-process retry avoids the full re-claim
+    cycle for the common transient case.
+    """
+    import time as _time
+    output_dir.mkdir(parents=True, exist_ok=True)
+    filelist = output_dir / "_filelist.txt"
+    filelist.write_text(filelist_regex + "\n", encoding="utf-8")
+
+    cmd = [
+        str(dd_path),
+        "-app", str(PZ_APP_ID),
+        "-pubfile", workshop_id,
+        "-filelist", str(filelist),
+        "-dir", str(output_dir),
+    ]
+    last_err = ""
+    for attempt in range(1, max_attempts + 1):
+        try:
+            proc = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            last_err = "timeout"
+            print(f"  ! DepotDownloader timeout for {workshop_id} (attempt {attempt}/{max_attempts})",
+                  file=sys.stderr)
+        else:
+            if proc.returncode == 0:
+                if attempt > 1:
+                    print(f"  ✓ DepotDownloader recovered for {workshop_id} on attempt {attempt}",
+                          file=sys.stderr)
+                return True
+            last_err = f"rc={proc.returncode}"
+            print(f"  ! DepotDownloader rc={proc.returncode} for {workshop_id} "
+                  f"(attempt {attempt}/{max_attempts})", file=sys.stderr)
+            print(proc.stderr[-500:] if proc.stderr else proc.stdout[-500:], file=sys.stderr)
+        if attempt < max_attempts:
+            _time.sleep(backoff_s)
+    print(f"  !! DepotDownloader gave up on {workshop_id} after {max_attempts} attempts (last: {last_err})",
+          file=sys.stderr)
+    return False
+
+
+def discover_mod_infos(output_dir: Path) -> List[Path]:
+    """Find all mod.info files. Two layouts coexist in the wild:
+        B41:  mods/<mod_id>/mod.info
+        B42:  mods/<mod_id>/<gameVersion>/mod.info   e.g. mods/Foo/42/mod.info
+    A single mod can ship both. UPSERT on (workshop_id, mod_id) collapses
+    duplicates; lexicographic sort means the B41 (root-level) variant wins
+    last when present, the highest-numbered B42 variant otherwise."""
+    out = list(output_dir.glob("mods/*/mod.info"))
+    out.extend(output_dir.glob("mods/*/*/mod.info"))
+    return sorted(out)
+
+
+def discover_map_folders(mip_parent: Path) -> List[str]:
+    """Find map folders for the mod whose mod.info lives in `mip_parent`.
+
+    Three layouts coexist:
+      B41:  mods/<modId>/mod.info
+            mods/<modId>/media/maps/<x>/map.info
+      B42:  mods/<modId>/<branch>/mod.info       (branch is e.g., '42','42.13')
+            mods/<modId>/<branch>/media/maps/<x>/map.info
+      B42 split: mod.info under '42/' but map data under a sibling 'common/'
+                 branch — observed in Project RV Interior. This is why we
+                 walk back to the mod-id root and enumerate every branch.
+    """
+    if mip_parent.parent.name == "mods":
+        modid_root = mip_parent
+    else:
+        modid_root = mip_parent.parent
+    seen: set = set()
+    out: List[str] = []
+    candidates = list(modid_root.glob("media/maps/*/map.info"))
+    candidates.extend(modid_root.glob("*/media/maps/*/map.info"))
+    for cand in sorted(candidates):
+        folder = cand.parent.name
+        if folder in seen:
+            continue
+        seen.add(folder)
+        out.append(folder)
+    return out
+
+
+# -----------------------------------------------------------------------------
+# DB upserts
+# -----------------------------------------------------------------------------
+
+
+UPSERT_WORKSHOP_META = """
+INSERT INTO workshop_meta (
+    workshop_id, title, description, tags, creator_steamid,
+    time_created, time_updated, file_size, preview_url,
+    consumer_app_id, visibility, banned, last_checked_at
+) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12, now())
+ON CONFLICT (workshop_id) DO UPDATE SET
+    title           = EXCLUDED.title,
+    description     = EXCLUDED.description,
+    tags            = EXCLUDED.tags,
+    creator_steamid = EXCLUDED.creator_steamid,
+    time_created    = EXCLUDED.time_created,
+    time_updated    = EXCLUDED.time_updated,
+    file_size       = EXCLUDED.file_size,
+    preview_url     = EXCLUDED.preview_url,
+    consumer_app_id = EXCLUDED.consumer_app_id,
+    visibility      = EXCLUDED.visibility,
+    banned          = EXCLUDED.banned,
+    last_checked_at = now();
+"""
+
+EVICT_AND_RECORD_CONFLICT = """
+-- Per the cache invariant: a mod_id is owned by exactly one wsid at a time.
+-- When we're about to UPSERT (wsid, mod_id), evict any (other_wsid, mod_id)
+-- claims so the new pull becomes canonical, and record the eviction in
+-- mod_id_conflicts so /api/sort can warn users who paste the displaced wsid.
+WITH evicted AS (
+    DELETE FROM mod_parsed
+     WHERE mod_id = $2 AND workshop_id <> $1
+    RETURNING workshop_id
+)
+INSERT INTO mod_id_conflicts (mod_id, evicting_wsid, evicted_wsid)
+SELECT $2, $1, workshop_id FROM evicted
+ON CONFLICT (mod_id, evicting_wsid, evicted_wsid)
+DO UPDATE SET recorded_at = now();
+"""
+
+UPSERT_MOD_PARSED = """
+INSERT INTO mod_parsed (
+    workshop_id, mod_id, name, category,
+    requirements, load_after, load_before, incompatible_mods,
+    load_first, load_last, tags, maps,
+    raw_mod_info, version_min, is_addon,
+    parsed_at_time_updated, parsed_at
+) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15,$16, now())
+ON CONFLICT (workshop_id, mod_id) DO UPDATE SET
+    name                   = EXCLUDED.name,
+    category               = EXCLUDED.category,
+    requirements           = EXCLUDED.requirements,
+    load_after             = EXCLUDED.load_after,
+    load_before            = EXCLUDED.load_before,
+    incompatible_mods      = EXCLUDED.incompatible_mods,
+    load_first             = EXCLUDED.load_first,
+    load_last              = EXCLUDED.load_last,
+    tags                   = EXCLUDED.tags,
+    maps                   = EXCLUDED.maps,
+    raw_mod_info           = EXCLUDED.raw_mod_info,
+    version_min            = EXCLUDED.version_min,
+    is_addon               = EXCLUDED.is_addon,
+    parsed_at_time_updated = EXCLUDED.parsed_at_time_updated,
+    parsed_at              = now();
+"""
+
+# Description-text heuristic for "this mod is an optional add-on to the
+# primary mod published by the same wsid". Matches:
+#   "Optional add-on: removes ..."   (TMMumble)
+#   "optional addon ..."
+#   "Optional add on ..."
+# Strict "optional + add-on" keyword pair to avoid false positives on
+# generic "addon" naming. Author-driven signal — set via the description=
+# field of mod.info.
+_RE_OPTIONAL_ADDON = re.compile(
+    r"description\s*=\s*[^\r\n]*\bOptional\s+Add[- ]?on\b",
+    re.IGNORECASE,
+)
+
+
+def detect_is_addon(raw: str) -> bool:
+    """Return True if the mod.info description self-identifies as an
+    optional add-on (`Optional add-on: …`)."""
+    return bool(_RE_OPTIONAL_ADDON.search(raw or ""))
+
+DELETE_STALE_MOD_PARSED = """
+DELETE FROM mod_parsed
+WHERE workshop_id = $1 AND mod_id <> ALL($2::text[]);
+"""
+
+CHECK_PARSED_FRESH = """
+SELECT mod_id FROM mod_parsed
+WHERE workshop_id = $1 AND parsed_at_time_updated = $2;
+"""
+
+
+def extract_version_min(raw: str) -> Optional[str]:
+    for line in raw.splitlines():
+        s = line.strip().lower()
+        if s.startswith("versionmin"):
+            _, _, v = line.partition("=")
+            return v.strip() or None
+    return None
+
+
+# -----------------------------------------------------------------------------
+# Main flow
+# -----------------------------------------------------------------------------
+
+
+async def process_one(
+    conn: asyncpg.Connection,
+    workshop_id: str,
+    detail: dict,
+    dd_path: Path,
+    force: bool,
+) -> str:
+    """Returns 'hit' | 'refreshed' | 'banned' | 'missing' | 'no_mod_info' | 'failed'.
+
+    'no_mod_info' = DepotDownloader succeeded but the workshop item contained
+    no parseable mod.info file (typical for collections, art-only items, and
+    other non-mod uploads that share the PZ consumer_app_id). Distinct from
+    'failed' (DD itself errored), so the API can surface "this isn't a mod"
+    differently from "we couldn't fetch this."
+    """
+    # Pre-flight: bad results
+    if detail.get("result") != 1:
+        return "missing"
+    if detail.get("banned"):
+        return "banned"
+    if detail.get("consumer_app_id") != PZ_APP_ID:
+        return "failed"  # wrong app
+
+    time_updated = int(detail.get("time_updated", 0))
+
+    # Always refresh meta (cheap)
+    await conn.execute(
+        UPSERT_WORKSHOP_META,
+        workshop_id,
+        detail.get("title", ""),
+        detail.get("description", "") or "",
+        flatten_tags(detail),
+        str(detail.get("creator", "")) or None,
+        int(detail.get("time_created", 0)) or None,
+        time_updated,
+        int(detail.get("file_size", 0)) or None,
+        detail.get("preview_url"),
+        detail.get("consumer_app_id"),
+        detail.get("visibility"),
+        bool(detail.get("banned", False)),
+    )
+
+    # Cache check
+    if not force:
+        rows = await conn.fetch(CHECK_PARSED_FRESH, workshop_id, time_updated)
+        if rows:
+            return "hit"
+
+    # Cache miss → download + parse
+    with tempfile.TemporaryDirectory(prefix=f"pzsort_{workshop_id}_") as tmpdir:
+        tmp = Path(tmpdir)
+        ok = run_depot_downloader(workshop_id, tmp, dd_path)
+        if not ok:
+            return "failed"
+
+        mod_info_paths = discover_mod_infos(tmp)
+        if not mod_info_paths:
+            print(f"  ! no mod.info found in {workshop_id}", file=sys.stderr)
+            return "no_mod_info"
+
+        seen_mod_ids: List[str] = []
+        for mip in mod_info_paths:
+            raw = mip.read_text(encoding="utf-8", errors="replace")
+            mod = parse_mod_info(raw, workshop_id=workshop_id)
+            if mod is None:
+                continue
+            maps = discover_map_folders(mip.parent)
+            # Evict any other wsid's claim on this mod_id before we install
+            # ours. Cache invariant: at most one wsid per mod_id, with the
+            # most-recent pull winning.
+            await conn.execute(EVICT_AND_RECORD_CONFLICT, workshop_id, mod.id)
+            await conn.execute(
+                UPSERT_MOD_PARSED,
+                workshop_id,
+                mod.id,
+                mod.name,
+                mod.category,
+                mod.requirements,
+                mod.loadAfter,
+                mod.loadBefore,
+                mod.incompatibleMods,
+                mod.loadFirst,
+                mod.loadLast,
+                mod.tags,
+                maps,
+                raw,
+                extract_version_min(raw),
+                detect_is_addon(raw),
+                time_updated,
+            )
+            seen_mod_ids.append(mod.id)
+
+        # Drop rows for mods that no longer exist in this workshop item
+        if seen_mod_ids:
+            await conn.execute(DELETE_STALE_MOD_PARSED, workshop_id, seen_mod_ids)
+
+    # Scrape the public Workshop page for the "Required Items" section so the
+    # API can auto-resolve missing-dep warnings against this mod's declared
+    # Steam-side dependencies. Best-effort: None on fetch error → leave the
+    # existing cached value; [] or list → overwrite.
+    required = await asyncio.to_thread(fetch_required_wsids, workshop_id)
+    if required is not None:
+        await conn.execute(
+            """
+            UPDATE workshop_meta
+               SET required_wsids = $1, required_scraped_at = now()
+             WHERE workshop_id = $2
+            """,
+            required, workshop_id,
+        )
+
+    return "refreshed"
+
+
+async def main_async(workshop_ids: List[str], dd_path: Path, force: bool, dsn: str) -> int:
+    print(f"[steam] fetching metadata for {len(workshop_ids)} item(s)")
+    details = fetch_workshop_details(workshop_ids)
+    missing_from_steam = [w for w in workshop_ids if w not in details]
+    if missing_from_steam:
+        print(f"[steam] no detail returned for: {missing_from_steam}", file=sys.stderr)
+
+    summary: Dict[str, int] = {"hit": 0, "refreshed": 0, "banned": 0, "missing": 0, "failed": 0}
+
+    conn = await asyncpg.connect(dsn=dsn)
+    try:
+        for wid in workshop_ids:
+            detail = details.get(wid)
+            if detail is None:
+                summary["missing"] += 1
+                print(f"  - {wid} -> missing (no Steam response)")
+                continue
+            status = await process_one(conn, wid, detail, dd_path, force)
+            summary[status] += 1
+            print(f"  - {wid} -> {status}")
+    finally:
+        await conn.close()
+
+    print(f"[done] {summary}")
+    return 0 if summary["failed"] == 0 else 1
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("workshop_ids", nargs="+")
+    ap.add_argument("--force", action="store_true", help="ignore cache, always re-download")
+    ap.add_argument("--dd-path", default=DEFAULT_DD_PATH)
+    ap.add_argument("--dsn", default=os.environ.get("DATABASE_URL"))
+    args = ap.parse_args()
+
+    if not args.dsn:
+        print("ERROR: --dsn or DATABASE_URL required", file=sys.stderr)
+        sys.exit(2)
+
+    dd = Path(args.dd_path)
+    if not dd.is_file():
+        print(f"ERROR: DepotDownloader not found at {dd}", file=sys.stderr)
+        sys.exit(2)
+
+    rc = asyncio.run(main_async(args.workshop_ids, dd, args.force, args.dsn))
+    sys.exit(rc)
+
+
+if __name__ == "__main__":
+    main()