From dd30cc2422f4869d80be498da4dad18c89281390 Mon Sep 17 00:00:00 2001
From: Axel Meyer <axel.meyer@durania.net>
Date: Sun, 17 May 2026 01:40:03 +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                | 78 ++++++++++++++++++++++++++++++++++++++--
 scripts/install-hooks.sh |  3 ++
 3 files changed, 91 insertions(+), 3 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 1f26cb2..2566c39 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,77 @@
 # spine-prototype
 
-P.0.module.skeleton end-to-end demo module. Loads `lib-core.maps`,
-holds 6 inline-stubs for libs that get extracted in subsequent slices.
-Self-exits after 60 frames.
+Foundational end-to-end demo module from the bootstrap phase. Loads `lib-core.maps` and demonstrates lib-composition with basic player movement, free-pan camera, click-select, RMB-move, and proximity-triggered interactions. Self-exits after 30 frames for CI.
+
+**Version:** 0.1.0  
+**Module-ID:** spine-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.selection v>=0.1.0, lib-core.input v>=0.4.0, lib-core.player_control v>=0.1.0, lib-core.interaction v>=0.1.0, lib-core.command v>=0.1.0  
+**Tags:** demo, skeleton, foundational, tile-map
+
+## Topology
+
+<!-- topology:start (auto-generated; do not edit) -->
+```mermaid
+graph LR
+  this["spine-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_selection["lib-core.selection"]
+  this --> lib_core_selection
+  lib_core_input["lib-core.input"]
+  this --> lib_core_input
+  lib_core_player_control["lib-core.player_control"]
+  this --> lib_core_player_control
+  lib_core_interaction["lib-core.interaction"]
+  this --> lib_core_interaction
+  lib_core_command["lib-core.command"]
+  this --> lib_core_command
+  engine["engine.*"]
+  this --> engine
+```
+<!-- topology:end -->
+
+## Controls
+
+- **WASD / Arrow-Keys**: Move the player; also pans the camera in free-cam mode.
+- **E**: Interact with the nearest in-range trigger (e.g. proximity sign).
+- **Tab**: Toggle free-cam (decouples camera from player follow).
+- **Mouse-Left**: Click-select / drag-box-select units. Hold Shift to add, Ctrl to toggle.
+- **Mouse-Right**: Issue a move-command to the currently selected units.
+- **Mouse-Middle (drag)**: Pan the camera by dragging.
+- **Escape**: Quit the module.
+
+## Demonstrates
+
+- End-to-end bootstrap of a module: manifest deps -> init -> update -> render -> cleanup.
+- Lib-composition: 8 libs (maps, render, camera, input, selection, command, player_control, interaction) wired together in one module.
+- Tile-based map loading + walkability queries via `lib-core.maps`.
+- Free-pan + follow camera through `lib-core.camera` (`set_target`, `bind_pan_keys`, `update`).
+- Click-select / drag-box / modifier-keys via `lib-core.selection`.
+- RMB-move with target-provider bridge to `lib-core.command` (`bind_target_provider`).
+- Proximity-triggered interactions via `lib-core.interaction.register` + per-frame `interaction.update(px, py)`.
+
+## Interactions
+
+The module wires selection to command via a one-line bridge so RMB issues moves to whatever is currently selected:
+
+```lua
+command.bind_move_action("rmb")
+command.bind_target_provider(function() return selection.list() end)
+```
+
+Each demo-unit registers in both libs so it is selectable AND movable:
+
+```lua
+s.sel_handle = selection.register(function() return aabb(s) end)
+s.cmd_handle = command.register(function() return pos(s) end, ...)
+```
+
+## References
+
+- meta/docs/superpowers/specs/2026-05-09-p0-module-skeleton-design.md
+- meta/docs/architecture/module-lifecycle.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."