docs: add README and AGENTS project guidance

AGENTS.md

@@ -0,0 +1,83 @@
+# AGENTS.md
+
+Guidance for coding agents working in this repository.
+
+## Mission
+
+Build `left4me` according to the two implementation plans:
+
+- `docs/superpowers/plans/2026-04-22-l4d2-host-lib-v1.md`
+- `docs/superpowers/plans/2026-04-23-l4d2-web-app-v1.md`
+
+Do not invent architecture outside these plans unless explicitly requested.
+
+## Current Project State
+
+- Repo is newly initialized.
+- Only planning docs exist right now.
+- Implementation directories are planned, not yet created.
+
+## Non-Negotiable Constraints
+
+### Naming and boundaries
+
+- Use `l4d2` naming consistently.
+- Keep host library and web app as separate components.
+- Do not collapse them into one package.
+
+### Host library (`l4d2host` / `l4d2ctl`)
+
+- Exposed CLI command set is fixed:
+  - `install`
+  - `initialize <name> -f <spec.yaml>`
+  - `start <name>`
+  - `stop <name>`
+  - `delete <name>`
+- Hard-coded paths under `/opt/l4d2`.
+- Overlays are external directories (no overlay content management here).
+- Fail-fast subprocess behavior; pass raw stderr; propagate return code.
+- No lock manager, no rollback, no preflight runtime checks.
+- Delete missing instance/runtime dirs must succeed (no-op).
+- Read APIs required for web app integration:
+  - `get_instance_status(name)`
+  - `stream_instance_logs(name, lines=200, follow=True)`
+
+### Web app (`l4d2-web-app`)
+
+- Flask + server-rendered templates + vendored HTMX.
+- No external frontend framework/dependencies.
+- Custom CSS with consistent link color `#0F766E`.
+- Local username/password auth and `admin` flag.
+- Persist command logs in `job_logs` table (retain indefinitely).
+- Desired vs actual server state model.
+- Live logs in UI for both jobs and servers.
+- Blueprint semantics (locked):
+  - private per user in v1
+  - live-linked to servers
+  - no server-level overrides
+  - deleting in-use blueprint is blocked
+  - updates apply on next action
+  - servers can reassign blueprint anytime
+
+## Delivery Workflow
+
+1. Read both plan files fully before coding.
+2. Execute plan tasks in order.
+3. Keep changes scoped to one task at a time.
+4. Run task-level tests before moving forward.
+5. Do not claim completion without command evidence.
+6. Keep docs updated when behavior/contracts change.
+
+## Verification Expectations
+
+Before claiming success on any step, run the relevant command and report actual output status.
+
+Typical commands (once components exist):
+
+- `pytest components/l4d2-host-lib/tests -q`
+- `pytest components/l4d2-web-app/tests -q`
+
+## Change Control
+
+- If a requested change conflicts with this file, follow explicit user instruction.
+- If plans and code diverge, update plans or flag the mismatch clearly.

README.md

@@ -0,0 +1,64 @@
+# left4me
+
+`left4me` is a local L4D2 server management platform with two planned components:
+
+1. `l4d2host` + `l4d2ctl` (host library + CLI)
+2. `l4d2-web-app` (Flask web app for users, blueprints, servers, jobs, and logs)
+
+## Status
+
+This repository is currently in planning phase.
+Implementation plans are the source of truth:
+
+- `docs/superpowers/plans/2026-04-22-l4d2-host-lib-v1.md`
+- `docs/superpowers/plans/2026-04-23-l4d2-web-app-v1.md`
+
+## Locked v1 Decisions
+
+- Naming is strictly `l4d2` (not `l4d`).
+- Host library and web app are separate components.
+- Host CLI commands are fixed to:
+  - `install`
+  - `initialize <name> -f <spec.yaml>`
+  - `start <name>`
+  - `stop <name>`
+  - `delete <name>`
+- Runtime paths are hard-coded under `/opt/l4d2`.
+- Overlay handling is directory-based and externally populated.
+- No lock manager, no rollback, no preflight checks in host library.
+- CLI propagates subprocess failures via stderr and return code.
+- `delete` on missing instance is no-op success.
+- Blueprint model (web app):
+  - user-private in v1
+  - servers are live-linked to blueprint
+  - no per-server overrides
+  - delete blueprint blocked when linked servers exist
+  - blueprint changes apply on next action
+  - server can reassign blueprint anytime
+
+## Planned Repository Layout
+
+- `components/l4d2-host-lib/`
+- `components/l4d2-web-app/`
+- `docs/superpowers/plans/`
+
+## Tech Stack (planned)
+
+- Python 3.12+
+- Typer, PyYAML, pytest
+- Flask, SQLAlchemy, Alembic
+- HTMX (vendored locally), custom CSS, SSE
+- systemd user units, fuse-overlayfs, steamcmd
+
+## Recommended Implementation Order
+
+1. Implement `components/l4d2-host-lib` plan first.
+2. Implement `components/l4d2-web-app` plan second.
+3. Keep tests green task-by-task (TDD flow from plans).
+4. Keep commits small and aligned with plan tasks.
+
+## Contributing Notes
+
+- Follow plan task order unless explicitly re-planned.
+- Keep contracts above unchanged unless the user asks to change them.
+- Update plan docs when scope or behavior changes.