# 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