> **Draft** — auto-generated by roll-doc on 2026-05-28. Review before treating as authoritative.

# lib/ — Python helpers and i18n runtime

Python scripts and shell libraries that `bin/roll` delegates to for rendering-heavy or data-processing tasks.

## Key files

| File | Purpose |
|------|---------|
| `roll-loop-status.py` | Renders the `roll loop status` health dashboard — reads cycle event NDJSON, computes per-cycle rows, daily rollups, and phase-tracing breakdown |
| `roll-loop-story.py` | Per-story rollup: aggregates cycles, tokens, cost, and PR outcomes for `roll loop story <ID>` |
| `roll-status.py` | Renders the `roll status` one-screen sync health view |
| `roll-init.py` | Init-flow helpers called by `roll init` |
| `roll-setup.py` | Setup-flow helpers (convention sync, tool config write) |
| `roll-brief.py` | Brief generation: reads cycle records and produces the feature brief |
| `roll-backlog.py` | Backlog read/write helpers |
| `roll-peer.py` | Peer review coordination helpers |
| `roll-help.py` | Renders `roll --help` output |
| `roll-plan-validate.py` | Validates `.roll/onboard-plan.yaml` and paired `.roll/init-diagnosis.yaml` before `roll init --apply` mutates a project |
| `model_prices.py` | List-price table for AI model API pricing (per MTok, native currency) |
| `prices_fetcher.py` | Fetches fresh price snapshots from vendor APIs |
| `roll_render.py` | Shared rendering utilities (tables, color, formatting) |
| `loop-fmt.py` | Loop log formatter (ANSI-strip, timestamp alignment) |
| `loop_unstick.py` | Diagnostic: detects and unsticks hung loop state |
| `backfill-pi-usage.py` | Backfills pi/deepseek token and cost data into existing cycle records |
| `i18n.sh` | Shell wrapper that delegates i18n string lookups to `lib/i18n/` |
| `slides-render.py` | Renders `.deck.md` → HTML slides |
| `slides-validate.py` | Validates deck file syntax and asset references |

## Sub-directories

- `agent_usage/` — token-usage capture and cost attribution per agent invocation
- `i18n/` — localized string tables for all CLI output (EN + ZH)
- `prices/` — price snapshot JSON files (per-vendor, dated)
- `slides/` — slide component library for `roll deck`

## Dependencies

Imported by `bin/roll` via subprocess calls (`python3 lib/<script>.py`).
Most helpers are standard-library only; YAML-facing helpers such as `roll-plan-validate.py` and `roll-onboard-render.py` require PyYAML.