first commit

AGENTS.md

@@ -0,0 +1,52 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+- `hearthmod/` contains orchestration scripts (`host_ctl_ubuntu.sh`, `docker_ctl.sh`) and legacy Docker setup.
+- 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).
+- 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.
+
+## Build, Test, and Development Commands
+
+- `make -C hm_base target=game` builds the shared base library for the gameserver.
+- `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.
+
+Current priority is a stable dev environment. Prefer adding a unified `dev` script
+or `docker-compose` workflow over expanding the legacy scripts.
+
+## Coding Style & Naming Conventions
+
+- C code uses 4-space indentation and snake_case for functions and variables.
+- 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`.
+
+## 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.
+
+## 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.
+
+## Security & Configuration Tips
+
+- 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`.