web: the guide has a fourth part, Audio

.github/ISSUE_TEMPLATE/guide_stuck.yml

@@ -13,7 +13,7 @@ body:
     id: where
     attributes:
       label: Where in the guide
-      description: The guide (Build, Play or Make), the chapter and the step. Filled in for you if you came from the guide.
+      description: The guide (Build, Play, Make or Audio), the chapter and the step. Filled in for you if you came from the guide.
       placeholder: "Play · 01 Flash, step 5 — Hold BOOT, tap RST, let go."
     validations:
       required: true

.gitignore

@@ -36,6 +36,7 @@ out/
 # Local staging for a release upload (bins duplicated from the flasher folder).
 firmware/release/
 firmware/patternflow/patternflow_secrets.h
+firmware/patternflow/patternflow_secrets.h.shelf-aside
 
 # KiCad 자동 생성/백업
 *.kicad_prl

AGENTS.md

@@ -11,7 +11,7 @@ It is standalone (not Eurorack), powered from a 5 V power bank through a screw t
 - `docs/` — contracts and long-form docs: `EDITIONS.md` (the firmware seam — read it before touching firmware), `rest-api.md` / `osc-spec.md` / `midi-spec.md` / `audio-ws-spec.md` (wire contracts integrations are built against), `pfst-v2-spec.md` (show files), `panel-compatibility.md`, `RELEASING.md`, `SERVICES.md` (production server ops), the assembly map (`docs/assembly/`), the manifesto, investigations, and media (build-guide images in `docs/build-guide/`). Root-level guides: `BUILD_GUIDE.md` (the **v3.0 board**), `BUILD_GUIDE_v2.md` (legacy v2.x board), `PATTERN_GUIDE.md` (community → deck → Pattern Lab → device), `FEATURE_GUIDE.md` (writing a firmware feature or edition), `AUDIO_GUIDE.md` (sound into the panel). The live roadmap is patternflow.work/journal and the `/roadmap` page.
 - `firmware/` — PlatformIO/Arduino code for the ESP32-S3. Main sketch folder: `firmware/patternflow/` with `patternflow.ino`, `config.h` (pin mappings, brightness, limits, LED calibration), `net_config.h` (Wi-Fi / Improv / OTA / self-update defaults and the lane scale — core only; a feature's own tunables live in `features/<name>/<name>_config.h`, and settings TUNE a feature, they never add one; per-device secrets in gitignored `patternflow_secrets.h`), and `pattern_registry.h` (function-pointer pattern table; compiles in Origin alone — the rest of the curated set ships as the Basics pack). Shared engine code lives in `firmware/patternflow/src/` (`core_display.h` HUB75 driver, `core_encoders.h`, canvas/color/math/noise helpers, Wi-Fi/OTA/web-console modules, the hotspot in `core_hotspot.h`) — core only: OSC, audio, MQTT, weather, shows, MIDI and the clock all live in `features/`. `firmware/patternflow/abi/` is the frozen host ⇄ module contract. Curated patterns live in `firmware/patternflow/presets/` (`preset_origin.h`, `preset_wave_saw.h`, dated presets), each using its own pattern namespace; user patterns are `.pfm` modules uploaded to the device over Wi-Fi, built from `firmware/modules/` via `firmware/toolchain/build_module.py` (the old `custom1.h`–`custom3.h` root slots are gone). Features attach through `firmware/patternflow/features/` (named `addons/` until 2026-08-30; legacy spellings are shimmed for out-of-tree bundles — see docs/EDITIONS.md) — a directory and a descriptor of function pointers, with the core naming none of them (see its README). `firmware/bundles/` names firmwares built from the same tree (the shelf editions `audio` and `performance`, plus `clock` and `midi`, compositions the tree keeps buildable but does not publish; the default build has no bundle): two files each, saying which features compile in and what the build calls itself; `firmware/bundles/build.sh` builds the default or a named one, `shelf.sh` stages a publishable image. Device console pages are plain HTML in `firmware/patternflow/console/`, spliced into `*_index.h` by `firmware/toolchain/console_pages.py`. Tooling lives in `firmware/toolchain/` (repo-level scripts) and `firmware/patternflow/toolchain/` (PlatformIO `extra_scripts`, which must stay sketch-relative). Also: `firmware/encoder_test/` (standalone encoder diagnostic) and `firmware/CUSTOM_PATTERNS.md` (pattern authoring guide).
 - `hardware/` — Hardware designs. `case/` (Blender source in `source/`, STLs by printer bed size, `legacy_v2/` for the v2.x board), `pcb/` (KiCad 10.0 source, Gerbers per revision, schematic PDF), `bom/` (`bom_v3.9.csv` — **the BOM source of truth**; the guide's table is derived from it. `bom_v3.0.csv` is kept for the previous board).
-- `web/` — Next.js site at patternflow.work: landing page (`/`, `/pattern`, `/build`, `/inside` are tabs of one view), the interactive guide (`/guide` is a hub over `/guide/build`, `/guide/play` and `/guide/make`, each with a `/ko` twin; one 3D stage in `components/guide/`, the firmware simulator in `lib/guide/`), Pattern Lab (`/pattern-lab`), community (`/community/**`, SQLite + Drizzle + Better Auth, only on the Pi deployment), browser flasher (`/flash`), the edition shelf (`/editions`; `/variants` redirects there), the feature catalogue (`/features`, reels per feature), device update handoff (`/update`), journal, roadmap. `lib/pattern/` is the pattern runtime and annotations, `lib/lab/` the Pattern Lab, `lib/community/` the community, `lib/ai/` the Gemini client. Architecture doc: `web/ARCHITECTURE.md`. The JS presets in `web/src/lib/presets/` are the source of truth for firmware preset headers.
+- `web/` — Next.js site at patternflow.work: landing page (`/`, `/pattern`, `/build`, `/inside` are tabs of one view), the interactive guide (`/guide` is a hub over `/guide/build`, `/guide/play`, `/guide/make` and `/guide/audio`, each with a `/ko` twin; one 3D stage in `components/guide/`, the firmware simulator in `lib/guide/`), Pattern Lab (`/pattern-lab`), community (`/community/**`, SQLite + Drizzle + Better Auth, only on the Pi deployment), browser flasher (`/flash`), the edition shelf (`/editions`; `/variants` redirects there), the feature catalogue (`/features`, reels per feature), device update handoff (`/update`), journal, roadmap. `lib/pattern/` is the pattern runtime and annotations, `lib/lab/` the Pattern Lab, `lib/community/` the community, `lib/ai/` the Gemini client. Architecture doc: `web/ARCHITECTURE.md`. The JS presets in `web/src/lib/presets/` are the source of truth for firmware preset headers.
 - `tools/` — desktop-side helpers: `patternflow-audio-extension` (the browser audio-react extension — also the authoring source the device's `/audio-in` console page is assembled from), `patternflow-audio-android` (phone capture app), `rtpmidi-probe`.
 - `integrations/` — host-software integrations, each with its own README. `integrations/ableton/` is the Max for Live bridge (knobs → Live parameters over OSC). The Home Assistant integration left this repository on 2026-09-03; its author maintains it separately. Integrations are built against the contracts in `docs/` (`rest-api.md`, `osc-spec.md`, `midi-spec.md`), not against the firmware source. `docs/rest-api.md` also has the table for choosing between HTTP, OSC and MQTT, and the rules that make the device's single-connection web server easy to knock over.
 

AUDIO_GUIDE.md

@@ -6,12 +6,15 @@ know where knob values come from.
 
 There are two main ways in, and this guide covers both: the **Chrome
 extension** (any browser tab becomes the source) and the **on-board
-microphone** (a $5 part and four solder joints, and the panel hears the
+microphone** (a $5 part and five thin leads, and the panel hears the
 room with no computer involved). A phone app exists too — it's covered
 briefly at the end — and if you work in a DAW, the panel is also a **MIDI
 device** ([its own section](#midi--the-panel-as-a-midi-port)) and speaks
 OSC ([here](#osc--ableton-today-anything-tomorrow)).
 
+The same ground step by step, on a 3D Patternflow in the browser:
+[patternflow.work/guide/audio](https://patternflow.work/guide/audio).
+
 Like the [Feature Guide](FEATURE_GUIDE.md), this page ends with a section
 written for AI coding agents; everything above it is for people.
 
@@ -92,15 +95,15 @@ until you solder one on and switch it on.
 | Part | What to look for | Notes |
 | --- | --- | --- |
 | PDM MEMS microphone breakout | **Adafruit PDM MEMS Microphone Breakout #3492** (MP34DT01-M), or any clone whose pin row reads **3V · GND · SEL · CLK · DAT** | ~$5. This is the one in the photo. |
-| Hookup wire | 4 thin leads, ~10 cm | Shorter is better — see routing note below. |
+| Hookup wire | 5 thin leads, ~10 cm | Shorter is better — see routing note below. |
 
 **Don't buy these instead:** an **INMP441** or other standard I²S mic (it
 needs three signal pins — this board has exactly two free), or an analog
 electret module (no ADC pin is free at all). It must be **PDM**.
 
 ### Wiring
 
-Four leads, five pads:
+Five leads, four places on the DevKit (GND takes two):
 
 ```
    mic breakout                 ESP32-S3 DevKit
@@ -111,11 +114,11 @@ Four leads, five pads:
    │  CLK  ───────┼──┼───────────►  TX  (GPIO 43)
    │  DAT  ───────┼──┼───────────►  RX  (GPIO 44)
    └──────────────┘  │
-                     └──────────►  GND   ← SEL goes to ground
+                     └──────────►  G   (GND)   ← SEL goes to ground: the same GND pin
 ```
 
-- **Don't forget SEL → GND** — jumper it to the breakout's own GND pad so it
-  shares the same lead. It selects the LEFT channel, the slot a mono read
+- **Don't forget SEL → GND** — it is a lead of its own, soldered to the same
+  GND pin as the GND lead. It selects the LEFT channel, the slot a mono read
   uses; tied high, the mic reads silence while looking perfectly healthy.
 - The DevKit silkscreen says **TX / RX**, not 43/44 — those are the ones.
   They're free because the console talks over native USB, and they are the
@@ -127,8 +130,8 @@ the main board:
 
 1. **Pull the DevKit out** of its sockets (straight up).
 2. Solder the thin wires on the **top side**, where the header pins poke
-   through the module — four spots: TX, RX, 3V3, GND (that's what the photo
-   shows).
+   through the module — five wires on four spots: TX, RX, 3V3, and GND
+   twice (that's what the photo shows).
 3. Route the wires out the top and plug the DevKit back in.
 
 Fully reversible — to undo it, just remove the wires. Two cautions: while
@@ -154,7 +157,7 @@ phone app*, is the other input: the same switch as `AUD` on the panel's
 NETWORK screen.)
 
 The same box editor from the extension lives on this page, under
-**Microphone mapping**, in the console's own look (light, or dark from the
+**Mapping**, in the console's own look (light, or dark from the
 toggle in the header) — same boxes K1 to K4, same curves, same Preview. Its
 level axis is the microphone's, about −45 to +2 dB, and its frequencies stop
 at 8 kHz. Changes save to the panel as you make them; mic settings are stored
@@ -236,6 +239,11 @@ microphone on any lane it's driving. The mic takes whatever's left. So you
 can leave the mic on and still grab a knob whenever you want — it comes back
 to the music a few seconds after you let go.
 
+A value set from the console's knob sliders, by MIDI CC 20–23 or by
+`POST /api/params` outranks all of them: that knob stays where it was put, and
+sound does not move it, until that encoder is turned. The Audio page's line
+does not show this.
+
 The extension keeps driving its knobs through a silent or paused tab, so with
 both on, the microphone does not take over during a pause. Press **Stop** in
 the extension to give the knobs to the room, or **Mute** a knob in the