From 3de68b7539654df708de69f0f3207a393a21dfd4 Mon Sep 17 00:00:00 2001 From: mwiegand Date: Sun, 17 May 2026 12:20:45 +0200 Subject: [PATCH] docs(agents): forbid system paths in dev; point to scripts/dev-server.py Production paths (/var/lib/left4me, /usr/local/...) exist only on Linux deploy hosts. Local dev must use scripts/dev-server.py which sets LEFT4ME_ROOT=./.tmp/dev-server and seeds demo content. Running plain "flask run" leaves LEFT4ME_ROOT unset and the app falls back to the production path, surfacing as 404s on what looks like code bugs. Adds symptom-to-cause guidance so future agents diagnose "route 404 in dev" as a config issue, not a code defect. Co-Authored-By: Claude Opus 4.7 (1M context) --- AGENTS.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index db5b60e..c24232b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,6 +23,13 @@ Do not invent architecture outside these plans unless explicitly requested. - Do not use git worktrees. - 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. +### Dev server and filesystem paths + +- **Production paths (`/var/lib/left4me`, `/usr/local/lib/systemd/system`, `/usr/local/libexec/left4me`, `/etc/left4me`) exist only on Linux deploy hosts.** Never create or write to these on a developer machine. They are referenced in `l4d2host/l4d2host/paths.py` and the spec only as the production layout. +- **For local dev, always use `scripts/dev-server.py`.** It sets `LEFT4ME_ROOT=./.tmp/dev-server`, runs migrations, seeds demo content (admin + blueprint + script overlay + files overlay), and starts Flask on port 5051. Reset state with `rm -rf .tmp/dev-server` then re-run. Never invoke `flask run` directly — that leaves `LEFT4ME_ROOT` unset and the app falls back to the production `/var/lib/left4me`, which on macOS surfaces as "route returns 404 / empty modal / file not found" and can be mistaken for a code bug. +- **All ephemeral dev state lives under `.tmp/`** (gitignored). Use `$TMPDIR` only for transient files outside the repo. Do NOT use `/tmp`, `~/Library/Application Support`, or any system path for project state — only `.tmp/` (project-local) or `$TMPDIR` (sandbox-blessed). +- **Symptom-to-cause translation:** if a route returns 404 or behaves as if the filesystem is empty, the first diagnosis is "`LEFT4ME_ROOT` is wrong" (defaulted to the production path), not "code bug." Restart via `scripts/dev-server.py`. + ### Planning artifacts - Design specs live in `docs/superpowers/specs/` as `YYYY-MM-DD--design.md`.