docs: add README update design spec

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-15 16:56:58 -07:00
parent f6f177590b
commit 4afab642f7
1 changed files with 145 additions and 0 deletions
--- a/docs/superpowers/specs/2026-03-15-readme-update-design.md
+++ b/docs/superpowers/specs/2026-03-15-readme-update-design.md
@@ -0,0 +1,145 @@
+# README Update Design — 2026-03-15
+
+## Goal
+
+Restructure and expand `README.md` to:
+1. Align with the current codebase (Python 3.10+, uv/mise/pytest/ruff toolchain, 6 new fonts)
+2. Add extensibility-focused content (`Extending` section)
+3. Add developer workflow coverage (`Development` section)
+4. Improve navigability via top-level grouping (Approach C)
+
+---
+
+## Proposed Structure
+
+```
+# MAINLINE
+> tagline + description
+
+## Using
+  ### Run
+  ### Config
+  ### Feeds
+  ### Fonts
+  ### ntfy.sh
+
+## Internals
+  ### How it works
+  ### Architecture
+
+## Extending
+  ### NtfyPoller
+  ### MicMonitor
+  ### Render pipeline
+
+## Development
+  ### Setup
+  ### Tasks
+  ### Testing
+  ### Linting
+
+## Roadmap
+
+---
+*footer*
+```
+
+---
+
+## Section-by-section design
+
+### Using
+
+All existing content preserved verbatim. Two changes:
+- **Run**: add `uv run mainline.py` as an alternative invocation; expand bootstrap note to mention `uv sync` / `uv sync --all-extras`
+- **ntfy.sh**: remove `NtfyPoller` reuse code example (moves to Extending); keep push instructions and topic config
+
+Subsections moved into Using (currently standalone):
+- `Feeds` — it's configuration, not a concept
+- `ntfy.sh` (usage half)
+
+### Internals
+
+All existing content preserved verbatim. One change:
+- **Architecture**: append `tests/` directory listing to the module tree
+
+### Extending
+
+Entirely new section. Three subsections:
+
+**NtfyPoller**
+- Minimal working import + usage example
+- Note: stdlib only dependencies
+
+```python
+from engine.ntfy import NtfyPoller
+
+poller = NtfyPoller("https://ntfy.sh/my_topic/json?since=20s&poll=1")
+poller.start()
+
+# in your render loop:
+msg = poller.get_active_message()  # → (title, body, timestamp) or None
+if msg:
+    title, body, ts = msg
+    render_my_message(title, body)  # visualizer-specific
+```
+
+**MicMonitor**
+- Minimal working import + usage example
+- Note: sounddevice/numpy optional, degrades gracefully
+
+```python
+from engine.mic import MicMonitor
+
+mic = MicMonitor(threshold_db=50)
+if mic.start():                # returns False if sounddevice unavailable
+    excess = mic.excess        # dB above threshold, clamped to 0
+    db = mic.db                # raw RMS dB level
+```
+
+**Render pipeline**
+- Brief prose about `engine.render` as importable pipeline
+- Minimal sketch of serve.py / ESP32 usage pattern
+- Reference to `Mainline Renderer + ntfy Message Queue for ESP32.md`
+
+### Development
+
+Entirely new section. Four subsections:
+
+**Setup**
+- Hard requirements: Python 3.10+, uv
+- `uv sync` / `uv sync --all-extras` / `uv sync --group dev`
+
+**Tasks** (via mise)
+- `mise run test`, `test-cov`, `lint`, `lint-fix`, `format`, `run`, `run-poetry`, `run-firehose`
+
+**Testing**
+- Tests in `tests/` covering config, filter, mic, ntfy, sources, terminal
+- `uv run pytest` and `uv run pytest --cov=engine --cov-report=term-missing`
+
+**Linting**
+- `uv run ruff check` and `uv run ruff format`
+- Note: pre-commit hooks run lint via `hk`
+
+### Roadmap
+
+Existing `## Ideas / Future` content preserved verbatim. Only change: rename heading to `## Roadmap`.
+
+### Footer
+
+Update `Python 3.9+` → `Python 3.10+`.
+
+---
+
+## Files changed
+
+- `README.md` — restructured and expanded as above
+- No other files
+
+---
+
+## What is not changing
+
+- All existing prose, examples, and config table values — preserved verbatim where retained
+- The Ideas/Future content — kept intact under the new Roadmap heading
+- The cyberpunk voice and terse style of the existing README