From 03027b077aaec68118b7ee50603502681499e2e4 Mon Sep 17 00:00:00 2001
From: Calic <axel.meyer@durania.net>
Date: Sun, 17 May 2026 01:39:53 +0200
Subject: [PATCH] docs: add standard module documentation

Initial README following 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                | 41 ++++++++++++++++++++++++++++++++++++++++
 scripts/install-hooks.sh |  3 +++
 3 files changed, 57 insertions(+)
 create mode 100644 .githooks/pre-commit
 create mode 100644 README.md
 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
new file mode 100644
index 0000000..105ac57
--- /dev/null
+++ b/README.md
@@ -0,0 +1,41 @@
+# lib-sporel.launcher
+
+Module-discovery and module-switch entry. Lists available modules from the configured modules-dir and launches the selected one via `engine.switch_module`. Typical entry point: `--module=lib-sporel.launcher` boots into a chooser screen rather than directly into a game.
+
+**Version:** 0.1.0  
+**Module-ID:** lib-sporel.launcher  
+**Requires:** lib-core.input v>=0.4.0  
+**Tags:** launcher, menu, system, navigation
+
+## Topology
+
+<!-- topology:start (auto-generated; do not edit) -->
+```mermaid
+graph LR
+  this["lib-sporel.launcher"]
+  lib_core_input["lib-core.input"]
+  this --> lib_core_input
+  engine["engine.*"]
+  this --> engine
+```
+<!-- topology:end -->
+
+## Controls
+
+- **Mouse-Left**: Click a module-button to launch it; click confirm/cancel in the quit-modal.
+- **Enter**: Confirm quit when the modal is open.
+- **Escape**: Open the quit-modal from the chooser; cancel the modal when open.
+
+## Demonstrates
+
+- `engine.module.list` discovery of installed modules from the modules-dir.
+- `engine.switch_module` runtime swap from the launcher to the selected module.
+- Simple text + rect rendering via `engine.render` for the chooser UI.
+- Input-action binding through `lib-core.input` (`ui_click`, `ui_back`, `ui_confirm`).
+- Modal-state FSM (chooser <-> quit-modal) factored into a sibling `fsm.lua` loaded via `engine.module.dir_of`.
+
+## References
+
+- meta/docs/architecture/module-lifecycle.md
+- meta/docs/architecture/host-app.md
+- meta/docs/superpowers/specs/2026-05-14-launcher-design.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."