initial

AGENTS.md

@@ -2,51 +2,50 @@
 
 ## Project Structure & Module Organization
 
-- `hearthmod/` contains orchestration scripts (`host_ctl_ubuntu.sh`, `docker_ctl.sh`) and legacy Docker setup.
+- `hearthmod/` contains legacy orchestration scripts and original docs.
 - Core C services live in `hm_gameserver/`, `hm_lobbyserver/`, and shared code in `hm_base/`.
 - Web UI is in `hm_web/` (Python `web.py`, templates, and static assets).
-- Card rendering and assets are in `hm_sunwell/` (Node-based renderer).
+- Card rendering lives in `hm_sunwell/` (Node-based renderer).
 - TLS proxy and web server components live in `hm_stud/` and `hm_nginx/`.
-- Database snapshot and seed data are in `hm_database/`.
-
-Long-term maintainability should focus on repeatable local environments and
-centralized configuration. See `README-dev.md` for the current plan.
+- Database snapshot/seed data is in `hm_database/`.
 
 ## Build, Test, and Development Commands
 
-- `make -C hm_base target=game` builds the shared base library for the gameserver.
+- `make -C hm_base target=game` builds the shared base library.
 - `make -C hm_gameserver` builds the gameserver binary.
 - `make -C hm_lobbyserver` builds the lobbyserver binary.
-- `bash hearthmod/host_ctl_ubuntu.sh start <ip>` starts the stack (legacy flow).
-- `bash hearthmod/host_ctl_ubuntu.sh build` runs the full build, including client/web assets.
+- `bash hearthmod/host_ctl_ubuntu.sh start <ip>` starts the legacy stack.
 
-Current priority is a stable dev environment. Prefer adding a unified `dev` script
-or `docker-compose` workflow over expanding the legacy scripts.
+When adding new workflows, prefer a single entrypoint script (e.g., `./dev`) or
+container orchestration; keep legacy scripts untouched unless required.
 
 ## Coding Style & Naming Conventions
 
-- C code uses 4-space indentation and snake_case for functions and variables.
+- C code uses 4-space indentation and snake_case identifiers.
 - Python uses 4-space indentation; prefer explicit names over abbreviations.
-- Avoid one-letter variable names unless used as simple loop counters.
-- Keep config constants centralized; avoid embedding ports/paths inline.
-- New config values should be documented in `README-dev.md` and `.env.example`.
+- Avoid one-letter variable names except for simple loop counters.
+- Centralize ports and credentials in config or env variables.
 
 ## Testing Guidelines
 
-- There is no dedicated test suite currently.
-- If you introduce tests, keep them close to the component (e.g., `hm_web/tests/`).
-- Prefer simple smoke tests (service port checks, Couchbase connectivity) that
-  validate the dev environment.
+- There is no dedicated test suite today.
+- If you add tests, keep them close to the component (e.g., `hm_web/tests/`).
+- Favor smoke tests that validate service ports and Couchbase connectivity.
 
 ## Commit & Pull Request Guidelines
 
-- Git history is not available in this workspace, so no commit convention is enforced.
-- For new work, use concise imperative messages (e.g., “Add dev config loader”).
-- Pull requests should include a short summary, testing notes, and any config changes.
-- If the change impacts the dev environment, update `README-dev.md` in the same PR.
+- Git history is limited here; use concise imperative commit messages.
+- Pull requests should include a short summary and testing notes.
+- If you touch configuration or workflows, update the README.
 
-## Security & Configuration Tips
+## Modernization Roadmap (Maintainability)
 
-- Couchbase credentials and ports are hard-coded in places; prefer `.env` or config files.
-- `hm_stud` is abandonware; avoid deploying it to production without replacement.
-- When adding config, document defaults and provide an `.env.example`.
+The long-term goal is to replace components one at a time while keeping protocol
+compatibility. Suggested phases:
+
+- Baseline: document current behavior and add logs/health checks.
+- Gateway: add a thin protocol gateway to route traffic to legacy services.
+- Lobby: reimplement lobby features behind the gateway with canary routing.
+- Game: reimplement game loop and compare state snapshots for parity.
+- Data: introduce a new data layer, mirror writes, then flip reads.
+- Decommission: remove unused legacy components once traffic is migrated.

README.md

@@ -0,0 +1,30 @@
+# Hearthmod Modernization Notes
+
+This workspace contains the Hearthmod stack (game server, lobby server, web UI,
+and supporting components). The current goal is to stabilize the development
+environment and improve maintainability without changing client protocol
+compatibility.
+
+## Component-by-Component Replacement Plan
+
+Replacing services incrementally is the safest path. It preserves existing
+behavior while enabling modernization behind compatibility boundaries.
+
+1. **Baseline and observability**: document startup order, ports, and data flows;
+   add basic health checks and structured logs.
+2. **Gateway layer**: introduce a thin gateway that speaks the legacy protocol
+   and routes to existing lobby/game services.
+3. **Lobby replacement**: implement lobby endpoints behind the gateway, canary
+   traffic to validate parity.
+4. **Game server replacement**: implement the game loop and compare deterministic
+   state snapshots with the legacy server before shifting traffic.
+5. **Data layer swap**: add a DAL in new services, mirror writes to a new store,
+   then flip reads after validation.
+6. **Decommission legacy**: remove unused services and dependencies once traffic
+   is fully migrated.
+
+## Maintainability Priorities
+
+- Keep configuration centralized (env or config files).
+- Prefer a single entrypoint script or container orchestration for local dev.
+- Add small smoke tests to validate service health and database connectivity.