diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..f42ac75
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,24 @@
+# Repository notes
+
+Console Minesweeper on .NET 10 (`Minesweeper.slnx`).
+
+## Layout
+- `src/Minesweeper.Core` — game rules only. No `System.Console`, no rendering. Keep it that way.
+- `src/Minesweeper.Cli` — parsing, ANSI rendering, game loop. All console I/O lives here.
+- `tests/Minesweeper.Core.Tests` — xUnit. References both projects, so CLI types are tested directly.
+
+## Conventions
+- Coordinates are **0-based** everywhere except player input. `CommandParser` is the only place that
+  converts 1-based input; `BoardRenderer` is the only place that formats back to 1-based.
+- Columns are lettered (`A`..`Z`, then `AA`..) so typed input can never be ambiguous with a row.
+- Colour is applied **after** padding in `BoardRenderer`: escape codes inflate string length and would
+  misalign the grid. `AnsiPalette.Number(count, paddedGlyph)` exists for that reason.
+- Cells render as fixed 3-character slots, and the cursor uses `[x]` so it stays visible without colour.
+- Use `MinesweeperGame.FromMines(size, mines)` for tests that need an exact layout; it skips random
+  placement and the first-click safety rule. A flood that opens every safe cell wins immediately and
+  auto-flags the mines, so pick layouts that leave cells hidden when a test needs play to continue.
+
+## Commands
+- `dotnet build`
+- `dotnet test`
+- `dotnet run --project src/Minesweeper.Cli -- --help`