docs: update ADR references to /docs

flemming-n-larsen · flemming-n-larsen · commit be68695ae0d3 · 2026-05-12T20:53:30.000+02:00
diff --git a/docs/DEBUGGING-GUIDE.md b/docs/DEBUGGING-GUIDE.md
@@ -233,6 +233,6 @@ Bug reported
 | [`bot-api/tests/TESTING-GUIDE.md`](../bot-api/tests/TESTING-GUIDE.md) | Intent-capture protocol, MockedServer gates, Bot vs BaseBot |
 | [`bot-api/tests/TEST-REGISTRY.md`](../bot-api/tests/TEST-REGISTRY.md) | Acceptance test IDs and cross-platform coverage |
 | [`runner/README.md`](../runner/README.md) | Full Battle Runner API reference |
-| [ADR-0037](architecture/adr/0037-functional-core-bot-api-testability.md) | Functional core extraction for Bot API |
-| [ADR-0038](architecture/adr/0038-shared-cross-platform-test-definitions.md) | Shared test definitions and parity policy |
-| [ADR-0039](architecture/adr/0039-server-testability.md) | Server physics test framework |
+| [ADR-0037](/docs/decisions/0037-functional-core-bot-api-testability.md) | Functional core extraction for Bot API |
+| [ADR-0038](/docs/decisions/0038-shared-cross-platform-test-definitions.md) | Shared test definitions and parity policy |
+| [ADR-0039](/docs/decisions/0039-server-testability.md) | Server physics test framework |
diff --git a/docs/INDEX.md b/docs/INDEX.md
@@ -5,3 +5,4 @@
 | [README.md](./README.md) | Overview and entry point for internal engineering documentation |
 | [DEBUGGING-GUIDE.md](./DEBUGGING-GUIDE.md) | Debugging patterns, timing issues, and diagnostics reference |
 | [architecture/](./architecture/) | ADRs, C4 views, domain models, and business flows |
+| [decisions/](./decisions/) | Architecture Decision Records (ADRs) — canonical list with statuses and dates |
diff --git a/docs/architecture/INDEX.md b/docs/architecture/INDEX.md
@@ -3,6 +3,6 @@
 | File / Directory | Type | Purpose |
 |-----------------|------|---------|
 | [README.md](./README.md) | Entry point | Navigation hub — ADRs, C4 views, message schemas, business flows |
-| [adr/](./adr/) | Directory | Architecture Decision Records (Why) |
+| [decisions/](../decisions/) | Directory | Architecture Decision Records (Why) |
 | [c4-views/](./c4-views/) | Directory | C4 diagrams — System Context, Container, Component views (What/Visual) |
 | [models/](./models/) | Directory | Message schemas and business flows (What/Detailed + How) |
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
@@ -7,16 +7,16 @@ Comprehensive architecture documentation for Robocode Tank Royale following the
 ## 🎯 Quick Navigation
 
 ### **Architecture Decision Records (ADRs)** — The "Why"
-**[👉 adr/](./adr/)**
+**[👉 Decisions](/docs/decisions/README.md)**
 
-Why key architectural decisions were made. See **[adr/README.md](./adr/README.md)** for the full index with statuses and dates.
+Why key architectural decisions were made. See **[Decisions](/docs/decisions/README.md)** for the full index with statuses and dates.
 
 **Use When:** Understanding design rationale, trade-offs, alternatives
 
 ---
 
 ### **C4 Architecture Diagrams** — The "What" (Visual)
-**[👉 c4-views/](./c4-views/)**
+**[👉 C4-views/](./c4-views/)**
 
 Hierarchical system visualization at multiple zoom levels:
 - ✅ [**System Context**](./c4-views/system-context.md) — High-level 10,000-foot view
@@ -63,7 +63,7 @@ How entities interact through processes:
 
 ### ADRs (Architecture Decision Records)
 
-See **[adr/README.md](./adr/README.md)** for the full canonical ADR index with dates and statuses.
+See **[Decisions](/docs/decisions/README.md)** for the full canonical ADR index with dates and statuses.
 
 ### Message Schema
 | Category | Coverage | Status |
@@ -113,12 +113,12 @@ See **[adr/README.md](./adr/README.md)** for the full canonical ADR index with d
 
 ### For **Server Developers**
 1. All message schemas ([Handshakes](./models/message-schema/handshakes.md), [Commands](./models/message-schema/commands.md), [Events](./models/message-schema/events.md), [Intents](./models/message-schema/intents.md), [State](./models/message-schema/state.md))
-2. [ADR-0011: Game Loop](./adr/0011-realtime-game-loop-architecture.md) — Timing & determinism
+2. [ADR-0011: Game Loop](/docs/decisions/0011-realtime-game-loop-architecture.md) — Timing & determinism
 3. [Turn Execution Flow](./models/flows/turn-execution.md) — 15-step sequence
 4. [Battle Lifecycle Flow](./models/flows/battle-lifecycle.md) — State machine
 
 ### For **System Designers**
-1. [ADR index](./adr/) — All architectural decisions and their rationale
+1. [Decisions](/docs/decisions/README.md) — All architectural decisions and their rationale
 2. System Context and Container diagrams
 3. All message schemas and state objects
 4. Flow state machines
@@ -165,7 +165,7 @@ Business Flows:           4
 | Question | Answer |
 |----------|--------|
 | **New to Tank Royale?** | Start with [System Context](./c4-views/system-context.md) |
-| **Why this architecture?** | Check the [ADRs](./adr/) |
+| **Why this architecture?** | Check the [Decisions](/docs/decisions/README.md) |
 | **What messages are exchanged?** | Browse [Message Schema](./models/message-schema/) |
 | **How do processes work?** | See [Business Flows](./models/flows/) |
 | **Building bot code?** | Reference [Handshakes](./models/message-schema/handshakes.md) + [Events](./models/message-schema/events.md) + [Intents](./models/message-schema/intents.md) |
diff --git a/docs/architecture/c4-views/README.md b/docs/architecture/c4-views/README.md
@@ -31,10 +31,10 @@ Think of it like Google Maps: zoom out to see the country, zoom in to see street
 
 ## Related Documentation
 
-- **[ADRs](../adr/)** — Why architectural decisions were made
-- **[Message Schema](../models/message-schema/)** — WebSocket message contracts
-- **[Business Flows](../models/flows/)** — Process documentation
-- **[OpenSpec](../../../openspec/)** — Detailed specifications
+- **[ADRs](/docs/decisions/README.md)** — Why architectural decisions were made
+- **[Message Schema](../models/message-schema/README.md)** — WebSocket message contracts
+- **[Business Flows](../models/flows/README.md)** — Process documentation
+- **[OpenSpec](/openspec/project.md)** — Detailed specifications
 
 ---
 
diff --git a/docs/architecture/c4-views/system-context.md b/docs/architecture/c4-views/system-context.md
@@ -226,9 +226,9 @@ This design choice ensures:
 
 ## Related Documentation
 
-- **[ADR-0009: WebSocket Protocol](../adr/0009-websocket-communication-protocol.md)** — Why WebSocket was chosen
-- **[ADR-0003: Cross-Platform Bot APIs](../adr/0003-cross-platform-bot-api-strategy.md)** — Multi-language support strategy
-- **[ADR-0011: Real-Time Game Loop](../adr/0011-realtime-game-loop-architecture.md)** — Real-time 30 TPS tick system
+- **[ADR-0009: WebSocket Protocol](/docs/decisions/0009-websocket-communication-protocol.md)** — Why WebSocket was chosen
+- **[ADR-0003: Cross-Platform Bot APIs](/docs/decisions/0003-cross-platform-bot-api-strategy.md)** — Multi-language support strategy
+- **[ADR-0011: Real-Time Game Loop](/docs/decisions/0011-realtime-game-loop-architecture.md)** — Real-time 30 TPS tick system
 - **[Battle Lifecycle Flow](../models/flows/battle-lifecycle.md)** — How battles progress
 - **[Bot Connection Flow](../models/flows/bot-connection.md)** — Bot connection sequence
 
diff --git a/docs/architecture/models/flows/README.md b/docs/architecture/models/flows/README.md
@@ -131,10 +131,10 @@ These flow diagrams are the **single canonical source** for all protocol sequenc
 
 ## Related Documentation
 
-- **[Message Schema](../message-schema/)** — WebSocket message contracts
-- **[Schema YAML Definitions](/schema/schemas/)** — Actual message format definitions
-- **[ADRs](../../adr/)** — Design decisions about flow architecture
-- **[C4 Views](../../c4-views/)** — Component interactions
+- **[Message Schema](../message-schema/README.md)** — WebSocket message contracts
+- **[Schema YAML Definitions](/schema/schemas/README.md)** — Actual message format definitions
+- **[ADRs](../../../decisions/README.md)** — Design decisions about flow architecture
+- **[C4 Views](../../c4-views/README.md)** — Component interactions
 
 ---
 
diff --git a/docs/architecture/models/flows/battle-lifecycle.md b/docs/architecture/models/flows/battle-lifecycle.md
@@ -626,9 +626,9 @@ gantt
 - **[Message Schema](../message-schema/README.md)** — WebSocket message contracts
 - **[Events](../message-schema/events.md)** — Event message definitions
 - **[Commands](../message-schema/commands.md)** — Controller command definitions
-- **[ADR-0011: Real-Time Game Loop Architecture](../../adr/0011-realtime-game-loop-architecture.md)** — Design rationale
-- **[ADR-0033: Server Debug Mode](../../adr/0033-bot-debug-mode.md)** — Turn-by-turn stepping
-- **[ADR-0034: Breakpoint Mode](../../adr/0034-breakpoint-mode.md)** — Per-bot breakpoint pause
+- **[ADR-0011: Real-Time Game Loop Architecture](/docs/decisions/0011-realtime-game-loop-architecture.md)** — Design rationale
+- **[ADR-0033: Server Debug Mode](/docs/decisions/0033-bot-debug-mode.md)** — Turn-by-turn stepping
+- **[ADR-0034: Breakpoint Mode](/docs/decisions/0034-breakpoint-mode.md)** — Per-bot breakpoint pause
 
 ---
 
diff --git a/docs/architecture/models/flows/bot-connection.md b/docs/architecture/models/flows/bot-connection.md
@@ -567,9 +567,9 @@ netstat -an | grep 7654
 - **[Turn Execution Flow](./turn-execution.md)** — What happens after game starts
 - **[Handshakes](../message-schema/handshakes.md)** — Handshake message schemas
 - **[Events](../message-schema/events.md)** — Event message schemas
-- **[ADR-0009: WebSocket Protocol](../../adr/0009-websocket-communication-protocol.md)** — Protocol design
-- **[ADR-0003: Cross-Platform Bot APIs](../../adr/0003-cross-platform-bot-api-strategy.md)** — API design
-- **[ADR-0035: Bot Debugger Detection](../../adr/0035-bot-debugger-detection.md)** — `debuggerAttached` field
+- **[ADR-0009: WebSocket Protocol](/docs/decisions/0009-websocket-communication-protocol.md)** — Protocol design
+- **[ADR-0003: Cross-Platform Bot APIs](/docs/decisions/0003-cross-platform-bot-api-strategy.md)** — API design
+- **[ADR-0035: Bot Debugger Detection](/docs/decisions/0035-bot-debugger-detection.md)** — `debuggerAttached` field
 
 ---
 
diff --git a/docs/architecture/models/flows/event-handling.md b/docs/architecture/models/flows/event-handling.md
@@ -653,8 +653,8 @@ Both calls must happen in sequence for handler output to appear in the GUI.
 - **[Battle Lifecycle Flow](./battle-lifecycle.md)** — When round ends and events fire
 - **[Bot Connection Flow](./bot-connection.md)** — Event handler setup during initialization
 - **[Message Schema: Events](../message-schema/events.md)** — Event message contracts
-- **[ADR-0011: Realtime Game Loop](../../adr/0011-realtime-game-loop-architecture.md)** — Design decisions about event timing
-- **[ADR-0012: Turn Timing Semantics](../../adr/0012-turn-timing-semantics.md)** — Exact timing semantics
+- **[ADR-0011: Realtime Game Loop](/docs/decisions/0011-realtime-game-loop-architecture.md)** — Design decisions about event timing
+- **[ADR-0012: Turn Timing Semantics](/docs/decisions/0012-turn-timing-semantics.md)** — Exact timing semantics
 
 ---
 
diff --git a/docs/architecture/models/flows/turn-execution.md b/docs/architecture/models/flows/turn-execution.md
@@ -746,10 +746,10 @@ for (Bot other : nearby) {
 - **[State Objects](../message-schema/state.md)** — Bot state and bullet state schemas
 - **[Events](../message-schema/events.md)** — Tick events and bot gameplay events
 - **[Intents](../message-schema/intents.md)** — Bot intent message schema
-- **[ADR-0011: Game Loop](../../adr/0011-realtime-game-loop-architecture.md)** — Design rationale
-- **[ADR-0033: Server Debug Mode](../../adr/0033-bot-debug-mode.md)** — Turn-by-turn stepping
-- **[ADR-0034: Breakpoint Mode](../../adr/0034-breakpoint-mode.md)** — Per-bot breakpoint pause
-- **[Schema YAML Definitions](/schema/schemas/)** — Raw YAML message format specifications
+- **[ADR-0011: Game Loop](/docs/decisions/0011-realtime-game-loop-architecture.md)** — Design rationale
+- **[ADR-0033: Server Debug Mode](/docs/decisions/0033-bot-debug-mode.md)** — Turn-by-turn stepping
+- **[ADR-0034: Breakpoint Mode](/docs/decisions/0034-breakpoint-mode.md)** — Per-bot breakpoint pause
+- **[Schema YAML Definitions](/schema/schemas/README.md)** — Raw YAML message format specifications
 
 ---
 
diff --git a/docs/architecture/models/message-schema/README.md b/docs/architecture/models/message-schema/README.md
@@ -17,7 +17,7 @@ Message schemas answer: **"What messages are exchanged over the network?"**
 
 ## Schema Categories
 
-All schemas are defined in [`/schema/schemas/`](../../../../schema/schemas/) as YAML files using JSON Schema Draft 2020-12.
+All schemas are defined in [`/schema/schemas/`](/schema/schemas/README.md) as YAML files using JSON Schema Draft 2020-12.
 
 ```mermaid
 graph TD
@@ -339,7 +339,7 @@ Use schemas to generate test fixtures and validate responses.
 - **[State Objects](./state.md)** — Data transfer objects
 - **[Battle Lifecycle Flow](../flows/battle-lifecycle.md)** — How messages flow through battle
 - **[Turn Execution Flow](../flows/turn-execution.md)** — Per-turn message sequence
-- **[Schema Source](../../../../schema/schemas/)** — YAML schema definitions
+- **[Schema Source](/schema/schemas/README.md)** — YAML schema definitions
 
 ---
 
diff --git a/docs/architecture/models/message-schema/commands.md b/docs/architecture/models/message-schema/commands.md
@@ -443,7 +443,7 @@ classDiagram
 
 **Direction:** Controller → Server
 
-**Purpose:** Enable server debug mode, allowing step-through execution and breakpoints (see [ADR-0033](../../adr/0033-bot-debug-mode.md))
+**Purpose:** Enable server debug mode, allowing step-through execution and breakpoints (see [ADR-0033](/docs/decisions/0033-bot-debug-mode.md))
 
 ### Structure
 
@@ -481,7 +481,7 @@ classDiagram
 
 **Direction:** Controller → Server
 
-**Purpose:** Disable server debug mode and return to normal real-time execution (see [ADR-0033](../../adr/0033-bot-debug-mode.md))
+**Purpose:** Disable server debug mode and return to normal real-time execution (see [ADR-0033](/docs/decisions/0033-bot-debug-mode.md))
 
 ### Structure
 
@@ -519,7 +519,7 @@ classDiagram
 
 **Direction:** Controller → Server
 
-**Purpose:** Update the policy for a specific bot — used for breakpoint mode and debug graphics visibility (see [ADR-0034](../../adr/0034-breakpoint-mode.md))
+**Purpose:** Update the policy for a specific bot — used for breakpoint mode and debug graphics visibility (see [ADR-0034](/docs/decisions/0034-breakpoint-mode.md))
 
 ### Example
 
@@ -703,17 +703,17 @@ Server ignores message (no response)
 
 ## Related Schemas
 
-- [start-game.schema.yaml](../../../../schema/schemas/start-game.schema.yaml)
-- [stop-game.schema.yaml](../../../../schema/schemas/stop-game.schema.yaml)
-- [pause-game.schema.yaml](../../../../schema/schemas/pause-game.schema.yaml)
-- [resume-game.schema.yaml](../../../../schema/schemas/resume-game.schema.yaml)
-- [next-turn.schema.yaml](../../../../schema/schemas/next-turn.schema.yaml)
-- [change-tps.schema.yaml](../../../../schema/schemas/change-tps.schema.yaml)
-- [enable-debug-mode.schema.yaml](../../../../schema/schemas/enable-debug-mode.schema.yaml)
-- [disable-debug-mode.schema.yaml](../../../../schema/schemas/disable-debug-mode.schema.yaml)
-- [bot-policy-update.schema.yaml](../../../../schema/schemas/bot-policy-update.schema.yaml)
-- [game-setup.schema.yaml](../../../../schema/schemas/game-setup.schema.yaml)
-- [bot-address.schema.yaml](../../../../schema/schemas/bot-address.schema.yaml)
+- [start-game.schema.yaml](/schema/schemas/start-game.schema.yaml)
+- [stop-game.schema.yaml](/schema/schemas/stop-game.schema.yaml)
+- [pause-game.schema.yaml](/schema/schemas/pause-game.schema.yaml)
+- [resume-game.schema.yaml](/schema/schemas/resume-game.schema.yaml)
+- [next-turn.schema.yaml](/schema/schemas/next-turn.schema.yaml)
+- [change-tps.schema.yaml](/schema/schemas/change-tps.schema.yaml)
+- [enable-debug-mode.schema.yaml](/schema/schemas/enable-debug-mode.schema.yaml)
+- [disable-debug-mode.schema.yaml](/schema/schemas/disable-debug-mode.schema.yaml)
+- [bot-policy-update.schema.yaml](/schema/schemas/bot-policy-update.schema.yaml)
+- [game-setup.schema.yaml](/schema/schemas/game-setup.schema.yaml)
+- [bot-address.schema.yaml](/schema/schemas/bot-address.schema.yaml)
 
 ---
 
@@ -723,8 +723,8 @@ Server ignores message (no response)
 - [Handshakes](./handshakes.md)
 - [Events](./events.md)
 - [Battle Lifecycle Flow](../flows/battle-lifecycle.md)
-- [ADR-0033: Server Debug Mode](../../adr/0033-bot-debug-mode.md)
-- [ADR-0034: Breakpoint Mode](../../adr/0034-breakpoint-mode.md)
+- [ADR-0033: Server Debug Mode](/docs/decisions/0033-bot-debug-mode.md)
+- [ADR-0034: Breakpoint Mode](/docs/decisions/0034-breakpoint-mode.md)
 
 ---
 
diff --git a/docs/architecture/models/message-schema/state.md b/docs/architecture/models/message-schema/state.md
@@ -642,7 +642,7 @@ classDiagram
 - Observers can also infer the participant type from `id` when `isTeam` is absent:
   - `id > 0` = real team
   - `id < 0` = solo bot (negated bot ID)
-  - See [ADR-0015: Participant ID as Unified Team Identifier](../../adr/0015-bot-id-team-id-namespace-separation.md) for rationale.
+  - See [ADR-0015: Participant ID as Unified Team Identifier](/docs/decisions/0015-bot-id-team-id-namespace-separation.md) for rationale.
 
 ### Example (Mixed teams and solo bots)
 
