Mainline/docs/superpowers/specs/2026-03-15-readme-update-design.md

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

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

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