cronekorkn/left4me
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(agents): forbid system paths in dev; point to scripts/dev-server.py

Browse source 
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) <noreply@anthropic.com>
This commit is contained in:
mwiegand 2026-05-17 12:20:45 +02:00
parent bc8edbcd50
commit 3de68b7539
No known key found for this signature in database
1 changed files with 7 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

7
AGENTS.md
View file

@ -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-<topic>-design.md`.