From 0d906605e9e3d16827f455fe7102097a5c6921a4 Mon Sep 17 00:00:00 2001
From: mwiegand <martin.wiegand@seibert.group>
Date: Fri, 8 May 2026 18:56:51 +0200
Subject: [PATCH] chore: add direnv .envrc for local Python 3.13 venv

Pins to python3.13 to match the Debian Trixie production target.
Documents the dev setup in README and AGENTS.md so a fresh checkout
gets a working `python` via `direnv allow` + editable installs.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .envrc     | 1 +
 .gitignore | 1 +
 AGENTS.md  | 1 +
 README.md  | 9 +++++++++
 4 files changed, 12 insertions(+)
 create mode 100644 .envrc

diff --git a/.envrc b/.envrc
new file mode 100644
index 0000000..63e22a3
--- /dev/null
+++ b/.envrc
@@ -0,0 +1 @@
+layout python python3.13
diff --git a/.gitignore b/.gitignore
index 947d73e..6ef3e46 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,7 @@
 .worktrees/
 .claude/
 .venv/
+.direnv/
 .pytest_cache/
 __pycache__/
 *.pyc
diff --git a/AGENTS.md b/AGENTS.md
index b29f4b8..4fff97e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,6 +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.
 
 ### Naming and boundaries
 
diff --git a/README.md b/README.md
index 67fe5ff..15266a2 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,15 @@ Implementation plans remain the source of truth for architecture and task sequen
 
 See `deploy/README.md` for the Linux test deployment contract, including the runtime user, target filesystem layout, systemd units, privileged helpers, sudoers rules, admin bootstrap, and overlay reference rules.
 
+## 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:
+
+1. `direnv allow` once per fresh checkout (and after any `.envrc` change).
+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.
+4. `pip install pytest` to run the test suites (`pytest tests/` inside either subproject).
+
 ## Tech Stack (planned)
 
 - Python 3.12+