# Phase 01 — Runnable service scaffold

**Story:** `US-01_create_anonymous_lobby` (partial — landing surface only)
**Context:** `.agents/PLAN.md` §4 (app/static/HTTP boundary), A1, A2, A12, A17, A18, A20

## Objective
Turn the empty repository into a launchable FastAPI service that serves the client
shell, exposes `/healthz`, enforces the no-external-asset rule, and has its quality
toolchain wired end to end. Nothing about gameplay exists yet; the app must still boot,
serve, and pass every check.

## Dependencies
- none (first phase; `pyproject.toml`, `Containerfile`, `compose.yaml`, `README.md`,
  `AGENTS.md`, `.agents/PLAN.md` already exist in the repo)

## Tasks
1. `01_lock_toolchain_and_packages.md` — deps resolve, `uv sync` clean, test tree + markers, first passing test
2. `02_config_and_debugpy.md` — typed env config, `.env.example`, debugpy bootstrap
3. `03_fastapi_app_and_static_shell.md` — app factory, CLI entry point, static shell page, security headers
4. `04_no_cdn_guard_and_docs.md` — no-external-asset test, header tests, README/AGENTS verified

## Testing & Quality
- Unit: config parsing/defaults/overrides; static asset scan finds zero external URLs;
  security headers present; `/healthz` returns 200 with a JSON body.
- Integration: app boots through `create_app()` and serves `/` and `/static/*`.
- Coverage: **>90%** on new/modified code (`config.py` and `server/app.py` fully covered).
- The phase is "Complete" only when the **entire** project test suite passes 100%
  (every test in the project, not just this phase's).
- Gate commands, all green: `uv run ruff check .`, `uv run pyright`, `uv run pytest`.

## Documentation & Consistency
- The final pass reviews `README.md` and `AGENTS.md` in full against the project as it
  will stand after this phase — fixing every inconsistency found, **including
  pre-existing ones not caused by this phase** (e.g. commands or variable names that
  drifted from `config.py`).
- Tasks update `README.md`/`AGENTS.md` immediately when their own changes are
  user-visible (setup, commands, configuration, features, conventions).

## Completion Criteria
- [ ] `uv sync --extra dev` succeeds and `uv.lock` is committed
- [ ] `uv run undercooked --host 127.0.0.1 --port 8000 &` then
      `curl -fsS http://127.0.0.1:8000/healthz` → `{"status":"ok"}`; `curl -fsS http://127.0.0.1:8000/` → the shell HTML
- [ ] `DEBUGPY=1 uv run undercooked` opens port 5678 and still serves `/healthz`
- [ ] `uv run pytest -q` → 100% passing, coverage ≥ 90%
- [ ] `uv run ruff check .` and `uv run pyright` → zero errors
- [ ] no file under `app/static/` references an external URL (test-enforced)
- [ ] README.md and AGENTS.md are accurate and consistent with the whole project (verified in the final pass)
- [ ] no behavior change in completed phases (n/a — first phase)