The three things a first build got wrong

BUILD_GUIDE.md

@@ -252,8 +252,21 @@ No installation required — desktop **Chrome or Edge** only (Web Serial; Firefo
 
 1. Visit **[patternflow.work](https://patternflow.work)** on a desktop browser.
 2. Connect the ESP32-S3 to your computer with a USB-C **data cable**, using the **left port** (see above).
-3. Scroll to the **Patterns** section, click **"Flash Patternflow OS"**, pick the serial port, and follow the on-screen steps. Wi-Fi can be provisioned right there too (Improv-Serial).
+3. Scroll to the **Patterns** section, click **"Flash Patternflow"**, pick the serial port, and follow the on-screen steps. Wi-Fi can be provisioned right there too (Improv-Serial).
 4. Disconnect, seat the module back into the board sockets (orientation per silkscreen), and connect power.
+5. **Load the patterns.** The image ships with **Origin only** — the rest live on the device's filesystem instead of inside the firmware, which is what freed the memory for everything else. Open **[the decks shelf](https://community.patternflow.work/community/decks)** and press **Install to my board** on the **Basics** pack: 33 patterns, one click, no account. Your browser fetches the pack and hands it to the board over your Wi-Fi, so the board is never talking to the internet itself.
+
+> 🎛️ **One pattern after flashing is correct, not a failed install.** It used to be 34 baked into the image. They moved out so that patterns can be added and removed without reflashing, which is also how anything you make yourself reaches the panel.
+
+> 🔍 **Nothing in the port list?** A module that is running its own firmware does not always announce itself, so put it into download mode by hand before you look again:
+>
+> 1. Press and **hold BOOT**
+> 2. **Tap and release EN / RST** (the reset button)
+> 3. **Release BOOT**
+>
+> The picker should now offer a line like `USB JTAG/serial debug unit (COM4) – Paired`. The number depends on which USB port you used.
+>
+> Still nothing? On this port it is almost always the **cable** — a charge-only USB-C cable enumerates nothing at all. The ESP32-S3 drives its native port from a USB-Serial/JTAG controller built into the chip, so there is no bridge chip and **no CP2102 / CH34x driver to install**; Windows 10 and later, macOS and Linux all recognise it on their own. The driver links on the flasher's "No port selected" screen are for the *right-hand* `UART` port (§8.2), and chasing them here is a dead end.
 
 > 📶 **Changing Wi-Fi later.** The network you set during flashing is **saved on the device and reused on every boot** — it stays until you overwrite it. To move Patternflow to a different Wi-Fi, either **re-flash from the browser** (you'll set the new network during Improv provisioning), or in Arduino IDE do a **full erase** (Tools → *Erase All Flash Before Sketch Upload* → *Enabled*) and re-upload. A plain re-upload does **not** clear the stored credentials.
 

BUILD_GUIDE_v2.md

@@ -382,7 +382,7 @@ No installation required. Works on any desktop with Chrome or Edge.
 
 1. Visit **[patternflow.work](https://patternflow.work)** on a desktop browser.
 2. Connect your ESP32-S3 to your computer via a USB-C **data cable**, using the **left port** (see above) — do not insert it into the PCB yet.
-3. Scroll to the **Patterns** section and click **"Flash Patternflow OS"**.
+3. Scroll to the **Patterns** section and click **"Flash Patternflow"**.
 4. Select the correct serial port when prompted and follow the on-screen steps. Wi-Fi can be provisioned right there too (Improv-Serial).
 
 <img src="docs/build-guide/images/web_flash.jpg" width="33%">

web/public/flash/manifest.json

@@ -2,6 +2,7 @@
   "name": "Patternflow",
   "version": "v3.4.0",
   "new_install_prompt_erase": true,
+  "new_install_improv_wait_time": 20,
   "builds": [
     {
       "chipFamily": "ESP32-S3",

web/src/app/build/breadboard/page.tsx

@@ -138,7 +138,7 @@
             </div>
             <p style={{ margin: '8px 0 0 0', fontSize: '13.5px', lineHeight: 1.55, color: 'var(--pf-ink-muted)' }}>
               Flashing is fiddly once everything is wired into a tangle of jumpers. Connect the bare ESP32-S3 to your computer via USB-C, visit{' '}
-              <Link href="/" style={{ color: 'var(--pf-led)', fontWeight: 600, textDecoration: 'underline' }}>patternflow.work</Link>, and click <strong>“Flash Patternflow OS”</strong> in the Patterns section (Chrome / Edge desktop). Confirm it boots — <strong>then</strong> start the build.
+              <Link href="/" style={{ color: 'var(--pf-led)', fontWeight: 600, textDecoration: 'underline' }}>patternflow.work</Link>, and click <strong>“Flash Patternflow”</strong> in the Patterns section (Chrome / Edge desktop). Confirm it boots — <strong>then</strong> start the build.
             </p>
             <p style={{ margin: '6px 0 0 0', fontSize: '12px', lineHeight: 1.5, color: 'var(--pf-ink-faint)' }}>
               Prefer Arduino IDE? See{' '}
@@ -387,7 +387,7 @@
             ↑ Ground (GND) pins on both sides of all four rotary encoders land on the Ground (<strong>−</strong>) rail of the breadboard.
           </p>
           <div className="w-full mt-4 step-photo-right flex flex-col gap-2">
             <img
               src="/builds/breadboard/step1.jpg"
               alt="Encoders mounted with GND wires connected to the breadboard rail"
               style={{ width: '100%', display: 'block', borderRadius: '8px', border: '1px solid var(--pf-rule)' }}
@@ -428,7 +428,7 @@
             ↑ U1 (ESP32-S3) on the left, and J1 (HUB75E) on the right. Wire the pins that share the same color-coded labels (e.g. R1, B1, A, B...).
           </p>
           <div className="w-full mt-4 step-photo-left flex flex-col gap-2">
             <img
               src="/builds/breadboard/step3.jpg"
               alt="ESP32-S3 connected to the HUB75E LED matrix via ribbon cable"
               style={{ width: '100%', display: 'block', borderRadius: '8px', border: '1px solid var(--pf-rule)' }}
@@ -469,7 +469,7 @@
             ↑ Four rotary encoders on the left, and ESP32 on the right. Wire the signal channels (A, B, SW) to their matching colored tags (e.g. 1A, 2A...).
           </p>
           <div className="w-full mt-4 step-photo-right flex flex-col gap-2">
             <img
               src="/builds/breadboard/step4.jpg"
               alt="All encoder signal wires routed routed into the case alongside the LED panel"
               style={{ width: '100%', display: 'block', borderRadius: '8px', border: '1px solid var(--pf-rule)' }}
@@ -507,7 +507,7 @@
             <BreadboardDiagram mode="rail" />
           </div>
           <div className="w-full mt-4 step-photo-left flex flex-col gap-2">
             <img
               src="/builds/breadboard/step2.jpg"
               alt="Stripped USB and LED panel power wires being twisted onto jumpers"
               style={{ width: '100%', display: 'block', borderRadius: '8px', border: '1px solid var(--pf-rule)' }}
@@ -549,7 +549,7 @@
               { src: '/builds/breadboard/step8.jpg', label: "It's alive! 🎉" }
             ].map((img, idx) => (
               <div key={idx} style={{ display: 'flex', flexDirection: 'column', gap: '4px' }}>
                 <img
                   src={img.src}
                   alt={img.label}
                   style={{ width: '100%', display: 'block', borderRadius: '8px', border: '1px solid var(--pf-rule)' }}

web/src/components/sections/PatternPanel.module.css

@@ -326,6 +326,18 @@
   line-height: 1.5;
 }
 
+/* Underlined, because these two are the way out of this block and the note
+   sits on a dark panel where a colour shift alone is easy to miss. */
+.hardwareNote a {
+  color: inherit;
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}
+
+.hardwareNote a:hover {
+  color: var(--pf-led);
+}
+
 .hardwareReq {
   color: var(--pf-cream);
   opacity: 0.55;

web/src/components/sections/PatternPanel.tsx

@@ -100,9 +100,15 @@ const EDITOR_HEIGHT = 480;
 // with the `.presetNumbers` column count in the 720px media query.
 const MOBILE_PRESET_WINDOW = 7;
 
-// Curated presets baked into the official flash image — keep in sync with
-// presetPatterns[] in firmware/patternflow/pattern_registry.h.
-const NUM_FIRMWARE_PRESETS = 34;
+// Patterns in the Basics pack, which a freshly flashed board installs in one
+// click from the community's decks shelf. Keep in sync with
+// web/public/packs/basics.json.
+//
+// This used to be the count of presets baked into the image, and said 34 long
+// after the firmware kept only Origin — which read as a promise the flash did
+// not deliver, and got filed as a bug. The image ships one pattern on purpose
+// now; the rest arrive as modules.
+const NUM_BASICS_PATTERNS = 33;
 
 export default function PatternPanel({ content }: PatternPanelProps) {
   // Start with Origin selected; the effect below loads it into the editor.
@@ -365,9 +371,25 @@ export default function PatternPanel({ content }: PatternPanelProps) {
                   Browser flashing works in desktop Chrome or Edge.
                 </div>
               </EspWebInstallButton>
+              {/* Kept to one line. A first install can go wrong at the port,
+                  at the pattern count and at Wi-Fi, but a note under a button
+                  is the wrong place to answer all three — the guide holds it,
+                  and the link is how you get there. */}
               <p className={styles.hardwareNote}>
-                Plug the ESP32-S3 in over USB. Brings {NUM_FIRMWARE_PRESETS} presets and sets up
-                Wi-Fi. After that your own patterns go over the air.
+                Plug the ESP32-S3 into the <b>left</b> USB-C port. Sets up Wi-Fi and boots into
+                Origin, then{' '}
+                <a href="https://community.patternflow.work/community/decks">the Basics pack</a>{' '}
+                adds {NUM_BASICS_PATTERNS} more in one click.
+              </p>
+              <p className={styles.hardwareNote}>
+                <a
+                  href="https://github.com/engmung/Patternflow/blob/main/BUILD_GUIDE.md#8-firmware"
+                  target="_blank"
+                  rel="noreferrer"
+                >
+                  Flashing guide ↗
+                </a>{' '}
+                for the steps, the port, and what to do if the board doesn&rsquo;t show up.
               </p>
               <span className={styles.hardwareReq}>Chrome / Edge only</span>
             </div>