docs: add AGENTS.md

.gitignore

@@ -37,3 +37,6 @@ htmlcov/
 
 # debug resources
 debug/
+
+# Node dependencies for browser automation tooling
+node_modules/

AGENTS.md

@@ -0,0 +1,32 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+Core poker service code lives in `texas_holdem/`. Important modules include `engine.py` for Texas Hold'em rules, `service.py` for game management, `server.py` for the HTTP API, `agents.py` for local/HTTP agents, and `ai_client.py` / `human_client.py` for standalone agents. Prompt templates live in `texas_holdem/prompts/`.
+
+Replay UI code lives in `texas_holdem_replay/`, with static browser assets under `texas_holdem_replay/static/`. Tests are in `tests/`, named by feature area such as `test_engine.py`, `test_service.py`, and `test_replay_server.py`. Design notes belong in `docs/`.
+
+## Build, Test, and Development Commands
+
+- `python -m unittest discover -v` runs the full test suite.
+- `python -m compileall texas_holdem texas_holdem_replay tests` checks import and syntax validity.
+- `python -m texas_holdem.server --host 127.0.0.1 --port 8000` starts the game service.
+- `python -m texas_holdem.human_client --port 9001 --keep-history` starts an interactive human HTTP agent.
+- `python -m texas_holdem.ai_client --port 9101 --api-key "$OPENAI_API_KEY" --model gpt-4o-mini` starts an OpenAI-compatible AI agent.
+- `python -m texas_holdem_replay.server --port 8088` starts the replay viewer.
+
+## Coding Style & Naming Conventions
+
+Use Python 3.11+ standard-library APIs unless a dependency is intentionally added to `pyproject.toml`. Keep modules focused and prefer explicit dataclasses for wire/state models. Use 4-space indentation, type hints, `snake_case` for functions and variables, `PascalCase` for classes, and concise comments only where logic is non-obvious.
+
+## Testing Guidelines
+
+Use `unittest`. Add tests near the behavior changed: engine rules in `tests/test_engine.py`, HTTP/service behavior in `tests/test_service.py`, agent transport in `tests/test_agents.py`, and replay UI server helpers in `tests/test_replay_server.py`. New bug fixes should include a regression test. Avoid tests that require external network access or real LLM calls.
+
+## Commit & Pull Request Guidelines
+
+History uses short Conventional Commit-style subjects, for example `feat: add replay server and web client` and `fix: game service api block when a game is running`. Keep commits scoped to one behavior change. Pull requests should include a short summary, test commands run, linked issue or motivation, and screenshots only for replay UI or visible terminal-output changes.
+
+## Security & Configuration Tips
+
+Do not commit API keys. Pass LLM credentials through `OPENAI_API_KEY` or CLI flags in local shells only. HTTP Agent endpoints are exclusive per active game; preserve this invariant when changing service concurrency.