Docs: cover BYE/IP/PING protocol + clients/liveness; add release workflow

- PROTOCOL.md: document BYE, IP, and the PING liveness beacon (+ handshake diagram
  and the 5s board-disconnect timeout).
- ARCHITECTURE.md / HOW-IT-WORKS.md: mention the join/leave/IP/PING events, the
  live clients view, and the loading / board-disconnected dashboard states.
- CHANGELOG: note the live clients view, board-disconnect detection, loading
  screen, and PING beacon; date 0.3.0.
- Add .github/workflows/release.yml: on a v* tag, build the fap + ESP firmware and
  publish a GitHub Release with the images attached.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: tarikbc

.github/workflows/release.yml

@@ -0,0 +1,59 @@
+name: release
+
+# Push a version tag (e.g. v0.3.0) to build both halves and publish a GitHub
+# Release with the fap + firmware images attached.
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Build + publish release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build Flipper app (fap)
+        run: |
+          pip install --upgrade ufbt
+          ufbt update --index-url=https://up.momentum-fw.dev/firmware/directory.json --channel=release --hw-target=f7
+          cd flipper/flytrap && ufbt
+
+      - name: Build ESP32-S2 firmware
+        run: |
+          mkdir -p "$HOME/bin"
+          curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | BINDIR="$HOME/bin" sh
+          export PATH="$HOME/bin:$PATH"
+          arduino-cli config init --overwrite
+          arduino-cli config set board_manager.additional_urls https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
+          arduino-cli core update-index
+          arduino-cli core install esp32:esp32@2.0.17
+          mkdir -p esp32/libs
+          git clone --depth 1 https://github.com/me-no-dev/AsyncTCP.git esp32/libs/AsyncTCP
+          git clone --depth 1 https://github.com/me-no-dev/ESPAsyncWebServer.git esp32/libs/ESPAsyncWebServer
+          arduino-cli compile \
+            --fqbn esp32:esp32:esp32s2:PartitionScheme=huge_app \
+            --libraries esp32/libs \
+            --output-dir esp32/flytrap-fw/build \
+            esp32/flytrap-fw
+
+      - name: Publish release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG: ${{ github.ref_name }}
+          REPO: ${{ github.repository }}
+        run: |
+          gh release create "$TAG" \
+            --repo "$REPO" \
+            --title "Flytrap $TAG" \
+            --generate-notes \
+            flipper/flytrap/dist/flytrap.fap \
+            esp32/flytrap-fw/build/flytrap-fw.ino.bin \
+            esp32/flytrap-fw/build/flytrap-fw.ino.bootloader.bin \
+            esp32/flytrap-fw/build/flytrap-fw.ino.partitions.bin

CHANGELOG.md

@@ -2,9 +2,10 @@
 
 All notable changes to Flytrap are documented here.
 
-## [0.3.0] — unreleased
+## [0.3.0] — 2026-07-17
 
-Interface polish, structured captures, docs, and an important bug fix.
+Interface polish, structured captures, a single offline social portal, a live
+clients view, board-liveness detection, docs, and an important bug fix.
 
 ### Fixed
 - **App no longer hangs on "loading" when closed.** The UART worker could block posting
@@ -17,6 +18,11 @@ Interface polish, structured captures, docs, and an important bug fix.
   update it live, so a device that disconnects is removed and the **Clients** counter is
   accurate (previously it only ever counted up). Console moved to the menu to keep the
   dashboard to two uncrowded buttons (**← Captures · → Clients**).
+- **Board-disconnect detection** — a 1s liveness tick watches the ESP's `PING` beacon; if
+  nothing arrives for 5s the dashboard shows **Board disconnected** instead of falsely
+  claiming **Broadcasting**, and recovers automatically when the board returns.
+- **Loading screen** — Start Portal now shows a *Starting…* screen while the ~38.5 KB
+  portal streams over UART (which blocks the UI ~3s), instead of freezing on the dashboard.
 - **Refined dashboard** — status tokens mapped to clean words with a `●` indicator
   (`portal_up ip=…` → **Broadcasting**), evenly-aligned rows, buttons on left/right.
 - **Structured captures** — browse a **list → detail**; fields are **url-decoded** and shown
@@ -31,6 +37,8 @@ Interface polish, structured captures, docs, and an important bug fix.
 - **Station join/leave/IP events.** The ESP now emits `BYE mac=…` when a station leaves
   and `IP mac=… ip=…` when DHCP leases an address (MAC resolved from the soft-AP table),
   in addition to `HIT`. This is what powers the live client list and accurate counter.
+- **`PING` liveness beacon** (~every 2s) so the Flipper can tell the board is still
+  attached and flag the link as lost when it isn't.
 
 ### Portals
 - **Single `social.html` portal replaces the old template pile.** One page with a picker that

docs/ARCHITECTURE.md

@@ -36,9 +36,10 @@ flowchart LR
 A single Arduino sketch. It holds the portal HTML in RAM (streamed from the
 Flipper), runs an open `WiFi.softAP`, a wildcard `DNSServer`, and an
 `ESPAsyncWebServer` catch-all handler. Submitted form fields go back over UART as
-`CRED` lines; station joins as `HIT`. All protocol output is serialized behind a
-mutex so the loop / WiFi-event / async-server tasks can't interleave a line. It
-touches no filesystem — see [PROTOCOL.md](PROTOCOL.md).
+`CRED` lines; stations report as `HIT` / `IP` / `BYE` (join / DHCP lease / leave),
+and a `PING` beacon (~2s) lets the Flipper notice an unplugged board. All protocol
+output is serialized behind a mutex so the loop / WiFi-event / async-server tasks
+can't interleave a line. It touches no filesystem — see [PROTOCOL.md](PROTOCOL.md).
 
 ## Flipper app (`flipper/flytrap/`)
 
@@ -51,7 +52,7 @@ A standard `ViewDispatcher` + `SceneManager` app.
 | `helpers/flytrap_session.c` | start/stop the portal, parse ESP lines, store captures, fire alerts |
 | `helpers/flytrap_storage.c` | FlipperFormat config, portal/HTML + log file I/O, RTC timestamps |
 | `helpers/flytrap_format.c` | url-encode/decode + `key=value` → readable field pretty-printer |
-| `scenes/flytrap_scene_*.c` | main menu, ssid input, settings, dashboard (live), captures list, capture detail, textview (console/log) |
+| `scenes/flytrap_scene_*.c` | main menu, ssid input, settings, dashboard (live, with loading + board-disconnect states), captures list/detail, clients list/detail, textview (console/log) |
 
 ### Threading model
 

docs/HOW-IT-WORKS.md

@@ -64,9 +64,12 @@ touches any filesystem — see [PROTOCOL.md](PROTOCOL.md).
 
 The app is a standard Flipper `ViewDispatcher` + `SceneManager` structure:
 
-- **Main menu** → start/stop the portal, pick a portal HTML, set the SSID, view logs.
-- **Dashboard** (a `Widget`) → live status, credential + client counters.
+- **Main menu** → start/stop the portal, pick a portal HTML, set the SSID, view logs, console.
+- **Dashboard** (a `Widget`) → live status (with a *Starting…* screen and a *Board
+  disconnected* state when the ESP's beacon stops), credential + client counters.
 - **Captures** → a list of captures → a detail screen that url-decodes each field.
+- **Clients** → who's connected right now (MAC, IP, joined time); updates live as
+  stations join, get a DHCP lease, and leave.
 - **Console** → the raw serial stream, exactly as in [PROTOCOL.md](PROTOCOL.md).
 
 A background thread reads UART bytes; all parsing happens on the GUI thread (so there

docs/PROTOCOL.md

@@ -37,6 +37,7 @@ All line-oriented. The Flipper parser matches on the leading token.
 | `BYE mac=<AA:BB:...>` | A station left the AP — the Flipper drops it from the live client list. |
 | `IP mac=<AA:BB:...> ip=<ip>` | DHCP assigned a station its IP (MAC resolved from the soft-AP table). Falls back to `IP ip=<ip>` when the MAC can't be resolved; the Flipper then pairs it to the most recent client without an IP. |
 | `CRED ip=<ip>&<field>=<val>&...` | A form was submitted — the client IP plus every submitted field, url-encoded. One line per submission. |
+| `PING` | Liveness beacon, emitted ~every 2s. The Flipper uses it to detect an unplugged board (no `PING`/traffic for 5s ⇒ link lost); it's dropped from the console so it doesn't spam. |
 
 ## Handshake
 
@@ -56,12 +57,15 @@ Flipper                              ESP
   |  <---- IP mac=... ip=...(DHCP leases it an address)
   |  <---- CRED ip=...&...  (a form is submitted)
   |  <---- BYE mac=...      (the phone leaves)
+  |  <---- PING             (~every 2s, all the while)
   |                                   |
   |  stop\n / reset\n          ----> |   (tear down / reboot)
 ```
 
 If the ESP emits `STATUS boot` mid-session (it rebooted), the Flipper re-sends
-`sethtml` automatically to recover.
+`sethtml` automatically to recover. If `PING` (and all other traffic) stops for
+5s, the Flipper flags the link as lost and the dashboard shows **Board
+disconnected** until the board returns.
 
 ## Notes