engmung · Oct 14, 2026 · Oct 14, 2026 · Oct 14, 2026 · Oct 14, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
@@ -19,7 +19,8 @@ the `[Unreleased]` section of `CHANGELOG.md` written:
 python firmware/toolchain/release.py cut v3.9.4 --audio v0.5.4 --performance v0.2.4
 ```
 
-bumps the versions, dates the changelog section, updates `AGENTS.md`, runs
+bumps the versions, dates the changelog section and files it in
+`docs/releases/`, updates `AGENTS.md`, runs
 `shelf.sh` for the core and each named edition, points the flasher manifest
 and the `/editions` cards at the new images, runs the web checks, commits
 `release: v3.9.4` and tags it. Name only the editions that should be re-cut;
@@ -63,7 +64,7 @@ What the two commands do, step by step - and the way to do it by hand.
 
 1. Make sure all intended changes are committed, and `./firmware/bundles/build.sh all` is green if anything under `firmware/` moved.
 2. Bump the version the firmware reports: `PF_IMPROV_FW_VERSION` in `firmware/patternflow/net_config.h` (written `X.Y.Z`, no `v`). `shelf.sh` refuses a core image whose define disagrees with the version it is being shelved as.
-3. Turn `CHANGELOG.md`'s `[Unreleased]` into `## [X.Y.Z] - YYYY-MM-DD` and open a fresh `[Unreleased]` above it.
+3. Turn `CHANGELOG.md`'s `[Unreleased]` into `## [X.Y.Z] - YYYY-MM-DD` and open a fresh `[Unreleased]` above it. Copy the new section to `docs/releases/vX.Y.Z.md` (the file name always carries the `v`), with each relative link two folders up (`../../`). The root keeps three releases in full: the fourth-newest section leaves it and becomes a line at the top of *Older releases*, linking its file.
 4. Update the version the docs claim: the "current" line in `AGENTS.md`, the *Moving fast* note in `README.md`, and any guide that names a release.
 5. If hardware changed: confirm `BUILD_GUIDE.md`'s parts table, `hardware/bom/bom_v*.csv` and the schematic agree; regenerate the Gerber zip, renders and schematic exports with the recipe in `hardware/pcb/README.md`; add a `### Hardware` entry to the changelog section; update the board table in `hardware/README.md` and the version line in `docs/assembly/README.md`; attach the Gerber zip, the BOM CSV and the STLs to the release.
 6. Stage the images the site serves:
@@ -102,7 +103,7 @@ Work happens on `dev`, then lands on `main` through a pull request. `main` is pr
 
 ## Current release line
 
-`CHANGELOG.md` is the record — one section per release, newest first — and the [releases page](https://github.com/engmung/Patternflow/releases) carries the notes and the flashable images. The shape of the line, for orientation:
+Every release has its own file in `docs/releases/`, `vX.Y.Z.md`, back to `v1.0.0`. `CHANGELOG.md` holds the three newest in full, newest first, and a line for each older one. The [releases page](https://github.com/engmung/Patternflow/releases) carries the notes and the flashable images. The shape of the line, for orientation:
 
 - `v1.x` -- first public buildable release, then the multi-pattern firmware and browser flasher.
 - `v2.x` -- the v2.0 board (GPIO0 cold-boot fix, cleaned silkscreen), custom pattern workflow, the web platform. `v2.1.0` is the last release for v2.x hardware.

diff --git a/docs/releases/v1.0.0.md b/docs/releases/v1.0.0.md
@@ -0,0 +1,39 @@
+## [v1.0.0] - 2026-04 (initial public release)
+
+The first publicly buildable version of Patternflow.
+
+### Hardware
+- 128x64 px HUB75 LED matrix (P2.5, 320x160 mm)
+- ESP32-S3-WROOM-1 (N16R8 -- 16MB Flash, 8MB PSRAM)
+- 4x EC11 rotary encoders with push-switches
+- Custom PCB (KiCad) -- fabricated via PCBway sponsorship
+- 3D-printed PLA case (white body, black knobs)
+- Powered by user-supplied USB power bank, with internal mounting compartment
+
+### Firmware
+- Arduino-based firmware for ESP32-S3
+- HUB75 DMA driver
+- Default pattern set
+
+### Documentation
+- `docs/BUILD.md` -- full build guide with BOM and assembly walkthrough
+- AliExpress affiliate sourcing links for all electronic components
+- KiCad project files for PCB
+- STL files for case (3 prints total)
+
+### License
+- Firmware & web: MIT
+- Hardware & designs: CC-BY-SA 4.0
+- "Patternflow" is a trademark of SeungHun Lee
+
+### Known Issues
+See [BUILD_GUIDE.md](../../BUILD_GUIDE.md) -- Known Issues section for full details.
+- Reset button must be pressed once after power-up
+- Rotary encoder direction reversed in PCB (compensated in firmware)
+- Silkscreen ambiguity between 0805 caps and resistors
+- LED matrix alignment bumps require trimming during assembly
+
+### Acknowledgments
+- **PCBway** -- for sponsoring v1.0 PCB fabrication
+- **r/arduino community** -- 1.6k upvotes on the prototype thread that pushed this from "just a personal project" toward open source
+- **Doyoon** -- for the suggestion that started the LED matrix direction
diff --git a/docs/releases/v1.1.0.md b/docs/releases/v1.1.0.md
@@ -0,0 +1,16 @@
+## [v1.1.0] - 2026-04 (Multi-pattern Update)
+
+This update consolidates multiple patterns into a single firmware and introduces a runtime pattern selection mode.
+
+### Firmware
+- **Refactored Modular Architecture**: Patterns are now modularized (`pattern_*.h`) and registered in a central registry.
+- **Unified Input Handling**: Introduced `InputFrame` to share normalized encoder and button states across patterns.
+- **Pattern Selection Mode**: Long-press Encoder 4 (1 second) to enter/exit the pattern selection UI.
+- **New Pattern**: Added `Wave1_Saw` (rotated sawtooth waves with fractal noise distortion).
+- **Improved Performance**: Replaced macros with namespace-scoped constants and optimized LUT usage.
+
+### Web
+- **Consolidated Flasher**: The web flasher now provides a single "PatternFlow OS v1.1.0" image containing all patterns.
+- **Simplified UI**: Removed individual pattern buttons in favor of the all-in-one OS build.
+
+---
diff --git a/docs/releases/v2.0.0.md b/docs/releases/v2.0.0.md
@@ -0,0 +1,24 @@
+## [2.0.0] - 2026-05
+
+### Added
+- **Custom pattern workflow.** New `firmware/CUSTOM_PATTERNS.md` with a prompt template and step-by-step guide for creating patterns using AI coding assistants. Drop in a new `pattern_*.h` file, register it, flash.
+- **Web platform.** patternflow.work is now substantially complete: browser-based firmware flasher (Chrome/Edge), Live Editor, journal, and build map.
+- **PCB R13** -- 10k pullup on GPIO0. Resolves the v1 cold-boot issue.
+- **Silkscreen revisions** -- clear R/C designators, explicit encoder back-side marking.
+
+### Changed
+- **Unified versioning.** Project, firmware, PCB, and case are tracked as a single Patternflow version. v2.0.0 covers all of them.
+- **Pattern naming canonicalized.** "Origin" and "Wave Saw" are the display names across firmware, web, and docs. Firmware filename `pattern_wave1.h` renamed to `pattern_wave_saw.h`.
+- **Build guide reorganized.** Known Issues section split into "Fixed in v2.0," "Still open," and "Design notes."
+
+### Fixed
+- **Cold-boot unreliability** after extended power-off. Root cause: GPIO0 strapping pin floating. Full story: [Issue #16](https://github.com/engmung/Patternflow/issues/16). Credit to @idranoutof1d and u/Infrated on r/AskElectronics.
+
+### Still open
+- **Issue #19** -- LED matrix alignment bumps require manual trimming. Will be addressed when the LED diffuser variant ships.
+
+### Deliberate non-changes
+- **C11 (1000uF bulk cap)** retained despite USB inrush concerns. Patternflow is power-bank-powered, not desktop-USB-powered, and the cap improves boot transient stability.
+- **Encoder direction** handled in firmware (sign inversion) rather than via PCB footprint re-spin. Transparent to users.
+
+---
diff --git a/docs/releases/v2.1.0.md b/docs/releases/v2.1.0.md
@@ -0,0 +1,61 @@
+## [2.1.0] - 2026-07
+
+The final consolidation release of the v2.x line before v3.0. Everything a v2.x builder needs — the v2.1 board, the case options, the current firmware and web tools — is pinned here.
+
+### Hardware — PCB
+
+- **v2.1 Gerbers are the recommended board** (`hardware/pcb/gerber/patternflow_v2.1_gerber.zip`). Over v2.0: reworked ESP32↔J1 (HUB75) routing and silkscreen fixes (clearer C15/R10 reference positions). The build guide pins PCB orders to v2.1.
+- **v3.0 test board** lives in `hardware/pcb/gerber/experiment/` — hybrid power input (USB-C plus a 2-pin screw terminal bypass for beginners), all-through-hole, DRC clean. **Unverified — do not order** ([#114](https://github.com/engmung/Patternflow/issues/114)). This absorbs the earlier v2.2 USB-C experiment.
+- Schematic component placement tidied to mirror the physical board layout.
+
+### Hardware — Case
+
+- **One-piece snap-fit enclosure** (`print-ready/variants/oneshot_v2_1/2.stl`) promoted to a supported print option ([#113](https://github.com/engmung/Patternflow/issues/113)): single-piece body plus snap-fit closing part, no gluing. Needs a ~330 mm bed (H2S-class). Includes a wall-mount hanger hole; stable print confirmed.
+- **`easyfit` main plate variant** with alignment tabs along the bond seam — ⚠️ current STL is missing the LED matrix divider slot; do not print as-is ([#154](https://github.com/engmung/Patternflow/issues/154)).
+- **Divided snap-fit experiments** (`print-ready/experiment/`): the one-piece design split to fit 256 mm (P1S-class) beds, including the latest `v2.1_divided.stl`. Modeled but **not print-tested yet**.
+- `oneshot_v3-wip/` quarantined — for the upcoming v3.0 board only, not compatible with v2.x.
+- USB-C adapter clearance fixed after the encoder position change.
+- STLs are stored as regular git files (not LFS) so GitHub's *Download ZIP* works; the Blender source stays in LFS and is attached to releases.
+- v1 Blender/SVG source for the original laser-cut acrylic case added for reference.
+
+### Firmware
+
+- **Foundation refactor.** Patterns render through `PFCanvas` instead of touching the HUB75 driver directly; shared `core_math` / `core_color` / `core_noise` libraries; foundation modules moved into `src/`.
+- **Color and refresh quality**: gamma LUT applied in `PFCanvas::present()`, per-channel white balance and saturation boost, panel refresh raised to ~240 Hz to eliminate phone-camera flicker bands.
+- **Controls**: encoder acceleration; K1 long-press global brightness mode; K2 long-press OSC info screen and runtime toggle (persisted in NVS); K3 knob-map screen; K1/K2 logical mapping fixed; encoder direction corrected for Bourns PEC11R parts.
+- **Two-way OSC as a sidechannel** (no longer a content mode): accepts knob, pattern, and content commands; `/patternflow/ping` full-announce for late-starting hosts; `/patternflow/version` sent with `hello`; remote host auto-learned from the last valid sender (`PF_OSC_REMOTE_HOST` now optional); up to 8 datagrams drained per frame; numeric args accepted as int or float.
+- **Wireless workflows**: ArduinoOTA flashing (with Arduino IDE 2.x workaround documented) and Improv-Serial Wi-Fi provisioning from the browser flasher.
+- **Live pattern preview** behind the SELECT screen.
+- **Audio-react foundation**: WebSocket server routing browser audio analysis through virtual knobs (opt-in override).
+- **Pattern system**: preset library plus reusable custom slots with a custom-first registry (Origin stays pattern 1); memory-for-math optimization toolkit (`fastPow`, LUTs, typed angle constants replacing Arduino macros).
+- Video Baker `PFV1` playback support and a standalone rotary encoder test sketch.
+
+### Web (patternflow.work)
+
+- **Pattern Lab**: development harness with calibrated knobs and encoder buttons; in-app Gemini pattern generation (bring-your-own-key); color ramp + v-field mode with a gradient editor; Experiment tab — a layer-stack patch editor that compiles to pattern code, with knob bindings.
+- **Video Baker** tool for baking patterns to `PFV1` video.
+- **Live Editor**: hardened C++ conversion prompt (exact helper signatures, expensive-math decision table, pre-baked ramp LUTs, knob ranges and `@knobs` annotations carried through), collapsible preset library with shuffle, pattern sharing modal and links, source-aware Discord share.
+- **Build globe**: community builds shown on an interactive globe inside the Inside viewer, with multi-link support per build.
+- **Interactive project map** replacing the status page, including the project's origins (PCBWay sponsorship, Nam June Paik Art Center).
+- **SEO / AI discoverability**: robots.txt, sitemap, JSON-LD, `llms.txt`.
+- **Crowd Supply pre-launch funnel**: hero and mobile floating CTAs link to the campaign page.
+- CI via GitHub Actions: web build, lint as a hard gate, Discord notifications.
+
+### Integrations
+
+- **Ableton Live integration** (`integrations/ableton/`). A Max for Live bridge device maps the four hardware knobs to any Live parameters over OSC (relative encoder deltas, per-slot sweep sensitivity, mappings saved with the Live set), plus guides for M4L/OSC pitfalls and a filming-with-synced-sound workflow.
+- **OSC spec** (`docs/osc-spec.md`): the wire protocol as a versioned contract for third-party integrations.
+
+### Docs
+
+- **Build guide moved to the repo root** as `BUILD_GUIDE.md`, with an all-through-hole BOM and PCB orders pinned to the v2.1 Gerbers.
+- **Breadboard-only build guide** — the no-PCB path is now documented and surfaced as available.
+- HUB75 driver-IC selection and panel compatibility guidance.
+- Pattern licensing stated: CC-BY-SA-4.0, inbound=outbound.
+- Issue form templates, a "Share your build" discussion form, and a development workflow section in CONTRIBUTING.
+
+### Known issues
+
+- `easyfit` main plate STL missing the divider slot ([#154](https://github.com/engmung/Patternflow/issues/154)).
+- Divided (256 mm bed) snap-fit enclosure not yet print-tested.
+- LED matrix alignment bumps still require manual trimming ([#19](https://github.com/engmung/Patternflow/issues/19)).
diff --git a/docs/releases/v3.0.0-notes.md b/docs/releases/v3.0.0-notes.md
@@ -0,0 +1,51 @@
+# Patternflow v3.0.0 — the hybrid-power generation
+
+> **Historical (2026-07).** Long-form notes for one release, kept as written. Release notes since 3.2 live on [GitHub Releases](https://github.com/engmung/Patternflow/releases); `CHANGELOG.md` at the root is the complete record.
+
+The biggest hardware revision since launch. The v3.0 board and enclosure were rebuilt around one goal: **anyone should be able to solder and assemble this.**
+
+**Building one? Start here → [BUILD_GUIDE.md](https://github.com/engmung/Patternflow/blob/v3.0.0/BUILD_GUIDE.md)** — the PCB soldering is covered by a [full video walkthrough](https://youtu.be/NZCjMBCsDAc).
+
+## Highlights
+
+### The board: two power inputs, zero SMD
+- **Screw-terminal power** — strip a USB cable, clamp two wires into the 2-pin terminal on the back of the board. No soldering iron needed for the power input.
+  > ⏸️ **Update (2026-07):** the board also carries a USB-C footprint (`USB1`), but **that input is on hold** — a USB-C-powered board ran fine for 20–30+ minutes and then smoked at a connector pin, destroying the receptacle and power path ([#221](https://github.com/engmung/Patternflow/issues/221)). Leave `USB1`/`R1`/`R2` unpopulated and power the board through `J4` for now. See [BUILD_GUIDE §2](https://github.com/engmung/Patternflow/blob/main/BUILD_GUIDE.md#2-power-input--use-the-screw-terminal).
+- **No SMD passives at all** — every part you solder is through-hole. The whole board is beginner-solderable.
+- Fabricated, assembled, and verified on the screw-terminal input.
+
+### The enclosure: snap-fit, printable on a 256 mm bed
+- Folders named by **printer bed size**: `bed_256mm/encloser.stl` (one STL, ~10 h on a P1S) or `bed_330mm/` one-piece for large-format printers. Knobs print separately in black — white body, black knobs.
+- **Bambu printers: one click** — the case is on [MakerWorld](https://makerworld.com/ko/models/3072492-patternflow-open-source-led-synthesizer-case#profileId-3459015) with tuned print profiles; the same 4-plate project is attached below as `patternflow_v3.3mf`.
+- **Snap-fit back panel**, **two wall-mount holes**, and recesses for the LED panel's alignment bumps — **the nipper-trimming step that's been with us since v1.0 is gone** ([#19](https://github.com/engmung/Patternflow/issues/19)).
+- Using a different LED panel than the recommended one? `bed_256mm/for_other_panels/` has an adjustable-mount variant ([#169](https://github.com/engmung/Patternflow/issues/169)).
+
+### The BOM: every part by part number
+- [`hardware/bom/bom_v3.0.csv`](https://github.com/engmung/Patternflow/blob/v3.0.0/hardware/bom/bom_v3.0.csv) — machine-readable, every part specified by MPN, sourcing notes included. Order from Mouser/DigiKey/LCSC or find the same parts anywhere.
+
+### The guide: watch, don't decipher
+- [BUILD_GUIDE.md](https://github.com/engmung/Patternflow/blob/v3.0.0/BUILD_GUIDE.md) rewritten for v3.0 — **two full video walkthroughs** ([PCB soldering](https://youtu.be/NZCjMBCsDAc) and [assembly to first power-on](https://youtu.be/J9C9bZgkNKs)), photo-documented printing/bonding steps, a collapsible netlist-derived pin reference, and a dedicated OSC/Ableton build path.
+- PCB ordering routed through the [PCBWay shared project](https://www.pcbway.com/project/shareproject/Patternflow_An_LED_synthesizer_776d796c.html) (no Gerber upload needed) — any fab works with the attached zip too.
+
+### Firmware
+- **One image for every board generation** — v2.x and v3.0 share an identical pin map, so the [browser flasher](https://patternflow.work) just works on both. No board selection to get wrong.
+- **Bigger preset library, sturdier engine** — thirteen new presets from the June–July daily batch, three fresh custom-slot patterns, and a new PSRAM-first allocator (`PFMem`) so a fully loaded pattern image can't starve the Wi-Fi/DMA DRAM budget.
+
+## Breaking changes
+
+- **v2.x boards and v3.0 cases are not interchangeable** (and vice versa) — different board size, different port positions.
+- Already own a v2.x build? Everything you need stays bundled at the [v2.1.0 release](https://github.com/engmung/Patternflow/releases/tag/v2.1.0), and the v2 guide lives on as [`BUILD_GUIDE_v2.md`](https://github.com/engmung/Patternflow/blob/v3.0.0/BUILD_GUIDE_v2.md). Bonus for v2 owners: `hardware/case/legacy_v2/encloser_v2.1.stl` is a newly verified snap-fit case for the v2.1 board — no gluing, no trimming.
+
+## Assets
+
+- `patternflow_v3_case_stl_pack.zip` — all v3 case STLs (256 mm kit, 330 mm one-piece, adjustable-mount variant, knob plates)
+- `patternflow_v3.3mf` — Bambu Studio project (4 pre-arranged plates with print settings; same as the [MakerWorld listing](https://makerworld.com/ko/models/3072492-patternflow-open-source-led-synthesizer-case#profileId-3459015))
+- `patternflow_v3.0_gerber.zip` — the verified board
+- `patternflow_v3_firmware.zip` — prebuilt ESP32-S3 binaries (the browser-flasher image) with esptool offsets in the included README
+- `patternflow_case.blend` — Blender source for every printed part (stored in Git LFS; attached here so *Download ZIP* users get the real file)
+
+Full details in the [CHANGELOG](https://github.com/engmung/Patternflow/blob/v3.0.0/CHANGELOG.md).
+
+---
+
+Firmware & web: MIT · Hardware & designs: CC-BY-SA 4.0