Site: published by CI after a push to main and after a release (#79)

The Site workflow's last step, and the release workflow after publishing,
ask the web server over SSH to rebuild the site. The key CI holds is tied
on the server to one forced command (restrict,command=...), so CI sends no
command and a leaked key can only refresh the site. The server, the user,
the key and the server's host key are Gitea secrets; with none of them set
the step does nothing.

scripts/site_refresh.sh is what both workflows run;
scripts/site_deploy_keygen.sh makes the key and prints where each half goes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT

.gitea/workflows/ci.yml

@@ -1,14 +1,32 @@
 # CI and releases (docs/milestones/R1.md).
 #   A push to main:    the host tests, with their coverage of lib/, and the README's badges
 #                      published to the branch `badges`.
-#   A pull request:    the same tests and coverage, then the firmware.
+#   A pull request:    the same tests and coverage, then the firmware (from the build cache).
 #                      A branch's pushes run nothing by themselves: its pull request runs, once.
-#   A tag v*:          all of it, then a Gitea release with the signed Update File.
+#   A tag v*:          the tests, then the firmware built once, clean, signed and published as a
+#                      Gitea release. The site is then rebuilt: its home page and Downloads name
+#                      the latest release when they are built (issue #79).
 #   Run by hand:       the release of a tag that exists already (the ones from before CI).
 #
 # The job runs in a plain Python image, as scripts/ci.sh does on a developer's machine, with the
 # toolchains in a Docker volume the runner allows (container.valid_volumes: roro9stack-pio): that
 # volume is the cache. No JavaScript actions, so the image needs no Node: the checkout is git.
+#
+# What the volume keeps between runs, and what makes each go stale (issue #74, R1.md):
+#   /pio/packages, /pio/platforms   toolchains and the framework: by their versions in platformio.ini
+#   .../framework-arduinoespressif32-libs/.roro-sdkconfig.defaults
+#                                   the mark that the framework is already rebuilt with our SDK settings: the
+#                                   project's sdkconfig.defaults, which isn't in git, so that every fresh
+#                                   checkout rebuilt the framework (260 s). The platform checks its hash
+#                                   against platformio.ini's settings, and rebuilds if they differ. It is kept
+#                                   inside the libraries it describes, so it goes when they are reinstalled.
+#   /pio/ci/build-cache             PlatformIO's build cache (SCons): objects by the signature of their
+#                                   sources and command line. For pull requests only: a release compiles
+#                                   its own sources from nothing.
+#   /pio/ci/ccache                  the host tests' objects (they're built for coverage, which the build
+#                                   cache can't keep: it would lose the .gcno files)
+#   /pio/ci/venv                    PlatformIO and gcovr: delete the folder to upgrade them
+# To start from nothing (a slow run, about 7 minutes): delete /pio/ci and that .roro-sdkconfig.defaults file.
 name: CI
 on:
   push:
@@ -37,13 +55,23 @@ jobs:
     env:
       PLATFORMIO_CORE_DIR: /pio
       RORO_NO_DOCKER: 1
+      SDK_MARK: /pio/packages/framework-arduinoespressif32-libs/.roro-sdkconfig.defaults
+      CCACHE_DIR: /pio/ci/ccache
+      CCACHE_MAXSIZE: 1G
     steps:
       - name: Tools
         run: |
           apt-get update -qq
-          apt-get install -y -qq --no-install-recommends git build-essential openssl >/dev/null
-          pip install -q --no-cache-dir --root-user-action=ignore platformio gcovr
-          pio --version; df -h /pio | tail -1; ls /pio | head
+          apt-get install -y -qq --no-install-recommends git build-essential openssl ccache >/dev/null
+          mkdir -p /pio/ci
+          if [ ! -x /pio/ci/venv/bin/pio ]; then
+            python -m venv /pio/ci/venv
+            /pio/ci/venv/bin/pip install -q --no-cache-dir platformio gcovr
+          fi
+          ln -sf /pio/ci/venv/bin/pio /pio/ci/venv/bin/gcovr /usr/local/bin/
+          pio --version; df -h /pio | tail -1; du -sh /pio/ci/* 2>/dev/null || true
+          # The build cache only grows: start it again past 3 GB (a full set of objects is 160 MB, and each run adds about 40).
+          if [ "$(du -sm /pio/ci/build-cache 2>/dev/null | cut -f1)" -gt 3072 ] 2>/dev/null; then rm -rf /pio/ci/build-cache; fi
 
       - name: Check out
         run: |
@@ -57,11 +85,20 @@ jobs:
 
       - name: Host tests, and their coverage of lib/
         if: github.event_name != 'workflow_dispatch'
-        run: scripts/coverage.sh
+        run: |
+          export PATH="/usr/lib/ccache:$PATH"  # gcc and g++ through ccache
+          scripts/coverage.sh
+          ccache -s | grep -E 'Hits|Misses' | head -2
 
+      # A pull request only: a tag's firmware is built once, by the release step below.
       - name: The firmware
-        if: github.event_name == 'pull_request' || github.ref_type == 'tag'
-        run: scripts/ci.sh builds
+        if: github.event_name == 'pull_request'
+        env:
+          PLATFORMIO_BUILD_CACHE_DIR: /pio/ci/build-cache
+        run: |
+          [ ! -f "$SDK_MARK" ] || cp "$SDK_MARK" sdkconfig.defaults
+          scripts/ci.sh builds
+          cp sdkconfig.defaults "$SDK_MARK"  # what the framework in the volume is rebuilt with, now
 
       # The README's badges are files on a branch of their own, replaced at each push to main and
       # at each tag (the release badge says which tag is the latest)
@@ -103,7 +140,12 @@ jobs:
           trap 'rm -f "$RORO_OTA_KEY"' EXIT
           printf '%s\n' "$OTA_SIGNING_KEY" > "$RORO_OTA_KEY"
           umask 022
+          # The framework rebuilt with our settings is reused if it matches (the platform checks);
+          # the release's own sources are compiled from nothing, with no build cache.
+          [ ! -f "$SDK_MARK" ] || cp "$SDK_MARK" /tmp/release-src/sdkconfig.defaults
           scripts/release_build.sh /tmp/release-src dist
+          # An old tag has no SDK settings of its own, and no sdkconfig.defaults afterwards: nothing to mark.
+          [ ! -f /tmp/release-src/sdkconfig.defaults ] || [ ! -d "$(dirname "$SDK_MARK")" ] || cp /tmp/release-src/sdkconfig.defaults "$SDK_MARK"
 
       - name: Publish the release
         if: steps.release.outputs.tag != ''
@@ -112,3 +154,14 @@ jobs:
           GITEA_REPO: ${{ github.repository }}
           GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
         run: scripts/release_publish.py dist
+
+      # The site names the latest release on its home page and lists them all on Downloads, both
+      # read when it is built: so it is rebuilt now (issue #79, as the Site workflow does).
+      - name: Refresh the site
+        if: steps.release.outputs.tag != ''
+        env:
+          SITE_DEPLOY_KEY: ${{ secrets.SITE_DEPLOY_KEY }}
+          SITE_DEPLOY_HOST: ${{ secrets.SITE_DEPLOY_HOST }}
+          SITE_DEPLOY_USER: ${{ secrets.SITE_DEPLOY_USER }}
+          SITE_DEPLOY_KNOWN_HOSTS: ${{ secrets.SITE_DEPLOY_KNOWN_HOSTS }}
+        run: scripts/site_refresh.sh

.gitea/workflows/site.yml

@@ -1,17 +1,19 @@
 # The project site (docs/milestones/W1.md): built with Zola to see that it builds and that its pages
-# are sound. Publishing is the maintainer's: the web server pulls main and runs `zola build`.
+# are sound. After a push to main it is then published: the job asks the web server, over SSH, to
+# pull main and rebuild (issue #79, scripts/site_refresh.sh). The key it holds can run that one
+# command there and nothing else; the server, the user and the keys are secrets, not in this file.
 #
 # It runs when the site, or a document the site is built from, changes (a pull request, or a push to
 # main); the firmware workflow (ci.yml) skips a change that touches only these files. A change that
-# touches both runs both. src/main.cpp is here too: the site's command reference is generated from the
-# firmware's own `help` text, and this job checks that it is still current.
+# touches both runs both. src/main.cpp and lib/core/src/app_keys.h are here too: the site's command
+# reference and its key tables are generated from them, and this job checks that they are still current.
 name: Site
 on:
   push:
     branches: [main]
-    paths: ['site/**', 'docs/**', 'README.md', 'CONTEXT.md', 'src/main.cpp', '.gitea/workflows/site.yml']
+    paths: ['site/**', 'docs/**', 'README.md', 'CONTEXT.md', 'src/main.cpp', 'lib/core/src/app_keys.h', '.gitea/workflows/site.yml', 'scripts/site_refresh.sh']
   pull_request:
-    paths: ['site/**', 'docs/**', 'README.md', 'CONTEXT.md', 'src/main.cpp', '.gitea/workflows/site.yml']
+    paths: ['site/**', 'docs/**', 'README.md', 'CONTEXT.md', 'src/main.cpp', 'lib/core/src/app_keys.h', '.gitea/workflows/site.yml', 'scripts/site_refresh.sh']
 
 jobs:
   build:
@@ -51,3 +53,14 @@ jobs:
 
       - name: Check the pages
         run: python3 site/tools/check_site.py /tmp/site-out
+
+      # Only what has been merged, and only once it has built and passed the checks above. A pull
+      # request never gets here, and the secrets are given to this step alone.
+      - name: Publish the site
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        env:
+          SITE_DEPLOY_KEY: ${{ secrets.SITE_DEPLOY_KEY }}
+          SITE_DEPLOY_HOST: ${{ secrets.SITE_DEPLOY_HOST }}
+          SITE_DEPLOY_USER: ${{ secrets.SITE_DEPLOY_USER }}
+          SITE_DEPLOY_KNOWN_HOSTS: ${{ secrets.SITE_DEPLOY_KNOWN_HOSTS }}
+        run: scripts/site_refresh.sh

.gitignore

@@ -12,3 +12,6 @@ sdkconfig.*
 
 # The built site (site/config.toml sends it here)
 /public/
+
+# The version, written by scripts/version.py before each build
+lib/version/src/version_generated.h

CONTEXT.md

@@ -106,6 +106,14 @@ The regulatory band plan the device transmits under (here EU868). It sets the al
 **Duty Cycle Budget**:
 The share of airtime the Region allows this device to transmit. When it's used up, outgoing traffic waits.
 
+**Shell**:
+The App that runs the console's commands on the device itself, and shows what the console prints. Trusted like the USB port, not like the network.
+_Avoid_: terminal, command line, REPL
+
+**Help panel**:
+The list of the keys that work on the screen you are on, opened with Fn+h anywhere (or `?` outside Text Entry). Each App answers for its current state; no screen names keys any other way, except the first-start Setup.
+_Avoid_: hints, cheat sheet, shortcuts bar
+
 **Text Entry**:
 When an App is editing text. During Text Entry, `;` `.` `,` `/` type their characters and Fn makes them arrows. Otherwise they are arrows on their own.
 _Avoid_: edit mode, insert mode

README.md

@@ -8,6 +8,10 @@ A multi-app firmware for the **M5Stack Cardputer ADV** with the **Cap LoRa-1262*
 - Decisions: [docs/adr/](docs/adr/)
 - Milestones: [docs/milestones/](docs/milestones/)
 
+## On the device: one key
+
+**Fn+h, on any screen, lists the keys that work there** (`?` does the same outside a text field). No screen names its keys itself (docs/milestones/U1.md). Every screen's keys are one table in `lib/core/src/app_keys.h`: the help panel shows the table of the state an App is in, and the website's key tables are generated from the same file.
+
 ## Requirements
 
 Only **Docker** is needed. PlatformIO and the ESP32 toolchain run inside a container, and are cached in the `roro9stack-pio` Docker volume. The first build downloads about 1 GB and takes a few minutes.
@@ -22,7 +26,7 @@ This runs the host-side unit tests (`test/`, `native` environment), then builds
 
 `scripts/coverage.sh` runs the same tests with coverage counters and writes a line-by-line report to `.pio/coverage/index.html`. The badge above is its figure for `main`: the share of the lines of `lib/` that the host tests run. `lib/` is the logic that compiles on a PC; `lib/SD` (the card's driver) and `src/` (the Apps, the Services, everything that needs the device) have no host tests and aren't in that figure.
 
-The framework is rebuilt with the TLS settings in `platformio.ini` (`custom_sdkconfig`, ADR 0006), so the first build after a fresh checkout takes about 4 minutes; later builds take under a minute.
+The framework is rebuilt with the TLS settings in `platformio.ini` (`custom_sdkconfig`, ADR 0006), so the first build after a fresh checkout takes about 6 minutes; later builds take about 15 seconds when little has changed. The platform knows the framework is already rebuilt by `sdkconfig.defaults` in the project folder, which it writes and git ignores: delete it and the next build rebuilds the framework. CI keeps that file, a build cache and ccache in its volume (docs/milestones/R1.md).
 
 ## CI and releases
 
@@ -152,6 +156,10 @@ A new note has no file until something is typed; its file is then named after it
 
 A note holds up to 16 KB while it's edited. A bigger text file opens read-only in the Storage App (editing any size is issue #47). The Storage App's text viewer has `e` to edit a file with the same editor, anywhere on the card, unless the file is read-only.
 
+## Shell
+
+The Shell App (docs/milestones/S1.md) runs the commands below on the device's own screen and keyboard: no PC, no cable, no Wi-Fi. **It shows the replies to its own commands and nothing else**: the console knows who each line is printed for, so a listing read by another task a moment later is still the Shell's, and what USB or the Debug Console asked for is not. Ctrl+b shows everything instead. Tab completes a command word by word (`lora st` gives `lora status`) and, past it, a path on the SD card (`ls /no` gives `ls /notes/`), Fn with up and down recalls earlier lines, Alt with up and down scrolls back. **An App's name with a capital opens it** (`Notes`, `Irc`, `Wifi`, `Gnss`, `Gemini`, `Lora`, `Storage`, `System`, `Settings`), from the consoles too. `rm` is Unix's, with a question: a folder needs `-r`; a file, or a folder with something in it, is asked about unless `-f` (`rm -rf`); an empty folder goes without a word. `*` and `?` in a name stand for several files (`rm /notes/*.txt` asks once, with the count; 64 at most). `clear` empties the screen and `quit` leaves. It is trusted like the USB port: `debug on` and `debug token` work from it. It uses about 7 KB of memory while it is open, and none otherwise.
+
 ## Development aids
 
 `scripts/serial_log.sh [seconds] [command…]` records the serial output, and can send commands to the firmware first. For example, `scripts/serial_log.sh 30 short sleep:12 burst` sets short screen timeouts, waits 12 s, then sends a burst of Toasts.
@@ -159,7 +167,7 @@ A note holds up to 16 KB while it's edited. A bigger text file opens read-only i
 | Command | Effect |
 |---|---|
 | `burst` | Publishes 5 Notifications at once |
-| `key up\|down\|left\|right\|select\|back\|home`, or `key <char>` | Injects a key press |
+| `key up\|down\|left\|right\|select\|back\|home\|del\|tab\|space\|help`, or `key <char>` | Injects a key press (`help` is Fn+h: the keys of the screen that is showing) |
 | `sound on` / `sound off` | Toggles the Sound setting (beep + LED) |
 | `short` / `normal` | Screen timeouts 5 s / 10 s, or 30 s / 60 s |
 | `wifi add <ssid><TAB><password>` | Adds a Saved Network (so credentials stay out of the repo) |
@@ -177,13 +185,15 @@ A note holds up to 16 KB while it's edited. A bigger text file opens read-only i
 | `irc say <buffer> <text>` | Types into a Buffer, commands included (`irc say 0 /join #test`) |
 | `irc dump` | Prints IRC status, memory, and the last lines of each Buffer |
 | `wifi status` | Prints Wi-Fi state, network, signal, clock and free heap, then the address, gateway, DNS and NTP servers in use and where each came from |
-| `info` | Firmware, uptime, last start reason, memory, Wi-Fi, the SD card and its write faults since boot, and both app slots with their versions and OTA states |
+| `info` | Firmware, uptime, last start reason, memory, Wi-Fi, the SD card and its write faults since boot, **which App is in front**, and both app slots with their versions and OTA states |
+| `Notes`, `Irc`, `Wifi`, `Gnss`, `Gemini`, `Lora`, `Storage`, `Shell`, `System`, `Settings` | Opens that App: a capital letter is an App, not a command |
 | `tasks` | FreeRTOS tasks over the next second: state, priority, lowest free stack, share of a core, each core's load, and how many passes the main loop made |
 | `net` | Bytes each network service has read and written since boot |
 | `reboot` / `boot other` | Restart, or restart into the other app slot (a manual Rollback) |
 | `log level <0-5>` | ESP-IDF log level |
 | `ls [folder]` / `du <path>` | Lists a folder of the SD card with sizes and dates, or counts the files and bytes under a path |
-| `cp [-f] <from> <to>` / `mv [-f] <from> <to>` / `rm <path>` / `mkdir <path>` / `cancel` | What the Storage App does, with its rules: copy (folders too), move or rename, delete (a folder with what's in it), new folder. `-f` replaces a file that's in the way; a tab separates paths that hold spaces; `cancel` stops a copy or a delete |
+| `screenshot [seconds]` | The screen as a PNG in `/screenshots` on the card, now or after a pause to get to the screen you want (240 x 135, about 33 KB). Over the Debug Console a bare `screenshot` sends the screen to the PC instead |
+| `cp [-f] <from> <to>` / `mv [-f] <from> <to>` / `rm [-r] [-f] <path>` / `mkdir <path>` / `cancel` | What the Storage App does, with its rules: copy (folders too), move or rename, delete (`rm -r` for a folder and what's in it, as Unix has it), new folder. `-f` replaces a file that's in the way; `*` and `?` in the last part of a path (`ls`, `du`, `rm`, `cp`, `mv`) run the command for each name matched, 64 at most; a tab separates paths that hold spaces; `cancel` stops a copy or a delete |
 | `install <path>` | Update from SD with that `.ota` file, as Settings → Firmware does |
 | `update check` / `update list` / `update status` / `update install <tag>` | The project's releases on Gitea: look at the latest, list the last ten, say what's known, or download and install one |
 | `update pretend <version>` / `update probe <host>` / `update damage cut\|flip <n>` / `update daily` | Pretend to run another version (so a release counts as an update), see whether a server's certificate is accepted, cut or damage the next download, run the daily check again |

docs/milestones/R1.md

@@ -172,3 +172,62 @@ The issue asked for a token that could be set, so that Debug Builds could be pub
 **One false alarm:** after the tests the console "wouldn't come back on". It was off: the setting had been left off by `debug off`, and the page's "Switch it on?" dialog opens on **Cancel**, so Enter twice leaves it off. Nothing was lost.
 
 **Not checked:** `scripts/flash.sh --debug` over USB (no device on USB here); "New token" and "Type a token" from the page (the code paths are the ones `debug token` uses, which need the cable); the Toast itself on screen (the console is closed while it shows; its Notification is in the log); free memory with the console off, which only the serial port could say (the static figures above are the evidence); fetching a release's ELF, which needs a crash on a released version.
+
+## CI that doesn't rebuild the world (issue #74)
+
+A pull request's run took over seven minutes, a tag's thirteen and a half. The goal: a firmware build under a minute.
+
+### Where the time went (run 81, a pull request, 2026-10-06)
+
+| Step | Time |
+|---|---|
+| Tools (apt, pip) | 15 s |
+| Check out | 2 s |
+| Host tests and coverage | 55 s |
+| **The firmware** | **358 s** |
+| of which: CMake configuring ESP-IDF | 87 s |
+| of which: compiling ESP-IDF's libraries | 171 s |
+| of which: our own build (the Arduino core, the libraries, `src/`) | 91 s |
+
+A tag's run did the firmware step, then built the same commit again for the release: twice 356 s.
+
+### Why the framework was rebuilt every time
+
+The framework is rebuilt with our SDK settings (ADR 0006), and the rebuilt libraries stay in the toolchain volume. But the platform decides whether they match by reading **`sdkconfig.defaults` in the project folder**, whose first line carries a hash of the settings. That file is generated, and not in git. A fresh checkout has none, so the platform concluded "different settings", **reinstalled the framework and rebuilt it**: 260 seconds, at every run, to arrive at the libraries that were already there. On a developer's machine the file is simply still there from the last build, which is why nobody saw it.
+
+### What changed
+
+| Change | Effect |
+|---|---|
+| **The file is kept in the volume, inside the libraries it describes** (`framework-arduinoespressif32-libs/.roro-sdkconfig.defaults`), copied into the checkout before a build and back after one that passed. The platform still checks its hash against `platformio.ini`: changed settings rebuild, as they must. Kept there and not beside them, it disappears when the libraries are reinstalled, so it can't describe libraries that are gone | 358 s to 92 s |
+| **The version is no longer a `-D` on every compiler command line.** `scripts/version.py` writes `lib/version/src/version_generated.h` (not in git, written only when it changes), read by one file. Before, every commit recompiled everything, on a developer's machine too, and no cache could have helped | A rebuild with nothing changed: 77 s to 13 s, locally |
+| **PlatformIO's build cache** (`PLATFORMIO_BUILD_CACHE_DIR`, SCons's CacheDir) in the volume, for the firmware of pull requests: objects by the signature of their sources and command line | 92 s to 26 s, with a new version and one changed file |
+| **ccache for the host tests.** They are built with coverage counters, and the build cache would return objects without their `.gcno` files; ccache keeps both | 49 s to 33 s. What's left is PlatformIO starting 51 test programs |
+| **A tag builds its firmware once**, in the release step | minus 6 minutes |
+| PlatformIO and gcovr in a virtual environment in the volume | a few seconds |
+
+**A release compiles its own sources from nothing:** it reuses the rebuilt framework (the platform checks the hash) but not the build cache, so no published file contains an object that came from another commit's build.
+
+### Measured (a development machine, fresh copies of the tree, the same volume)
+
+| | Before | After |
+|---|---|---|
+| The firmware, fresh checkout, nothing cached for it | 358 s | 82 s (it fills the cache) |
+| The firmware, fresh checkout, a new version and one file changed | 358 s | **27 s** |
+| Host tests and coverage | 49 s | 33 s |
+| Rebuilding locally with nothing changed | 77 s | 13 s |
+
+### Measured on the runner (pull request #76, 2026-10-07)
+
+| Run | Tools | Tests and coverage | The firmware | The whole job |
+|---|---|---|---|---|
+| Before (run 81) | 15 s | 55 s | 358 s | 434 s |
+| The first with the new workflow: no mark yet, the framework is rebuilt once more and the caches fill | 16 s | 59 s | 354 s | 431 s |
+| The next commit (only the workflow changed) | 10 s | 36 s | **51 s** | **100 s** |
+| The same commit again | 10 s | 36 s | **18 s** | **66 s** |
+
+In the 51-second run, 245 objects came from the cache and 43 were compiled: `version.cpp`, as expected, and all 42 files of `src/`, which had not changed. In the run after it, all 290 came from the cache. So the objects of `src/` made by the run that rebuilt the framework were not reusable by a normal run, and those of a normal run are: the two-pass build that rebuilds the framework compiles `src/` with something different on its command line. It costs one 51-second run after each framework rebuild, which is rare; I did not look for what differs.
+
+The firmware step with everything cached is 18 seconds: the libraries are downloaded and unpacked (4 s), the dependency scan (5 s), fetching 290 objects, the link and the image (the last 11 s). A pull request that changes a few files should land between that and 51 seconds.
+
+**What it costs:** the build cache grows by about 40 MB a run (each linked firmware is kept) and is started again past 3 GB; ccache is held to 1 GB.

docs/milestones/S1.md

@@ -136,3 +136,69 @@ M3 found the LoRa radio's noise floor about 15 dB above what the chip hears alon
 **Settings > Pause GNSS for LoRa**, off by default: while the LoRa radio listens or sweeps, the GNSS receiver waits in standby, and wakes when the radio goes back to sleep (a Fix again after about 7 s here). Never during a Track. The GNSS App says "GNSS is paused" meanwhile. `gnss quiet on|off` on the console.
 
 It's off by default because GNSS on by default was decided in M2 (Q58), and from M4 the radio listens all the time: then "pause while listening" means GNSS mostly off, which is a decision about position, the clock and Tracks, for M4's design round (issue #23).
+
+## The Shell (issue #67)
+
+The console's commands could only be typed on a PC: over USB, or over Wi-Fi with the Debug Console. A device in a bag, or on a network that is down, could not be asked anything. The Shell is an App that runs the same commands on the device's own screen and keyboard.
+
+### Decisions (design round 2026-10-07)
+
+| # | Decision |
+|---|---|
+| Q204 | **An App, "Shell", in the Launcher**, in every firmware: its commands already work over USB for anyone holding the device. |
+| Q205 | **Trusted like USB serial**, not like the network: `debug on` and `debug token` work from it, as they do in Settings. The token is never shown. |
+| Q206 | *Revised the same day, after trying it.* **It shows the replies to its own commands, and only those.** The console knows who each line is printed for (`Console::Origin`): a command run from the Shell prints as the Shell's, and so does what answers it later from another task, which notes who asked and takes it back when it prints (`ls`, `tasks`, `du`, `cp`, `update check`, `sd list`, `screenshot`, `gemini get`). What USB or the Debug Console asked for, and the system's own lines, are not the Shell's. **Ctrl+b shows everything** instead. The first version kept whatever was printed in the ten seconds after a command, which was a guess, and a noisy one. |
+| Q207 | **Nothing while it's closed.** Open, a 4 KB ring of the console's and up to 4 KB of lines; both go when the App is left, with the list of commands for Tab. |
+| Q208 | Enter runs the line; Fn with up and down recalls the last 16; Alt with up and down scrolls back. **Tab completes** the command, **every word of it** *(the first only, at first)*: `lora st` gives `lora status`, `gnss track ` lists `start  stop`, `key ` its eleven names. The words come from the firmware's `help` text, read as it is written, so a new command completes without a table to keep. *(Added the same day)* **past the command, a path on the SD card**: a folder keeps its slash to go on from, a file completed whole gets a space, several candidates are listed. Whatever the case typed, the name's own is taken, since the card doesn't tell them apart. After a file command the first slash is understood (`cat no` is `/no`). A name with a space in it isn't completed. |
+| Q209 | *Revised the same day.* **`rm` is Unix's, with a question.** A folder needs `-r`, here and over the consoles (where `rm <folder>` used to remove it with what was in it). In the Shell, a file, or a folder with something in it, is asked about unless `-f` (`-rf`, `-r -f`); an empty folder with `-r` goes without a word; what `rm` would refuse anyway, it refuses itself. Over the consoles nothing is asked: scripts delete as before. **`screenshot [seconds]`** saves the screen as a PNG in `/screenshots`, now or after a pause, since from the Shell "now" is the Shell. `get`, `put`, `coredump get` and `reset` answer `Debug Console only`. *(Added the same day)* **`*` and `?` in a name**, for `ls`, `du`, `rm`, `cp` and `mv`, here and over the consoles: `rm /notes/*.txt`, `cp /gnss/2026-10-0?.gpx /backup`. In the last part of the path only, any case, as the card has it. It is the same command once for each name matched, in the name's order; `cp` and `mv` then need a folder that exists to put them in. Over 64 matches is refused whole, as is none. In the Shell `rm` with a pattern asks **once**, with the count. |
+| Q210 | Commands are echoed as `> command` into the console, so a session reads the same from afar. **A token being set is not echoed.** |
+| Q211 | **Not in Safe Mode**, which starts no Apps: issue #77. |
+| Q212 | Its keys are a table in `app_keys.h`, so the help panel and the website have them; a page in the user guide. |
+| Q213 | *Added the same day.* **An App's name with a capital opens it:** `Irc`, `Wifi`, `Gnss`, `Gemini`, `Lora`, `Storage`, `Notes`, `Shell`, `System`, `Settings` (the App's id, up to its first dash). From the Shell, without going back to the Launcher, and from the consoles too. The capital says "an App": every command of the firmware is in small letters. Tab completes them. |
+
+### As built
+
+- **`ShellApp`** (`src/apps/shell_app.cpp`), with its model host-tested in `lib/apps_model/src/shell_log.h`: lines arriving in pieces, the 4 KB limit, the words of every command out of the `help` text (Apps' names included), and Tab.
+- **Who a line is for:** `Console::As` marks the calling task as printing for the Shell while it lives, and `Console::origin()` lets a command that answers later carry that to wherever it prints. The console has a second ring for the Shell, which gets the lines marked so, or everything.
+- **The Shell hands its lines to the main loop**, which runs them like the consoles' commands. See below for why.
+- **`info` says which App is in front** (`app: Shell`): so that a hand driving the device from afar can look before it types.
+- **`screenshot`** writes the PNG a row at a time with no buffer: 8-bit indexed colour, the 256 colours of RGB332 as the palette, the pixels in one stored deflate block (`lib/files/src/png_rgb332.h`, 4 tests). 33,383 bytes for the 240 x 135 screen. A Toast says so once it is on the card, so the Toast is never in the picture.
+- **The `help` text lost its shorthand** (`update check | list | status` is written out), since Tab reads its words from there: `|` between two commands, `on|off` between two words, three spaces before the description. The Shell's own words (`clear`, `quit`, `key`'s names) are added in the same notation.
+- **Tab on a path** reads the folder on the storage task while the main loop waits, so it is bounded: 400 entries looked at, 24 candidates given back, and `...` after the list when there were more.
+- **A pattern** is matched in `lib/files/src/file_names.h` (`globMatch`, host-tested), and the names it matches are lined up as so many commands, which the main loop runs one after the other as each finishes. `cancel` empties the line-up. 2000 entries looked at, 64 matches at most.
+- **Cost:** 21 KB of flash, 96 bytes of static RAM. Open: 7 KB of heap (107.6 KB free before, 100.7 with it open, 106.1 after leaving).
+
+### What went wrong while building it
+
+**The device crashed, and the test sent a message to an IRC channel.** The first version ran a command from inside the key handler. Driven from the Debug Console, that is: the main loop, a remote command, `key select`, the App manager, the Shell, `runCommand` a second time, the file command, and `printf` under all of it. The main loop has under 2 KB of stack to spare; `rm` on a folder went past it. The crash report decoded to exactly that chain.
+
+The device restarted into the Launcher, and the test script, which did not look, went on typing. Its next Enter opened IRC, which connected, and a few lines later it typed "No" into a channel and pressed Enter. One word, sent to real people, that can't be taken back.
+
+Two changes came of it. The Shell now **queues** its line and the main loop runs it, at the same stack depth as a console's command. And `info` reports the App in front, which the test script now checks before every line it types.
+
+### Checks on the device (2026-10-07, driven over the Debug Console with `key`)
+
+| Check | Result |
+|---|---|
+| Open it from the Launcher, type `ls /`, Enter | The folders are listed |
+| Tab on `in` | `info  install` is shown and the line stays; on `u` it becomes `update `; on `l`, `log  ls  lora  loop` |
+| Up | The line before comes back |
+| `screenshot` | `/screenshots/20261007-104357.png`, 33,383 bytes. Fetched and decoded on the PC: 240 x 135, indexed, every chunk's CRC right, the pixels the Shell's screen |
+| Output | With a Debug Console client connecting and disconnecting for every key, the Shell shows the commands and their replies and nothing else: `info`, `ls /` (answered by the storage task), `tasks` (answered a second later) |
+| `rm` on a folder, without `-r` | Refused, the folder stays |
+| `rm -r` on an empty folder | Removed, no question |
+| `rm -r` on a folder with files | Asks; Cancel leaves it. `rm -rf` removes it without asking |
+| `rm` on a file | Asks; Delete removes it |
+| Tab on a path | `ls /no` becomes `ls /notes/`, and again, with one note in it, the note's whole name and a space. `ls /g` lists `gemini/  gnss/`. `cat no` becomes `cat /notes/`. `rm -r /CAP` becomes `rm -r /captures/`. `ls /zz` stays as it is |
+| Tab past the first word | `lora st` becomes `lora status `; `gnss tr` becomes `gnss track ` and Tab again lists `start  stop`; `key ` lists its eleven names; `upd` becomes `update ` and lists `check  list  status  install` |
+| `ls` with a pattern | `ls /gt/*.txt` the five files, `ls /gt/*2*` the one, `ls /gt3/*6?.txt` ten of seventy. `ls /g*/x`: refused, a pattern goes in the last part |
+| `cp /gt/file-000?.txt /gt2`, `du /gt2/*1*` | Five copies; one size |
+| `rm /gt2/*` in the Shell | "The 5 that match /gt2/\*": Cancel leaves the five. `rm /gt3/*6?.txt`, Delete: ten gone, sixty left. `rm -f /gt2/*`: gone without a question |
+| `rm /gt/*` where one match is a folder | The files go, the folder stays (no `-r`) |
+| No match, and seventy | `rm: error nothing matches`; `rm: error more than 64 match: a narrower pattern, please`, and all seventy still there |
+| `No`, Tab, Enter | Completes to `Notes ` and opens Notes. `Shell` from the Debug Console opens the Shell |
+| `screenshot 4`, then Home | The picture, taken four seconds later, is of the Launcher: the pause works, and the Toast isn't in it |
+| `quit` | Back to the Launcher, and the memory comes back |
+| The help panel in the Shell | Its keys, then the ones that work everywhere |
+
+**Not checked:** Ctrl+b and the Alt scroll, which `key` can't press (no modifiers): the filter itself is host-tested, the key that flips it is not; the real keyboard altogether; the Toast after a screenshot, which was published but not looked at; and `mv` with a pattern and `cancel` in the middle of a line-up, which share their code with `cp` and `rm` but were not run. The main loop's lowest free stack after all of it: 1.8 KB, where it was.

docs/milestones/U1.md

@@ -0,0 +1,46 @@
+# U1 — Look and feel
+
+**Status:** in progress. The help key (issue #69) is merged; the website's key tables generated from the same lists (issue #72) are in a pull request. Screen recording (#17) and the rest of the milestone are not started.
+
+**Goal:** the interface is consistent and uncrowded: the same thing is done the same way on every screen, and the 135 pixels of height go to content.
+
+## The help key (issue #69)
+
+Every screen used to say something about its keys, differently: a footer of abbreviations in one place (`c x v:paste r:name d:del n:new i:info s:sort`), a line under a text field in another (`Enter: save   \`: cancel`), `Tab: sky` in a corner, and nothing at all in several. About 30 such strings, each costing a line of a small screen, and none of them complete.
+
+### Decisions (design round 2026-10-07)
+
+| # | Decision |
+|---|---|
+| Q196 | **Fn+h, on every screen,** text fields included (Fn is held, so nothing is typed). **`?` too, outside Text Entry.** |
+| Q197 | It opens **a panel over the content area**, titled with where you are: the screen's own keys, then an "Everywhere" group (Back, Home, the arrows, the help key). The arrows scroll it; any other key closes it and is not passed on. |
+| Q198 | **Each App answers "what are your keys right now?"** for the state it is in; pages, viewers, dialogs and text fields answer for themselves, with shared lists for dialogs, lists and text entry. The lists are constants; the panel's rows exist only while it is open. |
+| Q199 | **Every hint that names a key goes,** text fields included. What stays is state: `REC 12 points`, `LOG 42`, `sort:signal`, `typing`/`saved`, what is waiting to be pasted, the Sweep's floor. Messages were reworded where they named a key ("v pastes a copy of…" is "Copied …: paste it where you like"). |
+| Q200 | **The first-start Setup keeps its hints,** and is the one place that does: someone in their first minute doesn't know the help key yet. It tells them about it on its first and last screens. |
+| Q201 | **Loud everywhere else:** the user guide opens with it, the FAQ has it first, and a device set up before this firmware gets one Toast, once: "Fn+h: the keys of any screen". |
+| Q202 | `key help` over the consoles. Generating the website's key tables from the same lists is a follow-up, not this issue. |
+| Q203 | The key and the panel first, host-tested; then one App at a time, declaring its keys and losing its hints in the same step; then every screen looked at on the device. |
+
+### As built
+
+- **`Key::Help`** from the key mapper: Fn+h in both modes, `?` only outside Text Entry (`lib/input`, 3 tests).
+- **`App::help()` and `App::helpTitle()`** (`lib/core/src/app.h`), `KeyHelp` rows and `HelpModel` (`key_help.h`). The **App manager** opens the panel, appends the "Everywhere" group, and while it is open takes every key: nothing reaches the App, Home included. It closes when the App changes (5 tests).
+- **Every App declares its keys by state:** the Launcher, IRC (chat, settings, a field), Wi-Fi Tools (4 views), GNSS, Gemini (page, saved page, address, answer, dialogs), the LoRa Scanner (4 views), Storage (browse, details, a name, the viewer's 6 modes, the editor, Maintenance, busy), Notes (list, editor, a file name), System (5 views), Settings (menu, text, choice, and the Wi-Fi, Firmware and Debug Console pages with their own states), Setup and the widget demo.
+- **The hints are gone** from all of them. The footers that remain say state only.
+- **It costs** 8.5 KB of flash and 40 bytes of static RAM.
+
+### Checks
+
+| Check | Result |
+|---|---|
+| Host tests | 476 pass (468 before) |
+| On the device, `key help` and a screenshot | The Launcher and all nine Apps, and these states: Storage scrolled, System's tasks, a Settings text field, Wi-Fi Tools' networks. The panel is titled with the scope, lists the right keys, scrolls, and closes on Tab |
+| The one-time Toast | `notification: Fn+h: the keys of any screen` on the first start after the update |
+
+### One source for the device and the website (issue #72)
+
+The lists first lived in each App's `help()`, as code. They are now **data, in one file**: `lib/core/src/app_keys.h`, 52 constant tables, each under a comment `// id: Title`. An App's `help()` picks the table of the state it is in. `site/tools/gen_dev_docs.py` reads the same file and writes `site/data/keys.toml`; the `keys` shortcode shows a screen's tables on its guide page, and `/guide/keys/` shows all of them. The Site job fails when the data file is out of date, or when a page asks for a table that doesn't exist, and it now runs when `app_keys.h` changes. A key added to an App shows up on the website without anyone editing a page.
+
+Three rows lost their second wording on the way, since a table is constant: GNSS's `Tab` and `r`, and the Scanner's `c`, now say both things they do ("record a Track, or stop it") instead of the one that applies. The guide pages keep their written tables too, where they say more than a key list can; those can still drift, and the generated ones under them are the reference.
+
+**Not checked:** the real Fn+h and `?` on the keyboard (the mapper is host-tested; the device was driven with `key help`); the Setup screens, which only a device that was never set up shows, so their new text has not been seen on a screen; and the states that need something to happen first (a dialog, a copy in progress, a Gemini prompt, a packet's details): their lists were read against the key handling, not looked at.

docs/milestones/W1.md

@@ -21,7 +21,7 @@ The home page was designed on a canvas in a Claude chat (a dark and a light them
 | Q175 | The site lives in this repository, in `site/`, so the documentation is built from `docs/`, `CONTEXT.md` and the README instead of being copied. |
 | Q176 | **Zola,** like the blog. The design becomes a template, its tokens CSS custom properties. Dark and light follow the visitor's setting, with a visible switch. No JavaScript except the flasher's. |
 | Q177 | Domain: **roro9stack.net.** The blog stays at experiments.twis.la. |
-| Q178 | **Publishing is the blog's way:** the web server pulls `main` and runs `zola build`; that part is the maintainer's. Changes reach `main` through pull requests as everywhere. **CI is split:** a dedicated `site` job builds the site (`zola build`) when `site/`, `docs/`, `README.md` or `CONTEXT.md` change, and the firmware tests and builds skip a change that touches nothing else. A change that touches both runs both. |
+| Q178 | **Publishing is the blog's way:** the web server pulls `main` and runs `zola build`; that part is the maintainer's. *(Since issue #79, CI asks the server to do it: see "Published by CI" below.)* Changes reach `main` through pull requests as everywhere. **CI is split:** a dedicated `site` job builds the site (`zola build`) when `site/`, `docs/`, `README.md` or `CONTEXT.md` change, and the firmware tests and builds skip a change that touches nothing else. A change that touches both runs both. |
 | Q179 | Phases, each its own pull request: **1.** the CI split, the home page, an Install page with the browser flasher, downloads and the changelog. **2.** a user guide page per App. **3.** how-tos and the FAQ. **4.** developer docs generated from the repository. |
 | Q180 | **A browser flasher** (ESP Web Tools), **without copying the firmware.** Caddy, in front of Gitea, adds `Access-Control-Allow-Origin: https://roro9stack.net` (and `Vary: Origin`) to GET and HEAD on `/twisla/roro9stack/releases/download/*` and `/api/v1/repos/twisla/roro9stack/releases*`: both are public already. The Install page asks the API for the latest release in the browser, finds the asset ending `-factory.bin`, and gives ESP Web Tools a manifest built on the spot, so it offers a new release as soon as it exists, with no rebuild. The library is **vendored** into `site/static/` (Apache-2.0), not loaded from a CDN. The file's SHA-256 is shown on the page. Chrome or Edge on a desktop only; other browsers, and visitors without JavaScript, get the `esptool` steps on the same page. |
 | Q181 | Docs for the latest version only. The changelog is the Gitea releases, read at build time. |
@@ -125,3 +125,46 @@ Not one of the planned phases: the blog's seven roro9stack posts, imported into
 - **Left out on purpose:** the M0 and M1 milestone documents and `CONTEXT.md` (the glossary) describe Wi-Fi monitoring, which the site does not publish. They stay in the repository.
 - **The Debug Console pages were written against the source and the live console:** the protocol (the token line, the banner, the 4 KB backlog, one client, 8 queued commands, 240-byte lines, `denied` after a second) and the replies shown were checked on a Debug Build, v0.11.0-3, over Wi-Fi. Not run: `crash abort`, `crash wdt` and Safe Mode, which are described from ADR 0005 and the code.
 - **Found while writing it:** the README's table lacked the `gnss` commands (rows added); piping commands into `rdbg.py` returns before the replies unless the input stays open (documented, not changed); `update install` on a Debug Build needs `force` (documented).
+
+## Published by CI (issue #79, design round 2026-10-07)
+
+Q178 left publishing to the maintainer: a merge, then a command typed on the web server. It was forgotten often enough.
+
+| # | Decision |
+|---|---|
+| Q214 | **A plain ed25519 key with a forced command**, not a certificate: one line in the web server user's `authorized_keys`, `restrict,command="/full/path/to/the/refresh"`. `restrict` takes away the terminal and every forwarding. A certificate could carry the same and an expiry date, at the price of a CA to keep and a key to sign again each time: too much for one key and one command. |
+| Q215 | **The CI sends no command.** The server runs the forced one whatever is asked for, so there is nothing to keep secret about it and nothing a leaked key could choose. The full path is written once, on the server (a command over SSH doesn't get the user's login `PATH`). |
+| Q216 | Four secrets: `SITE_DEPLOY_KEY`, `SITE_DEPLOY_HOST` (or `host:port`), `SITE_DEPLOY_USER`, and **`SITE_DEPLOY_KNOWN_HOSTS`**, the server's host key: the job connects to that server or to nothing. None of them is in the repository, which is public. |
+| Q217 | `from="<the runner's address>"` on the same line: the key works from the runner only. |
+| Q218 | **The last step of the Site workflow**, after the build and the checks, on a push to `main` only. A pull request never reaches it, and the secrets are given to that step alone. |
+| Q219 | **After a release too.** The Install page asks Gitea for the latest release when it is opened, but the home page and Downloads read it when the site is built: so the release workflow refreshes the site once the release is published. |
+| Q220 | A refresh that fails makes the run red, with what the server's script printed: it has to exit with an error when it fails. |
+| Q221 | Two refreshes at once are the server script's to refuse or queue (`flock`). |
+| Q222 | The key is a file only while the step runs, in the job's container, as the signing key is. |
+
+### As built
+
+- **`scripts/site_refresh.sh`** is what both workflows run: it writes the key and the host key to a temporary folder, connects with no configuration but its own line (`-F none`, strict host key checking, that one key, no command), and removes them. With none of the four secrets it does nothing and says so (a fork, or a repository without them); with only some it fails.
+- **`scripts/site_deploy_keygen.sh`** makes the key pair once, in `~/.config/roro9stack/`, and prints the `authorized_keys` line and what goes in each secret. It never prints the private key.
+- **The server's script** should start like this, for Q220 and Q221:
+
+  ```sh
+  #!/bin/sh
+  set -e
+  exec 9>/tmp/rororefresh.lock
+  flock -w 120 9
+  ```
+
+### Checks (2026-10-07, against an SSH server in a throwaway container)
+
+| Check | Result |
+|---|---|
+| The refresh | The forced command runs as the server's user; the script ends with `site refresh: done` |
+| The same key, asking for `id; cat /etc/passwd` | The refresh runs instead; what was asked for is only handed to it as text |
+| A terminal | Refused: `PTY allocation request failed` |
+| `scp` with the key | Nothing is copied |
+| Another host key in the secret | `Host key verification failed`, the run fails, nothing is sent |
+| The server's script exits with an error | So does the step |
+| No secrets at all; only one of the four | Does nothing and says so; fails and says which are needed |
+
+**Not checked:** the real web server and the runner, which wait for the key to be installed: whether the runner reaches the server's SSH port is the first thing the first run will tell. Port forwarding, which `restrict` switches off, was not tried. `from=` was not tried either.

lib/apps_model/src/shell_log.cpp

@@ -0,0 +1,171 @@
+#include "shell_log.h"
+
+#include <algorithm>
+
+namespace roro {
+
+void ShellLog::push(const std::string& line) {
+    lines_.push_back(line);
+    bytes_ += line.size() + 1;
+    while (bytes_ > kMaxBytes && lines_.size() > 1) {
+        bytes_ -= lines_.front().size() + 1;
+        lines_.pop_front();
+    }
+    revision_++;
+}
+
+void ShellLog::add(const std::string& line) { push(line); }
+
+void ShellLog::feed(const char* data, size_t len) {
+    for (size_t i = 0; i < len; i++) {
+        char c = data[i];
+        if (c == '\r') continue;
+        if (c != '\n') {
+            if (partial_.size() < 512) partial_ += c;  // a line that never ends doesn't take the heap
+            continue;
+        }
+        if (partial_.rfind("status: heap ", 0) != 0) push(partial_);
+        partial_.clear();
+    }
+}
+
+void ShellLog::clear() {
+    lines_.clear();
+    partial_.clear();
+    bytes_ = 0;
+    revision_++;
+}
+
+namespace {
+
+bool isWord(const std::string& w) {
+    if (w.empty()) return false;
+    for (size_t i = 0; i < w.size(); i++) {
+        bool small = w[i] >= 'a' && w[i] <= 'z', capital = w[i] >= 'A' && w[i] <= 'Z';
+        if (!(small || (i == 0 && capital))) return false;
+    }
+    return true;
+}
+
+std::vector<std::string> split(const std::string& text, const std::string& by) {
+    std::vector<std::string> out;
+    size_t at = 0;
+    for (;;) {
+        size_t next = text.find(by, at);
+        out.push_back(text.substr(at, next == std::string::npos ? std::string::npos : next - at));
+        if (next == std::string::npos) return out;
+        at = next + by.size();
+    }
+}
+
+// The words a command can have at `index`, given the `index` words before it: added to `out`.
+void nextWords(const std::string& command, const std::vector<std::string>& before, size_t index, std::vector<std::string>& out) {
+    std::vector<std::string> tokens;
+    for (auto& t : split(command, " "))
+        if (!t.empty()) tokens.push_back(t);
+    for (size_t i = 0; i < tokens.size(); i++) {
+        std::vector<std::string> either = split(tokens[i], "|");  // on|off: either of them
+        bool words = true;
+        for (auto& w : either) words = words && isWord(w);
+        if (!words) return;  // an <argument>, an [option], "...": the command's words end here
+        if (i == index) {
+            for (auto& w : either)
+                if (std::find(out.begin(), out.end(), w) == out.end()) out.push_back(w);
+            return;
+        }
+        if (std::find(either.begin(), either.end(), before[i]) == either.end()) return;  // another command
+    }
+}
+
+}  // namespace
+
+std::string completeWords(const std::string& typed, const char* helpText, std::vector<std::string>& matches) {
+    matches.clear();
+    std::vector<std::string> words = split(typed, " ");
+    for (size_t i = 0; i + 1 < words.size(); i++)
+        if (words[i].empty()) return typed;  // two spaces: not ours to guess
+    const std::string last = words.back();
+    words.pop_back();
+    if (words.empty() && last.empty()) return typed;
+
+    std::vector<std::string> next;
+    for (auto& line : split(helpText ? helpText : "", "\n")) {
+        std::string commands = line.substr(0, line.find("   "));  // the description starts at three spaces
+        for (auto& command : split(commands, " | ")) nextWords(command, words, words.size(), next);
+    }
+    for (auto& w : next)
+        if (w.rfind(last, 0) == 0) matches.push_back(w);
+    if (matches.empty()) return typed;
+
+    std::string common = matches[0];
+    for (auto& m : matches) {
+        size_t n = 0;
+        while (n < common.size() && n < m.size() && common[n] == m[n]) n++;
+        common.resize(n);
+    }
+    std::string head = typed.substr(0, typed.size() - last.size());
+    if (matches.size() == 1) {
+        matches.clear();
+        return head + common + " ";
+    }
+    return head + common;
+}
+
+namespace {
+
+char lower(char c) { return c >= 'A' && c <= 'Z' ? static_cast<char>(c - 'A' + 'a') : c; }
+
+bool startsWithNoCase(const std::string& name, const std::string& prefix) {
+    if (name.size() < prefix.size()) return false;
+    for (size_t i = 0; i < prefix.size(); i++)
+        if (lower(name[i]) != lower(prefix[i])) return false;
+    return true;
+}
+
+bool takesAPath(const std::string& command) {
+    static const char* const kCommands[] = {"ls", "du", "mkdir", "rm", "cp", "mv", "cat", "install"};
+    for (auto c : kCommands)
+        if (command == c) return true;
+    return false;
+}
+
+}  // namespace
+
+bool splitForPath(const std::string& typed, PathToComplete& out) {
+    size_t space = typed.rfind(' ');
+    if (space == std::string::npos) return false;  // still the command's own word
+    std::string word = typed.substr(space + 1);
+    if (!word.empty() && word[0] == '-') return false;  // a switch
+    if (word.empty() || word[0] != '/') {
+        if (!takesAPath(typed.substr(0, typed.find(' ')))) return false;
+        word = "/" + word;
+    }
+    size_t slash = word.rfind('/');
+    out.head = typed.substr(0, space + 1);
+    out.folder = word.substr(0, slash + 1);
+    out.prefix = word.substr(slash + 1);
+    return true;
+}
+
+std::string completePath(const PathToComplete& what, const std::vector<std::string>& names, std::vector<std::string>& matches) {
+    matches.clear();
+    for (auto& n : names)
+        if (startsWithNoCase(n, what.prefix)) matches.push_back(n);
+    if (matches.empty()) return what.head + what.folder + what.prefix;
+    std::string common = matches[0];
+    for (auto& m : matches) {
+        size_t n = 0;
+        while (n < common.size() && n < m.size() && lower(common[n]) == lower(m[n])) n++;
+        common.resize(n);
+    }
+    if (matches.size() == 1) {
+        bool folder = !common.empty() && common.back() == '/';
+        matches.clear();
+        return what.head + what.folder + common + (folder ? "" : " ");
+    }
+    // Several: never shorter than what was typed (cases may differ past the prefix).
+    if (common.size() < what.prefix.size()) common = what.prefix;
+    return what.head + what.folder + common;
+}
+
+}  // namespace roro

lib/apps_model/src/shell_log.h

@@ -0,0 +1,65 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <deque>
+#include <string>
+#include <vector>
+
+namespace roro {
+
+// What the Shell App shows (issue #67): the lines it was given, with the oldest dropped past a size.
+// Which lines it is given is the console's business: by default, only what is printed for the
+// Shell's own commands (Console::Origin).
+class ShellLog {
+   public:
+    static constexpr size_t kMaxBytes = 4096;
+
+    // Bytes as the console printed them: lines may arrive in pieces. The line with the free heap
+    // every ten seconds is never kept: it would push everything else off a ten-line screen.
+    void feed(const char* data, size_t len);
+    // A line the Shell adds itself.
+    void add(const std::string& line);
+
+    const std::deque<std::string>& lines() const { return lines_; }
+    void clear();
+    uint32_t revision() const { return revision_; }  // changes when the lines do
+
+   private:
+    void push(const std::string& line);
+
+    std::deque<std::string> lines_;
+    std::string partial_;
+    size_t bytes_ = 0;
+    uint32_t revision_ = 0;
+};
+
+// Tab on a command (issue #67): every word of it, read from the firmware's `help` text each time it
+// is asked, so nothing is kept in memory for it. A line of that text is commands, three spaces, then
+// what they do; commands are separated by " | ", a word like on|off is either of them, and a command
+// stops being words at its first <argument>, [option] or "...":
+//     lora rx on|off | lora preset <name>   the radio
+// gives "lora rx on", "lora rx off" and "lora preset". An App's name starts with a capital.
+//
+// The line with its last word completed as far as the commands that fit agree; a word completed
+// whole gets a space after it. `matches` gets the candidates when there are several. Unchanged, with
+// no matches, when no command goes on that way: then it may be a path (below).
+std::string completeWords(const std::string& typed, const char* helpText, std::vector<std::string>& matches);
+
+// Tab on a later word: a path on the SD card (issue #67). What is being completed, taken apart:
+// `rm -r /notes/sh` is head "rm -r ", folder "/notes/", prefix "sh". False when the cursor is still
+// on the first word, when the word is a switch (-r), or when it isn't a path and the command doesn't
+// take one. After a file command a path may be started without its slash: `cat no` is /no.
+struct PathToComplete {
+    std::string head, folder, prefix;
+};
+bool splitForPath(const std::string& typed, PathToComplete& out);
+
+// `names` are the folder's entries, a folder's with a slash at its end. The line with the path
+// completed as far as the entries that start with the prefix agree, whatever their case (the card
+// doesn't tell cases apart, so the name's own case is taken). A file completed whole gets a space
+// after it; a folder keeps its slash, to go on from. `matches` gets the candidates when there are
+// several. Unchanged when nothing matches.
+std::string completePath(const PathToComplete& what, const std::vector<std::string>& names, std::vector<std::string>& matches);
+
+}  // namespace roro

lib/core/src/app.h

@@ -2,7 +2,10 @@
 
 #include <cstdint>
 
+#include <vector>
+
 #include "key_event.h"
+#include "key_help.h"
 
 namespace roro {
 
@@ -25,6 +28,12 @@ class App {
     // True while the App is editing text: the arrow keys then type ; . , / and need Fn to move.
     virtual bool textEntryActive() const { return false; }
 
+    // The keys that work right now, for the help panel (Fn+h): the App's own, in the state it's
+    // in. Back, Home and the arrows are added for it. No screen names keys any other way.
+    virtual void help(std::vector<KeyHelp>& out) const { (void)out; }
+    // What the panel is titled with, when the App's name isn't enough ("Notes: editor").
+    virtual const char* helpTitle() const { return nullptr; }
+
     // Called every main-loop pass while in the foreground (e.g. to refresh live values).
     virtual void update(uint32_t nowMs) { (void)nowMs; }
 

lib/core/src/app_keys.h

@@ -0,0 +1,451 @@
+#pragma once
+
+#include <cstddef>
+#include <vector>
+
+#include "key_help.h"
+
+// Every key of every screen, as data (issues #69 and #72). The help panel (Fn+h) shows the table of
+// the state an App is in; site/tools/gen_dev_docs.py reads this file to write the website's key
+// tables, so the two can't drift.
+//
+// The format is read by that script, so keep it: a comment `// id: Title`, then one table,
+//     inline constexpr KeyHelp kName[] = {
+//         {"keys", "what they do"},
+//     };
+// with one row a line and plain string literals. `id` is what a guide page asks for.
+namespace roro::keys {
+
+template <size_t N>
+inline void add(std::vector<KeyHelp>& out, const KeyHelp (&rows)[N]) {
+    out.insert(out.end(), rows, rows + N);
+}
+
+// everywhere: Everywhere
+inline constexpr KeyHelp kEverywhere[] = {
+    {"`", "back"},
+    {"Fn `", "home, the Launcher"},
+    {"; . , /", "arrows (Fn+ while typing)"},
+    {"Fn h  ?", "these keys (? not typing)"},
+};
+
+// dialog: A question
+inline constexpr KeyHelp kDialog[] = {
+    {", /", "the other answer"},
+    {"Enter", "choose it"},
+    {"`", "cancel"},
+};
+
+// text: A text field
+inline constexpr KeyHelp kText[] = {
+    {"Enter", "save"},
+    {"`", "cancel"},
+    {"Del", "delete backwards"},
+    {"Fn , /", "move the cursor"},
+    {"opt ' e", "an accent: \xC3\xA9"},
+};
+
+// launcher: The Launcher
+inline constexpr KeyHelp kLauncher[] = {
+    {"; .", "up, down"},
+    {"Enter", "open the App"},
+};
+
+// setup: Setup, a step
+inline constexpr KeyHelp kSetup[] = {
+    {"Enter", "continue"},
+    {"`", "the step before"},
+};
+
+// setup-choice: Setup, a choice
+inline constexpr KeyHelp kSetupChoice[] = {
+    {"; .", "up, down"},
+    {"Enter", "choose it, next step"},
+    {"`", "the step before"},
+};
+
+// setup-text: Setup, a name
+inline constexpr KeyHelp kSetupText[] = {
+    {"Enter", "next step"},
+    {"`", "the step before"},
+    {"Del", "delete backwards"},
+    {"Fn , /", "move the cursor"},
+    {"opt ' e", "an accent: \xC3\xA9"},
+};
+
+// irc: IRC
+inline constexpr KeyHelp kIrc[] = {
+    {"Enter", "send the line"},
+    {"Tab", "the next buffer"},
+    {"Alt ; .", "scroll back, forward"},
+    {"Fn ; .", "lines you sent before"},
+    {"Fn , /", "move the cursor"},
+    {"Del", "delete backwards"},
+    {"/settings", "server, nick, passwords"},
+    {"/join #x", "join a channel"},
+    {"/part", "leave it"},
+    {"/msg nick", "a private chat"},
+    {"/me", "an action"},
+    {"/nick", "change your nick"},
+    {"/topic", "see or set the topic"},
+    {"/names", "who is there"},
+    {"/quit", "disconnect, and stay so"},
+    {"/raw", "a line as it is"},
+    {"`", "leave: IRC stays connected"},
+};
+
+// irc-settings: IRC settings
+inline constexpr KeyHelp kIrcSettings[] = {
+    {"; .", "up, down"},
+    {"Enter", "edit, switch, or save"},
+    {"`", "leave without saving"},
+};
+
+// irc-field: IRC, a setting
+inline constexpr KeyHelp kIrcField[] = {
+    {"Enter", "keep it"},
+    {"`", "cancel"},
+    {"Del", "delete backwards"},
+    {"Fn , /", "move the cursor"},
+};
+
+// wifi-tools: Wi-Fi Tools
+inline constexpr KeyHelp kWifiTools[] = {
+    {"; .", "up, down"},
+    {"Enter", "open"},
+};
+
+// wifi-networks: Networks nearby
+inline constexpr KeyHelp kWifiNetworks[] = {
+    {"; .", "up, down"},
+    {"Enter", "track its signal"},
+    {"s", "sort: signal, channel, name"},
+    {"o", "open networks only"},
+    {"h", "hide the hidden ones"},
+    {"w", "strong ones only"},
+    {"l", "log the scans to the card"},
+};
+
+// wifi-tracker: Signal tracker
+inline constexpr KeyHelp kWifiTracker[] = {
+    {"m", "clicks on or off"},
+};
+
+// gnss: GNSS
+inline constexpr KeyHelp kGnss[] = {
+    {"Tab", "the position, or the sky"},
+    {"r", "record a Track, or stop it"},
+};
+
+// gemini: Gemini, a page
+inline constexpr KeyHelp kGemini[] = {
+    {"Tab", "the next link"},
+    {"Aa Tab", "the link before"},
+    {"Enter", "follow the link"},
+    {"`  Del", "the page before"},
+    {"; .", "scroll"},
+    {"Space", "a page down"},
+    {", /", "sideways, in wide blocks"},
+    {"g", "type an address"},
+    {"b", "bookmark this page"},
+    {"s", "save the page to the card"},
+    {"S", "...with the pages it links to"},
+};
+
+// gemini-saved: Gemini, a Saved Page
+inline constexpr KeyHelp kGeminiSaved[] = {
+    {"Tab", "the next link"},
+    {"Aa Tab", "the link before"},
+    {"Enter", "follow the link"},
+    {"`  Del", "the page before"},
+    {"; .", "scroll"},
+    {"Space", "a page down"},
+    {", /", "sideways, in wide blocks"},
+    {"g", "type an address"},
+    {"b", "bookmark this page"},
+    {"r", "refresh this Saved Page"},
+    {"d", "delete this Saved Page"},
+};
+
+// gemini-address: Gemini, an address
+inline constexpr KeyHelp kGeminiAddress[] = {
+    {"Enter", "go there"},
+    {"`", "cancel"},
+    {"Del", "delete backwards"},
+    {"Fn , /", "move the cursor"},
+};
+
+// gemini-answer: Gemini, an answer to a page
+inline constexpr KeyHelp kGeminiAnswer[] = {
+    {"Enter", "send it"},
+    {"`", "cancel"},
+    {"Del", "delete backwards"},
+    {"Fn , /", "move the cursor"},
+};
+
+// lora: LoRa Scanner, the packets
+inline constexpr KeyHelp kLora[] = {
+    {"; .", "up, down"},
+    {"Enter", "the packet's details"},
+    {"p", "pick a Meshtastic preset"},
+    {"c", "start a Capture, or stop it"},
+    {"Tab", "the Sweep"},
+};
+
+// lora-packet: LoRa Scanner, a packet
+inline constexpr KeyHelp kLoraPacket[] = {
+    {"; .", "scroll"},
+    {"Enter", "back to the list"},
+};
+
+// lora-presets: LoRa Scanner, the presets
+inline constexpr KeyHelp kLoraPresets[] = {
+    {"; .", "up, down"},
+    {"Enter", "listen with this preset"},
+};
+
+// lora-sweep: LoRa Scanner, the Sweep
+inline constexpr KeyHelp kLoraSweep[] = {
+    {"Tab", "the Sniffer"},
+};
+
+// storage: Storage, a folder
+inline constexpr KeyHelp kStorage[] = {
+    {"; .", "up, down"},
+    {"Enter", "open the folder or the file"},
+    {", /", "a page up, down"},
+    {"c  x", "copy, cut"},
+    {"v", "paste here"},
+    {"r", "rename"},
+    {"d  Del", "delete, after asking"},
+    {"n", "a new folder"},
+    {"i", "details: size, date, type"},
+    {"s", "sort: name, date, size"},
+    {"m", "Maintenance: clean-up, erase"},
+    {"`", "the folder above"},
+};
+
+// storage-details: Storage, an item's details
+inline constexpr KeyHelp kStorageDetails[] = {
+    {"; .", "scroll"},
+    {"Enter", "back to the folder"},
+};
+
+// storage-name: Storage, a name
+inline constexpr KeyHelp kStorageName[] = {
+    {"Enter", "rename it, or make the folder"},
+    {"`", "cancel"},
+    {"Del", "delete backwards"},
+    {"Fn , /", "move the cursor"},
+};
+
+// storage-busy: Storage, while it copies or deletes
+inline constexpr KeyHelp kStorageBusy[] = {
+    {"`", "stop the copy or the delete"},
+};
+
+// maintenance: Storage, Maintenance
+inline constexpr KeyHelp kMaintenance[] = {
+    {"; .", "up, down"},
+    {"Enter", "open, or choose"},
+};
+
+// viewer-text: A file, as text
+inline constexpr KeyHelp kViewerText[] = {
+    {"; .", "a line up, down"},
+    {", /", "a page up, down"},
+    {"t  b", "the top, the end"},
+    {"e", "edit it (up to 16 KB)"},
+    {"Tab", "the file as hex, or back"},
+};
+
+// viewer-hex: A file, as hex
+inline constexpr KeyHelp kViewerHex[] = {
+    {"; .", "a line up, down"},
+    {", /", "a page up, down"},
+    {"t  b", "the top, the end"},
+    {"Tab", "the file as text, or back"},
+};
+
+// viewer-pcap: A Capture
+inline constexpr KeyHelp kViewerPcap[] = {
+    {"; .", "up, down"},
+    {"Enter", "the packet"},
+    {", /", "a page up, down"},
+    {"Tab", "the file as hex"},
+};
+
+// viewer-packet: A Capture's packet
+inline constexpr KeyHelp kViewerPacket[] = {
+    {"; .", "scroll"},
+    {"Enter", "back to the packets"},
+};
+
+// viewer-gpx: A Track
+inline constexpr KeyHelp kViewerGpx[] = {
+    {"Tab", "the file as text"},
+};
+
+// viewer-ota: An Update File
+inline constexpr KeyHelp kViewerOta[] = {
+    {"Enter", "install it, if it's genuine"},
+    {"Tab", "the file as hex"},
+};
+
+// notes: Notes, the list
+inline constexpr KeyHelp kNotes[] = {
+    {"; .", "up, down"},
+    {"Enter", "open the note"},
+    {", /", "a page up, down"},
+    {"n", "a new note"},
+    {"r", "rename its file"},
+    {"d  Del", "delete it"},
+    {"s", "sort: newest, or by name"},
+};
+
+// notes-editor: Notes, the editor
+inline constexpr KeyHelp kNotesEditor[] = {
+    {"Enter", "a new line"},
+    {"Del", "delete backwards"},
+    {"Tab", "two spaces"},
+    {"Fn ; . , /", "move the cursor"},
+    {"Alt Fn ; .", "a page up, down"},
+    {"Ctrl a  e", "start, end of the line"},
+    {"opt ' e", "an accent: \xC3\xA9"},
+    {"`", "done: it saves by itself"},
+};
+
+// notes-name: Notes, a file name
+inline constexpr KeyHelp kNotesName[] = {
+    {"Enter", "rename the file"},
+    {"`", "cancel"},
+    {"Del", "delete backwards"},
+    {"Fn , /", "move the cursor"},
+};
+
+// shell: Shell
+inline constexpr KeyHelp kShell[] = {
+    {"Enter", "run the line"},
+    {"Tab", "complete: a command, a path"},
+    {"* ?", "several files: /notes/*.txt"},
+    {"Fn ; .", "lines you typed before"},
+    {"Alt ; .", "scroll back, forward"},
+    {"Ctrl b", "your replies only, or all"},
+    {"Fn , /", "move the cursor"},
+    {"Del", "delete backwards"},
+    {"help", "every command"},
+    {"clear", "an empty screen"},
+    {"Notes", "an App, by its name"},
+    {"rm -rf", "delete without being asked"},
+    {"quit  `", "leave the Shell"},
+};
+
+// system: System, any view
+inline constexpr KeyHelp kSystem[] = {
+    {"Tab", "the next view"},
+    {"Aa Tab", "the view before"},
+};
+
+// system-tasks: System, the tasks
+inline constexpr KeyHelp kSystemTasks[] = {
+    {"Tab", "the next view"},
+    {"Aa Tab", "the view before"},
+    {"; .", "scroll"},
+    {"s", "sort: cpu, stack, name"},
+};
+
+// system-system: System, the system view
+inline constexpr KeyHelp kSystemSystem[] = {
+    {"Tab", "the next view"},
+    {"Aa Tab", "the view before"},
+    {"; .", "scroll"},
+};
+
+// settings: Settings
+inline constexpr KeyHelp kSettings[] = {
+    {"; .", "up, down"},
+    {"Enter", "edit, or open the page"},
+    {", /", "change a switch or a slider"},
+};
+
+// settings-choice: Settings, a choice
+inline constexpr KeyHelp kSettingsChoice[] = {
+    {"; .", "up, down"},
+    {"Enter", "choose it"},
+};
+
+// wifi: Settings, Wi-Fi
+inline constexpr KeyHelp kWifi[] = {
+    {"; .", "up, down"},
+    {"Enter", "open, or change"},
+    {", /", "switch Wi-Fi on or off"},
+};
+
+// wifi-servers: Settings, DNS and NTP
+inline constexpr KeyHelp kWifiServers[] = {
+    {"; .", "up, down"},
+    {"Enter", "edit"},
+    {", /", "Always use my DNS: on, off"},
+};
+
+// wifi-network: Settings, a saved network
+inline constexpr KeyHelp kWifiNetwork[] = {
+    {"; .", "up, down"},
+    {"Enter", "edit, or forget"},
+    {", /", "Automatic or Fixed"},
+};
+
+// wifi-status: Settings, the Wi-Fi status
+inline constexpr KeyHelp kWifiStatus[] = {
+    {"Enter", "back"},
+};
+
+// wifi-scan: Settings, adding a network
+inline constexpr KeyHelp kWifiScan[] = {
+    {"; .", "up, down"},
+    {"Enter", "choose this network"},
+};
+
+// wifi-name: Settings, a hidden network's name
+inline constexpr KeyHelp kWifiName[] = {
+    {"Enter", "next: the password"},
+    {"`", "cancel"},
+    {"Del", "delete backwards"},
+    {"Fn , /", "move the cursor"},
+};
+
+// firmware: Settings, Firmware
+inline constexpr KeyHelp kFirmware[] = {
+    {"; .", "up, down"},
+    {"Enter", "check, open, or install"},
+    {"c", "look for a newer release"},
+};
+
+// firmware-release: Settings, a release
+inline constexpr KeyHelp kFirmwareRelease[] = {
+    {"; .", "scroll"},
+    {"Enter", "install it"},
+    {"c", "check again"},
+};
+
+// firmware-older: Settings, older releases
+inline constexpr KeyHelp kFirmwareOlder[] = {
+    {"; .", "up, down"},
+    {"Enter", "its details"},
+    {"c", "read the list again"},
+};
+
+// debug-console: Settings, Debug Console
+inline constexpr KeyHelp kDebugConsole[] = {
+    {"; .", "up, down"},
+    {"Enter", "switch, or open"},
+    {", /", "switch the console on or off"},
+};
+
+// demo: The widget demo
+inline constexpr KeyHelp kDemo[] = {
+    {"; .", "up, down"},
+    {"Enter", "try the widget"},
+};
+
+}  // namespace roro::keys

lib/core/src/app_manager.cpp

@@ -1,5 +1,7 @@
 #include "app_manager.h"
 
+#include "app_keys.h"
+
 #include <cstring>
 
 namespace roro {
@@ -52,6 +54,22 @@ void AppManager::endModal() {
 }
 
 void AppManager::handleKey(const KeyEvent& event) {
+    if (help_.isOpen()) {  // scrolls or closes; nothing reaches the App, Home included
+        help_.onKey(event);
+        redraw_ = true;
+        return;
+    }
+    if (event.key == Key::Help) {
+        std::vector<KeyHelp> rows;
+        foreground_->help(rows);
+        rows.push_back({"Everywhere", nullptr});
+        keys::add(rows, keys::kEverywhere);
+        const char* scope = foreground_->helpTitle();
+        const char* app = foregroundTitle();
+        help_.open(scope ? scope : app ? app : "Launcher", std::move(rows));
+        redraw_ = true;
+        return;
+    }
     if (modal_) {
         foreground_->onKey(event);
         return;
@@ -64,6 +82,19 @@ void AppManager::handleKey(const KeyEvent& event) {
     if (!consumed && event.key == Key::Back) home();
 }
 
+std::string AppManager::commandFor(const char* id) {
+    std::string command;
+    for (const char* p = id; *p && *p != '-'; p++) command += *p;
+    if (!command.empty() && command[0] >= 'a' && command[0] <= 'z') command[0] = static_cast<char>(command[0] - 'a' + 'A');
+    return command;
+}
+
+const AppInfo* AppManager::byCommand(const std::string& command) const {
+    for (auto& info : apps_)
+        if (!info.hidden && commandFor(info.id) == command) return &info;
+    return nullptr;
+}
+
 const char* AppManager::foregroundTitle() const {
     for (auto& info : apps_)
         if (info.app == foreground_) return info.title;
@@ -77,6 +108,7 @@ bool AppManager::takeRedraw() {
 }
 
 void AppManager::switchTo(App& app) {
+    help_.close();  // an App opened from elsewhere (a Notification, a command): its keys, not the last one's
     if (&app == foreground_) return;
     foreground_->onExit();
     foreground_ = &app;

lib/core/src/app_manager.h

@@ -1,5 +1,6 @@
 #pragma once
 
+#include <string>
 #include <vector>
 
 #include "app.h"
@@ -34,9 +35,19 @@ class AppManager {
     void handleKey(const KeyEvent& event);
     void update(uint32_t nowMs) { foreground_->update(nowMs); }
 
+    // The command that opens an App from the consoles and the Shell (issue #67): its id with a
+    // capital letter, up to the first dash. "notes" is Notes, "wifi-tools" is Wifi. The capital says
+    // "an App", where every command of the firmware is in small letters.
+    static std::string commandFor(const char* id);
+    // The App that command names, among the ones the Launcher lists; nullptr if there's none.
+    const AppInfo* byCommand(const std::string& command) const;
+
     App& foreground() const { return *foreground_; }
     const char* foregroundTitle() const;  // nullptr for the Launcher
 
+    // The help panel (Fn+h): open, it takes every key, and the App sees none of them.
+    const HelpModel& help() const { return help_; }
+
     // True once after the screen needs redrawing (App switch, or the App asked for it).
     bool takeRedraw();
 
@@ -47,6 +58,7 @@ class AppManager {
     App& launcher_;
     App* foreground_;
     std::vector<AppInfo> apps_;
+    HelpModel help_;
     bool redraw_ = true;
     bool modal_ = false;
 };

lib/core/src/key_event.h

@@ -16,6 +16,7 @@ enum class Key : uint8_t {
     Home,
     Tab,
     Delete,
+    Help,  // Fn+h anywhere, or ? outside Text Entry: the keys of this screen (issue #69)
 };
 
 struct KeyEvent {

lib/core/src/key_help.h

@@ -0,0 +1,63 @@
+#pragma once
+
+#include <algorithm>
+#include <string>
+#include <vector>
+
+#include "key_event.h"
+
+// The help panel (issue #69, docs/milestones/U1.md): Fn+h on any screen lists the keys that work
+// there. Every App says what its keys are in the state it's in; nothing on a screen names keys.
+namespace roro {
+
+// One line of the panel: a key (or keys) and what it does. A line with no action is a heading.
+struct KeyHelp {
+    const char* keys;
+    const char* action;
+};
+
+
+// The panel itself: what it lists, and how far it's scrolled. The keys it takes while open are the
+// arrows; any other key closes it, and none reaches the App.
+class HelpModel {
+   public:
+    explicit HelpModel(int visibleRows = 8) : visible_(visibleRows) {}
+
+    void open(const std::string& title, std::vector<KeyHelp> rows) {
+        title_ = title;
+        rows_ = std::move(rows);
+        top_ = 0;
+        open_ = true;
+    }
+    void close() {
+        open_ = false;
+        rows_.clear();
+        rows_.shrink_to_fit();  // nothing is kept while it's closed
+    }
+    bool isOpen() const { return open_; }
+
+    void onKey(const KeyEvent& e) {
+        int last = std::max(0, static_cast<int>(rows_.size()) - visible_);
+        switch (e.key) {
+            case Key::Up: top_ = std::max(0, top_ - 1); break;
+            case Key::Down: top_ = std::min(last, top_ + 1); break;
+            case Key::Left: top_ = std::max(0, top_ - visible_); break;
+            case Key::Right: top_ = std::min(last, top_ + visible_); break;
+            default: close(); break;
+        }
+    }
+
+    const std::string& title() const { return title_; }
+    const std::vector<KeyHelp>& rows() const { return rows_; }
+    int top() const { return top_; }
+    int visibleRows() const { return visible_; }
+
+   private:
+    std::string title_;
+    std::vector<KeyHelp> rows_;
+    int top_ = 0;
+    int visible_;
+    bool open_ = false;
+};
+
+}  // namespace roro

lib/files/src/file_names.cpp

@@ -4,7 +4,7 @@
 
 namespace roro::files {
 
-const char* const kFirmwareFolders[] = {"/irc", "/wifi", "/updates", "/gnss", "/gemini", "/captures", "/notes"};
+const char* const kFirmwareFolders[] = {"/irc", "/wifi", "/updates", "/gnss", "/gemini", "/captures", "/notes", "/screenshots"};
 const size_t kFirmwareFolderCount = sizeof kFirmwareFolders / sizeof kFirmwareFolders[0];
 
 std::string parentOf(const std::string& path) {
@@ -96,4 +96,52 @@ bool looksLikeText(const uint8_t* data, size_t len) {
     return odd * 20 <= len;  // a stray control character or two is still text
 }
 
+RmArgs parseRm(const std::string& args) {
+    RmArgs out;
+    size_t at = 0;
+    while (at < args.size()) {
+        while (at < args.size() && args[at] == ' ') at++;
+        if (at >= args.size() || args[at] != '-') break;
+        size_t end = args.find(' ', at);
+        std::string flags = args.substr(at + 1, end == std::string::npos ? std::string::npos : end - at - 1);
+        bool known = !flags.empty();
+        for (char c : flags) known = known && (c == 'r' || c == 'R' || c == 'f');
+        if (!known) break;  // a name that starts with a dash
+        for (char c : flags) (c == 'f' ? out.force : out.recursive) = true;
+        at = end == std::string::npos ? args.size() : end;
+    }
+    out.path = at < args.size() ? args.substr(at) : "";
+    while (!out.path.empty() && out.path.back() == ' ') out.path.pop_back();
+    return out;
+}
+
+bool hasGlob(const std::string& text) { return text.find_first_of("*?") != std::string::npos; }
+
+bool globMatch(const std::string& pattern, const std::string& name) {
+    auto lower = [](char c) { return c >= 'A' && c <= 'Z' ? static_cast<char>(c - 'A' + 'a') : c; };
+    size_t p = 0, n = 0, star = std::string::npos, mark = 0;
+    while (n < name.size()) {
+        if (p < pattern.size() && (pattern[p] == '?' || lower(pattern[p]) == lower(name[n]))) {
+            p++;
+            n++;
+        } else if (p < pattern.size() && pattern[p] == '*') {
+            star = p++;  // try it as nothing first; come back here to let it take one more
+            mark = n;
+        } else if (star != std::string::npos) {
+            p = star + 1;
+            n = ++mark;
+        } else return false;
+    }
+    while (p < pattern.size() && pattern[p] == '*') p++;
+    return p == pattern.size();
+}
+
+bool splitGlob(const std::string& path, std::string& folder, std::string& pattern) {
+    size_t slash = path.rfind('/');
+    if (slash == std::string::npos) return false;
+    pattern = path.substr(slash + 1);
+    folder = slash == 0 ? "/" : path.substr(0, slash);
+    return hasGlob(pattern) && !hasGlob(folder);
+}
+
 }  // namespace roro::files

lib/files/src/file_names.h

@@ -39,4 +39,20 @@ FileKind kindOf(const std::string& name);
 bool opensAtEnd(const std::string& name);  // logs
 bool looksLikeText(const uint8_t* data, size_t len);
 
+// `rm`'s arguments, as Unix has them (issue #67): -r for a folder and what's in it, -f for no
+// question, alone or together (-rf, -fr, -r -f), then the path, which may hold spaces.
+struct RmArgs {
+    bool recursive = false, force = false;
+    std::string path;
+};
+RmArgs parseRm(const std::string& args);
+
+// Patterns in a path (issue #67): * for any run of characters, ? for one, in the last part of the
+// path only (/notes/*.txt, not /*/a.txt). Cases aren't told apart, as on the card.
+bool hasGlob(const std::string& text);
+bool globMatch(const std::string& pattern, const std::string& name);
+// "/notes/*.txt" taken apart: the folder ("/notes", or "/" at the top) and the pattern ("*.txt").
+// False if there's no pattern in it, or if the folder has one too.
+bool splitGlob(const std::string& path, std::string& folder, std::string& pattern);
+
 }  // namespace roro::files

lib/files/src/png_rgb332.cpp

@@ -0,0 +1,118 @@
+#include "png_rgb332.h"
+
+namespace roro::png {
+
+uint32_t crc32(uint32_t crc, const uint8_t* data, size_t len) {
+    crc = ~crc;
+    for (size_t i = 0; i < len; i++) {
+        crc ^= data[i];
+        for (int bit = 0; bit < 8; bit++) crc = (crc >> 1) ^ (0xEDB88320u & (0u - (crc & 1)));
+    }
+    return ~crc;
+}
+
+uint32_t adler32(uint32_t adler, const uint8_t* data, size_t len) {
+    uint32_t a = adler & 0xFFFF, b = adler >> 16;
+    for (size_t i = 0; i < len; i++) {
+        a = (a + data[i]) % 65521;
+        b = (b + a) % 65521;
+    }
+    return (b << 16) | a;
+}
+
+namespace {
+
+void be32(uint8_t* out, uint32_t v) {
+    out[0] = static_cast<uint8_t>(v >> 24);
+    out[1] = static_cast<uint8_t>(v >> 16);
+    out[2] = static_cast<uint8_t>(v >> 8);
+    out[3] = static_cast<uint8_t>(v);
+}
+
+size_t rawSize(int w, int h) { return static_cast<size_t>(w + 1) * h; }  // a filter byte before each row
+size_t idatSize(int w, int h) { return 2 + 5 + rawSize(w, h) + 4; }       // zlib header, block header, data, adler
+
+}  // namespace
+
+size_t Rgb332Writer::fileSize(int w, int h) {
+    return 8 + (12 + 13) + (12 + 768) + (12 + idatSize(w, h)) + 12;  // signature, IHDR, PLTE, IDAT, IEND
+}
+
+bool Rgb332Writer::put(const uint8_t* data, size_t len, bool inIdat) {
+    if (inIdat) crc_ = crc32(crc_, data, len);
+    return sink_(data, len);
+}
+
+bool Rgb332Writer::put32(uint32_t value, bool inIdat) {
+    uint8_t b[4];
+    be32(b, value);
+    return put(b, 4, inIdat);
+}
+
+bool Rgb332Writer::begin() {
+    if (w_ <= 0 || h_ <= 0 || rawSize(w_, h_) > 65535) return false;
+    static const uint8_t signature[] = {0x89, 'P', 'N', 'G', '\r', '\n', 0x1A, '\n'};
+    if (!sink_(signature, sizeof signature)) return false;
+
+    uint8_t ihdr[4 + 13] = {'I', 'H', 'D', 'R'};
+    be32(ihdr + 4, static_cast<uint32_t>(w_));
+    be32(ihdr + 8, static_cast<uint32_t>(h_));
+    ihdr[12] = 8;  // bits a pixel
+    ihdr[13] = 3;  // indexed colour
+    ihdr[14] = ihdr[15] = ihdr[16] = 0;
+    uint8_t word[4];
+    be32(word, 13);
+    if (!sink_(word, 4) || !sink_(ihdr, sizeof ihdr)) return false;
+    be32(word, crc32(0, ihdr, sizeof ihdr));
+    if (!sink_(word, 4)) return false;
+
+    // The palette: every RGB332 value is its own index, as scripts/rdbg.py expands them. Sixteen
+    // colours at a time: this runs on a task with a small stack.
+    be32(word, 768);
+    const uint8_t plteKind[] = {'P', 'L', 'T', 'E'};
+    if (!sink_(word, 4) || !sink_(plteKind, 4)) return false;
+    uint32_t plteCrc = crc32(0, plteKind, 4);
+    for (int first = 0; first < 256; first += 16) {
+        uint8_t piece[48];
+        for (int i = 0; i < 16; i++) {
+            int v = first + i;
+            piece[i * 3] = static_cast<uint8_t>((v >> 5) * 255 / 7);
+            piece[i * 3 + 1] = static_cast<uint8_t>(((v >> 2) & 7) * 255 / 7);
+            piece[i * 3 + 2] = static_cast<uint8_t>((v & 3) * 255 / 3);
+        }
+        plteCrc = crc32(plteCrc, piece, sizeof piece);
+        if (!sink_(piece, sizeof piece)) return false;
+    }
+    be32(word, plteCrc);
+    if (!sink_(word, 4)) return false;
+
+    // IDAT: a zlib stream of one stored block. Its length is known, so it can be written first.
+    size_t raw = rawSize(w_, h_);
+    be32(word, static_cast<uint32_t>(idatSize(w_, h_)));
+    if (!sink_(word, 4)) return false;
+    crc_ = 0;
+    const uint8_t head[] = {'I', 'D', 'A', 'T', 0x78, 0x01, 0x01, static_cast<uint8_t>(raw), static_cast<uint8_t>(raw >> 8),
+                            static_cast<uint8_t>(~raw), static_cast<uint8_t>(~raw >> 8)};
+    return put(head, sizeof head, true);
+}
+
+bool Rgb332Writer::row(const uint8_t* pixels) {
+    if (rows_ >= h_) return false;
+    rows_++;
+    const uint8_t filter = 0;  // none
+    adler_ = adler32(adler_, &filter, 1);
+    adler_ = adler32(adler_, pixels, static_cast<size_t>(w_));
+    return put(&filter, 1, true) && put(pixels, static_cast<size_t>(w_), true);
+}
+
+bool Rgb332Writer::end() {
+    if (rows_ != h_) return false;
+    if (!put32(adler_, true)) return false;
+    uint8_t word[4];
+    be32(word, crc_);
+    if (!sink_(word, 4)) return false;
+    static const uint8_t iend[] = {0, 0, 0, 0, 'I', 'E', 'N', 'D', 0xAE, 0x42, 0x60, 0x82};
+    return sink_(iend, sizeof iend);
+}
+
+}  // namespace roro::png

lib/files/src/png_rgb332.h

@@ -0,0 +1,38 @@
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <functional>
+
+// A PNG of the screen, written a row at a time with almost no memory (issue #67, Q209): 8-bit
+// indexed colour with the 256 colours of RGB332 as its palette, and the pixels stored, not
+// compressed (a "stored" deflate block), so there is nothing to compress with and nothing to buffer.
+// One block holds at most 65,535 bytes: enough for the 240 x 135 screen (32,535 with its row bytes).
+namespace roro::png {
+
+uint32_t crc32(uint32_t crc, const uint8_t* data, size_t len);      // running; start from 0
+uint32_t adler32(uint32_t adler, const uint8_t* data, size_t len);  // running; start from 1
+
+class Rgb332Writer {
+   public:
+    using Sink = std::function<bool(const uint8_t* data, size_t len)>;  // false: writing failed
+
+    Rgb332Writer(int width, int height, Sink sink) : w_(width), h_(height), sink_(std::move(sink)) {}
+
+    // The file's size, known before a byte is written.
+    static size_t fileSize(int width, int height);
+
+    bool begin();                      // false: too big for one block, or the sink refused
+    bool row(const uint8_t* pixels);   // `width` bytes, RRRGGGBB each
+    bool end();
+
+   private:
+    bool put(const uint8_t* data, size_t len, bool inIdat);
+    bool put32(uint32_t value, bool inIdat);
+
+    int w_, h_, rows_ = 0;
+    Sink sink_;
+    uint32_t crc_ = 0, adler_ = 1;
+};
+
+}  // namespace roro::png

lib/input/src/key_mapper.cpp

@@ -99,6 +99,20 @@ void KeyMapper::onChar(char c, const RawKeys& keys, std::vector<KeyEvent>& out)
                     return;
                 }
                 break;
+            case 'h':
+            case 'H':
+                if (keys.fn) {  // Fn+h: help, while typing too
+                    out.push_back(KeyEvent::of(Key::Help));
+                    return;
+                }
+                break;
+            case '?':
+                if (!textEntry_ && !keys.fn) {  // ? alone, when it wouldn't be typed
+                    out.push_back(KeyEvent::of(Key::Help));
+                    return;
+                }
+                if (keys.fn) return;
+                break;
             default:
                 if (keys.fn) return;  // other Fn combos are unassigned
                 break;

lib/input/src/key_mapper.h

@@ -23,7 +23,7 @@ struct RawKeys {
 
 // Turns keyboard state changes into logical KeyEvents: only newly pressed keys produce events;
 // Fn + ; . , / are arrows, and so are ; . , / alone when no text is being entered; ` is Back and
-// Fn + ` is Home; the Compose Key (opt) followed by an accent and a letter types the accented
+// Fn + ` is Home; Fn + h is Help anywhere, and so is ? when no text is being entered; the Compose Key (opt) followed by an accent and a letter types the accented
 // letter (opt ' e -> é).
 class KeyMapper {
    public:

lib/services/src/settings.cpp

@@ -44,6 +44,7 @@ const Definition kDefinitions[] = {
     {"check_updates", Kind::Bool, 1, nullptr, 0, 1},  // on: it only looks, and says so (R1, Q165)
     {"debug_on", Kind::Bool, 0, nullptr, 0, 1},  // off: nothing listens until the owner says so (Q189)
     {"debug_token", Kind::String, 0, "", 0, 64},  // empty, or a valid token
+    {"help_told", Kind::Bool, 0, nullptr, 0, 1},
 };
 static_assert(sizeof(kDefinitions) / sizeof(kDefinitions[0]) == static_cast<size_t>(Setting::Count),
               "every Setting needs a definition");

lib/services/src/settings.h

@@ -33,6 +33,7 @@ enum class Setting : uint8_t {
     CheckUpdates,     // bool: look for a newer release on Gitea once a day (R1, Q165)
     DebugConsole,     // bool: the Debug Console listens on Wi-Fi (ADR 0010, Q189: off unless switched on)
     DebugToken,       // string: its token, tidied (debug_auth.h); empty until the console is first switched on
+    HelpTold,         // bool: this device has been told about the help key once (issue #69, Q201)
     Count
 };
 

lib/version/src/version.cpp

@@ -0,0 +1,15 @@
+#include "version.h"
+
+// Written by scripts/version.py before each build; not in git.
+#if __has_include("version_generated.h")
+#include "version_generated.h"
+#endif
+#ifndef RORO_VERSION
+#define RORO_VERSION "unknown"
+#endif
+
+namespace roro {
+
+const char* versionString() { return RORO_VERSION; }
+
+}  // namespace roro

lib/version/src/version.h

@@ -1,14 +1,12 @@
 #pragma once
 
-#ifndef RORO_VERSION
-#define RORO_VERSION "unknown"
-#endif
-
 namespace roro {
 
 constexpr const char* kProductName = "roro9stack";
 
-// "roro9stack v0.1.0" — used on the boot screen and in About.
-inline const char* versionString() { return RORO_VERSION; }
+// "v0.1.0", from `git describe` (scripts/version.py): used on the boot screen and in About.
+// A function in one file, not a macro on every compiler command line: a new commit then recompiles
+// that one file, and everything else comes from the build cache (issue #74).
+const char* versionString();
 
 }  // namespace roro

scripts/site_deploy_keygen.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Creates the key CI uses to ask the web server for a site refresh, once (issue #79,
+# docs/milestones/W1.md), and says where each half goes. The private key stays in
+# ~/.config/roro9stack/ until it is pasted into the Gitea secret; it is never committed and this
+# script doesn't print it.
+#
+#   scripts/site_deploy_keygen.sh [/full/path/to/rororefresh.sh] [the runner's address]
+set -euo pipefail
+KEY="${RORO_SITE_DEPLOY_KEY:-$HOME/.config/roro9stack/site-deploy-key}"
+COMMAND="${1:-/full/path/to/rororefresh.sh}"
+FROM="${2:-}"
+
+if [ -e "$KEY" ]; then
+    echo "A site deploy key already exists at $KEY; not overwriting it." >&2
+else
+    mkdir -p "$(dirname "$KEY")"
+    ( umask 077; ssh-keygen -q -t ed25519 -N "" -C roro9stack-ci-site-refresh -f "$KEY" )
+fi
+
+options="restrict,command=\"$COMMAND\""
+[ -z "$FROM" ] || options="from=\"$FROM\",$options"
+
+cat <<TEXT
+
+1. On the web server, as the user that runs the refresh, add this one line to ~/.ssh/authorized_keys:
+
+$options $(cat "$KEY.pub")
+
+   restrict: no terminal, no forwarding of any kind. command=: whatever the client asks for, this
+   runs instead.$([ -n "$FROM" ] || printf '\n   Give the runner'"'"'s address as the second argument to add from="...": the key then works from there only.')
+
+2. In Gitea, the repository's Settings > Actions > Secrets:
+
+   SITE_DEPLOY_KEY          the whole of $KEY (the private key, with its BEGIN and END lines)
+   SITE_DEPLOY_HOST         the server's address as the runner reaches it, or address:port
+   SITE_DEPLOY_USER         that user's name
+   SITE_DEPLOY_KNOWN_HOSTS  the server's host key, one line, from a machine you trust the network of:
+                              ssh-keyscan -t ed25519 <address>            (or: -p <port> <address>)
+                            and compare it with the server's own:
+                              ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub   (on the server)
+                              ssh-keyscan -t ed25519 <address> | ssh-keygen -lf -   (here)
+
+3. Try it, from here, with the same four values in the environment:
+
+   SITE_DEPLOY_KEY="\$(cat $KEY)" SITE_DEPLOY_HOST=... SITE_DEPLOY_USER=... \\
+   SITE_DEPLOY_KNOWN_HOSTS="\$(ssh-keyscan -t ed25519 ... 2>/dev/null)" scripts/site_refresh.sh
+
+   (with from= set, this works from the runner's address only.) Then, to see that the key can do
+   nothing else:   ssh -i $KEY <user>@<address> id      must run the refresh, not \`id\`.
+
+Once the secret is in Gitea, the copy at $KEY can be deleted.
+TEXT

scripts/site_refresh.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Asks the web server to rebuild the site (issue #79, docs/milestones/W1.md). Run by CI after a push
+# to main that changed the site, and after a release is published (the home page and Downloads
+# name the latest release when they are built).
+#
+# It only connects: the server's authorized_keys line forces the one command this key may run, so
+# nothing sent from here chooses what happens there. From the environment (Gitea secrets):
+#   SITE_DEPLOY_KEY          the private key (scripts/site_deploy_keygen.sh makes it)
+#   SITE_DEPLOY_HOST         the server, or server:port
+#   SITE_DEPLOY_USER         the user there
+#   SITE_DEPLOY_KNOWN_HOSTS  the server's host key, as a known_hosts line: nothing else is trusted
+# With none of them set it does nothing (a fork, or before the key is installed); with only some, it fails.
+set -euo pipefail
+
+set_count=0
+for v in SITE_DEPLOY_KEY SITE_DEPLOY_HOST SITE_DEPLOY_USER SITE_DEPLOY_KNOWN_HOSTS; do
+    [ -z "${!v:-}" ] || set_count=$((set_count + 1))
+done
+if [ "$set_count" = 0 ]; then
+    echo "site refresh: no SITE_DEPLOY_* secrets here, nothing done"
+    exit 0
+fi
+if [ "$set_count" != 4 ]; then
+    echo "site refresh: SITE_DEPLOY_KEY, _HOST, _USER and _KNOWN_HOSTS are needed, and only $set_count of them are set" >&2
+    exit 1
+fi
+
+if ! command -v ssh >/dev/null; then
+    apt-get update -qq
+    apt-get install -y -qq --no-install-recommends openssh-client >/dev/null
+fi
+
+host="$SITE_DEPLOY_HOST" port=22
+case "$host" in
+    *:*) port="${host##*:}" host="${host%:*}" ;;
+esac
+
+# The key and the host key exist as files only while this runs, in a container that goes with the job.
+umask 077
+tmp="$(mktemp -d)"
+trap 'rm -rf "$tmp"' EXIT
+printf '%s\n' "$SITE_DEPLOY_KEY" > "$tmp/key"
+printf '%s\n' "$SITE_DEPLOY_KNOWN_HOSTS" > "$tmp/known_hosts"
+
+# -F none: no configuration but this line. -T and no command: the server's forced command runs.
+ssh -F none -T -p "$port" -i "$tmp/key" \
+    -o IdentitiesOnly=yes -o BatchMode=yes \
+    -o StrictHostKeyChecking=yes -o UserKnownHostsFile="$tmp/known_hosts" -o GlobalKnownHostsFile=/dev/null \
+    -o ConnectTimeout=20 -o ServerAliveInterval=15 -o ServerAliveCountMax=8 \
+    "$SITE_DEPLOY_USER@$host"
+echo "site refresh: done"

scripts/version.py

@@ -10,7 +10,15 @@ try:
 except Exception:
     version = "unknown"
 
-env.Append(CPPDEFINES=[("RORO_VERSION", '\\"%s\\"' % version)])  # noqa: F821
+# The version goes into one generated header, read by one file (lib/version/src/version.cpp). As a -D
+# on every command line it made each new commit recompile everything, and no build cache could help
+# (issue #74). Written only when it changes, so an unchanged version rebuilds nothing.
+import os
+
+_header = os.path.join(env.subst("$PROJECT_DIR"), "lib", "version", "src", "version_generated.h")  # noqa: F821
+_text = '#define RORO_VERSION "%s"\n' % version
+if not os.path.exists(_header) or open(_header).read() != _text:
+    open(_header, "w").write(_text)
 
 
 # Keep every build's ELF, named by version and the first 16 hex digits of its SHA-256 (the core dump

site/content/dev/_index.md

@@ -8,6 +8,6 @@ sort_by = "weight"
 eyebrow = "Developer docs"
 +++
 
-The firmware is open source (GPL-3.0) and lives on [Gitea](https://git.twis.la/twisla/roro9stack). It is built for one device, the M5Stack Cardputer ADV with the Cap LoRa-1262, and it is built to be **worked on without touching the device**: install a build over Wi-Fi, read its console, press its keys, take screenshots of it, copy files to and from its SD card, and fetch its crash dumps, all from a PC on the same network. The first section is about exactly that.
+The firmware is open source (GPL-3.0) and lives on [Gitea](https://git.twis.la/twisla/roro9stack). It is built for one device, the M5Stack Cardputer ADV with the Cap LoRa-1262, and it is built to be **worked on without touching the device**: install a build over Wi-Fi, read its console, press its keys, take screenshots of it, copy files to and from its SD card, and fetch its crash dumps, all from a PC on the same network. The first section is about exactly that. The same commands also run on the device itself, in the [Shell](/guide/shell/).
 
 Some of these pages are written by hand. The rest are **generated from the repository's own documents** (the decisions, the milestone plans, the README and the firmware's own `help` text), so they are never out of date: each says which file it comes from.

site/content/dev/build/build-and-test.md

@@ -22,7 +22,7 @@ This runs the host-side unit tests (`test/`, `native` environment), then builds
 
 `scripts/coverage.sh` runs the same tests with coverage counters and writes a line-by-line report to `.pio/coverage/index.html`. The badge above is its figure for `main`: the share of the lines of `lib/` that the host tests run. `lib/` is the logic that compiles on a PC; `lib/SD` (the card's driver) and `src/` (the Apps, the Services, everything that needs the device) have no host tests and aren't in that figure.
 
-The framework is rebuilt with the TLS settings in `platformio.ini` (`custom_sdkconfig`, ADR 0006), so the first build after a fresh checkout takes about 4 minutes; later builds take under a minute.
+The framework is rebuilt with the TLS settings in `platformio.ini` (`custom_sdkconfig`, ADR 0006), so the first build after a fresh checkout takes about 6 minutes; later builds take about 15 seconds when little has changed. The platform knows the framework is already rebuilt by `sdkconfig.defaults` in the project folder, which it writes and git ignores: delete it and the next build rebuilds the framework. CI keeps that file, a build cache and ccache in its volume (docs/milestones/R1.md).
 
 ## CI and releases
 

site/content/dev/debug/commands.md

@@ -19,24 +19,26 @@ net               bytes each network service has read and written since boot
 reboot            restart
 boot other        restart into the other app slot (manual Rollback)
 log level <0-5>   ESP-IDF log level (0 none ... 5 verbose)
-ls [folder] | du <path> | mkdir <path> | rm <path> | cp [-f] <from> <to> | mv [-f] <from> <to> | cancel   the SD card, with the Storage App's rules
+ls [folder] | du <path> | mkdir <path> | rm [-r] [-f] <path> | cp [-f] <from> <to> | mv [-f] <from> <to> | cancel   the SD card, with the Storage App's rules (rm -r for a folder; -f: the Shell doesn't ask; * and ? in a name: /notes/*.txt)
+screenshot [seconds]   the screen as a PNG in /screenshots on the card, now or after a pause
 lora probe | lora status | lora rx on|off | lora preset <name>   the LoRa radio, receive only
 lora capture start|stop   a LoRa Capture to /captures/lora (pcap, LoRaTap)
-lora sweep on [from MHz] [to MHz] [step kHz] | off | dump   RSSI across a band (863 870 100)
+lora sweep on [from MHz] [to MHz] [step kHz] | lora sweep off | lora sweep dump   RSSI across a band (863 870 100)
 lora custom <MHz> <BW kHz> <SF> <CR 5-8> <sync hex> [preamble]   e.g. 868.1 125 7 5 34 8 (LoRaWAN)
 gnss quiet on|off   pause the GNSS receiver while the LoRa radio listens (it costs the radio 8 dB)
 gnss status | gnss restart | gnss track start|stop | gnss nmea on|off | gnss send <sentence without $ and checksum>
 crash             the last crash: firmware, reason, task, backtrace
 coredump erase    forget the core dump in flash
-key <name|char>   press a key: up down left right select back home del tab space, or one character
+key <name|char>   press a key: up down left right select back home del tab space help, or one character
 wifi status | wifi add <ssid><TAB><password>
 wifi ip <ssid> dhcp | wifi ip <ssid> <address>/<prefix> [gateway]   a Saved Network's IP setting
 wifi dns <a> [b] | wifi dns always on|off | wifi ntp <a> [b]   DNS and NTP servers
 gemini get <url>  fetch a Gemini page and report header, size, certificate, heap
 irc start | irc stop | irc dump | irc say <buffer> <text>
 install <path.ota>   Update from SD
-update check | list | status | install <tag>   the project's releases on Gitea
+update check | update list | update status | update install <tag>   the project's releases on Gitea
 sd card | sd list | cat <path> | log <text> | burst | sound on|off | short | normal
+Irc | Wifi | Gnss | Gemini | Lora | Storage | Notes | Shell | System | Settings   open that App: a capital letter is an App, not a command
 debug status | debug off [seconds]   the Debug Console over Wi-Fi (Settings > Debug Console); with seconds, it comes back
 debug on | debug token <16 to 64 characters> | debug token new   (USB serial only) switch it on, set its token
 crash abort|wdt   crash on purpose (to test crash reports and Safe Mode)
@@ -47,7 +49,7 @@ lora inject <hex> [rssi] [snr]   a packet into the LoRa Scanner as if received (
 sd fill <folder> <count>   makes that many small files there, to test a crowded folder
 coredump get      (Debug Console only) send the raw core dump: use scripts/rdbg.py coredump
 reset             (Debug Console only) restart at once, even if the main loop is stuck
-get <path> | put <path> <size> <sha256> | screenshot   (Debug Console only) binary, see rdbg.py
+get <path> | put <path> <size> <sha256> | screenshot   (Debug Console only) binary, see rdbg.py: there, a bare `screenshot` sends the screen instead of saving it
 quit              close the Debug Console connection
 ```
 
@@ -60,7 +62,7 @@ In **Safe Mode** (see [Crashes and Safe Mode](/dev/debug/crashes/)) only a few r
 | Command | Effect |
 |---|---|
 | `burst` | Publishes 5 Notifications at once |
-| `key up\|down\|left\|right\|select\|back\|home`, or `key <char>` | Injects a key press |
+| `key up\|down\|left\|right\|select\|back\|home\|del\|tab\|space\|help`, or `key <char>` | Injects a key press (`help` is Fn+h: the keys of the screen that is showing) |
 | `sound on` / `sound off` | Toggles the Sound setting (beep + LED) |
 | `short` / `normal` | Screen timeouts 5 s / 10 s, or 30 s / 60 s |
 | `wifi add <ssid><TAB><password>` | Adds a Saved Network (so credentials stay out of the repo) |
@@ -78,13 +80,15 @@ In **Safe Mode** (see [Crashes and Safe Mode](/dev/debug/crashes/)) only a few r
 | `irc say <buffer> <text>` | Types into a Buffer, commands included (`irc say 0 /join #test`) |
 | `irc dump` | Prints IRC status, memory, and the last lines of each Buffer |
 | `wifi status` | Prints Wi-Fi state, network, signal, clock and free heap, then the address, gateway, DNS and NTP servers in use and where each came from |
-| `info` | Firmware, uptime, last start reason, memory, Wi-Fi, the SD card and its write faults since boot, and both app slots with their versions and OTA states |
+| `info` | Firmware, uptime, last start reason, memory, Wi-Fi, the SD card and its write faults since boot, **which App is in front**, and both app slots with their versions and OTA states |
+| `Notes`, `Irc`, `Wifi`, `Gnss`, `Gemini`, `Lora`, `Storage`, `Shell`, `System`, `Settings` | Opens that App: a capital letter is an App, not a command |
 | `tasks` | FreeRTOS tasks over the next second: state, priority, lowest free stack, share of a core, each core's load, and how many passes the main loop made |
 | `net` | Bytes each network service has read and written since boot |
 | `reboot` / `boot other` | Restart, or restart into the other app slot (a manual Rollback) |
 | `log level <0-5>` | ESP-IDF log level |
 | `ls [folder]` / `du <path>` | Lists a folder of the SD card with sizes and dates, or counts the files and bytes under a path |
-| `cp [-f] <from> <to>` / `mv [-f] <from> <to>` / `rm <path>` / `mkdir <path>` / `cancel` | What the Storage App does, with its rules: copy (folders too), move or rename, delete (a folder with what's in it), new folder. `-f` replaces a file that's in the way; a tab separates paths that hold spaces; `cancel` stops a copy or a delete |
+| `screenshot [seconds]` | The screen as a PNG in `/screenshots` on the card, now or after a pause to get to the screen you want (240 x 135, about 33 KB). Over the Debug Console a bare `screenshot` sends the screen to the PC instead |
+| `cp [-f] <from> <to>` / `mv [-f] <from> <to>` / `rm [-r] [-f] <path>` / `mkdir <path>` / `cancel` | What the Storage App does, with its rules: copy (folders too), move or rename, delete (`rm -r` for a folder and what's in it, as Unix has it), new folder. `-f` replaces a file that's in the way; `*` and `?` in the last part of a path (`ls`, `du`, `rm`, `cp`, `mv`) run the command for each name matched, 64 at most; a tab separates paths that hold spaces; `cancel` stops a copy or a delete |
 | `install <path>` | Update from SD with that `.ota` file, as Settings → Firmware does |
 | `update check` / `update list` / `update status` / `update install <tag>` | The project's releases on Gitea: look at the latest, list the last ten, say what's known, or download and install one |
 | `update pretend <version>` / `update probe <host>` / `update damage cut\|flip <n>` / `update daily` | Pretend to run another version (so a release counts as an update), see whether a server's certificate is accepted, cut or damage the next download, run the daily check again |

site/content/dev/debug/drive-the-ui.md

@@ -11,7 +11,7 @@ Everything the keyboard can do, a command can do, and everything on the screen c
 ## Keys
 
 ```
-key up|down|left|right|select|back|home|del|tab|space
+key up|down|left|right|select|back|home|del|tab|space|help
 key a        # any single character: it is typed
 ```
 
@@ -22,6 +22,18 @@ Two things to know before you use them:
 
 `Fn` combinations, modifiers and the compose key have no command: the arrows are `key up|down|left|right`, and `key back` is the back key (`` ` `` on the device). Text is typed one character at a time.
 
+**`key help` opens the help panel** (<kbd>Fn</kbd>+<kbd>h</kbd> on the device): the keys of the screen that is showing. A screenshot of it is the quickest way to learn what a screen accepts, and it is how every screen's list was checked. Any key but the arrows closes it.
+
+## Open an App by its name
+
+```
+Notes        # an App's name, with a capital: opens it
+Shell        # Irc Wifi Gnss Gemini Lora Storage Notes Shell System Settings
+info         # ...and `app: Notes` says which App is in front
+```
+
+Far better than `key home`, some `key down` and `key select`: it doesn't depend on where the Launcher's selection was.
+
 ## Look before you press
 
 **Take a screenshot before any key that deletes, renames or installs.** A blind sequence of `key` commands goes wrong the moment the screen is not where you think it is, and the screen is often not where you think it is: a Toast, a dialog that has not closed, a different App. A sequence that was meant to open a note once renamed real data instead.
@@ -34,6 +46,7 @@ scripts/rdbg.py key select
 scripts/rdbg.py screenshot b.png  # look again before the next destructive step
 ```
 
+- **Check the App in front before typing anything.** `info` prints `app: <name>`. A crash restarts the device into the Launcher, and a script that goes on typing is typing somewhere else: one of this project's own test scripts sent a word to an IRC channel that way.
 - Prefer **reading a state** to assuming it: `info`, `ls <folder>`, `cat <file>`, `irc dump`, `gnss status`, `lora status`, `wifi status`, `update status`.
 - Test on a **scratch folder** on the card, not on your real files.
 - For anything that deletes (`rm`, a delete dialog), `ls` first and `ls` after.

site/content/dev/debug/files-and-screens.md

@@ -45,6 +45,7 @@ The device sends `screenshot: rgb332 <width> <height>` and then **one byte per p
 
 - It is read **as it stands**, while the UI may be drawing, so it can **tear**. It is for looking at, not for pixel-exact comparison.
 - It is the real thing: the screenshots on this site, in the [user guide](/guide/) and the [devlog](/devlog/), were taken this way.
+- **With a number, it saves to the card instead:** `screenshot 5` (or `screenshot 0`) writes a PNG to `/screenshots` on the SD card after that many seconds, as the [Shell](/guide/shell/) does. A bare `screenshot` over the console is the binary one above.
 - Its main use is in a loop: send a key, wait a moment, take a screenshot, look. See [Drive the UI](/dev/debug/drive-the-ui/).
 
 ## `coredump get`: the crash dump

site/content/dev/milestones/r1.md

@@ -180,3 +180,62 @@ The issue asked for a token that could be set, so that Debug Builds could be pub
 **One false alarm:** after the tests the console "wouldn't come back on". It was off: the setting had been left off by `debug off`, and the page's "Switch it on?" dialog opens on **Cancel**, so Enter twice leaves it off. Nothing was lost.
 
 **Not checked:** `scripts/flash.sh --debug` over USB (no device on USB here); "New token" and "Type a token" from the page (the code paths are the ones `debug token` uses, which need the cable); the Toast itself on screen (the console is closed while it shows; its Notification is in the log); free memory with the console off, which only the serial port could say (the static figures above are the evidence); fetching a release's ELF, which needs a crash on a released version.
+
+## CI that doesn't rebuild the world (issue #74)
+
+A pull request's run took over seven minutes, a tag's thirteen and a half. The goal: a firmware build under a minute.
+
+### Where the time went (run 81, a pull request, 2026-10-06)
+
+| Step | Time |
+|---|---|
+| Tools (apt, pip) | 15 s |
+| Check out | 2 s |
+| Host tests and coverage | 55 s |
+| **The firmware** | **358 s** |
+| of which: CMake configuring ESP-IDF | 87 s |
+| of which: compiling ESP-IDF's libraries | 171 s |
+| of which: our own build (the Arduino core, the libraries, `src/`) | 91 s |
+
+A tag's run did the firmware step, then built the same commit again for the release: twice 356 s.
+
+### Why the framework was rebuilt every time
+
+The framework is rebuilt with our SDK settings (ADR 0006), and the rebuilt libraries stay in the toolchain volume. But the platform decides whether they match by reading **`sdkconfig.defaults` in the project folder**, whose first line carries a hash of the settings. That file is generated, and not in git. A fresh checkout has none, so the platform concluded "different settings", **reinstalled the framework and rebuilt it**: 260 seconds, at every run, to arrive at the libraries that were already there. On a developer's machine the file is simply still there from the last build, which is why nobody saw it.
+
+### What changed
+
+| Change | Effect |
+|---|---|
+| **The file is kept in the volume, inside the libraries it describes** (`framework-arduinoespressif32-libs/.roro-sdkconfig.defaults`), copied into the checkout before a build and back after one that passed. The platform still checks its hash against `platformio.ini`: changed settings rebuild, as they must. Kept there and not beside them, it disappears when the libraries are reinstalled, so it can't describe libraries that are gone | 358 s to 92 s |
+| **The version is no longer a `-D` on every compiler command line.** `scripts/version.py` writes `lib/version/src/version_generated.h` (not in git, written only when it changes), read by one file. Before, every commit recompiled everything, on a developer's machine too, and no cache could have helped | A rebuild with nothing changed: 77 s to 13 s, locally |
+| **PlatformIO's build cache** (`PLATFORMIO_BUILD_CACHE_DIR`, SCons's CacheDir) in the volume, for the firmware of pull requests: objects by the signature of their sources and command line | 92 s to 26 s, with a new version and one changed file |
+| **ccache for the host tests.** They are built with coverage counters, and the build cache would return objects without their `.gcno` files; ccache keeps both | 49 s to 33 s. What's left is PlatformIO starting 51 test programs |
+| **A tag builds its firmware once**, in the release step | minus 6 minutes |
+| PlatformIO and gcovr in a virtual environment in the volume | a few seconds |
+
+**A release compiles its own sources from nothing:** it reuses the rebuilt framework (the platform checks the hash) but not the build cache, so no published file contains an object that came from another commit's build.
+
+### Measured (a development machine, fresh copies of the tree, the same volume)
+
+| | Before | After |
+|---|---|---|
+| The firmware, fresh checkout, nothing cached for it | 358 s | 82 s (it fills the cache) |
+| The firmware, fresh checkout, a new version and one file changed | 358 s | **27 s** |
+| Host tests and coverage | 49 s | 33 s |
+| Rebuilding locally with nothing changed | 77 s | 13 s |
+
+### Measured on the runner (pull request #76, 2026-10-07)
+
+| Run | Tools | Tests and coverage | The firmware | The whole job |
+|---|---|---|---|---|
+| Before (run 81) | 15 s | 55 s | 358 s | 434 s |
+| The first with the new workflow: no mark yet, the framework is rebuilt once more and the caches fill | 16 s | 59 s | 354 s | 431 s |
+| The next commit (only the workflow changed) | 10 s | 36 s | **51 s** | **100 s** |
+| The same commit again | 10 s | 36 s | **18 s** | **66 s** |
+
+In the 51-second run, 245 objects came from the cache and 43 were compiled: `version.cpp`, as expected, and all 42 files of `src/`, which had not changed. In the run after it, all 290 came from the cache. So the objects of `src/` made by the run that rebuilt the framework were not reusable by a normal run, and those of a normal run are: the two-pass build that rebuilds the framework compiles `src/` with something different on its command line. It costs one 51-second run after each framework rebuild, which is rare; I did not look for what differs.
+
+The firmware step with everything cached is 18 seconds: the libraries are downloaded and unpacked (4 s), the dependency scan (5 s), fetching 290 objects, the link and the image (the last 11 s). A pull request that changes a few files should land between that and 51 seconds.
+
+**What it costs:** the build cache grows by about 40 MB a run (each linked firmware is kept) and is started again past 3 GB; ccache is held to 1 GB.

site/content/dev/milestones/s1.md

@@ -144,3 +144,69 @@ M3 found the LoRa radio's noise floor about 15 dB above what the chip hears alon
 **Settings > Pause GNSS for LoRa**, off by default: while the LoRa radio listens or sweeps, the GNSS receiver waits in standby, and wakes when the radio goes back to sleep (a Fix again after about 7 s here). Never during a Track. The GNSS App says "GNSS is paused" meanwhile. `gnss quiet on|off` on the console.
 
 It's off by default because GNSS on by default was decided in M2 (Q58), and from M4 the radio listens all the time: then "pause while listening" means GNSS mostly off, which is a decision about position, the clock and Tracks, for M4's design round (issue #23).
+
+## The Shell (issue #67)
+
+The console's commands could only be typed on a PC: over USB, or over Wi-Fi with the Debug Console. A device in a bag, or on a network that is down, could not be asked anything. The Shell is an App that runs the same commands on the device's own screen and keyboard.
+
+### Decisions (design round 2026-10-07)
+
+| # | Decision |
+|---|---|
+| Q204 | **An App, "Shell", in the Launcher**, in every firmware: its commands already work over USB for anyone holding the device. |
+| Q205 | **Trusted like USB serial**, not like the network: `debug on` and `debug token` work from it, as they do in Settings. The token is never shown. |
+| Q206 | *Revised the same day, after trying it.* **It shows the replies to its own commands, and only those.** The console knows who each line is printed for (`Console::Origin`): a command run from the Shell prints as the Shell's, and so does what answers it later from another task, which notes who asked and takes it back when it prints (`ls`, `tasks`, `du`, `cp`, `update check`, `sd list`, `screenshot`, `gemini get`). What USB or the Debug Console asked for, and the system's own lines, are not the Shell's. **Ctrl+b shows everything** instead. The first version kept whatever was printed in the ten seconds after a command, which was a guess, and a noisy one. |
+| Q207 | **Nothing while it's closed.** Open, a 4 KB ring of the console's and up to 4 KB of lines; both go when the App is left, with the list of commands for Tab. |
+| Q208 | Enter runs the line; Fn with up and down recalls the last 16; Alt with up and down scrolls back. **Tab completes** the command, **every word of it** *(the first only, at first)*: `lora st` gives `lora status`, `gnss track ` lists `start  stop`, `key ` its eleven names. The words come from the firmware's `help` text, read as it is written, so a new command completes without a table to keep. *(Added the same day)* **past the command, a path on the SD card**: a folder keeps its slash to go on from, a file completed whole gets a space, several candidates are listed. Whatever the case typed, the name's own is taken, since the card doesn't tell them apart. After a file command the first slash is understood (`cat no` is `/no`). A name with a space in it isn't completed. |
+| Q209 | *Revised the same day.* **`rm` is Unix's, with a question.** A folder needs `-r`, here and over the consoles (where `rm <folder>` used to remove it with what was in it). In the Shell, a file, or a folder with something in it, is asked about unless `-f` (`-rf`, `-r -f`); an empty folder with `-r` goes without a word; what `rm` would refuse anyway, it refuses itself. Over the consoles nothing is asked: scripts delete as before. **`screenshot [seconds]`** saves the screen as a PNG in `/screenshots`, now or after a pause, since from the Shell "now" is the Shell. `get`, `put`, `coredump get` and `reset` answer `Debug Console only`. *(Added the same day)* **`*` and `?` in a name**, for `ls`, `du`, `rm`, `cp` and `mv`, here and over the consoles: `rm /notes/*.txt`, `cp /gnss/2026-10-0?.gpx /backup`. In the last part of the path only, any case, as the card has it. It is the same command once for each name matched, in the name's order; `cp` and `mv` then need a folder that exists to put them in. Over 64 matches is refused whole, as is none. In the Shell `rm` with a pattern asks **once**, with the count. |
+| Q210 | Commands are echoed as `> command` into the console, so a session reads the same from afar. **A token being set is not echoed.** |
+| Q211 | **Not in Safe Mode**, which starts no Apps: issue #77. |
+| Q212 | Its keys are a table in `app_keys.h`, so the help panel and the website have them; a page in the user guide. |
+| Q213 | *Added the same day.* **An App's name with a capital opens it:** `Irc`, `Wifi`, `Gnss`, `Gemini`, `Lora`, `Storage`, `Notes`, `Shell`, `System`, `Settings` (the App's id, up to its first dash). From the Shell, without going back to the Launcher, and from the consoles too. The capital says "an App": every command of the firmware is in small letters. Tab completes them. |
+
+### As built
+
+- **`ShellApp`** (`src/apps/shell_app.cpp`), with its model host-tested in `lib/apps_model/src/shell_log.h`: lines arriving in pieces, the 4 KB limit, the words of every command out of the `help` text (Apps' names included), and Tab.
+- **Who a line is for:** `Console::As` marks the calling task as printing for the Shell while it lives, and `Console::origin()` lets a command that answers later carry that to wherever it prints. The console has a second ring for the Shell, which gets the lines marked so, or everything.
+- **The Shell hands its lines to the main loop**, which runs them like the consoles' commands. See below for why.
+- **`info` says which App is in front** (`app: Shell`): so that a hand driving the device from afar can look before it types.
+- **`screenshot`** writes the PNG a row at a time with no buffer: 8-bit indexed colour, the 256 colours of RGB332 as the palette, the pixels in one stored deflate block (`lib/files/src/png_rgb332.h`, 4 tests). 33,383 bytes for the 240 x 135 screen. A Toast says so once it is on the card, so the Toast is never in the picture.
+- **The `help` text lost its shorthand** (`update check | list | status` is written out), since Tab reads its words from there: `|` between two commands, `on|off` between two words, three spaces before the description. The Shell's own words (`clear`, `quit`, `key`'s names) are added in the same notation.
+- **Tab on a path** reads the folder on the storage task while the main loop waits, so it is bounded: 400 entries looked at, 24 candidates given back, and `...` after the list when there were more.
+- **A pattern** is matched in `lib/files/src/file_names.h` (`globMatch`, host-tested), and the names it matches are lined up as so many commands, which the main loop runs one after the other as each finishes. `cancel` empties the line-up. 2000 entries looked at, 64 matches at most.
+- **Cost:** 21 KB of flash, 96 bytes of static RAM. Open: 7 KB of heap (107.6 KB free before, 100.7 with it open, 106.1 after leaving).
+
+### What went wrong while building it
+
+**The device crashed, and the test sent a message to an IRC channel.** The first version ran a command from inside the key handler. Driven from the Debug Console, that is: the main loop, a remote command, `key select`, the App manager, the Shell, `runCommand` a second time, the file command, and `printf` under all of it. The main loop has under 2 KB of stack to spare; `rm` on a folder went past it. The crash report decoded to exactly that chain.
+
+The device restarted into the Launcher, and the test script, which did not look, went on typing. Its next Enter opened IRC, which connected, and a few lines later it typed "No" into a channel and pressed Enter. One word, sent to real people, that can't be taken back.
+
+Two changes came of it. The Shell now **queues** its line and the main loop runs it, at the same stack depth as a console's command. And `info` reports the App in front, which the test script now checks before every line it types.
+
+### Checks on the device (2026-10-07, driven over the Debug Console with `key`)
+
+| Check | Result |
+|---|---|
+| Open it from the Launcher, type `ls /`, Enter | The folders are listed |
+| Tab on `in` | `info  install` is shown and the line stays; on `u` it becomes `update `; on `l`, `log  ls  lora  loop` |
+| Up | The line before comes back |
+| `screenshot` | `/screenshots/20261007-104357.png`, 33,383 bytes. Fetched and decoded on the PC: 240 x 135, indexed, every chunk's CRC right, the pixels the Shell's screen |
+| Output | With a Debug Console client connecting and disconnecting for every key, the Shell shows the commands and their replies and nothing else: `info`, `ls /` (answered by the storage task), `tasks` (answered a second later) |
+| `rm` on a folder, without `-r` | Refused, the folder stays |
+| `rm -r` on an empty folder | Removed, no question |
+| `rm -r` on a folder with files | Asks; Cancel leaves it. `rm -rf` removes it without asking |
+| `rm` on a file | Asks; Delete removes it |
+| Tab on a path | `ls /no` becomes `ls /notes/`, and again, with one note in it, the note's whole name and a space. `ls /g` lists `gemini/  gnss/`. `cat no` becomes `cat /notes/`. `rm -r /CAP` becomes `rm -r /captures/`. `ls /zz` stays as it is |
+| Tab past the first word | `lora st` becomes `lora status `; `gnss tr` becomes `gnss track ` and Tab again lists `start  stop`; `key ` lists its eleven names; `upd` becomes `update ` and lists `check  list  status  install` |
+| `ls` with a pattern | `ls /gt/*.txt` the five files, `ls /gt/*2*` the one, `ls /gt3/*6?.txt` ten of seventy. `ls /g*/x`: refused, a pattern goes in the last part |
+| `cp /gt/file-000?.txt /gt2`, `du /gt2/*1*` | Five copies; one size |
+| `rm /gt2/*` in the Shell | "The 5 that match /gt2/\*": Cancel leaves the five. `rm /gt3/*6?.txt`, Delete: ten gone, sixty left. `rm -f /gt2/*`: gone without a question |
+| `rm /gt/*` where one match is a folder | The files go, the folder stays (no `-r`) |
+| No match, and seventy | `rm: error nothing matches`; `rm: error more than 64 match: a narrower pattern, please`, and all seventy still there |
+| `No`, Tab, Enter | Completes to `Notes ` and opens Notes. `Shell` from the Debug Console opens the Shell |
+| `screenshot 4`, then Home | The picture, taken four seconds later, is of the Launcher: the pause works, and the Toast isn't in it |
+| `quit` | Back to the Launcher, and the memory comes back |
+| The help panel in the Shell | Its keys, then the ones that work everywhere |
+
+**Not checked:** Ctrl+b and the Alt scroll, which `key` can't press (no modifiers): the filter itself is host-tested, the key that flips it is not; the real keyboard altogether; the Toast after a screenshot, which was published but not looked at; and `mv` with a pattern and `cancel` in the middle of a line-up, which share their code with `cp` and `rm` but were not run. The main loop's lowest free stack after all of it: 1.8 KB, where it was.

site/content/dev/milestones/u1.md

@@ -0,0 +1,54 @@
++++
+title = "Look and feel"
+description = "The interface is consistent and uncrowded: the same thing is done the same way on every screen, and the 135 pixels of height go to content."
+weight = 90
+
+[extra]
+docs = true
+source = "docs/milestones/U1.md"
+tag = "U1"
++++
+**Status:** in progress. The help key (issue #69) is merged; the website's key tables generated from the same lists (issue #72) are in a pull request. Screen recording (#17) and the rest of the milestone are not started.
+
+**Goal:** the interface is consistent and uncrowded: the same thing is done the same way on every screen, and the 135 pixels of height go to content.
+
+## The help key (issue #69)
+
+Every screen used to say something about its keys, differently: a footer of abbreviations in one place (`c x v:paste r:name d:del n:new i:info s:sort`), a line under a text field in another (`Enter: save   \`: cancel`), `Tab: sky` in a corner, and nothing at all in several. About 30 such strings, each costing a line of a small screen, and none of them complete.
+
+### Decisions (design round 2026-10-07)
+
+| # | Decision |
+|---|---|
+| Q196 | **Fn+h, on every screen,** text fields included (Fn is held, so nothing is typed). **`?` too, outside Text Entry.** |
+| Q197 | It opens **a panel over the content area**, titled with where you are: the screen's own keys, then an "Everywhere" group (Back, Home, the arrows, the help key). The arrows scroll it; any other key closes it and is not passed on. |
+| Q198 | **Each App answers "what are your keys right now?"** for the state it is in; pages, viewers, dialogs and text fields answer for themselves, with shared lists for dialogs, lists and text entry. The lists are constants; the panel's rows exist only while it is open. |
+| Q199 | **Every hint that names a key goes,** text fields included. What stays is state: `REC 12 points`, `LOG 42`, `sort:signal`, `typing`/`saved`, what is waiting to be pasted, the Sweep's floor. Messages were reworded where they named a key ("v pastes a copy of…" is "Copied …: paste it where you like"). |
+| Q200 | **The first-start Setup keeps its hints,** and is the one place that does: someone in their first minute doesn't know the help key yet. It tells them about it on its first and last screens. |
+| Q201 | **Loud everywhere else:** the user guide opens with it, the FAQ has it first, and a device set up before this firmware gets one Toast, once: "Fn+h: the keys of any screen". |
+| Q202 | `key help` over the consoles. Generating the website's key tables from the same lists is a follow-up, not this issue. |
+| Q203 | The key and the panel first, host-tested; then one App at a time, declaring its keys and losing its hints in the same step; then every screen looked at on the device. |
+
+### As built
+
+- **`Key::Help`** from the key mapper: Fn+h in both modes, `?` only outside Text Entry (`lib/input`, 3 tests).
+- **`App::help()` and `App::helpTitle()`** (`lib/core/src/app.h`), `KeyHelp` rows and `HelpModel` (`key_help.h`). The **App manager** opens the panel, appends the "Everywhere" group, and while it is open takes every key: nothing reaches the App, Home included. It closes when the App changes (5 tests).
+- **Every App declares its keys by state:** the Launcher, IRC (chat, settings, a field), Wi-Fi Tools (4 views), GNSS, Gemini (page, saved page, address, answer, dialogs), the LoRa Scanner (4 views), Storage (browse, details, a name, the viewer's 6 modes, the editor, Maintenance, busy), Notes (list, editor, a file name), System (5 views), Settings (menu, text, choice, and the Wi-Fi, Firmware and Debug Console pages with their own states), Setup and the widget demo.
+- **The hints are gone** from all of them. The footers that remain say state only.
+- **It costs** 8.5 KB of flash and 40 bytes of static RAM.
+
+### Checks
+
+| Check | Result |
+|---|---|
+| Host tests | 476 pass (468 before) |
+| On the device, `key help` and a screenshot | The Launcher and all nine Apps, and these states: Storage scrolled, System's tasks, a Settings text field, Wi-Fi Tools' networks. The panel is titled with the scope, lists the right keys, scrolls, and closes on Tab |
+| The one-time Toast | `notification: Fn+h: the keys of any screen` on the first start after the update |
+
+### One source for the device and the website (issue #72)
+
+The lists first lived in each App's `help()`, as code. They are now **data, in one file**: `lib/core/src/app_keys.h`, 52 constant tables, each under a comment `// id: Title`. An App's `help()` picks the table of the state it is in. `site/tools/gen_dev_docs.py` reads the same file and writes `site/data/keys.toml`; the `keys` shortcode shows a screen's tables on its guide page, and `/guide/keys/` shows all of them. The Site job fails when the data file is out of date, or when a page asks for a table that doesn't exist, and it now runs when `app_keys.h` changes. A key added to an App shows up on the website without anyone editing a page.
+
+Three rows lost their second wording on the way, since a table is constant: GNSS's `Tab` and `r`, and the Scanner's `c`, now say both things they do ("record a Track, or stop it") instead of the one that applies. The guide pages keep their written tables too, where they say more than a key list can; those can still drift, and the generated ones under them are the reference.
+
+**Not checked:** the real Fn+h and `?` on the keyboard (the mapper is host-tested; the device was driven with `key help`); the Setup screens, which only a device that was never set up shows, so their new text has not been seen on a screen; and the states that need something to happen first (a dialog, a copy in progress, a Gemini prompt, a packet's details): their lists were read against the key handling, not looked at.

site/content/dev/milestones/w1.md

@@ -29,7 +29,7 @@ The home page was designed on a canvas in a Claude chat (a dark and a light them
 | Q175 | The site lives in this repository, in `site/`, so the documentation is built from `docs/`, `CONTEXT.md` and the README instead of being copied. |
 | Q176 | **Zola,** like the blog. The design becomes a template, its tokens CSS custom properties. Dark and light follow the visitor's setting, with a visible switch. No JavaScript except the flasher's. |
 | Q177 | Domain: **roro9stack.net.** The blog stays at experiments.twis.la. |
-| Q178 | **Publishing is the blog's way:** the web server pulls `main` and runs `zola build`; that part is the maintainer's. Changes reach `main` through pull requests as everywhere. **CI is split:** a dedicated `site` job builds the site (`zola build`) when `site/`, `docs/`, `README.md` or `CONTEXT.md` change, and the firmware tests and builds skip a change that touches nothing else. A change that touches both runs both. |
+| Q178 | **Publishing is the blog's way:** the web server pulls `main` and runs `zola build`; that part is the maintainer's. *(Since issue #79, CI asks the server to do it: see "Published by CI" below.)* Changes reach `main` through pull requests as everywhere. **CI is split:** a dedicated `site` job builds the site (`zola build`) when `site/`, `docs/`, `README.md` or `CONTEXT.md` change, and the firmware tests and builds skip a change that touches nothing else. A change that touches both runs both. |
 | Q179 | Phases, each its own pull request: **1.** the CI split, the home page, an Install page with the browser flasher, downloads and the changelog. **2.** a user guide page per App. **3.** how-tos and the FAQ. **4.** developer docs generated from the repository. |
 | Q180 | **A browser flasher** (ESP Web Tools), **without copying the firmware.** Caddy, in front of Gitea, adds `Access-Control-Allow-Origin: https://roro9stack.net` (and `Vary: Origin`) to GET and HEAD on `/twisla/roro9stack/releases/download/*` and `/api/v1/repos/twisla/roro9stack/releases*`: both are public already. The Install page asks the API for the latest release in the browser, finds the asset ending `-factory.bin`, and gives ESP Web Tools a manifest built on the spot, so it offers a new release as soon as it exists, with no rebuild. The library is **vendored** into `site/static/` (Apache-2.0), not loaded from a CDN. The file's SHA-256 is shown on the page. Chrome or Edge on a desktop only; other browsers, and visitors without JavaScript, get the `esptool` steps on the same page. |
 | Q181 | Docs for the latest version only. The changelog is the Gitea releases, read at build time. |
@@ -133,3 +133,46 @@ Not one of the planned phases: the blog's seven roro9stack posts, imported into
 - **Left out on purpose:** the M0 and M1 milestone documents and `CONTEXT.md` (the glossary) describe Wi-Fi monitoring, which the site does not publish. They stay in the repository.
 - **The Debug Console pages were written against the source and the live console:** the protocol (the token line, the banner, the 4 KB backlog, one client, 8 queued commands, 240-byte lines, `denied` after a second) and the replies shown were checked on a Debug Build, v0.11.0-3, over Wi-Fi. Not run: `crash abort`, `crash wdt` and Safe Mode, which are described from ADR 0005 and the code.
 - **Found while writing it:** the README's table lacked the `gnss` commands (rows added); piping commands into `rdbg.py` returns before the replies unless the input stays open (documented, not changed); `update install` on a Debug Build needs `force` (documented).
+
+## Published by CI (issue #79, design round 2026-10-07)
+
+Q178 left publishing to the maintainer: a merge, then a command typed on the web server. It was forgotten often enough.
+
+| # | Decision |
+|---|---|
+| Q214 | **A plain ed25519 key with a forced command**, not a certificate: one line in the web server user's `authorized_keys`, `restrict,command="/full/path/to/the/refresh"`. `restrict` takes away the terminal and every forwarding. A certificate could carry the same and an expiry date, at the price of a CA to keep and a key to sign again each time: too much for one key and one command. |
+| Q215 | **The CI sends no command.** The server runs the forced one whatever is asked for, so there is nothing to keep secret about it and nothing a leaked key could choose. The full path is written once, on the server (a command over SSH doesn't get the user's login `PATH`). |
+| Q216 | Four secrets: `SITE_DEPLOY_KEY`, `SITE_DEPLOY_HOST` (or `host:port`), `SITE_DEPLOY_USER`, and **`SITE_DEPLOY_KNOWN_HOSTS`**, the server's host key: the job connects to that server or to nothing. None of them is in the repository, which is public. |
+| Q217 | `from="<the runner's address>"` on the same line: the key works from the runner only. |
+| Q218 | **The last step of the Site workflow**, after the build and the checks, on a push to `main` only. A pull request never reaches it, and the secrets are given to that step alone. |
+| Q219 | **After a release too.** The Install page asks Gitea for the latest release when it is opened, but the home page and Downloads read it when the site is built: so the release workflow refreshes the site once the release is published. |
+| Q220 | A refresh that fails makes the run red, with what the server's script printed: it has to exit with an error when it fails. |
+| Q221 | Two refreshes at once are the server script's to refuse or queue (`flock`). |
+| Q222 | The key is a file only while the step runs, in the job's container, as the signing key is. |
+
+### As built
+
+- **`scripts/site_refresh.sh`** is what both workflows run: it writes the key and the host key to a temporary folder, connects with no configuration but its own line (`-F none`, strict host key checking, that one key, no command), and removes them. With none of the four secrets it does nothing and says so (a fork, or a repository without them); with only some it fails.
+- **`scripts/site_deploy_keygen.sh`** makes the key pair once, in `~/.config/roro9stack/`, and prints the `authorized_keys` line and what goes in each secret. It never prints the private key.
+- **The server's script** should start like this, for Q220 and Q221:
+
+  ```sh
+  #!/bin/sh
+  set -e
+  exec 9>/tmp/rororefresh.lock
+  flock -w 120 9
+  ```
+
+### Checks (2026-10-07, against an SSH server in a throwaway container)
+
+| Check | Result |
+|---|---|
+| The refresh | The forced command runs as the server's user; the script ends with `site refresh: done` |
+| The same key, asking for `id; cat /etc/passwd` | The refresh runs instead; what was asked for is only handed to it as text |
+| A terminal | Refused: `PTY allocation request failed` |
+| `scp` with the key | Nothing is copied |
+| Another host key in the secret | `Host key verification failed`, the run fails, nothing is sent |
+| The server's script exits with an error | So does the step |
+| No secrets at all; only one of the four | Does nothing and says so; fails and says which are needed |
+
+**Not checked:** the real web server and the runner, which wait for the key to be installed: whether the runner reaches the server's SSH port is the first thing the first run will tell. Port forwarding, which `restrict` switches off, was not tried. `from=` was not tried either.

site/content/devlog/roro9stack-console/index.md

@@ -0,0 +1,266 @@
++++
+title = '''It was off'''
+description = '''roro9stack gets a website, and writing down how its Debug Console works shows that only one person could ever use it. So the Debug Build is retired: one firmware, with the console in it, off until its owner switches it on. Then an evening of chasing a console that wouldn't come back and a memory leak, neither of which existed.'''
+date = 2026-10-07T00:30:00+02:00
+
+[extra]
+topics = '''ESP32-S3 · Debugging · Security'''
+read_label = '''Read what was off →'''
+uid = '''<b>debug:</b> on, token set, client connected'''
+dek = "A day of writing for [roro9stack](/devlog/roro9stack/), my firmware for the M5Stack Cardputer: a website, a user guide, and developer docs about the thing I like best in it, a console over Wi-Fi. Documenting it properly made one fact hard to miss: nobody else could have it. Fixing that deleted more than it added, and then cost me an evening looking for two bugs that turned out to be a switch in the Off position and TCP minding its own business."
+byline = '''designed by interrogation, round twelve: fourteen questions thrown away, eight kept'''
+
+[extra.sign]
+label = "Tokens leaked by the feature built to protect them"
+note = "In a screenshot, taken over the console, of the one page that shows the token."
+count = "1"
+tone = "red"
+
+[[extra.cast]]
+name = "The Debug Build"
+role = "retired, v0.3.0 to v0.11.0"
+text = "The same firmware plus a console over Wi-Fi, with its builder's token compiled in. Which is why it could never be published, and why the firmware I tested was never the one I released."
+
+[[extra.cast]]
+name = "Port 3232"
+role = "the Update Service, in every build since v0.3.0"
+text = "Listens on the network in release builds, guarded by a signature. The counter-example to \"in a release, nothing listens\" that had been sitting there all along."
+
+[[extra.cast]]
+name = "The token"
+role = "100 bits, 20 characters"
+text = "Made by the device, shown on one page of Settings and nowhere else. Read off a 240-pixel screen by a human, which is where the trouble started."
+
+[[extra.cast]]
+name = "The dialog"
+role = "\"Switch it on?\""
+text = "Opens with Cancel selected, as a question about a remote control should. Enter, Enter: still off. Works exactly as designed."
+
+[[extra.cast]]
+name = "TIME_WAIT"
+role = "two minutes, per closed connection"
+text = "What TCP does with a connection it has closed, in case a late packet turns up. About 270 bytes each. Looks exactly like a leak if you only watch for one minute."
++++
+
+## TL;DR
+
+- **roro9stack has a website:** [roro9stack.net](/), with an Install page that flashes a Cardputer from the browser, a [user guide](/guide/), [how-tos](/howto/), an [FAQ](/faq/), [developer docs](/dev/) generated from the repository, and this devlog, which moved here.
+- **The Debug Build is gone.** There is one firmware (**v0.12.0**), and the Debug Console is in it: **off** until you switch it on in Settings, with a token the device makes itself.
+- **The token never crosses the network.** The device sends a challenge, the client answers with an HMAC. Five wrong answers close the console for a minute.
+- **It costs** 30 KB of flash and 88 bytes of RAM over the old release build. Off, nothing listens and nothing is allocated.
+- Then I spent an evening on **a console that wouldn't come back on** (it was off) and **a memory leak of 230 bytes per reopening** (it was TCP). Both produced a real fix on the way, and one design change I had to undo.
+- 468 host tests, 12 more than last time. The decision is [ADR 0010](/dev/decisions/0010-debug-console-in-every-build/).
+
+## The cast
+
+{{ cast() }}
+
+## A site, in four phases
+
+The [last post](/devlog/roro9stack-f1-r1/) ended with a device that installs its own releases. That makes it something another person could use, and another person needs somewhere to start that isn't a Gitea README. So the first half of the day was a website: a home page, an Install page, then a guide to each App, how-tos, an FAQ, and developer docs.
+
+Three things from that half are worth keeping.
+
+**Flashing from the browser, without a copy of the firmware.** The Install page uses ESP Web Tools and Web Serial. The obvious way is to copy the firmware image next to the page; then every release needs a rebuild of the site. Instead the page asks Gitea's API for the latest release, in the browser, and hands the flasher a manifest it builds on the spot. That only needed one header: Caddy, in front of Gitea, adds `Access-Control-Allow-Origin: https://roro9stack.net` to the release downloads and to the releases API, which are public anyway. A new release shows up on the page the moment it exists.
+
+**"Generated from the repository" met Zola.** The developer docs were to be built from `docs/`, the README and the firmware's own `help` text, not copied by hand. Zola refuses to read a file outside its own folder, and it resolves symlinks before deciding, so that door is closed too. So a small script writes those pages, they are committed, and CI fails when one is out of date. The command reference is the part I like: it is parsed from the `kHelp` string in `main.cpp`, so the site can't describe a command the firmware doesn't have.
+
+**The posts you're reading had `<style>` in them.** This devlog came over from my blog, seventeen diagrams included, each an inline SVG with its own `<style>` block. The site's Content-Security-Policy is `style-src 'self'`, which refuses exactly that. The rules moved into a stylesheet and the `style="…"` attributes became classes. Tested in a real browser with the production policy on every response: no violations.
+
+The site says only what the firmware does today, which meant writing the same sentence several times: the mesh messenger isn't built. The radio listens. It doesn't talk yet.
+
+## Documenting a feature only I could use
+
+The part of the developer docs I cared most about is the Debug Console: the serial console over Wi-Fi, with key presses, screenshots, file transfer and crash dumps. I wrote six pages on it, checked the protocol against the live device, and by the end had described, in detail, a feature with this property:
+
+> A Debug Build carries its builder's token, so Debug Builds are never published.
+
+Everything in those pages was for whoever builds the firmware. That's me.
+
+The issue I filed was the obvious patch: make the token configurable, so that Debug Builds can be published. The design round for it had fourteen questions. Where does a published Debug Build go, so that devices in the field don't install it by accident (v0.11.0 takes the last `.ota` it finds in a release)? What is its tag called, so that CI doesn't start itself again? How does a device that runs one get the next?
+
+Then one question from the other side of the table replaced all fourteen: *why have Debug Builds at all?*
+
+## The argument that was never whole
+
+[ADR 0004](/dev/decisions/0004-debug-console-in-debug-builds/) kept the console out of release builds with one sentence, which I was rather proud of:
+
+> A console that runs commands is a remote control: in a release build, nothing listens.
+
+Except something does. The Update Service has listened on TCP 3232 in every build since v0.3.0, guarded by a signature. "Nothing listens" was never true; "nothing listens without a lock on it" was. A console that is off by default, behind a secret the device made itself, is the same trade.
+
+And the split had been charging rent the whole time:
+
+- **What I tested wasn't what I shipped.** I lived on Debug Builds. Releases were a different binary that nobody ran before it was published.
+- **Rules that only protected the console.** A Debug Build refused to install a release (it would have lost its console), so there was `update install … force` to do it anyway, and advice about which firmware to keep in the other slot.
+- **Versions ending in `+debug`** that had to compare equal to their release.
+- **Two firmwares built by CI** on every pull request and every tag.
+
+One firmware deletes all four.
+
+## What off means
+
+The new argument only holds if "off" is as good as "not compiled in". So:
+
+- **Off is the default,** and what a missing or damaged setting falls back to.
+- **Off, nothing exists:** no socket, no task, and no 4 KB buffer, which used to be a static array and is now allocated when the console is switched on.
+- **On needs someone at the device,** or on the USB cable. Over the console itself, `debug on` and `debug token` answer `over USB serial only`: it can switch itself off, not open itself wider.
+
+{% table() %}
+| Build | Flash | Static RAM |
+|---|---|---|
+| The release build, before | 1,851,387 | 54,612 |
+| The Debug Build, before | 1,874,887 | 58,780 |
+| **The one firmware** | **1,881,799** | **54,700** |
+{% end %}
+
+Thirty kilobytes of flash, and 88 bytes of RAM, for a console in every device. The Debug Build's extra 4 KB of RAM was the buffer, sitting there whether anyone connected or not.
+
+## A token you can read, and one you can't steal
+
+The token used to be 32 hex digits in a file on my laptop, compiled in. Now the device makes it, the first time the console is switched on: 100 bits from the hardware generator, as twenty characters of Crockford's base32, the alphabet that leaves out I, L, O and U because people misread them.
+
+The old login sent the token as the first line of a plain TCP connection. That was fine for a secret that lived on one laptop and one device on one network. It's not fine for a secret in every device, on whatever Wi-Fi its owner uses: mine is called `knbg-guests`, and anyone with the Wi-Fi password can watch it.
+
+So the token no longer travels:
+
+{% code(caption="The whole login. A recorded answer is no use for the next challenge.") %}
+```
+device:  roro9stack debug console, challenge 3f9a…c1   (16 random bytes)
+client:  HMAC-SHA256(key = token, message = those bytes), in hex
+device:  roro9stack v0.12.0 debug console. 'help' lists the commands. Backlog follows.
+```
+{% end %}
+
+HMAC is twenty lines on top of the SHA-256 the firmware already had for update files, checked against the RFC's vectors and against the same vector as the Python client. Five wrong answers in a row and the console answers `locked` to everyone for a minute:
+
+{% code(caption="Six tries with a wrong token, then the right one.") %}
+```
+try 1 at  1s: wrong token
+try 2 at  3s: wrong token
+try 3 at  4s: wrong token
+try 4 at  5s: wrong token
+try 5 at  6s: wrong token
+try 6 at  6s: closed for a minute after too many wrong tokens
+right token:  closed for a minute after too many wrong tokens
+```
+{% end %}
+
+This breaks every old client. I'm the only user, and v1 is a long way off; this is exactly when to break things.
+
+## Three ways it went wrong
+
+### I couldn't read my own token
+
+First login, on the real device: `wrong token`. The firmware was right. I had typed one character wrong, reading a 20-character token drawn in bold at the normal size, where 8 and B, 5 and S, 2 and Z are a matter of opinion.
+
+The token is now drawn at twice the size, in regular weight, on two lines. And what I should have done from the start: Crockford's rule says that if someone types an O, an I or an L, they meant 0 or 1, because the alphabet doesn't have those letters. Both ends now apply it.
+
+### The screenshot
+
+To check the new layout I did what I always do: took a screenshot over the console.
+
+{{ figure(src="token.png", alt="The Cardputer's Settings, Debug Console page at 2x: Debug Console On, Connect to 10.39.39.12:2323, New token, Type a token, and below them a token in large type on two lines, T49R-HQXB-NDJX then BNSB-XSWD. The Status Bar shows DBG in blue.", width=480, height=270, caption="The page that shows the token \"and nowhere else\", in a file on my laptop. This token was replaced within the hour.") }}
+
+The documentation I had written an hour earlier says the token is shown on one page and never printed anywhere. And there it is, in a PNG. No escalation: whoever can take a screenshot already has the token. But a secret now sits in a file because of a habit, and the sign at the top of this post is for that. The docs now say it in so many words: a screenshot of that page is a copy of the token.
+
+### The console that wouldn't come back
+
+The last test was `debug off`, sent over the console: the client is dropped, the port refuses connections. Good. I switched it back on at the device, made a new token, and tried to log in.
+
+Connection refused.
+
+The device was up. Its update port answered. And it stayed refused across another firmware push and a restart. So, I reasoned, the console fails to come back once it has been closed, and I went looking:
+
+- **The framework's `begin()` returns nothing.** `NetworkServer::begin()` can fail at `socket()`, `bind()` or `listen()` and says nothing either way; my code set `listening = true` and never asked. A real hole. Fixed: it asks, complains on the console, and tries again every two seconds.
+- **I couldn't reproduce it from my desk.** Switching the console on is for the device and the cable only, by design, so the one path I wanted to test was the one I had made unreachable. Hence `debug off <seconds>`: the console closes and comes back by itself after the pause. It can't open anything wider (same state, same token), and it makes closing and reopening something a script can do twenty times.
+
+Then I went and looked at the device's screen.
+
+It said **Off**.
+
+The "Switch it on?" dialog opens with **Cancel** selected. Enter on the row, Enter on the dialog: nothing changes, and the page says so in plain letters that I hadn't read. I had filed a bug against a switch for being in the position I left it in.
+
+### The leak that was TCP
+
+With `debug off <seconds>` I could finally hammer the path. It came back every time. And free memory fell by about 230 bytes per cycle.
+
+A leak in code I had just written, in a firmware where 836 bytes was [once all that was left](/devlog/roro9stack-f1-r1/). I had a suspect: the console's task is deleted when the console goes off and made again when it comes back. Twenty plain logins leaked nothing, so it wasn't connections. I changed the design: the task stays, asleep, while the console is off. That breaks the promise that off means nothing is there, but a leak is worse.
+
+It leaked exactly as much as before.
+
+So I did what I should have done first, and measured for longer:
+
+{% table() %}
+| | Free heap |
+|---|---|
+| Before | 107,248 |
+| Right after 15 closings and reopenings | 103,180 |
+| 60 s later | 105,008 |
+| 120 s later | 107,004 |
+| 240 s later | 106,924 |
+{% end %}
+
+All of it comes back. When the device closes a connection, TCP keeps it for two minutes in case a late packet arrives, and each one holds about 270 bytes. Fifteen cycles in a minute and a half look like a leak; fifteen cycles and a cup of tea look like nothing at all.
+
+The design change went back out. Off means the task is gone too, as decided.
+
+## What held
+
+{{ figure(src="dbg.png", alt="The Cardputer's Launcher at 2x, listing IRC, Wi-Fi Tools, GNSS, Gemini, LoRa Scanner, Storage, Notes, System and Settings. The Status Bar shows DBG in blue between the GNSS and Wi-Fi indicators.", width=480, height=270, caption="`DBG` in the Status Bar: there while the console listens, bright while someone is connected. Taken over the console, so: bright.") }}
+
+Checked on the device, not just in tests:
+
+- **Off by default.** Pushed over a Debug Build, the new firmware came up with port 2323 refusing connections.
+- **The setting survives updates.** Four pushes later the console came back by itself each time.
+- **Safe Mode has the console.** Three `crash abort` in a row, and the device started in Safe Mode with 178 KB free and the console reachable. `ls /` answered `not available in Safe Mode`, and the crash decoded to the line of `main.cpp` with `abort()` on it.
+- **25 closings and reopenings,** each back a second after its pause.
+- **More memory than before.** 108 KB free with the console on and a client connected, against 104 KB on the Debug Build.
+
+And what I didn't check: `scripts/flash.sh --debug`, which now sets a device up over USB, with no cable attached to the VM that night; typing a token of my own on the device; and the notification on the screen during a lockout, which nobody connected can see, the console being closed.
+
+## By the numbers
+
+{% table() %}
+| | |
+|---|---|
+| Design questions written, then thrown away | 14 |
+| Design questions kept | 8 |
+| Host tests | 468 |
+| Bits in a token | 100 |
+| Wrong answers before the console closes | 5 |
+| Flash it costs every device | 30,412 bytes |
+| RAM it costs every device, off | 88 bytes |
+| Bytes TCP holds for a closed connection, for two minutes | about 270 |
+| Pages on the website | 66 |
+| Bugs found in the console that evening | 1 (the silent `begin()`) |
+| Bugs I thought I'd found | 3 |
+{% end %}
+
+## Where it stands
+
+{% steps() %}
+1. ~~M0 and M1: the skeleton, Wi-Fi, IRC, Wi-Fi Tools.~~ v0.1.0 to v0.2.1, [the first post](/devlog/roro9stack/).
+
+2. ~~Updates and debugging over the air.~~ v0.3.0, [Look, no cables](/devlog/roro9stack-ota/).
+
+3. ~~M2: GNSS.~~ v0.4.0, [Seventeen satellites](/devlog/roro9stack-gnss/).
+
+4. ~~G1: Gemini.~~ v0.5.0, [A browser in the RAM IRC left over](/devlog/roro9stack-gemini/).
+
+5. ~~M3: the LoRa radio, listening.~~ v0.6.0, [The loudest thing it hears is itself](/devlog/roro9stack-lora/).
+
+6. ~~S1: the card, fixed addresses, the System App.~~ v0.6.1 to v0.8.1, [One byte too early](/devlog/roro9stack-s1/).
+
+7. ~~F1 and the start of R1: files, notes, signed releases, updates from Gitea.~~ v0.9.0 to v0.11.0, [836 bytes](/devlog/roro9stack-f1-r1/).
+
+8. ~~W1: the website.~~ You're on it.
+
+9. ~~One firmware, with the Debug Console in it.~~ v0.12.0, this post.
+
+10. Next: notes of any size, a shell on the device itself for the same commands, and one help key everywhere instead of a hint line on every screen. And M4, the mesh, which still wants a second node.
+{% end %}
+
+{% signoff() %}
+I wrote a feature whose whole point is that it's off until you switch it on, and then spent an evening debugging it for being off. The switch works. So does TCP. The only thing that leaked was the token, and I did that myself.
+{% end %}

site/content/faq.md

@@ -6,6 +6,10 @@ template = "guide-page.html"
 toc = true
 +++
 
+## Which keys work on this screen?
+
+Press **<kbd>Fn</kbd> + <kbd>h</kbd>**, on any screen: it lists the keys that work there, then the ones that work everywhere. <kbd>?</kbd> does the same when you are not typing text. The screens themselves never name their keys, so this is the one key to remember. See [The basics](/guide/basics/).
+
 ## Can I send messages over the mesh?
 
 **Not yet.** The LoRa Scanner **listens** to Meshtastic traffic and shows what it hears, but nothing is transmitted. A mesh messenger is the goal and is planned in two milestones, one for receiving and one for transmitting; it waits for a second node to test against.

site/content/guide/_index.md

@@ -6,7 +6,7 @@ sort_by = "weight"
 page_template = "guide-page.html"
 +++
 
-This guide says what the firmware does **today** and nothing else. Start with the basics (the keys, the Launcher, the first start), then read the page of any App. It describes the latest release; the numbers and key names come from the firmware's own source.
+This guide says what the firmware does **today** and nothing else. Start with the basics (the keys, the Launcher, the first start), then read the page of any App. **On the device itself, <kbd>Fn</kbd> + <kbd>h</kbd> lists the keys of whatever screen you are on:** nothing else on a screen names them. It describes the latest release; the numbers and key names come from the firmware's own source.
 
 **The mesh messenger is planned, not built.** The LoRa Scanner listens to Meshtastic traffic and shows it, but the device sends nothing yet: that is the next milestone and waits for a second node to test with.
 

site/content/guide/basics.md

@@ -6,6 +6,14 @@ weight = 1
 tag = "Start here"
 +++
 
+## One key to remember
+
+**<kbd>Fn</kbd> + <kbd>h</kbd>, on any screen, lists the keys that work there.** No screen names its keys: that key does. It works everywhere, in a text field too, and <kbd>?</kbd> does the same whenever you are not typing. The arrows scroll the list; any other key closes it.
+
+The list is for *the screen you are on*: in Storage it is the file keys, in a dialog it is the dialog's, in a text field it is the editing keys. Each list ends with the keys that work everywhere.
+
+If you only read one paragraph of this guide, this was it.
+
 ## The keys
 
 The Cardputer's keyboard has no arrow keys and no Escape, so the firmware gives a few keys a second job:
@@ -17,11 +25,12 @@ The Cardputer's keyboard has no arrow keys and no Escape, so the firmware gives
 | <kbd>Fn</kbd> + <kbd>`</kbd> | **Home**: back to the Launcher |
 | <kbd>Fn</kbd> + <kbd>;</kbd> <kbd>.</kbd> <kbd>,</kbd> <kbd>/</kbd> | The arrows: up, down, left, right |
 | <kbd>;</kbd> <kbd>.</kbd> <kbd>,</kbd> <kbd>/</kbd> alone | The same arrows, as long as you are **not** typing text |
+| <kbd>Fn</kbd> + <kbd>h</kbd>, or <kbd>?</kbd> when not typing | **Help:** the keys of the screen you are on |
 | <kbd>Tab</kbd> | Switches view in an App that has more than one |
 | <kbd>Del</kbd> | Deletes backwards when you type |
 | <kbd>opt</kbd> then an accent, then a letter | Types an accented letter: <kbd>opt</kbd> <kbd>'</kbd> <kbd>e</kbd> gives é |
 
-While you type text (a note, an IRC line, a setting), `;` `.` `,` `/` type their own characters and you need <kbd>Fn</kbd> for the arrows. The bottom of the screen shows `opt` while a compose is waiting for its letter.
+While you type text (a note, an IRC line, a setting), `;` `.` `,` `/` type their own characters and you need <kbd>Fn</kbd> for the arrows. The Status Bar shows `opt` while a compose is waiting for its letter.
 
 ## The Launcher
 
@@ -50,7 +59,7 @@ News from a background service (an IRC mention, a Storage warning, an update tha
 
 ## The first start
 
-On a new device a short Setup asks four things, then never appears again:
+On a new device a short Setup asks four things, then never appears again. It also tells you about <kbd>Fn</kbd> + <kbd>h</kbd>, twice, and it is the only part of the firmware that names keys on the screen:
 
 1. **Long name**, up to 39 bytes.
 2. **Short name**, up to 4 characters.
@@ -59,6 +68,12 @@ On a new device a short Setup asks four things, then never appears again:
 
 ## The SD card
 
-Put a microSD card in the Cardputer. Without one the radio, GNSS, Wi-Fi and IRC still work, but nothing can be saved: no notes, IRC logs, Wi-Fi scan logs, GPX tracks, LoRa captures or saved Gemini pages. The [Storage App](/guide/storage/) shows what is on the card.
+Put a microSD card in the Cardputer. Without one the radio, GNSS, Wi-Fi and IRC still work, but nothing can be saved: no notes, IRC logs, Wi-Fi scan logs, GPX tracks, LoRa captures, screenshots or saved Gemini pages. The [Storage App](/guide/storage/) shows what is on the card.
 
-The firmware keeps its own folders at the top of the card (`captures`, `gemini`, `gnss`, `irc`, `updates`, `wifi`, plus `notes`). You can use the card in a computer too, but those names are the firmware's.
+The firmware keeps its own folders at the top of the card (`captures`, `gemini`, `gnss`, `irc`, `notes`, `screenshots`, `updates`, `wifi`). You can use the card in a computer too, but those names are the firmware's.
+
+## The keys, as the device lists them
+
+What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
+
+{{ keys(scopes=["launcher", "everywhere", "dialog", "text"]) }}

site/content/guide/gemini.md

@@ -40,3 +40,9 @@ Most capsules sign their own certificate. The first certificate seen for a host
 ## Big pages and memory
 
 With a card, every page streams to the card first, so a page larger than the device's memory still arrives whole and is read from the card as you scroll. Without a card, a page is limited to what fits in memory. If there is not enough free memory to open a secure connection, the fetch says so instead of failing silently; stopping IRC frees the most.
+
+## The keys, as the device lists them
+
+What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
+
+{{ keys(scopes=["gemini", "gemini-saved", "gemini-address", "gemini-answer"]) }}

site/content/guide/gnss.md

@@ -28,3 +28,9 @@ Once there is a fix, the device's clock follows it.
 ## Tracks
 
 <kbd>r</kbd> starts recording a **Track**: the route is saved as a **GPX** file on the SD card, in `/gnss/tracks` (named by date and time), and the Status Bar shows `REC`. Press <kbd>r</kbd> again to stop. A Track keeps recording with the App closed. It needs a card and a clock (a fix or Wi-Fi sets it); if it cannot start, the App says why: `GNSS is off`, `No SD card` or `Waiting for the time`. The [Storage App](/guide/storage/) opens a `.gpx` file and shows its points, start, duration and distance.
+
+## The keys, as the device lists them
+
+What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
+
+{{ keys(scopes=["gnss"]) }}

site/content/guide/irc.md

@@ -49,3 +49,9 @@ Every buffer is logged to the SD card, one file per day, under `/irc`. Logs stop
 
 - IRC **pauses** while Wi-Fi is monitoring (the Status Bar shows `MON`) and while the device **installs an update**. It reconnects and rejoins its channels afterwards; the App says `paused` in the meantime.
 - A secure connection costs memory: IRC's takes about 40 KB of the 107 KB the device has, and an update's download needs about 52 KB more. That is why IRC steps aside for an update, and why the daily update check waits for IRC to be disconnected (see [Updates](/guide/updates/)).
+
+## The keys, as the device lists them
+
+What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
+
+{{ keys(scopes=["irc", "irc-settings", "irc-field"]) }}

site/content/guide/keys.md

@@ -0,0 +1,13 @@
++++
+title = "Every key"
+description = "The keys of every screen of the firmware, as the help panel lists them on the device: one table for each screen and state."
+weight = 13
+[extra]
+tag = "Reference"
++++
+
+On the device, <kbd>Fn</kbd> + <kbd>h</kbd> lists the keys of the screen you are on (and <kbd>?</kbd> does, when you are not typing). This page is all of those lists at once, generated from the same source the firmware reads: `lib/core/src/app_keys.h`.
+
+In the tables, `; . , /` are the arrow keys (up, down, left, right): alone when you are not typing, with <kbd>Fn</kbd> when you are. `` ` `` is Back, `Aa` is Shift, and two keys separated by spaces are two keys that do the two things listed.
+
+{{ keys(all=true) }}

site/content/guide/lora-scanner.md

@@ -33,3 +33,9 @@ A capture records packets into a **pcap** file with LoRaTap headers in `/capture
 ## The GNSS receiver raises the noise
 
 The GNSS receiver on the same Cap makes the radio's noise floor about **8 dB** worse while it runs. **Settings → Pause GNSS for LoRa** (off by default) puts the receiver on standby while the radio listens, except while a Track is being recorded.
+
+## The keys, as the device lists them
+
+What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
+
+{{ keys(scopes=["lora", "lora-packet", "lora-presets", "lora-sweep"]) }}

site/content/guide/notes.md

@@ -35,3 +35,9 @@ A new note has no file until you type something. The file is then named after it
 ## Limits
 
 A note holds up to **16 KB** while it is edited. A bigger text file opens read-only in the [Storage App](/guide/storage/); editing a file of any size is planned. In Storage, <kbd>e</kbd> on a text file opens it in the same editor, anywhere on the card, unless the file is read-only. Notes are never offered for deletion by the clean-up.
+
+## The keys, as the device lists them
+
+What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
+
+{{ keys(scopes=["notes", "notes-editor", "notes-name"]) }}

site/content/guide/settings.md

@@ -1,7 +1,7 @@
 +++
 title = "Settings"
 description = "The device's names, region, screen, sound, GNSS and Wi-Fi, and where firmware updates are found."
-weight = 10
+weight = 11
 [extra]
 tag = "Settings"
 +++
@@ -41,3 +41,9 @@ A network normally gives the device its address by itself (DHCP, **Automatic**).
 ### DNS and NTP
 
 Two DNS servers (9.9.9.9 and 1.1.1.1 by default), used on Fixed networks, or on every network if **Always use my DNS** is on; and two NTP servers (pool.ntp.org and time.cloudflare.com), used after any that the network's DHCP offers. <kbd>Enter</kbd> on **Status** shows what is in use and where each value came from.
+
+## The keys, as the device lists them
+
+What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
+
+{{ keys(scopes=["settings", "settings-choice", "wifi", "wifi-servers", "wifi-network", "wifi-status", "wifi-scan", "wifi-name", "debug-console"]) }}

site/content/guide/shell.md

@@ -0,0 +1,90 @@
++++
+title = "Shell"
+description = "The firmware's own commands, typed on the device: look at its state, the SD card, the radio and the network with no PC and no cable."
+weight = 9
+[extra]
+tag = "Shell"
++++
+
+The firmware has a set of **commands**, made for working on it from a PC. The Shell runs them **on the device itself**: no computer, no cable, no Wi-Fi. It is the tool for the day something is wrong and you are nowhere near a desk.
+
+It can do real damage: `rm` deletes, `reboot` restarts, `debug on` opens the device to the network. It is the same trust as holding the device, and nothing more.
+
+## Using it
+
+Type a command and press <kbd>Enter</kbd>. `help` lists them all; the [command reference](/dev/debug/commands/) says what each does. A few to start with:
+
+| Command | Shows |
+|---|---|
+| `info` | The firmware's version, uptime, memory, Wi-Fi, the SD card and both firmware slots |
+| `wifi status` | The network, the address, and where the DNS and time servers came from |
+| `ls /notes` | A folder of the SD card, with sizes and dates |
+| `crash` | The last crash, if there was one |
+| `update check` | Whether a newer release exists |
+| `lora status` | What the radio is set to and what it has heard |
+
+- <kbd>Tab</kbd> **completes** what you are typing: the command, word by word (`lora st` gives `lora status`, and `gnss track ` with Tab lists `start  stop`), then **a path on the SD card**. `ls /no` and Tab gives `ls /notes/`; Tab again goes on inside the folder. If several names fit, it completes as far as they agree and lists them. You can type the name in any case, and after a file command you can leave out the first slash: `cat no` and Tab gives `cat /notes/`. A name with a space in it isn't completed.
+- <kbd>Fn</kbd> with up and down brings back **lines you typed before**.
+- <kbd>Alt</kbd> with up and down **scrolls back** through what was printed.
+- `clear` empties the screen, and `quit` (or Back) leaves.
+
+## What you see
+
+**The replies to your own commands, and nothing else.** The firmware prints a lot besides: IRC connecting, a packet received, whatever a PC on the USB port or the Debug Console is asking for. None of that reaches the Shell. The firmware knows who each line is printed for, so an answer that comes a moment later from another part of it (a folder listing, `tasks`) is still yours.
+
+<kbd>Ctrl</kbd> + <kbd>b</kbd> shows **everything** the firmware prints instead, and `all` shows in the corner. Press it again to go back.
+
+## Opening an App
+
+Type an App's name **with a capital letter** to open it, without going back to the Launcher:
+
+`Irc`  `Wifi`  `Gnss`  `Gemini`  `Lora`  `Storage`  `Notes`  `System`  `Settings`
+
+The capital is the difference: every command is in small letters, every App starts with a capital. <kbd>Tab</kbd> completes them too.
+
+## Deleting
+
+`rm` works as it does on Unix, with one addition: it asks.
+
+| You type | What happens |
+|---|---|
+| `rm /notes/a.txt` | Asks, then deletes the file |
+| `rm -f /notes/a.txt` | Deletes it without asking |
+| `rm /captures/old` | Refused: it is a folder, and a folder needs `-r` |
+| `rm -r /captures/old` | Removed at once if it is empty. If not, asks first |
+| `rm -rf /captures/old` | Removed with everything in it, without asking |
+
+## Several files at once
+
+`*` stands for any run of characters in a name and `?` for exactly one, in `ls`, `du`, `rm`, `cp` and `mv`:
+
+| You type | What happens |
+|---|---|
+| `ls /notes/*.txt` | Only the notes ending in `.txt` |
+| `du /captures/lora/*.pcap` | The size of each capture |
+| `cp /gnss/2026-10-0?.gpx /backup` | Copies the tracks of the 1st to the 9th into `/backup`, which must exist |
+| `rm /screenshots/2026*` | Asks **once**, saying how many match, then deletes them |
+| `rm -f /screenshots/*` | Deletes them all without asking |
+
+The pattern goes in the **last part** of the path (`/notes/*.txt`, not `/*/a.txt`), and capitals don't matter. A folder that matches is left alone by `rm` unless you add `-r`. At most 64 names at a time: past that nothing is done, and you are asked for a narrower pattern. `cancel` stops what is left.
+
+The folders the firmware keeps its own files in can't be removed, as in the [Storage App](/guide/storage/).
+
+## Screenshots
+
+```
+screenshot        the screen, now
+screenshot 5      the screen in 5 seconds: time to go to another App
+```
+
+The picture is saved as a PNG in `/screenshots` on the SD card, named by date and time, and a Toast says so once it is written (so the Toast is never in the picture). From the Shell, "now" is always a picture of the Shell: use the pause to get to the screen you want. The [Storage App](/guide/storage/) shows the files; to look at them, take the card to a computer.
+
+## What it costs
+
+Nothing while it is closed. Open, about 7 KB of memory, given back when you leave: with IRC connected and a Gemini page open, that can be the difference (see [the memory limit](/howto/not-enough-memory/)).
+
+## The keys, as the device lists them
+
+What <kbd>Fn</kbd> + <kbd>h</kbd> shows on this screen. This table is generated from the firmware's own lists, so it is always the current one.
+
+{{ keys(scopes=["shell"]) }}

site/content/guide/storage.md

@@ -13,7 +13,7 @@ Storage shows what is on the SD card: each folder's entries with their size and
 
 | Key | Does |
 |---|---|
-| <kbd>c</kbd> / <kbd>x</kbd> | Copies or cuts the selected file or folder; the footer shows what <kbd>v</kbd> would paste |
+| <kbd>c</kbd> / <kbd>x</kbd> | Copies or cuts the selected file or folder; the footer shows what is waiting to be pasted |
 | <kbd>v</kbd> | Pastes it into the folder shown. A copy next to its original is named `name (2).txt`; anything in the way is asked about first |
 | <kbd>r</kbd> | Renames |
 | <kbd>d</kbd> | Deletes, after saying what is inside: "Delete saved and its 42 files (1.2 MB)?" |
@@ -45,3 +45,9 @@ The App says why when it refuses.
 At the top of the card, the last row, **Maintenance** (or <kbd>m</kbd>), shows the card's usage and holds **Storage clean-up** and **Erase SD card**. They delete for good, so they sit behind a warning. Clean-up deletes old logs and captures by category and age, showing the space it would free first. Notes and Saved Pages are never offered.
 
 The firmware warns once per start when the card passes **80%** full; past **90%**, logs stop being written so that the rest is kept for captures.
+
+## The keys, as the device lists them
+
+What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
+
+{{ keys(scopes=["storage", "storage-details", "storage-name", "storage-busy", "maintenance", "viewer-text", "viewer-hex", "viewer-pcap", "viewer-packet", "viewer-gpx", "viewer-ota"]) }}

site/content/guide/system.md

@@ -1,7 +1,7 @@
 +++
 title = "System"
 description = "What the device is doing right now: load, tasks, memory, network traffic, battery and temperature. Live, and read-only."
-weight = 9
+weight = 10
 [extra]
 tag = "System"
 screens = ["system.png"]
@@ -18,3 +18,9 @@ System changes nothing: it shows. It samples once a second and keeps its history
 ## Why it exists
 
 The device has about 107 KB of free memory and no PSRAM, so memory is the resource that decides what can run together: a secure connection takes about 52 KB at its peak. System makes that visible, and is how the project measures its own changes.
+
+## The keys, as the device lists them
+
+What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
+
+{{ keys(scopes=["system", "system-tasks", "system-system"]) }}

site/content/guide/updates.md

@@ -1,7 +1,7 @@
 +++
 title = "Updates"
 description = "How the device updates itself from the project's releases, from the SD card or from a PC, and how it protects itself when an update goes wrong."
-weight = 11
+weight = 12
 [extra]
 tag = "Firmware"
 screens = ["update.png"]
@@ -42,3 +42,9 @@ The connection to the project's server is checked against the two root certifica
 ## For developers
 
 Updates can also be pushed from a PC over Wi-Fi, with `scripts/flash.sh --ota <ip>`, or put on the card with `scripts/sd_put.sh`: see the [README](https://git.twis.la/twisla/roro9stack#firmware-updates-over-wi-fi-ota). The firmware's console can be reached over Wi-Fi too: see [The Debug Console](/dev/debug/).
+
+## The keys, as the device lists them
+
+What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
+
+{{ keys(scopes=["firmware", "firmware-release", "firmware-older"]) }}

site/content/guide/wifi-tools.md

@@ -34,3 +34,9 @@ One bar for each of the 13 Wi-Fi channels shows how busy it is: how many network
 ## Signal tracker
 
 Follows one network: its name, address and channel, then the signal in dBm in large type, a strength bar, and a graph of the recent readings, so you can walk towards the strongest signal. <kbd>m</kbd> turns audible clicks on and off. If the network is no longer heard the screen says `lost`. <kbd>`</kbd> (Back) returns to the list.
+
+## The keys, as the device lists them
+
+What <kbd>Fn</kbd> + <kbd>h</kbd> shows on these screens. These tables are generated from the firmware's own lists, so they are always the current ones.
+
+{{ keys(scopes=["wifi-tools", "wifi-networks", "wifi-tracker"]) }}

site/content/howto/sd-files.md

@@ -19,6 +19,7 @@ Everything the firmware writes goes in a folder at the top of the card. Switch t
 | Gemini bookmarks | `/gemini/bookmarks.gmi` | gemtext |
 | Files saved from Gemini that are not text | `/gemini/downloads` | whatever they were |
 | Update files | `/updates` | `.ota` |
+| Screenshots (the Shell's `screenshot`) | `/screenshots` | `.png`, named by date and time |
 
 ## Rules worth knowing
 

site/data/keys.toml

@@ -0,0 +1,535 @@
+# Generated by site/tools/gen_dev_docs.py from lib/core/src/app_keys.h: the keys of every screen, as the
+# help panel (Fn+h) lists them on the device. Edit that header, not this file.
+
+[[scope]]
+id = "everywhere"
+title = "Everywhere"
+rows = [
+    ["`", "back"],
+    ["Fn `", "home, the Launcher"],
+    ["; . , /", "arrows (Fn+ while typing)"],
+    ["Fn h  ?", "these keys (? not typing)"],
+]
+
+[[scope]]
+id = "dialog"
+title = "A question"
+rows = [
+    [", /", "the other answer"],
+    ["Enter", "choose it"],
+    ["`", "cancel"],
+]
+
+[[scope]]
+id = "text"
+title = "A text field"
+rows = [
+    ["Enter", "save"],
+    ["`", "cancel"],
+    ["Del", "delete backwards"],
+    ["Fn , /", "move the cursor"],
+    ["opt ' e", "an accent: é"],
+]
+
+[[scope]]
+id = "launcher"
+title = "The Launcher"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "open the App"],
+]
+
+[[scope]]
+id = "setup"
+title = "Setup, a step"
+rows = [
+    ["Enter", "continue"],
+    ["`", "the step before"],
+]
+
+[[scope]]
+id = "setup-choice"
+title = "Setup, a choice"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "choose it, next step"],
+    ["`", "the step before"],
+]
+
+[[scope]]
+id = "setup-text"
+title = "Setup, a name"
+rows = [
+    ["Enter", "next step"],
+    ["`", "the step before"],
+    ["Del", "delete backwards"],
+    ["Fn , /", "move the cursor"],
+    ["opt ' e", "an accent: é"],
+]
+
+[[scope]]
+id = "irc"
+title = "IRC"
+rows = [
+    ["Enter", "send the line"],
+    ["Tab", "the next buffer"],
+    ["Alt ; .", "scroll back, forward"],
+    ["Fn ; .", "lines you sent before"],
+    ["Fn , /", "move the cursor"],
+    ["Del", "delete backwards"],
+    ["/settings", "server, nick, passwords"],
+    ["/join #x", "join a channel"],
+    ["/part", "leave it"],
+    ["/msg nick", "a private chat"],
+    ["/me", "an action"],
+    ["/nick", "change your nick"],
+    ["/topic", "see or set the topic"],
+    ["/names", "who is there"],
+    ["/quit", "disconnect, and stay so"],
+    ["/raw", "a line as it is"],
+    ["`", "leave: IRC stays connected"],
+]
+
+[[scope]]
+id = "irc-settings"
+title = "IRC settings"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "edit, switch, or save"],
+    ["`", "leave without saving"],
+]
+
+[[scope]]
+id = "irc-field"
+title = "IRC, a setting"
+rows = [
+    ["Enter", "keep it"],
+    ["`", "cancel"],
+    ["Del", "delete backwards"],
+    ["Fn , /", "move the cursor"],
+]
+
+[[scope]]
+id = "wifi-tools"
+title = "Wi-Fi Tools"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "open"],
+]
+
+[[scope]]
+id = "wifi-networks"
+title = "Networks nearby"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "track its signal"],
+    ["s", "sort: signal, channel, name"],
+    ["o", "open networks only"],
+    ["h", "hide the hidden ones"],
+    ["w", "strong ones only"],
+    ["l", "log the scans to the card"],
+]
+
+[[scope]]
+id = "wifi-tracker"
+title = "Signal tracker"
+rows = [
+    ["m", "clicks on or off"],
+]
+
+[[scope]]
+id = "gnss"
+title = "GNSS"
+rows = [
+    ["Tab", "the position, or the sky"],
+    ["r", "record a Track, or stop it"],
+]
+
+[[scope]]
+id = "gemini"
+title = "Gemini, a page"
+rows = [
+    ["Tab", "the next link"],
+    ["Aa Tab", "the link before"],
+    ["Enter", "follow the link"],
+    ["`  Del", "the page before"],
+    ["; .", "scroll"],
+    ["Space", "a page down"],
+    [", /", "sideways, in wide blocks"],
+    ["g", "type an address"],
+    ["b", "bookmark this page"],
+    ["s", "save the page to the card"],
+    ["S", "...with the pages it links to"],
+]
+
+[[scope]]
+id = "gemini-saved"
+title = "Gemini, a Saved Page"
+rows = [
+    ["Tab", "the next link"],
+    ["Aa Tab", "the link before"],
+    ["Enter", "follow the link"],
+    ["`  Del", "the page before"],
+    ["; .", "scroll"],
+    ["Space", "a page down"],
+    [", /", "sideways, in wide blocks"],
+    ["g", "type an address"],
+    ["b", "bookmark this page"],
+    ["r", "refresh this Saved Page"],
+    ["d", "delete this Saved Page"],
+]
+
+[[scope]]
+id = "gemini-address"
+title = "Gemini, an address"
+rows = [
+    ["Enter", "go there"],
+    ["`", "cancel"],
+    ["Del", "delete backwards"],
+    ["Fn , /", "move the cursor"],
+]
+
+[[scope]]
+id = "gemini-answer"
+title = "Gemini, an answer to a page"
+rows = [
+    ["Enter", "send it"],
+    ["`", "cancel"],
+    ["Del", "delete backwards"],
+    ["Fn , /", "move the cursor"],
+]
+
+[[scope]]
+id = "lora"
+title = "LoRa Scanner, the packets"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "the packet's details"],
+    ["p", "pick a Meshtastic preset"],
+    ["c", "start a Capture, or stop it"],
+    ["Tab", "the Sweep"],
+]
+
+[[scope]]
+id = "lora-packet"
+title = "LoRa Scanner, a packet"
+rows = [
+    ["; .", "scroll"],
+    ["Enter", "back to the list"],
+]
+
+[[scope]]
+id = "lora-presets"
+title = "LoRa Scanner, the presets"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "listen with this preset"],
+]
+
+[[scope]]
+id = "lora-sweep"
+title = "LoRa Scanner, the Sweep"
+rows = [
+    ["Tab", "the Sniffer"],
+]
+
+[[scope]]
+id = "storage"
+title = "Storage, a folder"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "open the folder or the file"],
+    [", /", "a page up, down"],
+    ["c  x", "copy, cut"],
+    ["v", "paste here"],
+    ["r", "rename"],
+    ["d  Del", "delete, after asking"],
+    ["n", "a new folder"],
+    ["i", "details: size, date, type"],
+    ["s", "sort: name, date, size"],
+    ["m", "Maintenance: clean-up, erase"],
+    ["`", "the folder above"],
+]
+
+[[scope]]
+id = "storage-details"
+title = "Storage, an item's details"
+rows = [
+    ["; .", "scroll"],
+    ["Enter", "back to the folder"],
+]
+
+[[scope]]
+id = "storage-name"
+title = "Storage, a name"
+rows = [
+    ["Enter", "rename it, or make the folder"],
+    ["`", "cancel"],
+    ["Del", "delete backwards"],
+    ["Fn , /", "move the cursor"],
+]
+
+[[scope]]
+id = "storage-busy"
+title = "Storage, while it copies or deletes"
+rows = [
+    ["`", "stop the copy or the delete"],
+]
+
+[[scope]]
+id = "maintenance"
+title = "Storage, Maintenance"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "open, or choose"],
+]
+
+[[scope]]
+id = "viewer-text"
+title = "A file, as text"
+rows = [
+    ["; .", "a line up, down"],
+    [", /", "a page up, down"],
+    ["t  b", "the top, the end"],
+    ["e", "edit it (up to 16 KB)"],
+    ["Tab", "the file as hex, or back"],
+]
+
+[[scope]]
+id = "viewer-hex"
+title = "A file, as hex"
+rows = [
+    ["; .", "a line up, down"],
+    [", /", "a page up, down"],
+    ["t  b", "the top, the end"],
+    ["Tab", "the file as text, or back"],
+]
+
+[[scope]]
+id = "viewer-pcap"
+title = "A Capture"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "the packet"],
+    [", /", "a page up, down"],
+    ["Tab", "the file as hex"],
+]
+
+[[scope]]
+id = "viewer-packet"
+title = "A Capture's packet"
+rows = [
+    ["; .", "scroll"],
+    ["Enter", "back to the packets"],
+]
+
+[[scope]]
+id = "viewer-gpx"
+title = "A Track"
+rows = [
+    ["Tab", "the file as text"],
+]
+
+[[scope]]
+id = "viewer-ota"
+title = "An Update File"
+rows = [
+    ["Enter", "install it, if it's genuine"],
+    ["Tab", "the file as hex"],
+]
+
+[[scope]]
+id = "notes"
+title = "Notes, the list"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "open the note"],
+    [", /", "a page up, down"],
+    ["n", "a new note"],
+    ["r", "rename its file"],
+    ["d  Del", "delete it"],
+    ["s", "sort: newest, or by name"],
+]
+
+[[scope]]
+id = "notes-editor"
+title = "Notes, the editor"
+rows = [
+    ["Enter", "a new line"],
+    ["Del", "delete backwards"],
+    ["Tab", "two spaces"],
+    ["Fn ; . , /", "move the cursor"],
+    ["Alt Fn ; .", "a page up, down"],
+    ["Ctrl a  e", "start, end of the line"],
+    ["opt ' e", "an accent: é"],
+    ["`", "done: it saves by itself"],
+]
+
+[[scope]]
+id = "notes-name"
+title = "Notes, a file name"
+rows = [
+    ["Enter", "rename the file"],
+    ["`", "cancel"],
+    ["Del", "delete backwards"],
+    ["Fn , /", "move the cursor"],
+]
+
+[[scope]]
+id = "shell"
+title = "Shell"
+rows = [
+    ["Enter", "run the line"],
+    ["Tab", "complete: a command, a path"],
+    ["* ?", "several files: /notes/*.txt"],
+    ["Fn ; .", "lines you typed before"],
+    ["Alt ; .", "scroll back, forward"],
+    ["Ctrl b", "your replies only, or all"],
+    ["Fn , /", "move the cursor"],
+    ["Del", "delete backwards"],
+    ["help", "every command"],
+    ["clear", "an empty screen"],
+    ["Notes", "an App, by its name"],
+    ["rm -rf", "delete without being asked"],
+    ["quit  `", "leave the Shell"],
+]
+
+[[scope]]
+id = "system"
+title = "System, any view"
+rows = [
+    ["Tab", "the next view"],
+    ["Aa Tab", "the view before"],
+]
+
+[[scope]]
+id = "system-tasks"
+title = "System, the tasks"
+rows = [
+    ["Tab", "the next view"],
+    ["Aa Tab", "the view before"],
+    ["; .", "scroll"],
+    ["s", "sort: cpu, stack, name"],
+]
+
+[[scope]]
+id = "system-system"
+title = "System, the system view"
+rows = [
+    ["Tab", "the next view"],
+    ["Aa Tab", "the view before"],
+    ["; .", "scroll"],
+]
+
+[[scope]]
+id = "settings"
+title = "Settings"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "edit, or open the page"],
+    [", /", "change a switch or a slider"],
+]
+
+[[scope]]
+id = "settings-choice"
+title = "Settings, a choice"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "choose it"],
+]
+
+[[scope]]
+id = "wifi"
+title = "Settings, Wi-Fi"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "open, or change"],
+    [", /", "switch Wi-Fi on or off"],
+]
+
+[[scope]]
+id = "wifi-servers"
+title = "Settings, DNS and NTP"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "edit"],
+    [", /", "Always use my DNS: on, off"],
+]
+
+[[scope]]
+id = "wifi-network"
+title = "Settings, a saved network"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "edit, or forget"],
+    [", /", "Automatic or Fixed"],
+]
+
+[[scope]]
+id = "wifi-status"
+title = "Settings, the Wi-Fi status"
+rows = [
+    ["Enter", "back"],
+]
+
+[[scope]]
+id = "wifi-scan"
+title = "Settings, adding a network"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "choose this network"],
+]
+
+[[scope]]
+id = "wifi-name"
+title = "Settings, a hidden network's name"
+rows = [
+    ["Enter", "next: the password"],
+    ["`", "cancel"],
+    ["Del", "delete backwards"],
+    ["Fn , /", "move the cursor"],
+]
+
+[[scope]]
+id = "firmware"
+title = "Settings, Firmware"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "check, open, or install"],
+    ["c", "look for a newer release"],
+]
+
+[[scope]]
+id = "firmware-release"
+title = "Settings, a release"
+rows = [
+    ["; .", "scroll"],
+    ["Enter", "install it"],
+    ["c", "check again"],
+]
+
+[[scope]]
+id = "firmware-older"
+title = "Settings, older releases"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "its details"],
+    ["c", "read the list again"],
+]
+
+[[scope]]
+id = "debug-console"
+title = "Settings, Debug Console"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "switch, or open"],
+    [", /", "switch the console on or off"],
+]
+
+[[scope]]
+id = "demo"
+title = "The widget demo"
+rows = [
+    ["; .", "up, down"],
+    ["Enter", "try the widget"],
+]

site/static/css/site.css

@@ -254,3 +254,12 @@ footer small { display: block; max-width: 760px; }
 .source { max-width: 820px; font-size: 14px; line-height: 20px; }
 .source code { background: var(--s2); padding: 0 6px; }
 .card.featured { flex-basis: 100%; }
+
+/* The keys of a screen, as the device's help panel lists them (the `keys` shortcode) */
+.keys { display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: 16px 32px; }
+.keys-scope { background: var(--s2); padding: 16px 20px; }
+.keys-scope h4 { font: 500 12px/16px var(--mono); letter-spacing: .08em; text-transform: uppercase; color: var(--cyantext); margin: 0 0 8px; }
+.prose .keys table { width: 100%; }
+.prose .keys td { padding: 4px 8px 4px 0; border-bottom: 0; font-size: 15px; }
+.prose .keys td:first-child { white-space: nowrap; width: 1%; padding-right: 16px; }
+.prose .keys kbd { white-space: pre; }

site/templates/index.html

@@ -68,7 +68,7 @@
     </article>
     {% endfor %}
   </div>
-  <p class="cards-note">Plus Settings, with its Wi-Fi and Firmware pages. Every App has a page in the <a class="accent-link" href="/guide/">user guide</a>.</p>
+  <p class="cards-note">Plus a Shell that runs the firmware's commands on the device, and Settings, with its Wi-Fi and Firmware pages. Every App has a page in the <a class="accent-link" href="/guide/">user guide</a>.</p>
 </section>
 
 <section class="wrap" id="screens" aria-labelledby="screens-title">

site/templates/shortcodes/keys.html

@@ -0,0 +1,18 @@
+{#- The keys of one or more screens, as the help panel (Fn+h) lists them on the device:
+    {{ keys(scopes=["storage", "storage-details"]) }}, or {{ keys(all=true) }} for every screen.
+    The tables come from site/data/keys.toml, generated from lib/core/src/app_keys.h (issue #72):
+    a key added to an App shows up here without anyone editing a page. -#}
+{%- set data = load_data(path="data/keys.toml", format="toml") -%}
+{%- set everything = all is defined and all -%}
+<div class="keys">
+{%- for s in data.scope %}{% if everything or (scopes is defined and s.id in scopes) %}
+<div class="keys-scope">
+<h4 id="keys-{{ s.id }}">{{ s.title }}</h4>
+<table>
+{%- for r in s.rows %}
+<tr><td><kbd>{{ r.0 }}</kbd></td><td>{{ r.1 }}</td></tr>
+{%- endfor %}
+</table>
+</div>
+{%- endif %}{% endfor %}
+</div>

site/tools/gen_dev_docs.py

@@ -9,6 +9,8 @@ Zola cannot read a file outside its own folder, so the pages are generated and c
   milestones/ one page for each docs/milestones/*.md
   build/build-and-test, build/flash   sections of README.md
   debug/commands   the commands the firmware's `help` prints (parsed from src/main.cpp), then README's table of them
+  site/data/keys.toml   every screen's keys, from lib/core/src/app_keys.h: what the help panel (Fn+h) shows on the
+                   device, for the `keys` shortcode of the user guide (issue #72)
 Every generated page says where it comes from; edit that file, not the page. Hand-written pages sit next to them.
 """
 import json
@@ -23,7 +25,7 @@ REPO = SITE.parent
 OUT = SITE / "content" / "dev"
 REPO_URL = re.search(r'repo\s*=\s*"([^"]+)"', (SITE / "config.toml").read_text()).group(1)
 
-MILESTONES = ["OTA", "M2", "G1", "M3", "S1", "F1", "R1", "W1"]  # in the order they were done
+MILESTONES = ["OTA", "M2", "G1", "M3", "S1", "F1", "R1", "W1", "U1"]  # in the order they were done
 # Left out on purpose: docs/milestones/M0.md, M1.md and CONTEXT.md (the glossary) describe Wi-Fi monitoring, which this site does not publish.
 # They stay in the repository.
 
@@ -139,8 +141,38 @@ def safe_mode_commands():
     return exact, prefix
 
 
+def key_tables():
+    """Every table of lib/core/src/app_keys.h: [(id, title, [(keys, action), ...])], in the file's order."""
+    src = (REPO / "lib" / "core" / "src" / "app_keys.h").read_text()
+
+    def text(literal):  # a C string literal's contents: \xHH bytes are UTF-8
+        raw = re.sub(r"\\x([0-9A-Fa-f]{2})", lambda m: chr(int(m.group(1), 16)), literal).replace('\\"', '"')
+        return raw.encode("latin-1").decode("utf-8")
+
+    tables = []
+    for m in re.finditer(r"// ([a-z0-9-]+): ([^\n]+)\ninline constexpr KeyHelp k\w+\[\] = \{\n(.*?)\n\};", src, re.S):
+        rows = [(text(k), text(a)) for k, a in re.findall(r'\{"((?:[^"\\]|\\.)*)", "((?:[^"\\]|\\.)*)"\},', m.group(3))]
+        if len(rows) != len([l for l in m.group(3).splitlines() if l.strip()]):
+            sys.exit(f"gen_dev_docs: a row of `{m.group(1)}` in app_keys.h isn't in the form {{\"keys\", \"action\"}},")
+        tables.append((m.group(1), m.group(2).strip(), rows))
+    declared = len(re.findall(r"^inline constexpr KeyHelp k\w+\[\]", src, re.M))
+    if len(tables) != declared or len({t[0] for t in tables}) != len(tables):
+        sys.exit(f"gen_dev_docs: app_keys.h has {declared} tables, {len(tables)} with an `// id: Title` comment and a unique id")
+    return tables
+
+
+def keys_toml():
+    out = ["# Generated by site/tools/gen_dev_docs.py from lib/core/src/app_keys.h: the keys of every screen, as the",
+           "# help panel (Fn+h) lists them on the device. Edit that header, not this file.", ""]
+    for ident, title, rows in key_tables():
+        out += ["[[scope]]", f"id = {json.dumps(ident)}", f"title = {json.dumps(title, ensure_ascii=False)}", "rows = ["]
+        out += [f"    [{json.dumps(k, ensure_ascii=False)}, {json.dumps(a, ensure_ascii=False)}]," for k, a in rows]
+        out += ["]", ""]
+    return "\n".join(out)
+
+
 def build():
-    pages = {}
+    pages = {"../../data/keys.toml": keys_toml()}
 
     for path in sorted((REPO / "docs" / "adr").glob("*.md")):
         title, body = title_and_body(path.read_text())
@@ -179,9 +211,25 @@ def build():
     return pages
 
 
+def unknown_scopes():
+    """Scopes a page asks the `keys` shortcode for that app_keys.h doesn't have."""
+    known = {t[0] for t in key_tables()}
+    bad = []
+    for path in sorted((SITE / "content").rglob("*.md")):
+        for call in re.findall(r"keys\(scopes=\[([^\]]*)\]", path.read_text()):
+            for ident in re.findall(r'"([^"]+)"', call):
+                if ident not in known:
+                    bad.append(f"{path.relative_to(SITE)}: no key table `{ident}` in lib/core/src/app_keys.h")
+    return bad
+
+
 def main():
     check = "--check" in sys.argv
     pages = build()
+    for problem in unknown_scopes():
+        print("gen_dev_docs:", problem)
+    if unknown_scopes():
+        sys.exit(1)
     stale = []
     for rel, text in sorted(pages.items()):
         path = OUT / rel
@@ -193,10 +241,10 @@ def main():
                 path.write_text(text)
     if check:
         for rel in stale:
-            print(f"gen_dev_docs: content/dev/{rel} is out of date: run site/tools/gen_dev_docs.py and commit the result")
-        print(f"gen_dev_docs: {len(pages)} pages, {len(stale)} out of date")
+            print(f"gen_dev_docs: {os.path.normpath(os.path.join('site/content/dev', rel))} is out of date: run site/tools/gen_dev_docs.py and commit the result")
+        print(f"gen_dev_docs: {len(pages)} files, {len(stale)} out of date")
         sys.exit(1 if stale else 0)
-    print(f"gen_dev_docs: {len(pages)} pages, {len(stale)} written")
+    print(f"gen_dev_docs: {len(pages)} files, {len(stale)} written")
 
 
 if __name__ == "__main__":

src/apps/debug_console_page.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "apps/debug_console_page.h"
 
 #include "debug_auth.h"
@@ -74,6 +75,12 @@ bool DebugConsolePage::onKey(const KeyEvent& e) {
     return true;
 }
 
+void DebugConsolePage::help(std::vector<KeyHelp>& out) const {
+    if (confirm_) return keys::add(out, keys::kDialog);
+    if (typing_) return keys::add(out, keys::kText);
+    keys::add(out, keys::kDebugConsole);
+}
+
 void DebugConsolePage::draw(Canvas& c) {
     const auto& area = theme::kContent;
     c.setTextDatum(top_left);
@@ -84,8 +91,6 @@ void DebugConsolePage::draw(Canvas& c) {
         widgets::lineEditor(c, editor_, {4, area.y + 22, area.w - 8, 0});
         c.setTextColor(refusal_.empty() ? theme::kMuted : theme::kWarning);
         c.drawString(refusal_.empty() ? "16 to 64 characters. Capitals or not, it's the same." : refusal_.c_str(), 4, area.y + 44);
-        c.setTextColor(theme::kMuted);
-        c.drawString("Enter: save   `: cancel", 4, area.y + 44 + theme::kLineHeight);
         return;
     }
 

src/apps/debug_console_page.h

@@ -5,6 +5,7 @@
 
 #include "dialog_model.h"
 #include "key_event.h"
+#include "key_help.h"
 #include "line_editor.h"
 #include "list_model.h"
 #include "services/wifi_service.h"
@@ -25,6 +26,8 @@ class DebugConsolePage {
     bool onKey(const KeyEvent& e);  // false: leave the page
     bool textEntryActive() const { return typing_; }
     void draw(Canvas& c);
+    void help(std::vector<KeyHelp>& out) const;
+    const char* helpTitle() const { return typing_ ? "A token of your own" : "Debug Console"; }
 
    private:
     enum Row { kSwitch, kAddress, kNewToken, kTypeToken, kRows };

src/apps/demo_app.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "demo_app.h"
 
 #include "ui/widgets.h"
@@ -25,6 +26,12 @@ void DemoApp::notify(const char* text, NotificationLevel level) {
     bus_.publish(Event::withText(EventType::Notification, text, static_cast<int32_t>(level)));
 }
 
+void DemoApp::help(std::vector<KeyHelp>& out) const {
+    if (dialog_) return keys::add(out, keys::kDialog);
+    if (page_ == Page::Editor) return keys::add(out, keys::kText);
+    if (page_ == Page::Menu) keys::add(out, keys::kDemo);
+}
+
 bool DemoApp::onKey(const KeyEvent& e) {
     requestRedraw();
     if (dialog_) {
@@ -97,7 +104,7 @@ void DemoApp::draw(Canvas& c) {
         }
         case Page::Editor:
             c.setTextColor(theme::kMuted);
-            c.drawString("Type (opt ' e = \xC3\xA9). Enter: toast", 4, area.y + 4);
+            c.drawString("A line editor", 4, area.y + 4);
             widgets::lineEditor(c, editor_, {4, area.y + 22, area.w - 8, 0});
             c.setTextColor(theme::kMuted);
             c.drawString((std::to_string(editor_.text().size()) + "/39 bytes").c_str(), 4, area.y + 44);

src/apps/demo_app.h

@@ -21,6 +21,7 @@ class DemoApp : public App {
     bool onKey(const KeyEvent& e) override;
     bool textEntryActive() const override { return page_ == Page::Editor && !dialog_; }
     void draw(Canvas& c) override;
+    void help(std::vector<KeyHelp>& out) const override;
 
    private:
     enum class Page { Menu, Text, Editor };

src/apps/file_viewer.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "file_viewer.h"
 
 #include <Arduino.h>
@@ -265,6 +266,18 @@ void FileViewer::openPacket(int index) {
     mode_ = Mode::Packet;
 }
 
+void FileViewer::help(std::vector<KeyHelp>& out) const {
+    if (confirm_) return keys::add(out, keys::kDialog);
+    switch (mode_) {
+        case Mode::Text: keys::add(out, keys::kViewerText); break;
+        case Mode::Hex: keys::add(out, keys::kViewerHex); break;
+        case Mode::Pcap: keys::add(out, keys::kViewerPcap); break;
+        case Mode::Packet: keys::add(out, keys::kViewerPacket); break;
+        case Mode::Gpx: keys::add(out, keys::kViewerGpx); break;
+        case Mode::Ota: keys::add(out, keys::kViewerOta); break;
+    }
+}
+
 bool FileViewer::onKey(const KeyEvent& e) {
     if (confirm_) {
         confirm_->onKey(e);
@@ -380,7 +393,7 @@ void FileViewer::draw(Canvas& c) {
     refresh();
     c.setTextDatum(top_left);
     theme::Rect body{area.x, area.y + 10, area.w, kRows * theme::kLineHeight};
-    std::string right, keys = "Tab: hex";
+    std::string right;
     bool scanning = scan_ && !scan_->done;
 
     switch (mode_) {
@@ -396,8 +409,6 @@ void FileViewer::draw(Canvas& c) {
                 c.fillRect(area.w - 2, barY, 2, barH, theme::kMuted);
             }
             right = formatBytes(size_);
-            keys = std::string("Tab: ") + (mode_ != base_ ? "back" : mode_ == Mode::Text ? "hex" : "text") + "  t: top  b: end";
-            if (mode_ == Mode::Text) keys += "  e: edit";
             break;
         }
         case Mode::Gpx: {
@@ -407,7 +418,6 @@ void FileViewer::draw(Canvas& c) {
             else if (scan_) lines = scan_->gpx.lines();
             widgets::textLines(c, lines, 0, body);
             right = formatBytes(size_);
-            keys = "Tab: the file as text";
             break;
         }
         case Mode::Pcap: {
@@ -423,7 +433,6 @@ void FileViewer::draw(Canvas& c) {
                     return row < shown_.size() ? shown_[row] : std::string();
                 });
                 right = std::to_string(scan_->packets.size()) + (scan_->morePackets ? "+ packets" : " packets");
-                keys = "Enter: the packet  Tab: hex";
             }
             break;
         }
@@ -447,7 +456,6 @@ void FileViewer::draw(Canvas& c) {
             }
             widgets::textLines(c, lines, 0, body);
             right = formatBytes(size_);
-            keys = ok ? "Enter: install  Tab: hex" : "Tab: hex";
             if (confirm_) {
                 widgets::dialog(c, "Install update?", "The device restarts into " + scan_->version + " once it's written.", *confirm_);
                 return;
@@ -464,7 +472,7 @@ void FileViewer::draw(Canvas& c) {
     c.drawString(right.c_str(), area.w - 3, area.y + 1);
     c.setTextDatum(top_left);
     if (!message_.empty()) c.setTextColor(theme::kWarning);
-    c.drawString(message_.empty() ? keys.c_str() : message_.c_str(), 4, area.y + area.h - 9);
+    if (!message_.empty()) c.drawString(message_.c_str(), 4, area.y + area.h - 9);
 }
 
 }  // namespace roro

src/apps/file_viewer.h

@@ -7,6 +7,7 @@
 #include <vector>
 
 #include "dialog_model.h"
+#include "key_help.h"
 #include "key_event.h"
 #include "list_model.h"
 #include "services/storage_service.h"
@@ -27,6 +28,7 @@ class FileViewer {
     void open(const std::string& path, uint32_t size);
     void close();
     bool onKey(const KeyEvent& e);  // false: leave the viewer
+    void help(std::vector<KeyHelp>& out) const;
     bool update(uint32_t nowMs);    // true: draw again
     void draw(Canvas& c);
 

src/apps/firmware_page.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "firmware_page.h"
 
 #include <SD.h>
@@ -63,9 +64,9 @@ std::string FirmwarePage::latestText(bool& warn) const {
     release::Release r;
     if (g.status() == GiteaReleases::Status::Failed && !g.latest(r)) {
         warn = true;
-        return "failed: Enter retries";
+        return "the check failed";
     }
-    if (!g.latest(r)) return "Enter: check";
+    if (!g.latest(r)) return "not checked yet";
     return r.tag + (release::isNewer(r, update_.runningVersion()) ? " (new)" : " (current)");
 }
 
@@ -202,7 +203,7 @@ void FirmwarePage::drawRelease(Canvas& c) {
     c.setFont(&fonts::small);
     c.setTextDatum(top_left);
     c.setTextColor(theme::kMuted);
-    c.drawString(ok ? "Enter: install   c: check again" : (why + "   c: check").c_str(), 4, area.y + area.h - 9);
+    if (!ok) c.drawString(why.c_str(), 4, area.y + area.h - 9);  // why it can't be installed from here
 }
 
 void FirmwarePage::drawOlder(Canvas& c) {
@@ -232,9 +233,19 @@ void FirmwarePage::drawOlder(Canvas& c) {
             return r.tag + (r.tag == running ? "  (running)" : release::versionNewer(r.tag, running) ? "  (new)" : "");
         },
         [&](int i) { return olderReleases_[i].date(); });
-    c.setFont(&fonts::small);
-    c.setTextColor(theme::kMuted);
-    c.drawString("Enter: details   c: look again", 4, area.y + area.h - 9);
+}
+
+void FirmwarePage::help(std::vector<KeyHelp>& out) const {
+    if (confirm_) return keys::add(out, keys::kDialog);
+    switch (view_) {
+        case View::Main: keys::add(out, keys::kFirmware); break;
+        case View::Release: keys::add(out, keys::kFirmwareRelease); break;
+        case View::Older: keys::add(out, keys::kFirmwareOlder); break;
+    }
+}
+
+const char* FirmwarePage::helpTitle() const {
+    return view_ == View::Release ? "A release" : view_ == View::Older ? "Older releases" : "Firmware";
 }
 
 void FirmwarePage::drawMain(Canvas& c) {

src/apps/firmware_page.h

@@ -7,6 +7,7 @@
 
 #include "dialog_model.h"
 #include "key_event.h"
+#include "key_help.h"
 #include "list_model.h"
 #include "release_info.h"
 #include "services/storage_service.h"
@@ -28,6 +29,8 @@ class FirmwarePage {
     void enter();
     bool onKey(const KeyEvent& e);  // false: leave the page
     void draw(Canvas& c);
+    void help(std::vector<KeyHelp>& out) const;
+    const char* helpTitle() const;
 
    private:
     enum Row { kVersion, kStatus, kAddress, kLatest, kOlder, kSdHeader, kFixed };

src/apps/gemini_app.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "gemini_app.h"
 
 #include <Arduino.h>
@@ -171,7 +172,7 @@ void GeminiApp::update(uint32_t nowMs) {
                         else {
                             std::string mime = result.header.mimeType();
                             showMessage(url, "# Not a text page\nThis is " + mime +
-                                                 ", which the Cardputer can't show. s saves it to the card, in "
+                                                 ", which the Cardputer can't show. Saving it puts it on the card, in "
                                                  "/gemini/downloads.\n");
                             page_.header.meta = mime;  // so s knows to download it
                         }
@@ -302,6 +303,18 @@ void GeminiApp::selectLink(int direction) {
     requestRedraw();
 }
 
+void GeminiApp::help(std::vector<KeyHelp>& out) const {
+    if (certDialog_ || deleteDialog_) return keys::add(out, keys::kDialog);
+    if (inputOpen_) return keys::add(out, keys::kGeminiAnswer);
+    if (addressOpen_) return keys::add(out, keys::kGeminiAddress);
+    if (isSaved()) keys::add(out, keys::kGeminiSaved);
+    else keys::add(out, keys::kGemini);
+}
+
+const char* GeminiApp::helpTitle() const {
+    return inputOpen_ ? "Gemini: an answer" : addressOpen_ ? "Gemini: an address" : nullptr;
+}
+
 bool GeminiApp::onKey(const KeyEvent& e) {
     requestRedraw();
     if (certDialog_) {
@@ -388,7 +401,7 @@ bool GeminiApp::onKey(const KeyEvent& e) {
                     if (isGemini(page_.base())) gemini_.addBookmark(page_.base(), titleOf());
                     break;
                 case 's':  // Q82, Q73
-                    if (isSaved()) status_ = "Already saved; r refreshes it";
+                    if (isSaved()) status_ = "Already saved: it can be refreshed";
                     else if (!isGemini(page_.url)) status_ = "Only Gemini pages can be saved";
                     else if (page_.header.mimeType().rfind("text/", 0) == 0) gemini_.save(page_.url);
                     else gemini_.download(page_.url);
@@ -485,7 +498,7 @@ void GeminiApp::draw(Canvas& c) {
         c.fillRect(box.x - 2, box.y - 12, box.w + 4, box.h + 14, theme::kBackground);
         c.setFont(&fonts::small);
         c.setTextColor(theme::kMuted);
-        c.drawString("Go to (Enter, or ` to cancel)", box.x, box.y - 10);
+        c.drawString("Go to", box.x, box.y - 10);
         widgets::lineEditor(c, address_, box);
     }
     if (inputOpen_) {
@@ -496,7 +509,7 @@ void GeminiApp::draw(Canvas& c) {
         c.drawString(displayText(inputPrompt_).substr(0, 39).c_str(), box.x, box.y - 22);
         c.setFont(&fonts::small);
         c.setTextColor(theme::kMuted);
-        c.drawString(inputSensitive_ ? "(hidden) Enter sends, ` cancels" : "Enter sends, ` cancels", box.x, box.y - 9);
+        if (inputSensitive_) c.drawString("(hidden)", box.x, box.y - 9);
         if (inputSensitive_) {
             LineEditor masked(1024);
             masked.setText(std::string(input_.text().size(), '*'));

src/apps/gemini_app.h

@@ -24,6 +24,8 @@ class GeminiApp : public App {
     bool textEntryActive() const override { return addressOpen_ || inputOpen_; }
     void update(uint32_t nowMs) override;
     void draw(Canvas& c) override;
+    void help(std::vector<KeyHelp>& out) const override;
+    const char* helpTitle() const override;
 
    private:
     struct Visit {

src/apps/gnss_app.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "gnss_app.h"
 
 #include <Arduino.h>
@@ -80,11 +81,10 @@ void GnssApp::draw(Canvas& c) {
         return;
     }
     sky_ ? drawSky(c) : drawPosition(c);
-    c.setFont(&fonts::small);
-    c.setTextColor(theme::kMuted);
-    c.setTextDatum(top_right);
-    c.drawString(sky_ ? "Tab: position" : "Tab: sky", area.w - 3, area.y + area.h - 9);
-    c.setTextDatum(top_left);
+}
+
+void GnssApp::help(std::vector<KeyHelp>& out) const {
+    keys::add(out, keys::kGnss);
 }
 
 void GnssApp::drawPosition(Canvas& c) {
@@ -139,15 +139,12 @@ void GnssApp::drawPosition(Canvas& c) {
     c.setFont(&fonts::small);
     if (gnss_.tracking()) {
         c.setTextColor(theme::kWarning);
-        std::snprintf(line, sizeof line, "REC %d point%s, %s  r: stop", gnss_.trackPoints(),
+        std::snprintf(line, sizeof line, "REC %d point%s, %s", gnss_.trackPoints(),
                       gnss_.trackPoints() == 1 ? "" : "s", duration(now - gnss_.trackStartMs()).c_str());
     } else if (!refusal_.empty() && now - refusalMs_ < 4000) {
         c.setTextColor(theme::kWarning);
         std::snprintf(line, sizeof line, "%s", refusal_.c_str());
-    } else {
-        c.setTextColor(theme::kMuted);
-        std::snprintf(line, sizeof line, "r: record a Track");
-    }
+    } else line[0] = 0;
     c.drawString(line, 4, area.y + area.h - 9);
 }
 

src/apps/gnss_app.h

@@ -17,6 +17,7 @@ class GnssApp : public App {
     bool onKey(const KeyEvent& e) override;
     void update(uint32_t nowMs) override;
     void draw(Canvas& c) override;
+    void help(std::vector<KeyHelp>& out) const override;
 
    private:
     void drawPosition(Canvas& c);

src/apps/irc_app.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "irc_app.h"
 
 #include "ui/fonts.h"
@@ -299,6 +300,16 @@ void IrcApp::drawChat(Canvas& c) {
     widgets::lineEditor(c, input_, {2, area.y + area.h - inputH, area.w - 4, 0});
 }
 
+void IrcApp::help(std::vector<KeyHelp>& out) const {
+    if (page_ == Page::Chat) return keys::add(out, keys::kIrc);
+    if (editing_) return keys::add(out, keys::kIrcField);
+    keys::add(out, keys::kIrcSettings);
+}
+
+const char* IrcApp::helpTitle() const {
+    return page_ == Page::Settings ? (editing_ ? "IRC: a setting" : "IRC settings") : nullptr;
+}
+
 void IrcApp::drawSettings(Canvas& c) {
     const auto& area = theme::kContent;
     if (editing_) {
@@ -306,8 +317,7 @@ void IrcApp::drawSettings(Canvas& c) {
         c.setTextColor(theme::kMuted);
         c.drawString(fieldLabel(fields_.selected()).c_str(), 4, area.y + 4);
         widgets::lineEditor(c, fieldEditor_, {4, area.y + 22, area.w - 8, 0});
-        c.drawString(fields_.selected() == kAutojoin ? "e.g. #roro, #private key" : "Enter: OK   `: cancel", 4,
-                     area.y + 44);
+        if (fields_.selected() == kAutojoin) c.drawString("e.g. #roro, #private key", 4, area.y + 44);
         return;
     }
     widgets::list(

src/apps/irc_app.h

@@ -24,6 +24,8 @@ class IrcApp : public App {
     void update(uint32_t nowMs) override;
     bool textEntryActive() const override { return page_ == Page::Chat || editing_; }
     void draw(Canvas& c) override;
+    void help(std::vector<KeyHelp>& out) const override;
+    const char* helpTitle() const override;
 
    private:
     enum class Page { Chat, Settings };

src/apps/launcher_app.h

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "app.h"
+#include "app_keys.h"
 #include "app_manager.h"
 #include "list_model.h"
 #include "ui/theme.h"
@@ -14,6 +15,7 @@ class LauncherApp : public App {
     void onEnter() override;
     bool onKey(const KeyEvent& e) override;
     void draw(Canvas& c) override;
+    void help(std::vector<KeyHelp>& out) const override { keys::add(out, keys::kLauncher); }
 
    private:
     AppManager* manager_ = nullptr;

src/apps/lora_scanner_app.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "lora_scanner_app.h"
 
 #include <Arduino.h>
@@ -165,6 +166,24 @@ void LoraScannerApp::update(uint32_t nowMs) {
         requestRedraw();
 }
 
+void LoraScannerApp::help(std::vector<KeyHelp>& out) const {
+    switch (view_) {
+        case View::Packets: keys::add(out, keys::kLora); break;
+        case View::Details: keys::add(out, keys::kLoraPacket); break;
+        case View::Presets: keys::add(out, keys::kLoraPresets); break;
+        case View::Sweep: keys::add(out, keys::kLoraSweep); break;
+    }
+}
+
+const char* LoraScannerApp::helpTitle() const {
+    switch (view_) {
+        case View::Details: return "A LoRa packet";
+        case View::Presets: return "LoRa presets";
+        case View::Sweep: return "LoRa Sweep";
+        default: return nullptr;
+    }
+}
+
 void LoraScannerApp::draw(Canvas& c) {
     lastDrawMs_ = millis();
     c.setTextDatum(top_left);
@@ -234,8 +253,7 @@ void LoraScannerApp::drawPackets(Canvas& c) {
     c.setFont(&fonts::small);
     bool showMessage = !message_.empty() && millis() - messageMs_ < kMessageMs;
     c.setTextColor(showMessage ? theme::kWarning : theme::kMuted);
-    std::string keys = std::string("Enter: details  p: preset  Tab: sweep  c: ") + (capture_.capturing() ? "stop" : "capture");
-    c.drawString(showMessage ? message_.c_str() : keys.c_str(), 4, area.y + area.h - 9);
+    if (showMessage) c.drawString(message_.c_str(), 4, area.y + area.h - 9);
 }
 
 void LoraScannerApp::drawDetails(Canvas& c) {
@@ -329,9 +347,9 @@ void LoraScannerApp::drawSweep(Canvas& c) {
     c.drawString(line, x0 + f.steps * cell, wfTop + kWaterfallRows + 1);
     c.setTextDatum(top_left);
     if (st.peaks.empty())
-        std::snprintf(line, sizeof line, "floor %d dBm, nothing above it   Tab: sniffer", st.floor);
+        std::snprintf(line, sizeof line, "floor %d dBm, nothing above it", st.floor);
     else
-        std::snprintf(line, sizeof line, "floor %d, %.1f MHz at %d dBm   Tab: sniffer", st.floor, st.peaks[0].hz / 1e6,
+        std::snprintf(line, sizeof line, "floor %d, %.1f MHz at %d dBm", st.floor, st.peaks[0].hz / 1e6,
                       st.peaks[0].dbm);
     c.setTextColor(theme::kMuted);
     c.drawString(line, 4, y);

src/apps/lora_scanner_app.h

@@ -26,6 +26,8 @@ class LoraScannerApp : public App {
     bool onKey(const KeyEvent& e) override;
     void update(uint32_t nowMs) override;
     void draw(Canvas& c) override;
+    void help(std::vector<KeyHelp>& out) const override;
+    const char* helpTitle() const override;
 
    private:
     enum class View { Packets, Details, Presets, Sweep };

src/apps/maintenance_page.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "maintenance_page.h"
 
 #include "ui/widgets.h"
@@ -35,6 +36,11 @@ CleanupPlan MaintenancePage::planFor(int age) const {
     return CleanupPlan::make(listing_[categories_.selected()], cutoff, today);
 }
 
+void MaintenancePage::help(std::vector<KeyHelp>& out) const {
+    if (dialog_) return keys::add(out, keys::kDialog);
+    keys::add(out, keys::kMaintenance);
+}
+
 bool MaintenancePage::onKey(const KeyEvent& e) {
     if (dialog_) {
         dialog_->onKey(e);

src/apps/maintenance_page.h

@@ -5,6 +5,7 @@
 
 #include "cleanup_plan.h"
 #include "dialog_model.h"
+#include "key_help.h"
 #include "event_bus.h"
 #include "key_event.h"
 #include "list_model.h"
@@ -24,6 +25,7 @@ class MaintenancePage {
     void enter();
     bool onKey(const KeyEvent& e);  // false: leave the page
     void draw(Canvas& c);
+    void help(std::vector<KeyHelp>& out) const;
 
    private:
     enum class View { Main, Categories, Ages };

src/apps/note_editor.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "note_editor.h"
 
 #include <Arduino.h>
@@ -182,6 +183,11 @@ bool NoteEditor::save() {
     return true;
 }
 
+void NoteEditor::help(std::vector<KeyHelp>& out) const {
+    if (dialog_) return keys::add(out, keys::kDialog);
+    keys::add(out, keys::kNotesEditor);
+}
+
 bool NoteEditor::onKey(const KeyEvent& e) {
     if (!text_) return false;
     redraw_ = true;
@@ -290,7 +296,7 @@ void NoteEditor::draw(Canvas& c) {
     c.setFont(&fonts::small);
     bool showMessage = !message_.empty() && millis() - messageMs_ < kMessageMs;
     c.setTextColor(showMessage ? theme::kWarning : theme::kMuted);
-    c.drawString(showMessage ? message_.c_str() : "Fn+arrows: move  Ctrl+A/E: line  Back: done", 4, area.y + area.h - 9);
+    if (showMessage) c.drawString(message_.c_str(), 4, area.y + area.h - 9);
 
     if (dialog_ && ask_ == Ask::Recover)
         widgets::dialog(c, "Unsaved copy", "A save of this note was cut short. Its copy has " + formatBytes(recovered_.size()) + ", the note " +

src/apps/note_editor.h

@@ -5,6 +5,7 @@
 #include <vector>
 
 #include "dialog_model.h"
+#include "key_help.h"
 #include "key_event.h"
 #include "note_text.h"
 #include "services/clock_service.h"
@@ -33,6 +34,7 @@ class NoteEditor {
     const std::string& path() const { return path_; }  // "" for a new note nothing was typed in
 
     bool onKey(const KeyEvent& e);  // false: done, and saved
+    void help(std::vector<KeyHelp>& out) const;
     bool update(uint32_t nowMs);    // true: draw again
     void draw(Canvas& c);
 

src/apps/notes_app.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "notes_app.h"
 
 #include <Arduino.h>
@@ -173,6 +174,18 @@ std::string NotesApp::titleOf(int row) {
     return files::fitName(list_.name(notes_[row]), kTitleChars);  // an empty note, or not a text
 }
 
+void NotesApp::help(std::vector<KeyHelp>& out) const {
+    if (view_ == View::Edit) return editor_.help(out);
+    if (dialog_) return keys::add(out, keys::kDialog);
+    if (view_ == View::Name) return keys::add(out, keys::kNotesName);
+    if (view_ == View::NoMemory) return;
+    keys::add(out, keys::kNotes);
+}
+
+const char* NotesApp::helpTitle() const {
+    return view_ == View::Edit ? "Notes: the editor" : view_ == View::Name ? "Notes: a file name" : nullptr;
+}
+
 bool NotesApp::onKey(const KeyEvent& e) {
     requestRedraw();
     if (view_ == View::NoMemory) return false;
@@ -315,7 +328,6 @@ void NotesApp::draw(Canvas& c) {
     } else if (notes_.empty()) {
         c.setTextColor(theme::kMuted);
         c.drawString("No notes yet.", 4, rows.y + 4);
-        c.drawString("n starts one.", 4, rows.y + 4 + theme::kLineHeight);
     } else {
         readTitles();
         widgets::list(
@@ -329,7 +341,7 @@ void NotesApp::draw(Canvas& c) {
     c.setFont(&fonts::small);
     bool showMessage = !message_.empty() && millis() - messageMs_ < kMessageMs;
     c.setTextColor(showMessage ? theme::kWarning : theme::kMuted);
-    c.drawString(showMessage ? message_.c_str() : "n: new  Enter: open  r: name  d: del  s: sort", 4, area.y + area.h - 9);
+    if (showMessage) c.drawString(message_.c_str(), 4, area.y + area.h - 9);
 
     if (view_ == View::Name) {
         theme::Rect box{16, 44, theme::kWidth - 32, 48};

src/apps/notes_app.h

@@ -28,6 +28,8 @@ class NotesApp : public App {
     bool textEntryActive() const override { return view_ == View::Edit || view_ == View::Name; }
     void update(uint32_t nowMs) override;
     void draw(Canvas& c) override;
+    void help(std::vector<KeyHelp>& out) const override;
+    const char* helpTitle() const override;
 
    private:
     enum class View { List, Edit, Name, NoMemory };

src/apps/settings_app.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "settings_app.h"
 
 #include <Arduino.h>
@@ -129,6 +130,28 @@ bool SettingsApp::onAboutKey(const KeyEvent& e) {
     return true;
 }
 
+void SettingsApp::help(std::vector<KeyHelp>& out) const {
+    switch (page_) {
+        case Page::Menu: keys::add(out, keys::kSettings); break;
+        case Page::Text: keys::add(out, keys::kText); break;
+        case Page::Choice: keys::add(out, keys::kSettingsChoice); break;
+        case Page::About: break;
+        case Page::Wifi: wifiPage_.help(out); break;
+        case Page::Firmware: firmwarePage_.help(out); break;
+        case Page::Debug: debugPage_.help(out); break;
+    }
+}
+
+const char* SettingsApp::helpTitle() const {
+    switch (page_) {
+        case Page::Wifi: return wifiPage_.helpTitle();
+        case Page::Firmware: return firmwarePage_.helpTitle();
+        case Page::Debug: return debugPage_.helpTitle();
+        case Page::About: return "About";
+        default: return nullptr;
+    }
+}
+
 void SettingsApp::update(uint32_t nowMs) {
     // Live values on About and Firmware.
     bool live = page_ == Page::About || page_ == Page::Firmware || page_ == Page::Debug ||
@@ -177,10 +200,8 @@ void SettingsApp::draw(Canvas& c) {
             c.setTextColor(theme::kMuted);
             c.drawString(menu_.label(editingRow_).c_str(), 4, area.y + 4);
             widgets::lineEditor(c, editor_, {4, area.y + 22, area.w - 8, 0});
-            c.drawString(("Enter: save   `: cancel   " + std::to_string(editor_.text().size()) + "/" +
-                          std::to_string(editor_.maxBytes()) + " bytes")
-                             .c_str(),
-                         4, area.y + 44);
+            c.drawString((std::to_string(editor_.text().size()) + " of " + std::to_string(editor_.maxBytes()) + " bytes").c_str(), 4,
+                         area.y + 44);
             break;
         case Page::Choice: {
             auto options = menu_.choices(editingRow_);

src/apps/settings_app.h

@@ -50,6 +50,8 @@ class SettingsApp : public App {
                (page_ == Page::Debug && debugPage_.textEntryActive());
     }
     void draw(Canvas& c) override;
+    void help(std::vector<KeyHelp>& out) const override;
+    const char* helpTitle() const override;
 
    private:
     enum class Page { Menu, Text, Choice, About, Wifi, Firmware, Debug };

src/apps/setup_app.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "setup_app.h"
 
 #include "platform/identity.h"
@@ -44,6 +45,18 @@ bool SetupApp::onKey(const KeyEvent& e) {
     return true;
 }
 
+void SetupApp::help(std::vector<KeyHelp>& out) const {
+    switch (wizard_.step()) {
+        case Step::LongName:
+        case Step::ShortName: keys::add(out, keys::kSetupText); break;
+        case Step::Region:
+        case Step::Timezone: keys::add(out, keys::kSetupChoice); break;
+        default: keys::add(out, keys::kSetup); break;
+    }
+}
+
+// The one place that names keys on the screen (Q200): someone in their first minute doesn't know
+// the help key yet, and this is where they learn it.
 void SetupApp::draw(Canvas& c) {
     const auto& area = theme::kContent;
     auto heading = [&](const char* text) {
@@ -63,6 +76,7 @@ void SetupApp::draw(Canvas& c) {
             heading("Welcome to roro9stack");
             note("Let's set up this device: your names on the mesh, your radio region and your timezone.",
                  area.y + 22, theme::kText);
+            note("One key to know: Fn + h lists the keys of the screen you're on.", area.y + 22 + 4 * theme::kLineHeight, theme::kAccent);
             note("Enter: continue", area.y + area.h - 14);
             break;
         case Step::LongName:
@@ -88,8 +102,10 @@ void SetupApp::draw(Canvas& c) {
                           [this](int i) { return wizard_.choiceLabel(i); });
             break;
         case Step::Done:
-            heading("All set");
-            note("You can change all of this later in Settings.", area.y + 22, theme::kText);
+            heading("All set. One key to remember:");
+            note("Fn + h, on any screen, lists the keys that work there. No screen names its keys: that key does. Try it now.",
+                 area.y + 22, theme::kAccent);
+            note("The rest can be changed later in Settings.", area.y + 22 + 4 * theme::kLineHeight, theme::kText);
             note("Enter: start   `: go back", area.y + area.h - 14);
             break;
     }

src/apps/setup_app.h

@@ -17,6 +17,8 @@ class SetupApp : public App {
         return wizard_.step() == SetupWizard::Step::LongName || wizard_.step() == SetupWizard::Step::ShortName;
     }
     void draw(Canvas& c) override;
+    void help(std::vector<KeyHelp>& out) const override;
+    const char* helpTitle() const override { return "Setup"; }
 
    private:
     AppManager& apps_;

src/apps/shell_app.cpp

@@ -0,0 +1,204 @@
+#include "apps/shell_app.h"
+
+#include <Arduino.h>
+
+#include <algorithm>
+
+#include "app_keys.h"
+#include "file_names.h"
+#include "platform/console.h"
+#include "ui/fonts.h"
+#include "ui/theme.h"
+#include "ui/widgets.h"
+
+namespace roro {
+
+namespace {
+
+bool startsWith(const std::string& s, const char* prefix) { return s.rfind(prefix, 0) == 0; }
+
+}  // namespace
+
+void ShellApp::onEnter() {
+    open_ = console.openShellRing();
+    console.shellShowsAll(false);  // its own replies only, each time it's opened
+    ringPos_ = 0;
+    scroll_ = 0;
+    confirm_.reset();
+    // What Tab completes besides the firmware's own commands, written as `help` writes them.
+    ownHelp_ = "help | clear | quit | exit\nkey up|down|left|right|select|back|home|del|tab|space|help\n";
+    log_.clear();
+    log_.add(open_ ? "The console's commands. `help` lists them." : "No memory for the Shell: leave an App, or stop IRC.");
+}
+
+// Nothing is kept once it's left: the ring, the lines and the list of commands all go (Q207).
+void ShellApp::onExit() {
+    console.closeShellRing();
+    console.shellShowsAll(false);
+    open_ = false;
+    log_.clear();
+    std::string().swap(ownHelp_);
+    confirm_.reset();
+}
+
+void ShellApp::update(uint32_t) {
+    uint8_t buf[256];
+    uint32_t skipped = 0;
+    size_t n;
+    while ((n = console.readShellSince(ringPos_, buf, sizeof buf, skipped)) > 0) {
+        if (skipped) log_.add("[... " + std::to_string(skipped) + " bytes lost: more was printed than fits]");
+        log_.feed(reinterpret_cast<const char*>(buf), n);
+    }
+    if (log_.revision() != seenRevision_) {
+        seenRevision_ = log_.revision();
+        requestRedraw();
+    }
+}
+
+void ShellApp::runNow(const std::string& line) {
+    // The runner echoes the line into the console, where the Shell reads it back with the reply,
+    // except a token being set, which goes nowhere (Q210): that one is shown here, masked.
+    if (startsWith(line, "debug token ") && line != "debug token new") log_.add("> debug token ...");
+    run_(line);
+}
+
+void ShellApp::enter(const std::string& line) {
+    history_.add(line);
+    scroll_ = 0;
+    if (line == "quit" || line == "exit") return apps_.home();
+    if (line == "clear") return log_.clear();
+    // Q209: `rm` as Unix has it, with a question where Unix has none, since a slip of the finger is
+    // a key away here. A file, or a folder with something in it, is asked about unless -f says not
+    // to. An empty folder goes without a word; anything `rm` would refuse anyway, it refuses itself.
+    if (startsWith(line, "rm ")) {
+        files::RmArgs args = files::parseRm(line.substr(3));
+        bool ask = false;
+        if (args.force || args.path.empty()) {
+        } else if (files::hasGlob(args.path)) {  // a pattern: one question for all it matches
+            bool more = false;
+            int n = count_(args.path, more);
+            ask = n > 0 && !more;  // none, or too many: `rm` says so itself
+            question_ = "The " + std::to_string(n) + " that match " + args.path + (args.recursive ? ", folders and what's in them too" : "") + ". It can't be undone.";
+        } else {
+            Target target = probe_(args.path);
+            ask = target == Target::File || (target == Target::FullFolder && args.recursive);
+            question_ = target == Target::File ? args.path + ". It can't be undone." : args.path + " and everything in it. It can't be undone.";
+        }
+        if (ask) {
+            pending_ = line;
+            confirm_.reset(new DialogModel({"Cancel", "Delete"}));
+            return;
+        }
+    }
+    runNow(line);
+}
+
+bool ShellApp::onKey(const KeyEvent& e) {
+    requestRedraw();
+    if (confirm_) {
+        confirm_->onKey(e);
+        if (confirm_->result() == DialogModel::kPending) return true;
+        if (confirm_->result() == 1) runNow(pending_);
+        else log_.add("Not deleted.");
+        confirm_.reset();
+        return true;
+    }
+    // Alt + ; / Alt + . scroll back and forward; Up / Down (Fn + ; / Fn + .) recall earlier lines.
+    if (e.key == Key::Char && e.alt && (e.ch == ';' || e.ch == '.')) {
+        if (e.ch == ';') scroll_++;
+        else if (scroll_ > 0) scroll_--;
+        return true;
+    }
+    if (e.key == Key::Char && e.ctrl && (e.ch == 'b' || e.ch == 'B')) {  // Q206
+        console.shellShowsAll(!console.shellShowsAll());
+        log_.add(console.shellShowsAll() ? "Showing everything the console prints." : "Showing only the replies to your commands.");
+        return true;
+    }
+    std::string recalled;
+    switch (e.key) {
+        case Key::Char: input_.insert(e.ch); break;
+        case Key::Delete: input_.backspace(); break;
+        case Key::Left: input_.left(); break;
+        case Key::Right: input_.right(); break;
+        case Key::Up:
+            if (history_.up(input_.text(), recalled)) input_.setText(recalled);
+            break;
+        case Key::Down:
+            if (history_.down(recalled)) input_.setText(recalled);
+            break;
+        case Key::Tab: {  // the command, every word of it; where its words end, a path on the card
+            std::vector<std::string> matches;
+            PathToComplete path;
+            bool more = false;
+            const std::string typed = input_.text();
+            std::string done = completeWords(typed, (std::string(helpText_) + ownHelp_).c_str(), matches);
+            if (done == typed && matches.empty() && splitForPath(typed, path)) done = completePath(path, list_(path.folder, path.prefix, more), matches);
+            input_.setText(done);
+            if (matches.size() > 1) {
+                std::string all;
+                for (auto& m : matches) all += (all.empty() ? "" : "  ") + m;
+                log_.add(all + (more ? "  ..." : ""));
+            }
+            break;
+        }
+        case Key::Select: {
+            std::string line = input_.text();
+            input_.setText("");
+            if (!line.empty()) enter(line);
+            break;
+        }
+        default: return false;  // Back leaves the Shell
+    }
+    return true;
+}
+
+void ShellApp::help(std::vector<KeyHelp>& out) const {
+    if (confirm_) return keys::add(out, keys::kDialog);
+    keys::add(out, keys::kShell);
+}
+
+void ShellApp::draw(Canvas& c) {
+    const auto& area = theme::kContent;
+    const int inputH = theme::kLineHeight + 4;
+    const theme::Rect output{area.x, area.y, area.w, area.h - inputH - 1};
+    const int rows = output.h / theme::kLineHeight;
+
+    // Wrapped from the newest line backwards, only as far as the screen and the scroll need.
+    std::vector<std::pair<std::string, uint16_t>> shown;  // newest first
+    auto measure = widgets::bodyMeasure(c);
+    c.setFont(&fonts::body);
+    const auto& lines = log_.lines();
+    int needed = rows + scroll_;
+    for (auto it = lines.rbegin(); it != lines.rend() && static_cast<int>(shown.size()) < needed; ++it) {
+        uint16_t color = it->rfind("> ", 0) == 0 ? theme::kAccent : theme::kText;
+        auto wrapped = wrapText(it->empty() ? std::string(" ") : *it, output.w - 8, measure);
+        for (auto w = wrapped.rbegin(); w != wrapped.rend(); ++w) shown.push_back({*w, color});
+    }
+    int total = static_cast<int>(shown.size());
+    if (scroll_ > total - rows) scroll_ = total > rows ? total - rows : 0;
+    c.setClipRect(output.x, output.y, output.w, output.h);
+    for (int r = 0; r < rows; r++) {
+        int i = scroll_ + (rows - 1 - r);  // the row at the bottom is the newest
+        if (i >= total) continue;
+        c.setTextColor(shown[i].second);
+        c.drawString(shown[i].first.c_str(), 4, output.y + r * theme::kLineHeight + 1);
+    }
+    c.clearClipRect();
+
+    // State, not keys: how far back it's scrolled, and whether background lines are hidden.
+    c.setFont(&fonts::small);
+    c.setTextDatum(top_right);
+    if (scroll_ > 0) {
+        c.setTextColor(theme::kWarning);
+        c.drawString(("^ " + std::to_string(scroll_)).c_str(), area.w - 3, output.y + 1);
+    } else if (console.shellShowsAll()) {
+        c.setTextColor(theme::kMuted);
+        c.drawString("all", area.w - 3, output.y + 1);
+    }
+    c.setTextDatum(top_left);
+
+    widgets::lineEditor(c, input_, {2, area.y + area.h - inputH, area.w - 4, 0});
+    if (confirm_) widgets::dialog(c, "Delete?", question_, *confirm_);
+}
+
+}  // namespace roro

src/apps/shell_app.h

@@ -0,0 +1,68 @@
+#pragma once
+
+#include <functional>
+#include <memory>
+#include <string>
+#include <vector>
+
+#include "app.h"
+#include "app_manager.h"
+#include "dialog_model.h"
+#include "input_history.h"
+#include "line_editor.h"
+#include "shell_log.h"
+
+namespace roro {
+
+// The Shell (issue #67): the console's commands on the device's own screen and keyboard. A third
+// place to type them, after USB serial and the Debug Console, and trusted like the first: whoever
+// holds the device can do all of it in Settings anyway (Q205).
+//
+// It shows the replies to its own commands, and only those unless asked otherwise (Q206): the
+// console knows who each line was printed for (Console::Origin) and fills a ring that exists only
+// while the App is open. Nothing is kept once it is left.
+class ShellApp : public App {
+   public:
+    using Run = std::function<void(const std::string& line)>;
+    // What `rm` is pointed at: it decides whether the Shell asks first.
+    enum class Target { Missing, File, EmptyFolder, FullFolder };
+    using Probe = std::function<Target(const std::string& path)>;
+    // A folder's entries that start with `prefix`, whatever their case, a folder's with a slash at its
+    // end: what Tab completes a path from. `more` when there were too many to give them all.
+    using List = std::function<std::vector<std::string>(const std::string& folder, const std::string& prefix, bool& more)>;
+    // How many names a pattern matches (/notes/*.txt), for the question `rm` asks; `more` past the limit.
+    using Count = std::function<int(const std::string& pattern, bool& more)>;
+
+    ShellApp(Run run, Probe probe, List list, Count count, const char* helpText, AppManager& apps)
+        : run_(std::move(run)), probe_(std::move(probe)), list_(std::move(list)), count_(std::move(count)), helpText_(helpText), apps_(apps) {}
+
+    void onEnter() override;
+    void onExit() override;
+    bool onKey(const KeyEvent& e) override;
+    bool textEntryActive() const override { return !confirm_; }
+    void update(uint32_t nowMs) override;
+    void draw(Canvas& c) override;
+    void help(std::vector<KeyHelp>& out) const override;
+
+   private:
+    void enter(const std::string& line);
+    void runNow(const std::string& line);
+
+    Run run_;
+    Probe probe_;
+    List list_;
+    Count count_;
+    const char* helpText_;
+    AppManager& apps_;
+    ShellLog log_;
+    std::string ownHelp_;  // the Shell's own commands and the keys `key` takes, in the form of `help`'s text
+    LineEditor input_{240};
+    InputHistory history_{16};
+    std::unique_ptr<DialogModel> confirm_;
+    std::string pending_, question_;  // the `rm` being asked about, and what's asked
+    uint32_t ringPos_ = 0, seenRevision_ = 0;
+    int scroll_ = 0;  // wrapped lines scrolled back from the bottom
+    bool open_ = false;
+};
+
+}  // namespace roro

src/apps/storage_app.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "storage_app.h"
 
 #include <Arduino.h>
@@ -199,7 +200,7 @@ void StorageApp::onFinished(const FileOps::Status& s) {
 }
 
 void StorageApp::paste(bool replace) {
-    if (!clip_) return say("Nothing to paste: c copies, x cuts");
+    if (!clip_) return say("Nothing to paste: copy or cut something first");
     std::string name = baseName(clip_.path), why;
     if (cut_) {
         why = ops_.move(clip_.path, clip_.folder, joinPath(cwd_, name), replace);
@@ -273,6 +274,32 @@ void StorageApp::showDetails(const Item& item) {
     view_ = View::Details;
 }
 
+void StorageApp::help(std::vector<KeyHelp>& out) const {
+    switch (view_) {
+        case View::NoMemory: return;
+        case View::Maintenance: return maintenance_.help(out);
+        case View::Editor: return noteEditor_.help(out);
+        case View::Viewer: return viewer_.help(out);
+        case View::Details: return keys::add(out, keys::kStorageDetails);
+        default: break;
+    }
+    if (dialog_) return keys::add(out, keys::kDialog);
+    if (wantList_ || wait_ != Wait::None) return keys::add(out, keys::kStorageBusy);
+    if (view_ == View::Name) return keys::add(out, keys::kStorageName);
+    keys::add(out, keys::kStorage);
+}
+
+const char* StorageApp::helpTitle() const {
+    switch (view_) {
+        case View::Maintenance: return "Storage: maintenance";
+        case View::Editor: return "Storage: the editor";
+        case View::Viewer: return "Storage: a file";
+        case View::Details: return "Storage: details";
+        case View::Name: return "Storage: a name";
+        default: return nullptr;
+    }
+}
+
 bool StorageApp::onKey(const KeyEvent& e) {
     requestRedraw();
     if (view_ == View::NoMemory) return false;
@@ -434,7 +461,7 @@ bool StorageApp::onBrowseKey(const KeyEvent& e) {
     if (ch == 'c') {
         clip_ = item;
         cut_ = false;
-        say("v pastes a copy of " + name);
+        say("Copied " + name + ": paste it where you like");
         return true;
     }
     // Cut, rename and delete change the original: the rules of Q130 first.
@@ -446,7 +473,7 @@ bool StorageApp::onBrowseKey(const KeyEvent& e) {
     if (ch == 'x') {
         clip_ = item;
         cut_ = true;
-        say("v moves " + name + " here");
+        say("Cut " + name + ": paste it where it should go");
     } else if (ch == 'r') {
         target_ = item;
         renaming_ = true;
@@ -542,7 +569,6 @@ void StorageApp::drawBrowse(Canvas& c) {
     } else if (rows_.count() == 0) {
         c.setTextColor(theme::kMuted);
         c.drawString("Nothing in this folder.", 4, rows.y + 4);
-        c.drawString("n makes a folder, v pastes.", 4, rows.y + 4 + theme::kLineHeight);
     } else {
         int entries = static_cast<int>(list_.count());
         auto value = [&](int i) {
@@ -558,13 +584,13 @@ void StorageApp::drawBrowse(Canvas& c) {
             value);
     }
 
-    // Footer: a message for a few seconds, what v would paste, or the keys.
+    // Footer: a message for a few seconds, or what a paste would do. Never the keys (Fn+h).
     c.setFont(&fonts::small);
     bool showMessage = !message_.empty() && millis() - messageMs_ < kMessageMs;
     c.setTextColor(showMessage ? theme::kWarning : theme::kMuted);
-    std::string keys = "c x v:paste r:name d:del n:new i:info s:sort";
+    std::string keys;
     if ((wantList_ || wait_ == Wait::List) && millis() - waitSinceMs_ >= kQuietMs) keys = "Reading " + files::fitName(want_, 30) + "...";
-    else if (clip_) keys = std::string("v: ") + (cut_ ? "move " : "copy ") + files::fitName(baseName(clip_.path), 20) + " here";
+    else if (clip_) keys = std::string(cut_ ? "Cut: " : "Copied: ") + files::fitName(baseName(clip_.path), 28);
     c.drawString(showMessage ? message_.c_str() : keys.c_str(), 4, area.y + area.h - 9);
 }
 
@@ -589,8 +615,6 @@ void StorageApp::drawProgress(Canvas& c) {
         line = formatBytes(s.doneBytes) + " of " + formatBytes(s.totalBytes);
     }
     c.drawString(line.c_str(), box.x + 6, box.y + 31);
-    c.setFont(&fonts::small);
-    c.drawString("Back: cancel", box.x + 6, box.y + box.h - 10);
 }
 
 }  // namespace roro

src/apps/storage_app.h

@@ -34,6 +34,8 @@ class StorageApp : public App {
     bool textEntryActive() const override { return view_ == View::Name || view_ == View::Editor; }
     void update(uint32_t nowMs) override;
     void draw(Canvas& c) override;
+    void help(std::vector<KeyHelp>& out) const override;
+    const char* helpTitle() const override;
 
    private:
     enum class View { Browse, Details, Name, Viewer, Editor, Maintenance, NoMemory };

src/apps/system_app.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "system_app.h"
 
 #include <Arduino.h>
@@ -73,6 +74,22 @@ void SystemApp::onExit() {  // nothing is kept while it's closed (Q120)
     load_[0] = load_[1] = -1;
 }
 
+void SystemApp::help(std::vector<KeyHelp>& out) const {
+    if (view_ == View::Tasks) keys::add(out, keys::kSystemTasks);
+    else if (view_ == View::System) keys::add(out, keys::kSystemSystem);
+    else keys::add(out, keys::kSystem);
+}
+
+const char* SystemApp::helpTitle() const {
+    switch (view_) {
+        case View::Tasks: return "System: tasks";
+        case View::Memory: return "System: memory";
+        case View::Network: return "System: network";
+        case View::System: return "System: system";
+        default: return "System: overview";
+    }
+}
+
 bool SystemApp::onKey(const KeyEvent& e) {
     if (e.key == Key::Tab) {
         int n = static_cast<int>(View::Count), v = static_cast<int>(view_);
@@ -219,7 +236,6 @@ void SystemApp::drawOverview(Canvas& c) {
             }
         }
     }
-    footer(c, "Tab: tasks, memory, network, system");
 }
 
 void SystemApp::drawTasks(Canvas& c) {
@@ -249,8 +265,7 @@ void SystemApp::drawTasks(Canvas& c) {
         c.drawString(std::to_string(r.stackFree).c_str(), area.w - 4, y);
     }
     c.setTextDatum(top_left);
-    std::string keys = std::string("s: by ") + (sort_ == TaskSort::Share ? "stack" : sort_ == TaskSort::Stack ? "name" : "cpu") +
-                       "   " + std::to_string(rows_.size()) + " tasks   Tab: memory";
+    std::string keys = std::to_string(rows_.size()) + " tasks, by " + (sort_ == TaskSort::Share ? "cpu" : sort_ == TaskSort::Stack ? "stack" : "name");
     footer(c, keys.c_str());
 }
 
@@ -288,7 +303,7 @@ void SystemApp::drawMemory(Canvas& c) {
         int x0 = gx + 1 + static_cast<int>((i - 1) * (gw - 2) / kHistory), x1 = gx + 1 + static_cast<int>(i * (gw - 2) / kHistory);
         c.drawLine(x0, yOf(heapHistory_.at(i - 1)), x1, yOf(heapHistory_.at(i)), theme::kAccent);
     }
-    footer(c, "KB free, 2 min, with the floors   Tab: network");
+    footer(c, "KB free, 2 min, with the floors");
 }
 
 void SystemApp::drawNetwork(Canvas& c) {
@@ -331,7 +346,7 @@ void SystemApp::drawNetwork(Canvas& c) {
         y += theme::kLineHeight;
     }
     c.setTextDatum(top_left);
-    footer(c, "bytes since boot   Tab: system");
+    footer(c, "bytes since boot");
 }
 
 void SystemApp::drawSystem(Canvas& c) {
@@ -355,7 +370,6 @@ void SystemApp::drawSystem(Canvas& c) {
     wrappedLines_ = static_cast<int>(wrapped.size());
     systemTop_ = std::clamp(systemTop_, 0, std::max(0, wrappedLines_ - 8));
     widgets::textLines(c, wrapped, systemTop_, {area.x + 2, area.y + 2, area.w - 2, area.h - 12});
-    footer(c, "Tab: overview");
 }
 
 }  // namespace roro

src/apps/system_app.h

@@ -28,6 +28,8 @@ class SystemApp : public App {
     bool onKey(const KeyEvent& e) override;
     void update(uint32_t nowMs) override;
     void draw(Canvas& c) override;
+    void help(std::vector<KeyHelp>& out) const override;
+    const char* helpTitle() const override;
 
    private:
     enum class View : uint8_t { Overview, Tasks, Memory, Network, System, Count };

src/apps/wifi_settings_page.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "wifi_settings_page.h"
 
 #include "ipv4.h"
@@ -413,7 +414,6 @@ void WifiSettingsPage::draw(Canvas& c) {
             c.setTextColor(theme::kMuted);
             c.drawString(editTitle_.c_str(), 4, area.y + 4);
             widgets::lineEditor(c, editor_, {4, area.y + 22, area.w - 8, 0});
-            c.drawString("Enter: save   `: cancel", 4, area.y + 44);
             break;
         }
 
@@ -427,7 +427,7 @@ void WifiSettingsPage::draw(Canvas& c) {
                 if (!n.ssid.empty()) found.push_back(n);
             if (scan_.count() != static_cast<int>(found.size())) scan_.setCount(static_cast<int>(found.size()));
             if (found.empty()) {
-                widgets::textLines(c, {"No networks found.", "", "`: back"}, 0, area);
+                widgets::textLines(c, {"No networks found."}, 0, area);
                 break;
             }
             widgets::list(
@@ -443,20 +443,46 @@ void WifiSettingsPage::draw(Canvas& c) {
             std::string title = view_ == View::Ssid ? "Hidden network name" : "Password for " + newSsid_;
             c.drawString(title.c_str(), 4, area.y + 4);
             widgets::lineEditor(c, editor_, {4, area.y + 22, area.w - 8, 0});
-            c.drawString(view_ == View::Ssid ? "Enter: next   `: cancel" : "Enter: save (empty = open)   `: cancel", 4,
-                         area.y + 44);
+            if (view_ == View::Password) c.drawString("Leave it empty for an open network.", 4, area.y + 44);
             break;
         }
     }
 }
 
+void WifiSettingsPage::help(std::vector<KeyHelp>& out) const {
+    if (forgetDialog_) return keys::add(out, keys::kDialog);
+    switch (view_) {
+        case View::Main: keys::add(out, keys::kWifi); break;
+        case View::Servers: keys::add(out, keys::kWifiServers); break;
+        case View::Network: keys::add(out, keys::kWifiNetwork); break;
+        case View::Details: keys::add(out, keys::kWifiStatus); break;
+        case View::Scan: keys::add(out, keys::kWifiScan); break;
+        case View::Ssid: keys::add(out, keys::kWifiName); break;
+        case View::Password:
+        case View::Edit: keys::add(out, keys::kText); break;
+    }
+}
+
+const char* WifiSettingsPage::helpTitle() const {
+    switch (view_) {
+        case View::Servers: return "DNS and NTP";
+        case View::Network: return "A saved network";
+        case View::Details: return "Wi-Fi status";
+        case View::Scan: return "Add a network";
+        case View::Ssid: return "Hidden network name";
+        case View::Password: return "Wi-Fi password";
+        case View::Edit: return "Wi-Fi: a field";
+        default: return "Wi-Fi";
+    }
+}
+
 // What the device is using and where each part came from (Q113).
 void WifiSettingsPage::drawDetails(Canvas& c) {
     const auto& area = theme::kContent;
     WifiService::Connection n = wifi_.connection();
     std::vector<std::string> lines;
     if (!n.connected) {
-        lines = {statusText(), "", "`: back"};
+        lines = {statusText()};
     } else {
         lines.push_back(wifi_.ssid() + ", " + std::to_string(wifi_.rssi()) + " dBm");
         lines.push_back("Address " + n.address + "/" + std::to_string(n.prefix) + (n.fixed ? " (fixed)" : " (DHCP)"));

src/apps/wifi_settings_page.h

@@ -6,6 +6,7 @@
 #include "dialog_model.h"
 #include "event_bus.h"
 #include "key_event.h"
+#include "key_help.h"
 #include "line_editor.h"
 #include "list_model.h"
 #include "saved_networks.h"
@@ -30,6 +31,8 @@ class WifiSettingsPage {
     // Redraw periodically: the status, a scan, the connection details.
     bool live() const { return view_ == View::Main || view_ == View::Scan || view_ == View::Details; }
     void draw(Canvas& c);
+    void help(std::vector<KeyHelp>& out) const;
+    const char* helpTitle() const;
 
    private:
     enum class View { Main, Scan, Ssid, Password, Details, Servers, Network, Edit };

src/apps/wifi_tools_app.cpp

@@ -1,3 +1,4 @@
+#include "app_keys.h"
 #include "wifi_tools_app.h"
 
 #include <M5Cardputer.h>
@@ -153,6 +154,24 @@ void WifiToolsApp::draw(Canvas& c) {
     }
 }
 
+void WifiToolsApp::help(std::vector<KeyHelp>& out) const {
+    switch (view_) {
+        case View::Menu: keys::add(out, keys::kWifiTools); break;
+        case View::Networks: keys::add(out, keys::kWifiNetworks); break;
+        case View::Channels: break;  // nothing but the keys that work everywhere
+        case View::Tracker: keys::add(out, keys::kWifiTracker); break;
+    }
+}
+
+const char* WifiToolsApp::helpTitle() const {
+    switch (view_) {
+        case View::Networks: return "Networks nearby";
+        case View::Channels: return "Channel occupancy";
+        case View::Tracker: return "Signal tracker";
+        default: return nullptr;
+    }
+}
+
 void WifiToolsApp::drawNetworks(Canvas& c) {
     const auto& area = theme::kContent;
     const auto& scan = wifi_.listScan();
@@ -178,7 +197,7 @@ void WifiToolsApp::drawNetworks(Canvas& c) {
         widgets::textLines(c,
                            {wifi_.listScanDone() ? (any ? "Nothing matches the filter." : "No networks found yet.")
                                                  : "Scanning...",
-                            "", "s sort  o open  h hide-hidden  w strong  l log"},
+                            },
                            0, list);
         return;
     }
@@ -233,7 +252,7 @@ void WifiToolsApp::drawTracker(Canvas& c) {
     c.drawString(targetName_.c_str(), 4, area.y + 2);
     c.setFont(&fonts::small);
     c.setTextColor(theme::kMuted);
-    std::string sub = targetBssid_ + "  ch" + std::to_string(targetChannel_) + "  m: clicks " + (clicks_ ? "on" : "off");
+    std::string sub = targetBssid_ + "  ch" + std::to_string(targetChannel_) + "  clicks " + (clicks_ ? "on" : "off");
     c.drawString(sub.c_str(), 4, area.y + 17);
 
     c.setFont(&fonts::bold);

src/apps/wifi_tools_app.h

@@ -27,6 +27,8 @@ class WifiToolsApp : public App {
     bool onKey(const KeyEvent& e) override;
     void update(uint32_t nowMs) override;
     void draw(Canvas& c) override;
+    void help(std::vector<KeyHelp>& out) const override;
+    const char* helpTitle() const override;
 
    private:
     enum class View { Menu, Networks, Channels, Tracker };