# AGENTS (Repository Guidance)

## Repository Intent
- The `web/desktop` and `web/mobile` folders host the live HUD demo (Desktop and mobile). Keep everything that should be served from a webserver inside those folders.
- `docs/game_rulebook.md` is the **Single Source of Truth (SSOT)** for Galaxy Forge’s game logic, builder system, resources, and requirements. Any UI work, game behavior, or rules must align with — not contradict — that document unless a new decision is logged.
- `docs/` stores documentation while `planning/` holds sketches/notes that are not meant for deployment.

## Key Instructions for Agents
1. **Reference SSOT first.** When implementing features or answering questions related to game balance, resources, blueprints, buildings, or world generation, open `docs/game_rulebook.md` and confirm compliance. Note any missing detail needs a Decision Log entry (see section 13).
2. **Respect folder intent.** Changes to web assets go in `web/desktop` or `web/mobile` only. Use `planning/` for drafts and `docs/` for textual explanations.
3. **Document assumptions.** If you must deviate from `docs/game_rulebook.md`, append an entry to the Decision Log (section 13) explaining the why/when.
4. **Keep mobile/desktop aligned.** When adjusting UI/partials, mirror updates in both `web/desktop` and `web/mobile` unless the change is explicitly mobile-only or desktop-only and documented.

## When touching docs
- Expand `docs/game_rulebook.md` if you update core rules, flow, or systems described there. Keep numbering/sections intact; append entries in the Decision Log (section 13) with dates.
- The root `README.md` should mention where to find the SSOT and purpose of each folder.

## Decision Log Reminder
- Section 13 of `docs/game_rulebook.md` is the Decision Log. Add a dated entry whenever:
  - You introduce a new rule variant or exception.
  - The implementation deviates from the documented defaults.