refactor(repo): uv workspace + hatchling + layout restructure

Migrate from pip-install-e + setuptools to a uv workspace with a
committed uv.lock for deterministic deps. Switch both members to
hatchling, and move package sources into nested standard layout
(l4d2host/l4d2host/, l4d2web/l4d2web/) so builds work from a
read-only source tree — setuptools wrote egg-info to source under
the old layout, which broke uv sync on the root-owned /opt/left4me/src.

Local dev install: `pip install -e ./l4d2host -e ./l4d2web` -> `uv sync`.
.envrc switches from `layout python python3.13` to `use uv`. Python
pinned to 3.13 via .python-version.

l4d2web now declares its cross-dep on l4d2host explicitly via
[tool.uv.sources] (workspace = true). l4d2web/alembic.ini and
l4d2web/alembic/ stay at the project root (standard alembic layout).

Test fixes:
- tests/__init__.py added to both test dirs so pytest doesn't shadow
  l4d2host as a namespace package via outer-dir walk.
- 3 CWD-relative paths in tests (l4d2web/static/css/{tokens,layout}.css
  and js/sse.js) anchored to Path(__file__) so they survive layout
  changes.
- Two test_install.py tests now monkeypatch HOME to tmp_path so they
  stop silently mutating ~/.steam/sdk32 on every run.

628 tests pass under sandboxed `uv run pytest`.

Per docs/superpowers/plans/2026-05-15-uv-workspace-execution.md;
prereq for the ckn-bw bundle's uv-sync action (queued).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.envrc

@@ -1 +1 @@
-layout python python3.13
+use uv

.python-version

@@ -0,0 +1 @@
+3.13

AGENTS.md

@@ -21,7 +21,7 @@ Do not invent architecture outside these plans unless explicitly requested.
 ### Workspace and tools
 
 - Do not use git worktrees.
-- Local Python venv is direnv-managed via `.envrc` (Python 3.13). After fresh checkout: `direnv allow`, then `pip install -e ./l4d2host -e ./l4d2web pytest`. See README **Local development** for details.
+- Repo is a uv workspace; Python is pinned to 3.13 via `.python-version`. After fresh checkout: install `uv` (`brew install uv` / `curl -LsSf https://astral.sh/uv/install.sh | sh`), then `direnv allow` (or `uv sync` directly). See README **Local development** for details.
 
 ### Planning artifacts
 

README.md

@@ -52,16 +52,17 @@ See `deploy/README.md` for the Linux test deployment contract, including the run
 
 ## Local development
 
-This repo uses [direnv](https://direnv.net/) to auto-activate a Python 3.13 venv on `cd` (matching the Debian Trixie production target). With direnv installed and hooked into your shell:
+This repo is a [uv](https://docs.astral.sh/uv/) workspace (`l4d2host` + `l4d2web` as members) with a committed `uv.lock` and a `.python-version` pinning Python 3.13 (matching the Debian Trixie production target).
 
-1. `direnv allow` once per fresh checkout (and after any `.envrc` change).
+One-time prereq: install `uv` (macOS: `brew install uv`; Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh` — `uv` is not yet in Debian stable's apt).
-2. `cd` out and back in — `.direnv/python-3.13/` is created and put on `PATH`.
+
-3. `pip install -e ./l4d2host -e ./l4d2web` to install both packages editable.
+1. `direnv allow` once per fresh checkout (and after any `.envrc` change). `.envrc` uses `use uv`, which runs `uv sync` and activates `.venv/` on `cd`.
-4. `pip install pytest` to run the test suites (`pytest tests/` inside either subproject).
+2. Without direnv: `uv sync` at the repo root creates `.venv/`, installs both workspace members editable, and pulls in dev deps (pytest) from the lockfile.
+3. Tests: `uv run pytest` (or just `pytest` once the venv is on PATH).
 
 ## Tech Stack (planned)
 
-- Python 3.12+
+- Python 3.13+ (workspace uses uv + hatchling)
 - Typer, PyYAML, pytest
 - Flask, SQLAlchemy, Alembic
 - HTMX (vendored locally), custom CSS, SSE

docs/superpowers/plans/2026-05-15-uv-workspace-execution.md

@@ -0,0 +1,408 @@
+# Plan — collapse left4me venv chain into uv workspace + `uv sync`
+
+**Status:** executed (left4me side). ckn-bw side queued — see
+`~/Projekte/ckn-bw/bundles/left4me/` and the matching section below.
+
+**Notable deviations from the original handoff
+(`docs/superpowers/specs/2026-05-15-handoff-uv-workspace.md`):**
+
+- Handoff assumed `pkg_apt: uv` works on Debian Trixie. It does not — uv
+  is in `experimental`/`sid` only. Replaced with a `left4me_install_uv`
+  action that downloads a pinned 0.11.8 tarball from astral-sh/uv
+  releases, SHA256-verifies, installs to `/usr/local/bin/`.
+- Handoff assumed the existing layout (`l4d2host/pyproject.toml` with
+  `package-dir = "."`) was workspace-compatible. It was not — setuptools
+  writes `egg-info/` to source during any build, which fails on the
+  root-owned `/opt/left4me/src` tree. Required layout restructure to
+  `l4d2host/l4d2host/` (package source nested) plus a switch from
+  setuptools to hatchling.
+- `git` is not installed on the prod host (bw drives git from the
+  control machine). Verification check #1 uses `find` for build
+  artifacts instead of `git status`.
+
+## Context
+
+The production deploy of left4me to `ovh.left4me` currently uses a 5-action
+chain in `ckn-bw/bundles/left4me/items.py` that builds out a Python venv
+under `/var/lib/left4me/.venv` by chaining `python3 -m venv` → `pip upgrade`
+→ `pip install` (with an 8-line tempdir-copy dance because the source at
+`/opt/left4me/src` is root-owned and setuptools wants to write `.egg-info/`
+into it) → `alembic upgrade` → `seed_overlays`. The chain has three
+problems:
+
+1. **Non-deterministic prod deploys.** `pip install` resolves whatever is
+   latest at apply time. A transitive CVE-relevant bump between two
+   `bw apply` runs is invisible until something breaks.
+2. **Cognitive cost.** The tempdir-copy in `left4me_pip_install` is the
+   single longest, gnarliest action in the bundle.
+3. **Implicit cross-package dep.** `l4d2web` imports from `l4d2host.paths`
+   in 5 files but doesn't declare the dependency — today's setup works
+   only because both get `pip install -e`'d side-by-side.
+
+This plan migrates the repo to a uv workspace with a committed `uv.lock`,
+replacing the 5-action chain with `left4me_install_uv` (download +
+SHA256 verify, idempotent — only re-runs on version change) plus
+`left4me_uv_sync`. On the steady-state path (uv already pinned at
+0.11.8), only `uv_sync` fires per deploy. Both sides of the change
+(left4me repo and the ckn-bw `left4me` bundle) ship together. The plan
+executes the migration sequence already documented in
+`/Users/mwiegand/Projekte/left4me/docs/superpowers/specs/2026-05-15-handoff-uv-workspace.md`
+— treat that handoff as the design document. This plan adds the
+empirically-verified ground truth, resolves the small open questions, and
+encodes the executable sequence.
+
+## Source of truth
+
+- **Design**: `docs/superpowers/specs/2026-05-15-handoff-uv-workspace.md`
+  (in the left4me repo) — read this first; do not duplicate its content
+  here.
+- **Sibling context** (don't dive in):
+  `docs/superpowers/specs/2026-05-15-deployment-responsibility-design.md`
+  (just-shipped; left the venv chain alone),
+  `docs/superpowers/specs/2026-05-15-runtime-state-relocation-design.md`
+  (made `/opt/left4me/src` root-owned, which is *why* the current
+  tempdir-copy dance exists).
+
+## Resolved questions (from planning)
+
+- **Branch flow**: direct-to-master on both sides. (Matches left4me's
+  recent workflow, e.g. `b13d164`, `55b0138`. ckn-bw side committed
+  but NOT pushed — operator pushes manually.)
+- **Python version alignment**: align all three pyprojects (root + both
+  members) to `requires-python = ">=3.13"`. Matches `.envrc` and the
+  production host. Removes the workspace-vs-member skew.
+- **Spike test scope**: extend beyond the handoff to also dry-run a
+  `uv sync --frozen` shape against a root-owned source — the production
+  command path is `sync`, not `build`, and they're different code paths.
+- **Scope handoff at `git push`**: agent's deliverable is two ready-to-deploy
+  commits (left4me pushed; ckn-bw committed but unpushed). The user runs
+  `bw apply ovh.left4me`, the post-apply restart, and the 6-check
+  verification matrix themselves. (Per session memory:
+  `feedback_left4me_deploy_workflow` — supersedes the original prompt's
+  ask to drive apply + verify end-to-end.) The spike test remains agent
+  work — it's information gathering, and the one-shot direct install
+  fits the "one-shot via direct command" rule from the same memory.
+- **uv install vector**: direct GitHub tarball download + SHA256 verify
+  against the official `.sha256` sibling, install to `/usr/local/bin/`.
+  The handoff doc's `pkg_apt: uv` assumption was wrong — uv is not in
+  Debian Trixie's apt archive (in `experimental`/`sid` only). Astral's
+  canonical methods are curl-pipe-sh and direct tarball; we chose
+  tarball for auditability and pattern-match with the existing
+  `left4me_install_steamcmd` action. Pin to **uv 0.11.8** to match
+  the local brew-installed version, eliminating the lockfile-format-skew
+  risk between dev and prod.
+
+## Ground-truth from exploration
+
+- **Cross-package imports confirmed**: 5 files in `l4d2web/` import
+  `from l4d2host.paths`:
+  - `l4d2web/routes/overlay_routes.py`
+  - `l4d2web/services/overlay_creation.py`
+  - `l4d2web/services/overlay_builders.py`
+  - `l4d2web/services/overlay_files.py`
+  - `l4d2web/services/workshop_paths.py`
+- **Layout compatibility**: both members use `[tool.setuptools.package-dir]
+  {name} = "."` (pyproject lives inside the package directory). uv
+  workspace `members = ["l4d2host", "l4d2web"]` handles this fine — uv
+  uses the pyproject as the project root regardless of the package-dir
+  mapping.
+- **`.gitignore` already covers** `*.egg-info/`, `.venv/`, `__pycache__/`,
+  etc. No `.gitignore` changes needed.
+- **No `pytest.ini` / `[tool.pytest.ini_options]` exists** — pytest
+  defaults work; `uv run pytest` from repo root will discover tests in
+  `l4d2host/tests/` and `l4d2web/tests/`.
+- **Bundle action conventions** (from `ckn-bw/bundles/left4me/items.py`
+  and neighbors): every action sets `cascade_skip: False` explicitly.
+  Action keys in use: `command`, `triggered`, `cascade_skip`, `unless`,
+  `needs`, `triggers`, `comment`.
+- **Additional `git_deploy` consumer**: `left4me_chmod_scripts` at
+  `items.py:324` also `needs: 'git_deploy:/opt/left4me/src'`. Untouched
+  by this refactor, but listed here so it's not missed during review.
+- **Bundle README §"deploy-flow"**: lines 84–90 of
+  `bundles/left4me/README.md` document the pip_install tempdir dance.
+  This is the prose to rewrite (not vague — those exact lines).
+- **`apt.packages`** declaration: `metadata.py:29–49`. Currently lists
+  `python3`, `python3-venv`, `python3-pip`, `python3-dev`, plus i386
+  multiarch entries.
+- **uv NOT in Debian Trixie apt archive** (verified via
+  `apt-cache search "^uv$"` and `apt-cache policy uv` on the live host
+  — both return nothing for the actual `uv` package). Handoff doc's
+  assumption was wrong on this point.
+- **`git` is NOT installed on the production host** (verified via
+  `command -v git` on prod returning empty; `/usr/bin/git` doesn't
+  exist). The bw `git_deploy` item operates from the *control* machine
+  (dev laptop), pushing files to prod via SSH — prod itself needs no
+  git. Implication: the handoff's verification check #1
+  (`sudo git -C /opt/left4me/src status --porcelain`) cannot be used.
+  Replace with `find /opt/left4me/src \( -name '*.egg-info' -o -name
+  build -o -name dist \) -print`.
+- **ckn-bw is currently EVEN with `origin/master`** (verified via
+  `git status -sb` showing `## master...origin/master` with empty
+  log). The original prompt's "7 commits ahead" was stale — the
+  operator has since pushed. After our ckn-bw commit lands locally,
+  the repo will be 1 commit ahead (not 8).
+- **Prod arch**: `x86_64` / `amd64`. **Prod curl**: 8.14.1 at
+  `/usr/bin/curl`. **Prod tar**: GNU tar 1.35. **Prod install**: GNU
+  coreutils 9.7. **`/usr/local/bin`** exists, root-owned, currently
+  contains only the `downtime` binary.
+- **Current prod venv state**: `/var/lib/left4me/.venv/` exists, owned
+  by `left4me:left4me`, contains `python3.13`, `pip`, `alembic`,
+  `flask`, `gunicorn`, `l4d2ctl`. `pip show l4d2host` / `pip show
+  l4d2web` both report version 0.1.0. So uv will be adopting a venv
+  that already has working installs of both members + their deps.
+- **Local dev environment**: `uv 0.11.8` (brew), `direnv 2.37.1`
+  (supports `use uv`), `python 3.13.13`. No `.venv` exists locally yet
+  — clean slate.
+
+## Critical files
+
+### left4me repo
+- **NEW** `/Users/mwiegand/Projekte/left4me/pyproject.toml` — workspace root
+- **NEW** `/Users/mwiegand/Projekte/left4me/uv.lock` — generated via `uv lock`
+- `l4d2host/pyproject.toml:10` — bump `requires-python` to `>=3.13`
+- `l4d2web/pyproject.toml:10–18` — bump `requires-python`, add
+  `"l4d2host"` to `dependencies`, add `[tool.uv.sources] l4d2host = { workspace = true }`
+- `.envrc` — replace `layout python python3.13` with `use uv` (with
+  fallback if direnv stdlib is too old)
+- `README.md`, `AGENTS.md`, `l4d2web/README.md` — update install
+  instructions
+
+### ckn-bw repo (`~/Projekte/ckn-bw/`)
+- `bundles/left4me/metadata.py:29–49` — **ensure** `'curl': {}` is in
+  `apt.packages` (required by the new install action; verify it's not
+  already inherited from a base bundle). **Drop** `'python3-pip'` (uv
+  replaces pip; bundle has no other consumer). **Drop** `'python3-venv'`
+  (the chain no longer uses `python3 -m venv`; uv creates its own venv
+  via `UV_PROJECT_ENVIRONMENT`). **Keep** `'python3'`, `'python3-dev'`,
+  and the i386 multiarch entries.
+  **Do NOT add** `'uv': {}` — uv is not in Trixie's apt archive.
+- `bundles/left4me/items.py:285–305` — update `git_deploy:/opt/left4me/src`
+  triggers: replace `action:left4me_pip_install` with
+  `action:left4me_uv_sync`
+- `bundles/left4me/items.py:328–340` — **DELETE** `left4me_create_venv`
+- `bundles/left4me/items.py:342–352` — **DELETE** `left4me_pip_upgrade`
+- `bundles/left4me/items.py:354–382` — **DELETE** `left4me_pip_install`
+  (replaced by `left4me_uv_sync` below)
+- `bundles/left4me/items.py:384–407` — `left4me_alembic_upgrade`:
+  update `needs:` (or `triggered_by:` equivalent) to point at
+  `action:left4me_uv_sync` instead of `action:left4me_pip_install`
+- `bundles/left4me/items.py` — **ADD** two new actions:
+  - `left4me_install_uv`: download pinned 0.11.8 tarball from
+    github.com/astral-sh/uv/releases/, SHA256-verify, install to
+    /usr/local/bin/. Idempotent via `unless: '/usr/local/bin/uv --version
+    | grep -qx "uv 0.11.8"'`. `needs: ['pkg_apt:curl']`,
+    `triggers: ['action:left4me_uv_sync']`. (Body matches the approved
+    preview, with `unless:` refined to `grep -qx` for BRE portability.)
+  - `left4me_uv_sync`: `sudo -u left4me env
+    UV_PROJECT_ENVIRONMENT=/var/lib/left4me/.venv /usr/local/bin/uv
+    sync --frozen --project /opt/left4me/src`. `triggered: True`,
+    `cascade_skip: False`, `needs:` includes
+    `'git_deploy:/opt/left4me/src'`, `'action:left4me_install_uv'`,
+    `'directory:/var/lib/left4me'`, `'user:left4me'`. `triggers:
+    ['action:left4me_alembic_upgrade']`.
+- `bundles/left4me/README.md:84–90` — rewrite the deploy-flow description
+  to mention the install_uv + uv_sync chain instead of the tempdir-dance
+
+## Execution steps
+
+### Step 0 — Spike test (extended) — DO FIRST
+Verify the architectural assumption empirically on the live host.
+Uses the SAME install vector the production action will use (direct
+tarball + SHA256 verify), so the spike doubles as a smoke test for
+the install action itself.
+
+```bash
+# A. Install pinned uv on prod (one-shot via direct command; matches
+#    what the future bw action will do).
+ssh ckn@left4.me '
+  set -e
+  tmpdir=$(mktemp -d); trap "rm -rf $tmpdir" EXIT
+  base=https://github.com/astral-sh/uv/releases/download/0.11.8
+  tar=uv-x86_64-unknown-linux-gnu.tar.gz
+  curl -fsSL -o $tmpdir/$tar       $base/$tar
+  curl -fsSL -o $tmpdir/$tar.sha256 $base/$tar.sha256
+  (cd $tmpdir && sha256sum -c $tar.sha256)
+  tar -xzf $tmpdir/$tar -C $tmpdir --strip-components=1
+  sudo install -m 0755 $tmpdir/uv  /usr/local/bin/uv
+  sudo install -m 0755 $tmpdir/uvx /usr/local/bin/uvx
+  /usr/local/bin/uv --version
+'
+
+# B. uv build against root-owned source: source must stay clean.
+ssh ckn@left4.me '
+  sudo -u left4me sh -c "
+    wheels=\$(mktemp -d)
+    /usr/local/bin/uv build --wheel --sdist /opt/left4me/src/l4d2host --out-dir \$wheels
+    ls \$wheels
+  "
+'
+# Cleanliness probe — git not on prod, so use find for build artifacts.
+# Expected: only-existing egg-info dirs (the ones already on disk from
+# the current pip install -e flow); NO NEW artifacts from this run.
+# Capture a baseline BEFORE the build, compare AFTER.
+ssh ckn@left4.me 'sudo find /opt/left4me/src \( -name "*.egg-info" -o -name build -o -name dist -o -name "__pycache__" \) -printf "%T@ %p\n" | sort'
+
+# C. Extended sync-shape check — dry-run `uv sync --frozen` against a
+#    root-owned workspace mock in /tmp. Verify the project root stays
+#    clean (no .python-version written, no transient files left over).
+#    This validates that `uv sync` (not just `uv build`) is safe against
+#    a read-only project tree, which is the actual production code path.
+```
+
+**Decision gate**:
+- Source stays clean across B and C → proceed with full plan.
+- New `*.egg-info` / `build/` / `dist/` directories appear in
+  `/opt/left4me/src` after `uv build` → fall back to **Medium scope**
+  (handoff §"Empirical spike" → fallback). Update the handoff doc to
+  record the fallback decision and re-plan.
+- `uv sync` writes into the project root during step C → also fall back
+  to Medium scope. Same handoff update.
+
+### Step 1 — left4me workspace setup (local)
+1. Write `/Users/mwiegand/Projekte/left4me/pyproject.toml` (workspace root)
+   — see handoff §"What changes — left4me side / New: pyproject.toml"
+2. Bump `l4d2host/pyproject.toml:10` to `requires-python = ">=3.13"`
+3. Update `l4d2web/pyproject.toml`: bump `requires-python`, add
+   `"l4d2host"` to `dependencies`, append `[tool.uv.sources]` block
+4. `uv lock` at the repo root → produces `uv.lock`
+5. `uv sync` → creates `.venv/`, installs both members editable + pytest
+6. `uv run pytest` → all green
+7. Update `.envrc`: replace `layout python python3.13` with `use uv`
+   (fallback to `uv sync >/dev/null && source .venv/bin/activate` if
+   the dev's direnv version doesn't ship `use uv`)
+8. Update `README.md`, `AGENTS.md`, `l4d2web/README.md`: replace the
+   `pip install -e ...` invocation with `uv sync` and add the one-time
+   prereq line about installing uv. Mention macOS (`brew install uv`)
+   and Linux (curl-pipe-sh from astral.sh) — **do NOT** suggest
+   `apt install uv`, as it's not in Debian's apt archive yet (only
+   `experimental`/`sid`).
+
+### Step 2 — left4me commit + push
+Single commit using the suggested message from the handoff
+(§"Commit messages — left4me side"). Push to `origin` (gitlab on
+sublimity.de — confirmed safe-publish-exempt per memory). The commit
+makes the workspace and lockfile available to ckn-bw's `git_deploy`.
+
+### Step 3 — ckn-bw bundle refactor
+1. Edit `bundles/left4me/metadata.py:29–49`:
+   - Ensure `'curl': {}` is in `apt.packages` (verify it's not already
+     inherited from a base bundle; if not, add it explicitly).
+   - Drop `'python3-pip'` (uv replaces pip; bundle has no other
+     consumer — grep the bundle to confirm).
+   - Drop `'python3-venv'` (chain no longer uses `python3 -m venv`).
+   - Keep `'python3'`, `'python3-dev'`, and the i386 multiarch entries.
+   - **Do NOT add `'uv': {}`** — not in Trixie's apt.
+2. Edit `bundles/left4me/items.py`:
+   - Delete `left4me_create_venv`, `left4me_pip_upgrade`,
+     `left4me_pip_install` blocks (lines 328–382 inclusive).
+   - Add `left4me_install_uv` action: downloads pinned uv 0.11.8 tarball
+     from github.com/astral-sh/uv/releases/, SHA256-verifies against the
+     official `.sha256` sibling, installs to `/usr/local/bin/{uv,uvx}`.
+     Idempotent via `unless: '/usr/local/bin/uv --version 2>/dev/null
+     | grep -qx "uv 0.11.8"'`. `needs: ['pkg_apt:curl']`,
+     `triggers: ['action:left4me_uv_sync']`, `triggered: False`,
+     `cascade_skip: False`.
+   - Add `left4me_uv_sync` action: `sudo -u left4me env
+     UV_PROJECT_ENVIRONMENT=/var/lib/left4me/.venv /usr/local/bin/uv
+     sync --frozen --project /opt/left4me/src`. `triggered: True`,
+     `cascade_skip: False`. `needs:` includes
+     `'git_deploy:/opt/left4me/src'`, `'action:left4me_install_uv'`,
+     `'directory:/var/lib/left4me'`, `'user:left4me'`. `triggers:
+     ['action:left4me_alembic_upgrade']`.
+   - Update `git_deploy:/opt/left4me/src` triggers (lines 285–305):
+     replace `'action:left4me_pip_install'` with
+     `'action:left4me_uv_sync'`. Keep `left4me_alembic_upgrade` and
+     `left4me_daemon_reload` triggers.
+   - Update `left4me_alembic_upgrade` (lines 384–407): its dependency
+     on `left4me_pip_install` must now point at `left4me_uv_sync`.
+3. Rewrite `bundles/left4me/README.md:84–90` to describe the new
+   `install_uv → uv_sync → alembic_upgrade → seed_overlays + restart`
+   chain (drop the pip + tempdir-dance prose).
+4. `(cd ~/Projekte/ckn-bw && .venv/bin/bw test)` → must pass clean.
+
+### Step 4 — ckn-bw commit (DO NOT PUSH)
+Single commit using the suggested message from the handoff
+(§"Commit messages — ckn-bw side"). Do **not** `git push`. Per
+verified state today, ckn-bw is currently EVEN with `origin/master`
+(not 7 ahead as the original prompt claimed — the operator pushed
+since the prompt was written). After this commit lands locally, the
+repo will be 1 commit ahead of origin.
+
+### Step 5 — Report to operator (handoff to user for deploy)
+Agent's work ends here. Brief summary to the user including:
+- Spike outcome (full uv-workspace path confirmed, or Medium-scope
+  fallback taken — including any handoff doc updates if the latter).
+- What's committed and where it sits: left4me pushed to `origin/master`;
+  ckn-bw committed locally, now 1 commit ahead of origin (unpushed).
+- The `bw apply ovh.left4me` invocation for the user to run, with the
+  expected output (left4me_install_uv runs the download+verify, three
+  old actions removed from the graph, two new actions present
+  (install_uv + uv_sync), alembic+seed+restart cascade fires).
+- The 6-check verification matrix from handoff §"Verification
+  (end-to-end)" for the user to walk through after apply — with
+  check #1 amended: use
+  `sudo find /opt/left4me/src \( -name '*.egg-info' -o -name build
+  -o -name dist \) -newer <baseline>` instead of `git status`,
+  because git isn't installed on prod.
+- Recovery path if uv refuses to adopt the existing venv: one-shot
+  `ssh ckn@left4.me 'sudo -u left4me rm -rf /var/lib/left4me/.venv'`,
+  then re-apply.
+- Open follow-ups (uv version pinning policy — bump cadence, signing,
+  etc; direnv `use uv` fallback applied or not; whether to add a
+  separate `pkg_apt: curl` if it wasn't already declared).
+
+**Do NOT run `bw apply`, the verification matrix, or the gameserver
+round-trip — those are explicitly user-side per session memory.**
+
+## Plan storage after approval
+
+Per the user's global AGENTS.md (`~/.claude/agents/AGENTS.md`): specs
+and plans live in the repo they describe, typically under `docs/`. After
+ExitPlanMode and approval, this plan should be copied to
+`/Users/mwiegand/Projekte/left4me/docs/superpowers/plans/2026-05-15-uv-workspace-execution.md`
+as a peer to the design handoff, then committed alongside the left4me
+changes in Step 2.
+
+## What does NOT change (out of scope)
+
+- Source ownership: `/opt/left4me/src` stays root-owned.
+- Venv location: `/var/lib/left4me/.venv` stays where it is, owned by
+  the `left4me` user, accessed via `UV_PROJECT_ENVIRONMENT`.
+- Hardening drop-ins, sudoers, sysctl, helpers — all stable from the
+  deployment-responsibility migration.
+- systemd unit shapes — reactor-emitted, unchanged.
+- `alembic_upgrade` and `seed_overlays` shell bodies — same commands,
+  just triggered from `uv_sync` instead of `pip_install`.
+- `pkg_apt: python3` and `python3-dev` — kept (uv shells out to system
+  Python).
+- Other ckn-bw bundles — this is left4me-specific.
+- The build-overlay-unit refactor — separate queued thread.
+- CI — none currently exists.
+
+## Risks (carried from handoff, sized empirically)
+
+1. **Spike test failure** → fall back to Medium scope. Graceful.
+2. ~~Lockfile format skew between dev and prod~~ → **MITIGATED** by
+   pinning prod uv to 0.11.8 (same as local brew). Lockfile generated
+   by dev's uv 0.11.8 will be consumed by prod's uv 0.11.8 byte-for-byte
+   compatible. Risk effectively eliminated unless dev's brew bumps uv
+   independently — track this in the pinning-policy follow-up.
+3. **direnv `use uv` availability** → local direnv is 2.37.1 (`use uv`
+   added in 2.34+, so we're fine). Fallback snippet documented in case
+   another dev has an older direnv.
+4. **`alembic`/`flask` binary paths** → uv installs the same
+   `console_scripts` entrypoints as pip, so paths under
+   `/var/lib/left4me/.venv/bin/` are identical. Verify in verification
+   matrix.
+5. **`--force-reinstall` semantics** → no longer needed; `uv sync` is
+   lockfile-aware, not package-version-aware.
+6. **uv release artifact availability** → if github.com/astral-sh/uv
+   takes down release 0.11.8 (extremely unlikely but theoretically
+   possible), the install action would fail. Mitigation: pin a recent
+   stable release, monitor astral's deprecation cadence; if needed,
+   mirror the artifact to an internal location for future-proofing
+   (out of scope for this migration).
+7. **SHA256 of the tarball** → we trust the `.sha256` sibling fetched
+   from the same github release. A future hardening pass could embed
+   the checksum in the bundle source for offline verification, but the
+   current trust model matches steamcmd's (also github-sourced).

docs/superpowers/specs/2026-05-15-handoff-uv-workspace.md

@@ -2,10 +2,13 @@
 
 ## Status
 
-Queued. Independent of the deployment-responsibility reshape
+**Executed (left4me side) — see
-(`2026-05-15-deployment-responsibility-design.md`) which just shipped;
+`docs/superpowers/plans/2026-05-15-uv-workspace-execution.md` for what
-that work left the venv-chain shape intact. This handoff replaces the
+actually shipped and what diverged from the assumptions below.** Three
-chain end-to-end.
+load-bearing assumptions in this doc turned out to be wrong (no
+`pkg_apt: uv` on Trixie; existing layout incompatible with read-only
+source builds via setuptools; no `git` on prod). The executed plan
+records the corrections.
 
 ## Goal
 

l4d2host/pyproject.toml

@@ -1,13 +1,13 @@
 [build-system]
-requires = ["setuptools>=68", "wheel"]
+requires = ["hatchling"]
-build-backend = "setuptools.build_meta"
+build-backend = "hatchling.build"
 
 [project]
 name = "l4d2host"
 version = "0.1.0"
 description = "L4D2 host library and CLI"
 readme = "README.md"
-requires-python = ">=3.12"
+requires-python = ">=3.13"
 dependencies = [
   "typer>=0.12",
   "PyYAML>=6.0",
@@ -15,9 +15,3 @@ dependencies = [
 
 [project.scripts]
 l4d2ctl = "l4d2host.cli:app"
-
-[tool.setuptools]
-packages = ["l4d2host"]
-
-[tool.setuptools.package-dir]
-l4d2host = "."

l4d2host/tests/test_install.py

@@ -5,7 +5,9 @@ import pytest
 from l4d2host.steam_install import SteamInstaller
 
 
-def test_windows_then_linux(monkeypatch: pytest.MonkeyPatch) -> None:
+def test_windows_then_linux(tmp_path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path / "home"))
+    monkeypatch.setenv("LEFT4ME_ROOT", str(tmp_path))
     calls: list[list[str]] = []
 
     def fake_run_command(cmd, **kwargs):
@@ -36,6 +38,7 @@ def test_fail_fast_on_first_failure(monkeypatch: pytest.MonkeyPatch) -> None:
 
 
 def test_default_install_dir_uses_left4me_root(tmp_path, monkeypatch):
+    monkeypatch.setenv("HOME", str(tmp_path / "home"))
     monkeypatch.setenv("LEFT4ME_ROOT", str(tmp_path))
     calls = []
     monkeypatch.setattr("l4d2host.steam_install.run_command", lambda cmd, **kwargs: calls.append(cmd))

l4d2web/README.md

@@ -22,10 +22,11 @@ Flask web app for managing L4D2 servers through user-private blueprints.
 
 ## Development
 
+From the workspace root (`../`):
+
 ```bash
-python3 -m venv .venv
+uv sync          # creates .venv, installs l4d2host + l4d2web editable, plus dev deps
-.venv/bin/pip install -e .
+uv run pytest l4d2web/tests -q
-.venv/bin/pytest tests -q
 ```
 
 ## Configuration

l4d2web/pyproject.toml

@@ -1,13 +1,13 @@
 [build-system]
-requires = ["setuptools>=68", "wheel"]
+requires = ["hatchling"]
-build-backend = "setuptools.build_meta"
+build-backend = "hatchling.build"
 
 [project]
 name = "l4d2web"
 version = "0.1.0"
 description = "L4D2 web app"
 readme = "README.md"
-requires-python = ">=3.12"
+requires-python = ">=3.13"
 dependencies = [
   "Flask>=3.0",
   "SQLAlchemy>=2.0",
@@ -15,18 +15,8 @@ dependencies = [
   "PyYAML>=6.0",
   "gunicorn>=22.0",
   "requests>=2.31",
+  "l4d2host",
 ]
 
-[tool.setuptools]
+[tool.uv.sources]
-packages = ["l4d2web", "l4d2web.routes", "l4d2web.services"]
+l4d2host = { workspace = true }
-
-[tool.setuptools.package-dir]
-l4d2web = "."
-
-[tool.setuptools.package-data]
-l4d2web = [
-  "templates/*.html",
-  "static/css/*.css",
-  "static/js/*.js",
-  "static/vendor/*.js",
-]

l4d2web/tests/test_job_logs.py

@@ -104,7 +104,7 @@ def test_sse_resumes_from_last_event_id_header(seeded_job_logs) -> None:
 
 
 def test_sse_js_handles_job_log_custom_events() -> None:
-    js = Path("l4d2web/static/js/sse.js").read_text()
+    js = (Path(__file__).resolve().parents[1] / "l4d2web" / "static" / "js" / "sse.js").read_text()
 
     assert 'addEventListener("stdout"' in js
     assert 'addEventListener("stderr"' in js

l4d2web/tests/test_pages.py

@@ -91,7 +91,7 @@ def test_shell_nav_uses_main_sections(auth_client_with_server) -> None:
 
 
 def test_css_tokens_define_neutral_light_and_dark_theme() -> None:
-    css = Path("l4d2web/static/css/tokens.css").read_text()
+    css = (Path(__file__).resolve().parents[1] / "l4d2web" / "static" / "css" / "tokens.css").read_text()
 
     for token in [
         "--color-bg",
@@ -113,11 +113,11 @@ def test_css_tokens_define_neutral_light_and_dark_theme() -> None:
     ]:
         assert token in css
     assert "prefers-color-scheme: dark" in css
-    assert "radial-gradient" not in Path("l4d2web/static/css/layout.css").read_text()
+    assert "radial-gradient" not in (Path(__file__).resolve().parents[1] / "l4d2web" / "static" / "css" / "layout.css").read_text()
 
 
 def test_log_tokens_follow_light_and_dark_theme() -> None:
-    css = Path("l4d2web/static/css/tokens.css").read_text()
+    css = (Path(__file__).resolve().parents[1] / "l4d2web" / "static" / "css" / "tokens.css").read_text()
 
     assert "--color-log-bg: #f8fafc;" in css
     assert "--color-log-text: #18181b;" in css