From 4b6ec297be054b3cbafee5bf62cc4731d6278133 Mon Sep 17 00:00:00 2001
From: Axel Meyer <axel.meyer@durania.net>
Date: Sun, 17 May 2026 01:40:12 +0200
Subject: [PATCH] docs: restructure README to standard module documentation

Reorganized to follow the project's module documentation structure:
Abstract paragraph, Badges as bold key:value list, Topology section
with auto-generated mermaid graph, Controls describing player input,
Demonstrates listing the Sporel features showcased, References at
the end.

Install pre-commit hook via Sporel --install-hooks=.; topology is
auto-managed by Sporel --lint --fix.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .githooks/pre-commit     | 13 ++++++++
 README.md                | 69 ++++++++++++++++++++++++++++++++--------
 scripts/install-hooks.sh |  3 ++
 3 files changed, 71 insertions(+), 14 deletions(-)
 create mode 100644 .githooks/pre-commit
 create mode 100644 scripts/install-hooks.sh

diff --git a/.githooks/pre-commit b/.githooks/pre-commit
new file mode 100644
index 0000000..1ebdad0
--- /dev/null
+++ b/.githooks/pre-commit
@@ -0,0 +1,13 @@
+#!/bin/sh
+# Sporel API-Doc-Convention pre-commit hook.
+SPOREL_EXE="${SPOREL_EXE:-$(command -v Sporel.exe 2>/dev/null || command -v sporel 2>/dev/null)}"
+if [ -z "$SPOREL_EXE" ]; then
+  echo "INFO: Sporel.exe not on PATH. Skipping lint." >&2
+  exit 0
+fi
+"$SPOREL_EXE" --lint="$(pwd)" --fix
+RC=$?
+if git diff --cached --name-only | grep -qx 'README.md'; then
+  git add README.md
+fi
+exit $RC
diff --git a/README.md b/README.md
index 59a1628..e355fa4 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,34 @@
-# rts-prototype — v0.1.0
+# rts-prototype
 
-Pure-RTS Composer-Demo integriert P.3.4-P.3.7 Libs.
+Pure-RTS composer-demo integrating the P.3.4-P.3.7 libs (camera free-pan, input actions, selection, command). 8 units in 3 speed-classes on a 20x20 tile-map; LMB selects, RMB moves.
+
+**Version:** 0.1.0  
+**Module-ID:** rts-prototype  
+**Requires:** lib-core.maps v>=0.1.1, lib-core.render v>=0.1.0, lib-core.camera v>=0.3.0, lib-core.input v>=0.4.0, lib-core.selection v>=0.1.0, lib-core.command v>=0.1.0  
+**Tags:** rts, tech-demo, composition
+
+## Topology
+
+<!-- topology:start (auto-generated; do not edit) -->
+```mermaid
+graph LR
+  this["rts-prototype"]
+  lib_core_maps["lib-core.maps"]
+  this --> lib_core_maps
+  lib_core_render["lib-core.render"]
+  this --> lib_core_render
+  lib_core_camera["lib-core.camera"]
+  this --> lib_core_camera
+  lib_core_input["lib-core.input"]
+  this --> lib_core_input
+  lib_core_selection["lib-core.selection"]
+  this --> lib_core_selection
+  lib_core_command["lib-core.command"]
+  this --> lib_core_command
+  engine["engine.*"]
+  this --> engine
+```
+<!-- topology:end -->
 
 ## Controls
 
@@ -14,19 +42,32 @@ Pure-RTS Composer-Demo integriert P.3.4-P.3.7 Libs.
 - **Middle-Drag**: Pan camera by dragging
 - **ESC**: Return to launcher
 
-## Demo
+## Demonstrates
 
-8 units in 3 speed-classes (rot=100, braun=150, gelb=200 px/s) clustered
-in the left half of a 20×20 map. Move them across the map; speed-variation
-visible. Units walk through wall-clusters (direct-line-move; pathfinding
-deferred to P.4).
+- Pure-composition module: no game-logic libs, just maps + render + camera + input + selection + command wired together.
+- 8 units in 3 speed-classes (red=100, brown=150, yellow=200 px/s) clustered in the left half of a 20x20 map; speed-variation visible on cross-map moves.
+- Direct-line move (no pathfinding — units walk through wall-clusters; pathfinding deferred to P.4).
+- Free-pan camera with all three pan-sources (keys, edge-scroll, middle-drag) simultaneously enabled.
+- `engine.switch_module("lib-sporel.launcher")` on ESC to return to the launcher chooser.
 
-## Deps
+## Interactions
 
-- lib-core.maps, lib-core.render — map + rendering
-- lib-core.camera v0.3.0 — free-pan + screen-to-world
-- lib-core.input v0.3.0 — action bindings
-- lib-core.selection v0.1.0 — click-select + drag-box
-- lib-core.command v0.1.0 — RMB-to-move
+The selection -> command bridge is a one-line target-provider registration. `command` does not know about `selection`; the module wires them together:
 
-See `meta/docs/superpowers/specs/2026-05-14-p3-8-rts-prototype-design.md` for full design.
+```lua
+command.bind_move_action("rmb")
+command.bind_target_provider(function() return selection.list() end)
+```
+
+Camera setup composes all three pan-sources at once, then `camera.update(dt)` sums them per-frame:
+
+```lua
+camera.bind_pan_keys("pan_left", "pan_right", "pan_up", "pan_down")
+camera.bind_pan_drag("pan_drag")
+camera.enable_pan_edge()
+```
+
+## References
+
+- meta/docs/superpowers/specs/2026-05-14-p3-8-rts-prototype-design.md
+- meta/docs/architecture/lib-composition.md
diff --git a/scripts/install-hooks.sh b/scripts/install-hooks.sh
new file mode 100644
index 0000000..2ff6e41
--- /dev/null
+++ b/scripts/install-hooks.sh
@@ -0,0 +1,3 @@
+#!/bin/sh
+git config core.hooksPath .githooks
+echo "Hooks activated."