docs(workspace): scaffold docs/ tree with ADRs and documentation map

AGENTS.md

@@ -8,6 +8,16 @@ Voxel-based game with souls-like combat. Built in Rust; rendering targets Vulkan
 
 World is procedurally generated. Voxel edge length is half of Minecraft's (0.5 m), so the player occupies **3 blocks tall × 2 blocks wide**. This finer grid is load-bearing for design decisions: collision, mesh chunking, LOD thresholds, and network bandwidth all need to assume ~8× the voxel count of a Minecraft-scale world per unit volume — pick chunk sizes and data layouts accordingly. Supports both single-player and multiplayer via a dedicated server — that dual mode is why `server` exists as its own crate even for solo play (the single-player path is expected to run the server logic in-process or invoke the same crate, rather than having a separate offline code path).
 
+## Documentation map
+
+Documentation is layered by altitude; keep content at the layer it belongs to so no single file accretes everything.
+
+- **This file (`AGENTS.md`)** — cross-cutting engineering conventions and architecture invariants: rules that apply regardless of which feature is being touched. There is a finite set of these, so this file should grow slowly. Subsystem-specific specs do **not** belong here.
+- **[`docs/`](docs/) + Rust module docs (`//!`, `///`)** — per-subsystem technical implementation docs. How an individual system (meshing, networking, worldgen, …) is built. Prefer module docs next to the code; promote to a `docs/<subsystem>.md` note when the design spans multiple files.
+- **[`docs/adr/`](docs/adr/)** — Architecture Decision Records: the *why* behind significant, hard-to-reverse choices, one append-only file per decision. See [`docs/README.md`](docs/README.md) for the full scheme and [`docs/adr/0001-record-architecture-decisions.md`](docs/adr/0001-record-architecture-decisions.md) for the practice.
+
+The canonical game-*design* specification (intent, world rules, gameplay behaviour) is maintained separately and is not part of this repository; this repo documents how that design is implemented.
+
 ## Workspace layout
 
 Cargo workspace (resolver = "3", edition 2024) with four crates under `crates/`:

docs/README.md

@@ -0,0 +1,36 @@
+# Documentation
+
+Technical, implementation-facing documentation for the Synvael engine. This directory is the **code-side** counterpart to the game-design specification; it describes how subsystems are built, not what the game should feel like.
+
+## How documentation is layered
+
+Documentation lives at three altitudes. Each layer answers a different question, and content is kept at the layer it belongs to so that no single file accretes everything.
+
+| Layer | Location | Answers | Churn |
+|-------|----------|---------|-------|
+| **Project conventions** | [`AGENTS.md`](../AGENTS.md) | "What rules apply no matter which feature I touch?" | Slow — a finite set of cross-cutting invariants |
+| **Subsystem technical docs** | this `docs/` tree + Rust module docs (`//!`, `///`) | "How does *this* subsystem work?" | Grows with features, distributed across files |
+| **Architecture decisions** | [`docs/adr/`](adr/) | "*Why* was this chosen over the alternatives?" | Append-only, one file per decision |
+
+The rule that keeps `AGENTS.md` lean: if a piece of documentation is specific to one subsystem, it does **not** go in `AGENTS.md`. It goes in that subsystem's module docs or a `docs/<subsystem>.md` note, and `AGENTS.md` only links to it. `AGENTS.md` is an index and a rulebook, not a container for feature specs.
+
+### Where to put a new piece of documentation
+
+- A rule true across the whole project (a convention, an invariant) → `AGENTS.md`.
+- How one subsystem is implemented → prefer Rust **module docs** next to the code (`//!` at the top of the module). They cannot drift far from the code and render with `cargo doc`.
+- Cross-file technical design too large for a doc comment (e.g. the rendering frame graph, the network protocol, the worldgen pipeline) → a `docs/<subsystem>.md` note.
+- The reasoning behind a specific, hard-to-reverse choice → an **ADR** in [`docs/adr/`](adr/).
+
+## Relationship to the design specification
+
+The canonical **design** specification — intent, world rules, gameplay-system behaviour, and unresolved questions — is maintained separately and is **not** part of this repository. This `docs/` tree records how the engine *implements* those designs.
+
+Each subsystem note should name the design topic it implements (by title, e.g. "Design source: *Worldgen*"), so the trail from intent to implementation exists without coupling the repository to an external location. When the implementation and the design disagree, surface the disagreement rather than silently resolving it in code.
+
+## Index
+
+- [`adr/`](adr/) — Architecture Decision Records.
+  - [`adr/0001-record-architecture-decisions.md`](adr/0001-record-architecture-decisions.md) — establishes the ADR practice.
+  - [`adr/template.md`](adr/template.md) — template for new decisions.
+
+Subsystem notes are added here as systems are implemented and locked.

docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,26 @@
+# 0001. Record architecture decisions
+
+- **Status:** Accepted
+- **Date:** 2026-06-27
+
+## Context
+
+The engine makes a number of architectural choices that are hard to reverse and non-obvious from the code alone: the crate boundaries, the determinism stance for worldgen, the server-authoritative simulation model, the content-ID namespacing scheme, and similar. The reasoning behind such choices is valuable to future contributors but does not belong inline in the source, where it would either be lost or bloat a single guidance file.
+
+A durable, low-ceremony place is required to record *why* significant choices were made, kept separate from the cross-cutting rules in `AGENTS.md` (which records *what* to follow) and from subsystem implementation docs (which record *how* a system works).
+
+## Decision
+
+Architecture Decision Records (ADRs), in the lightweight format popularised by Michael Nygard, are used to capture significant, hard-to-reverse decisions.
+
+- Each ADR is a single Markdown file in `docs/adr/`, numbered sequentially (`0001-…`, `0002-…`).
+- Each record carries a status (`Proposed`, `Accepted`, `Deprecated`, or `Superseded by …`) and a date.
+- Records are **append-only**: once accepted, an ADR is not edited to reflect a later change of mind. A new ADR is written instead and the old one is marked `Superseded`.
+- New records are started from [`template.md`](template.md).
+
+## Consequences
+
+- The rationale behind significant choices is preserved with its historical context, independent of how the code later evolves.
+- `AGENTS.md` stays lean: it can state a rule and link to the ADR that explains it, rather than carrying the justification inline.
+- A small, ongoing discipline is required — a contributor making a significant architectural choice is expected to add an ADR for it. Trivial or easily reversible choices do not warrant one.
+- Because records are numbered and append-only, the directory grows monotonically without any single file becoming a bottleneck.

docs/adr/template.md

@@ -0,0 +1,16 @@
+# NNNN. <short decision title>
+
+- **Status:** Proposed | Accepted | Deprecated | Superseded by [ADR-XXXX](XXXX-...)
+- **Date:** YYYY-MM-DD
+
+## Context
+
+The forces at play: the technical situation, the constraints, and the problem that requires a decision. State the facts neutrally. What makes this choice non-obvious or hard to reverse later?
+
+## Decision
+
+The choice that was made, stated in the active, present tense ("The engine uses …", "Worldgen seeds from …"). One decision per record.
+
+## Consequences
+
+What becomes easier and what becomes harder as a result. Include the trade-offs accepted, the follow-on work implied, and anything a future contributor must keep true for the decision to remain valid.