Merge pull request 'Storage: share the card with a phone's browser (#88 )' (#89 ) from web-files into main

Devlog: "Press w" is v0.18.0
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EhqxQ49eCju4CzKYNjZzwT
2026-10-07 22:37:11 +00:00 · 2026-10-08 00:35:15 +02:00 · 2026-10-08 00:33:14 +02:00 · 2026-10-08 00:30:50 +02:00 · 2026-10-08 00:26:43 +02:00 · 2026-10-08 00:11:55 +02:00
387 changed files with 29775 additions and 360 deletions
@@ -0,0 +1,167 @@
 # 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 (from the build cache).
 #                      A branch's pushes run nothing by themselves: its pull request runs, once.
 #   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:
    branches: [main]  # other branches are tested by their pull request: one run, not two
    tags: ['v*']
    # A change that touches nothing but the site and the documents it is built from runs the Site
    # workflow only (a tag always runs this one: Gitea doesn't apply path filters to tags).
    paths-ignore: ['site/**', 'docs/**', 'README.md', 'CONTEXT.md']
  pull_request:
    paths-ignore: ['site/**', 'docs/**', 'README.md', 'CONTEXT.md']
  workflow_dispatch:
    inputs:
      tag:
        description: An existing tag to build and publish as a release
        required: true
 jobs:
  build:
    runs-on: ubuntu
    # A pull request from a fork would run someone else's code on our runner: not without us (Q154).
    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
    container:
      image: python:3.12-slim
      volumes:
        - roro9stack-pio:/pio
    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 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: |
          find . -mindepth 1 -maxdepth 1 -exec rm -rf {} +
          git config --global --add safe.directory '*'
          git init -q .
          git remote add origin "${{ github.server_url }}/${{ github.repository }}.git"
          git fetch -q --tags origin '+refs/heads/*:refs/remotes/origin/*' '+refs/pull/*/head:refs/remotes/pull/*'
          git checkout -q --detach "${{ github.sha }}"
          git describe --tags --always
      - name: Host tests, and their coverage of lib/
        if: github.event_name != 'workflow_dispatch'
        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'
        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)
      - name: Publish the badges
        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref_type == 'tag')
        env:
          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
        run: |
          rm -rf /tmp/badges && mkdir /tmp/badges
          cp .pio/coverage/coverage.svg .pio/coverage/summary.json /tmp/badges/
          scripts/coverage_badge.py --plain release "$(git describe --tags --abbrev=0)" /tmp/badges/release.svg
          cd /tmp/badges
          git init -q -b badges .
          git add .
          git -c user.name="roro9stack CI" -c user.email="ci@git.twis.la" commit -q -m "Coverage of ${{ github.ref_name }} at ${{ github.sha }}"
          git push -q --force "$(echo "${{ github.server_url }}" | sed "s#://#://ci:${GITEA_TOKEN}@#")/${{ github.repository }}.git" badges
      - name: Which release
        id: release
        run: |
          if [ "${{ github.event_name }}" = workflow_dispatch ]; then
            echo "tag=${{ inputs.tag }}" >> "$GITHUB_OUTPUT"
          elif [ "${{ github.ref_type }}" = tag ]; then
            echo "tag=${{ github.ref_name }}" >> "$GITHUB_OUTPUT"
          fi
      - name: Build and sign the release
        if: steps.release.outputs.tag != ''
        env:
          OTA_SIGNING_KEY: ${{ secrets.OTA_SIGNING_KEY }}
        run: |
          # The sources of the tag in a clone of their own; the tools are this commit's.
          rm -rf /tmp/release-src dist
          git clone -q . /tmp/release-src
          git -C /tmp/release-src checkout -q --detach "refs/tags/${{ steps.release.outputs.tag }}"
          # The key exists as a file only while this step runs, in a container that goes with the job.
          umask 077
          export RORO_OTA_KEY="$(mktemp)"
          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 != ''
        env:
          GITEA_API: ${{ github.server_url }}/api/v1
          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
@@ -0,0 +1,66 @@
 # The project site (docs/milestones/W1.md): built with Zola to see that it builds and that its pages
 # 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 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', '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', 'lib/core/src/app_keys.h', '.gitea/workflows/site.yml', 'scripts/site_refresh.sh']
 jobs:
  build:
    runs-on: ubuntu
    # A pull request from a fork would run someone else's code on our runner: not without us.
    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
    container:
      image: python:3.12-slim
    steps:
      - name: Tools
        run: |
          apt-get update -qq
          apt-get install -y -qq --no-install-recommends git ca-certificates curl >/dev/null
          # Zola, pinned by its checksum.
          curl -fsSL -o /tmp/zola.tgz https://github.com/getzola/zola/releases/download/v0.22.0/zola-v0.22.0-x86_64-unknown-linux-gnu.tar.gz
          echo "f1d491f8956b94384c27d75cb6b2bf60d3916d1ade9564bcbfe7c03f0258aebf  /tmp/zola.tgz" | sha256sum -c -
          tar xzf /tmp/zola.tgz -C /usr/local/bin zola
          zola --version
      - name: Check out
        run: |
          find . -mindepth 1 -maxdepth 1 -exec rm -rf {} +
          git config --global --add safe.directory '*'
          git init -q .
          git remote add origin "${{ github.server_url }}/${{ github.repository }}.git"
          git fetch -q origin '+refs/heads/*:refs/remotes/origin/*' '+refs/pull/*/head:refs/remotes/pull/*'
          git checkout -q --detach "${{ github.sha }}"
      - name: The generated developer pages are current
        run: python3 site/tools/gen_dev_docs.py --check
      - name: Build the site
        run: |
          cd site
          zola check --skip-external-links
          zola build --output-dir /tmp/site-out
      - 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
@@ -9,3 +9,9 @@
 .dummy/
 managed_components/
 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
@@ -69,7 +69,7 @@ The Service that owns the Wi-Fi radio. It's always in exactly one mode: *Off*, *
 _Avoid_: network manager
 **Saved Network**:
-A Wi-Fi network the device may join on its own (name, password). When several are in range, the strongest wins.
+A Wi-Fi network the device may join on its own: its name, its password, and how it gets its address, *Automatic* (DHCP) or *Fixed* (an address, a prefix and an optional gateway typed in Settings). When several are in range, the strongest wins.
 _Avoid_: profile, known network
 **IRC Service**:
@@ -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
@@ -123,13 +131,28 @@ Data the user explicitly starts recording, such as Wi-Fi packet captures and LoR
 _Avoid_: dump, log
 **Storage Warning**:
-The Notification raised once per boot when the SD card passes 80% full. Selecting it opens Storage Clean-up.
+The Notification raised once per boot when the SD card passes 80% full. It points at the Storage App, where Maintenance holds Storage Clean-up.
 **Storage Clean-up**:
-The screen where the user deletes old Logs and Captures by category and age, with a preview of the space freed. Notes are never offered for deletion.
+The screen where the user deletes old Logs and Captures by category and age, with a preview of the space freed. Notes are never offered for deletion. It lives in the Storage App, under Maintenance.
 **Note**:
 A plain text file in `/notes`, written on the device in the Notes App. Listed by its first line. Saved without being asked; never offered by Storage Clean-up.
 _Avoid_: memo, document
 **Storage App**:
 The App that browses the SD card: folders and files, a clipboard for one item at a time (copy, cut, paste), rename, delete, new folder, and a viewer for each kind of file the firmware writes. The top-level folders, `/gemini/cache` and files being written are read-only.
 _Avoid_: file manager, Files, explorer
 **Maintenance**:
 The part of the Storage App that deletes in bulk: the card's usage, Storage Clean-up and erasing the card. Reached through a warning.
 _Avoid_: Settings > Storage
 **Firmware Update**:
-Installing a new firmware image without a USB cable: pushed over Wi-Fi from the developer's PC, or read from the SD card.
+Installing a new firmware image without a USB cable: pushed over Wi-Fi from the developer's PC, read from the SD card, or downloaded from the project's Gitea **Release**.
 **Release**:
 A tag `v*` on the project's Gitea with a signed **Update File**, a factory image for USB, the ELF to decode crashes and checksums, built and published by CI. The device reads them to look for updates.
 _Avoid_: flash, upgrade (alone)
 **Update File**:
@@ -145,16 +168,12 @@ Returning automatically to the previous firmware when new firmware resets or cra
 _Avoid_: revert, downgrade (a downgrade is installing an older version on purpose)
 **Safe Mode**:
-What the firmware starts instead of everything else after 3 crash restarts in a row: Wi-Fi and Firmware Updates (and the Debug Console in a Debug Build), so it can be fixed without a cable. A normal restart leaves it.
+What the firmware starts instead of everything else after 3 crash restarts in a row: Wi-Fi and Firmware Updates (and the Debug Console if it's switched on), so it can be fixed without a cable. A normal restart leaves it.
 _Avoid_: recovery mode, failsafe
 **Debug Build**:
 A firmware built with the remote debugging aids compiled in (`+debug` in its version). Release builds have none of them.
 _Avoid_: dev build, test build (a test build is one made to fail on purpose, such as a crashing update)
 **Debug Console**:
-The console of a Debug Build over Wi-Fi: live log lines and the serial commands, behind a token.
+The console over Wi-Fi, in every firmware but off until switched on in Settings: live log lines and the serial commands, for whoever holds the device's token.
-_Avoid_: telnet, remote shell
+_Avoid_: telnet, remote shell, Debug Build (there is one firmware)
 ## Relationships
@@ -1,11 +1,17 @@
 # roro9stack
 [![CI](https://git.twis.la/twisla/roro9stack/actions/workflows/ci.yml/badge.svg?branch=main)](https://git.twis.la/twisla/roro9stack/actions?workflow=ci.yml) [![Coverage of lib/ by the host tests](https://git.twis.la/twisla/roro9stack/raw/branch/badges/coverage.svg)](#build-and-test-local-ci) [![Latest release](https://git.twis.la/twisla/roro9stack/raw/branch/badges/release.svg)](https://git.twis.la/twisla/roro9stack/releases/latest)
 A multi-app firmware for the **M5Stack Cardputer ADV** with the **Cap LoRa-1262**. It's a Meshtastic-compatible mesh messenger, plus Wi-Fi tools, IRC, GNSS and more. Licensed GPL-3.0.
 - Domain language: [CONTEXT.md](CONTEXT.md)
 - 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.
@@ -18,7 +24,26 @@ scripts/ci.sh
 This runs the host-side unit tests (`test/`, `native` environment), then builds the firmware. The output is `.pio/build/cardputer-adv/firmware.factory.bin`.
-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.
+`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 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
 Gitea Actions (`.gitea/workflows/ci.yml`, docs/milestones/R1.md) runs the host tests on every push to `main`, and on a pull request also builds the firmware: changes reach `main` through pull requests. Pushing a tag `v*` runs all of it and publishes a release on Gitea with:
 - `roro9stack-<version>.ota`, the signed Update File;
 - `roro9stack-<version>-factory.bin`, the whole flash image for a first install over USB;
 - `roro9stack-<version>.elf.gz`, to decode crash reports from that build;
 - `SHA256SUMS`.
 CI signs with the project's key, held as a repository secret (ADR 0008). There is one firmware: the Debug Console is in every build, switched off until its owner switches it on (ADR 0010).
 `scripts/ota_verify.py <file.ota>` checks an Update File on a PC the way a device does. `scripts/release_build.sh` and `scripts/release_publish.py` are what the workflow runs; they work the same by hand.
 ## The website
 The project's site, **roro9stack.net**, is built from `site/` with Zola (see `site/README.md`): the home page, an Install page that flashes a Cardputer from the browser, and every release. Changes under `site/`, `docs/`, `README.md` and `CONTEXT.md` run only the site's CI job, not the firmware tests and builds.
 ## Flash
@@ -52,7 +77,39 @@ The device shows the push address in **Settings → Firmware**. It installs a co
 To install from the SD card instead, copy the `.ota` file from `.pio/build/cardputer-adv/` into `/updates` on the card, then use **Settings → Firmware**. With the Cardputer on USB, the card can stay in: `scripts/sd_put.sh <file.ota>` sends it over the serial console into `/updates` (about 30 s for 1.6 MB, checked with SHA-256 before it's renamed into place; `SD_PUT_DEBUG=1` shows the console while it runs).
-**The private key** lives in `~/.config/roro9stack/ota-key.pem` and must never be committed. If it's lost, generate a new pair and flash once over USB.
+**The private key** lives in `~/.config/roro9stack/ota-key.pem` and must never be committed. If it's lost, generate a new pair and flash once over USB. (CI signs releases with a copy kept as a repository secret, ADR 0008.)
 ### Updates from Gitea
 With no PC and no card, the device can install the project's releases itself (docs/milestones/R1.md). In **Settings → Firmware**:
 - **Latest release** checks the server (Enter, or `c`) and says `v0.11.0 (new)` or `(current)`. Enter again opens the release: its version, date, size and the tag's message, with **Install** when it's newer. The download goes straight into the inactive slot, so no card is needed; the signature is checked after the first 160 bytes, before anything is written, and the image's hash at the end. The new firmware then runs on Probation as for any update.
 - **Older releases** lists the last ten, newest first. Opening an older one offers to go back to it, with a different question.
 - **Settings → Check for updates** (on by default): once a day, with Wi-Fi up and the clock set, the device looks at the latest release and says `v0.11.0 is out: see Settings > Firmware`, once per version. It installs nothing by itself, and doesn't announce a version that already failed and rolled back on this device.
 The connection is checked against the two ISRG roots Let's Encrypt chains end in (ADR 0009), not the usual bundle of about 130 authorities. Whatever the connection, the Update File's own signature is what decides what gets installed.
 **IRC steps aside.** A secure connection takes about 52 KB of memory at its peak, and IRC's own takes 40 KB of the 107 KB there is. A check or an install you ask for makes IRC disconnect for the few seconds it takes and reconnect afterwards. The daily check never does that: with IRC connected it waits for a moment when IRC isn't, so while IRC stays connected for days it doesn't run, and **Latest release** is the way to check.
 **There is no separate Debug Build** any more (ADR 0010): every firmware installs releases, and the Debug Console is a setting, which an update leaves as it was.
 ## Networks without DHCP
 Each Saved Network gets its address automatically (DHCP) or has a Fixed one (docs/milestones/S1.md): in Settings > Wi-Fi, Enter on a network opens its page, where "IP address" switches between Automatic and Fixed, with an address, a prefix length (24 is 255.255.255.0) and an optional gateway. Switching to Fixed starts from what the network is giving the device at that moment. The setting is checked and applied when you leave the page. IPv4 only.
 "DNS and NTP" on the same screen holds two DNS servers (9.9.9.9 and 1.1.1.1 by default), used on Fixed networks, or on every network with "Always use my DNS"; and two NTP servers (pool.ntp.org and time.cloudflare.com), used after any the network's DHCP offers. Enter on "Status" shows what's in use and where each value came from.
 ## System
 The System App (docs/milestones/S1.md) shows what the device is doing, live and read-only, in any build. Tab moves between five views:
 - **Overview:** each core's load, free memory, network traffic, battery, uptime and chip temperature, and both cores' load over the last two minutes.
 - **Tasks:** every FreeRTOS task with its core, its share of a core over the last second, and the least stack it ever had left (in the warning colour under 512 bytes). `s` sorts by share, stack or name.
 - **Memory:** free heap, the lowest since boot and the largest free block, with two minutes of free heap drawn against the three memory floors (55, 40 and 20 KB).
 - **Network:** the connection, then for IRC, Gemini, the Debug Console and Firmware Updates the bytes read and written since boot and what's moving now. For TLS connections these are the bytes the service sees, without the encryption overhead.
 - **System:** what `info` prints, plus the battery, the SD card with its write faults, the radio and the GNSS receiver.
 It samples once a second and keeps its history only while it's open.
 ## Gemini
@@ -62,7 +119,49 @@ On a page, `b` bookmarks it, `s` saves it to the SD card to read offline (a non-
 ## LoRa Scanner
-The LoRa Scanner (docs/milestones/M3.md) listens with the Cap's radio and **never transmits**. The Sniffer lists what it hears, newest first: time, RSSI, SNR, and for Meshtastic packets the sender and receiver (their last 4 hex digits) and hops. Enter shows a packet's details: the Meshtastic header (which is never encrypted) and a hex dump. `p` picks one of the 7 Meshtastic presets allowed in EU868 (LongFast by default), `c` starts or stops a Capture: a pcap file with LoRaTap headers in `/captures/lora/`, for Wireshark. A Capture keeps recording with the App closed; otherwise the radio sleeps when the App isn't open. Tab switches to **Sweep**: the signal strength across 863–870 MHz in 100 kHz steps, as bars with peak hold and a waterfall, with the Sniffer's frequency marked; the Sniffer is paused meanwhile and picks up where it was. The Status Bar shows `L` while the radio listens (bright for a moment on each packet), `SW` while sweeping, and `CAP` while capturing.
+The LoRa Scanner (docs/milestones/M3.md) listens with the Cap's radio and **never transmits**. The Sniffer lists what it hears, newest first: time, RSSI, SNR, and for Meshtastic packets the sender and receiver (their last 4 hex digits) and hops. Enter shows a packet's details: the Meshtastic header (which is never encrypted) and a hex dump. `p` picks one of the 7 Meshtastic presets allowed in EU868 (LongFast by default), `c` starts or stops a Capture: a pcap file with LoRaTap headers in `/captures/lora/`, for Wireshark. A Capture keeps recording with the App closed; otherwise the radio sleeps when the App isn't open. Tab switches to **Sweep**: the signal strength across 863–870 MHz in 100 kHz steps, as bars with peak hold and a waterfall, with the Sniffer's frequency marked; the Sniffer is paused meanwhile and picks up where it was. The GNSS receiver on the same Cap raises the radio's noise floor by 8 dB while it runs: Settings > "Pause GNSS for LoRa" (off by default) puts it in standby while the radio listens, except during a Track. The Status Bar shows `L` while the radio listens (bright for a moment on each packet), `SW` while sweeping, and `CAP` while capturing.
 ## Storage
 The Storage App (docs/milestones/F1.md) shows what's on the SD card: each folder's entries with their size and date, folders first. Enter opens a folder, Back goes up; `s` sorts by name, date or size. It works on one item at a time, with a clipboard:
 | Key | Does |
 |---|---|
 | `c` / `x` | Copies or cuts the selected file or folder; the footer shows what `v` would paste |
 | `v` | 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 |
 | `r` | Renames |
 | `d` | Deletes, after saying what's inside: "Delete saved and its 42 files (1.2 MB)?" |
 | `n` | Makes a folder |
 | `i` | Details: type, exact size, date, and why an item is read-only if it is |
 A copy runs in the background of the card (about 400 KB a second) in short turns, so Logs and Captures keep being written; it shows its progress, Back cancels it and takes back what was copied, and each file's size is checked afterwards. Three things can't be changed: the top-level folders the firmware keeps its files in (what's inside them can), `/gemini/cache`, and any file being written right now (today's IRC Logs, a Track or a Capture being recorded). The App says why when it refuses. A folder with more than 256 entries shows the first 256 by name and says so.
 **`w` shares the card with a browser on the same network** (issue #88): a small HTTP server and one page, for a phone with nothing to install. The screen shows the address as a QR code and a six-digit code, new each time; whoever has typed it can list, download, upload (streamed to the card under a temporary name), make folders and delete, under the Storage App's rules. It runs only while that screen is open, takes one request at a time, moves about 200 KB a second, and is not encrypted. It costs 57 KB of flash, and 13 KB of memory while it is on.
 Enter on a file opens it by type; Tab switches to the same file as a hex dump or as text:
 - **Text** (`.txt`, `.log`, `.gmi`, `.csv`, and anything that looks like text): only the screen's worth is read from the card, so a file of any size opens at once. Logs open at the end. Up and Down move a line, Left and Right a page, `t` and `b` go to the top and the end, `e` edits it, whatever its size (see Notes).
 - **Pictures** (`.png`, `.jpg`, `.bmp`, `.gif`; issue #45): shrunk to fit the screen, or at their own size with Enter, the arrows then moving half a screen at a time; `i` gives the size in pixels. Dithered to the screen's 256 colours, decoded straight into the screen's buffer with no copy in memory, on the storage task so the keys keep working (12 megapixels of JPEG: 7 s). A GIF shows its first picture. A progressive JPEG or an interlaced PNG opens as hex, with the reason.
 - **Captures** (`.pcap`): the packets as the LoRa Scanner lists them; Enter shows one with its Meshtastic header and bytes.
 - **Tracks** (`.gpx`): the number of points, the start, the duration and the distance.
 - **Update Files** (`.ota`): the version, and whether the file would install: it's checked as an install checks it (signature and contents) without writing anything. Enter then installs it.
 - **Anything else:** a hex dump.
 At the top of the card the last row, **Maintenance** (also `m`), holds the card's usage, Storage Clean-up and "Erase SD card", behind a warning: those delete for good. It replaces Settings > Storage.
 ## Notes
 The Notes App (docs/milestones/F1.md) keeps plain text notes in `/notes` on the SD card. The list shows each note's first line and its date, newest first; `s` switches to by file name. `n` starts a note, Enter opens one, `r` renames its file, `d` deletes it after asking.
 In the editor, type. Enter starts a line, Del deletes backwards, Fn with the arrows moves the cursor through the wrapped text, Ctrl+A and Ctrl+E go to the start and the end of the line, Ctrl with Fn+Up and Fn+Down to the start and the end of the note, Tab types two spaces, and the Compose Key gives accents as everywhere. **There's no save key:** the note is written five seconds after the last key, on Back, on leaving the App, when the screen turns off and before the device powers off. The top line says "typing" or "saved". Each save writes a temporary file and then puts it in the note's place, so a power cut costs a few seconds of typing and never the note; if a save was cut short, opening the note offers its copy back.
 A new note has no file until something is typed; its file is then named after its first line (`shopping-list.txt`), or `note-<date>-<time>.txt`.
 **A note can be any size** (issue #47): the editor keeps a window of about 8 KB around the cursor in memory and the rest on the card, so a megabyte opens as fast as a line and uses the same 17 KB. Up to 64 KB a save rewrites the file. Above, the five-second save writes only what changed to a side file, `<note>.edit`, and the file itself is rewritten when the note is left, with a progress bar (about 450 KB a second). After a power cut, opening the note picks the edit up where it was saved. Saving needs room on the card for a second copy. 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
@@ -71,13 +170,16 @@ The LoRa Scanner (docs/milestones/M3.md) listens with the Cap's radio and **neve
 | 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\|shot`, or `key <char>` | Injects a key press (`help` is Fn+h: the keys of the screen that is showing; `shot` is Fn+p: a screenshot). `ctrl-`, `alt-` and `shift-` before it hold that key: `key ctrl-down`, `key alt-up`, `key ctrl-b` |
 | `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) |
 | `wifi ip <ssid> dhcp` / `wifi ip <ssid> <address>/<prefix> [gateway]` | A Saved Network's IP setting: Automatic, or Fixed. Add `try <seconds>` to go back to the previous setting unless `wifi ip keep` follows |
 | `wifi dns <a> [b]` / `wifi dns always on\|off` / `wifi ntp <a> [b]` | DNS servers (used on Fixed networks, or always), and NTP servers |
 | `log <text>` | Appends a line to a test IRC Log (`/irc/dev/#test/<date>.log`) |
 | `sd card` | What the SD card says it is: type, size, and its identity register (maker, name, revision, serial, date) |
 | `sd list` | Lists the files of each Storage Clean-up category |
 | `sd fill <folder> <count>` | Makes that many small files in a folder, to test a crowded one |
 | `cat <path>` | Prints the first ~1.2 KB of a file on the SD card |
 | `irc start` | Starts the IRC Service (normally done by opening the IRC App) |
 | `irc stop` | Stops it, as `/quit` does: QUIT if connected, no more retries, and the App stays disconnected until you type |
@@ -85,37 +187,55 @@ The LoRa Scanner (docs/milestones/M3.md) listens with the Cap's radio and **neve
 | `gemini trust <host> <port> <sha256>` | Pins a certificate by hand (the Gemini App asks when one changes) |
 | `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 |
+| `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 |
-| `tasks` | FreeRTOS tasks: state, priority, lowest free stack, CPU share |
+| `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]` / `rm <path>` | Lists a folder of the SD card, or deletes a file |
+| `ls [folder]` / `du <path>` | Lists a folder of the SD card with sizes and dates, or counts the files and bytes under a path |
 | `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 |
 | `lora probe` | Finds the radio: chip, oscillator, antenna switch, DIO1 interrupt, noise floor |
 | `lora status` | Radio settings, who's listening, packet and error counters, noise floor, task stack |
 | `lora rx on` / `lora rx off` | Listens and prints each packet on the console |
 | `lora preset <name>` / `lora custom <MHz> <BW kHz> <SF> <CR> <sync hex> [preamble]` | Receive settings: a Meshtastic preset, or anything else (`lora custom 868.1 125 7 5 34 8` for LoRaWAN) |
 | `lora capture start` / `lora capture stop` | A LoRa Capture, as `c` in the App |
 | `lora sweep on [from MHz] [to MHz] [step kHz]` / `lora sweep off` / `lora sweep dump` | Sweep a band (863 870 100 by default), with a summary every 2 s (floor, strongest, peaks), or print the latest pass |
-| `lora inject <hex> [rssi] [snr]` | Debug Builds: a packet into the Scanner as if received (nothing is sent) |
+| `gnss quiet on` / `gnss quiet off` | The "Pause GNSS for LoRa" setting |
 | `gnss status` / `gnss restart` | The receiver's state, and a restart of it |
 | `gnss track start` / `gnss track stop` | A Track, as `r` in the GNSS App (the reason is printed if it can't start) |
 | `gnss nmea on` / `gnss nmea off` | Prints each NMEA sentence the receiver sends, as `nmea: …` |
 | `gnss send <sentence>` | Sends a sentence to the receiver, without the `$` and the checksum (it adds them) |
 | `lora noise test [gnss\|quiet]` / `lora noise report` | Sweep under one changed condition at a time to find what raises the noise floor (Wi-Fi goes off for a few seconds); then the result |
 | `lora inject <hex> [rssi] [snr]` | A packet into the Scanner as if received (nothing is sent) |
 | `crash` | The last crash: which firmware, why, task, PC and backtrace (from the core dump in flash) |
 | `coredump erase` | Forgets the core dump |
-| `crash abort` / `crash wdt` | Debug Builds: crash on purpose, or hang the main loop until the watchdog fires |
+| `loop spin on` / `loop spin off` | Make the main loop spin without resting, to compare load and radio noise |
 | `crash abort` / `crash wdt` | Crash on purpose, or hang the main loop until the watchdog fires |
 | `debug status` / `debug off [seconds]` | The Debug Console: whether it's on, has a token and a client; switch it off. With a number of seconds, it comes back by itself after that long |
 | `debug on` / `debug token <value>` / `debug token new` | USB serial only: switch it on (making a token if there's none), give it a token of 16 to 64 characters, or make a new one. The token is never printed |
 | `help` | Lists the commands |
 `scripts/flash.sh` stops a running serial log first, since it would hold the port.
-### Debug Builds and the Debug Console
+### The Debug Console
-`scripts/flash.sh --debug` (USB) or `scripts/flash.sh --debug --ota <ip>` (Wi-Fi) installs a Debug Build: the same firmware plus the Debug Console on TCP 2323 (ADR 0004). Then, with `RORO_OTA_HOST` set to the device's IP:
+Every firmware has the Debug Console (ADR 0010): the serial console over Wi-Fi, on TCP 2323. It is **off** until you switch it on in **Settings → Debug Console**, which also makes its token and shows it. With the device on USB, `scripts/flash.sh --debug` flashes it, switches the console on and gives it the token in `~/.config/roro9stack/debug-token`, so nothing has to be typed. Then, with `RORO_OTA_HOST` set to the device's IP:
 ```sh
 scripts/rdbg.py                 # interactive: the console backlog, live lines, and commands
 scripts/rdbg.py info            # one command and its reply
 scripts/rdbg.py -b tasks        # the same, after the backlog (boot messages and so on)
 scripts/rdbg.py -t K7QF-3M2X-9WBD-HT4P-6RNC info   # another device's token; or $RORO_DEBUG_TOKEN
 ```
 The token never crosses the network: the device sends a challenge and `rdbg.py` answers with its HMAC. Five wrong answers in a row close the console for a minute. `debug status` and `debug off` work from anywhere; `debug on`, `debug token <value>` and `debug token new` work over USB serial only.
 Every command above works there too, plus a few handled by the PC side or the console's own task:
 ```sh
@@ -129,6 +249,6 @@ scripts/rdbg.py get <card path> [file]    # from the SD card
 So a Firmware Update can also go `rdbg.py put roro9stack-….ota` then `rdbg.py install /updates/roro9stack-….ota`: the Update from SD path, without touching the device.
-Every build keeps its ELF in `.pio/elves/` (version and digest in the name) for that; `scripts/decode_backtrace.sh <version|digest> <addresses>` decodes any backtrace by hand.
+Every build keeps its ELF in `.pio/elves/` (version and digest in the name) for that, and `rdbg.py crash` fetches a release's ELF from Gitea when it isn't there; `scripts/decode_backtrace.sh <version|digest> <addresses>` decodes any backtrace by hand.
-After 3 crash restarts in a row the firmware starts in **Safe Mode** (ADR 0005): only Wi-Fi, Firmware Updates and the Debug Console, so a fix can be pushed as usual. `reboot` leaves it. The token is in `~/.config/roro9stack/debug-token`, made by the first build; keep developing on Debug Builds, so the firmware a Rollback returns to always has the console.
+After 3 crash restarts in a row the firmware starts in **Safe Mode** (ADR 0005): only Wi-Fi, Firmware Updates and, if it's switched on, the Debug Console, so a fix can be pushed as usual. `reboot` leaves it.
@@ -5,7 +5,7 @@ RUN apt-get update \
 && apt-get install -y --no-install-recommends git build-essential \
 && rm -rf /var/lib/apt/lists/*
-RUN pip install --no-cache-dir platformio
+RUN pip install --no-cache-dir platformio gcovr
 # Toolchains and libraries are cached in a named volume mounted here.
 RUN mkdir -p /pio && chmod 777 /pio
@@ -1,5 +1,7 @@
 # A Debug Console over Wi-Fi, in Debug Builds only
 **Superseded in part by [ADR 0010](0010-debug-console-in-every-build.md) (2026-10-06):** there is no Debug Build any more. The console is in every firmware, off until switched on, and its token belongs to the device, not to the build. What this record says about how the console works (the ring, commands on the main loop, binary commands on its own task, one client) still holds.
 The goal of Firmware Updates is to manage the device without a cable, and that includes finding out what went wrong. So a **Debug Build** (`cardputer-adv-debug`, `-DRORO_DEBUG`, version suffix `+debug`) adds a **Debug Console** on TCP 2323: the serial console, over Wi-Fi. A client sends a token as its first line, then gets the last 4 KB of console output (boot messages included), every new line live, and runs the same commands as the serial port, plus a few that only make sense remotely. ESP-IDF's own log lines are teed into it.
 It's compiled out of release builds entirely, rather than switched off by a setting. A console that runs commands is a remote control: in a release build, nothing listens.
@@ -1,9 +1,9 @@
 # Safe Mode, crash reports and a watched main loop, in every build
-Rollback protects against new firmware that fails Probation. It does nothing for firmware that was confirmed and crashes later: a corrupt setting, a server that sends something unexpected, a bug that takes an hour to show. Without a cable, such a device would restart forever. Three measures, in release and Debug Builds alike, keep it reachable:
+Rollback protects against new firmware that fails Probation. It does nothing for firmware that was confirmed and crashes later: a corrupt setting, a server that sends something unexpected, a bug that takes an hour to show. Without a cable, such a device would restart forever. Three measures, in every build, keep it reachable:
- **Safe Mode.** The firmware counts starts that follow a crash (panic or watchdog) in NVS, first thing at boot. After 3 in a row, it starts only the clock, Wi-Fi, the Update Service and, in a Debug Build, the Debug Console: no Apps, no IRC, no SD card, and a screen that says so with the address to push an update to. Any normal restart (a `reboot`, an update), or a minute of uptime, resets the count.
+- **Safe Mode.** The firmware counts starts that follow a crash (panic or watchdog) in NVS, first thing at boot. After 3 in a row, it starts only the clock, Wi-Fi, the Update Service and, if it's switched on, the Debug Console: no Apps, no IRC, no SD card, and a screen that says so with the address to push an update to. Any normal restart (a `reboot`, an update), or a minute of uptime, resets the count.
- **Crash reports.** The same boot record keeps which version was running, so after a crash the firmware knows which one crashed, even when a Rollback has switched slots since. ESP-IDF already writes a core dump to its flash partition on a panic; after the restart the firmware prints its summary (task, PC, reason, backtrace) and raises a Notification. The `crash` command shows it again later. In a Debug Build, `scripts/rdbg.py crash` decodes the backtrace and `scripts/rdbg.py coredump` fetches the whole dump for `esp-coredump`, against the ELF of that exact build (`.pio/elves/`, named by version and ELF digest).
+- **Crash reports.** The same boot record keeps which version was running, so after a crash the firmware knows which one crashed, even when a Rollback has switched slots since. ESP-IDF already writes a core dump to its flash partition on a panic; after the restart the firmware prints its summary (task, PC, reason, backtrace) and raises a Notification. The `crash` command shows it again later. With the Debug Console, `scripts/rdbg.py crash` decodes the backtrace and `scripts/rdbg.py coredump` fetches the whole dump for `esp-coredump`, against the ELF of that exact build (`.pio/elves/`, named by version and ELF digest).
 - **The main loop is watched.** Arduino-ESP32 subscribes only core 0's idle task to the task watchdog, and the main loop runs on core 1: a stuck loop used to hang the device for good, with the screen frozen and the Debug Console unable to run commands. `enableLoopWDT()` makes a loop stuck for 5 s a panic, with a core dump, counted towards Safe Mode. And an installed update no longer depends on the main loop: the Update Service restarts into it by itself after 90 s.
 ## Consequences
@@ -0,0 +1,17 @@
 # CI signs releases with the project's key
 A tag `v*` is built, signed and published by Gitea Actions with nobody at a keyboard. The signing key of ADR 0003 is therefore held twice: in `~/.config/roro9stack/ota-key.pem` on the development machine, as before, and as the repository secret `OTA_SIGNING_KEY`, which the release step writes to a file for as long as it runs.
 We chose this over signing by hand after CI has built (a command per release, the key in one place), and over a second key for CI that the firmware would also trust. A release that needs a manual step isn't made on the day it's ready, and issue #6, the device installing releases by itself, needs releases that are always there and always signed.
 ## What it costs
 - **Whoever can run a workflow in this repository can sign firmware every device accepts.** That means: anyone who can push to it, the runner's host and whoever administers it, and the Gitea instance with its database, where the secret is stored. Before, it took the development machine.
 - The runner executes jobs **on its own host**, not in a container, as a user who can use Docker. A workflow is not confined.
 - Pull requests from forks must never run with this secret. Gitea doesn't pass secrets to them; the workflow also only runs on pushes and by hand.
 ## What limits it
 - The release step checks the signed file against the public key in the sources it built (`scripts/ota_verify.py`): a wrong or replaced secret stops the release instead of publishing a file no device takes.
 - ADR 0003's way out stays: a firmware release can carry a new public key. If the secret is ever in doubt, make a new pair, ship it in a release signed with the old key, and replace the secret.
 - A device still only installs what it's told to (until #6), keeps a new image on Probation, and rolls back one that doesn't hold.
@@ -0,0 +1,22 @@
 # The device trusts the two ISRG roots for what it fetches
 The firmware talks to the project's Gitea over HTTPS (issue #6, and #4 after it). A TLS client has to decide whose certificates it believes. Three ways were possible:
 - **The framework's bundle**, about 130 certificate authorities (about 60 KB of flash). Any of them could vouch for `git.twis.la`.
 - **Pin the server's certificate**, as the Gemini App does for capsules. The server's certificate is replaced every few months, so a pin would ask the question again at every renewal.
 - **Carry the roots the server's chain ends in:** `ISRG Root X1` (RSA 4096) and `ISRG Root X2` (ECDSA P-384), the Let's Encrypt roots, about 2.7 KB of flash (`src/platform/ca_roots.h`).
 We chose the third. The chain and the name are checked by mbedTLS during the handshake. It trusts one organisation's two roots, valid until 2035 and 2040, and a renewal changes nothing.
 ## What it costs
 - **If the server moves to another CA, the device can no longer reach it**, and the next firmware, carrying that CA's root, has to come from the PC or the SD card. Both still work; they don't use TLS.
 - The roots are public data checked against the published fingerprints (listed in the file), refreshed by hand if Let's Encrypt ever changes them.
 ## What it doesn't change
 The Update File's own signature (ADR 0003) is what decides what gets installed. A hijacked connection could hide a release, or serve an older signed one, but never make the device install firmware that isn't ours. The TLS check matters more for #4, where a token will travel over it.
 ## Measured while building it
 A TLS connection to this server peaks at about 52 KB of heap, **the same whether the certificate is checked or not**, so skipping the check would have saved nothing. The cost is the connection itself (record buffers and handshake), not the trust decision.
@@ -0,0 +1,30 @@
 # The Debug Console is in every build, off until its owner switches it on
 There is **one firmware**. The Debug Console of ADR 0004 is compiled into it, and so are the commands that used to exist only in Debug Builds. It listens only while **Settings → Debug Console** is on, which is not the default, and it lets in whoever proves they hold **the device's own token**. The `cardputer-adv-debug` environment, `RORO_DEBUG`, the `+debug` version and the token compiled in from the builder's machine are gone.
 ADR 0004 kept the console out of release builds with one argument: a console that runs commands is a remote control, so in a release nothing should listen. That argument was never whole: the Update Service has listened on TCP 3232 in every build since Firmware Updates exist, guarded by a signature. A listener that is off by default and guarded by a secret the device made itself is the same kind of trade, and what the split cost had grown:
 - **What was tested wasn't what shipped.** Development ran on Debug Builds; releases were a different binary, built to be published and never run by the person who wrote them.
 - **Debug Builds couldn't be published**, since each carried its builder's token. So the console, `rdbg.py`, screenshots and crash decoding were for whoever built the firmware, and nobody else.
 - **Rules that existed only to protect the console:** a Debug Build never installed a release (it would have lost the console), `update install … force` to do it anyway, "keep a Debug Build in the fallback slot", versions with `+debug` that had to compare equal to their release.
 - **CI built two firmwares** on every pull request and every tag.
 ## How it works
 - **Off means nothing is there.** With the setting off, no socket listens, the console's task doesn't exist and neither does its 4 KB ring: a device that never uses the console pays for it in flash (30 KB more than the release build was) and 88 bytes of static RAM, measured. A missing or invalid stored setting counts as off.
 - **The token is the device's.** The first time the console is switched on, the device makes one from its hardware random generator: 100 bits, as 20 characters of Crockford's base32 (`K7QF-3M2X-9WBD-HT4P-6RNC`), shown on the Debug Console page and nowhere else. It can be replaced by one typed by hand, of 16 to 64 characters. It is stored with the other settings and is never printed on a console.
 - **The token never crosses the network.** The device sends 16 random bytes; the client answers with their HMAC-SHA256 keyed by the token. Someone on the same Wi-Fi who records a login has nothing they can use for the next one.
 - **Five wrong answers in a row** close the console to everyone for a minute, with a Notification naming the address they came from. A wrong answer still costs a second.
 - **`DBG` in the Status Bar** while the console listens, bright while a client is connected.
 - **USB serial can set it up:** `debug on`, `debug token <value>`, `debug token new`. `scripts/flash.sh --debug` uses them to give a freshly flashed device the developer's token. Whoever holds the cable can flash anything anyway (ADR 0003); the console itself can only switch itself off.
 - **Safe Mode** starts the console if it's switched on: the settings are read before Safe Mode is decided.
 ## Consequences
 - **"Nothing listens" now rests on one stored setting**, not on absent code. That setting is typed, validated and host-tested, and its default is off; a bug that flipped it would have to come from code that already runs on the device.
 - **Whoever has the token and the network has the device:** the console, its keys, the SD card's files, a restart. Not its firmware: an update still has to be signed (ADR 0003).
 - **The stream is still plain text.** The token is safe from an eavesdropper; what the console prints, and the files it carries, are not. TLS would cost about 52 KB of the 107 KB there is, next to IRC's own connection: not for a console.
 - **An old `rdbg.py` can't talk to a new firmware**, and the reverse: the first line of the protocol changed. Accepted, with one user.
 - **A device whose settings are damaged has no console in Safe Mode**, only the signed update push. Before, a Debug Build always had it.
 - **The commands that crash, damage a download or fill a folder on purpose** are in every build. They need the cable or the token, like everything else.
 - **Releases already publish their ELF**, so `rdbg.py crash` fetches it when it isn't in `.pio/elves/`: crash reports can be decoded without having built the firmware.
@@ -0,0 +1,335 @@
 # F1 — Files and Notes
 **Status:** in progress. The Storage App (issue #3) shipped as **v0.9.0** on 2026-10-06. Notes (#19) shipped as **v0.10.0** the same day. The card as a USB drive (#1) comes after.
 **Goal:** get at what's on the SD card from the device itself: browse it, look inside the files the firmware writes, copy, move, rename and delete, and keep notes. A side milestone, like G1 and S1; Files and Notes were M3's original second half (Q30, Q89).
 ## The Storage App (issue #3)
 Until now the card could be looked at only through the Debug Console (`ls`, `get`, `put`), and Settings > Storage could only delete whole categories by age.
 **On the card today:** six top-level folders, `irc`, `wifi`, `updates`, `gnss`, `gemini` and `captures`. No `notes` yet; settings are in flash, not on the card.
 ### Decisions (design round 2026-10-06)
 | # | Decision |
 |---|---|
 | Q128 | An App of its own, **Storage**, in the Launcher. **Settings > Storage goes away:** its usage figures, Storage Clean-up and "Erase SD card" move into the App, under **Maintenance**, behind a warning that these delete things for good. |
 | Q129 | A row shows the name, then the size or "folder", then the date modified. Folders first, then by name; `s` cycles the sort (name, date, size). The top line shows the path and the card's free space. |
 | Q130 | Nothing is hidden. **Read-only:** `/gemini/cache`; any file the firmware has open right now (today's IRC log, a Track or Capture being recorded, a file being received); and the top-level folders themselves, which can't be renamed or deleted though their contents can. **Everything else, the user's own data included, can be renamed, moved or deleted**, always after a confirmation. |
 | Q131 | One item at a time, with a clipboard: Enter opens; Back goes up, and leaves the App at the top; `c` copy, `x` cut, `v` paste into the current folder; `r` rename; `d` delete; `n` new folder; `i` details. |
 | Q132 | Copy, move and delete work on folders too, recursively. The confirmation says what's inside: "Delete *saved* and its 42 files?". |
 | Q133 | A copy is a job on the storage task in 4 KB pieces, with a progress Toast; Back cancels it. It checks free space first and asks before replacing anything. **Afterwards the sizes are compared**, not the contents: the driver is trusted since v0.6.1 (ADR 0007). A move within the card is a rename. |
 | Q134 | Viewers by type. **Text** (`.txt`, `.log`, `.gmi`, `.csv`, `.gpx`, and anything that looks like text): read from the card as you scroll, so size doesn't matter; logs open at the end. **`.pcap`:** the LoRa Scanner's packet list. **`.gpx`:** a summary (start, duration, points, distance), Tab for the text. **`.ota`:** version, size, whether the signature is valid; Enter installs through Update from SD. **Anything else:** a hex dump. |
 | Q135 | No editing: that comes with Notes (#19). |
 | Q136 | A listing holds **up to 256 entries**, packed, about 10 KB; a bigger folder shows the first 256 by name and says how many more there are. The App refuses to open below the memory floors (Q86). |
 | Q137 | **The Clock also sets the system time**, so files are dated correctly with GNSS alone and not only after NTP. A file dated before 2020 shows "-". |
 | Q138 | Console: `cp`, `mv` and `mkdir`, next to `ls` and `rm`. |
 | Q139 | Left out, each with its issue: selecting several items (#41), finding files by name (#42), opening a `.gmi` in the Gemini App (#43), a table view for `.csv` (#44), images (#45). |
 | Q140 | Ships as **v0.9.0** when done and checked. |
 ### Done when
 - The Storage App lists any folder of the card with sizes and dates, sorted three ways, and says so when a folder has more than 256 entries.
 - A file can be copied, moved, renamed and deleted, and a folder too; a new folder can be made. Each destructive action asks first; a copy shows progress and can be cancelled.
 - The read-only rules of Q130 hold, with a reason given when something is refused.
 - Each viewer of Q134 opens its type, and a 1 MB text file scrolls without loading whole.
 - Maintenance shows the card's usage and does what Settings > Storage did, behind its warning; Settings no longer has a Storage row; the Storage Warning points at the Storage App.
 - A file written with only a GNSS Fix (no Wi-Fi) is dated correctly.
 - Free heap stays above the floors with the App open, Wi-Fi and IRC on TLS.
 ### Work breakdown
 1. **Model** (host-tested): paths and names, the read-only rules, the packed listing and its sorts, file types, sizes and dates for display, the GPX summary.
 2. **Card operations:** listing a folder, copy, move, delete (recursive, counted), new folder, as storage jobs with progress and cancel; `cp`, `mv`, `mkdir`; the Clock sets the system time.
 3. **The App:** browsing, the clipboard, dialogs, details.
 4. **Maintenance:** usage, Clean-up and Erase moved in from Settings, with the warning.
 5. **Viewers:** text, hex, `.pcap`, `.gpx`, `.ota`.
 6. **Checks on the device**, recorded here.
 ### As built
 - **`FileOps`** (`src/services/file_ops`) does the card's work for the App and for the console alike: list, count, copy, move, delete, new folder. One operation at a time on the storage task, **in turns of about 150 ms** that queue themselves again, so Log lines and a Capture are written in between. The rules of Q130 are checked there, whoever asks.
 - **A listing reads the folder straight from FatFs.** Through the Arduino `File`, every entry was looked up by name again for its size and again for its date: 329 entries took over two seconds. One pass now, and it's there before the screen has redrawn. Counting, copying and deleting still walk with `File`; they show progress and can be stopped.
 - **A copy shows its progress in a box in the App**, not a Toast (Q133): it has a bar and says Back cancels. A cancelled or failed copy deletes what it had written. The copy gets today's date, like `cp`.
 - **The viewers** (`src/apps/file_viewer`, models in `lib/files`): text through `TextPager`, which reads about a kilobyte around the screen and wraps at spaces, 38 columns; going back a line wraps the paragraph before again, so a file reads the same in both directions. A `.pcap`, a `.gpx` and an `.ota` are read through once by a storage job, in the same 150 ms turns. An Update File is fed to the installer's own parser with a sink that writes nothing, so "would it install" is the same answer an install gives.
 - **Tab** in a viewer shows the same file as hex, or as text (not in Q134).
 - **Maintenance** is the last row at the top of the card, and `m` anywhere in the App. It's the old Settings > Storage page behind a dialog.
 - **The Storage Warning** was only ever a Toast; "selecting it opens Storage Clean-up" (CONTEXT.md) was never built. It now reads "SD card over 80% full: see Storage".
 - **Console:** `cp`, `mv`, `mkdir` (Q138), and `rm` and `du` through the same code, so `rm` now takes folders and follows the rules; `ls` shows dates. Debug Builds: `sd fill <folder> <count>` makes test files.
 ### Checks on the device (2026-10-06, v0.8.1-2 Debug Build)
 All in a scratch folder, `/f1test`, removed afterwards.
 | Check | Result |
 |---|---|
 | Host tests | 424 pass (411 before the viewers' models) |
 | Browsing | Folders first, sizes and dates, the three sorts; a 300-file and a 329-file folder show "first 256 of 300" and "of 329" |
 | New folder, rename, copy, cut and paste, delete | Each works on a file and on a folder; a copy next to its original is named `(2)`; a name in the way asks "Replace it?" |
 | A folder of 11 files, 8.4 MB, copied | 19.4 s, 435 KB/s, the bar moving; two Log lines queued meanwhile were written |
 | The same copy cancelled at 1.8 MB | "Cancelled: nothing was copied", and nothing was left behind |
 | Delete | 341 files in 9.7 s; the dialog had counted them first |
 | Read-only rules | `/irc`, `/gnss` (top-level folders), `/`, `/gemini/cache` and a folder made inside it, a folder into itself, a name with `:`; a Capture being recorded and the folder holding it; a folder under `/irc` while IRC runs. Each refused with its reason; the Capture could still be copied |
 | Text | A 1 MB log opens at its last line at once; top, pages, lines; a file without an extension that looks like text opens as text |
 | Hex | A 5 KB binary file; Tab from any other viewer |
 | `.pcap` | A LoRa Capture: 3 packets as the Scanner lists them, Enter shows the Meshtastic header and bytes |
 | `.gpx` | 400 points: start, 33 min 15 s, 4.68 km; Tab shows the text |
 | `.ota` | A signed file: version, "intact", "older than what's running", Enter asks to install (not confirmed). A tampered one: "image corrupted (hash mismatch)" |
 | Maintenance | The warning, then usage, Clean-up's categories and Erase (not run) |
 | Date with GNSS only | NTP pointed at an address that doesn't answer, restart: the Clock came from the Fix, and a folder made then is dated 2026-10-06 08:39. A Track from the day before, written the same way by v0.8.1, shows "-" |
 | Memory | IRC connected, the App open on 256 entries: 61 KB free (70 KB before opening). Lowest since boot 29.7 KB, during IRC's TLS handshake |
 | Stacks | `storage` 3.1 KB free of 6 KB at worst, `loopTask` 1.5 KB |
 **Not checked by hand:** how the keys feel on the device itself; everything above was driven through the Debug Console's `key` command and screenshots.
 **One slip during the checks:** a scripted key sequence ran in the wrong folder and renamed `/gemini/saved` to `saved2`, then copied it to the top of the card. Both were put right at once (renamed back, the copy deleted; 7 files, 53,798 bytes, as before).
 **Found on the way:** a panic at Wi-Fi join, there since v0.7.0 (SNTP started twice, issue #46). Fixed in v0.9.0.
 ## Notes (issue #19)
 Plain text notes on the SD card, written on the device. Q30 settled the base: `.txt` files in `/notes`, created, edited and deleted from the device, never offered by Storage Clean-up.
 ### Decisions (design round 2026-10-06)
 | # | Decision |
 |---|---|
 | Q141 | A **Notes** App in the Launcher. One row per note: its first line as the title, then the date. Newest first; `s` switches to by name. `n` new, Enter opens, `d` deletes after a confirmation, `r` renames the file. |
 | Q142 | A new note's file name is never typed: it comes from the first line when the note is first saved (`shopping-list.txt`), or `note-20261006-0919.txt` if that line is empty. It doesn't change afterwards unless the note is renamed. |
 | Q143 | **Autosave, no "discard changes?" prompt:** five seconds after the last key, on leaving the note or the App, and when the screen turns off. A save writes a temporary file and renames it over the note, so a power cut loses the last few seconds at most. A temporary file left behind is offered back at the next open. |
 | Q144 | The whole note is in memory while it's edited, up to **16 KB**. A bigger text file opens read-only in the Storage App's viewer. The App refuses to open below the memory floors (Q86). *(Lifted by issue #47: see "Notes of any size" below.)* **Editing files of any size must come in a later release: issue #47.** |
 | Q145 | The editor wraps at spaces, 38 columns by 8 rows, with a line for the name and the state. Enter is a new line, Del deletes backwards, Fn+arrows move (the Text Entry rule), Ctrl+A and Ctrl+E go to the start and the end of the line, Tab types two spaces, Back saves and returns. The Compose Key works as elsewhere. |
 | Q146 | The Storage App's text viewer gets `e`: edit this file with the same editor, for a text file up to 16 KB that isn't read-only. That lifts Q135 without Apps opening each other (#43 stays). |
 | Q147 | The list is flat: the files directly in `/notes`. Sub-folders are reached through the Storage App. |
 | Q148 | UTF-8, LF line ends; a file with CRLF is saved back with LF. Characters the font lacks are kept on save. |
 | Q149 | Left out, each with its issue: editing files of any size (#47), searching inside notes (#48), undo (#49), selecting and copying text (#50). |
 | Q150 | Ships as **v0.10.0** when built and checked on the device. |
 ### Done when
 - A note can be started, typed with accents, left and found again in the list under its first line; renamed; deleted after a confirmation.
 - What's typed is on the card five seconds after the last key, and after Back, Home, or the screen turning off, without a prompt.
 - Pulling the power while typing loses a few seconds at most, and the note is never left empty or half-written.
 - The cursor moves by character and by line through wrapped text, and the screen follows it; a 16 KB note edits without lag.
 - A note at 16 KB refuses more text and says so; a bigger file opens read-only.
 - `e` in the Storage App's text viewer edits a file; a read-only one is refused with its reason.
 - Free heap stays above the floors with a 16 KB note open and IRC connected.
 ### Work breakdown
 1. **Model** (host-tested): the text buffer with its cursor, wrapping and scrolling; file names from first lines.
 2. **The editor on the device:** loading, drawing, keys, autosave through a temporary file, recovery.
 3. **The Notes App:** the list with titles, new, rename, delete.
 4. **`e` in the Storage App.**
 5. **Checks on the device**, recorded here.
 ### As built
 - **`NoteText`** (`lib/notes`, host-tested) is the text, its cursor and the screen around it. A line owns the space or the newline it ends with, so every byte is on exactly one line and the cursor has one place for each. **No index of lines is kept:** a note of newlines alone would need twice its own size for one. Where a line starts is worked out from the start of its paragraph.
 - **One buffer, 16 KB, for as long as the editor is open.** It's reserved when the note is opened, the file is read straight into it, and typing never makes it grow. On this device a failed allocation is an abort, and with IRC connected the largest free block is about 31 KB whatever the total says: the first version read the file into one string and copied it into another, and opening a full note with IRC connected restarted the device. The editor now also refuses to open without a free block of 24 KB.
 - **`NoteEditor`** (`src/apps/note_editor`) is shared by the Notes App and the Storage App's `e`. A save runs on the storage task while the main loop waits for it: no second copy of the note, and at 16 KB the wait is a fraction of a second at a moment when nobody has typed for five.
 - **A save** writes `<note>.tmp`, checks its size, deletes the note and renames the temporary file (FAT can't rename onto a file). A cut between the last two steps leaves only the `.tmp`: the Notes list puts such a file back under its name. A `.tmp` next to its note is an unfinished save: opening the note offers it.
 - **Titles** in the list are read from the card for the eight rows on screen, when the list moves.
 - **Before powering off**, the firmware now leaves the foreground App (`PowerService::beforePowerOff`), which makes the editor save.
 - Shift or Alt with Fn+Up and Fn+Down moves a page (not in Q145).
 ### Found on the way
 - **The screen could go "off" for one tick after a key sent through the Debug Console**, and the next key was then swallowed as a wake-up: the `key` command stamps the power timer from `millis()`, the power tick compares with its pass's older time, and the unsigned difference read as 49 days idle. The same shape as #46. Fixed in `PowerPolicy::update` with a test. Keys from the keyboard were never affected. It explains remote keys "lost" in earlier sessions.
 - **`scripts/rdbg.py` held back piped lines** written while it was still connecting, until the next line came (a buffered `readline()` behind `select()`). Fixed.
 ### Checks on the device (2026-10-06, Debug Build of branch `notes`)
 Test notes were made in `/notes` and removed afterwards; the folder is left, empty.
 | Check | Result |
 |---|---|
 | Host tests | 439 pass |
 | A first note | "No notes yet", `n`, typed three lines: the top line says "typing", then "saved" five seconds after the last key, under `shopping-list.txt`. 63 keys in a row all arrived |
 | Leaving | Back saves and returns to the list, which shows the note under its first line. Home in the middle of a new note saved it as `ideas.txt` |
 | The cursor | Down, Right, an insertion in the middle of a line; the screen scrolls through a note of about 230 lines |
 | A power cut | Typed, waited seven seconds, typed more and restarted the device at once (`reset`): the note has what was saved, whole, and not the last keys |
 | An unfinished save | A `.tmp` next to its note: "Unsaved copy... Keep the note / Use the copy"; using it brings its text back and saves it. A `.tmp` alone was put back under its name when the list opened |
 | 16 KB | A note of exactly 16,384 bytes opens and scrolls; one more character: "This note is full: 16 KB". A file of 16,398 bytes: "Too big to edit: 16 KB at most" |
 | Rename, delete, sort | `r` renamed `orphan.txt` to `orphan2.txt`; `d` asked, then deleted; `s` switched between newest first and by file name |
 | `e` in the Storage App | A note opened from the text viewer, edited, saved on Back; the listing shows its new size |
 | Memory | IRC connected, the full 16 KB note open: 55 KB free, largest block 31.7 KB (72 KB free before opening) |
 **Not checked:** accents through the Compose Key and Ctrl+A / Ctrl+E (the remote `key` command can't send them; the model's tests cover both), the power button's save (it needs a hand on the device), a missing card, and how typing feels on the keyboard itself.
 **One slip during the checks:** a key sequence sent right after a restart opened IRC instead of Notes, and the test letters went into IRC's input line. Nothing was sent: the line was cleared and the App left. IRC connected to Libera as it does when opened.
 ## Notes of any size (issue #47)
 Q144 held the whole note in memory and stopped at 16 KB, for the first version only. This lifts it: the editor opens a text file whatever its size.
 ### Decisions (design round 2026-10-07)
 | # | Decision |
 |---|---|
 | Q223 | **The note is the file on the card plus one window in memory.** The window is the `NoteText` of before, up to 16 KB around the cursor; the rest is a list of pieces: runs of the file, and runs of a side file. The cursor leaving the window writes it to the side file if it was changed, and loads the next. Typing never fills a note: a full window is written away and loaded smaller. |
 | Q224 | **The five-second save:** up to 64 KB it rewrites the file, as before (about 150 ms). Above, it appends the window and the list of pieces to `<note>.edit`: 8 KB or so, whatever the note's size. "saved" means "on the card" either way. |
 | Q225 | **The file itself is rewritten on leaving the note** (Back, Home, another App), with a progress bar. The screen turning off and the device powering off write the side file only: powering off never waits. |
 | Q226 | **After a power cut, opening the note picks the edit up** where it was last saved, without a question, and says so. Until then the file has the old text for anything else that reads it. |
 | Q227 | If the file was changed elsewhere meanwhile, the side file no longer fits it: it is **kept as `<note>.edit.lost`** and the editor says so. Typed text is never deleted without a word. |
 | Q228 | **No limit but the card:** a note over 16 KB needs room for a second copy to be opened for editing. No warning for a big file; the progress bar on leaving tells the cost. |
 | Q229 | A side file over 1 MB, or a list of over 256 pieces, makes the next save a rewrite. |
 | Q230 | **CRLF becomes LF** (Q148) for a long file too: in the window as it is read, and in the rest of the file as the rewrite streams it, so a saved file is never of both kinds. |
 | Q231 | **One path.** A 16 KB note is the case with no pieces: there is no second editor for small notes. |
 | Q232 | Notes, and `e` in the Storage App's viewer, which no longer says "Too big to edit". |
 ### As built
 - **`NoteDocument`** (`lib/notes/src/note_document.h`, host-tested against a card in memory) is the list of pieces, the window's moves, the side file and the recovery. `NoteText` is unchanged but for being refilled.
 - **The window moves** when the cursor comes within 2 KB of an end of it that isn't an end of the note: it is then 4 KB on each side of the cursor. It starts where a line starts on screen whenever that can be known (after a newline, or where the window before had a line start), so the same text wraps the same from one window to the next, and never in the middle of a character. The cursor keeps its row on screen.
 - **Looking writes nothing:** a window that wasn't changed goes back as the pieces it was read from.
 - **The side file** starts with a line of text, the note's size and checksums of its first and last kilobyte, which is how a file changed elsewhere is told. After that, text that left a window, and snapshots of the list of pieces, each with its checksum. The newest snapshot that checks out is the note as last saved; anything after it is ignored.
 - **The rewrite** streams the pieces and the window into `<note>.tmp`, checks its size, then writes a mark at the end of the side file: from that mark on, the rewrite counts as done, and opening the note finishes it whatever was cut (remove the old file, rename, remove the side file). Before the mark, the note and its side file are still the truth and the temporary file is dropped.
 - **On the device** the card is reached through an adapter that keeps the file being read and the file being appended to open between calls; every call runs on the storage task while the main loop waits. The rewrite runs in steps of 64 KB with the progress drawn between them.
 - **The Notes list** doesn't show `.edit` and `.edit.lost` files, and a note's side file is deleted and renamed with it.
 - **Ctrl with Fn+Up and Fn+Down** go to the start and the end of the note.
 - **`key ctrl-down`**: the consoles' `key` command takes `ctrl-`, `alt-` and `shift-`, which these checks needed. It also lets the checks S1 couldn't make (Ctrl+b, the Alt scroll) be made.
 - **Cost:** 15 KB of flash. Memory with a note open is what it was: 17.5 KB, for 62 bytes or for 1.2 MB.
 ### Host tests (15, `test/test_note_document`)
 A walk down 3,000 lines and back up through the windows; start and end; an edit in the middle rewritten into the file; 48 KB typed into a new note; a journal picked up after a cut; **a cut at every 997th byte of a sequence of two saves and a rewrite**, after which the note is always one of the three texts it should be, what was reported saved is there, and no stray file is left; a file changed elsewhere; CRLF; windows on text with no space and no newline, made of 2, 3 and 4-byte characters; a full card; and **36,000 random keys** (typing, deleting, moving, jumping, saving, power cuts) on six notes of 30 to 130 KB, compared with a plain string after every key.
 ### Checks on the device (2026-10-07, driven over the Debug Console)
 Test notes were copied to `/notes` and removed afterwards; the note that was already there was not touched.
 | Check | Result |
 |---|---|
 | A 36 KB note | Opens (it was refused before). Two letters at the top, 400 lines down across the windows, four more: the file fetched back is exactly that, and no other file is left |
 | A 1.2 MB note | Opens at once. Free memory 104.2 KB before, 86.7 KB with it open |
 | Its five-second save | `zz-big.txt.edit`, 4 KB; the note's file untouched |
 | Ctrl with Down, Ctrl with Up | The end and the start, as fast as any key |
 | A restart with unsaved keys | "Your unsaved changes are back", the cursor where it was, the unsaved keys gone and nothing else |
 | Leaving it | The progress bar, then one file: **1.2 MB rewritten in 2.6 s**. Fetched back: the original with what was typed at both ends, byte for byte |
 | A restart in the middle of that rewrite | The note, its side file and an empty `.tmp` remain; opening picks the edit up, leaving rewrites it, the result is right |
 | A new note | No file until typed in, then `zz-test-note.txt` from its first line |
 | `e` in the Storage App on the 1.2 MB file | The same editor; edited and rewritten |
 | The Notes list | Side files are not listed as notes |
 **Not checked:** the power button's path (side file only), the screen turning off, a card pulled while editing, and memory with IRC connected, which wasn't connected for these checks: the editor's own use hasn't changed, and it still refuses to open without a free block of 24 KB. The real keyboard's Ctrl with Fn and the arrows. A file of tens of megabytes. Renaming or deleting a note from the Storage App leaves its side file behind.
 **Measured against what was said:** the first build rewrote 1.2 MB in 3.5 to 4.5 s, with 2 KB blocks. With 4 KB blocks it is 2.6 s, about 450 KB a second, which is what the card gives a plain copy.
 ## Pictures in the Storage App (issue #45)
 Q139 left images out: the firmware wrote none. Since the Shell's `screenshot` it does.
 ### Decisions (design round 2026-10-07)
 | # | Decision |
 |---|---|
 | Q233 | **PNG, JPEG, BMP and GIF.** A GIF shows its first picture; it doesn't move. |
 | Q234 | *Revised while building.* **Our own PNG decoder**, a row at a time, with the window the file's compression asks for: 32 KB at most. The plan was the display library's, which takes 44 KB in one block: after one picture the largest free block was 43 to 47 KB, and every second PNG was refused. **The firmware's own screenshots** are read with no decoding at all: they are stored uncompressed, each byte already a colour of the screen. |
 | Q235 | **The picture is decoded once, straight into the screen's buffer, and left there.** No copy in memory (it would be up to 30 KB). `App::retainsContent()` tells the screen not to clear the App's part; `contentLost()` tells the App that it was cleared after all, or that a Toast or the help panel drawn over it has gone: then it is decoded again. |
 | Q236 | **Shrunk to fit; Enter shows it at its own size**, the arrows then moving half a screen. A picture smaller than the screen sits in the middle at its size. |
 | Q237 | **Ordered dithering** to the screen's 256 colours (a 4 x 4 pattern). A colour the screen has exactly comes out as itself wherever it lands, so a screenshot isn't touched. |
 | Q238 | Shrinking takes, for each pixel of the screen, the first of the picture's that falls on it. No averaging: there is nowhere to keep the sums. Thin lines break up; a JPEG looks better, its decoder halving it up to three times first. |
 | Q239 | **What can't be shown opens as hex, with the reason:** a progressive JPEG, an interlaced PNG, a BMP that is compressed or has 16 bits. The rotation a camera stores in the file is ignored. |
 | Q240 | *Revised while building.* **Decoding runs on the storage task while the main loop goes on.** The picture appears as it comes, and anything that needs the screen back stops the decoding first. The plan was to wait for it, behind a "Decoding..." line: 12 megapixels took longer than the watchdog allows the main loop to stand still, and the device restarted. |
 | Q241 | The Storage App: Enter on `.png`, `.jpg`, `.jpeg`, `.bmp`, `.gif`, or on a file with no known extension whose first bytes say what it is. Tab gives the hex. `i`, and opening, show the size in pixels on the last line for three seconds. |
 | Q242 | Not in this one: animation, opening a picture from the Gemini App, a slideshow. |
 ### As built
 - **`lib/files/src/image_file.h`** (host-tested): what a file is and how big, where each pixel lands (`ImageFrame`, `ImageMap`), the dithering, and readers for BMP and GIF that hand their pixels on as they get them. **`png_reader.h`**: the PNG decoder, with its own inflate: every colour type and bit depth, palettes with transparency. Transparent pixels are left as the background.
 - **`ImagePane`** (`src/apps/image_pane`) is the view. One decoding is a `Job` shared with the storage task; `cancel()` flags it and waits behind it in the task's queue, which is how the screen is known to be free again.
 - **JPEG is the one decoder that isn't ours:** the display library's TJpgDec, with its 3.9 KB pool. It shrinks by 2, 4 or 8 while decoding, which is why a photograph is possible at all.
 - **A decoder stops early** once the rest of the file is below the screen (a picture at its own size), and a BMP's rows that aren't shown aren't read.
 - **The note** on the last line is written over the picture; the strip under it (2.6 KB) is kept and put back, so showing it costs no decoding.
 - **A BMP is read in the order its rows are stored**, last row first: reading it top to bottom meant going back through the file for every row, a second for 135 rows.
 - **Cost:** 21 KB of flash. Nothing while no picture is shown.
 ### Measured on the device
 | Picture | Fitted | Its own size |
 |---|---|---|
 | A screenshot of ours, 240 x 135 | 80 ms | 78 ms |
 | PNG, 800 x 600 | 855 ms | 575 ms |
 | PNG with transparency, 800 x 600 | 1,098 ms | |
 | JPEG, 800 x 600 | 305 ms | |
 | JPEG, 4000 x 3000 (2.6 MB) | 6.9 s | 7.7 s (the middle of it) |
 | GIF, 800 x 600 | 642 ms | |
 | BMP, 800 x 600 (1.4 MB) | 991 ms | |
 | BMP, 240 x 135 | 124 ms | |
 Free memory fell to 48.8 KB at the lowest while a PNG was decoded, from 104 KB. The storage task's stack: 3.2 KB never used, of 6.
 ### Host tests (20, `test/test_image_file` and `test/test_png_reader`)
 The pictures in them were made with Pillow, so the readers are checked against an encoder that isn't ours: GIFs plain, interlaced, transparent and long enough for the codes to reach 12 bits; BMPs of 8 and 24 bits; PNGs of every kind (colour, with alpha, palette of 8 and 4 bits with a transparent entry, greys of 1, 8 and 16 bits, grey with alpha, not compressed, and one that refers 21,600 bytes back). Every reader is also fed its file with a byte changed, at every few bytes: an answer each time, and no pixel outside the picture.
 ### Checks on the device (2026-10-07, driven over the Debug Console)
 Test pictures were copied to a scratch folder and removed afterwards, with the test screenshot.
 | Check | Result |
 |---|---|
 | Colour bars as PNG, JPEG, BMP and GIF, 240 x 135 and 800 x 600 | The same picture each time, the colours in the right order |
 | A PNG with a transparent square | The square is the background |
 | A screenshot taken in the Shell | Shown; at its own size it is the screen, pixel for pixel |
 | A progressive JPEG | Hex, with "A progressive JPEG can't be shown" |
 | An animated GIF | Its first picture |
 | 12 megapixels | Arrives from the top down in 6.9 s; the size is noted when it is whole |
 | Enter, then the arrows | Its own size from the middle, then half a screen at a time |
 | Back in the middle of a decoding | The folder's listing at once |
 | Tab to hex and back, three times; the help panel, then closed | The picture again each time |
 **Not checked:** a photograph from a real camera (the test JPEGs were made by Pillow); a Toast over a picture; a PNG with IRC connected, when there may not be the memory; the card pulled while decoding; the real keyboard.
 ### What went wrong while building it
 **The watchdog.** The first version waited for the decoder. The main loop is watched: five seconds without a pass and the device restarts, which is what it did on the 12-megapixel test. The crash report named the decoder's line. The decoding moved to the background, which also made the picture appear as it comes.
 **A decoder that worked once.** The library's PNG decoder showed the first picture and refused the next five: "no memory". It wants 44 KB in one piece, and after some use the largest piece is 43 to 47 KB. Writing a decoder that needs 32 KB was less work than it sounds, and unlike the library's it has tests.
 **Two sentences still said "up to 16 KB"** about editing, in the README and the Storage guide, after issue #47 lifted that. Corrected here.
 ## Sharing the card with a browser (issue #88)
 Files reached the card through the Debug Console's `put` and `get`, or by taking the card out. A phone has neither.
 ### Decisions (2026-10-07; the recommendation was accepted as it stood, without a round of questions)
 - **A web page, not FTP, SFTP or WebDAV.** A browser is the only client every phone has. FTP and WebDAV need an app there; SFTP needs a whole SSH server here. WebDAV can come later on the same server, for computers.
 - **Off unless asked for:** `w` in the Storage App opens a "Share" screen, and the server runs only while that screen is open.
 - **A six-digit code on the screen**, new each time, typed in the page; the address is also a QR code, which carries the code. Five wrong codes close it for a minute (the Debug Console's `AuthGate`). A browser that got it right holds a cookie; starting again puts every browser out.
 - **Not encrypted.** A TLS server costs about 40 KB of memory a connection. The screen says so.
 - **The Storage App's rules** (`whyReadOnly`): the firmware's own folders, and files in use.
 ### As built
 - **`WebShare`** (`src/services/web_share`): ESP-IDF's HTTP server, which is in the framework already. Seven requests: the page, the code, a listing as JSON, a download, an upload, a new folder, a delete.
 - **Every access to the card is handed to the storage task**, 8 KB at a time, from the server's own task: a download and an upload are loops of "one piece from the card, one piece to the network".
 - **An upload is the request's body**, as the browser's `PUT` sends it: no form to take apart. It goes to `<name>.part` and is renamed when the last byte has come; anything less is removed. A file that exists is refused unless the page asked, after asking the user.
 - **The page** (`web_share_page.h`) is one file of 5.4 KB with its style and script in it, served from flash.
 - **`lib/files/src/share_rules.h`** (host-tested, 5 tests): what a request names, which paths a browser may ask for (from the root, no `..`), the JSON, the code and the cookie.
 - **Cost:** 57 KB of flash, most of it the server. 13 KB of memory while sharing (108.4 KB free before, 95.4 with the screen open), given back on leaving.
 ### Checks on the device (2026-10-07 and 08)
 A scratch folder was used and removed.
 | Check | Result |
 |---|---|
 | `w` | The QR code, the address and the code; `share: on` on the console |
 | The page, and a listing without the code | 200; 401 |
 | A wrong code, the right one (typed `825 132`) | 403; in |
 | Upload, 2.6 MB | 11 to 17 s (150 to 230 KB/s); downloaded again and compared: the same, byte for byte |
 | The same name again; with "replace" | 409; replaced |
 | `..` in a path; deleting `/notes`; deleting a folder that isn't empty | 400; 403 "The firmware keeps its files in /notes"; 403 |
 | Five wrong codes | The fifth and every one after: 429, the right code too. A browser that was in stays in |
 | In Chromium at a phone's width | The scanned address logs in by itself; two files uploaded, one downloaded and compared, a folder made, a file deleted after asking, a replacement after asking, the refusal shown. No sideways scroll |
 | Back | The server is gone (connection refused), memory is back |
 **Found on the way:** the server answers one request at a time. A second request during a slow download waited until it had ended. It is said in the guide, and not changed.
 **On a real phone** (the maintainer's, 2026-10-08): the QR code, scanned with the phone's camera, opens the page and logs in; the page lists the card, in the phone's dark theme.
 **Not checked:** Safari. A card pulled during a transfer. Sharing with IRC connected, when memory is shorter. Home, and the screen turning off, while sharing (the code stops the server on leaving the App; only Back was tried).
@@ -0,0 +1,233 @@
 # R1 — Releases
 **Status:** in progress. CI and signed releases on Gitea (issue #5) are in place since 2026-10-06: every tag from v0.1.0 to v0.10.0 has its release. Updates from Gitea (issue #6) is built and checked on the device, on branch `gitea-updates`, not merged yet. The Issues App (#4) comes after.
 **Goal:** a tag is a release, built the same way every time and published where a device can find it.
 ## CI and releases (issue #5)
 Until now the tests, the builds, the signing and the flashing all happened on one machine, through `scripts/ci.sh` and `scripts/flash.sh`. Nothing was published.
 ### Decisions (design round 2026-10-06)
 | # | Decision |
 |---|---|
 | Q151 | A push to `main`: the host tests (with their coverage). A push to another branch: nothing, its pull request is what runs (a branch with an open pull request ran twice, once for each). A pull request: the same and both builds; changes reach `main` through pull requests. A tag `v*`: all of it, then a release. (First: everything on every push, which rebuilt the firmware far more often than anyone looked at it.) |
 | Q152 | **CI signs.** The signing key is the repository secret `OTA_SIGNING_KEY`; a tag push makes a complete, signed release with no manual step (ADR 0008). |
 | Q153 | *Revised by Q188: there is one firmware.* The Debug Build is built in CI with a token of the runner's own, to prove it compiles, and **isn't published**: it would hand everyone its Debug Console token. |
 | Q154 | Pull requests from forks don't start a run. |
 | Q155 | A release carries `roro9stack-<version>.ota` (signed), `-factory.bin` for USB, `.elf.gz` to decode crashes, and `SHA256SUMS`. |
 | Q156 | Its text is the tag's message, what the files are, and the commits since the tag before. |
 | Q157 | No cache service to begin with: measure first. |
 | Q158 | Reproducible builds aren't needed for signing any more (Q152); not pursued here. |
 | Q159 | **The tags from before CI get their releases too**, v0.1.0 to v0.10.0, built from each tag's own sources by running the workflow by hand. |
 | Q160 | Actions is switched on for the repository. |
 | Q161 | **Changes reach `main` through pull requests, merged as "rebase, then a merge commit"**, the only style the repository allows: the branch's commits keep their messages, the merge commit marks the pull request, and what CI tested is what lands. No squash, no fast-forward. |
 ### As built
 - **One workflow, `.gitea/workflows/ci.yml`, one job**, on the runner `runner0` (label `ubuntu`). The job asks for a `python:3.12-slim` container, installs git, a compiler, openssl and PlatformIO, and runs the same scripts as a developer's machine. No Docker inside the job.
 - **The cache is a Docker volume**, `roro9stack-pio`, mounted at `/pio`; the runner's `config.yaml` allows it under `container.valid_volumes`. A first run downloads about 1 GB and rebuilds the framework. Measured from the jobs' own start and end times: the first full run on an empty cache took 11.4 minutes (tests and both builds); the first run in a container, 8.1; a pull request now takes about 8.7 (tests, coverage and both builds), a release build alone 5.5, and a push to `main` (tests and coverage) 1.1. (An earlier version of this note said 17 minutes: that was the waiting time, not the job's.)
 - **No JavaScript actions**, so the image needs no Node and nothing is fetched from GitHub: the checkout is four git commands.
 - **`scripts/_docker.sh`** runs the command in place when `RORO_NO_DOCKER` is set (a CI job is already in a build container), and in the project's image otherwise. The Debug Build's token is made on the spot in CI and goes with the container.
 - **`scripts/release_build.sh <checkout> <out>`** builds a tag's own sources with today's tools, signs, verifies against the public key in those sources, and writes the files and the release's text. **`scripts/release_publish.py`** creates the Gitea release or completes it; run twice, it replaces what's there. Both run the same on a developer's machine.
 - **`scripts/ota_verify.py`** checks an Update File as a device does, on a PC.
 - **The job's own token** (`secrets.GITEA_TOKEN`) is enough to create a release and upload its files.
 - **Old tags.** v0.1.0 to v0.3.0 are from before the framework was rebuilt with our settings (ADR 0006) and can't link against a rebuilt one left in the cache: the release build puts the stock framework libraries back for them. v0.1.0 to v0.2.1 have no public key in their sources (Firmware Updates came with v0.3.0); their files are checked against today's.
 ### How it went
 - **The runner's label took three tries.** Registered as `ubuntu://docker:ubuntu:resolute` and then as `ubuntu::docker://...`, Gitea took the whole string for the label's name; with the first, jobs ran on the runner's host itself. The first version of the workflow was written for that (plain shell, `docker run` for the build) and published v0.10.0 that way. `ubuntu:docker://docker.gitea.com/runner-images:ubuntu-latest` is the form that works.
 - **Gitea 1.27's API can't cancel a run that isn't finished**, only delete a finished one; switching Actions off and on for the repository doesn't either. Runs queued for a label that no longer exists stay queued until cancelled in the web UI.
 - **CI's image isn't byte-identical to a local build of the same tag** (same size, different bytes). Not pursued (Q158).
 ## Updates from Gitea (issue #6)
 The device looks at the project's Gitea for a newer release, says so, and installs it on request, with the same signed Update Files, Probation and rollback as a push from the PC or an install from the card.
 ### What the server gives (checked 2026-10-06)
 - **Its certificate** is Let's Encrypt, all ECDSA: leaf `git.twis.la` (renewed every few months, next expiry 2026-12-14) under the intermediate YE2, Root YE and ISRG Root X2, which X1 cross-signs. Pinning the leaf would ask a question at every renewal.
 - **The API** answers over HTTP/1.1, chunked: `releases/latest` is 3.2 KB (about 350 bytes of it matter), a list of ten releases is 33 KB.
 - **A download** is a direct 200 with `Content-Length` and no redirect; ranges work.
 ### Decisions (design round 2026-10-06)
 | # | Decision |
 |---|---|
 | Q162 | **Trust:** the firmware carries ISRG Root X1 and X2 and checks the server's chain and name against them, not the framework's bundle of about 130 CAs (ADR 0009). Shared with #4. If the server moves to another CA, the next firmware comes from the PC. |
 | Q163 | The Update File's own signature stays the real guard. A hijacked connection could hide a release or offer an older signed one, never install firmware that isn't ours. |
 | Q164 | The source, `git.twis.la` and `twisla/roro9stack`, is a constant in the firmware. A fork changes it, and has its own key. |
 | Q165 | **When:** on request in Settings > Firmware, and once a day in the background while Wi-Fi is up and the Clock is set (certificate dates need it). A setting, **Check for updates**, on by default. It installs nothing by itself; it skips quietly below the memory floor and never runs during an install. |
 | Q166 | A Toast, "Update v0.11.0 available: see Settings > Firmware", once per version per boot. |
 | Q167 | **The download goes straight into the inactive slot,** no card needed. A truncated or tampered file is refused after 160 bytes or at its end, and the running firmware is untouched. A failed download starts over. |
 | Q168 | A version that failed (rolled back) isn't announced again by the background check until a newer one exists; it can still be installed by hand. |
 | Q169 | **Older releases:** a list of the last ten, newest first, the running one marked. Installing an older one asks with a stronger warning. |
 | Q170 | Enter on a release shows its version, date, size and the tag message, with Install. |
 | Q171 | *Revised by Q188: there is no Debug Build, every firmware installs releases.* **Debug Builds** check and show the latest release, but don't install it: it would replace the Debug Build and its console (Q153: Debug Builds aren't published). Their updates come from the PC. |
 | Q172 | **Memory, as measured:** a TLS connection peaks at about 52 KB of heap, with or without checking the certificate, so it starts with 80 KB free (Q86's 20 KB spare on top), not 55 KB. **A check, list or install someone asked for makes IRC step aside** and come back after; the daily check never does, and with IRC connected it waits. (First: 55 KB and nothing else. With IRC connected a check left 3 KB and a download 836 bytes.) |
 | Q173 | Left out, each with its issue: installing automatically (#52), a release channel (#53), resuming a download (#54). |
 | Q174 | Ships as **v0.11.0**. Tested on the device with the real signed releases; a Debug Build command pretends the device runs an older version, so v0.10.0 counts as an update. |
 ### Done when
 - A check, by hand or daily, tells the right thing: up to date, newer available, no network, bad certificate, no clock, too little memory.
 - A newer release installs from the Firmware page with no card and no PC, and the device restarts into it and confirms it.
 - A tampered or truncated download is refused and the running firmware keeps running.
 - The Older releases list shows ten, and installing one asks first.
 - A release that rolled back isn't announced again.
 - A Debug Build shows the latest release and doesn't install it.
 - The daily check never runs below the memory floor, during an install, or without a clock.
 ### Work breakdown
 1. **Model** (host-tested): a streaming JSON scanner, the release list read from it, HTTP response heads and chunked bodies, URLs, which release counts as an update.
 2. **The connection:** the root certificates, an HTTPS client, a check and a list from the Update Service's task; console commands to try them.
 3. **The download:** an HTTPS source for the existing install path.
 4. **The screens:** the Firmware page's release rows, the release page, Older releases, the setting, the daily check and its Toast.
 5. **Checks on the device**, recorded here.
 ### As built
 - **`lib/release`** (host-tested): a streaming JSON scanner, the release reader built on it, HTTP heads and chunked bodies, URLs, and the decisions (which release is an update, whether to announce it, which download URLs are taken). A list of ten releases is 33 KB of JSON and costs a few hundred bytes of memory, because nothing is kept but the path.
 - **`HttpsGet`** (`src/platform`): one GET, the answer read as a stream, redirects not followed. **`GiteaReleases`** keeps the latest and the list. **The Update Service** serves the requests on its own task (about 5.4 KB of its 7 KB stack at the peak) and installs through the install path that already existed, with an HTTPS source in place of the card or the TCP port.
 - **The daily check** is scheduled from the Update Service's tick: Wi-Fi up, the Clock set, no Probation, nothing else going on, memory for a connection. The day it last succeeded is kept in flash.
 - **A version that failed** (rolled back) is remembered as `ota_failed`, and isn't announced again by the daily check.
 - **The screens:** the Firmware page's Latest release and Older releases rows, a release page with the tag's message, and the install dialog.
 - **Debug Builds** get knobs to try what can't be tried otherwise: `update pretend`, `probe`, `damage` and `daily`.
 - **The first message,** `... available: see Settings > Firmware`, was cut at 48 bytes by the notification's own limit; it now reads `v0.11.0 is out: see Settings > Firmware`.
 ### Checks on the device (2026-10-06, Debug Builds of branch `gitea-updates`)
 | Check | Result |
 |---|---|
 | Host tests | 456 pass |
 | Check and list against the live server | The certificate is accepted against the two embedded roots; `releases/latest` read; a list of ten (33 KB) streamed |
 | Servers that must be refused | github.com, example.com, expired.badssl.com, self-signed.badssl.com, wrong.host.badssl.com, untrusted-root.badssl.com and the router: each "isn't accepted" or a TLS error |
 | A download cut short at 800,000 bytes | Refused, "update file too short"; the running firmware untouched |
 | One byte flipped in the signature | Refused after 160 bytes, "bad signature"; the image isn't read further |
 | One byte flipped in the image | Downloaded in full, refused at its end, "image corrupted (hash mismatch)" |
 | The real v0.10.0, from the console and then from the screen | Downloaded, restarted, confirmed on Probation: the slot table read `v0.10.0, valid` both times. The Debug Build was pushed back from the PC after each |
 | The screens | Latest release (checking, then `(current)` or `(new)`), the release page with the tag's message, Older releases with ten rows, the install dialog (Cancel by default, Back cancels), the progress screen at 28% |
 | IRC connected, before the hold | A check left 3 KB of heap; a full download, 836 bytes |
 | IRC connected, with the hold | The lowest free heap during a full download: 38 KB. IRC reconnected afterwards (its counters kept growing) |
 | The daily check | It ran by itself, announced `v0.10.0 is out: see Settings > Firmware` once; with IRC connected (68 KB free) it didn't run |
 | Speed | 1.9 MB in about 46 s, 40 KB/s, over the guest Wi-Fi at -65 dBm; not investigated further |
 **Not checked:** the certificate's **name** on its own. Connecting by IP makes the server end the handshake before it shows its certificate, so that test proved nothing; the library sets the name it verifies, and OpenSSL on the PC refused the wrong name against the same chain. A failed daily check retrying, the clock not being set, the release that failed before not being announced (host-tested, not on the device), and the hold when IRC isn't connected but Gemini holds memory.
 **Limits worth knowing:**
 - **With IRC connected for days, the daily check doesn't run.** It would have to take IRC down to make room. Opening Latest release does.
 - **A server that changes CA can't be reached** until a firmware carrying the new root comes from the PC (ADR 0009).
 - **No resuming:** a broken download starts over (#54).
 - **A key press during the hold:** Back on the Firmware page while a check is going doesn't cancel it.
 **Two slips during the checks:** a blind sequence of keys on the Firmware page opened the SD card's install dialog (the page keeps its selection between visits); it was cancelled with Back, nothing installed. And my port-polling while waiting for a restart took the Debug Console's only client slot, which made the first install attempt look like a failure.
 ## One firmware: the Debug Console in every build (issue #68)
 The issue asked for a token that could be set, so that Debug Builds could be published. The design round ended somewhere simpler: no Debug Builds. The console is in every firmware, off until switched on, with a token that belongs to the device (ADR 0010, which supersedes part of ADR 0004).
 ### Decisions (design round 2026-10-06)
 | # | Decision |
 |---|---|
 | Q188 | **One firmware,** with the Debug Console and the test commands compiled in. The `cardputer-adv-debug` environment, `RORO_DEBUG`, the `+debug` version and `scripts/debug_flags.py` go; CI builds one firmware. Revises Q153 and Q171. |
 | Q189 | **Off by default,** and off when the stored setting is missing or invalid. Off, nothing listens and no memory is used: the task and the 4 KB ring exist only while it's on. |
 | Q190 | **Settings → Debug Console:** the switch, where to connect, the token, "New token", "Type a token". It stays on across restarts and in Safe Mode. **`DBG` in the Status Bar** while it listens, bright with a client connected. |
 | Q191 | **The device makes the token** the first time the console is switched on: 100 bits as 20 characters of Crockford's base32, shown in groups of four. It can be replaced by one typed by hand, of at least 16 characters. Case and dashes don't count. |
 | Q192 | **USB serial can set it up:** `debug on`, `debug token <value>`, `debug token new`, over USB only; `debug status` and `debug off` from anywhere. `scripts/flash.sh --debug` gives a device the developer's token. The token is never printed. |
 | Q193 | **Challenge and answer:** the device sends 16 random bytes, the client their HMAC-SHA256 keyed by the token. Five wrong answers in a row close the console for a minute, with a Notification. **Old clients and old firmwares don't talk to each other:** accepted, this far from v1 and with one user. |
 | Q194 | `rdbg.py` takes the token from **`-t`/`--token`**, then **`$RORO_DEBUG_TOKEN`**, then `~/.config/roro9stack/debug-token`. |
 | Q195 | **The test commands are in every build** (`crash abort`, `crash wdt`, `update pretend`, `update damage`, `lora inject`, `sd fill`, `loop spin`, `wifi ip … try`). `update install … force` goes: there's nothing left to protect. |
 ### As built
 - **`lib/debug`** (host-tested, 9 tests): the token maker, tidying what a person types, HMAC-SHA256 on the project's own SHA-256 (checked against RFC 4231), the answer to a challenge (the same vector as `rdbg.py`'s), a comparison that takes the same time whatever it's given, and the pause after five wrong answers, right across the clock's wrap.
 - **Two settings,** `DebugConsole` and `DebugToken`, with the others: validated, and invalid stored values count as missing.
 - **The console's task and ring come and go with the setting.** `Console::openRing` allocates the ring; switching off closes the socket, frees it and ends the task. `tick` follows the settings once a second, so a switch off and on again takes a second or two.
 - **Measured against the two builds it replaces:** 1,881,799 bytes of flash and 54,700 of static RAM. The release build was 1,851,387 and 54,612 (so 30 KB more flash and 88 bytes more RAM); the Debug Build was 1,874,887 and 58,780 (4 KB of RAM back: the ring is no longer a static array).
 - **The listener is asked whether it listens.** The framework's `begin()` returns nothing and fails without a word; the task now checks, says so on the console, and tries again every two seconds.
 - **`debug off <seconds>`** closes the console and brings it back by itself: the only way to try its closing and reopening from afar, since switching it on is for the device and the cable only.
 - **`scripts/rdbg.py`** answers the challenge, and fetches a release's ELF from Gitea when a crash names a version that isn't in `.pio/elves/`.
 ### Checks
 | Check | Result |
 |---|---|
 | Host tests | 468 pass (456 before) |
 | The firmware builds | One environment, 1,881,799 bytes of flash used |
 | Pushed over Wi-Fi to a device running a Debug Build | Installed, restarted; the update port answers and **port 2323 refuses connections**: off by default |
 | Switched on at the device (Settings → Debug Console) | A token is made and shown. Its first drawing, in bold at normal size, was misread once: it is now at twice the size, in two lines, and `O`, `I` and `L` are taken for `0` and `1` |
 | A login with `scripts/rdbg.py` | The challenge is answered; `info`, `screenshot` and the backlog work |
 | `DBG` in the Status Bar | There while the console is on, bright while a client is connected (screenshots) |
 | `debug on` and `debug token` over the console | Refused: `over USB serial only` |
 | Six logins with a wrong token | Five are refused, a second apart; the sixth, and the right token after it, get `locked`. After a minute the right token works again. The console's own log and a Notification say so |
 | Three `crash abort` in a row | **Safe Mode**, with the console reachable: `info` works, `ls /` says `not available in Safe Mode`. `rdbg.py crash` decodes the backtrace to `runCommand` at the `abort()` line. `reboot` leaves Safe Mode |
 | An update over Wi-Fi with the console on | The setting and the token survive: the console is back by itself after the restart |
 | `debug off` over the console | The client is dropped and port 2323 refuses connections; the update port still answers |
 | `debug off 2`, 10 times in a row, then 15 | It came back each time, a second after the pause. Free heap dips by about 270 bytes for each connection the device closes and **is all back two minutes later** (107.2 KB before, 103.2 right after 15, 107.0 at two minutes): TCP holds a closed connection that long. Not a leak, though it looked like one for an hour |
 | Memory, console on with a client | 108 KB free (the Debug Build it replaces: 104 KB). In Safe Mode: 178 KB free |
 **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.
@@ -0,0 +1,204 @@
 # S1 — System basics
 **Status:** the three planned items are done: the SD driver fix in v0.6.1 (issue #21, ADR 0007), fixed IPv4 settings in v0.7.0 (issue #7), the System App in v0.8.0 (issue #11). v0.8.1 adds the resting main loop (issue #40) and the GNSS pause for the radio's noise (issue #20, still open for the 11 dB that remain). Still open in the milestone: #39, following the SD driver upstream.
 **Goal:** the device works on any network, the card can be trusted, and you can see what the system is doing. A side milestone, like G1.
 ## Fixed IPv4, DNS and NTP (issue #7)
 Not every network has a DHCP server: a lab bench, a direct link to a router, a network where addresses are handed out by hand. Until now every Saved Network used DHCP, DNS always came from DHCP, and the NTP server was `pool.ntp.org`, hard-coded.
 **IPv4 only.** IPv6 isn't part of this, now or as a planned follow-up.
 ### Decisions (design round 2026-10-05)
 | # | Decision |
 |---|---|
 | Q105 | The IP setting is **per Saved Network**: *Automatic* (DHCP, as before) or *Fixed*, with its own address, prefix and gateway. New networks start Automatic. |
 | Q106 | The subnet is entered as a **prefix length** (`24`), with the mask shown next to it. |
 | Q107 | The **gateway is optional**: left empty, the device talks to its own subnet only. |
 | Q108 | **DNS is global:** two servers in Settings, used on every Fixed network. On Automatic networks DHCP's DNS is used, unless **"Always use my DNS"** is on. |
 | Q109 | DNS defaults: **9.9.9.9** (Quad9), then **1.1.1.1** (Cloudflare). |
 | Q110 | **NTP is global:** two servers in Settings, names or addresses, defaulting to `pool.ntp.org` and `time.cloudflare.com`. NTP servers offered by DHCP are used first. GNSS still outranks NTP for the clock. |
 | Q111 | What's typed is checked, host-tested in `lib/wifi`: an address is four numbers from 0 to 255; a prefix is 1 to 30; the address isn't the subnet's network or broadcast address; the gateway is inside the subnet and isn't the device's own address. Refusals say why. |
 | Q112 | Addresses are typed in the line editor, limited to digits and dots. |
 | Q113 | Enter on a Saved Network opens **its page** (IP, Address, Prefix, Gateway, Forget) instead of asking to forget it. Settings > Wi-Fi gains DNS servers, "Always use my DNS" and NTP servers. The Status row opens **connection details**: address, mask, gateway, DNS and NTP in use, and where each came from. |
 | Q114 | A change applies **at once**: the network in use reconnects with the new settings. No automatic way back; the keyboard still works if Wi-Fi is cut. |
 | Q115 | Console: `wifi status` shows address, gateway, DNS, NTP and their sources; `wifi ip <ssid> dhcp`, `wifi ip <ssid> <address>/<prefix> [gateway]`, `wifi dns <a> [b]`, `wifi ntp <a> [b]`. Debug Builds: `wifi ip … try 60` goes back to the previous setting after 60 s unless confirmed with `wifi ip keep`. |
 | Q116 | Left out: checking whether the address is already taken, and per-network DNS. |
 The SDK already allows 3 NTP servers and 3 DNS servers and can take NTP servers from DHCP (`CONFIG_LWIP_SNTP_MAX_SERVERS=3`, `CONFIG_LWIP_DHCP_GET_NTP_SRV=y`), so the framework isn't rebuilt for this.
 ### Done when
 - A Saved Network set to Fixed joins with that address, mask and gateway, and the device reaches the internet (IRC, Gemini, NTP) through the DNS servers from Settings.
 - Set back to Automatic, it gets its address from DHCP again.
 - With "Always use my DNS" on, an Automatic network resolves through the servers from Settings.
 - The NTP servers from Settings set the clock.
 - Wrong entries are refused with a reason, in Settings and on the console.
 - Connection details show what's in use and where it came from.
 - Tested on `knbg-guests` with 10.39.39.12 (the device's DHCP lease) and 10.39.39.13 (free: the device is alone on that network).
 ### Measured (2026-10-05 and 06, on `knbg-guests`)
 The network is 10.39.39.0/24, gateway 10.39.39.1; DHCP gives 10.39.39.1 as DNS and offers no NTP server.
 - **Fixed 10.39.39.12/24** (the device's own lease) and **Fixed 10.39.39.13/24**, gateway 10.39.39.1: the device joins with that address, DNS is 9.9.9.9 and 1.1.1.1 from Settings, and a Gemini page loads (name resolution, routing, TLS). On .13, .12 no longer answers.
 - **A wrong gateway** (10.39.39.254) on a 60 s trial: the device stops answering from another subnet, and comes back by itself with the previous setting.
 - **Back to Automatic:** 10.39.39.12 by DHCP again, DNS 10.39.39.1 from DHCP.
 - **"Always use my DNS"** on an Automatic network: DNS becomes 9.9.9.9 and 1.1.1.1; switched off, the device joins again and has DHCP's DNS back.
 - **NTP:** `pool.ntp.org` answers; set to `time.cloudflare.com` alone, that one answers within 25 s.
 - **Refusals**, on the console and in Settings: the network's own address, a gateway outside the subnet, a prefix of 31 or 99, 10.39.39.300, an unknown network, a DNS name where an address is needed, a host name with an underscore.
 - **In Settings:** the network's page pre-fills Fixed with the address, prefix and gateway in use; leaving the page applies it; connection details show each value and where it came from.
 - **Not tested:** NTP servers offered by DHCP (this network offers none), and a Fixed network with no gateway.
 ### Work breakdown
 1. **IPv4 logic** (host-tested): parsing and formatting addresses, prefix and mask, the checks of Q111.
 2. **Storage:** the IP setting in each Saved Network; DNS, "Always use my DNS" and NTP in Settings.
 3. **Wi-Fi Service:** apply it when joining; DNS and NTP; `wifi status` and the console commands.
 4. **Settings:** the network page, the DNS and NTP rows, connection details.
 5. **Tests on the device**, recorded here.
 ## System Monitor (issue #11)
 Every milestone so far was driven by measurements, heap floors, stack sizes, TLS dips, that needed a Debug Build and a computer. The System App shows them on the device, in any build.
 ### Decisions (design round 2026-10-06)
 | # | Decision |
 |---|---|
 | Q117 | An App of its own, **System**, in release builds too. Read-only. |
 | Q118 | Four views, switched with Tab: **Overview** (CPU per core, memory, network, battery), **Tasks**, **Memory**, **System**. |
 | Q119 | Sampled once a second. A task's share is its run time over the last second; a core's load is 100 % minus its idle task's share. |
 | Q120 | **History only while the App is open:** two minutes at one sample a second, about 1 KB. The system already keeps what matters afterwards: the lowest free heap since boot and each task's lowest free stack. |
 | Q121 | **Bytes are counted per service:** IRC, Gemini, the Debug Console and Firmware Updates add what they read and write to a shared counter. The network view shows the connection details, each service's bytes in and out, and the signal strength. |
 | Q122 | Tasks: name, core, share, state and lowest free stack, sorted by share; `s` cycles the sort (share, stack, name). **Under 512 bytes of stack left shows in the warning colour.** |
 | Q123 | Memory: free heap, lowest since boot, largest free block, and a two-minute graph of free heap **with the floors of Q86 drawn as lines** (55, 40 and 20 KB). |
 | Q124 | System: uptime and why it last started, firmware and both app slots, chip temperature and CPU frequency, battery voltage and percentage, SD usage and write faults, the radio's and the GNSS receiver's state. |
 | Q125 | `info` and `tasks` are split into a **snapshot** that the console and the App share; the arithmetic (shares from two samples, sorting, the stack warning) is host-tested. |
 | Q126 | Left out: acting on tasks, an event log, exporting snapshots to the card. |
 | Q127 | The main loop uses about 81 % of a core. The App shows it; fixing it is issue #40, not part of #11. |
 The App has five views, not four: Q121's network view is one of its own (Overview, Tasks, Memory, Network, System).
 ### Measured (2026-10-06)
 - **Traffic counters are exact.** A Gemini fetch of a 164,970-byte page counts 164,986 bytes in (the page and its 16-byte header line) and 42 out (the 40-character URL and CRLF). A 1,797,760-byte upload counts 1,798,123 in for the Debug Console, commands included.
 - **The Memory view shows a TLS dip as it happens.** Starting IRC and a 165 KB Gemini fetch together: free heap falls from about 100 KB through the three floors to a low of 12.1 KB, then settles near 50 KB. That's the dip accepted in G1 (Q86).
 - **A run-time counter only moves when its task is switched out.** FreeRTOS adds to a task's run time at the context switch. The main loop takes the samples, and with core 1 to itself it's never switched out: its counter said 2 % while the core's idle task had 0 %. So the task that samples gets what's left of its core. With that: **the main loop uses 100 % of core 1 at rest** (issue #40 said 81 %, an average since boot).
 - **`tasks` on the console** sampled twice inside one command at first, a quarter second apart, and showed the loop at 1 %: it was asleep in the command's own wait. It now samples, lets the loop run for a second, and prints.
 - **Low stack, flagged:** `IDLE0` (232 bytes left), `IDLE1` (328 to 352) and `spk_task` (256 to 264), all the framework's own tasks.
 - **Cost:** 15.6 KB of flash for the App and the counters (1,742,723 bytes, release). Nothing while it's closed; about 2 KB of history and samples while it's open.
 ## The main loop rests (issue #40)
 The loop polled the keyboard, ticked the Services, ran the consoles and redrew when needed, then came straight back: 50,000 passes a second, and core 1 100 % busy with the device idle and the screen off.
 Nothing needs that. The keyboard controller buffers key events; the consoles and the radio have their own tasks or interrupts; no Service asks for a tick more often than every 50 ms. So after each pass the loop now rests: **5 ms with the screen on, 20 ms with it off**, and not at all during a serial file transfer (`sd put`), which reads its bytes from the loop. Safe Mode's loop rests 5 ms too. Debug Builds have `loop spin on|off` to bring the old behaviour back for comparison.
 ### Measured (2026-10-06, Debug Build, Wi-Fi connected, GNSS on, on USB power)
 | | Spinning | Resting |
 |---|---|---|
 | Passes a second, screen off | 50,160 | 50 |
 | Core 1 load, screen off | 100 % | 1 % |
 | Passes a second, screen on (Launcher) | 1,203 | 167 |
 | Core 1 load, screen on | 62 % | 10 % |
 | Chip temperature at rest, settled | 38.3 C | 34.3 C |
 | A 1.8 MB upload over the Debug Console | about 230 KB/s | 288 KB/s |
 - Still working at this pace: GNSS (a 3D Fix, 22 satellites), a Gemini fetch (52 KB), the upload read back by SHA-256, the Sweep (still 606 to 610 ms a pass), the radio's DIO1 interrupt.
 - **Not measured:** the current drawn (no meter on the battery line), and how typing feels on the real keyboard: a key now waits up to 5 ms for the loop, 20 ms if it's the one that wakes the screen.
 - **The radio's noise floor didn't move** (-97 to -99 dBm at 125 kHz either way): the spinning loop wasn't the source (issue #20).
 - **Not done:** real sleep. The framework is built without power management (`CONFIG_PM_ENABLE` is off), so an idle core only halts until the next interrupt. Automatic light sleep would need the framework rebuilt with it, Wi-Fi in modem sleep, and the USB serial port's behaviour checked. A next step if battery life calls for it.
 ## The radio's noise: the GNSS receiver (issue #20)
 M3 found the LoRa radio's noise floor about 15 dB above what the chip hears alone, and that the source travels with the device. Which part? Debug Builds got a self-test, `lora noise test`: it changes one thing at a time, Sweeps the band eight passes (568 readings), records the median as the floor, and puts the thing back. It runs on the device by itself, because one condition switches Wi-Fi off, and `lora noise report` prints the result afterwards.
 ### Measured (2026-10-06, indoors, on USB power, dBm at 125 kHz)
 | Condition | Floor |
 |---|---|
 | Antenna switched off (the chip alone) | -117 |
 | Antenna on, GNSS in standby | -106 |
 | Antenna on, GNSS running (as shipped) | -98 |
 - **The GNSS receiver, while it runs, raises the floor by 8 dB.** Three runs: -98 or -99 with it running, -106 in standby, every time. On LongFast (250 kHz) the Sniffer's own reading goes from about -93.5 to -101.5 dBm.
 - **It's the receiver working, not its serial line:** with one NMEA sentence a second instead of twenty (`PCAS03`), the receiver still tracking, the floor stays at -98.
 - **Nothing else moves it by more than 1 dB**, with GNSS running or in standby: the main loop spinning or resting, the CPU at 240, 160 or 80 MHz, Wi-Fi on or off, the screen on or off, the radio chip's regulator as DC-DC or LDO, its receive gain boosted or not.
 - **11 dB remain** between the antenna connected with GNSS quiet (-106) and the chip alone (-117). It comes in through the antenna and none of those switches changes it: the surroundings, or parts of the Cardputer that can't be switched off. Not separated: that needs another place, or the antenna on a cable away from the case.
 - M3's quick check had GNSS at "1 or 2 dB": it read one frequency for a few seconds, in a noisier spot. The median over the band is the better measure.
 ### What the firmware does about it
 **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.
@@ -0,0 +1,61 @@
 # 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.
 ## The screenshot key (issue #83)
 A screenshot could only be taken by typing `screenshot` in the Shell, where "now" is a picture of the Shell.
 - **Fn+p, on every screen**, text fields included, saves the screen as it is (a dialog, the help panel or a Toast if one is showing) as a PNG in `/screenshots`, the way the Shell's command does. A Toast says so once the file is written, so it is never in the picture.
 - **It never reaches an App.** `Key::Screenshot` comes out of the key mapper and is handled before the App manager, so the help panel stays open and a dialog keeps its selection.
 - **Not on Settings > Debug Console:** that page shows the token, and a picture of it is a copy of the token in a file. `App::showsSecret()` says so, and the key answers with a Toast instead.
 - **No card:** a Toast says so.
 - No setting to switch it off: Fn with a letter isn't pressed by accident.
 - It is in the "Everywhere" group of the help panel, and so in the website's key tables. `key shot` presses it over the consoles.
 **Checked on the device** (2026-10-07, with `key shot`): in the Launcher, a 33,383-byte PNG appears in `/screenshots` and is the Launcher; with the help panel open, the picture is of the panel (which now lists Fn p) and the panel stays open; on Settings > Debug Console, no file is written; back on the Settings list, one is. The test pictures were removed.
 **Not checked:** the real Fn+p on the keyboard (the mapper is host-tested); the two Toasts that refuse, which weren't looked at (one of them is on the page that mustn't be photographed); a device with no card.
@@ -0,0 +1,184 @@
 # W1: Website
 **Status:** phases 1 to 3 (home, Install and Downloads; the user guide; how-tos and the FAQ) and the devlog are live at roro9stack.net; phase 4 (the developer docs) is in a pull request. Issue #12.
 **Goal:** a public home for the project at **roro9stack.net**, separate from the blog (stories) and from Gitea (developers): what it is, how to install it, how to use each App, and the docs.
 The home page was designed on a canvas in a Claude chat (a dark and a light theme, built on the device's own 256-colour palette, pixel-notched corners, DM Mono and Hanken Grotesk). It is the starting point, not the final copy: it has to say only what the firmware does today.
 ## What was found while planning (2026-10-06)
 - `roro9stack.net` already points at the server that hosts Gitea. Plain HTTP redirects to HTTPS; HTTPS has no certificate yet, which is the server's side to set up.
 - **Release downloads from Gitea carry no CORS header,** so a browser can't fetch the factory image from another origin as things are. Gitea is behind Caddy, which can add the header (below).
 - Zola can read JSON from a URL at build time (`load_data`), so the home page's "latest version" can come from the Gitea API.
 - There is no Gitea wiki: the design's "Wiki" links would 404.
 - The blog is published by pulling its repository on the web server and running `zola build`. The site does the same.
 ## Decisions (design round 2026-10-06)
 | # | Decision |
 |---|---|
 | 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. *(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. |
 | Q182 | English only. |
 | Q183 | The FAQ starts from real questions: the README, and issues labelled `kind/docs`. |
 | Q184 | Fonts are **self-hosted** (no request to a third party). The hero keeps the design's illustrations, labelled as illustrations, and a section of **real device screenshots** is added. |
 | Q185 | **The site says only what the firmware does today.** Planned features are marked as planned, with their milestone. The mesh messenger is **planned**: the LoRa Scanner listens, nothing is sent. |
 | Q186 | Left out, each with its issue: a Gemini capsule mirror (#57), French (#58), docs per version (#59), search (#60). |
 | Q187 | The site has no version of its own. Contact is **contact@roro9stack.net,** and the issue tracker. |
 ## The design, reviewed
 Kept as designed: the layout, the tokens, the nine App cards (their facts check out against the code: Probation 3 minutes, Safe Mode after 3 crashes, 60 seconds of typing before an update restarts the device).
 Changed before it ships:
 - **Install, not Download, is the first action.** Downloads are for developers; a visitor wants to try it.
 - **A "what you need" strip:** Cardputer ADV, the Cap LoRa-1262 (only the radio needs it), a microSD card, Wi-Fi. And a plain status line: the version, and what isn't there yet.
 - **The mesh card and the hero** no longer promise sending and reading mesh messages.
 - **The latest version is read from the API,** not typed.
 - **"Wiki" is replaced by Docs.** The updates section gains what v0.11.0 added: the device installs releases from the project's server itself.
 - **An independence line:** not affiliated with or endorsed by M5Stack or Meshtastic.
 - **No cookies, no analytics, no third-party requests,** said on the page (fonts self-hosted).
 - **The keyboard focus ring** is invisible on the notched buttons: `clip-path` clips an outline. Another way to show focus is needed.
 - **The wordmark SVGs** carry an embedded C2PA content-credentials block: stripped from the site's copies.
 ## Done when (phase 1)
 - Pushing a change under `site/` runs the `site` job and not the firmware tests; a firmware change runs the firmware jobs and not the site's.
 - The home page renders in both themes, at phone width, with the keyboard, and says nothing the firmware doesn't do.
 - The latest version on the page is the latest release.
 - The browser flasher installs the latest release on a Cardputer ADV from Chrome (tried by hand), the page shows the file's SHA-256, and the `esptool` steps are on the same page.
 - A release published after the site was built is the one the Install page offers.
 - The home and Downloads pages make no request to another origin, and the Install page only asks git.twis.la.
 ## Work breakdown
 1. **CI split:** a `site` workflow, path filters on the firmware workflow.
 2. **The skeleton:** `site/` with the tokens, fonts, base template and the theme switch.
 3. **The home page,** from the design, with the changes above.
 4. **Install and downloads:** the flasher with its manifest built in the page, the `esptool` steps, the changelog. Needs the Caddy headers on the Gitea host (the maintainer's side); the page is tested against them once they're in.
 5. **Checks,** recorded here.
 ## As built (phase 1)
 - **CI is split.** `ci.yml` (the firmware) has `paths-ignore: site/**, docs/**, README.md, CONTEXT.md` on pushes to `main` and on pull requests. `site.yml` runs `zola check` and `zola build` with a Zola pinned by its checksum, then `site/tools/check_site.py`, when those files change. Gitea's own source (v1.24, read, not run against the 1.27 server) shows that path filters count as matched for tag pushes, so a tag still releases. A change that touches both runs both.
 - **The build output** goes to `public/` at the root of the repository, not into `site/`: `output_dir = "../public"` in `site/config.toml`, so `zola build` in `site/` and `zola --root site build` from the root agree, and git ignores `/public/`.
 - **The site** is in `site/`: `config.toml`, templates (base, home, install, downloads, 404), `data/` for the App cards and the screenshots' captions, `static/` (stylesheet, theme switch, fonts, wordmark, icons, real screenshots, the vendored flasher). `site/README.md` says how to build it and what the server needs.
 - **The home page** follows the design. Changed from it: the hero and the mesh card promise nothing that isn't built (the mesh messenger is a "planned" card), an Install button first, a status box, a "what you need" row, a section of real screenshots, the updates section says the device installs releases itself, an independence line and a statement about cookies and third-party requests in the footer, the latest version read from the Gitea API at build time, and the nav's Wiki replaced. The two hero drawings are generated by `site/tools/make_illustrations.py` (a port of the design's scripted shapes) as inline SVG.
 - **The focus ring.** `clip-path` clips outlines, so a focused notched control drops its notches and shows square corners and its ring.
 - **The Install page** asks the API for the latest release in the browser, builds the ESP Web Tools manifest as a blob, shows the version, size and SHA-256, and only ever hands the flasher a download from the project's own server for this repository. The flasher library (ESP Web Tools 10.4.0, Apache-2.0) is vendored, trimmed to the ESP32-S3. Fonts (DM Mono, Hanken Grotesk, SIL OFL) are self-hosted.
 - **The Downloads page** lists the last 30 releases with their files, read at build time.
 - **The wordmark SVGs** from the design carried an embedded C2PA content-credentials block; it is removed from the site's copies.
 ## As built (phase 2, the user guide)
 - **`/guide/`** is a section of 11 pages, `site/content/guide/`, each with `template` from the section's `page_template` and an order from `weight`: the basics (keys, Launcher, Status Bar, first start, the card), then one page per App (LoRa Scanner, GNSS, Gemini, IRC, Wi-Fi tools, Notes, Storage, System), Settings and Updates. Pages with real screenshots list them in `extra.screens`, looked up in `data/screens.toml`.
 - **Facts come from the README, the milestone documents and the Apps' own source** (key handlers, labels, the Status Bar's drawing code), not from memory. Some wording was corrected against the source while writing: the Track folder is `/gnss/tracks`, the reasons a Track won't start, what the Status Bar shows.
 - **Not covered:** the mesh messenger (planned), the debug console and Debug Builds beyond a pointer to the README. How-tos and the FAQ are phase 3.
 ## As built (the devlog)
 Not one of the planned phases: the blog's seven roro9stack posts, imported into `site/content/devlog/` and shown in the site's own style, with the **Blog** link in the navigation and the footer replaced by **Devlog**. The posts' text, tone and structure are unchanged; what changed:
 - **Links:** the posts' links to each other point to `/devlog/<same name>/`, and one link to an unpublished work-in-progress post became plain text. Each post keeps its old directory name, so the old URL `/<name>/` maps to `/devlog/<name>/`.
 - **The posts' parts** (the sign, the cast, the steps, asides, folded sections, diagrams, captions) are shortcodes in `site/templates/shortcodes/`, restyled in `static/css/devlog.css`: the site's palette, notched boxes, DM Mono and Hanken Grotesk. The two older posts about other subjects (a vinyl remote, a ZFS rescue) stay on the blog.
 - **The 17 diagrams are inline SVG**, and carried `<style>` blocks and `style` attributes that the site's Content-Security-Policy refuses. Their rules moved to `static/css/devlog-diagrams.css` (one block per diagram, plus colour classes for what the attributes did), and a diagram's minimum width is a class, not a style attribute. The Caddy policy needs no change.
 - **The diagrams' four colours** (red, green, yellow, accent) are defined for `.devlog` on the site's RGB332 grid, one value for each theme.
 - **Links between posts:** every post's reference to another ("the last post", "the first post", the milestone lists) is a link to it. `check_site.py` now also checks every link inside the site, and its #fragment: a broken one fails the Site job. External links are checked by `zola check` run by hand (without `--skip-external-links`, which CI uses); its only complaints today are line-range and heading anchors on Gitea, which Gitea resolves in the browser.
 - **An Atom feed** at `/devlog/atom.xml`, linked from every devlog page.
 - **Checked** in Chromium with the production CSP applied to every response: the index and the seven posts, at 1100 and 390 px, no policy violation, no broken image, no sideways scroll; `check_site.py` 24 pages, 0 problems.
 ## Checks (2026-10-06)
 | Check | Result |
 |---|---|
 | The Site workflow's own commands, in a clean container with the pinned Zola | `zola check` clean, build and page checks pass |
 | `tools/check_site.py` | 4 pages, 0 problems: titles, descriptions, a language, every image with alt text, every local file referenced exists, nothing loaded from another origin |
 | Browser tests (Chromium, 16 checks) | All pass: no request to another origin from the home, Downloads and 404 pages; no horizontal scroll at 1280 and 390 px; a visible focus ring on a notched button; the Install page reads the latest release, shows its version, size and SHA-256, builds a blob manifest naming an ESP32-S3 factory image at offset 0, and loads only git.twis.la; a download on another host is refused; the real server (no CORS header today) makes the page fall back to the esptool steps |
 | The pages looked at | Home in dark and light, at desktop and phone width; Install; Downloads |
 | `esptool` against the real v0.11.0 factory image | An ESP32-S3 image, bootloader at 0x0, partition table at 0x8000: flashing at offset 0 is right. The command's syntax was checked, not a flash |
 **Not checked:**
 - **Flashing a real Cardputer from Chrome.** It needs the device on a machine with a browser; the page's flasher logic is tested, the flashing itself isn't.
 - **Caddy's headers** on the real server (not applied yet), and **HTTPS on roro9stack.net** (the name resolves, the certificate isn't there).
 - **The CI split on a change that touches only `site/` or `docs/`.** This pull request touches both the workflows and the site, so it runs both; the first docs-only pull request will show it.
 - Firefox and Safari rendering, screen readers, and a printed page.
 - The unverified wording in the Install text is kept to what's known: nothing about how long flashing takes, or what the screen shows in download mode.
 ## As built (phase 3, how-tos and the FAQ)
 - **`/howto/`** has eight short recipes: when flashing fails, find your files on the SD card, install an update from the card, use a network without DHCP, record a Track, capture LoRa packets for Wireshark, read Gemini pages offline, and what to do when a connection says "not enough memory". **`/faq/`** is one page of questions with a list at the top. Both use the guide's templates (`guide-index.html`, `guide-page.html`, now generic: the page's parent section gives the eyebrow, the title and the pager).
 - **The FAQ starts from the README** and from the problems the project met (Q183): the flash troubles and the memory limit are the two that were hit most. The issues labelled `kind/docs` turned out to be design rounds for the mesh, not user questions, so they gave nothing to answer.
 - **Every step comes from the README, the milestone documents or the Apps' source.** The privacy answer says plainly that the device contacts the project's server once a day for the update check (on by default, one switch to turn it off).
 - **Linked from the guide's index,** not the navigation, which stays short.
 ## As built (phase 4, the developer docs)
 - **`/dev/`** has four sections: **Debug Builds and the Debug Console** (first, and the longest: Debug Builds, the Console and its protocol, files and screenshots, driving the UI, crashes and Safe Mode, and the command reference), **Build, test and release** (the README's build, CI and flash sections, and how an update works, with the update file, the four ways in and Probation drawn), **Decisions** (the ADRs) and **Milestones** (the plans).
 - **Generated from the repository, not copied by hand:** `site/tools/gen_dev_docs.py` writes the ADR pages, the milestone pages, the README's sections, and the command reference, which is read from the firmware's own `help` text in `src/main.cpp` and then the README's table of what each command does. Zola can't read outside its own folder (not even through a symlink), so the generated pages are **committed**, and the Site workflow runs `gen_dev_docs.py --check` and fails when one is out of date; it now also runs when `src/main.cpp` changes, because the command list lives there. The server's `pull; zola build` is unchanged.
 - **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, each time.
 | # | 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.
 ## Search (issue #60)
 A search over the documentation: the user guide, the how-tos, the questions and answers, and the developer docs. Not the devlog.
 - **The index is the search page itself** (`/search/`, `templates/search.html`): one list item for each page and for each `##` heading of it, with that part's text, written by Zola from the pages' own content when the site is built. Nothing is fetched and nothing typed leaves the browser, so the Content-Security-Policy needs nothing new, and the web server still only runs `zola build`.
 - **Without JavaScript** the page is a list of every page and heading of the documentation, each a link.
 - **With it**, `js/search.js` filters and ranks the items as you type: every word has to be in the part; a word in a heading counts for most, the words side by side for more than scattered, and the user guide, the how-tos and the FAQ come before the developer docs, the milestones last. A result links to its heading, with the text around the match.
 - **The content pages get no script for it:** the navigation has a link, and the index pages of the guide, the how-tos and the developer docs have a box that is a plain form to `/search/?q=`.
 - **Size:** about 245 items, about 310 KB of HTML, under 100 KB compressed, loaded only by who searches.
 **Checked** in Chromium with the production Content-Security-Policy on every response, no violation: "probation" (the guide's "Probation and Rollback" first), "safe mode", "rm -r", "how big can a note" (the FAQ's question first), a word that isn't there; typing, following a result to its heading, the box on the guide's index, 390 px wide with no sideways scroll, and JavaScript off. `check_site.py` follows every link of the page, so an index entry can't point at a heading that doesn't exist.
 **Not checked:** other browsers, and a screen reader.
@@ -20,11 +20,11 @@ const RowDef kRows[] = {
    {Row::Region, Kind::Choice, "Region"},      {Row::Timezone, Kind::Choice, "Timezone"},
    {Row::Brightness, Kind::Slider, "Brightness"}, {Row::DimTimeout, Kind::Choice, "Dim after"},
    {Row::OffTimeout, Kind::Choice, "Screen off after"}, {Row::Sound, Kind::Toggle, "Sound & LED"},
-    {Row::Gnss, Kind::Toggle, "GNSS"}, {Row::Coordinates, Kind::Toggle, "Coordinates"},
+    {Row::Gnss, Kind::Toggle, "GNSS"}, {Row::GnssQuiet, Kind::Toggle, "Pause GNSS for LoRa"},
    {Row::Coordinates, Kind::Toggle, "Coordinates"},
    {Row::ProbeMacs, Kind::Toggle, "Probe MACs"}, {Row::Wifi, Kind::Page, "Wi-Fi"},
-    {Row::Storage, Kind::Page, "Storage"},
+    {Row::CheckUpdates, Kind::Toggle, "Check for updates"}, {Row::Firmware, Kind::Page, "Firmware"},
-    {Row::Firmware, Kind::Page, "Firmware"},
+    {Row::DebugConsole, Kind::Page, "Debug Console"}, {Row::About, Kind::Page, "About"},
    {Row::About, Kind::Page, "About"},
 };
 const int kDimSeconds[] = {10, 15, 30, 60, 120, 300};
@@ -81,9 +81,12 @@ std::string SettingsMenu::value(int i) const {
        case Row::OffTimeout: return formatSeconds(settings_.getInt(Setting::OffTimeoutS));
        case Row::Sound: return settings_.getBool(Setting::Sound) ? "On" : "Off";
        case Row::Gnss: return settings_.getBool(Setting::GnssEnabled) ? "On" : "Off";
        case Row::GnssQuiet: return settings_.getBool(Setting::GnssQuietForLora) ? "On" : "Off";
        case Row::CheckUpdates: return settings_.getBool(Setting::CheckUpdates) ? "Daily" : "Off";
        case Row::Coordinates: return settings_.getBool(Setting::CoordinatesDms) ? "Deg min sec" : "Decimal";
        case Row::ProbeMacs: return settings_.getBool(Setting::ProbeMacRaw) ? "Raw" : "Pseudonymised";
        case Row::Wifi: return settings_.getBool(Setting::WifiEnabled) ? "On" : "Off";
        case Row::DebugConsole: return settings_.getBool(Setting::DebugConsole) ? "On" : "Off";
        default: return "";
    }
 }
@@ -126,6 +129,8 @@ std::string SettingsMenu::choose(int i, int c) {
 void SettingsMenu::toggle(int i) {
    if (row(i) == Row::Sound) settings_.setBool(Setting::Sound, !settings_.getBool(Setting::Sound));
    if (row(i) == Row::Gnss) settings_.setBool(Setting::GnssEnabled, !settings_.getBool(Setting::GnssEnabled));
    if (row(i) == Row::GnssQuiet) settings_.setBool(Setting::GnssQuietForLora, !settings_.getBool(Setting::GnssQuietForLora));
    if (row(i) == Row::CheckUpdates) settings_.setBool(Setting::CheckUpdates, !settings_.getBool(Setting::CheckUpdates));
    if (row(i) == Row::Coordinates) settings_.setBool(Setting::CoordinatesDms, !settings_.getBool(Setting::CoordinatesDms));
    if (row(i) == Row::ProbeMacs) settings_.setBool(Setting::ProbeMacRaw, !settings_.getBool(Setting::ProbeMacRaw));
 }
@@ -11,7 +11,7 @@ namespace roro {
 // values, choice lists and validation messages. Rendering and navigation live in the App.
 class SettingsMenu {
   public:
-    enum class Row { LongName, ShortName, Region, Timezone, Brightness, DimTimeout, OffTimeout, Sound, Gnss, Coordinates, ProbeMacs, Wifi, Storage, Firmware, About };
+    enum class Row { LongName, ShortName, Region, Timezone, Brightness, DimTimeout, OffTimeout, Sound, Gnss, GnssQuiet, Coordinates, ProbeMacs, Wifi, CheckUpdates, Firmware, DebugConsole, About };
    enum class Kind { Text, Choice, Toggle, Slider, Page };
    explicit SettingsMenu(Settings& settings) : settings_(settings) {}
@@ -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
@@ -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
@@ -2,7 +2,10 @@
 #include <cstdint>
 #include <vector>
 #include "key_event.h"
 #include "key_help.h"
 namespace roro {
@@ -25,11 +28,28 @@ 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; }
    virtual void draw(Canvas& canvas) = 0;
    // True while the screen shows something a picture of it shouldn't hold: the screenshot key
    // (Fn+p, issue #83) then refuses, and says so.
    virtual bool showsSecret() const { return false; }
    // An App whose screen is costly to draw again (a picture decoded from the card, issue #45) can
    // keep what it drew: while this is true its part of the screen isn't cleared before draw(),
    // which then draws only what changed. contentLost() says that it was cleared after all, or
    // that something drawn over it has gone: everything has to be drawn again.
    virtual bool retainsContent() const { return false; }
    virtual void contentLost() {}
    void requestRedraw() { redraw_ = true; }
    bool consumeRedraw() {
@@ -0,0 +1,467 @@
 #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)"},
    {"Fn p", "a screenshot, on the card"},
 };
 // 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"},
    {"w", "share with a browser"},
    {"`", "the folder above"},
 };
 // storage-share: Storage, sharing with a browser
 inline constexpr KeyHelp kStorageShare[] = {
    {"`", "stop sharing"},
 };
 // 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"},
    {"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"},
 };
 // viewer-image: A picture
 inline constexpr KeyHelp kViewerImage[] = {
    {"Enter", "its own size, or all of it"},
    {"; . , /", "move around it"},
    {"i", "its size"},
    {"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 Fn ; .", "start, end of the note"},
    {"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
@@ -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;
@@ -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;
 };
@@ -16,6 +16,8 @@ enum class Key : uint8_t {
    Home,
    Tab,
    Delete,
    Help,  // Fn+h anywhere, or ? outside Text Entry: the keys of this screen (issue #69)
    Screenshot,  // Fn+p anywhere: the screen as a PNG on the card (issue #83). Never reaches an App
 };
 struct KeyEvent {
@@ -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
@@ -0,0 +1,117 @@
 #include "debug_auth.h"
 #include <cstring>
 #include "sha256.h"
 namespace roro::debug {
 namespace {
 const char kAlphabet[] = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
 }
 std::string makeToken(const uint8_t random[kTokenRandom]) {
    std::string token;
    uint32_t bits = 0;
    int have = 0;
    size_t next = 0;
    while (token.size() < kTokenChars) {
        if (have < 5) {
            bits = (bits << 8) | random[next++];
            have += 8;
        }
        token += kAlphabet[(bits >> (have - 5)) & 31];
        have -= 5;
    }
    return token;
 }
 std::string tidyToken(const std::string& typed) {
    std::string out;
    for (char c : typed) {
        if (c == '-' || c == ' ' || c == '\t' || c == '\r' || c == '\n') continue;
        if (c >= 'a' && c <= 'z') c = static_cast<char>(c - 'a' + 'A');
        // Crockford's rule for the letters his alphabet leaves out: read as the digit they look like.
        if (c == 'O') c = '0';
        if (c == 'I' || c == 'L') c = '1';
        out += c;
    }
    return out;
 }
 bool validToken(const std::string& tidied) {
    if (tidied.size() < kMinTokenChars || tidied.size() > kMaxTokenChars) return false;
    for (char c : tidied)
        if (c <= ' ' || c > '~' || c == '-' || (c >= 'a' && c <= 'z') || c == 'O' || c == 'I' || c == 'L') return false;
    return true;
 }
 std::string groupToken(const std::string& token) {
    std::string out;
    for (size_t i = 0; i < token.size(); i++) {
        if (i && i % 4 == 0) out += '-';
        out += token[i];
    }
    return out;
 }
 void hmacSha256(const uint8_t* key, size_t keyLen, const uint8_t* message, size_t messageLen, uint8_t out[32]) {
    uint8_t block[64] = {};
    if (keyLen > sizeof block) Sha256::hash(key, keyLen, block);  // a long key is hashed first
    else memcpy(block, key, keyLen);
    uint8_t pad[64];
    for (size_t i = 0; i < sizeof pad; i++) pad[i] = block[i] ^ 0x36;
    uint8_t inner[32];
    Sha256 in;
    in.update(pad, sizeof pad);
    in.update(message, messageLen);
    in.finish(inner);
    for (size_t i = 0; i < sizeof pad; i++) pad[i] = block[i] ^ 0x5c;
    Sha256 outer;
    outer.update(pad, sizeof pad);
    outer.update(inner, sizeof inner);
    outer.finish(out);
 }
 std::string toHex(const uint8_t* data, size_t len) {
    static const char digits[] = "0123456789abcdef";
    std::string out;
    out.reserve(len * 2);
    for (size_t i = 0; i < len; i++) {
        out += digits[data[i] >> 4];
        out += digits[data[i] & 15];
    }
    return out;
 }
 std::string answerFor(const std::string& token, const uint8_t nonce[kNonceBytes]) {
    uint8_t mac[32];
    hmacSha256(reinterpret_cast<const uint8_t*>(token.data()), token.size(), nonce, kNonceBytes, mac);
    return toHex(mac, sizeof mac);
 }
 bool sameText(const std::string& a, const std::string& b) {
    uint8_t diff = a.size() != b.size();
    for (size_t i = 0; i < b.size(); i++) diff |= static_cast<uint8_t>((i < a.size() ? a[i] : 0) ^ b[i]);
    return diff == 0;
 }
 bool AuthGate::locked(uint32_t nowMs) {
    if (locked_ && nowMs - lockedAtMs_ >= kLockMs) {  // unsigned: right across the 49-day wrap too
        locked_ = false;
        failures_ = 0;
    }
    return locked_;
 }
 bool AuthGate::failed(uint32_t nowMs) {
    if (locked(nowMs)) return false;
    if (++failures_ < kMaxFailures) return false;
    locked_ = true;
    lockedAtMs_ = nowMs;
    return true;
 }
 }  // namespace roro::debug
@@ -0,0 +1,59 @@
 #pragma once
 #include <cstddef>
 #include <cstdint>
 #include <string>
 // Who may use the Debug Console (ADR 0010): a token that only the device and its owner know, proved
 // with a challenge and an answer so that it never crosses the network, and a pause after wrong answers.
 namespace roro::debug {
 constexpr size_t kTokenChars = 20;     // a token the device makes: 100 bits
 constexpr size_t kTokenRandom = 13;    // the random bytes it takes
 constexpr size_t kMinTokenChars = 16;  // a token typed by hand, once tidied
 constexpr size_t kMaxTokenChars = 64;
 constexpr size_t kNonceBytes = 16;
 // A token from random bytes: 20 characters of Crockford's base32 (no I, L, O or U to misread).
 std::string makeToken(const uint8_t random[kTokenRandom]);
 // What a person typed, as it's stored and compared: no dashes or spaces, in capitals, and with O
 // read as 0, I and L as 1. So a token can be read off the screen in groups, typed in any case,
 // and the usual misreadings don't matter.
 std::string tidyToken(const std::string& typed);
 // A tidied token that may be stored: 16 to 64 printable ASCII characters, as tidyToken leaves them.
 bool validToken(const std::string& tidied);
 // For the screen: K7QF-3M2X-9WBD-HT4P-6RNC.
 std::string groupToken(const std::string& token);
 void hmacSha256(const uint8_t* key, size_t keyLen, const uint8_t* message, size_t messageLen, uint8_t out[32]);
 std::string toHex(const uint8_t* data, size_t len);
 // What a client must send back for a challenge: HMAC-SHA256 of the nonce, keyed by the token, in hex.
 std::string answerFor(const std::string& token, const uint8_t nonce[kNonceBytes]);
 // Compares without stopping at the first difference, so timing says nothing about the answer.
 bool sameText(const std::string& a, const std::string& b);
 // Five wrong answers in a row, from anyone, and nobody is listened to for a minute.
 class AuthGate {
   public:
    static constexpr int kMaxFailures = 5;
    static constexpr uint32_t kLockMs = 60000;
    bool locked(uint32_t nowMs);
    // A wrong answer. True if it's the one that starts the pause.
    bool failed(uint32_t nowMs);
    void succeeded() { failures_ = 0; }
    int failures() const { return failures_; }
   private:
    int failures_ = 0;
    bool locked_ = false;
    uint32_t lockedAtMs_ = 0;
 };
 }  // namespace roro::debug
@@ -0,0 +1,137 @@
 #include "file_list.h"
 #include <algorithm>
 #include <cctype>
 #include <cstdio>
 #include <cstring>
 #include <ctime>
 namespace roro::files {
 namespace {
 // Names compare letters only, whatever the case; ties by the bytes, so the order is total.
 int compareNames(const char* a, const char* b) {
    for (const char *x = a, *y = b;; ++x, ++y) {
        int cx = std::tolower(static_cast<unsigned char>(*x)), cy = std::tolower(static_cast<unsigned char>(*y));
        if (cx != cy) return cx < cy ? -1 : 1;
        if (!cx) break;
    }
    return std::strcmp(a, b);
 }
 constexpr uint32_t kYear2020 = 1577836800;
 std::string sizeText(uint32_t bytes) {
    char s[16];
    if (bytes < 1024) std::snprintf(s, sizeof s, "%u B", static_cast<unsigned>(bytes));
    else if (bytes < 10 * 1024) std::snprintf(s, sizeof s, "%.1f KB", bytes / 1024.0);
    else if (bytes < 1024 * 1024) std::snprintf(s, sizeof s, "%u KB", static_cast<unsigned>(bytes / 1024));
    else if (bytes < 10u * 1024 * 1024) std::snprintf(s, sizeof s, "%.1f MB", bytes / 1048576.0);
    else if (bytes < 1024u * 1024 * 1024) std::snprintf(s, sizeof s, "%u MB", static_cast<unsigned>(bytes / 1048576));
    else std::snprintf(s, sizeof s, "%.1f GB", bytes / 1073741824.0);
    return s;
 }
 }  // namespace
 void FileList::clear() {
    std::vector<Entry>().swap(entries_);
    std::vector<uint16_t>().swap(order_);
    std::vector<char>().swap(names_);
    more_ = wasted_ = 0;
 }
 bool FileList::before(const Entry& a, const Entry& b, FileSort by) const {
    if (a.folder != b.folder) return a.folder;
    if (!a.folder) {
        if (by == FileSort::Date && a.modified != b.modified) return a.modified > b.modified;
        if (by == FileSort::Size && a.size != b.size) return a.size > b.size;
    }
    return compareNames(names_.data() + a.name, names_.data() + b.name) < 0;
 }
 void FileList::add(const char* name, uint32_t size, uint32_t modified, bool folder) {
    size_t len = std::strlen(name) + 1;
    if (entries_.size() >= kMax) {
        // Full: the new entry takes the place of the one that sorts last by name, if it sorts
        // before it. The old name's bytes stay in the buffer until there's enough waste to pack.
        more_++;
        size_t last = 0;
        for (size_t i = 1; i < entries_.size(); i++)
            if (before(entries_[last], entries_[i], FileSort::Name)) last = i;
        Entry candidate{static_cast<uint32_t>(names_.size()), size, modified, folder};
        names_.insert(names_.end(), name, name + len);
        if (!before(candidate, entries_[last], FileSort::Name)) {
            names_.resize(names_.size() - len);
            return;
        }
        wasted_ += std::strlen(names_.data() + entries_[last].name) + 1;
        entries_[last] = candidate;
        if (wasted_ > 2048) compact();
        return;
    }
    if (entries_.empty()) {
        entries_.reserve(32);
        names_.reserve(512);
    }
    entries_.push_back({static_cast<uint32_t>(names_.size()), size, modified, folder});
    names_.insert(names_.end(), name, name + len);
    order_.push_back(static_cast<uint16_t>(order_.size()));
 }
 void FileList::compact() {
    std::vector<char> packed;
    packed.reserve(names_.size() - wasted_);
    for (Entry& e : entries_) {
        const char* n = names_.data() + e.name;
        e.name = static_cast<uint32_t>(packed.size());
        packed.insert(packed.end(), n, n + std::strlen(n) + 1);
    }
    names_.swap(packed);
    wasted_ = 0;
 }
 void FileList::sort(FileSort by) {
    if (wasted_) compact();
    names_.shrink_to_fit();
    entries_.shrink_to_fit();
    order_.resize(entries_.size());
    for (size_t i = 0; i < order_.size(); i++) order_[i] = static_cast<uint16_t>(i);
    std::sort(order_.begin(), order_.end(), [&](uint16_t a, uint16_t b) { return before(entries_[a], entries_[b], by); });
 }
 int FileList::find(const std::string& name) const {
    for (size_t i = 0; i < order_.size(); i++)
        if (name == this->name(i)) return static_cast<int>(i);
    return -1;
 }
 size_t FileList::bytes() const {
    return entries_.capacity() * sizeof(Entry) + order_.capacity() * sizeof(uint16_t) + names_.capacity();
 }
 std::string formatStamp(uint32_t modified) {
    if (modified < kYear2020) return "-";
    time_t t = static_cast<time_t>(modified);
    struct tm local;
    localtime_r(&t, &local);
    char s[20];
    std::snprintf(s, sizeof s, "%04d-%02d-%02d %02d:%02d", local.tm_year + 1900, local.tm_mon + 1, local.tm_mday, local.tm_hour,
                  local.tm_min);
    return s;
 }
 std::string rowDetail(bool folder, uint32_t size, uint32_t modified) {
    if (folder) return "folder";
    std::string stamp = formatStamp(modified);
    return sizeText(size) + "  " + (stamp == "-" ? stamp : stamp.substr(0, 10));
 }
 std::string fitName(const std::string& name, size_t maxChars) {
    if (name.size() <= maxChars || maxChars < 8) return name.substr(0, maxChars);
    size_t tail = std::min<size_t>(6, maxChars / 3), head = maxChars - tail - 2;
    return name.substr(0, head) + ".." + name.substr(name.size() - tail);
 }
 }  // namespace roro::files
@@ -0,0 +1,55 @@
 #pragma once
 #include <cstddef>
 #include <cstdint>
 #include <string>
 #include <vector>
 namespace roro::files {
 enum class FileSort : uint8_t { Name, Date, Size };
 // A folder's entries for the Storage App (F1, Q129, Q136): 256 at most, the names packed into
 // one buffer, about 10 KB when full. A bigger folder keeps the first 256 by name, whatever order
 // the card lists them in, and counts the rest.
 class FileList {
   public:
    static constexpr size_t kMax = 256;
    void clear();
    void add(const char* name, uint32_t size, uint32_t modified, bool folder);
    void sort(FileSort by);  // folders first, by name; then files by name, newest or biggest first
    size_t count() const { return entries_.size(); }
    size_t more() const { return more_; }  // entries that didn't fit
    // By position after sort().
    const char* name(size_t i) const { return names_.data() + entries_[order_[i]].name; }
    uint32_t size(size_t i) const { return entries_[order_[i]].size; }
    uint32_t modified(size_t i) const { return entries_[order_[i]].modified; }  // Unix time, 0 if unknown
    bool folder(size_t i) const { return entries_[order_[i]].folder; }
    int find(const std::string& name) const;  // position, or -1
    size_t bytes() const;                     // memory held
   private:
    struct Entry {
        uint32_t name;  // offset into names_
        uint32_t size, modified;
        bool folder;
    };
    bool before(const Entry& a, const Entry& b, FileSort by) const;
    void compact();
    std::vector<Entry> entries_;
    std::vector<uint16_t> order_;
    std::vector<char> names_;
    size_t more_ = 0, wasted_ = 0;
 };
 // What a row shows on the right (Q129): "folder", or "1.2 KB  2026-10-05". A file dated before
 // 2020 was written before the clock was set: "-" (Q137). Local time.
 std::string rowDetail(bool folder, uint32_t size, uint32_t modified);
 std::string formatStamp(uint32_t modified);
 // A name cut to `maxChars` for a row, from the middle: the start and the extension stay readable.
 std::string fitName(const std::string& name, size_t maxChars);  // "2026-10-05 20:00", or "-"
 }  // namespace roro::files
@@ -0,0 +1,147 @@
 #include "file_names.h"
 #include <cctype>
 namespace roro::files {
 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) {
    size_t slash = path.rfind('/');
    return slash == std::string::npos || slash == 0 ? "/" : path.substr(0, slash);
 }
 std::string baseName(const std::string& path) {
    size_t slash = path.rfind('/');
    return slash == std::string::npos ? path : path.substr(slash + 1);
 }
 std::string joinPath(const std::string& folder, const std::string& name) {
    return folder == "/" ? "/" + name : folder + "/" + name;
 }
 std::string extensionOf(const std::string& name) {
    size_t dot = name.rfind('.');
    if (dot == std::string::npos || dot == 0) return "";
    std::string ext = name.substr(dot + 1);
    for (char& c : ext) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
    return ext;
 }
 bool isInside(const std::string& path, const std::string& folder) {
    if (folder == "/") return true;
    if (path.compare(0, folder.size(), folder) != 0) return false;
    return path.size() == folder.size() || path[folder.size()] == '/';
 }
 std::string checkName(const std::string& name) {
    if (name.empty()) return "A name can't be empty";
    if (name == "." || name == "..") return "\".\" and \"..\" aren't names";
    if (name.size() > 64) return "A name can be 64 characters at most";
    for (char c : name) {
        if (static_cast<unsigned char>(c) < 0x20) return "A name can't contain control characters";
        for (char bad : std::string("/\\:*?\"<>|"))
            if (c == bad) return std::string("A name can't contain ") + c;
    }
    if (name.back() == '.' || name.back() == ' ') return "A name can't end with a dot or a space";
    return "";
 }
 std::string whyReadOnly(const std::string& path, const std::vector<std::string>& inUse) {
    if (path == "/" || path.empty()) return "That's the card itself";
    if (isInside(path, kGeminiCache)) return std::string(kGeminiCache) + " is the Gemini App's working space";
    for (const std::string& open : inUse) {
        if (open == path) return "It's being written right now";
        if (isInside(open, path)) return "It holds a file that's being written right now";
    }
    for (size_t i = 0; i < kFirmwareFolderCount; i++)
        if (path == kFirmwareFolders[i]) return std::string("The firmware keeps its files in ") + path;
    return "";
 }
 std::string whyNotInto(const std::string& source, const std::string& into) {
    if (isInside(into, kGeminiCache)) return std::string(kGeminiCache) + " is the Gemini App's working space";
    if (isInside(into, source)) return "A folder can't go inside itself";
    if (parentOf(source) == into) return "It's already there";
    return "";
 }
 std::string copyName(const std::string& name, int n) {
    size_t dot = name.rfind('.');
    std::string suffix = " (" + std::to_string(n) + ")";
    if (dot == std::string::npos || dot == 0) return name + suffix;
    return name.substr(0, dot) + suffix + name.substr(dot);
 }
 FileKind kindOf(const std::string& name) {
    std::string ext = extensionOf(name);
    if (ext == "gpx") return FileKind::Gpx;
    if (ext == "pcap") return FileKind::Pcap;
    if (ext == "ota") return FileKind::Ota;
    for (const char* text : {"txt", "log", "gmi", "csv", "md", "json", "ini", "conf", "ir"})
        if (ext == text) return FileKind::Text;
    return FileKind::Unknown;
 }
 bool opensAtEnd(const std::string& name) { return extensionOf(name) == "log"; }
 bool looksLikeText(const uint8_t* data, size_t len) {
    size_t odd = 0;
    for (size_t i = 0; i < len; i++) {
        uint8_t b = data[i];
        if (b == 0) return false;
        if (b < 0x20 && b != '\n' && b != '\r' && b != '\t') odd++;
    }
    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
@@ -0,0 +1,58 @@
 #pragma once
 #include <cstddef>
 #include <cstdint>
 #include <string>
 #include <vector>
 namespace roro::files {
 // Paths on the SD card are absolute and use '/': "/gemini/saved/index.gmi".
 std::string parentOf(const std::string& path);    // "/" for a top-level entry and for "/"
 std::string baseName(const std::string& path);    // "" for "/"
 std::string joinPath(const std::string& folder, const std::string& name);
 std::string extensionOf(const std::string& name);  // lower case, without the dot; "" if none
 bool isInside(const std::string& path, const std::string& folder);  // a folder is inside itself
 // A name typed for rename or a new folder (F1, Q131): "" if FAT and this App can take it, or why not.
 std::string checkName(const std::string& name);
 // The top-level folders the firmware keeps its files in. They can't be renamed or deleted;
 // what's in them can (Q130).
 extern const char* const kFirmwareFolders[];
 extern const size_t kFirmwareFolderCount;
 constexpr const char* kGeminiCache = "/gemini/cache";
 // Why `path` can't be renamed, moved or deleted, or "" if it can (Q130). `inUse`: the files the
 // firmware has open right now.
 std::string whyReadOnly(const std::string& path, const std::vector<std::string>& inUse);
 // Why `source` can't be copied or moved into the folder `into`, or "" if it can.
 std::string whyNotInto(const std::string& source, const std::string& into);
 // "a (2).gmi": the name of a copy made next to its original.
 std::string copyName(const std::string& name, int n);
 // Which viewer opens a file (Q134), from its name. Unknown: look at the first bytes.
 enum class FileKind : uint8_t { Text, Gpx, Pcap, Ota, Unknown };
 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
@@ -0,0 +1,143 @@
 #include "file_views.h"
 #include <cstdio>
 #include <cstdlib>
 #include <cstring>
 #include "file_list.h"
 #include "track.h"
 namespace roro::files {
 std::string hexRow(uint32_t offset, const uint8_t* data, size_t len) {
    char head[8];
    std::snprintf(head, sizeof head, "%05X", static_cast<unsigned>(offset));
    std::string row = head, text;
    for (size_t i = 0; i < 8; i++) {
        if (i % 2 == 0) row += ' ';
        char hex[3] = "  ";
        if (i < len) {
            std::snprintf(hex, sizeof hex, "%02x", data[i]);
            text += data[i] >= 0x20 && data[i] < 0x7F ? static_cast<char>(data[i]) : '.';
        }
        row += hex;
    }
    return row + "  " + text;
 }
 namespace {
 // Days since 1970-01-01 (Howard Hinnant's days_from_civil): no timegm() everywhere.
 int64_t daysFromCivil(int y, int m, int d) {
    y -= m <= 2;
    int64_t era = (y >= 0 ? y : y - 399) / 400;
    int yoe = static_cast<int>(y - era * 400);
    int doy = (153 * (m + (m > 2 ? -3 : 9)) + 2) / 5 + d - 1;
    int doe = yoe * 365 + yoe / 4 - yoe / 100 + doy;
    return era * 146097 + doe - 719468;
 }
 bool attribute(const std::string& element, const char* name, double& out) {
    size_t at = element.find(name);
    if (at == std::string::npos) return false;
    const char* from = element.c_str() + at + std::strlen(name);
    char* end = nullptr;
    out = std::strtod(from, &end);
    return end != from;
 }
 }  // namespace
 void GpxSummary::point(const std::string& element) {
    double lat, lon;
    if (!attribute(element, "lat=\"", lat) || !attribute(element, "lon=\"", lon)) return;
    if (points_ > 0) meters_ += gnss::distanceMeters(lat_, lon_, lat, lon);
    lat_ = lat;
    lon_ = lon;
    points_++;
    size_t at = element.find("<time>");
    int y, mo, d, h, mi, s;
    if (at != std::string::npos && std::sscanf(element.c_str() + at + 6, "%d-%d-%dT%d:%d:%d", &y, &mo, &d, &h, &mi, &s) == 6) {
        int64_t t = daysFromCivil(y, mo, d) * 86400 + h * 3600 + mi * 60 + s;
        if (first_ == 0) first_ = t;
        last_ = t;
    }
 }
 void GpxSummary::feed(const char* data, size_t len) {
    carry_.append(data, len);
    size_t done = 0;
    for (;;) {
        size_t open = carry_.find("<trkpt", done);
        if (open == std::string::npos) {
            // Nothing begun, except perhaps the first letters of a tag at the very end.
            done = carry_.size() > 6 ? carry_.size() - 6 : done;
            break;
        }
        size_t close = carry_.find("</trkpt>", open);
        size_t next = carry_.find("<trkpt", open + 6);  // a point with nothing inside: <trkpt .../>
        if (close == std::string::npos && next == std::string::npos) {
            done = open;
            break;
        }
        size_t end = close != std::string::npos && (next == std::string::npos || close < next) ? close + 8 : next;
        point(carry_.substr(open, end - open));
        done = end;
    }
    carry_.erase(0, done);
    if (carry_.size() > 2048) carry_.erase(0, carry_.size() - 6);  // not a GPX point: don't keep it
 }
 std::string formatDuration(int64_t seconds) {
    char s[24];
    if (seconds < 60) std::snprintf(s, sizeof s, "%d s", static_cast<int>(seconds));
    else if (seconds < 3600) std::snprintf(s, sizeof s, "%d min %02d s", static_cast<int>(seconds / 60), static_cast<int>(seconds % 60));
    else std::snprintf(s, sizeof s, "%d h %02d min", static_cast<int>(seconds / 3600), static_cast<int>(seconds % 3600 / 60));
    return s;
 }
 std::vector<std::string> GpxSummary::lines() const {
    std::vector<std::string> out;
    out.push_back(std::to_string(points_) + (points_ == 1 ? " point" : " points"));
    if (first_ > 0) {
        out.push_back("Started " + formatStamp(static_cast<uint32_t>(first_)));
        out.push_back("Lasted " + formatDuration(last_ - first_));
    }
    char s[32];
    if (meters_ < 1000) std::snprintf(s, sizeof s, "Distance %.0f m", meters_);
    else std::snprintf(s, sizeof s, "Distance %.2f km", meters_ / 1000);
    out.push_back(s);
    return out;
 }
 namespace {
 uint32_t le32(const uint8_t* p) { return p[0] | p[1] << 8 | p[2] << 16 | static_cast<uint32_t>(p[3]) << 24; }
 }  // namespace
 PcapHeader parsePcapHeader(const uint8_t* data, size_t len) {
    PcapHeader h;
    if (len < kPcapHeaderSize || le32(data) != 0xA1B2C3D4) return h;  // little-endian, microseconds: what we write
    h.ok = true;
    h.linkType = le32(data + 20);
    return h;
 }
 bool parsePcapRecord(const uint8_t* data, size_t len, PcapRecord& out) {
    if (len < kPcapRecordSize) return false;
    out.seconds = le32(data);
    out.micros = le32(data + 4);
    out.length = le32(data + 8);
    return out.length <= 65535;
 }
 bool parseLoraTap(const uint8_t* d, size_t len, lora::RxInfo& out) {
    if (len < lora::kLoraTapSize || d[0] != 0) return false;
    out.frequencyHz = static_cast<uint32_t>(d[4]) << 24 | d[5] << 16 | d[6] << 8 | d[7];
    out.bandwidthKHz = d[8] * 125.0f;
    out.spreadingFactor = d[9];
    out.rssi = d[10] - 139.0f;
    out.noiseFloor = d[12] - 139.0f;
    out.snr = static_cast<int8_t>(d[13]) / 4.0f;
    out.syncWord = d[14];
    return true;
 }
 }  // namespace roro::files
@@ -0,0 +1,57 @@
 #pragma once
 #include <cstddef>
 #include <cstdint>
 #include <string>
 #include <vector>
 #include "loratap.h"
 namespace roro::files {
 // What the Storage App's viewers show of the files the firmware writes (F1, Q134).
 // One row of a hex dump, eight bytes: "00010 4865 6c6c 6f2c 2077  Hello, w".
 std::string hexRow(uint32_t offset, const uint8_t* data, size_t len);
 // A Track (.gpx) read a piece at a time: its points, when it started and ended, how far it went.
 class GpxSummary {
   public:
    void feed(const char* data, size_t len);
    uint32_t points() const { return points_; }
    int64_t start() const { return first_; }  // UTC seconds, 0 if no point carried a time
    int64_t end() const { return last_; }
    double meters() const { return meters_; }
    std::vector<std::string> lines() const;  // for the screen
   private:
    void point(const std::string& element);
    std::string carry_;  // the part of a point cut by the end of a piece
    uint32_t points_ = 0;
    int64_t first_ = 0, last_ = 0;
    double meters_ = 0, lat_ = 0, lon_ = 0;
 };
 // "1 h 02 min", "4 min 10 s", "12 s".
 std::string formatDuration(int64_t seconds);
 // A Capture (.pcap): the file's header, then one record after another.
 struct PcapHeader {
    bool ok = false;
    uint32_t linkType = 0;  // 270: LoRaTap, what the LoRa Scanner writes
 };
 constexpr size_t kPcapHeaderSize = 24, kPcapRecordSize = 16;
 constexpr uint32_t kLinkLoraTap = 270;
 PcapHeader parsePcapHeader(const uint8_t* data, size_t len);
 struct PcapRecord {
    uint32_t seconds = 0, micros = 0, length = 0;  // length: the bytes that follow in the file
 };
 bool parsePcapRecord(const uint8_t* data, size_t len, PcapRecord& out);  // false: not a record, stop there
 // The LoRaTap header a packet starts with; false if `len` is too short for one.
 bool parseLoraTap(const uint8_t* data, size_t len, lora::RxInfo& out);
 }  // namespace roro::files
@@ -0,0 +1,464 @@
 #include "image_file.h"
 #include <algorithm>
 #include <cstring>
 #include <memory>
 #include <new>
 #include "file_names.h"
 #include "png_rgb332.h"
 namespace roro::files {
 namespace {
 uint32_t le16(const uint8_t* p) { return p[0] | (p[1] << 8); }
 uint32_t le32(const uint8_t* p) { return p[0] | (p[1] << 8) | (p[2] << 16) | (static_cast<uint32_t>(p[3]) << 24); }
 uint32_t be16(const uint8_t* p) { return (p[0] << 8) | p[1]; }
 uint32_t be32(const uint8_t* p) { return (static_cast<uint32_t>(p[0]) << 24) | (p[1] << 16) | (p[2] << 8) | p[3]; }
 constexpr int kMaxSide = 16384;  // more than that isn't a picture for this screen
 const uint8_t kPngSignature[] = {0x89, 'P', 'N', 'G', '\r', '\n', 0x1A, '\n'};
 // A file read from its start on, a small block at a time.
 class Stream {
   public:
    Stream(const ImageRead& read, uint32_t size) : read_(read), size_(size) {}
    int get() {
        if (at_ >= have_) {
            if (next_ >= size_) return -1;
            have_ = read_(next_, buf_, std::min<size_t>(sizeof buf_, size_ - next_));
            at_ = 0;
            next_ += static_cast<uint32_t>(have_);
            if (!have_) return -1;
        }
        return buf_[at_++];
    }
    bool take(uint8_t* into, size_t len) {
        for (size_t i = 0; i < len; i++) {
            int c = get();
            if (c < 0) return false;
            into[i] = static_cast<uint8_t>(c);
        }
        return true;
    }
    bool skip(size_t len) {
        size_t buffered = std::min(len, have_ - at_);
        at_ += buffered;
        len -= buffered;
        if (len > size_ - next_) return false;
        next_ += static_cast<uint32_t>(len);
        return true;
    }
   private:
    const ImageRead& read_;
    uint32_t size_, next_ = 0;
    uint8_t buf_[256];
    size_t have_ = 0, at_ = 0;
 };
 }  // namespace
 ImageKind imageKindOfName(const std::string& name) {
    std::string ext = extensionOf(name);
    if (ext == "png") return ImageKind::Png;
    if (ext == "jpg" || ext == "jpeg") return ImageKind::Jpeg;
    if (ext == "bmp") return ImageKind::Bmp;
    if (ext == "gif") return ImageKind::Gif;
    return ImageKind::None;
 }
 ImageKind imageKindOfBytes(const uint8_t* head, size_t len) {
    if (len >= 8 && std::memcmp(head, kPngSignature, 8) == 0) return ImageKind::Png;
    if (len >= 3 && head[0] == 0xFF && head[1] == 0xD8 && head[2] == 0xFF) return ImageKind::Jpeg;
    if (len >= 6 && (std::memcmp(head, "GIF87a", 6) == 0 || std::memcmp(head, "GIF89a", 6) == 0)) return ImageKind::Gif;
    if (len >= 2 && head[0] == 'B' && head[1] == 'M') return ImageKind::Bmp;
    return ImageKind::None;
 }
 const char* imageKindName(ImageKind kind) {
    switch (kind) {
        case ImageKind::Png: return "PNG";
        case ImageKind::Jpeg: return "JPEG";
        case ImageKind::Bmp: return "BMP";
        case ImageKind::Gif: return "GIF";
        default: return "";
    }
 }
 std::string imageInfo(const ImageRead& read, uint32_t size, ImageInfo& out) {
    uint8_t head[32];
    size_t n = read(0, head, std::min<size_t>(sizeof head, size));
    out.kind = imageKindOfBytes(head, n);
    long w = 0, h = 0;
    switch (out.kind) {
        case ImageKind::Png:
            if (n < 24 || std::memcmp(head + 12, "IHDR", 4) != 0) return "This PNG is damaged";
            w = static_cast<long>(be32(head + 16));
            h = static_cast<long>(be32(head + 20));
            break;
        case ImageKind::Gif:
            if (n < 10) return "This GIF is damaged";
            w = static_cast<long>(le16(head + 6));
            h = static_cast<long>(le16(head + 8));
            break;
        case ImageKind::Bmp: {
            if (n < 26) return "This BMP is damaged";
            uint32_t dib = le32(head + 14);
            if (dib < 40) return "This kind of BMP can't be shown";
            w = static_cast<int32_t>(le32(head + 18));
            h = static_cast<int32_t>(le32(head + 22));
            if (h < 0) h = -h;  // top row first
            break;
        }
        case ImageKind::Jpeg: {
            // Marker after marker until the one that carries the size.
            uint32_t at = 2;
            for (int guard = 0; guard < 4000; guard++) {
                uint8_t m[9];
                if (read(at, m, 4) != 4 || m[0] != 0xFF) return "This JPEG is damaged";
                uint8_t marker = m[1];
                if (marker == 0xFF) {  // padding
                    at++;
                    continue;
                }
                if (marker == 0x01 || (marker >= 0xD0 && marker <= 0xD8)) {  // no length
                    at += 2;
                    continue;
                }
                if (marker == 0xD9 || marker == 0xDA) return "This JPEG is damaged";  // the picture, and no size yet
                bool frame = marker >= 0xC0 && marker <= 0xCF && marker != 0xC4 && marker != 0xC8 && marker != 0xCC;
                if (frame) {
                    if (read(at, m, 9) != 9) return "This JPEG is damaged";
                    h = static_cast<long>(be16(m + 5));
                    w = static_cast<long>(be16(m + 7));
                    if (marker == 0xC2) return "A progressive JPEG can't be shown";
                    if (marker != 0xC0 && marker != 0xC1) return "This kind of JPEG can't be shown";
                    break;
                }
                at += 2 + be16(m + 2);
            }
            break;
        }
        default: return "Not a picture this can show";
    }
    if (w <= 0 || h <= 0) return "This picture is damaged";
    if (w > kMaxSide || h > kMaxSide) return "Too big: 16,384 pixels a side at most";
    out.width = static_cast<int>(w);
    out.height = static_cast<int>(h);
    return "";
 }
 uint32_t screenshotPixelsAt(const ImageRead& read, uint32_t size, int width, int height) {
    if (width <= 0 || height <= 0 || size != png::Rgb332Writer::fileSize(width, height)) return 0;
    // Signature, IHDR, then a palette of 256 colours, then the one IDAT: a zlib header and a
    // single stored block.
    uint8_t ihdr[5], plte[8], idat[15];
    constexpr uint32_t kPlteAt = 8 + 25, kIdatAt = kPlteAt + 12 + 768;
    if (read(24, ihdr, 5) != 5 || ihdr[0] != 8 || ihdr[1] != 3 || ihdr[4] != 0) return 0;
    if (read(kPlteAt, plte, 8) != 8 || be32(plte) != 768 || std::memcmp(plte + 4, "PLTE", 4) != 0) return 0;
    if (read(kIdatAt, idat, 15) != 15 || std::memcmp(idat + 4, "IDAT", 4) != 0) return 0;
    uint32_t raw = static_cast<uint32_t>(width + 1) * static_cast<uint32_t>(height);
    if (idat[8] != 0x78 || idat[10] != 0x01 || le16(idat + 11) != raw || le16(idat + 13) != (raw ^ 0xFFFF)) return 0;
    return kIdatAt + 15 + 1;  // past the first row's filter byte
 }
 uint8_t rgb332Dithered(uint8_t r, uint8_t g, uint8_t b, int x, int y) {
    static const uint8_t kBayer[16] = {0, 8, 2, 10, 12, 4, 14, 6, 3, 11, 1, 9, 15, 7, 13, 5};
    int threshold = kBayer[((y & 3) << 2) | (x & 3)] * 16 + 8;  // 8 to 248
    auto level = [threshold](int v, int top) {
        int nearest = (v * top + 127) / 255;
        if (nearest * 255 / top == v) return nearest;  // a colour the screen has
        int low = v * top / 255, rest = v * top - low * 255;
        return rest > threshold ? low + 1 : low;
    };
    return static_cast<uint8_t>((level(r, 7) << 5) | (level(g, 7) << 2) | level(b, 3));
 }
 bool ImageMap::at(int sx, int sy, int& tx, int& ty) const {
    if (sx < 0 || sy < 0) return false;
    if (scale >= 65536) {
        tx = sx + offX;
        ty = sy + offY;
    } else {
        uint64_t fx = static_cast<uint64_t>(sx) * scale, fy = static_cast<uint64_t>(sy) * scale;
        if ((fx & 0xFFFF) >= scale || (fy & 0xFFFF) >= scale) return false;
        tx = static_cast<int>(fx >> 16) + offX;
        ty = static_cast<int>(fy >> 16) + offY;
    }
    if (tx < 0 || ty < 0 || tx >= viewW || ty >= viewH) return false;
    tx += viewX;
    ty += viewY;
    return true;
 }
 bool ImageMap::rowUsed(int sy) const {
    if (sy < 0) return false;
    int ty;
    if (scale >= 65536) {
        ty = sy + offY;
    } else {
        uint64_t fy = static_cast<uint64_t>(sy) * scale;
        if ((fy & 0xFFFF) >= scale) return false;
        ty = static_cast<int>(fy >> 16) + offY;
    }
    return ty >= 0 && ty < viewH;
 }
 bool ImageMap::below(int sy) const {
    if (sy < 0) return false;
    int ty = scale >= 65536 ? sy + offY : static_cast<int>((static_cast<uint64_t>(sy) * scale) >> 16) + offY;
    return ty >= viewH;
 }
 ImageFrame::ImageFrame(int width, int height, int viewX, int viewY, int viewW, int viewH)
    : w_(std::max(1, width)), h_(std::max(1, height)), vx_(viewX), vy_(viewY), vw_(std::max(1, viewW)), vh_(std::max(1, viewH)) {}
 uint32_t ImageFrame::fitScale() const {
    uint64_t sx = (static_cast<uint64_t>(vw_) << 16) / static_cast<uint64_t>(w_), sy = (static_cast<uint64_t>(vh_) << 16) / static_cast<uint64_t>(h_);
    return static_cast<uint32_t>(std::min<uint64_t>(65536, std::max<uint64_t>(1, std::min(sx, sy))));
 }
 void ImageFrame::toggle() {
    if (!bigger()) return;
    actual_ = !actual_;
    if (actual_) {  // the middle of it first
        panX_ = std::max(0, (w_ - vw_) / 2);
        panY_ = std::max(0, (h_ - vh_) / 2);
    }
 }
 bool ImageFrame::pan(int dx, int dy) {
    if (!actual_) return false;
    int x = std::clamp(panX_ + dx * (vw_ / 2), 0, std::max(0, w_ - vw_));
    int y = std::clamp(panY_ + dy * (vh_ / 2), 0, std::max(0, h_ - vh_));
    bool moved = x != panX_ || y != panY_;
    panX_ = x;
    panY_ = y;
    return moved;
 }
 int ImageFrame::percent() const { return actual_ ? 100 : static_cast<int>((static_cast<uint64_t>(fitScale()) * 100 + 32768) >> 16); }
 int ImageFrame::jpegShrink() const {
    if (actual_) return 0;
    uint32_t scale = fitScale();
    int shrink = 0;
    while (shrink < 3 && (static_cast<uint64_t>(scale) << (shrink + 1)) <= 65536) shrink++;
    return shrink;
 }
 ImageMap ImageFrame::map(int shrink) const {
    ImageMap m;
    m.viewX = vx_;
    m.viewY = vy_;
    m.viewW = vw_;
    m.viewH = vh_;
    if (actual_) {
        m.scale = 65536;
        m.offX = w_ <= vw_ ? (vw_ - w_) / 2 : -panX_;
        m.offY = h_ <= vh_ ? (vh_ - h_) / 2 : -panY_;
        return m;
    }
    uint32_t scale = fitScale();
    int tw = std::max<int>(1, static_cast<int>((static_cast<uint64_t>(w_) * scale) >> 16));
    int th = std::max<int>(1, static_cast<int>((static_cast<uint64_t>(h_) * scale) >> 16));
    m.offX = (vw_ - tw) / 2;
    m.offY = (vh_ - th) / 2;
    m.scale = static_cast<uint32_t>(std::min<uint64_t>(65536, static_cast<uint64_t>(scale) << shrink));
    return m;
 }
 std::string readBmp(const ImageRead& read, uint32_t size, const ImagePixels& pixels, const std::function<bool(int y)>& rowNeeded) {
    uint8_t head[54];
    if (read(0, head, sizeof head) != sizeof head || head[0] != 'B' || head[1] != 'M') return "This BMP is damaged";
    uint32_t dataAt = le32(head + 10), dib = le32(head + 14), compression = le32(head + 30), colours = le32(head + 46);
    int32_t w = static_cast<int32_t>(le32(head + 18)), h = static_cast<int32_t>(le32(head + 22));
    uint32_t bits = le16(head + 28);
    bool topDown = h < 0;
    if (topDown) h = -h;
    if (dib < 40 || w <= 0 || h <= 0 || w > kMaxSide || h > kMaxSide) return "This kind of BMP can't be shown";
    if ((bits != 8 && bits != 24 && bits != 32) || (compression != 0 && !(compression == 3 && bits == 32))) return "This kind of BMP can't be shown";
    std::unique_ptr<uint8_t[]> palette;
    if (bits == 8) {
        if (!colours || colours > 256) colours = 256;
        palette.reset(new (std::nothrow) uint8_t[1024]());
        if (!palette) return "Not enough memory";
        if (read(14 + dib, palette.get(), colours * 4) != colours * 4) return "This BMP is damaged";
    }
    uint32_t bytes = bits / 8, rowSize = (static_cast<uint32_t>(w) * bytes + 3) & ~3u;
    if (static_cast<uint64_t>(dataAt) + static_cast<uint64_t>(rowSize) * static_cast<uint32_t>(h) > size) return "This BMP is cut short";
    // A row in one read when it fits, a piece of it at a time otherwise.
    constexpr int kOut = 64;                  // pixels handed on at once
    constexpr uint32_t kRowBuffer = 4096;     // bytes
    uint32_t rowBytes = static_cast<uint32_t>(w) * bytes, bufSize = std::min(rowBytes, kRowBuffer);
    bufSize -= bufSize % bytes;
    std::unique_ptr<uint8_t[]> in(new (std::nothrow) uint8_t[bufSize]);
    if (!in) return "Not enough memory";
    uint8_t out[kOut * 3];
    // In the order the file has them, which is usually the last row first: going back through a
    // file on the card costs far more than going on (measured: a second for 135 rows).
    for (int stored = 0; stored < h; stored++) {
        int y = topDown ? stored : h - 1 - stored;
        if (rowNeeded && !rowNeeded(y)) continue;
        uint32_t rowAt = dataAt + rowSize * static_cast<uint32_t>(stored);
        for (uint32_t done = 0; done < rowBytes; done += bufSize) {
            size_t want = std::min(bufSize, rowBytes - done);
            if (read(rowAt + done, in.get(), want) != want) return "The card refused to read it";
            int first = static_cast<int>(done / bytes), count = static_cast<int>(want / bytes);
            for (int at = 0; at < count; at += kOut) {
                int n = std::min(kOut, count - at);
                for (int i = 0; i < n; i++) {
                    const uint8_t* p = bits == 8 ? palette.get() + in[at + i] * 4 : in.get() + static_cast<size_t>(at + i) * bytes;
                    out[i * 3] = p[2];  // stored blue, green, red
                    out[i * 3 + 1] = p[1];
                    out[i * 3 + 2] = p[0];
                }
                pixels(first + at, y, n, out);
            }
        }
    }
    return "";
 }
 namespace {
 struct GifWork {
    uint8_t palette[768];
    uint16_t prefix[4096];
    uint8_t suffix[4096], stack[4096];
 };
 }  // namespace
 std::string readGif(const ImageRead& read, uint32_t size, const ImagePixels& pixels) {
    Stream in(read, size);
    uint8_t head[13];
    if (!in.take(head, 13) || imageKindOfBytes(head, 6) != ImageKind::Gif) return "This GIF is damaged";
    int screenW = static_cast<int>(le16(head + 6)), screenH = static_cast<int>(le16(head + 8));
    std::unique_ptr<GifWork> work(new (std::nothrow) GifWork);
    if (!work) return "Not enough memory to show a GIF";
    std::memset(work->palette, 0, sizeof work->palette);
    if (head[10] & 0x80 && !in.take(work->palette, 3u << ((head[10] & 7) + 1))) return "This GIF is damaged";
    int transparent = -1;
    for (int guard = 0; guard < 100000; guard++) {
        int kind = in.get();
        if (kind == 0x21) {  // an extension: only the one before a picture matters, for its transparent colour
            int label = in.get();
            for (bool first = true;; first = false) {
                int len = in.get();
                if (len < 0) return "This GIF is damaged";
                if (len == 0) break;
                uint8_t block[255];
                if (!in.take(block, static_cast<size_t>(len))) return "This GIF is damaged";
                if (label == 0xF9 && first && len >= 4) transparent = (block[0] & 1) ? block[3] : -1;
            }
            continue;
        }
        if (kind != 0x2C) return kind == 0x3B ? "This GIF has no picture" : "This GIF is damaged";
        break;
    }
    uint8_t desc[9];
    if (!in.take(desc, 9)) return "This GIF is damaged";
    int left = static_cast<int>(le16(desc)), top = static_cast<int>(le16(desc + 2));
    int fw = static_cast<int>(le16(desc + 4)), fh = static_cast<int>(le16(desc + 6));
    bool interlaced = desc[8] & 0x40;
    if (desc[8] & 0x80 && !in.take(work->palette, 3u << ((desc[8] & 7) + 1))) return "This GIF is damaged";
    int minBits = in.get();
    if (fw <= 0 || fh <= 0 || minBits < 2 || minBits > 8) return "This GIF is damaged";
    // The pixels come out in the order they are stored; an interlaced picture stores every eighth
    // row first, then the rows between, in four passes.
    static const int kStart[4] = {0, 4, 2, 1}, kStep[4] = {8, 8, 4, 2};
    int px = 0, row = 0, pass = 0, rowsDone = 0;
    uint8_t run[64 * 3];
    int runLen = 0, runX = 0;
    auto flush = [&]() {
        int y = top + row;
        if (runLen && y >= 0 && y < screenH) pixels(left + runX, y, runLen, run);
        runLen = 0;
    };
    auto put = [&](uint8_t index) {
        if (rowsDone >= fh) return;
        int x = left + px;
        if (index == transparent || x < 0 || x >= screenW) {
            flush();
        } else {
            if (!runLen) runX = px;
            std::memcpy(run + runLen * 3, work->palette + index * 3, 3);
            if (++runLen == 64) flush();
        }
        if (++px < fw) return;
        flush();
        px = 0;
        rowsDone++;
        if (!interlaced) {
            row++;
            return;
        }
        row += kStep[pass];
        while (row >= fh && pass < 3) row = kStart[++pass];
    };
    const int clear = 1 << minBits, stop = clear + 1;
    int bits = minBits + 1, next = clear + 2, prev = -1, first = 0;
    uint32_t hold = 0;
    int held = 0, blockLeft = 0;
    bool ended = false;
    for (int i = 0; i < clear; i++) work->suffix[i] = static_cast<uint8_t>(i);
    while (rowsDone < fh && !ended) {
        while (held < bits) {
            if (!blockLeft) {
                blockLeft = in.get();
                if (blockLeft <= 0) {
                    ended = true;
                    break;
                }
            }
            int c = in.get();
            if (c < 0) return "This GIF is cut short";
            blockLeft--;
            hold |= static_cast<uint32_t>(c) << held;
            held += 8;
        }
        if (ended) break;
        int code = static_cast<int>(hold & ((1u << bits) - 1));
        hold >>= bits;
        held -= bits;
        if (code == clear) {
            bits = minBits + 1;
            next = clear + 2;
            prev = -1;
            continue;
        }
        if (code == stop) break;
        if (prev < 0) {
            if (code >= clear) return "This GIF is damaged";
            put(static_cast<uint8_t>(code));
            first = prev = code;
            continue;
        }
        if (code > next) return "This GIF is damaged";
        int sp = 0, walk = code;
        if (code == next) {  // the string being defined: the one before, and its own first pixel again
            work->stack[sp++] = static_cast<uint8_t>(first);
            walk = prev;
        }
        while (walk >= clear && sp < 4095) {
            work->stack[sp++] = work->suffix[walk];
            walk = work->prefix[walk];
        }
        if (walk >= clear) return "This GIF is damaged";
        first = walk;
        work->stack[sp++] = static_cast<uint8_t>(walk);
        if (next < 4096) {
            work->prefix[next] = static_cast<uint16_t>(prev);
            work->suffix[next] = static_cast<uint8_t>(first);
            next++;
            if (next == (1 << bits) && bits < 12) bits++;
        }
        prev = code;
        while (sp) put(work->stack[--sp]);
    }
    flush();
    return rowsDone ? "" : "This GIF is damaged";
 }
 }  // namespace roro::files
@@ -0,0 +1,86 @@
 #pragma once
 #include <cstddef>
 #include <cstdint>
 #include <functional>
 #include <string>
 // Pictures for the Storage App (issue #45, F1 Q233-Q242): what a file is and how big, where each
 // of its pixels goes on the screen, and the readers for BMP and the first frame of a GIF. PNG is in
 // png_reader.h; JPEG is decoded on the device by the display library's decoder.
 // Nothing here holds a picture: every reader hands its pixels on as it gets them.
 namespace roro::files {
 enum class ImageKind : uint8_t { None, Png, Jpeg, Bmp, Gif };
 // Reads up to `len` bytes at `offset`; returns how many it got.
 using ImageRead = std::function<size_t(uint32_t offset, uint8_t* into, size_t len)>;
 // `count` pixels of row `y` from column `x` on, three bytes each: red, green, blue.
 using ImagePixels = std::function<void(int x, int y, int count, const uint8_t* rgb)>;
 ImageKind imageKindOfName(const std::string& name);         // by its extension
 ImageKind imageKindOfBytes(const uint8_t* head, size_t len);  // by its first bytes (8 are enough)
 const char* imageKindName(ImageKind kind);
 struct ImageInfo {
    ImageKind kind = ImageKind::None;
    int width = 0, height = 0;
 };
 // "" and `out` filled, or why the file can't be shown.
 std::string imageInfo(const ImageRead& read, uint32_t size, ImageInfo& out);
 // A PNG the firmware's `screenshot` wrote (png_rgb332.h): its pixels are not compressed and each
 // is already a colour of the screen. Where the first row's pixels start, or 0 if it isn't one.
 // Row y's pixels are at that offset + y * (width + 1).
 uint32_t screenshotPixelsAt(const ImageRead& read, uint32_t size, int width, int height);
 // A colour as the screen has it (RRRGGGBB), dithered by where it lands: the screen has 8 levels of
 // red and green and 4 of blue, and a photograph bands without it. A colour the screen has exactly
 // comes out as itself wherever it lands, so a screenshot isn't touched.
 uint8_t rgb332Dithered(uint8_t r, uint8_t g, uint8_t b, int x, int y);
 // From a picture's pixels to the screen's.
 struct ImageMap {
    int viewX = 0, viewY = 0, viewW = 0, viewH = 0;  // the part of the screen the picture may use
    int offX = 0, offY = 0;                          // the picture's corner in it (negative: scrolled)
    uint32_t scale = 65536;                          // screen pixels for one of the picture's, 16.16; never over 1
    // Where the picture's pixel lands. False if it's outside the view, or if another pixel is the
    // one drawn there (shrunk, each screen pixel takes the first of the picture's that falls on it).
    bool at(int sx, int sy, int& tx, int& ty) const;
    bool rowUsed(int sy) const;  // does any pixel of this row land?
    bool below(int sy) const;    // this row and every one after it land under the view: nothing more to draw
 };
 // How a picture is looked at: whole, shrunk to fit if it has to be; or at its own size, a
 // screenful at a time.
 class ImageFrame {
   public:
    ImageFrame() = default;
    ImageFrame(int width, int height, int viewX, int viewY, int viewW, int viewH);
    bool bigger() const { return w_ > vw_ || h_ > vh_; }  // than the view: there is something to zoom
    bool actual() const { return actual_; }
    void toggle();
    bool pan(int dx, int dy);  // half a view a step, at its own size only; false: nothing moved
    int percent() const;       // of its own size, as shown
    int jpegShrink() const;    // 0 to 3: the halvings a JPEG decoder may do first, the picture still at least as big as shown
    // For pixels counted after `shrink` halvings (a JPEG's), or the picture's own.
    ImageMap map(int shrink = 0) const;
   private:
    uint32_t fitScale() const;
    int w_ = 0, h_ = 0, vx_ = 0, vy_ = 0, vw_ = 1, vh_ = 1, panX_ = 0, panY_ = 0;
    bool actual_ = false;
 };
 // A BMP: 8 bits with a palette, 24 or 32 bits, not compressed. `rowNeeded` lets rows be skipped
 // without being read. "" or why it can't be shown.
 std::string readBmp(const ImageRead& read, uint32_t size, const ImagePixels& pixels, const std::function<bool(int y)>& rowNeeded = nullptr);
 // The first picture of a GIF, interlaced or not; transparent pixels are not handed on. It needs
 // 17 KB while it runs. "" or why it can't be shown.
 std::string readGif(const ImageRead& read, uint32_t size, const ImagePixels& pixels);
 }  // namespace roro::files
@@ -0,0 +1,354 @@
 #include "png_reader.h"
 #include <algorithm>
 #include <cstring>
 #include <memory>
 #include <new>
 namespace roro::files {
 namespace {
 uint32_t be32(const uint8_t* p) { return (static_cast<uint32_t>(p[0]) << 24) | (p[1] << 16) | (p[2] << 8) | p[3]; }
 const char* const kDamaged = "This PNG is damaged";
 const char* const kCut = "This PNG is cut short";
 const char* const kNoMemory = "Not enough memory for this PNG";
 // A Huffman code as its lengths say: how many codes of each length, and the symbols in order.
 struct Huffman {
    uint16_t count[16];
    uint16_t symbol[288];
    // False if the lengths don't make a code.
    bool build(const uint8_t* lengths, int n) {
        std::memset(count, 0, sizeof count);
        for (int i = 0; i < n; i++) count[lengths[i]]++;
        int left = 1;
        for (int len = 1; len < 16; len++) {
            left = (left << 1) - count[len];
            if (left < 0) return false;
        }
        uint16_t offs[16];
        offs[1] = 0;
        for (int len = 1; len < 15; len++) offs[len + 1] = static_cast<uint16_t>(offs[len] + count[len]);
        for (int i = 0; i < n; i++)
            if (lengths[i]) symbol[offs[lengths[i]]++] = static_cast<uint16_t>(i);
        return true;
    }
 };
 // Everything one decoding holds, but the window and the two rows: on the heap, in one piece.
 struct Work {
    // The file, and the IDAT chunks as one stream of bytes.
    const ImageRead* read = nullptr;
    uint32_t size = 0, at = 0, chunkLeft = 0;
    uint8_t in[256];
    size_t inHave = 0, inAt = 0;
    bool inEnd = false;
    // Bits.
    uint32_t hold = 0;
    int held = 0;
    // The picture.
    int width = 0, height = 0, depth = 0, type = 0, channels = 0, bpp = 0;
    uint32_t rowBytes = 0;
    uint8_t palette[768], alpha[256];
    bool hasAlpha = false;
    // The window, the rows, and where the decoding is.
    std::unique_ptr<uint8_t[]> window, rows;
    uint32_t windowSize = 0, written = 0;
    uint8_t *cur = nullptr, *prev = nullptr;
    int64_t pos = -1;  // in the row; -1: its filter byte comes next
    int filter = 0, y = 0;
    bool stop = false;
    const char* problem = nullptr;
    const ImagePixels* pixels = nullptr;
    const std::function<bool(int)>* rowNeeded = nullptr;
    const std::function<bool(int)>* enough = nullptr;
    Huffman lengths, distances;
    uint8_t codeLengths[320];
    int byte() {
        if (inAt >= inHave) {
            while (!chunkLeft && !inEnd) {  // the next IDAT, past this one's checksum
                uint8_t head[12];
                if (at + 12 > size || (*read)(at, head, 12) != 12) return inEnd = true, -1;
                at += 4;  // the checksum
                if (std::memcmp(head + 8, "IDAT", 4) != 0) return inEnd = true, -1;
                chunkLeft = be32(head + 4);
                at += 8;
            }
            if (inEnd) return -1;
            size_t want = std::min<size_t>(sizeof in, chunkLeft);
            inHave = (*read)(at, in, want);
            inAt = 0;
            if (inHave != want) return inEnd = true, -1;
            at += static_cast<uint32_t>(want);
            chunkLeft -= static_cast<uint32_t>(want);
        }
        return in[inAt++];
    }
    int bits(int n) {  // -1: no more
        while (held < n) {
            int b = byte();
            if (b < 0) return -1;
            hold |= static_cast<uint32_t>(b) << held;
            held += 8;
        }
        int v = static_cast<int>(hold & ((1u << n) - 1));
        hold >>= n;
        held -= n;
        return v;
    }
    int decode(const Huffman& h) {  // -1: no more, or not a code
        int code = 0, first = 0, index = 0;
        for (int len = 1; len < 16; len++) {
            int b = bits(1);
            if (b < 0) return -1;
            code |= b;
            int n = h.count[len];
            if (code - n < first) return h.symbol[index + (code - first)];
            index += n;
            first += n;
            first <<= 1;
            code <<= 1;
        }
        return -1;
    }
    void row();
    // One byte out of the decompression: into the window, and into the row being rebuilt.
    void out(uint8_t b) {
        window[written++ & (windowSize - 1)] = b;
        if (pos < 0) {
            if (b > 4) {
                problem = kDamaged;
                stop = true;
            }
            filter = b;
            pos = 0;
            return;
        }
        uint32_t i = static_cast<uint32_t>(pos);
        int a = i >= static_cast<uint32_t>(bpp) ? cur[i - bpp] : 0, up = prev[i], c = i >= static_cast<uint32_t>(bpp) ? prev[i - bpp] : 0, add = 0;
        switch (filter) {
            case 1: add = a; break;
            case 2: add = up; break;
            case 3: add = (a + up) >> 1; break;
            case 4: {
                int p = a + up - c, pa = std::abs(p - a), pb = std::abs(p - up), pc = std::abs(p - c);
                add = pa <= pb && pa <= pc ? a : pb <= pc ? up : c;
                break;
            }
            default: break;
        }
        cur[i] = static_cast<uint8_t>(b + add);
        if (static_cast<uint32_t>(++pos) < rowBytes) return;
        if (!rowNeeded || !*rowNeeded || (*rowNeeded)(y)) row();
        std::swap(cur, prev);
        pos = -1;
        y++;
        if (y >= height || (enough && *enough && (*enough)(y))) stop = true;
    }
    bool inflate();
 };
 // The row as colours: runs of pixels, broken where one is transparent.
 void Work::row() {
    uint8_t run[64 * 3];
    int n = 0, from = 0;
    auto flush = [&]() {
        if (n) (*pixels)(from, y, n, run);
        n = 0;
    };
    int top = (1 << depth) - 1;
    for (int x = 0; x < width; x++) {
        uint8_t r, g, b, a = 255;
        auto sample = [&](int k) -> int {  // the k-th value of this pixel, as 8 bits; an index stays an index
            if (depth == 8) return cur[x * channels + k];
            if (depth == 16) return cur[(x * channels + k) * 2];
            int bit = x * depth, v = (cur[bit >> 3] >> (8 - depth - (bit & 7))) & top;
            return type == 3 ? v : v * 255 / top;
        };
        switch (type) {
            case 0: r = g = b = static_cast<uint8_t>(sample(0)); break;
            case 2: r = static_cast<uint8_t>(sample(0)), g = static_cast<uint8_t>(sample(1)), b = static_cast<uint8_t>(sample(2)); break;
            case 3: {
                int i = sample(0);
                r = palette[i * 3], g = palette[i * 3 + 1], b = palette[i * 3 + 2];
                if (hasAlpha) a = alpha[i];
                break;
            }
            case 4: r = g = b = static_cast<uint8_t>(sample(0)), a = static_cast<uint8_t>(sample(1)); break;
            default: r = static_cast<uint8_t>(sample(0)), g = static_cast<uint8_t>(sample(1)), b = static_cast<uint8_t>(sample(2)), a = static_cast<uint8_t>(sample(3)); break;
        }
        if (a < 128) {
            flush();
            continue;
        }
        if (!n) from = x;
        run[n * 3] = r, run[n * 3 + 1] = g, run[n * 3 + 2] = b;
        if (++n == 64) flush();
    }
    flush();
 }
 // Deflate (RFC 1951) inside a zlib stream (RFC 1950). False with `problem` set, or true when the
 // stream ended or enough rows were made.
 bool Work::inflate() {
    static const uint16_t kLenBase[29] = {3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 15, 17, 19, 23, 27, 31, 35, 43, 51, 59, 67, 83, 99, 115, 131, 163, 195, 227, 258};
    static const uint8_t kLenExtra[29] = {0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3, 3, 4, 4, 4, 4, 5, 5, 5, 5, 0};
    static const uint16_t kDistBase[30] = {1, 2, 3, 4, 5, 7, 9, 13, 17, 25, 33, 49, 65, 97, 129, 193, 257, 385, 513, 769, 1025, 1537, 2049, 3073, 4097, 6145, 8193, 12289, 16385, 24577};
    static const uint8_t kDistExtra[30] = {0, 0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 5, 6, 6, 7, 7, 8, 8, 9, 9, 10, 10, 11, 11, 12, 12, 13, 13};
    static const uint8_t kOrder[19] = {16, 17, 18, 0, 8, 7, 9, 6, 10, 5, 11, 4, 12, 3, 13, 2, 14, 1, 15};
    auto fail = [this](const char* what) {
        if (!problem) problem = what;
        return false;
    };
    for (bool last = false; !last && !stop;) {
        int head = bits(3);
        if (head < 0) return fail(kCut);
        last = head & 1;
        int kind = head >> 1;
        if (kind == 0) {  // stored
            hold = 0;
            held = 0;
            int a = byte(), b = byte(), c = byte(), d = byte();
            if (d < 0) return fail(kCut);
            int len = a | (b << 8);
            if (len != ((c | (d << 8)) ^ 0xFFFF)) return fail(kDamaged);
            for (int i = 0; i < len && !stop; i++) {
                int v = byte();
                if (v < 0) return fail(kCut);
                out(static_cast<uint8_t>(v));
            }
            continue;
        }
        if (kind == 3) return fail(kDamaged);
        if (kind == 1) {  // the code every decoder knows
            for (int i = 0; i < 288; i++) codeLengths[i] = i < 144 ? 8 : i < 256 ? 9 : i < 280 ? 7 : 8;
            lengths.build(codeLengths, 288);
            for (int i = 0; i < 30; i++) codeLengths[i] = 5;
            distances.build(codeLengths, 30);
        } else {  // a code of the block's own, itself sent coded
            int nlen = bits(5), ndist = bits(5), ncode = bits(4);
            if (ncode < 0) return fail(kCut);
            nlen += 257, ndist += 1, ncode += 4;
            if (nlen > 286 || ndist > 30) return fail(kDamaged);
            uint8_t first[19] = {0};
            for (int i = 0; i < ncode; i++) {
                int v = bits(3);
                if (v < 0) return fail(kCut);
                first[kOrder[i]] = static_cast<uint8_t>(v);
            }
            if (!lengths.build(first, 19)) return fail(kDamaged);
            for (int i = 0; i < nlen + ndist;) {
                int sym = decode(lengths);
                if (sym < 0) return fail(kDamaged);
                if (sym < 16) {
                    codeLengths[i++] = static_cast<uint8_t>(sym);
                    continue;
                }
                int repeat, value = 0;
                if (sym == 16) {
                    if (!i) return fail(kDamaged);
                    value = codeLengths[i - 1];
                    repeat = 3 + bits(2);
                } else if (sym == 17) {
                    repeat = 3 + bits(3);
                } else {
                    repeat = 11 + bits(7);
                }
                if (i + repeat > nlen + ndist) return fail(kDamaged);
                while (repeat--) codeLengths[i++] = static_cast<uint8_t>(value);
            }
            uint8_t dist[30];
            std::memcpy(dist, codeLengths + nlen, static_cast<size_t>(ndist));
            if (!lengths.build(codeLengths, nlen) || !distances.build(dist, ndist)) return fail(kDamaged);
        }
        while (!stop) {
            int sym = decode(lengths);
            if (sym < 0) return fail(inEnd ? kCut : kDamaged);
            if (sym < 256) {
                out(static_cast<uint8_t>(sym));
                continue;
            }
            if (sym == 256) break;
            sym -= 257;
            if (sym >= 29) return fail(kDamaged);
            int extra = bits(kLenExtra[sym]);
            int dsym = decode(distances);
            if (extra < 0 || dsym < 0 || dsym >= 30) return fail(inEnd ? kCut : kDamaged);
            int dextra = bits(kDistExtra[dsym]);
            if (dextra < 0) return fail(kCut);
            uint32_t len = static_cast<uint32_t>(kLenBase[sym] + extra), dist = static_cast<uint32_t>(kDistBase[dsym] + dextra);
            if (dist > written || dist > windowSize) return fail(kDamaged);
            for (uint32_t i = 0; i < len && !stop; i++) out(window[(written - dist) & (windowSize - 1)]);
        }
    }
    return true;
 }
 }  // namespace
 std::string readPng(const ImageRead& read, uint32_t size, const ImagePixels& pixels, const std::function<bool(int y)>& rowNeeded,
                    const std::function<bool(int y)>& enough) {
    static const uint8_t kSignature[] = {0x89, 'P', 'N', 'G', '\r', '\n', 0x1A, '\n'};
    uint8_t head[33];
    if (read(0, head, sizeof head) != sizeof head || std::memcmp(head, kSignature, 8) != 0 || std::memcmp(head + 12, "IHDR", 4) != 0) return kDamaged;
    std::unique_ptr<Work> w(new (std::nothrow) Work);
    if (!w) return kNoMemory;
    w->read = &read;
    w->size = size;
    w->pixels = &pixels;
    w->rowNeeded = &rowNeeded;
    w->enough = &enough;
    uint32_t width = be32(head + 16), height = be32(head + 20);
    w->depth = head[24];
    w->type = head[25];
    if (!width || !height || width > 16384 || height > 16384 || head[26] || head[27]) return kDamaged;
    if (head[28]) return "An interlaced PNG can't be shown";
    w->width = static_cast<int>(width);
    w->height = static_cast<int>(height);
    static const int8_t kChannels[7] = {1, 0, 3, 1, 2, 0, 4};
    int depth = w->depth, type = w->type;
    bool depthOk = depth == 8 || (depth == 16 && type != 3) || ((depth == 1 || depth == 2 || depth == 4) && (type == 0 || type == 3));
    if (type > 6 || !kChannels[type] || !depthOk) return "This kind of PNG can't be shown";
    w->channels = kChannels[type];
    w->bpp = std::max(1, w->channels * depth / 8);
    w->rowBytes = (width * static_cast<uint32_t>(w->channels * depth) + 7) / 8;
    std::memset(w->palette, 0, sizeof w->palette);
    std::memset(w->alpha, 255, sizeof w->alpha);
    // The chunks before the picture: the palette and its transparency.
    uint32_t at = 33;
    for (int guard = 0; guard < 1000; guard++) {
        uint8_t c[8];
        if (at + 8 > size || read(at, c, 8) != 8) return kCut;
        uint32_t len = be32(c);
        if (std::memcmp(c + 4, "IDAT", 4) == 0) break;
        if (std::memcmp(c + 4, "IEND", 4) == 0 || len > size) return kDamaged;
        if (std::memcmp(c + 4, "PLTE", 4) == 0 && read(at + 8, w->palette, std::min<size_t>(len, 768)) != std::min<size_t>(len, 768)) return kCut;
        if (std::memcmp(c + 4, "tRNS", 4) == 0 && type == 3) {
            if (read(at + 8, w->alpha, std::min<size_t>(len, 256)) != std::min<size_t>(len, 256)) return kCut;
            w->hasAlpha = true;
        }
        at += 12 + len;
    }
    w->at = at - 4;  // as if a chunk's checksum had just been reached: byte() steps over it to the IDAT
    // The zlib header says how far back the data refers: the window is that big and no bigger.
    int cmf = w->byte(), flg = w->byte();
    if (flg < 0) return kCut;
    if ((cmf & 0x0F) != 8 || (cmf >> 4) > 7 || ((cmf << 8) | flg) % 31 || (flg & 0x20)) return kDamaged;
    w->windowSize = 1u << ((cmf >> 4) + 8);
    w->window.reset(new (std::nothrow) uint8_t[w->windowSize]);
    w->rows.reset(new (std::nothrow) uint8_t[static_cast<size_t>(w->rowBytes) * 2]());
    if (!w->window || !w->rows) return kNoMemory;
    w->cur = w->rows.get();
    w->prev = w->rows.get() + w->rowBytes;
    if (enough && enough(0)) return "";
    if (!w->inflate()) return w->problem ? w->problem : kDamaged;
    if (w->problem) return w->problem;
    return w->stop ? "" : kCut;  // the data ended before the last row
 }
 }  // namespace roro::files
@@ -0,0 +1,20 @@
 #pragma once
 #include "image_file.h"
 namespace roro::files {
 // A PNG, decoded a row at a time (issue #45): every colour type and bit depth, not interlaced.
 // Pixels that are mostly transparent are not handed on. `rowNeeded` lets rows be left out (they
 // are still decoded: a row is stored as its difference from the one before); `enough` says that
 // from this row on nothing is wanted, and the decoding stops there.
 //
 // Memory while it runs: the window the file's compression refers back into (what its header asks
 // for, 32 KB at most), two rows of the picture, and about 3 KB. The display library's decoder
 // wanted 44 KB in one block, which this device often doesn't have.
 //
 // "" or why it can't be shown.
 std::string readPng(const ImageRead& read, uint32_t size, const ImagePixels& pixels, const std::function<bool(int y)>& rowNeeded = nullptr,
                    const std::function<bool(int y)>& enough = nullptr);
 }  // namespace roro::files
@@ -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
@@ -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
@@ -0,0 +1,135 @@
 #include "share_rules.h"
 #include <cstdio>
 namespace roro::files {
 namespace {
 int hexDigit(char c) {
    if (c >= '0' && c <= '9') return c - '0';
    if (c >= 'a' && c <= 'f') return c - 'a' + 10;
    if (c >= 'A' && c <= 'F') return c - 'A' + 10;
    return -1;
 }
 // Whatever the two strings hold, the time taken says nothing about where they differ.
 bool sameText(const std::string& a, const std::string& b) {
    unsigned diff = static_cast<unsigned>(a.size() ^ b.size());
    for (size_t i = 0; i < a.size() && i < b.size(); i++) diff |= static_cast<unsigned char>(a[i]) ^ static_cast<unsigned char>(b[i]);
    return diff == 0;
 }
 }  // namespace
 std::string urlDecode(const std::string& text) {
    std::string out;
    out.reserve(text.size());
    for (size_t i = 0; i < text.size(); i++) {
        int hi, lo;
        if (text[i] == '%' && i + 2 < text.size() + 0 && (hi = hexDigit(text[i + 1])) >= 0 && (lo = hexDigit(text[i + 2])) >= 0) {
            out += static_cast<char>(hi * 16 + lo);
            i += 2;
        } else {
            out += text[i];
        }
    }
    return out;
 }
 bool queryParam(const std::string& query, const std::string& key, std::string& out) {
    for (size_t at = 0; at <= query.size();) {
        size_t amp = query.find('&', at);
        if (amp == std::string::npos) amp = query.size();
        size_t eq = query.find('=', at);
        if (eq != std::string::npos && eq < amp && query.compare(at, eq - at, key) == 0) {
            out = urlDecode(query.substr(eq + 1, amp - eq - 1));
            return true;
        }
        at = amp + 1;
    }
    return false;
 }
 std::string cookieValue(const std::string& header, const std::string& name) {
    for (size_t at = 0; at < header.size();) {
        while (at < header.size() && (header[at] == ' ' || header[at] == ';')) at++;
        size_t end = header.find(';', at);
        if (end == std::string::npos) end = header.size();
        size_t eq = header.find('=', at);
        if (eq != std::string::npos && eq < end && header.compare(at, eq - at, name) == 0) return header.substr(eq + 1, end - eq - 1);
        at = end;
    }
    return "";
 }
 std::string checkSharePath(const std::string& path) {
    if (path.empty() || path[0] != '/') return "a path starts with /";
    if (path.size() > 255) return "that path is too long";
    if (path.size() > 1 && path.back() == '/') return "a path doesn't end with /";
    for (size_t at = 1; at < path.size();) {
        size_t end = path.find('/', at);
        if (end == std::string::npos) end = path.size();
        std::string part = path.substr(at, end - at);
        if (part.empty() || part == "." || part == "..") return "that isn't a path on the card";
        for (char c : part)
            if (static_cast<unsigned char>(c) < 0x20 || c == 0x7F || c == '\\' || c == ':' || c == '*' || c == '?' || c == '"' || c == '<' || c == '>' || c == '|')
                return "a name can't hold that character";
        at = end + 1;
    }
    return "";
 }
 std::string jsonString(const std::string& text) {
    std::string out = "\"";
    for (char c : text) {
        unsigned char u = static_cast<unsigned char>(c);
        if (c == '"' || c == '\\') {
            out += '\\';
            out += c;
        } else if (u < 0x20) {
            char buf[8];
            std::snprintf(buf, sizeof buf, "\\u%04x", u);
            out += buf;
        } else {
            out += c;
        }
    }
    return out + "\"";
 }
 ShareListing::ShareListing(const std::string& path) : out_("{\"path\":" + jsonString(path) + ",\"items\":[") {}
 void ShareListing::add(const std::string& name, uint32_t size, bool folder, int64_t modified) {
    if (count_++) out_ += ',';
    out_ += "{\"n\":" + jsonString(name) + ",\"s\":" + std::to_string(size) + ",\"d\":" + (folder ? "1" : "0") + ",\"t\":" + std::to_string(modified) + "}";
 }
 std::string ShareListing::json(bool more) { return out_ + "],\"more\":" + (more ? "true" : "false") + "}"; }
 void ShareAuth::begin(const uint8_t random[4]) {
    uint32_t n = (static_cast<uint32_t>(random[0]) << 24 | random[1] << 16 | random[2] << 8 | random[3]) % 1000000u;
    char buf[8];
    std::snprintf(buf, sizeof buf, "%06u", static_cast<unsigned>(n));
    code_ = buf;
    token_.clear();
    gate_ = debug::AuthGate();
 }
 ShareAuth::Result ShareAuth::login(const std::string& code, uint32_t nowMs, const uint8_t random[16], std::string& token) {
    if (code_.empty() || gate_.locked(nowMs)) return Result::Locked;
    std::string digits;
    for (char c : code)
        if (c >= '0' && c <= '9') digits += c;  // "123 456" is as good
    if (!sameText(digits, code_)) return gate_.failed(nowMs) ? Result::Locked : Result::Wrong;
    gate_.succeeded();
    static const char* const kHex = "0123456789abcdef";
    token_.clear();
    for (int i = 0; i < 16; i++) {
        token_ += kHex[random[i] >> 4];
        token_ += kHex[random[i] & 15];
    }
    token = token_;
    return Result::Ok;
 }
 bool ShareAuth::allowed(const std::string& token) const { return !token_.empty() && sameText(token, token_); }
 }  // namespace roro::files
@@ -0,0 +1,55 @@
 #pragma once
 #include <cstdint>
 #include <string>
 #include "debug_auth.h"
 // The parts of sharing files with a browser (issue #88) that need no network: what a request
 // asks for, whether it may, and the answers as JSON. The server itself is src/services/web_share.h.
 namespace roro::files {
 std::string urlDecode(const std::string& text);  // %41 is A; a + stays a +
 // The value of `key` in a query string ("path=%2Fnotes&replace=1"), decoded. False if it isn't there.
 bool queryParam(const std::string& query, const std::string& key, std::string& out);
 // The value of a cookie in a Cookie header ("a=1; s=abc"), or "".
 std::string cookieValue(const std::string& header, const std::string& name);
 // A path a browser may name: from the card's root, no "..", nothing a file name can't hold.
 // "" or why not.
 std::string checkSharePath(const std::string& path);
 std::string jsonString(const std::string& text);  // with its quotes
 // A folder's listing as the page wants it: {"path":"/notes","items":[{"n":"a.txt","s":12,"d":0,"t":1791400000}],"more":false}
 class ShareListing {
   public:
    explicit ShareListing(const std::string& path);
    void add(const std::string& name, uint32_t size, bool folder, int64_t modified);
    std::string json(bool more);
    size_t count() const { return count_; }
   private:
    std::string out_;
    size_t count_ = 0;
 };
 // Who may use the page: whoever typed the code the device's screen shows. The code is new each
 // time sharing starts; five wrong ones in a row close the door for a minute (as the Debug
 // Console's token does). A browser that got it right is given a token to send back as a cookie.
 // Nothing here is encrypted on the way: see the issue.
 class ShareAuth {
   public:
    enum class Result { Ok, Wrong, Locked };
    void begin(const uint8_t random[4]);  // a new code, and nobody is logged in
    const std::string& code() const { return code_; }  // six digits
    Result login(const std::string& code, uint32_t nowMs, const uint8_t random[16], std::string& token);
    bool allowed(const std::string& token) const;
   private:
    std::string code_, token_;
    debug::AuthGate gate_;
 };
 }  // namespace roro::files
@@ -0,0 +1,121 @@
 #include "text_pager.h"
 #include <algorithm>
 namespace roro::files {
 TextPager::TextPager(ReadAt read, uint32_t size, int cols, int rows)
    : read_(std::move(read)), size_(size), cols_(std::max(1, cols)), rows_(std::max(1, rows)) {}
 const uint8_t* TextPager::bytes(uint32_t at, size_t& len) {
    len = 0;
    if (at >= size_) return nullptr;
    bool cached = at >= cacheAt_ && at < cacheAt_ + cache_.size();
    // Wanted: a line's worth ahead, unless the cache already reaches the end of the file.
    size_t ahead = cached ? cacheAt_ + cache_.size() - at : 0;
    if (!cached || (ahead < kBlock / 4 && cacheAt_ + cache_.size() < size_)) {
        cacheAt_ = at - std::min<uint32_t>(at, kBlock / 2);  // room behind too: scrolling back is common
        cache_.resize(std::min<uint32_t>(kBlock, size_ - cacheAt_));
        cache_.resize(read_(cacheAt_, cache_.data(), cache_.size()));
        if (at >= cacheAt_ + cache_.size()) return nullptr;  // the file got shorter, or the card failed
    }
    len = cacheAt_ + cache_.size() - at;
    return cache_.data() + (at - cacheAt_);
 }
 int TextPager::byteAt(uint32_t at) {
    size_t len;
    const uint8_t* p = bytes(at, len);
    return p ? *p : -1;
 }
 uint32_t TextPager::nextLine(uint32_t at, std::string* text) {
    size_t len;
    const uint8_t* p = bytes(at, len);
    if (text) text->clear();
    if (!p) return size_;
    size_t end = len, next = len;  // the line is [0, end); the one after starts at `next`
    int count = 0;
    size_t lastSpace = 0;
    for (size_t i = 0; i < len; i++) {
        uint8_t b = p[i];
        if (b == '\n') {
            end = i;
            next = i + 1;
            break;
        }
        if ((b & 0xC0) == 0x80) continue;  // inside a UTF-8 character
        if (count == cols_) {              // one character too many: wrap
            if (b == ' ') end = i, next = i + 1;
            else if (lastSpace > 0) end = lastSpace, next = lastSpace + 1;
            else end = next = i;
            break;
        }
        count++;
        if (b == ' ') lastSpace = i;
    }
    if (text) {
        size_t n = end > 0 && p[end - 1] == '\r' ? end - 1 : end;
        text->reserve(n);
        for (size_t i = 0; i < n; i++) text->push_back(p[i] == '\t' ? ' ' : (p[i] < 0x20 || p[i] == 0x7F) ? '.' : static_cast<char>(p[i]));
    }
    return at + static_cast<uint32_t>(std::max<size_t>(next, 1));
 }
 uint32_t TextPager::lineBefore(uint32_t at) {
    if (at == 0) return 0;
    at = std::min(at, size_);
    // The paragraph the line before `at` belongs to starts after the newline before it. The byte
    // just before `at` may be that line's own newline.
    uint32_t from = at - 1;
    if (from > 0 && byteAt(from) == '\n') from--;
    uint32_t limit = at > kLookBack ? at - kLookBack : 0, start = limit;
    for (uint32_t i = from + 1; i-- > limit;) {
        if (byteAt(i) == '\n' && i < at - 1) {
            start = i + 1;
            break;
        }
    }
    // No newline that near: any character boundary will do as a place to wrap from.
    while (start > 0 && start < at && (byteAt(start) & 0xC0) == 0x80) start++;
    for (uint32_t a = start;;) {
        uint32_t next = nextLine(a, nullptr);
        if (next >= at) return a;
        a = next;
    }
 }
 bool TextPager::atEnd() {
    uint32_t a = top_;
    for (int i = 0; i < rows_; i++) {
        a = nextLine(a, nullptr);
        if (a >= size_) return true;
    }
    return false;
 }
 void TextPager::down(int n) {
    for (; n > 0 && !atEnd(); n--) top_ = nextLine(top_, nullptr);
 }
 void TextPager::up(int n) {
    for (; n > 0 && top_ > 0; n--) top_ = lineBefore(top_);
 }
 void TextPager::toEnd() {
    top_ = size_;
    up(rows_);
 }
 std::vector<std::string> TextPager::lines() {
    std::vector<std::string> out;
    uint32_t a = top_;
    for (int i = 0; i < rows_ && a < size_; i++) {
        std::string text;
        a = nextLine(a, &text);
        out.push_back(std::move(text));
    }
    return out;
 }
 }  // namespace roro::files
@@ -0,0 +1,50 @@
 #pragma once
 #include <cstddef>
 #include <cstdint>
 #include <functional>
 #include <string>
 #include <vector>
 namespace roro::files {
 // A text file of any size, shown a screen at a time (F1, Q134): only the part on screen is read,
 // through `read`, about a kilobyte at once. Lines wrap at spaces, `cols` characters wide. Going
 // back a line means finding where the paragraph before started and wrapping it again, so a file
 // reads the same whichever way it was scrolled.
 class TextPager {
   public:
    // Reads up to `len` bytes at `offset`; returns how many it got.
    using ReadAt = std::function<size_t(uint32_t offset, uint8_t* into, size_t len)>;
    TextPager(ReadAt read, uint32_t size, int cols, int rows);
    void toStart() { top_ = 0; }
    void toEnd();  // the last line at the bottom of the screen
    void down(int lines = 1);
    void up(int lines = 1);
    std::vector<std::string> lines();  // what's on screen: tabs as spaces, control characters as dots
    uint32_t top() const { return top_; }
    uint32_t size() const { return size_; }
    bool atEnd();  // the file's last line is on screen
    int percent() const { return size_ ? static_cast<int>(static_cast<uint64_t>(top_) * 100 / size_) : 0; }
   private:
    static constexpr size_t kBlock = 1024;       // read at once
    static constexpr uint32_t kLookBack = 1024;  // how far back a paragraph's start is looked for
    const uint8_t* bytes(uint32_t at, size_t& len);  // what's cached from `at` on
    int byteAt(uint32_t at);                         // -1 past the end
    uint32_t nextLine(uint32_t at, std::string* text);  // where the line after the one at `at` starts
    uint32_t lineBefore(uint32_t at);
    ReadAt read_;
    uint32_t size_;
    int cols_, rows_;
    uint32_t top_ = 0;
    std::vector<uint8_t> cache_;
    uint32_t cacheAt_ = 0;
 };
 }  // namespace roro::files
@@ -99,6 +99,27 @@ 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 'p':
            case 'P':
                if (keys.fn) {  // Fn+p: a screenshot, while typing too
                    out.push_back(KeyEvent::of(Key::Screenshot));
                    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;
@@ -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:
@@ -0,0 +1,97 @@
 #include "ipv4.h"
 #include <cstdio>
 namespace roro::net {
 bool parseIpv4(const std::string& text, uint32_t& out) {
    uint32_t value = 0;
    int parts = 0, digits = 0, part = 0;
    for (char c : text) {
        if (c >= '0' && c <= '9') {
            if (++digits > 3) return false;
            part = part * 10 + (c - '0');
            if (part > 255) return false;
        } else if (c == '.') {
            if (digits == 0 || ++parts > 3) return false;
            value = value << 8 | part;
            part = digits = 0;
        } else {
            return false;
        }
    }
    if (digits == 0 || parts != 3) return false;
    out = value << 8 | part;
    return true;
 }
 std::string formatIpv4(uint32_t a) {
    char s[16];
    std::snprintf(s, sizeof s, "%u.%u.%u.%u", static_cast<unsigned>(a >> 24), static_cast<unsigned>(a >> 16 & 255),
                  static_cast<unsigned>(a >> 8 & 255), static_cast<unsigned>(a & 255));
    return s;
 }
 uint32_t maskOf(int prefix) { return prefix <= 0 ? 0 : prefix >= 32 ? 0xFFFFFFFFu : ~0u << (32 - prefix); }
 std::string checkFixed(const FixedIp& f) {
    if (f.prefix < 1 || f.prefix > 30) return "The prefix must be 1 to 30";
    if (f.address == 0) return "0.0.0.0 isn't an address a device can have";
    uint32_t mask = maskOf(f.prefix), network = f.address & mask, broadcast = network | ~mask;
    if (f.address == network) return formatIpv4(f.address) + " is the network's own address";
    if (f.address == broadcast) return formatIpv4(f.address) + " is the broadcast address";
    if (f.gateway == 0) return "";
    if (f.gateway == f.address) return "The gateway can't be this device's address";
    if ((f.gateway & mask) != network)
        return "The gateway " + formatIpv4(f.gateway) + " isn't in " + formatIpv4(network) + "/" + std::to_string(f.prefix);
    if (f.gateway == broadcast) return "The gateway " + formatIpv4(f.gateway) + " is the broadcast address";
    if (f.gateway == network) return "The gateway " + formatIpv4(f.gateway) + " is the network's own address";
    return "";
 }
 std::string parseFixed(const std::string& text, FixedIp& out) {
    size_t slash = text.find('/');
    if (slash == std::string::npos) return "Write it as address/prefix, then the gateway if there is one";
    size_t space = text.find(' ', slash);
    std::string address = text.substr(0, slash);
    std::string prefix = text.substr(slash + 1, space == std::string::npos ? std::string::npos : space - slash - 1);
    std::string gateway = space == std::string::npos ? "" : text.substr(space + 1);
    FixedIp f;
    if (!parseIpv4(address, f.address)) return address + " isn't an IPv4 address";
    int p = 0;
    if (prefix.empty() || prefix.size() > 2) return "The prefix must be 1 to 30";
    for (char c : prefix) {
        if (c < '0' || c > '9') return "The prefix must be 1 to 30";
        p = p * 10 + (c - '0');
    }
    f.prefix = static_cast<uint8_t>(p);
    if (!gateway.empty() && !parseIpv4(gateway, f.gateway)) return gateway + " isn't an IPv4 address";
    std::string why = checkFixed(f);
    if (why.empty()) out = f;
    return why;
 }
 std::string formatFixed(const FixedIp& f) {
    std::string s = formatIpv4(f.address) + "/" + std::to_string(f.prefix);
    if (f.gateway) s += " " + formatIpv4(f.gateway);
    return s;
 }
 bool validHost(const std::string& text) {
    if (text.empty() || text.size() > 63) return false;
    uint32_t ignored;
    if (parseIpv4(text, ignored)) return true;
    bool allNumeric = true;  // digits and dots only, but not an address: "1.2.3", "999.1.1.1"
    char previous = '.';
    for (char c : text) {
        bool letter = (c >= 'a' && c <= 'z') || (c >= 'A' && c <= 'Z'), digit = c >= '0' && c <= '9';
        if (!letter && !digit && c != '-' && c != '.') return false;
        if (c == '.' && (previous == '.' || previous == '-')) return false;  // empty label, or one ending in '-'
        if (c == '-' && previous == '.') return false;                       // a label starting with '-'
        if (letter || c == '-') allNumeric = false;
        previous = c;
    }
    return previous != '.' && previous != '-' && !allNumeric;
 }
 }  // namespace roro::net
@@ -0,0 +1,30 @@
 #pragma once
 #include <cstdint>
 #include <string>
 namespace roro::net {
 // IPv4 addresses as 32-bit numbers, most significant byte first: 10.39.39.12 is 0x0A27270C.
 bool parseIpv4(const std::string& text, uint32_t& out);  // strict: four decimal numbers, 0 to 255
 std::string formatIpv4(uint32_t address);
 uint32_t maskOf(int prefix);  // 24 -> 255.255.255.0
 // A Saved Network's Fixed setting (S1, Q105 to Q107). gateway 0: none.
 struct FixedIp {
    uint32_t address = 0;
    uint8_t prefix = 24;
    uint32_t gateway = 0;
 };
 // "" when a device can use it, otherwise why not, for a human (Q111).
 std::string checkFixed(const FixedIp& f);
 // "address/prefix [gateway]", as typed on the console and kept in flash. parseFixed() also checks.
 std::string parseFixed(const std::string& text, FixedIp& out);
 std::string formatFixed(const FixedIp& f);
 // An IPv4 address or a host name, as an NTP server may be (Q110).
 bool validHost(const std::string& text);
 }  // namespace roro::net
@@ -0,0 +1,46 @@
 #include "traffic.h"
 #include <atomic>
 #include <cstdio>
 namespace roro::net {
 namespace {
 constexpr size_t kUsers = static_cast<size_t>(User::Count);
 std::atomic<uint32_t> in_[kUsers], out_[kUsers];
 }  // namespace
 const char* userName(User user) {
    switch (user) {
        case User::Irc: return "IRC";
        case User::Gemini: return "Gemini";
        case User::DebugConsole: return "Debug Console";
        case User::Updates: return "Updates";
        default: return "?";
    }
 }
 void received(User user, size_t bytes) { in_[static_cast<size_t>(user)] += static_cast<uint32_t>(bytes); }
 void sent(User user, size_t bytes) { out_[static_cast<size_t>(user)] += static_cast<uint32_t>(bytes); }
 Traffic traffic(User user) { return {in_[static_cast<size_t>(user)], out_[static_cast<size_t>(user)]}; }
 void resetTraffic() {
    for (size_t i = 0; i < kUsers; i++) in_[i] = out_[i] = 0;
 }
 uint32_t bytesPerSecond(uint32_t before, uint32_t now, uint32_t elapsedMs) {
    if (!elapsedMs) return 0;
    return static_cast<uint32_t>(static_cast<uint64_t>(now - before) * 1000 / elapsedMs);  // wraps with the counter
 }
 std::string formatTraffic(uint32_t bytes) {
    char s[16];
    if (bytes < 1000) std::snprintf(s, sizeof s, "%u B", static_cast<unsigned>(bytes));
    else if (bytes < 10 * 1024) std::snprintf(s, sizeof s, "%.1f KB", bytes / 1024.0);
    else if (bytes < 1000 * 1024) std::snprintf(s, sizeof s, "%u KB", static_cast<unsigned>(bytes / 1024));
    else if (bytes < 10u * 1024 * 1024) std::snprintf(s, sizeof s, "%.1f MB", bytes / 1048576.0);
    else std::snprintf(s, sizeof s, "%u MB", static_cast<unsigned>(bytes / 1048576));
    return s;
 }
 }  // namespace roro::net
@@ -0,0 +1,26 @@
 #pragma once
 #include <cstddef>
 #include <cstdint>
 #include <string>
 namespace roro::net {
 // Bytes each network service has read and written since boot (S1, Q121), as the service sees
 // them: for TLS connections that's the plain text, without the handshake or record overhead.
 // Counted from the services' own tasks, read from the main loop.
 enum class User : uint8_t { Irc, Gemini, DebugConsole, Updates, Count };
 const char* userName(User user);
 struct Traffic {
    uint32_t in = 0, out = 0;
 };
 void received(User user, size_t bytes);
 void sent(User user, size_t bytes);
 Traffic traffic(User user);
 void resetTraffic();  // for tests
 uint32_t bytesPerSecond(uint32_t before, uint32_t now, uint32_t elapsedMs);
 std::string formatTraffic(uint32_t bytes);  // "999 B", "1.5 KB", "12 KB", "1.7 MB"
 }  // namespace roro::net
@@ -0,0 +1,622 @@
 #include "note_document.h"
 #include <algorithm>
 #include <cstring>
 namespace roro::notes {
 namespace {
 // The side file: this line, the note's size and two checksums of it (its first and last
 // kilobyte), then, in any order, text that left a window and snapshots of the list of pieces.
 //   snapshot: "RSNP" cursor count { src at len }... crc32 length "PNSR"      (numbers: 32 bits, low byte first)
 // The newest snapshot that checks out is the note as it was last saved. kDone at the very end:
 // the rewrite this file was for is complete in `<note>.tmp`, and only has to take the note's place.
 const char kMagic[] = "roro9stack note edits 1\n";
 constexpr size_t kMagicLen = sizeof(kMagic) - 1;
 constexpr size_t kHeaderLen = kMagicLen + 12;
 const char kSnap[] = "RSNP", kSnapEnd[] = "PNSR", kDone[] = "RDONE1\n\n";
 constexpr size_t kDoneLen = 8;
 constexpr size_t kCheck = 1024;                 // of each end of the note, in the header
 constexpr uint32_t kStepBytes = 64 * 1024;      // a rewrite's step
 constexpr size_t kBlock = 4096;
 constexpr uint32_t kSeekNewline = 1024;
 constexpr size_t kMaxSnapshot = 12 + 9 * 4096 + 12;
 bool continuation(int c) { return (c & 0xC0) == 0x80; }
 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 k = 0; k < 8; k++) crc = (crc >> 1) ^ (0xEDB88320u & (0u - (crc & 1)));
    }
    return ~crc;
 }
 void put32(std::string& s, uint32_t v) {
    for (int i = 0; i < 4; i++) s += static_cast<char>((v >> (8 * i)) & 0xFF);
 }
 uint32_t get32(const uint8_t* p) { return p[0] | (p[1] << 8) | (p[2] << 16) | (static_cast<uint32_t>(p[3]) << 24); }
 const uint8_t* bytes(const std::string& s) { return reinterpret_cast<const uint8_t*>(s.data()); }
 }  // namespace
 NoteDocument::NoteDocument(NoteCard& card, int cols, int rows) : card_(card), text_(cols, rows) { openNew(); }
 void NoteDocument::reset() {
    path_.clear();
    sidePath_.clear();
    pieces_.clear();
    loaded_.clear();
    win_ = 0;
    windowLoaded_ = false;
    before_ = after_ = 0;
    droppedAtLoad_ = newlinesAtLoad_ = 0;
    flushedSinceSave_ = sidePending_ = false;
    sideSize_ = 0;
    windowSaved_.valid = false;
    rw_.active = false;
    std::vector<uint8_t>().swap(rw_.block);
 }
 void NoteDocument::openNew() {
    reset();
    text_.buffer().clear();
    text_.refilled(0, 0);
    windowLoaded_ = true;
    loadedRevision_ = savedRevision_ = text_.revision();
 }
 std::string NoteDocument::open(const std::string& path, std::string* told) {
    openNew();
    path_ = path;
    sidePath_ = side();
    uint32_t sideSize = 0, fileSize = 0, other = 0;
    bool hasSide = card_.size(sidePath_, sideSize);
    if (hasSide && sideIsDone(sideSize)) {  // a rewrite was cut after its last write: finish it
        if (card_.size(tmp(), other)) {
            if (card_.size(path_, fileSize)) card_.remove(path_);
            card_.rename(tmp(), path_);
        }
        card_.remove(sidePath_);
        hasSide = false;
    }
    if (!card_.size(path_, fileSize)) {
        card_.done();
        openNew();
        return "The card refused to open it";
    }
    if (fileSize > NoteText::kMaxBytes && card_.freeBytes() < static_cast<uint64_t>(fileSize) + 16 * 1024) {
        card_.done();
        openNew();
        return "Not enough room on the card: saving it needs a second copy";
    }
    uint32_t cursor = 0;
    bool resumed = false;
    if (hasSide) {
        if (card_.size(tmp(), other)) card_.remove(tmp());  // a rewrite that didn't get that far
        sideSize_ = sideSize;
        Resume r = resume(fileSize, cursor);
        if (r == Resume::Ok) {
            resumed = sidePending_ = true;
            if (told) *told = "Your unsaved changes are back";
        } else {
            sideSize_ = 0;
            pieces_.clear();
            if (r == Resume::Mismatch) {  // typed text is never thrown away without a word (Q227)
                std::string lost = sidePath_ + ".lost";
                card_.remove(lost);
                card_.rename(sidePath_, lost);
                if (told) *told = "The file changed: unsaved edits kept as .edit.lost";
            } else {
                card_.remove(sidePath_);
            }
        }
    }
    if (!resumed && fileSize) pieces_.push_back({0, 0, fileSize});
    windowLoaded_ = false;
    bool ok = load(cursor, cursor ? 1000 : 0, -1);  // an edit picked up: its last lines above the cursor
    card_.done();
    if (!ok) {
        openNew();
        return "The card refused to read it";
    }
    savedRevision_ = text_.revision();
    return "";
 }
 uint32_t NoteDocument::piecesBytes() const {
    uint32_t n = 0;
    for (const Piece& p : pieces_) n += p.len;
    return n;
 }
 int NoteDocument::percent() const {
    uint32_t all = size();
    return all ? static_cast<int>(static_cast<uint64_t>(before_ + text_.top()) * 100 / all) : 0;
 }
 size_t NoteDocument::readDoc(uint32_t at, uint8_t* into, size_t len) {
    size_t got = 0;
    uint32_t pos = 0;
    for (const Piece& p : pieces_) {
        if (got == len) break;
        if (at < pos + p.len) {
            uint32_t skip = at - pos;
            size_t n = std::min<size_t>(len - got, p.len - skip);
            size_t r = card_.read(fileOf(p), p.at + skip, into + got, n);
            got += r;
            at += static_cast<uint32_t>(r);
            if (r != n) break;
        }
        pos += p.len;
    }
    return got;
 }
 int NoteDocument::byteAt(uint32_t at) {
    uint8_t b;
    return readDoc(at, &b, 1) == 1 ? b : -1;
 }
 size_t NoteDocument::splitAt(uint32_t at) {
    uint32_t pos = 0;
    for (size_t i = 0; i < pieces_.size(); i++) {
        if (at == pos) return i;
        Piece& p = pieces_[i];
        if (at < pos + p.len) {
            uint32_t first = at - pos;
            Piece rest{p.src, p.at + first, p.len - first};
            p.len = first;
            pieces_.insert(pieces_.begin() + static_cast<long>(i) + 1, rest);
            return i + 1;
        }
        pos += p.len;
    }
    return pieces_.size();
 }
 void NoteDocument::merge() {
    size_t kept = 0;
    for (size_t i = 0; i < pieces_.size(); i++) {
        const Piece p = pieces_[i];
        if (!p.len) continue;
        if (kept && pieces_[kept - 1].src == p.src && pieces_[kept - 1].at + pieces_[kept - 1].len == p.at) pieces_[kept - 1].len += p.len;
        else pieces_[kept++] = p;
    }
    pieces_.resize(kept);
 }
 // The window dropped the CRs of the file's CRLFs when it was read. If it's put back untouched,
 // the cursor is further along in the file than in the window: by one for each line before it.
 uint32_t NoteDocument::noteCursor() const {
    size_t c = text_.cursor();
    if (windowLoaded_ && droppedAtLoad_ && text_.revision() == loadedRevision_) {
        const std::string& t = text_.text();
        if (droppedAtLoad_ == newlinesAtLoad_) c += static_cast<size_t>(std::count(t.begin(), t.begin() + static_cast<long>(c), '\n'));
        else if (!t.empty()) c += droppedAtLoad_ * c / t.size();  // a file of both kinds of line: near enough
    }
    return before_ + static_cast<uint32_t>(c);
 }
 bool NoteDocument::headerFor(std::string& header) {
    uint32_t fileSize = 0;
    if (path_.empty() || !card_.size(path_, fileSize)) return false;
    std::vector<uint8_t> buf(kCheck);
    size_t n = std::min<size_t>(kCheck, fileSize);
    if (card_.read(path_, 0, buf.data(), n) != n) return false;
    uint32_t head = crc32(0, buf.data(), n);
    if (card_.read(path_, fileSize - static_cast<uint32_t>(n), buf.data(), n) != n) return false;
    uint32_t tail = crc32(0, buf.data(), n);
    header.assign(kMagic, kMagicLen);
    put32(header, fileSize);
    put32(header, head);
    put32(header, tail);
    return true;
 }
 bool NoteDocument::ensureSide(std::string& why) {
    if (sideSize_) return true;
    std::string header;
    if (!headerFor(header)) {
        why = path_.empty() ? "the note has no file yet" : "the card refused to read the note";
        return false;
    }
    if (!card_.create(sidePath_) || !card_.append(sidePath_, bytes(header), header.size())) {
        card_.remove(sidePath_);
        why = "the card refused a write";
        return false;
    }
    sideSize_ = static_cast<uint32_t>(header.size());
    return true;
 }
 bool NoteDocument::putBack(std::string& why) {
    if (!windowLoaded_) return true;
    if (text_.revision() == loadedRevision_) {
        pieces_.insert(pieces_.begin() + static_cast<long>(win_), loaded_.begin(), loaded_.end());
    } else {
        Piece p{1, 0, static_cast<uint32_t>(text_.size())};
        if (windowSaved_.valid && windowSaved_.revision == text_.revision()) {
            p.at = windowSaved_.at;
        } else if (p.len) {
            if (!ensureSide(why)) return false;
            if (!card_.append(sidePath_, bytes(text_.text()), p.len)) {
                card_.done();
                if (!card_.size(sidePath_, sideSize_)) sideSize_ = 0;
                why = "the card refused a write";
                return false;
            }
            p.at = sideSize_;
            sideSize_ += p.len;
        }
        if (p.len) pieces_.insert(pieces_.begin() + static_cast<long>(win_), p);
        flushedSinceSave_ = sidePending_ = true;
    }
    windowLoaded_ = false;
    loaded_.clear();
    windowSaved_.valid = false;
    before_ = after_ = 0;
    merge();
    return true;
 }
 // The window's start is where a line starts on screen whenever that can be known: after a
 // newline, or where the window before had a line start. Otherwise the same text could wrap
 // differently from one window to the next.
 bool NoteDocument::load(uint32_t cursor, int row, int64_t startHint) {
    uint32_t total = piecesBytes();
    cursor = std::min(cursor, total);
    uint32_t s = 0, e = total;
    if (total > NoteText::kMaxBytes - kEdge) {
        uint32_t c = cursor > kHalf ? cursor - kHalf : 0;
        if (c == 0) {
            s = 0;
        } else if (startHint >= 0 && startHint <= static_cast<int64_t>(c)) {
            s = static_cast<uint32_t>(startHint);
        } else {
            uint8_t buf[128];
            uint32_t at = c, limit = std::min(c + kSeekNewline, cursor);
            bool found = false;
            while (at < limit && !found) {
                size_t n = readDoc(at, buf, std::min<size_t>(sizeof buf, limit - at));
                if (!n) break;
                for (size_t i = 0; i < n && !found; i++)
                    if (buf[i] == '\n') {
                        s = at + static_cast<uint32_t>(i) + 1;
                        found = true;
                    }
                at += static_cast<uint32_t>(n);
            }
            if (!found) {
                s = c;
                for (int k = 0; k < 3 && s < cursor && continuation(byteAt(s)); k++) s++;
            }
        }
        e = std::min(total, cursor + kHalf);
        for (int k = 0; k < 3 && e < total && continuation(byteAt(e)); k++) e++;
        if (e < total && e > 0 && byteAt(e) == '\n' && byteAt(e - 1) == '\r') e++;
        e = std::min<uint32_t>(e, s + NoteText::kMaxBytes);
    }
    size_t i0 = splitAt(s), i1 = splitAt(e);
    loaded_.assign(pieces_.begin() + static_cast<long>(i0), pieces_.begin() + static_cast<long>(i1));
    pieces_.erase(pieces_.begin() + static_cast<long>(i0), pieces_.begin() + static_cast<long>(i1));
    win_ = i0;
    before_ = s;
    after_ = total - e;
    std::string& b = text_.buffer();
    b.resize(e - s);
    size_t got = 0;
    bool ok = true;
    for (const Piece& p : loaded_) {
        size_t n = card_.read(fileOf(p), p.at, reinterpret_cast<uint8_t*>(&b[got]), p.len);
        got += n;
        if (n != p.len) {
            ok = false;
            break;
        }
    }
    if (!ok) {  // the note is whole in its pieces: stand on an empty window where the cursor was
        pieces_.insert(pieces_.begin() + static_cast<long>(i0), loaded_.begin(), loaded_.end());
        loaded_.clear();
        win_ = splitAt(cursor);
        before_ = cursor;
        after_ = total - cursor;
        s = cursor;
        b.clear();
    }
    droppedAtLoad_ = text_.refilled(cursor - s, row);
    newlinesAtLoad_ = static_cast<size_t>(std::count(b.begin(), b.end(), '\n'));
    loadedRevision_ = text_.revision();
    windowLoaded_ = true;
    windowSaved_.valid = false;
    return ok;
 }
 bool NoteDocument::wantsMove() const {
    if (!windowLoaded_) return true;
    size_t n = text_.size(), c = text_.cursor();
    if (n + kSpare >= NoteText::kMaxBytes) return true;
    if (before_ && c < kEdge) return true;
    return after_ && n - c < kEdge;
 }
 bool NoteDocument::move(std::string& why) {
    uint32_t cursor = noteCursor();
    int row = text_.cursorRow();
    int64_t hint = -1;
    if (windowLoaded_ && !droppedAtLoad_ && cursor > kHalf) {
        uint32_t c = cursor - kHalf;
        if (c >= before_ && c < before_ + text_.size()) hint = static_cast<int64_t>(before_) + static_cast<int64_t>(text_.startOfLine(c - before_));
    }
    if (!putBack(why)) return false;
    bool ok = load(cursor, row, hint);
    card_.done();
    if (!ok) why = "the card refused to read";
    return ok;
 }
 bool NoteDocument::jump(uint32_t to, std::string& why) {
    to = std::min(to, size());
    if (windowLoaded_ && to == 0 && !before_) return text_.toStart(), true;
    if (windowLoaded_ && to == size() && !after_) return text_.toEnd(), true;
    if (!putBack(why)) return false;
    bool ok = load(to, to ? 1000 : 0, -1);
    card_.done();
    if (!ok) why = "the card refused to read";
    return ok;
 }
 bool NoteDocument::wantsRewrite() const { return size() <= kWholeLimit || sideSize_ > kSideLimit || pieces_.size() > kManyPieces; }
 bool NoteDocument::journal(std::string& why) {
    if (path_.empty()) {
        why = "the note has no file yet";
        return false;
    }
    bool modified = text_.revision() != loadedRevision_;
    Piece w{1, 0, static_cast<uint32_t>(text_.size())};
    uint32_t cursor = noteCursor();
    if (!ensureSide(why)) return false;
    bool wrote = true;
    if (modified && w.len) {
        if (windowSaved_.valid && windowSaved_.revision == text_.revision()) {
            w.at = windowSaved_.at;
        } else if ((wrote = card_.append(sidePath_, bytes(text_.text()), w.len))) {
            w.at = sideSize_;
            sideSize_ += w.len;
            windowSaved_.valid = true;
            windowSaved_.at = w.at;
            windowSaved_.len = w.len;
            windowSaved_.revision = text_.revision();
        }
    }
    if (wrote) {
        std::vector<Piece> all(pieces_.begin(), pieces_.begin() + static_cast<long>(win_));
        if (!modified) all.insert(all.end(), loaded_.begin(), loaded_.end());
        else if (w.len) all.push_back(w);
        all.insert(all.end(), pieces_.begin() + static_cast<long>(win_), pieces_.end());
        std::string rec(kSnap, 4);
        put32(rec, cursor);
        put32(rec, static_cast<uint32_t>(all.size()));
        for (const Piece& p : all) {
            rec += static_cast<char>(p.src);
            put32(rec, p.at);
            put32(rec, p.len);
        }
        put32(rec, crc32(0, bytes(rec), rec.size()));
        put32(rec, static_cast<uint32_t>(rec.size()) + 8);
        rec.append(kSnapEnd, 4);
        wrote = card_.append(sidePath_, bytes(rec), rec.size());
        if (wrote) sideSize_ += static_cast<uint32_t>(rec.size());
    }
    card_.done();
    if (!wrote) {
        windowSaved_.valid = false;
        if (!card_.size(sidePath_, sideSize_)) sideSize_ = 0;
        why = "the card refused a write";
        return false;
    }
    savedRevision_ = text_.revision();
    flushedSinceSave_ = false;
    sidePending_ = true;
    return true;
 }
 bool NoteDocument::rewriteStart(std::string& why) {
    if (path_.empty()) {
        why = "the note has no file yet";
        return false;
    }
    if (card_.freeBytes() < static_cast<uint64_t>(size()) + 16 * 1024) {
        why = "the card is full";
        return false;
    }
    if (!card_.create(tmp())) {
        why = "the card refused to open a file";
        return false;
    }
    rw_.active = true;
    rw_.stage = 0;
    rw_.index = 0;
    rw_.offset = rw_.done = rw_.wrote = rw_.wroteBefore = rw_.wroteAfter = 0;
    rw_.total = size();
    rw_.revision = text_.revision();
    rw_.carry = false;
    rw_.block.resize(kBlock);
    return true;
 }
 int NoteDocument::rewriteStep(std::string& why) {
    if (!rw_.active) return -1;
    auto failed = [&](const char* what) {
        card_.done();
        card_.remove(tmp());
        rw_.active = false;
        std::vector<uint8_t>().swap(rw_.block);
        why = what;
        return -1;
    };
    auto out = [&](const uint8_t* data, size_t len) {
        if (!len) return true;
        if (!card_.append(tmp(), data, len)) return false;
        rw_.wrote += static_cast<uint32_t>(len);
        if (rw_.stage == 0) rw_.wroteBefore += static_cast<uint32_t>(len);
        if (rw_.stage == 2) rw_.wroteAfter += static_cast<uint32_t>(len);
        return true;
    };
    const uint8_t cr = '\r';
    uint32_t budget = kStepBytes;
    while (budget > 0 && rw_.stage < 3) {
        if (rw_.stage == 1) {
            uint32_t left = static_cast<uint32_t>(text_.size()) - rw_.offset;
            if (!left) {
                rw_.stage = 2;
                rw_.index = win_;
                rw_.offset = 0;
                continue;
            }
            uint32_t n = std::min(left, budget);
            if (!out(bytes(text_.text()) + rw_.offset, n)) return failed("the card refused a write");
            rw_.offset += n;
            rw_.done += n;
            budget -= n;
            continue;
        }
        size_t end = rw_.stage == 0 ? win_ : pieces_.size();
        bool pieceOver = rw_.index < end && rw_.offset >= pieces_[rw_.index].len;
        if (rw_.index >= end || pieceOver) {
            if (rw_.carry && !out(&cr, 1)) return failed("the card refused a write");  // a CR that ended its piece stays
            rw_.carry = false;
            rw_.offset = 0;
            if (pieceOver) rw_.index++;
            else rw_.stage++;
            continue;
        }
        const Piece& p = pieces_[rw_.index];
        uint32_t n = std::min<uint32_t>(std::min<uint32_t>(p.len - rw_.offset, budget), static_cast<uint32_t>(rw_.block.size()));
        uint8_t* b = rw_.block.data();
        if (card_.read(fileOf(p), p.at + rw_.offset, b, n) != n) return failed("the card refused to read the note");
        size_t m = n;
        if (p.src == 0) {  // CRLF becomes LF (Q148, Q230), in the file's own text: what was typed has none
            if (rw_.carry && b[0] != '\n' && !out(&cr, 1)) return failed("the card refused a write");
            rw_.carry = false;
            m = 0;
            for (uint32_t i = 0; i < n; i++) {
                if (b[i] == '\r') {
                    if (i + 1 == n) {
                        rw_.carry = true;
                        continue;
                    }
                    if (b[i + 1] == '\n') continue;
                }
                b[m++] = b[i];
            }
        }
        if (!out(b, m)) return failed("the card refused a write");
        rw_.offset += n;
        rw_.done += n;
        budget -= n;
    }
    if (rw_.stage < 3) return std::min(99, static_cast<int>(static_cast<uint64_t>(rw_.done) * 100 / std::max<uint32_t>(1, rw_.total)));
    // All of it is in the temporary file. From the mark in the side file on, the rewrite counts as
    // done: whatever is cut after that, opening the note finishes it.
    card_.done();
    uint32_t written = 0, old = 0;
    if (!card_.size(tmp(), written) || written != rw_.wrote) return failed("the card refused a write");
    if (sideSize_) {
        if (!card_.append(sidePath_, reinterpret_cast<const uint8_t*>(kDone), kDoneLen)) return failed("the card refused a write");
        sideSize_ += kDoneLen;
        card_.done();
    }
    rw_.active = false;
    std::vector<uint8_t>().swap(rw_.block);
    // FAT can't rename onto a file. Between these two lines only the temporary file exists: the
    // Notes list puts such a file back under its name.
    if ((card_.size(path_, old) && !card_.remove(path_)) || !card_.rename(tmp(), path_)) {
        card_.done();
        why = "the card refused to replace the note";
        return -1;
    }
    if (sideSize_) card_.remove(sidePath_);
    card_.done();
    sideSize_ = 0;
    uint32_t window = static_cast<uint32_t>(text_.size());
    pieces_.clear();
    loaded_.clear();
    if (rw_.wroteBefore) pieces_.push_back({0, 0, rw_.wroteBefore});
    win_ = pieces_.size();
    if (rw_.wroteAfter) pieces_.push_back({0, rw_.wroteBefore + window, rw_.wroteAfter});
    if (window) loaded_.push_back({0, rw_.wroteBefore, window});
    before_ = rw_.wroteBefore;
    after_ = rw_.wroteAfter;
    loadedRevision_ = savedRevision_ = rw_.revision;
    droppedAtLoad_ = 0;
    windowLoaded_ = true;
    flushedSinceSave_ = sidePending_ = false;
    windowSaved_.valid = false;
    return 100;
 }
 bool NoteDocument::sideIsDone(uint32_t sideSize) {
    uint8_t tail[kDoneLen];
    return sideSize >= kHeaderLen + kDoneLen && card_.read(sidePath_, sideSize - kDoneLen, tail, kDoneLen) == kDoneLen &&
           std::memcmp(tail, kDone, kDoneLen) == 0;
 }
 NoteDocument::Resume NoteDocument::resume(uint32_t fileSize, uint32_t& cursor) {
    uint8_t header[kHeaderLen];
    if (sideSize_ < kHeaderLen || card_.read(sidePath_, 0, header, kHeaderLen) != kHeaderLen || std::memcmp(header, kMagic, kMagicLen) != 0)
        return Resume::Nothing;
    // The newest snapshot that checks out, looking back from the end: after it there may be text
    // that left a window, or a write the power cut short.
    auto snapshotEndingAt = [&](uint32_t end) {
        uint8_t lenBytes[4];
        if (end < kHeaderLen + 24 || card_.read(sidePath_, end - 8, lenBytes, 4) != 4) return false;
        uint32_t len = get32(lenBytes);
        if (len < 24 || len > kMaxSnapshot || len > end - kHeaderLen || (len - 24) % 9) return false;
        std::string rec(len, '\0');
        if (card_.read(sidePath_, end - len, reinterpret_cast<uint8_t*>(&rec[0]), len) != len) return false;
        const uint8_t* r = bytes(rec);
        if (std::memcmp(r, kSnap, 4) != 0 || get32(r + len - 12) != crc32(0, r, len - 12)) return false;
        uint32_t count = get32(r + 8);
        if (count != (len - 24) / 9) return false;
        std::vector<Piece> list;
        list.reserve(count);
        for (uint32_t i = 0; i < count; i++) {
            const uint8_t* q = r + 12 + 9 * i;
            Piece p{q[0], get32(q + 1), get32(q + 5)};
            uint64_t stop = static_cast<uint64_t>(p.at) + p.len;
            if (p.src > 1 || !p.len) return false;
            if (p.src == 1 && (p.at < kHeaderLen || stop > end - len)) return false;
            list.push_back(p);
        }
        pieces_.swap(list);
        cursor = get32(r + 4);
        return true;
    };
    bool found = false;
    std::vector<uint8_t> buf(1024 + 3);
    for (uint32_t end = sideSize_; end > kHeaderLen && !found;) {
        uint32_t a = end > 1024 + kHeaderLen ? end - 1024 : static_cast<uint32_t>(kHeaderLen);
        size_t n = card_.read(sidePath_, a, buf.data(), std::min<size_t>(buf.size(), sideSize_ - a));
        for (size_t i = n >= 4 ? n - 4 + 1 : 0; i-- > 0 && !found;)
            if (std::memcmp(buf.data() + i, kSnapEnd, 4) == 0) found = snapshotEndingAt(a + static_cast<uint32_t>(i) + 4);
        end = a;
    }
    if (!found) return Resume::Nothing;
    std::string expect;
    if (!headerFor(expect) || std::memcmp(header, expect.data(), kHeaderLen) != 0) {
        pieces_.clear();
        return Resume::Mismatch;
    }
    for (const Piece& p : pieces_)
        if (p.src == 0 && static_cast<uint64_t>(p.at) + p.len > fileSize) return pieces_.clear(), Resume::Mismatch;
    merge();
    return Resume::Ok;
 }
 }  // namespace roro::notes
@@ -0,0 +1,130 @@
 #pragma once
 #include <cstddef>
 #include <cstdint>
 #include <string>
 #include <vector>
 #include "note_text.h"
 namespace roro::notes {
 // The card, as a note needs it. On the device every call is made on the storage task.
 class NoteCard {
   public:
    virtual ~NoteCard() = default;
    virtual bool size(const std::string& path, uint32_t& size) = 0;  // false: no such file
    virtual size_t read(const std::string& path, uint32_t at, uint8_t* into, size_t len) = 0;
    virtual bool create(const std::string& path) = 0;  // an empty file, in place of what was there
    virtual bool append(const std::string& path, const uint8_t* data, size_t len) = 0;
    virtual bool remove(const std::string& path) = 0;
    virtual bool rename(const std::string& from, const std::string& to) = 0;
    virtual uint64_t freeBytes() = 0;
    virtual void done() {}  // what was appended is on the card now (files kept open are closed)
 };
 // A text file of any size, edited (issue #47, F1 Q223-Q232). The file stays on the card; what is
 // in memory is one window of it, a NoteText of up to 16 KB around the cursor, and a list of pieces
 // saying what the rest is made of: runs of bytes of the file, and runs of the side file
 // `<note>.edit`, where a window that was changed is written when the cursor leaves it.
 //
 //   the note = pieces before the window + the window + pieces after it
 //
 // Saving comes in two kinds. `journal` appends the window and the list of pieces to the side
 // file: quick whatever the note's size, and enough to pick the edit up after a power cut.
 // `rewrite` streams the whole note into `<note>.tmp` and puts it in the note's place: the file is
 // then the note again, and the side file goes. A note of up to 64 KB is always rewritten.
 //
 // Every method marked [card] reads or writes the card.
 class NoteDocument {
   public:
    static constexpr uint32_t kHalf = 4096;            // loaded on each side of the cursor
    static constexpr uint32_t kEdge = 2048;            // this near an end of the window, it moves
    static constexpr uint32_t kSpare = 256;            // this near full, it moves
    static constexpr uint32_t kWholeLimit = 64 * 1024; // up to here a save is a rewrite
    static constexpr uint32_t kSideLimit = 1024 * 1024;  // a side file this big asks for a rewrite
    static constexpr size_t kManyPieces = 256;         // and so does a list this long
    NoteDocument(NoteCard& card, int cols, int rows);
    // [card] "" or why not. `told`: something the user should read (an edit picked up, or set aside).
    std::string open(const std::string& path, std::string* told = nullptr);
    void openNew();  // nothing on the card until the first rewrite
    const std::string& path() const { return path_; }
    void setPath(const std::string& path) {  // a new note's, before its first rewrite
        path_ = path;
        sidePath_ = path.empty() ? "" : side();
    }
    NoteText& text() { return text_; }
    const NoteText& text() const { return text_; }
    uint32_t size() const { return before_ + static_cast<uint32_t>(text_.size()) + after_; }
    uint32_t cursor() const { return before_ + static_cast<uint32_t>(text_.cursor()); }  // in the note
    int percent() const;
    bool windowed() const { return before_ || after_; }  // the note is more than its window
    // After each key: the cursor is near an end of the window that isn't an end of the note, or
    // the window is nearly full.
    bool wantsMove() const;
    bool move(std::string& why);                  // [card] the window, around the cursor
    bool jump(uint32_t to, std::string& why);     // [card] the cursor, anywhere in the note
    bool dirty() const { return text_.revision() != savedRevision_ || flushedSinceSave_; }  // the card doesn't have it
    bool filePending() const { return sidePending_; }  // saved, but in the side file: a rewrite is owed
    bool wantsRewrite() const;                         // the next save should be a rewrite
    bool journal(std::string& why);                    // [card]
    bool rewriteStart(std::string& why);               // [card]
    int rewriteStep(std::string& why);                 // [card] percent done; 100: the file is the note; -1: failed
    bool rewriting() const { return rw_.active; }
   private:
    struct Piece {
        uint8_t src;  // 0: the note's file, 1: the side file
        uint32_t at, len;
    };
    enum class Resume { Ok, Mismatch, Nothing };
    std::string side() const { return path_ + ".edit"; }
    std::string tmp() const { return path_ + ".tmp"; }
    const std::string& fileOf(const Piece& p) const { return p.src ? sidePath_ : path_; }
    uint32_t piecesBytes() const;
    size_t readDoc(uint32_t at, uint8_t* into, size_t len);  // from the pieces: the window is put back first
    int byteAt(uint32_t at);
    size_t splitAt(uint32_t at);  // the index of the piece that starts there
    void merge();
    uint32_t noteCursor() const;  // where the cursor is among the pieces once the window is put back
    bool putBack(std::string& why);
    bool load(uint32_t cursor, int row, int64_t startHint);  // false: the card refused, and the window is empty
    bool ensureSide(std::string& why);
    bool headerFor(std::string& header);
    Resume resume(uint32_t fileSize, uint32_t& cursor);
    bool sideIsDone(uint32_t sideSize);
    void reset();
    NoteCard& card_;
    NoteText text_;
    std::string path_, sidePath_;
    std::vector<Piece> pieces_;  // without the window while it's loaded
    std::vector<Piece> loaded_;  // what the window was read from
    size_t win_ = 0;             // the window sits before pieces_[win_]
    bool windowLoaded_ = false;
    uint32_t before_ = 0, after_ = 0;
    uint32_t loadedRevision_ = 0, savedRevision_ = 0;
    size_t droppedAtLoad_ = 0, newlinesAtLoad_ = 0;
    bool flushedSinceSave_ = false, sidePending_ = false;
    uint32_t sideSize_ = 0;  // 0: no side file
    struct {
        bool valid = false;
        uint32_t at = 0, len = 0, revision = 0;
    } windowSaved_;  // the window as the side file already has it
    struct {
        bool active = false;
        int stage = 0;  // 0: pieces before, 1: the window, 2: pieces after
        size_t index = 0;
        uint32_t offset = 0, done = 0, total = 0, wrote = 0, wroteBefore = 0, wroteAfter = 0, revision = 0;
        bool carry = false;  // a CR at the end of a block, waiting to see what follows
        std::vector<uint8_t> block;
    } rw_;
 };
 }  // namespace roro::notes
@@ -0,0 +1,342 @@
 #include "note_text.h"
 #include <algorithm>
 namespace roro::notes {
 namespace {
 bool continuation(char c) { return (static_cast<uint8_t>(c) & 0xC0) == 0x80; }
 }  // namespace
 NoteText::NoteText(int cols, int rows) : cols_(std::max(1, cols)), rows_(std::max(1, rows)) { text_.reserve(kMaxBytes); }
 NoteText::NoteText(int cols, int rows, std::string&& text) : cols_(std::max(1, cols)), rows_(std::max(1, rows)), text_(std::move(text)) {
    dropCarriageReturns();
    if (text_.size() > kMaxBytes) text_.resize(kMaxBytes);  // the caller checks sizes: not reached
    text_.reserve(kMaxBytes);
 }
 size_t NoteText::dropCarriageReturns(size_t* follow) {
    size_t kept = 0, size = text_.size(), place = follow ? *follow : 0;
    for (size_t i = 0; i < size; i++) {
        if (follow && i == place) *follow = kept;
        if (!(text_[i] == '\r' && i + 1 < size && text_[i + 1] == '\n')) text_[kept++] = text_[i];
    }
    if (follow && place >= size) *follow = kept;
    text_.resize(kept);
    return size - kept;
 }
 size_t NoteText::refilled(size_t cursor, int row) {
    size_t dropped = dropCarriageReturns(&cursor);
    cursor_ = std::min(cursor, text_.size());
    while (cursor_ > 0 && cursor_ < text_.size() && continuation(text_[cursor_])) cursor_--;
    top_ = lineOf(cursor_);
    for (int i = 0; i < row && top_ > 0; i++) top_ = lineOf(top_ - 1);
    return dropped;
 }
 bool NoteText::setText(const std::string& text) {
    size_t kept = text.size();
    for (size_t i = 0; i + 1 < text.size(); i++)
        if (text[i] == '\r' && text[i + 1] == '\n') kept--;
    if (kept > kMaxBytes) return false;
    text_.assign(text);
    dropCarriageReturns();
    cursor_ = top_ = 0;
    goal_ = -1;
    revision_++;
    return true;
 }
 size_t NoteText::nextLine(size_t start) const {
    size_t size = text_.size();
    int count = 0;
    size_t lastSpace = 0;
    bool space = false;
    for (size_t i = start; i < size; i++) {
        char c = text_[i];
        if (c == '\n') return i + 1;
        if (continuation(c)) continue;
        if (count == cols_) {  // one character too many: wrap
            if (c == ' ') return i + 1;       // the space stays at the end of this line
            if (space) return lastSpace + 1;  // after the last space that fits
            return i;                         // a word longer than the screen is cut
        }
        count++;
        if (c == ' ') {
            lastSpace = i;
            space = true;
        }
    }
    return size;
 }
 size_t NoteText::lineOf(size_t pos) const {
    size_t size = text_.size();
    pos = std::min(pos, size);
    size_t a = pos;  // the start of the paragraph: after the newline before `pos`
    while (a > 0 && text_[a - 1] != '\n') a--;
    while (a < size) {
        size_t n = nextLine(a);
        if (n > pos) return a;
        // The end of the text is on the last line, unless that line ended with a newline: then
        // it's on an empty line of its own.
        if (n == size && pos == size && text_[size - 1] != '\n') return a;
        a = n;
    }
    return a;
 }
 bool NoteText::hasLineAfter(size_t start) const {
    size_t n = nextLine(start), size = text_.size();
    if (n < size) return true;
    return start < size && lineOf(size) != start;  // the empty line after a final newline
 }
 size_t NoteText::lastSpot(size_t start) const {
    size_t n = nextLine(start), size = text_.size();
    if (n == start) return start;  // the empty line at the end
    if (n == size && lineOf(size) == start) return size;
    size_t p = n - 1;  // before the newline, the space or the last character the line ends with
    while (p > start && continuation(text_[p])) p--;
    return p;
 }
 int NoteText::columnOf(size_t start, size_t pos) const {
    int col = 0;
    for (size_t i = start; i < pos && i < text_.size(); i++)
        if (!continuation(text_[i])) col++;
    return col;
 }
 size_t NoteText::atColumn(size_t start, int col) const {
    size_t last = lastSpot(start), p = start;
    while (p < last && col > 0) {
        p++;
        while (p < last && continuation(text_[p])) p++;
        col--;
    }
    return p;
 }
 void NoteText::moved(bool keepGoal) {
    if (!keepGoal) goal_ = -1;
 }
 bool NoteText::insertText(const std::string& s) {
    if (text_.size() + s.size() > kMaxBytes) return false;
    text_.insert(cursor_, s);
    cursor_ += s.size();
    revision_++;
    moved();
    return true;
 }
 bool NoteText::insert(uint32_t cp) {
    std::string s;
    if (cp < 0x80) s += static_cast<char>(cp);
    else if (cp < 0x800) {
        s += static_cast<char>(0xC0 | (cp >> 6));
        s += static_cast<char>(0x80 | (cp & 0x3F));
    } else if (cp < 0x10000) {
        s += static_cast<char>(0xE0 | (cp >> 12));
        s += static_cast<char>(0x80 | ((cp >> 6) & 0x3F));
        s += static_cast<char>(0x80 | (cp & 0x3F));
    } else {
        s += static_cast<char>(0xF0 | (cp >> 18));
        s += static_cast<char>(0x80 | ((cp >> 12) & 0x3F));
        s += static_cast<char>(0x80 | ((cp >> 6) & 0x3F));
        s += static_cast<char>(0x80 | (cp & 0x3F));
    }
    return insertText(s);
 }
 void NoteText::backspace() {
    if (cursor_ == 0) return;
    size_t from = cursor_ - 1;
    while (from > 0 && continuation(text_[from])) from--;
    text_.erase(from, cursor_ - from);
    cursor_ = from;
    revision_++;
    moved();
 }
 void NoteText::left() {
    if (cursor_ == 0) return;
    cursor_--;
    while (cursor_ > 0 && continuation(text_[cursor_])) cursor_--;
    moved();
 }
 void NoteText::right() {
    if (cursor_ >= text_.size()) return;
    cursor_++;
    while (cursor_ < text_.size() && continuation(text_[cursor_])) cursor_++;
    moved();
 }
 void NoteText::up() {
    size_t line = lineOf(cursor_);
    if (goal_ < 0) goal_ = columnOf(line, cursor_);
    if (line == 0) return;
    cursor_ = atColumn(lineOf(line - 1), goal_);
    moved(true);
 }
 void NoteText::down() {
    size_t line = lineOf(cursor_);
    if (goal_ < 0) goal_ = columnOf(line, cursor_);
    if (!hasLineAfter(line)) return;
    size_t next = nextLine(line);
    cursor_ = next >= text_.size() ? text_.size() : atColumn(next, goal_);
    moved(true);
 }
 void NoteText::pageUp() {
    for (int i = 1; i < rows_; i++) up();
 }
 void NoteText::pageDown() {
    for (int i = 1; i < rows_; i++) down();
 }
 void NoteText::lineStart() {
    cursor_ = lineOf(cursor_);
    moved();
 }
 void NoteText::lineEnd() {
    cursor_ = lastSpot(lineOf(cursor_));
    moved();
 }
 void NoteText::toStart() {
    cursor_ = 0;
    moved();
 }
 void NoteText::toEnd() {
    cursor_ = text_.size();
    moved();
 }
 void NoteText::follow() {
    size_t line = lineOf(cursor_);
    top_ = lineOf(std::min(top_, text_.size()));  // an edit above may have moved where lines start
    if (line < top_) {
        top_ = line;
        return;
    }
    size_t a = top_;
    for (int i = 0; i < rows_; i++) {
        if (a == line) return;  // on screen
        if (!hasLineAfter(a)) return;
        a = nextLine(a);
    }
    // Below the screen: the cursor's line becomes the last row.
    top_ = line;
    for (int i = 1; i < rows_ && top_ > 0; i++) top_ = lineOf(top_ - 1);
 }
 std::vector<std::string> NoteText::rows() {
    follow();
    std::vector<std::string> out;
    size_t a = top_, size = text_.size();
    for (int i = 0; i < rows_; i++) {
        size_t n = nextLine(a);
        std::string row = text_.substr(a, n - a);
        if (!row.empty() && row.back() == '\n') row.pop_back();
        for (char& c : row)
            if (c == '\t') c = ' ';
        out.push_back(std::move(row));
        if (!hasLineAfter(a)) break;
        a = n >= size ? size : n;
    }
    return out;
 }
 int NoteText::cursorRow() {
    follow();
    size_t line = lineOf(cursor_), a = top_;
    for (int i = 0; i < rows_; i++) {
        if (a == line) return i;
        a = nextLine(a);
    }
    return rows_ - 1;
 }
 int NoteText::cursorCol() { return columnOf(lineOf(cursor_), cursor_); }
 // At most a screen's worth of it: a note that is one line of 16 KB must not be copied whole.
 std::string NoteText::firstLine() const { return text_.substr(0, std::min<size_t>(text_.find('\n'), 160)); }
 namespace {
 // U+00C0 to U+00FF as the plain letters a file name gets; 0: left out.
 const char kPlain[64] = {
    'a', 'a', 'a', 'a', 'a', 'a', 0,   'c', 'e', 'e', 'e', 'e', 'i', 'i', 'i', 'i',   // À..Ï
    0,   'n', 'o', 'o', 'o', 'o', 'o', 0,   'o', 'u', 'u', 'u', 'u', 'y', 0,   's',   // Ð..ß
    'a', 'a', 'a', 'a', 'a', 'a', 0,   'c', 'e', 'e', 'e', 'e', 'i', 'i', 'i', 'i',   // à..ï
    0,   'n', 'o', 'o', 'o', 'o', 'o', 0,   'o', 'u', 'u', 'u', 'u', 'y', 0,   'y'};  // ð..ÿ
 // Drops a character the end of the string cuts in two.
 void dropPartial(std::string& s) {
    size_t k = s.size();
    while (k > 0 && continuation(s[k - 1]) && s.size() - k < 3) k--;
    if (k == 0) return;
    uint8_t lead = static_cast<uint8_t>(s[k - 1]);
    size_t want = lead >= 0xF0 ? 4 : lead >= 0xE0 ? 3 : lead >= 0xC0 ? 2 : 1;
    if (s.size() - (k - 1) < want) s.resize(k - 1);
 }
 }  // namespace
 std::string nameFromFirstLine(const std::string& firstLine, const std::string& stamp) {
    std::string out;
    bool dash = false;
    for (size_t i = 0; i < firstLine.size() && out.size() < 32; i++) {
        uint8_t c = static_cast<uint8_t>(firstLine[i]);
        char letter = 0;
        if (c < 0x80) {
            if (c >= 'A' && c <= 'Z') letter = static_cast<char>(c + 32);
            else if ((c >= 'a' && c <= 'z') || (c >= '0' && c <= '9')) letter = static_cast<char>(c);
        } else if (c == 0xC3 && i + 1 < firstLine.size()) {  // U+00C0..U+00FF
            letter = kPlain[static_cast<uint8_t>(firstLine[++i]) & 0x3F];
        } else {
            while (i + 1 < firstLine.size() && continuation(firstLine[i + 1])) i++;  // anything else is left out
        }
        if (letter) {
            if (dash && !out.empty()) out += '-';
            dash = false;
            out += letter;
        } else {
            dash = true;
        }
    }
    return out.empty() ? "note-" + stamp : out;
 }
 std::string titleFrom(const std::string& head, size_t maxChars) {
    for (size_t at = 0; at < head.size();) {
        size_t end = head.find('\n', at);
        bool cut = end == std::string::npos;  // the line goes on past what was read
        if (cut) end = head.size();
        std::string line = head.substr(at, end - at);
        if (cut) dropPartial(line);
        while (!line.empty() && (line.back() == '\r' || line.back() == ' ' || line.back() == '\t')) line.pop_back();
        size_t first = line.find_first_not_of(" \t");
        if (first != std::string::npos) {
            line.erase(0, first);
            size_t bytes = 0;
            for (size_t chars = 0; bytes < line.size() && chars < maxChars; chars++) {
                bytes++;
                while (bytes < line.size() && continuation(line[bytes])) bytes++;
            }
            line.resize(bytes);
            return line;
        }
        at = end + 1;
    }
    return "";
 }
 }  // namespace roro::notes
@@ -0,0 +1,91 @@
 #pragma once
 #include <cstddef>
 #include <cstdint>
 #include <string>
 #include <vector>
 namespace roro::notes {
 // The text of a note while it's edited (F1, Q144, Q145): UTF-8 held in memory, a cursor, and the
 // part of it on screen. Up to 16 KB: a longer note is edited through NoteDocument (note_document.h),
 // which keeps this as its window on the file. Lines wrap at spaces, `cols` characters wide; a line owns the space or
 // the newline it ends with, so every byte of the text belongs to exactly one line. No index of
 // lines is kept (a note of newlines alone would need twice its size): where a line starts is
 // worked out from the start of its paragraph, which is never far.
 class NoteText {
   public:
    static constexpr size_t kMaxBytes = 16 * 1024;
    // Room for a full note is reserved once, so typing never has to find a bigger block of memory:
    // on the device a failed allocation is the end. The second form takes over a string the
    // caller filled (and reserved): a note is never in memory twice.
    NoteText(int cols, int rows);
    NoteText(int cols, int rows, std::string&& text);
    // Copied into the buffer already held. CRLF becomes LF (Q148). False, and nothing changes, if
    // it's over kMaxBytes.
    bool setText(const std::string& text);
    const std::string& text() const { return text_; }
    size_t cursor() const { return cursor_; }
    size_t size() const { return text_.size(); }
    uint32_t revision() const { return revision_; }  // changes with every edit: is it saved?
    // For a window on a longer text (issue #47): the caller refills the buffer, then says where
    // the cursor is in it and which row of the screen it should be on. CRLF becomes LF as in
    // setText; returns how many CRs went. The revision doesn't change: nothing was edited.
    std::string& buffer() { return text_; }
    size_t refilled(size_t cursor, int row);
    size_t startOfLine(size_t pos) const { return lineOf(pos); }
    size_t top() const { return top_; }
    bool insert(uint32_t codePoint);         // false: the note is full
    bool insertText(const std::string& s);   // all of it or nothing
    void backspace();
    void left();
    void right();
    void up();
    void down();
    void pageUp();
    void pageDown();
    void lineStart();
    void lineEnd();
    void toStart();
    void toEnd();
    // The screen, kept around the cursor: its rows (tabs as spaces, the ending newline left out),
    // and where the cursor is on it, in rows and characters.
    std::vector<std::string> rows();
    int cursorRow();
    int cursorCol();
    int percent() const { return text_.empty() ? 0 : static_cast<int>(top_ * 100 / text_.size()); }
    std::string firstLine() const;  // without its newline, for the title and the file's name
   private:
    size_t nextLine(size_t start) const;       // where the line after the one at `start` starts
    size_t lineOf(size_t pos) const;           // the start of the line `pos` is on
    size_t lastSpot(size_t start) const;       // the last place the cursor can be on that line
    size_t atColumn(size_t start, int col) const;
    int columnOf(size_t start, size_t pos) const;
    bool hasLineAfter(size_t start) const;
    void moved(bool keepGoal = false);
    void follow();  // scrolls so the cursor is on screen
    size_t dropCarriageReturns(size_t* follow = nullptr);  // how many; `follow` is a place in the text, kept on its character
    int cols_, rows_;
    std::string text_;
    size_t cursor_ = 0, top_ = 0;
    int goal_ = -1;  // the column Up and Down aim for, across short lines
    uint32_t revision_ = 0;
 };
 // The file a new note is saved as (Q142): from its first line, "Shopping list!" -> "shopping-list",
 // or "note-<stamp>" when that gives nothing. No extension, no folder.
 std::string nameFromFirstLine(const std::string& firstLine, const std::string& stamp);
 // A row's title in the Notes list, from the first bytes of a file: its first line that isn't
 // blank, cut to `maxChars`; "" if there's none.
 std::string titleFrom(const std::string& head, size_t maxChars);
 }  // namespace roro::notes
@@ -0,0 +1,158 @@
 #include "http_head.h"
 #include <algorithm>
 #include <cctype>
 #include <cstdlib>
 namespace roro::release {
 namespace {
 std::string lower(std::string s) {
    for (char& c : s) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
    return s;
 }
 }  // namespace
 size_t HttpHeadParser::feed(const char* data, size_t len) {
    size_t used = 0;
    while (used < len && !complete_ && !failed_) {
        char c = data[used++];
        total_++;
        if (total_ > kMaxBytes) {
            failed_ = true;
            break;
        }
        if (c == '\n') {
            if (!line_.empty() && line_.back() == '\r') line_.pop_back();
            line();
            line_.clear();
        } else {
            line_ += c;
        }
    }
    return used;
 }
 void HttpHeadParser::line() {
    if (first_) {  // "HTTP/1.1 200 OK"
        first_ = false;
        if (line_.compare(0, 5, "HTTP/") != 0) {
            failed_ = true;
            return;
        }
        size_t space = line_.find(' ');
        head_.status = space == std::string::npos ? 0 : std::atoi(line_.c_str() + space + 1);
        if (head_.status < 100 || head_.status > 599) failed_ = true;
        return;
    }
    if (line_.empty()) {
        complete_ = true;
        return;
    }
    size_t colon = line_.find(':');
    if (colon == std::string::npos) return;  // not a header: ignored
    std::string name = lower(line_.substr(0, colon));
    size_t from = line_.find_first_not_of(" \t", colon + 1);
    std::string value = from == std::string::npos ? "" : line_.substr(from);
    if (name == "content-length") head_.contentLength = std::atol(value.c_str());
    else if (name == "transfer-encoding") head_.chunked = lower(value).find("chunked") != std::string::npos;
    else if (name == "location") head_.location = value;
    else if (name == "content-type") head_.contentType = value;
 }
 size_t ChunkedDecoder::decode(const uint8_t* in, size_t len, uint8_t* out) {
    size_t written = 0;
    for (size_t i = 0; i < len && !failed_ && state_ != State::Done; i++) {
        uint8_t c = in[i];
        switch (state_) {
            case State::Size: {
                int digit = c >= '0' && c <= '9' ? c - '0' : c >= 'a' && c <= 'f' ? c - 'a' + 10 : c >= 'A' && c <= 'F' ? c - 'A' + 10 : -1;
                if (digit >= 0) {
                    if (remaining_ > (SIZE_MAX >> 5)) failed_ = true;
                    remaining_ = remaining_ * 16 + digit;
                    anyDigit_ = true;
                } else if (c == ';' && anyDigit_) {
                    state_ = State::Extension;
                } else if (c == '\r' && anyDigit_) {
                    state_ = State::SizeLf;
                } else {
                    failed_ = true;
                }
                break;
            }
            case State::Extension:
                if (c == '\r') state_ = State::SizeLf;
                break;
            case State::SizeLf:
                if (c != '\n') {
                    failed_ = true;
                } else if (remaining_ == 0) {
                    state_ = State::Trailer;
                    trailerLine_ = 0;
                } else {
                    state_ = State::Data;
                }
                break;
            case State::Data: {
                size_t take = std::min(remaining_, len - i);
                for (size_t k = 0; k < take; k++) out[written + k] = in[i + k];
                written += take;
                remaining_ -= take;
                i += take - 1;
                if (remaining_ == 0) state_ = State::DataCr;
                break;
            }
            case State::DataCr:
                if (c != '\r') failed_ = true;
                else state_ = State::DataLf;
                break;
            case State::DataLf:
                if (c != '\n') {
                    failed_ = true;
                } else {
                    state_ = State::Size;
                    anyDigit_ = false;
                }
                break;
            case State::Trailer:  // header lines after the last chunk, until an empty one
                if (c == '\n') {
                    if (trailerLine_ == 0) state_ = State::Done;
                    trailerLine_ = 0;
                } else if (c != '\r') {
                    trailerLine_++;
                }
                break;
            case State::Done: break;
        }
    }
    return written;
 }
 Url parseUrl(const std::string& url) {
    Url u;
    size_t scheme = url.find("://");
    if (scheme == std::string::npos) return u;
    std::string s = lower(url.substr(0, scheme));
    if (s != "http" && s != "https") return u;
    u.https = s == "https";
    size_t hostStart = scheme + 3, pathStart = url.find('/', hostStart);
    std::string authority = url.substr(hostStart, pathStart == std::string::npos ? std::string::npos : pathStart - hostStart);
    u.path = pathStart == std::string::npos ? "/" : url.substr(pathStart);
    if (authority.empty() || authority.find('@') != std::string::npos) return u;  // no credentials in a URL
    size_t colon = authority.rfind(':');
    u.port = u.https ? 443 : 80;
    if (colon != std::string::npos) {
        u.port = std::atoi(authority.c_str() + colon + 1);
        authority.resize(colon);
        if (u.port <= 0 || u.port > 65535) return u;
    }
    for (unsigned char c : authority)
        if (!(std::isalnum(c) || c == '.' || c == '-')) return u;
    for (unsigned char c : u.path)
        if (c <= ' ' || c == 0x7F) return u;
    u.host = lower(authority);
    u.ok = !u.host.empty();
    return u;
 }
 }  // namespace roro::release
@@ -0,0 +1,62 @@
 #pragma once
 #include <cstddef>
 #include <cstdint>
 #include <string>
 namespace roro::release {
 // The status line and headers of an HTTP/1.1 response, read as bytes arrive.
 struct HttpHead {
    int status = 0;
    long contentLength = -1;  // -1: not given
    bool chunked = false;
    std::string location, contentType;
 };
 class HttpHeadParser {
   public:
    static constexpr size_t kMaxBytes = 4096;
    // Takes bytes up to and including the blank line that ends the head; returns how many it used.
    // What follows is the body.
    size_t feed(const char* data, size_t len);
    bool complete() const { return complete_; }
    bool failed() const { return failed_; }
    const HttpHead& head() const { return head_; }
   private:
    void line();
    HttpHead head_;
    std::string line_;
    size_t total_ = 0;
    bool first_ = true, complete_ = false, failed_ = false;
 };
 // Takes the chunks of "Transfer-Encoding: chunked" apart as they arrive.
 class ChunkedDecoder {
   public:
    // `out` has room for `len` bytes (the body is never longer than what carried it).
    size_t decode(const uint8_t* in, size_t len, uint8_t* out);
    bool done() const { return state_ == State::Done; }
    bool failed() const { return failed_; }
   private:
    enum class State : uint8_t { Size, Extension, SizeLf, Data, DataCr, DataLf, Trailer, Done };
    State state_ = State::Size;
    size_t remaining_ = 0;
    bool anyDigit_ = false, failed_ = false;
    size_t trailerLine_ = 0;
 };
 // "https://git.twis.la/twisla/x/releases/download/v1/a.ota" taken apart. Only http and https.
 struct Url {
    bool ok = false;
    bool https = false;
    std::string host, path;  // path from the first "/", with its query; "/" if none
    int port = 0;
 };
 Url parseUrl(const std::string& url);
 }  // namespace roro::release
@@ -0,0 +1,202 @@
 #include "json_scan.h"
 namespace roro::release {
 namespace {
 bool space(char c) { return c == ' ' || c == '\t' || c == '\r' || c == '\n'; }
 bool continuation(char c) { return (static_cast<uint8_t>(c) & 0xC0) == 0x80; }
 }  // namespace
 void JsonScanner::feed(const char* data, size_t len) {
    for (size_t i = 0; i < len && !failed_; i++) step(data[i]);
 }
 std::string JsonScanner::path() const {
    std::string p;
    for (const Frame& f : stack_) {
        if (f.isObject) {
            if (!p.empty()) p += '.';
            p += f.key;
        } else {
            p += '[' + std::to_string(f.index) + ']';
        }
    }
    return p;
 }
 void JsonScanner::append(const char* bytes, size_t n) {
    if (text_.size() + n > max_) {
        truncated_ = true;
        return;
    }
    text_.append(bytes, n);
 }
 void JsonScanner::appendCodePoint(uint32_t cp) {
    char b[4];
    size_t n;
    if (cp < 0x80) {
        b[0] = static_cast<char>(cp);
        n = 1;
    } else if (cp < 0x800) {
        b[0] = static_cast<char>(0xC0 | (cp >> 6));
        b[1] = static_cast<char>(0x80 | (cp & 0x3F));
        n = 2;
    } else if (cp < 0x10000) {
        b[0] = static_cast<char>(0xE0 | (cp >> 12));
        b[1] = static_cast<char>(0x80 | ((cp >> 6) & 0x3F));
        b[2] = static_cast<char>(0x80 | (cp & 0x3F));
        n = 3;
    } else {
        b[0] = static_cast<char>(0xF0 | (cp >> 18));
        b[1] = static_cast<char>(0x80 | ((cp >> 12) & 0x3F));
        b[2] = static_cast<char>(0x80 | ((cp >> 6) & 0x3F));
        b[3] = static_cast<char>(0x80 | (cp & 0x3F));
        n = 4;
    }
    append(b, n);
 }
 void JsonScanner::startString(bool key) {
    inString_ = true;
    isKey_ = key;
    escape_ = false;
    unicodeLeft_ = 0;
    highSurrogate_ = 0;
    truncated_ = false;
    text_.clear();
 }
 void JsonScanner::stringChar(char c) {
    if (unicodeLeft_ > 0) {
        int digit = c >= '0' && c <= '9' ? c - '0' : c >= 'a' && c <= 'f' ? c - 'a' + 10 : c >= 'A' && c <= 'F' ? c - 'A' + 10 : -1;
        if (digit < 0) return fail();
        unicode_ = unicode_ * 16 + digit;
        if (--unicodeLeft_ == 0) {
            if (unicode_ >= 0xD800 && unicode_ < 0xDC00) {
                highSurrogate_ = unicode_;  // the low half comes next
            } else if (unicode_ >= 0xDC00 && unicode_ < 0xE000 && highSurrogate_) {
                appendCodePoint(0x10000 + ((highSurrogate_ - 0xD800) << 10) + (unicode_ - 0xDC00));
                highSurrogate_ = 0;
            } else {
                appendCodePoint(unicode_);
                highSurrogate_ = 0;
            }
        }
        return;
    }
    if (escape_) {
        escape_ = false;
        switch (c) {
            case 'n': append("\n", 1); break;
            case 't': append("\t", 1); break;
            case 'r': append("\r", 1); break;
            case 'b': append("\b", 1); break;
            case 'f': append("\f", 1); break;
            case 'u': unicodeLeft_ = 4; unicode_ = 0; break;
            default: append(&c, 1); break;  // \" \\ \/
        }
        return;
    }
    if (c == '\\') {
        escape_ = true;
    } else if (c == '"') {
        endString();
    } else {
        append(&c, 1);
    }
 }
 void JsonScanner::endString() {
    inString_ = false;
    // A cut can leave half a character at the end.
    while (truncated_ && !text_.empty()) {
        size_t k = text_.size();
        while (k > 0 && continuation(text_[k - 1])) k--;
        if (k == 0) break;
        uint8_t lead = static_cast<uint8_t>(text_[k - 1]);
        size_t want = lead >= 0xF0 ? 4 : lead >= 0xE0 ? 3 : lead >= 0xC0 ? 2 : 1;
        if (text_.size() - (k - 1) < want) text_.resize(k - 1);
        break;
    }
    if (isKey_) {
        stack_.back().key = text_;
        expect_ = Expect::Colon;
        return;
    }
    sink_(path(), text_, true, truncated_);
    valueDone();
 }
 void JsonScanner::endLiteral() {
    inLiteral_ = false;
    sink_(path(), text_, false, false);
    valueDone();
 }
 void JsonScanner::valueDone() {
    if (stack_.empty()) {
        done_ = true;
        return;
    }
    expect_ = Expect::CommaOrEnd;
 }
 void JsonScanner::step(char c) {
    if (inString_) return stringChar(c);
    if (inLiteral_) {
        if (space(c) || c == ',' || c == '}' || c == ']') {
            endLiteral();  // and the character that ended it is read again below
        } else {
            if (text_.size() < max_) text_ += c;
            return;
        }
    }
    if (space(c)) return;
    switch (expect_) {
        case Expect::Value:
            if (c == '{') {
                stack_.push_back({true, "", 0});
                expect_ = Expect::KeyOrEnd;
            } else if (c == '[') {
                stack_.push_back({false, "", 0});
                expect_ = Expect::Value;
            } else if (c == ']' && !stack_.empty() && !stack_.back().isObject && stack_.back().index == 0) {
                stack_.pop_back();  // an empty array
                valueDone();
            } else if (c == '"') {
                startString(false);
            } else if (c == '-' || (c >= '0' && c <= '9') || c == 't' || c == 'f' || c == 'n') {
                inLiteral_ = true;
                text_.assign(1, c);
            } else {
                fail();
            }
            return;
        case Expect::KeyOrEnd:
            if (c == '"') startString(true);
            else if (c == '}') {
                stack_.pop_back();
                valueDone();
            } else fail();
            return;
        case Expect::Colon:
            if (c == ':') expect_ = Expect::Value;
            else fail();
            return;
        case Expect::CommaOrEnd:
            if (c == ',') {
                if (stack_.back().isObject) expect_ = Expect::KeyOrEnd;
                else {
                    stack_.back().index++;
                    expect_ = Expect::Value;
                }
            } else if ((c == '}' && stack_.back().isObject) || (c == ']' && !stack_.back().isObject)) {
                stack_.pop_back();
                valueDone();
            } else fail();
            return;
    }
 }
 }  // namespace roro::release
@@ -0,0 +1,57 @@
 #pragma once
 #include <cstddef>
 #include <cstdint>
 #include <functional>
 #include <string>
 #include <vector>
 namespace roro::release {
 // Reads JSON as it arrives, a chunk at a time, and reports each plain value (a string, a number,
 // true, false, null) with where it was found: "tag_name", "assets[1].name", "[2].draft". Nothing
 // is kept but the path, so a 33 KB list of releases costs a few hundred bytes. A value longer than
 // `maxValueBytes` is cut (never in the middle of a character) and reported as truncated.
 // Meant for a server's answer, not for validating JSON: it only refuses what it can't follow.
 class JsonScanner {
   public:
    using Sink = std::function<void(const std::string& path, const std::string& value, bool isString, bool truncated)>;
    explicit JsonScanner(Sink sink, size_t maxValueBytes = 300) : sink_(std::move(sink)), max_(maxValueBytes) {}
    void feed(const char* data, size_t len);
    bool failed() const { return failed_; }
    bool done() const { return done_ && !failed_; }  // the top-level value is complete
   private:
    enum class Expect : uint8_t { Value, KeyOrEnd, Colon, CommaOrEnd };
    struct Frame {
        bool isObject;
        std::string key;
        int index;
    };
    void step(char c);
    void startString(bool key);
    void stringChar(char c);
    void appendCodePoint(uint32_t cp);
    void endString();
    void endLiteral();
    void valueDone();
    void append(const char* bytes, size_t n);
    std::string path() const;
    void fail() { failed_ = true; }
    Sink sink_;
    size_t max_;
    std::vector<Frame> stack_;
    Expect expect_ = Expect::Value;
    bool inString_ = false, isKey_ = false, escape_ = false, inLiteral_ = false;
    int unicodeLeft_ = 0;
    uint32_t unicode_ = 0, highSurrogate_ = 0;
    bool truncated_ = false;
    std::string text_;
    bool failed_ = false, done_ = false;
 };
 }  // namespace roro::release
@@ -0,0 +1,80 @@
 #include "release_info.h"
 #include <cstdlib>
 namespace roro::release {
 namespace {
 bool endsWith(const std::string& s, const char* tail) {
    size_t n = std::char_traits<char>::length(tail);
    return s.size() >= n && s.compare(s.size() - n, n, tail) == 0;
 }
 }  // namespace
 std::string firstParagraph(const std::string& text, bool truncated) {
    size_t end = text.find("\n\n");
    size_t crlf = text.find("\r\n\r\n");
    if (crlf != std::string::npos && (end == std::string::npos || crlf < end)) end = crlf;
    std::string p = text.substr(0, end);
    size_t first = p.find_first_not_of(" \t\r\n");
    if (first == std::string::npos) return "";
    p.erase(0, first);
    while (!p.empty() && (p.back() == ' ' || p.back() == '\t' || p.back() == '\r' || p.back() == '\n')) p.pop_back();
    if (truncated && end == std::string::npos) p += "...";
    return p;
 }
 ReleaseReader::ReleaseReader(size_t maxReleases)
    : scanner_([this](const std::string& path, const std::string& text, bool isString, bool truncated) {
          value(path, text, isString, truncated);
      }),
      max_(maxReleases) {}
 void ReleaseReader::end() { flushAsset(); }
 void ReleaseReader::flushAsset() {
    if (assetRelease_ >= 0 && assetRelease_ < static_cast<int>(releases_.size()) && endsWith(assetName_, ".ota") && !assetUrl_.empty()) {
        releases_[assetRelease_].otaUrl = assetUrl_;
        releases_[assetRelease_].otaSize = assetSize_;
    }
    assetRelease_ = assetIndex_ = -1;
    assetName_.clear();
    assetUrl_.clear();
    assetSize_ = 0;
 }
 void ReleaseReader::value(const std::string& path, const std::string& text, bool isString, bool truncated) {
    size_t index = 0;
    std::string rest = path;
    if (!path.empty() && path[0] == '[') {  // a list: "[2].tag_name"
        char* end;
        index = static_cast<size_t>(std::strtol(path.c_str() + 1, &end, 10));
        rest = *end == ']' ? std::string(end + 1) : "";
        if (!rest.empty() && rest[0] == '.') rest.erase(0, 1);
    }
    if (index >= max_) return;
    if (releases_.size() <= index) releases_.resize(index + 1);
    Release& r = releases_[index];
    if (rest == "tag_name") r.tag = text;
    else if (rest == "published_at") r.published = text;
    else if (rest == "body") r.notes = firstParagraph(text, truncated);
    else if (rest == "draft") r.draft = text == "true";
    else if (rest == "prerelease") r.prerelease = text == "true";
    else if (rest.compare(0, 7, "assets[") == 0) {
        char* end;
        int j = static_cast<int>(std::strtol(rest.c_str() + 7, &end, 10));
        if (static_cast<int>(index) != assetRelease_ || j != assetIndex_) {
            flushAsset();
            assetRelease_ = static_cast<int>(index);
            assetIndex_ = j;
        }
        std::string field = *end == ']' && end[1] == '.' ? std::string(end + 2) : "";
        if (field == "name") assetName_ = text;
        else if (field == "size") assetSize_ = static_cast<uint32_t>(std::strtoul(text.c_str(), nullptr, 10));
        else if (field == "browser_download_url") assetUrl_ = text;
    }
    (void)isString;
 }
 }  // namespace roro::release
@@ -0,0 +1,52 @@
 #pragma once
 #include <cstdint>
 #include <string>
 #include <vector>
 #include "json_scan.h"
 namespace roro::release {
 // What the device needs to know about one Gitea release (docs/milestones/R1.md, #6).
 struct Release {
    std::string tag;        // "v0.10.0"
    std::string published;  // "2026-10-06T08:11:31Z"
    std::string notes;      // the first paragraph of the text: the tag's message
    std::string otaUrl;     // where the signed Update File is
    uint32_t otaSize = 0;
    bool draft = false, prerelease = false;
    // Something that can be installed and that the project meant to publish (drafts and
    // pre-releases are left out for now: a release channel is #53).
    bool usable() const { return !draft && !prerelease && !tag.empty() && !otaUrl.empty(); }
    std::string date() const { return published.substr(0, 10); }  // "2026-10-06"
 };
 // Reads Gitea's answer as it arrives: `releases/latest` (one object) or `releases?limit=N` (a list).
 class ReleaseReader {
   public:
    explicit ReleaseReader(size_t maxReleases = 10);
    void feed(const char* data, size_t len) { scanner_.feed(data, len); }
    void end();  // after the last chunk
    bool ok() const { return !scanner_.failed(); }
    bool complete() const { return scanner_.done(); }
    const std::vector<Release>& releases() const { return releases_; }
   private:
    void value(const std::string& path, const std::string& text, bool isString, bool truncated);
    void flushAsset();
    JsonScanner scanner_;
    size_t max_;
    std::vector<Release> releases_;
    int assetRelease_ = -1, assetIndex_ = -1;
    std::string assetName_, assetUrl_;
    uint32_t assetSize_ = 0;
 };
 // The first paragraph of a release's text, trimmed; "..." if the text was cut before it ended.
 std::string firstParagraph(const std::string& text, bool truncated);
 }  // namespace roro::release
@@ -0,0 +1,15 @@
 #include "update_check.h"
 #include "http_head.h"
 namespace roro::release {
 bool trustedAssetUrl(const std::string& url, const std::string& host, const std::string& repo) {
    Url u = parseUrl(url);
    if (!u.ok || !u.https || u.port != 443 || u.host != host) return false;
    std::string prefix = "/" + repo + "/releases/download/";
    return u.path.compare(0, prefix.size(), prefix) == 0 && u.path.find("..") == std::string::npos &&
           u.path.find('?') == std::string::npos && u.path.find('#') == std::string::npos;
 }
 }  // namespace roro::release
@@ -0,0 +1,32 @@
 #pragma once
 #include <string>
 #include "release_info.h"
 #include "version_compare.h"
 namespace roro::release {
 // Where the project's releases are (Q164). A fork changes these, and its own signing key.
 constexpr const char* kGiteaHost = "git.twis.la";
 constexpr const char* kGiteaRepo = "twisla/roro9stack";
 inline bool versionNewer(const std::string& a, const std::string& b) { return versionOlder(b, a); }
 // Is `release` a newer one than what runs?
 inline bool isNewer(const Release& release, const std::string& running) {
    return release.usable() && versionNewer(release.tag, running);
 }
 // Should the background check say so (Q166, Q168)? Not for a version that failed on this device
 // before (it rolled back), and not twice for the same one.
 inline bool shouldAnnounce(const Release& latest, const std::string& running, const std::string& failed, const std::string& announced) {
    return isNewer(latest, running) && latest.tag != failed && latest.tag != announced;
 }
 // Is `url` a download this device takes from the project's server, for this repository? Whatever
 // the API says, the device only fetches from where it asked (a redirected or rewritten answer
 // can't send it elsewhere).
 bool trustedAssetUrl(const std::string& url, const std::string& host = kGiteaHost, const std::string& repo = kGiteaRepo);
 }  // namespace roro::release
@@ -10,7 +10,10 @@ bool PowerPolicy::activity(uint32_t nowMs) {
 }
 ScreenState PowerPolicy::update(uint32_t nowMs) {
-    uint32_t idle = nowMs - lastActivityMs_;
+    // Activity stamped from a clock read after this pass's nowMs (the Debug Console's `key`) is in
    // the future, not 49 days ago: unsigned, the screen went off for a tick and ate the next key.
    int32_t since = static_cast<int32_t>(nowMs - lastActivityMs_);
    uint32_t idle = since < 0 ? 0 : static_cast<uint32_t>(since);
    state_ = idle >= offMs_ ? ScreenState::Off : idle >= dimMs_ ? ScreenState::Dimmed : ScreenState::On;
    if (notifying_) {
        if (static_cast<int32_t>(nowMs - notifyUntilMs_) >= 0)
@@ -1,5 +1,8 @@
 #include "settings.h"
 #include "debug_auth.h"
 #include "ipv4.h"
 namespace roro {
 namespace {
@@ -32,6 +35,16 @@ const Definition kDefinitions[] = {
    {"gnss_on", Kind::Bool, 1, nullptr, 0, 1},
    {"coord_dms", Kind::Bool, 0, nullptr, 0, 1},
    {"lora_preset", Kind::Int, 0, nullptr, 0, 6},  // LongFast first
    {"dns1", Kind::String, 0, "9.9.9.9", 7, 15},  // Quad9
    {"dns2", Kind::String, 0, "1.1.1.1", 0, 15},  // Cloudflare
    {"dns_always", Kind::Bool, 0, nullptr, 0, 1},
    {"ntp1", Kind::String, 0, "pool.ntp.org", 1, 63},
    {"ntp2", Kind::String, 0, "time.cloudflare.com", 0, 63},
    {"gnss_quiet", Kind::Bool, 0, nullptr, 0, 1},  // off: GNSS stays on, as decided in M2 (Q58)
    {"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");
@@ -84,6 +97,12 @@ bool Settings::validString(Setting s, const std::string& value) const {
            if (value == region) return true;
        return false;
    }
    uint32_t address;
    if (s == Setting::Dns1) return net::parseIpv4(value, address);
    if (s == Setting::Dns2) return value.empty() || net::parseIpv4(value, address);
    if (s == Setting::Ntp1) return net::validHost(value);
    if (s == Setting::Ntp2) return value.empty() || net::validHost(value);
    if (s == Setting::DebugToken) return value.empty() || debug::validToken(value);
    return true;
 }
@@ -24,6 +24,16 @@ enum class Setting : uint8_t {
    GnssEnabled,      // bool: the GNSS Service reads the receiver (M2, Q58)
    CoordinatesDms,   // bool: show degrees, minutes and seconds instead of decimal degrees (Q64)
    LoraPreset,       // int: the LoRa Scanner's Meshtastic preset, an index into the EU868 list (M3, Q95)
    Dns1,             // string: the first DNS server, an IPv4 address (S1, Q108, Q109)
    Dns2,             // string: the second, or empty
    DnsAlways,        // bool: use them on Automatic (DHCP) networks too, instead of DHCP's
    Ntp1,             // string: the first NTP server, a host name or an IPv4 address (S1, Q110)
    Ntp2,             // string: the second, or empty
    GnssQuietForLora, // bool: put the GNSS receiver in standby while the LoRa radio listens (issue #20)
    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
 };
@@ -24,7 +24,7 @@ void StorageMonitor::update(bool present, uint64_t totalBytes, uint64_t usedByte
    if (next.present && next.level >= 80 && !warned_) {
        warned_ = true;
-        bus_.publish(Event::withText(EventType::Notification, "SD card over 80% full",
+        bus_.publish(Event::withText(EventType::Notification, "SD card over 80% full: see Storage",
                                     static_cast<int32_t>(NotificationLevel::Warning)));
    }
 }
@@ -0,0 +1,72 @@
 #include "task_stats.h"
 #include <algorithm>
 #include <cctype>
 #include <cstring>
 namespace roro {
 std::vector<TaskRow> taskRows(const std::vector<TaskSample>& before, uint32_t totalBefore,
                              const std::vector<TaskSample>& now, uint32_t totalNow) {
    uint32_t elapsed = totalNow - totalBefore;  // unsigned: right across one wrap
    std::vector<TaskRow> rows;
    rows.reserve(now.size());
    for (const TaskSample& t : now) {
        uint32_t ran = t.runtime;  // a task that wasn't there before ran all of it since
        for (const TaskSample& b : before)
            if (b.id == t.id) {
                ran = t.runtime - b.runtime;
                break;
            }
        TaskRow r;
        r.name = t.name;
        r.core = t.core;
        r.state = t.state;
        r.priority = t.priority;
        r.stackFree = t.stackFree;
        r.permille = elapsed ? static_cast<uint16_t>(std::min<uint64_t>(1000, static_cast<uint64_t>(ran) * 1000 / elapsed)) : 0;
        r.lowStack = t.stackFree < kLowStackBytes;
        r.idle = std::strncmp(t.name, "IDLE", 4) == 0;
        rows.push_back(r);
    }
    // The task that took the sample is running, and FreeRTOS counts a task's time when it's
    // switched out: with its core to itself it never was, and its counter hardly moved. Give it
    // what's left of its core once the idle task and the other tasks pinned there are counted.
    for (TaskRow& r : rows) {
        if (r.state != 0 || r.idle || r.core < 0) continue;  // 0: eRunning
        int others = 0;
        bool idleSeen = false;
        for (const TaskRow& o : rows) {
            if (&o == &r || o.core != r.core) continue;
            others += o.permille;
            idleSeen |= o.idle;
        }
        if (idleSeen && elapsed && 1000 - others > r.permille) r.permille = static_cast<uint16_t>(std::max(0, 1000 - others));
    }
    return rows;
 }
 int coreLoad(const std::vector<TaskRow>& rows, int core) {
    for (const TaskRow& r : rows)
        if (r.idle && r.core == core) return 100 - (r.permille + 5) / 10;
    return -1;
 }
 void sortTasks(std::vector<TaskRow>& rows, TaskSort by) {
    auto lower = [](const std::string& s) {
        std::string l = s;
        for (char& c : l) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
        return l;
    };
    std::stable_sort(rows.begin(), rows.end(), [&](const TaskRow& a, const TaskRow& b) {
        switch (by) {
            case TaskSort::Share:
                if (a.idle != b.idle) return !a.idle;  // idle tasks last
                return a.permille > b.permille;
            case TaskSort::Stack: return a.stackFree < b.stackFree;
            default: return lower(a.name) < lower(b.name);
        }
    });
 }
 }  // namespace roro
@@ -0,0 +1,65 @@
 #pragma once
 #include <cstddef>
 #include <cstdint>
 #include <cstdio>
 #include <string>
 #include <vector>
 namespace roro {
 // One task as FreeRTOS reports it at one moment.
 struct TaskSample {
    uint32_t id = 0;       // unique per task: a new task with an old name has another
    char name[17] = {};
    uint32_t runtime = 0;  // microseconds on a CPU since it started; 32 bits, so it wraps every 71 minutes
    uint16_t stackFree = 0;  // the least it ever had left, bytes
    int8_t core = -1;        // -1: not pinned
    uint8_t state = 0;       // eTaskState
    uint8_t priority = 0;
 };
 // What the System App and `tasks` show for a task (S1, Q119, Q122).
 struct TaskRow {
    std::string name;
    int core = -1;
    uint8_t state = 0, priority = 0;
    uint16_t stackFree = 0;
    uint16_t permille = 0;  // share of one core over the interval, in tenths of a percent
    bool lowStack = false;
    bool idle = false;      // a core's idle task: what's left over
 };
 constexpr uint16_t kLowStackBytes = 512;
 // Shares from two samples: each task's run time between them over the time that passed. The
 // 32-bit counters may have wrapped once in between. The task that took the samples (the one
 // running) gets what's left of its core: see the .cpp.
 std::vector<TaskRow> taskRows(const std::vector<TaskSample>& before, uint32_t totalBefore,
                              const std::vector<TaskSample>& now, uint32_t totalNow);
 // A core's load in percent: what its idle task didn't use. -1 without that task in the rows.
 int coreLoad(const std::vector<TaskRow>& rows, int core);
 enum class TaskSort : uint8_t { Share, Stack, Name };
 void sortTasks(std::vector<TaskRow>& rows, TaskSort by);
 // The last N samples, oldest first (Q120).
 template <typename T, size_t N>
 class History {
   public:
    void push(T value) {
        values_[(first_ + size_) % N] = value;
        if (size_ < N) size_++;
        else first_ = (first_ + 1) % N;
    }
    size_t size() const { return size_; }
    T at(size_t i) const { return values_[(first_ + i) % N]; }  // 0: the oldest kept
    void clear() { first_ = size_ = 0; }
   private:
    T values_[N] = {};
    size_t first_ = 0, size_ = 0;
 };
 }  // namespace roro
@@ -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
@@ -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.
+// "v0.1.0", from `git describe` (scripts/version.py): used on the boot screen and in About.
-inline const char* versionString() { return RORO_VERSION; }
+// 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
@@ -17,6 +17,8 @@ void SavedNetworks::load() {
        int32_t hidden = 0;
        store_.getInt(key(i, "hid").c_str(), hidden);
        net.hidden = hidden != 0;
        std::string ip;  // "address/prefix [gateway]", or empty for Automatic
        net.fixed = store_.getString(key(i, "ip").c_str(), ip) && !ip.empty() && net::parseFixed(ip, net.ip).empty();
        networks_.push_back(net);
    }
 }
@@ -40,11 +42,30 @@ std::string SavedNetworks::add(const std::string& ssid, const std::string& passw
        }
    }
    if (count() >= kMax) return "Already 8 saved networks: forget one first";
-    networks_.push_back({ssid, password, hidden});
+    SavedNetwork added;
    added.ssid = ssid;
    added.password = password;
    added.hidden = hidden;
    networks_.push_back(added);
    save();
    return "";
 }
 std::string SavedNetworks::setIp(const std::string& ssid, const net::FixedIp* fixed) {
    for (auto& n : networks_) {
        if (n.ssid != ssid) continue;
        if (fixed) {
            std::string why = net::checkFixed(*fixed);
            if (!why.empty()) return why;
            n.ip = *fixed;
        }
        n.fixed = fixed != nullptr;
        save();
        return "";
    }
    return "Not a saved network";
 }
 void SavedNetworks::forget(const std::string& ssid) {
    for (auto it = networks_.begin(); it != networks_.end(); ++it) {
        if (it->ssid == ssid) {
@@ -60,6 +81,7 @@ void SavedNetworks::save() {
        store_.putString(key(i, "ssid").c_str(), networks_[i].ssid);
        store_.putString(key(i, "pass").c_str(), networks_[i].password);
        store_.putInt(key(i, "hid").c_str(), networks_[i].hidden ? 1 : 0);
        store_.putString(key(i, "ip").c_str(), networks_[i].fixed ? net::formatFixed(networks_[i].ip) : "");
    }
    store_.putInt("net_count", count());
 }
@@ -3,6 +3,7 @@
 #include <string>
 #include <vector>
 #include "ipv4.h"
 #include "key_value_store.h"
 namespace roro {
@@ -11,6 +12,8 @@ struct SavedNetwork {
    std::string ssid;
    std::string password;  // empty for an open network
    bool hidden = false;   // doesn't broadcast its name, so never shows up in scans
    bool fixed = false;    // S1, Q105: Fixed address (`ip`), or Automatic (DHCP)
    net::FixedIp ip;
 };
 // The Saved Networks the Wi-Fi Service may join (see CONTEXT.md), persisted in internal flash.
@@ -28,6 +31,8 @@ class SavedNetworks {
    // Adds, or updates the password of an existing SSID. Empty on success, otherwise why not.
    std::string add(const std::string& ssid, const std::string& password, bool hidden = false);
    void forget(const std::string& ssid);
    // The IP setting: Fixed with these values, or Automatic (DHCP) for nullptr. Empty, or why not.
    std::string setIp(const std::string& ssid, const net::FixedIp* fixed);
   private:
    void save();
@@ -32,17 +32,19 @@ custom_sdkconfig =
    CONFIG_MBEDTLS_DYNAMIC_FREE_CONFIG_DATA=y
    CONFIG_MBEDTLS_DYNAMIC_FREE_CA_CERT=y
 ; Debug Build: the same firmware plus the Debug Console on TCP 2323 (see ADR 0004). The token comes
 ; from ~/.config/roro9stack/debug-token, passed in by scripts/_docker.sh; it's never committed.
 [env:cardputer-adv-debug]
 extends = env:cardputer-adv
 extra_scripts = pre:scripts/version.py, pre:scripts/debug_flags.py
 build_flags =
    ${env:cardputer-adv.build_flags}
    -DRORO_DEBUG
 ; Host-side unit tests for pure logic (no hardware).
 [env:native]
 platform = native
 lib_ldf_mode = deep+
 build_flags = -std=gnu++17
 ; The same tests, built to count which lines of lib/ they run (scripts/coverage.sh).
 [env:native-coverage]
 extends = env:native
 build_flags =
    ${env:native.build_flags}
    --coverage
    -O0
 extra_scripts =
    ${env.extra_scripts}
    pre:scripts/coverage_link.py
@@ -1,10 +1,14 @@
 # Shared helper: run a command inside the roro9stack build container.
 # With RORO_NO_DOCKER set, the caller is in such a container already (a CI job): the command runs
 # right here, in the checkout.
 IMAGE=roro9stack-build
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-docker build -q -t "$IMAGE" "$ROOT/docker" >/dev/null
+[ -n "${RORO_NO_DOCKER:-}" ] || docker build -q -t "$IMAGE" "$ROOT/docker" >/dev/null
-# The Debug Console token (ADR 0004): made once, kept with the OTA key, never committed.
+# The Debug Console token of the developer's device (ADR 0010): made once, kept with the OTA key, never
 # committed and never compiled in. scripts/flash.sh --debug gives it to a device over USB, and
 # scripts/rdbg.py answers the device's challenge with it.
 DEBUG_TOKEN_FILE="$HOME/.config/roro9stack/debug-token"
 if [ ! -s "$DEBUG_TOKEN_FILE" ]; then
    mkdir -p "$(dirname "$DEBUG_TOKEN_FILE")"
@@ -12,6 +16,10 @@ if [ ! -s "$DEBUG_TOKEN_FILE" ]; then
 fi
 run_in_container() {
    if [ -n "${RORO_NO_DOCKER:-}" ]; then
        (cd "$ROOT" && RORO_DEBUG_TOKEN="$(cat "$DEBUG_TOKEN_FILE")" "$@")
        return
    fi
    docker run --rm \
        -u "$(id -u):$(id -g)" -e HOME=/tmp \
        -e RORO_DEBUG_TOKEN="$(cat "$DEBUG_TOKEN_FILE")" \
@@ -1,7 +1,14 @@
 #!/usr/bin/env bash
 # Local CI: run host unit tests, then build the firmware.
 # Usage: scripts/ci.sh [tests|builds]   one half only; both by default
 set -euo pipefail
 source "$(dirname "$0")/_docker.sh"
 DOCKER_EXTRA=()
-run_in_container bash -c 'git config --global --add safe.directory /work && pio test -e native && pio run -e cardputer-adv -e cardputer-adv-debug'
+case "${1:-all}" in
    tests) STEPS='pio test -e native' ;;
    builds) STEPS='pio run -e cardputer-adv' ;;
    all) STEPS='pio test -e native && pio run -e cardputer-adv' ;;
    *) echo "Usage: scripts/ci.sh [tests|builds]" >&2; exit 1 ;;
 esac
 run_in_container bash -c 'git config --global --add safe.directory "$PWD" && '"$STEPS"
@@ -0,0 +1,21 @@
 #!/usr/bin/env bash
 # Runs the host tests and says how much of lib/ they run: they're built with coverage counters.
 # Usage: scripts/coverage.sh [out folder, default .pio/coverage]
 # Out: summary.json (gcovr), coverage.svg (the README's badge), index.html (line by line).
 # What it measures: the lines of lib/ that compile on a PC. Not lib/SD (the card's driver) and not
 # src/ (the Apps, the Services, everything that needs the device): those have no host tests.
 set -euo pipefail
 source "$(dirname "$0")/_docker.sh"
 DOCKER_EXTRA=()
 OUT="${1:-.pio/coverage}"
 run_in_container bash -c '
    set -eo pipefail  # a failing test fails this script, tail or not
    git config --global --add safe.directory "$PWD"
    rm -rf .pio/build/native-coverage "'"$OUT"'"
    mkdir -p "'"$OUT"'"
    pio test -e native-coverage | tail -1
    gcovr -r . --filter "lib/" --object-directory .pio/build/native-coverage \
        --json-summary "'"$OUT"'/summary.json" --html-details "'"$OUT"'/index.html" --print-summary | tail -4
    python3 scripts/coverage_badge.py "'"$OUT"'/summary.json" "'"$OUT"'/coverage.svg"
 '
@@ -0,0 +1,46 @@
 #!/usr/bin/env python3
 """Draws the README's coverage badge from gcovr's summary.
 Usage: scripts/coverage_badge.py <summary.json> <out.svg>
       scripts/coverage_badge.py --plain <label> <value> <out.svg>   any other badge, in blue
 Also prints one line, and appends a short table to $GITHUB_STEP_SUMMARY when CI sets it.
 """
 import json
 import os
 import sys
 def badge(label, value, color, title):
    left, right = 6 * len(label) + 12, 7 * len(value) + 12
    return f'''<svg xmlns="http://www.w3.org/2000/svg" width="{left + right}" height="20" role="img" aria-label="{label}: {value}">
 <title>{title}</title>
 <linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient>
 <clipPath id="r"><rect width="{left + right}" height="20" rx="3" fill="#fff"/></clipPath>
 <g clip-path="url(#r)"><rect width="{left}" height="20" fill="#555"/><rect x="{left}" width="{right}" height="20" fill="{color}"/><rect width="{left + right}" height="20" fill="url(#s)"/></g>
 <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">
 <text x="{left / 2}" y="14">{label}</text><text x="{left + right / 2}" y="14">{value}</text></g></svg>
 '''
 def main():
    if sys.argv[1] == "--plain":  # any other badge: --plain <label> <value> <out.svg>
        label, value, out = sys.argv[2:5]
        open(out, "w").write(badge(label, value, "#007ec6", f"{label}: {value}"))
        return
    summary = json.load(open(sys.argv[1]))
    lines, branches = summary["line_percent"], summary["branch_percent"]
    label, value = "lib coverage", f"{lines:.0f}%"
    color = "#4c1" if lines >= 90 else "#a4a61d" if lines >= 75 else "#dfb317" if lines >= 60 else "#e05d44"
    svg = badge(label, value, color, f"{label}: {value} of the lines of lib/ are run by the host tests")
    open(sys.argv[2], "w").write(svg)
    print(f"coverage of lib/: {lines:.1f}% of {summary['line_total']} lines, {branches:.1f}% of branches, {len(summary['files'])} files")
    step = os.environ.get("GITHUB_STEP_SUMMARY")
    if step:
        worst = sorted((f["line_percent"], f["filename"]) for f in summary["files"] if f["line_total"] >= 10)[:5]
        with open(step, "a") as out:
            out.write(f"### Coverage of `lib/` by the host tests\n\n**{lines:.1f}%** of {summary['line_total']} lines, {branches:.1f}% of branches.\n\n")
            out.write("| Least covered | Lines |\n|---|---|\n" + "".join(f"| `{name}` | {pct:.0f}% |\n" for pct, name in worst))
 if __name__ == "__main__":
    main()
@@ -0,0 +1,4 @@
 # The coverage build must also link with --coverage (build_flags only reaches the compiler).
 Import("env")  # noqa: F821  (provided by PlatformIO)
 env.Append(LINKFLAGS=["--coverage"])  # noqa: F821
@@ -1,12 +0,0 @@
 # Debug Builds only: compiles in the Debug Console token from $RORO_DEBUG_TOKEN (set by _docker.sh
 # from ~/.config/roro9stack/debug-token). Refuses to build without one rather than use a default.
 import os
 import re
 import sys
 Import("env")  # noqa: F821  (provided by PlatformIO)
 token = os.environ.get("RORO_DEBUG_TOKEN", "").strip()
 if not re.fullmatch(r"[0-9a-f]{32}", token):
    sys.exit("debug build: RORO_DEBUG_TOKEN is missing; build through scripts/ci.sh or scripts/flash.sh --debug")
 env.Append(CPPDEFINES=[("RORO_DEBUG_TOKEN", '\\"%s\\"' % token)])  # noqa: F821
@@ -1,17 +1,21 @@
 #!/usr/bin/env bash
 # Flash the firmware over USB, then open the serial monitor.
 # Usage: scripts/flash.sh [--debug] [port]   USB (default: the first Espressif device found)
-#        scripts/flash.sh [--debug] --ota [host]  Wi-Fi: build, sign and push a Firmware Update
+#        scripts/flash.sh --ota [host]       Wi-Fi: build, sign and push a Firmware Update
-#                                                 (host: the device's IP from Settings > About, or $RORO_OTA_HOST)
+#                                            (host: the device's IP from Settings > Firmware, or $RORO_OTA_HOST)
-# --debug builds the Debug Build (cardputer-adv-debug): the Debug Console on TCP 2323, see ADR 0004.
+# --debug (USB only): once flashed, switches the Debug Console on and gives it the token in
 #   ~/.config/roro9stack/debug-token, over the serial port (ADR 0010, Q192), so scripts/rdbg.py works
 #   at once. The settings survive later updates: it is needed once for a device, not at each flash.
 set -euo pipefail
 ENV=cardputer-adv
 PROVISION=
 if [ "${1:-}" = "--debug" ]; then
-    ENV=cardputer-adv-debug
+    PROVISION=1
    shift
 fi
 if [ "${1:-}" = "--ota" ]; then
    [ -z "$PROVISION" ] || echo "flash.sh: --debug does nothing over Wi-Fi: the console's setting stays as it is on the device" >&2
    ROOT="$(cd "$(dirname "$0")/.." && pwd)"
    HOST="${2:-${RORO_OTA_HOST:-}}"
    [ -n "$HOST" ] || { echo "Usage: scripts/flash.sh --ota <device IP> (or set RORO_OTA_HOST)" >&2; exit 1; }
@@ -19,7 +23,6 @@ if [ "${1:-}" = "--ota" ]; then
    DOCKER_EXTRA=()
    run_in_container bash -c "git config --global --add safe.directory /work && pio run -e $ENV" | tail -3
    VERSION="$(git -C "$ROOT" describe --tags --always --dirty)"
    [ "$ENV" = cardputer-adv-debug ] && VERSION="$VERSION+debug"  # as scripts/version.py names it
    OUT="$ROOT/.pio/build/$ENV/roro9stack-$VERSION.ota"
    "$ROOT/scripts/make_ota.py" "$ROOT/.pio/build/$ENV/firmware.bin" "$VERSION" "$OUT"
    exec "$ROOT/scripts/ota_push.py" "$OUT" "$HOST"
@@ -30,4 +33,10 @@ source "$(dirname "$0")/_docker.sh"
 docker rm -f roro9stack-serial >/dev/null 2>&1 || true  # a serial log would hold the port
 DOCKER_EXTRA=(--device "$PORT" --group-add "$(stat -c %g "$PORT")" -it)
-run_in_container bash -c "git config --global --add safe.directory /work && pio run -e $ENV -t upload --upload-port $PORT && pio device monitor -p $PORT -b 115200"
+# The token is read from the environment inside the container (_docker.sh passes it), so it is on no
 # command line of the host; serial_log.py prints what the device says, not what it sends.
 SETUP=""
 # serial_log.py finds the port by its name, and follows it when the device re-enumerates after the upload.
 [ -z "$PROVISION" ] || DOCKER_EXTRA=(--group-add "$(stat -c %g "$PORT")" --privileged -v /dev:/dev -it)
 [ -z "$PROVISION" ] || SETUP='&& /pio/penv/bin/python scripts/serial_log.py 8 sleep:4 "debug token $RORO_DEBUG_TOKEN" "debug on"'
 run_in_container bash -c "git config --global --add safe.directory /work && pio run -e $ENV -t upload --upload-port $PORT $SETUP && pio device monitor -p $PORT -b 115200"
@@ -0,0 +1,49 @@
 #!/usr/bin/env python3
 """Checks an Update File (.ota) the way the device does, on a PC: header, signature, image hash.
 Usage: scripts/ota_verify.py <file.ota> [public key, default keys/ota-public.pem]
 Exits 0 and prints the version if a device would accept the file.
 """
 import hashlib
 import os
 import struct
 import subprocess
 import sys
 import tempfile
 HEADER_SIZE = 160
 SIGNED_BYTES = 80
 def main():
    if len(sys.argv) < 2:
        sys.exit(__doc__)
    root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
    key = sys.argv[2] if len(sys.argv) > 2 else os.path.join(root, "keys", "ota-public.pem")
    data = open(sys.argv[1], "rb").read()
    if len(data) < HEADER_SIZE or data[:8] != b"RORO-OTA":
        sys.exit("not an update file")
    fmt, header_size, image_size = struct.unpack("<HHI", data[8:16])
    if fmt != 1 or header_size != HEADER_SIZE:
        sys.exit("unsupported update format")
    image = data[HEADER_SIZE:]
    if len(image) != image_size:
        sys.exit(f"the header announces {image_size} bytes of image, the file has {len(image)}")
    if hashlib.sha256(image).digest() != data[16:48]:
        sys.exit("image corrupted (hash mismatch)")
    version = data[48:80].split(b"\0")[0].decode()
    (sig_len,) = struct.unpack("<H", data[80:82])
    with tempfile.NamedTemporaryFile() as signed, tempfile.NamedTemporaryFile() as sig:
        signed.write(data[:SIGNED_BYTES])
        signed.flush()
        sig.write(data[82:82 + sig_len])
        sig.flush()
        ok = subprocess.run(["openssl", "dgst", "-sha256", "-verify", key, "-signature", sig.name, signed.name],
                            capture_output=True).returncode == 0
    if not ok:
        sys.exit("bad signature (wrong key)")
    print(f"{sys.argv[1]}: {version}, {image_size} bytes, signature good")
 if __name__ == "__main__":
    main()
@@ -1,10 +1,12 @@
 #!/usr/bin/env python3
-"""The Debug Console of a Debug Build, over Wi-Fi (TCP 2323, see ADR 0004).
+"""The Debug Console, over Wi-Fi (TCP 2323, see ADR 0010). Switch it on first: Settings > Debug Console.
-Usage: scripts/rdbg.py [-H host] [-b] [command ...]
+Usage: scripts/rdbg.py [-H host] [-t token] [-b] [command ...]
  no command   interactive: type commands, see every console line live; Ctrl-D or `quit` leaves
  command      runs it and prints what follows, until the console has been quiet for a moment
-  -H host      the device's IP (Settings > Firmware), default $RORO_OTA_HOST
+  -H host      the device's IP (Settings > Debug Console), default $RORO_OTA_HOST
  -t token     the device's token (also --token), as Settings > Debug Console shows it: dashes and
               case don't matter. Otherwise $RORO_DEBUG_TOKEN, otherwise ~/.config/roro9stack/debug-token
  -b           also print the backlog the device sends on connecting (boot messages and so on)
 Commands handled here as well as on the device:
@@ -14,9 +16,11 @@ Commands handled here as well as on the device:
  put <file> [card path]   copy a file to the SD card (default /updates/<name>), checked with SHA-256
  screenshot [file.png]    what the screen shows (default screen-<date>.png), at 2x
  reset                    restart at once, even if the main loop is stuck
-The token is read from ~/.config/roro9stack/debug-token (made by the first build).
+The token never crosses the network: the device sends a challenge, and this answers with its HMAC.
 """
 import gzip
 import hashlib
 import hmac
 import os
 import re
 import select
@@ -26,9 +30,53 @@ import zlib
 import socket
 import sys
 import time
 import urllib.request
 PORT = 2323
 TOKEN_FILE = os.path.expanduser("~/.config/roro9stack/debug-token")
 RELEASES = "https://git.twis.la/twisla/roro9stack/releases/download"
 def tidy_token(typed):
    """As the device stores it (lib/debug/src/debug_auth.cpp): no dashes or spaces, in capitals."""
    tidy = "".join(c for c in typed if c not in "- \t\r\n").upper()
    return tidy.replace("O", "0").replace("I", "1").replace("L", "1")  # read as the digits they look like
 def answer_for(token, nonce):
    """What the device expects back for a challenge: HMAC-SHA256 of the nonce, keyed by the token."""
    return hmac.new(token.encode(), nonce, hashlib.sha256).hexdigest()
 def find_token(given):
    token = given or os.environ.get("RORO_DEBUG_TOKEN")
    if not token and os.path.exists(TOKEN_FILE):
        token = open(TOKEN_FILE).read()
    token = tidy_token(token or "")
    if not token:
        sys.exit("No token: pass -t <token>, set RORO_DEBUG_TOKEN, or put it in " + TOKEN_FILE +
                 "\n(the device shows it in Settings > Debug Console)")
    return token
 def log_in(sock, token):
    """Answers the device's challenge; returns the banner line, or exits saying what went wrong."""
    first = read_until(sock, b"\n", 10)
    if first is None:
        sys.exit("device: nothing came back. Is the console switched on (Settings > Debug Console)?")
    line = first.decode(errors="replace").strip()
    if line.startswith("locked"):
        sys.exit("device: closed for a minute after too many wrong tokens")
    challenge = re.search(r"challenge ([0-9a-f]{32})$", line)
    if not challenge:
        sys.exit("device: no challenge (an older firmware?): " + line[:60])
    sock.sendall((answer_for(token, bytes.fromhex(challenge.group(1))) + "\n").encode())
    banner = read_until(sock, b"\n", 15)
    if banner is None:
        sys.exit("device: no answer")
    if banner.startswith(b"denied"):
        sys.exit("device: wrong token (Settings > Debug Console shows the right one)")
    return banner
 def read_until(sock, marker, timeout):
@@ -102,17 +150,40 @@ def crash_firmware(reply):
    return version.group(1) if version else None
 def have_elf(reply):
    """Makes sure .pio/elves/ holds the ELF of the firmware that crashed: a release's is on Gitea."""
    folder = os.path.join(os.path.dirname(SCRIPTS), ".pio", "elves")
    key = crash_firmware(reply)
    version = re.search(r"last one in (\S+)", reply)
    version = version.group(1) if version else None
    names = os.listdir(folder) if os.path.isdir(folder) else []
    if not key or any(key in n for n in names) or not version or not re.fullmatch(r"v\d+\.\d+\.\d+", version):
        return  # there already, or not a release: only tags are published
    url = f"{RELEASES}/{version}/roro9stack-{version}.elf.gz"
    try:
        elf = gzip.decompress(urllib.request.urlopen(url, timeout=60).read())
    except Exception as e:
        return print(f"(no ELF for {version} here, and none fetched from {url}: {e})")
    digest = hashlib.sha256(elf).hexdigest()[:16]
    os.makedirs(folder, exist_ok=True)
    path = os.path.join(folder, f"{version}.{digest}.elf")  # as scripts/version.py names them
    open(path, "wb").write(elf)
    print(f"(fetched the ELF of {version} from its release: {os.path.relpath(path)})")
 def crash(sock):
    reply = run(sock, "crash")
    trace = re.search(r"backtrace((?: 0x[0-9a-f]+)+)", reply)
    key = crash_firmware(reply)
    if trace and key:
        have_elf(reply)
        print()
        subprocess.call([os.path.join(SCRIPTS, "decode_backtrace.sh"), key] + trace.group(1).split())
 def coredump(sock, path):
    info = run(sock, "crash", out=None)
    have_elf(info)
    sock.sendall(b"coredump get\n")
    # One buffer throughout: the header, the size and the first bytes often share a packet.
    buf = b""
@@ -224,33 +295,40 @@ def interactive(sock):
            sys.stdout.write(data.decode(errors="replace"))
            sys.stdout.flush()
        if sys.stdin in ready:
-            line = sys.stdin.readline()
+            # Straight from the descriptor: readline() takes every waiting line into Python's own
-            if not line:
+            # buffer and hands over one, and select() then sees nothing more to read. Piped input
            # written while we were still connecting got stuck until the next line came.
            data = os.read(sys.stdin.fileno(), 4096)
            if not data:
                return
-            sock.sendall(line.encode())
+            sock.setblocking(True)
            sock.sendall(data)
            sock.setblocking(False)
 def main():
    args = sys.argv[1:]
-    host, backlog = os.environ.get("RORO_OTA_HOST"), False
+    host, backlog, token = os.environ.get("RORO_OTA_HOST"), False, None
    while args and args[0].startswith("-"):
        flag = args.pop(0)
        if flag == "-H" and args:
            host = args.pop(0)
        elif flag in ("-t", "--token") and args:
            token = args.pop(0)
        elif flag == "-b":
            backlog = True
        else:
            sys.exit(__doc__)
    if not host:
        sys.exit("No device: pass -H <ip> or set RORO_OTA_HOST\n\n" + __doc__)
-    token = open(TOKEN_FILE).read().strip()
+    token = find_token(token)
-    with socket.create_connection((host, PORT), timeout=10) as sock:
+    try:
-        sock.sendall((token + "\n").encode())
+        sock = socket.create_connection((host, PORT), timeout=10)
-        # The device may still be finishing a previous client: wait for this connection's banner.
+    except OSError as e:
-        banner = read_until(sock, b"Backlog follows.\n", 15)
+        sys.exit(f"device: can't connect to {host}:{PORT} ({e}). Is the console switched on (Settings > Debug Console)?")
-        if banner is None:
+    with sock:
-            sys.exit("device: no banner (wrong token, or another client is connected)")
+        banner = log_in(sock, token)
        show = sys.stdout if backlog or not args else None
        if show:
            show.write(banner.decode(errors="replace"))
@@ -0,0 +1,62 @@
 #!/usr/bin/env bash
 # Builds what a release publishes, from a checkout of the repository at a tag (docs/milestones/R1.md).
 # Usage: scripts/release_build.sh <checkout> <out folder>
 #   <checkout>   a clone with its tags, at the commit to release: its own sources are built, with
 #                this copy's build image and signing tools, so an old tag can be released today.
 # The signing key is read from $RORO_OTA_KEY (a file), as scripts/make_ota.py does.
 # Out: roro9stack-<version>.ota (signed, checked), -factory.bin (USB), .elf.gz (to decode crashes),
 #      SHA256SUMS, and notes.md for the release's text.
 set -euo pipefail
 SRC="$(cd "$1" && pwd)"
 mkdir -p "$2"
 OUT="$(cd "$2" && pwd)"
 TOOLS="$(cd "$(dirname "$0")" && pwd)"
 VERSION="$(git -C "$SRC" describe --tags --always --dirty)"
 case "$VERSION" in
    *-dirty) echo "release: $SRC has uncommitted changes ($VERSION)" >&2; exit 1 ;;
 esac
 git -C "$SRC" describe --tags --exact-match >/dev/null 2>&1 || { echo "release: $VERSION is not a tag" >&2; exit 1; }
 source "$TOOLS/_docker.sh"
 ROOT="$SRC"  # _docker.sh mounts $ROOT as /work: the checkout to build, not necessarily this copy
 DOCKER_EXTRA=()
 # A tag from before the framework was rebuilt with our settings (ADR 0006) can't link against a
 # rebuilt one left in the toolchain cache: it gets the framework's libraries as they come.
 if ! grep -q custom_sdkconfig "$SRC/platformio.ini"; then
    run_in_container bash -c 'rm -rf "${PLATFORMIO_CORE_DIR:-/pio}/packages/framework-arduinoespressif32-libs"'
 fi
 run_in_container bash -c 'git config --global --add safe.directory "$PWD" && pio run -e cardputer-adv'
 BUILD="$SRC/.pio/build/cardputer-adv"
 NAME="roro9stack-$VERSION"
 "$TOOLS/make_ota.py" "$BUILD/firmware.bin" "$VERSION" "$OUT/$NAME.ota"
 # A wrong key must stop the release here, not on a device: checked against the public key the
 # sources being built carry (the tags from before Firmware Updates have none: today's, then).
 PUBLIC="$SRC/keys/ota-public.pem"
 [ -e "$PUBLIC" ] || PUBLIC="$TOOLS/../keys/ota-public.pem"
 "$TOOLS/ota_verify.py" "$OUT/$NAME.ota" "$PUBLIC"
 cp "$BUILD/firmware.factory.bin" "$OUT/$NAME-factory.bin"
 gzip -9 -c "$BUILD/firmware.elf" > "$OUT/$NAME.elf.gz"
 (cd "$OUT" && sha256sum "$NAME.ota" "$NAME-factory.bin" "$NAME.elf.gz" > SHA256SUMS)
 # The release's text: what the tag says, then what went in since the tag before.
 PREVIOUS="$(git -C "$SRC" describe --tags --abbrev=0 "$VERSION^" 2>/dev/null || true)"
 {
    git -C "$SRC" tag -l --format='%(contents)' "$VERSION" | sed -e '/^-----BEGIN PGP/,$d'
    echo
    echo "## Files"
    echo
    echo "- \`$NAME.ota\`: the signed Update File. Copy it to \`/updates\` on the SD card and install it from Settings > Firmware or the Storage App, or push it over Wi-Fi with \`scripts/ota_push.py\`."
    echo "- \`$NAME-factory.bin\`: the whole flash image, for a first install over USB at offset 0."
    echo "- \`$NAME.elf.gz\`: the symbols, to decode a crash report from this build."
    echo "- \`SHA256SUMS\`: checksums of the three."
    if [ -n "$PREVIOUS" ]; then
        echo
        echo "## Changes since $PREVIOUS"
        echo
        git -C "$SRC" log --no-merges --format='- %s' "$PREVIOUS..$VERSION"
    fi
 } > "$OUT/notes.md"
 echo "$VERSION" > "$OUT/version"
 ls -l "$OUT"
@@ -0,0 +1,65 @@
 #!/usr/bin/env python3
 """Creates or completes a Gitea release from what scripts/release_build.sh made.
 Usage: scripts/release_publish.py <folder>
 Environment: GITEA_API (https://host/api/v1), GITEA_REPO (owner/name), GITEA_TOKEN.
 Run again for the same version, it replaces the files and the text instead of failing.
 """
 import json
 import os
 import sys
 import urllib.error
 import urllib.parse
 import urllib.request
 API = os.environ.get("GITEA_API", "").rstrip("/")
 REPO = os.environ.get("GITEA_REPO", "")
 TOKEN = os.environ.get("GITEA_TOKEN", "")
 def call(method, path, body=None, raw=None, content_type="application/json"):
    data = raw if raw is not None else (json.dumps(body).encode() if body is not None else None)
    request = urllib.request.Request(f"{API}/repos/{REPO}{path}", data=data, method=method)
    request.add_header("Authorization", f"token {TOKEN}")
    if data is not None:
        request.add_header("Content-Type", content_type)
    try:
        with urllib.request.urlopen(request, timeout=300) as response:
            text = response.read()
            return response.status, json.loads(text) if text else None
    except urllib.error.HTTPError as e:
        return e.code, e.read().decode(errors="replace")[:300]
 def main():
    if len(sys.argv) != 2 or not (API and REPO and TOKEN):
        sys.exit(__doc__)
    folder = sys.argv[1]
    version = open(os.path.join(folder, "version")).read().strip()
    notes = open(os.path.join(folder, "notes.md")).read()
    files = sorted(f for f in os.listdir(folder) if f not in ("version", "notes.md"))
    status, release = call("GET", f"/releases/tags/{urllib.parse.quote(version)}")
    fields = {"tag_name": version, "name": f"roro9stack {version}", "body": notes, "draft": False, "prerelease": False}
    if status == 200:
        status, release = call("PATCH", f"/releases/{release['id']}", fields)
    else:
        status, release = call("POST", "/releases", fields)
    if status not in (200, 201):
        sys.exit(f"release: Gitea answered {status}: {release}")
    for asset in release.get("assets") or []:  # a second run replaces what the first uploaded
        if asset["name"] in files:
            call("DELETE", f"/releases/{release['id']}/assets/{asset['id']}")
    for name in files:
        with open(os.path.join(folder, name), "rb") as f:
            status, answer = call("POST", f"/releases/{release['id']}/assets?name={urllib.parse.quote(name)}", raw=f.read(),
                                  content_type="application/octet-stream")
        if status != 201:
            sys.exit(f"release: uploading {name}: Gitea answered {status}: {answer}")
        print(f"uploaded {name} ({answer['size']} bytes)")
    print(f"published {release['html_url']}")
 if __name__ == "__main__":
    main()
@@ -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
@@ -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"
@@ -10,10 +10,15 @@ try:
 except Exception:
    version = "unknown"
-if env["PIOENV"].endswith("-debug"):  # noqa: F821
+# The version goes into one generated header, read by one file (lib/version/src/version.cpp). As a -D
-    version += "+debug"  # a Debug Build says so wherever the version shows
+# 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
-env.Append(CPPDEFINES=[("RORO_VERSION", '\\"%s\\"' % version)])  # noqa: F821
+_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
@@ -0,0 +1,45 @@
 # The roro9stack site
 Source of https://roro9stack.net (docs/milestones/W1.md): a [Zola](https://www.getzola.org/) site. The home page, an Install page with a browser flasher, and the list of releases so far; the user guide, how-tos, FAQ and developer docs come next.
 ```
 config.toml           base_url, the repository and API addresses
 content/              the pages (Markdown, with their template named in the front matter)
 templates/            base, home, install, downloads, 404; illustrations/ is generated
 data/                 the App cards and the screenshots' captions
 static/               css, js, fonts (self-hosted), img, screens (real screenshots), vendor/esp-web-tools
 tools/                make_illustrations.py, check_site.py
 ```
 ## Build and look
 ```sh
 docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/repo" -w /repo/site ghcr.io/getzola/zola:v0.22.0 build   # writes ./public
 docker run --rm -u "$(id -u):$(id -g)" -p 1111:1111 -v "$PWD:/repo" -w /repo/site ghcr.io/getzola/zola:v0.22.0 serve --interface 0.0.0.0
 python3 site/tools/check_site.py public    # what the pages promise, kept
 ```
 Or `zola build` with a Zola of your own, in `site/` (or `zola --root site build` from the root). **The output goes to `public/` at the root of the repository,** not into `site/`: `output_dir` in `config.toml`, and git ignores that directory. The build reads the latest release and the list of releases from the Gitea API (`load_data`); if the server can't be reached, the pages say so instead of failing.
 ## Publishing
 The web server pulls `main` and runs `zola build`, as for the blog. CI (`.gitea/workflows/site.yml`) builds the site and runs the checks when `site/`, `docs/`, `README.md` or `CONTEXT.md` change; the firmware workflow skips a change that touches only those.
 ## Things to know
 - **The Install page needs Caddy's help.** Gitea's release downloads carry no CORS header, so the page asks the API from the browser only if Caddy, in front of Gitea, allows this origin:
  ```caddy
  @releases {
      method GET HEAD
      path /twisla/roro9stack/releases/download/* /api/v1/repos/twisla/roro9stack/releases*
  }
  header @releases Access-Control-Allow-Origin "https://roro9stack.net"
  header @releases Vary Origin
  ```
  Without it the page says it can't reach the release server and points to the esptool steps.
 - **No third-party requests.** Fonts and the flasher library are served from here; `tools/check_site.py` fails the build if a page loads anything from another origin.
 - **Illustrations.** `templates/illustrations/*.html` are generated by `tools/make_illustrations.py`; run it again rather than editing them.
 - **Updating the flasher library:** see `static/vendor/esp-web-tools/README.txt`.
 - **Fonts** are DM Mono and Hanken Grotesk, under the SIL Open Font License (the licences are in `static/fonts/`).
@@ -0,0 +1,28 @@
 # roro9stack.net (docs/milestones/W1.md). Build with `zola build`; the web server pulls main and does this.
 base_url = "https://roro9stack.net"
 title = "roro9stack"
 description = "Open firmware for the M5Stack Cardputer ADV with the Cap LoRa-1262: a LoRa scanner, GNSS, a Gemini browser, IRC, Wi-Fi tools, notes and more."
 default_language = "en"
 compile_sass = false
 build_search_index = false
 generate_feeds = false  # the devlog turns its own on (content/devlog/_index.md)
 feed_filenames = ["atom.xml"]
 # The built site goes to public/ at the root of the repository (git ignores it), whether Zola is run
 # from site/ or from the root with `--root site`.
 output_dir = "../public"
 [markdown]
 smart_punctuation = false
 [markdown.highlighting]
 # Classes instead of inline colours; Zola 0.22 still wants a theme and writes giallo.css, which the
 # templates don't link.
 style = "class"
 theme = "nord"
 [extra]
 author = "twisla"
 repo = "https://git.twis.la/twisla/roro9stack"
 api = "https://git.twis.la/api/v1/repos/twisla/roro9stack"
 blog = "https://experiments.twis.la"
 contact = "contact@roro9stack.net"
@@ -0,0 +1,4 @@
 +++
 title = "roro9stack"
 template = "index.html"
 +++
@@ -0,0 +1,13 @@
 +++
 title = "Developer docs"
 description = "How roro9stack is built, debugged, tested and released: the Debug Console, the build, the decisions and the plans, from the repository's own documents."
 template = "dev-index.html"
 sort_by = "weight"
 [extra]
 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 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.
@@ -0,0 +1,13 @@
 +++
 title = "Build, test and release"
 description = "Building the firmware, running the tests, flashing a device, and what happens between a commit and a release."
 template = "guide-index.html"
 page_template = "guide-page.html"
 sort_by = "weight"
 weight = 2
 [extra]
 eyebrow = "Developer docs"
 +++
 The firmware is built, tested and released **in Docker**, so that a clean machine, your machine and the CI runner all get the same result. These pages say how. For the Debug Console, which is how you work on a device once it is flashed, see [The Debug Console](/dev/debug/).
@@ -0,0 +1,38 @@
 +++
 title = "Build, test and release"
 description = "Docker is the only tool you need. How the firmware is built, how the host tests run, and what CI does on a pull request and on a tag."
 weight = 1
 [extra]
 docs = true
 source = "README.md"
 tag = "Build"
 +++
 ## 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.
 ## Build and test (local CI)
 ```sh
 scripts/ci.sh
 ```
 This runs the host-side unit tests (`test/`, `native` environment), then builds the firmware. The output is `.pio/build/cardputer-adv/firmware.factory.bin`.
 `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 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
 Gitea Actions (`.gitea/workflows/ci.yml`, docs/milestones/R1.md) runs the host tests on every push to `main`, and on a pull request also builds the firmware: changes reach `main` through pull requests. Pushing a tag `v*` runs all of it and publishes a release on Gitea with:
 - `roro9stack-<version>.ota`, the signed Update File;
 - `roro9stack-<version>-factory.bin`, the whole flash image for a first install over USB;
 - `roro9stack-<version>.elf.gz`, to decode crash reports from that build;
 - `SHA256SUMS`.
 CI signs with the project's key, held as a repository secret (ADR 0008). There is one firmware: the Debug Console is in every build, switched off until its owner switches it on (ADR 0010).
 `scripts/ota_verify.py <file.ota>` checks an Update File on a PC the way a device does. `scripts/release_build.sh` and `scripts/release_publish.py` are what the workflow runs; they work the same by hand.
@@ -0,0 +1,57 @@
 +++
 title = "Flash and update"
 description = "Put the firmware on a Cardputer over USB, then update it over Wi-Fi or from the SD card, and from the project's releases."
 weight = 2
 [extra]
 docs = true
 source = "README.md"
 tag = "Flash"
 +++
 ## Flash
 1. Connect the Cardputer by USB-C.
 2. Run:
   ```sh
   scripts/flash.sh            # auto-detects the port; or: scripts/flash.sh /dev/ttyACM1
   ```
   This uploads the firmware, then opens the serial monitor. Quit the monitor with `Ctrl+C`.
 **If the upload can't connect,** put the device in download mode: hold **G0** (the button next to the screen) while plugging in USB, or while pressing reset. Then retry.
 **If you get "permission denied" on the port,** your user needs access to the serial device. Run this once, then log out and back in:
 ```sh
 sudo usermod -aG dialout "$USER"
 ```
 ## Firmware Updates over Wi-Fi (OTA)
 Once the Cardputer runs an OTA-capable firmware (flashed once over USB), updates can go over Wi-Fi:
 ```sh
 scripts/ota_keygen.sh                  # once: creates the signing key (see ADR 0003)
 scripts/flash.sh --ota 10.39.39.12     # build, sign and push; or set RORO_OTA_HOST
 ```
 The device shows the push address in **Settings → Firmware**. It installs a correctly signed update right away, restarts (waiting up to 60 s if you're typing), and runs the new firmware on **Probation**. If the new firmware crashes, or can't reconnect Wi-Fi within 3 minutes, it rolls back to the previous one and says so.
 To install from the SD card instead, copy the `.ota` file from `.pio/build/cardputer-adv/` into `/updates` on the card, then use **Settings → Firmware**. With the Cardputer on USB, the card can stay in: `scripts/sd_put.sh <file.ota>` sends it over the serial console into `/updates` (about 30 s for 1.6 MB, checked with SHA-256 before it's renamed into place; `SD_PUT_DEBUG=1` shows the console while it runs).
 **The private key** lives in `~/.config/roro9stack/ota-key.pem` and must never be committed. If it's lost, generate a new pair and flash once over USB. (CI signs releases with a copy kept as a repository secret, ADR 0008.)
 ### Updates from Gitea
 With no PC and no card, the device can install the project's releases itself (docs/milestones/R1.md). In **Settings → Firmware**:
 - **Latest release** checks the server (Enter, or `c`) and says `v0.11.0 (new)` or `(current)`. Enter again opens the release: its version, date, size and the tag's message, with **Install** when it's newer. The download goes straight into the inactive slot, so no card is needed; the signature is checked after the first 160 bytes, before anything is written, and the image's hash at the end. The new firmware then runs on Probation as for any update.
 - **Older releases** lists the last ten, newest first. Opening an older one offers to go back to it, with a different question.
 - **Settings → Check for updates** (on by default): once a day, with Wi-Fi up and the clock set, the device looks at the latest release and says `v0.11.0 is out: see Settings > Firmware`, once per version. It installs nothing by itself, and doesn't announce a version that already failed and rolled back on this device.
 The connection is checked against the two ISRG roots Let's Encrypt chains end in (ADR 0009), not the usual bundle of about 130 authorities. Whatever the connection, the Update File's own signature is what decides what gets installed.
 **IRC steps aside.** A secure connection takes about 52 KB of memory at its peak, and IRC's own takes 40 KB of the 107 KB there is. A check or an install you ask for makes IRC disconnect for the few seconds it takes and reconnect afterwards. The daily check never does that: with IRC connected it waits for a moment when IRC isn't, so while IRC stays connected for days it doesn't run, and **Latest release** is the way to check.
 **There is no separate Debug Build** any more (ADR 0010): every firmware installs releases, and the Debug Console is a setting, which an update leaves as it was.
@@ -0,0 +1,63 @@
 +++
 title = "How an update works"
 description = "The signed Update File, the four ways to get one onto a device, Probation and Rollback, and the check that sits in front of all of them."
 weight = 3
 [extra]
 tag = "Updates"
 diagrams = true
 +++
 A **Firmware Update** installs one signed file, an **Update File** (`.ota`). Every way of delivering it ends at the same gate, and a new firmware must prove itself before it is kept. The decisions are [ADR 0003](/dev/decisions/0003-own-signature-check-not-secure-boot/) (the signature), [ADR 0005](/dev/decisions/0005-safe-mode-crash-reports-watchdog/) (when the new firmware crashes) and [ADR 0008](/dev/decisions/0008-ci-signs-releases/) (who signs releases).
 ## The Update File
 {{ diagram(src="update-file.svg", min_width=580, caption="A 160-byte header, then the image. Bytes 0 to 79 are signed.") }}
 - A **160-byte header**: the magic `RORO-OTA`, the format, the header size, the image size, the image's **SHA-256** and the version (bytes 0 to 79, the signed part), then the signature's length, the **signature** and reserved bytes.
 - The signature is **ECDSA P-256 over the SHA-256 of bytes 0 to 79**, checked by the firmware against a **public key compiled into it** (`keys/ota-public.pem`, committed), **before anything is written**.
 - Then the **image**, hashed while it is written; at the end the hash must equal the one in the header.
 Make, check and push one:
 ```sh
 scripts/ota_keygen.sh                                  # once: creates the key pair. The private key goes to ~/.config/roro9stack/ota-key.pem (never committed); the public key to keys/ and the firmware source
 scripts/make_ota.py firmware.bin v0.12.0 out.ota       # wraps and signs an image (the key: $RORO_OTA_KEY or the default path)
 scripts/ota_verify.py out.ota                          # checks a file the way a device does, on the PC
 scripts/ota_push.py out.ota 10.39.39.12                # pushes it to the Update Service, TCP 3232
 scripts/flash.sh --ota 10.39.39.12                     # builds, signs and pushes in one go
 ```
 `ota_push.py` prints the device's answer (`OK …`), or says the device **refused the update and hung up**, with the reason on the device's screen: the header is checked first, so a refused file stops mid-transfer.
 ## Four ways in, one gate
 {{ diagram(src="ways-in.svg", min_width=580, caption="Every path ends at the same Update Service and the same signature check.") }}
 1. **Push over Wi-Fi** to TCP 3232: `scripts/flash.sh --ota`. The device always listens while Wi-Fi is connected.
 2. **From the SD card**: a `.ota` in `/updates`, installed from Settings → Firmware, from the Storage App, or with the `install <path>` command. Put it there by hand, with `scripts/rdbg.py put` over Wi-Fi, or with `scripts/sd_put.sh` over USB.
 3. **From the project's releases** on Gitea, which the device downloads itself over TLS (Settings → Firmware, or `update check` / `update install <tag>`): see [Flash and update](/dev/build/flash/).
 All three feed the same parser: the **header and signature are checked first**, the image is written to the **other app slot** while it is hashed, and the slot becomes the next boot **only if the hash matches**. Anything wrong ends in a Toast and **nothing changes**. A downgrade is allowed, and shows "older than the installed version".
 The device then restarts (waiting up to 60 seconds if you are typing) into **Probation**.
 ## Probation and Rollback
 {{ diagram(src="probation.svg", min_width=620, caption="The life of an update: install, restart, Probation, confirmed. A crash or a restart before the last step sends the device back to the previous firmware.") }}
 A new image is **not trusted** at first:
 1. **Install:** the image goes to the other slot and the OTA data marks it *new*.
 2. **Restart:** the bootloader turns *new* into *pending verify* and boots it.
 3. **Probation:** the new firmware must boot, draw its UI, start its Services, run **30 seconds without a crash**, and **reconnect Wi-Fi within 3 minutes** if one is configured.
 4. **Confirmed:** it marks itself valid and a Toast says `Updated`.
 If it crashes or restarts first, the bootloader marks the image *aborted* and boots the **previous firmware** again, which says the update failed. Meanwhile that previous firmware stayed in its slot: it is the way back.
 **Two lines of defence.** The bootloader's rollback is the first. The firmware counts its own boots on Probation, very first thing in `setup()`, and reverts itself on the second unconfirmed start, as a second line. And Arduino-ESP32 normally marks an image valid *before* `setup()` runs, which once hid the bootloader's rollback entirely; the firmware overrides `verifyRollbackLater()` so an image stays pending until Probation confirms it.
 ## Who signs releases
 A tag `v*` is built, signed and published by Gitea Actions, with the signing key held as a repository secret as well as on the maintainer's machine ([ADR 0008](/dev/decisions/0008-ci-signs-releases/) says what that costs and what limits it). The release step checks the signed file against the public key in the sources it built, so a wrong secret stops the release instead of publishing a file no device accepts.
 **If the private key is ever lost,** the next update has to go over USB, carrying a new public key. Someone with USB access can always flash anything: only Wi-Fi and SD card updates are guarded, by design (ADR 0003).
@@ -0,0 +1,55 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 316" role="img" aria-label="The life of an update. One: install, the image goes to app1 and the OTA data marks it NEW. Two: restart, the bootloader turns NEW into PENDING_VERIFY and boots app1. Three: Probation, 30 seconds up, a frame drawn, and Wi-Fi within 3 minutes if it is configured. Four: confirmed, the firmware marks itself VALID and a Toast says Updated. If it crashes or restarts before step four, the bootloader turns PENDING_VERIFY into ABORTED and boots app0 again, which says the update failed. Meanwhile app0 kept the previous firmware: the way back. The trap, under step two: Arduino's initArduino marks the image VALID before setup runs, unless verifyRollbackLater returns true.">
  <defs>
    <marker id="pb-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="currentColor"/></marker>
    <marker id="pb-arrow-ok" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="f-green" d="M0,0 L10,5 L0,10 z"/></marker>
    <marker id="pb-arrow-bad" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="f-red" d="M0,0 L10,5 L0,10 z"/></marker>
  </defs>
  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor">
    <rect class="pb-box" x="16" y="40" width="170" height="80" rx="6"/>
    <text x="28" y="62" font-size="12" font-weight="600">1 install</text>
    <text x="28" y="84" font-size="11">image → app1</text>
    <text x="28" y="102" font-size="11" class="pb-dim">otadata: NEW</text>
    <rect class="pb-box" x="206" y="40" width="170" height="80" rx="6"/>
    <text x="218" y="62" font-size="12" font-weight="600">2 restart</text>
    <text x="218" y="84" font-size="11">bootloader:</text>
    <text x="218" y="102" font-size="11" class="pb-dim">NEW → PENDING_VERIFY</text>
    <rect class="pb-hot" x="396" y="40" width="170" height="80" rx="6"/>
    <text x="408" y="62" font-size="12" font-weight="600">3 Probation</text>
    <text x="408" y="84" font-size="11">30 s up, a frame</text>
    <text x="408" y="102" font-size="11" class="pb-dim">Wi-Fi within 3 min</text>
    <rect class="pb-ok" x="586" y="40" width="158" height="80" rx="6"/>
    <text x="598" y="62" font-size="12" font-weight="600">4 confirmed</text>
    <text x="598" y="84" font-size="11">→ VALID</text>
    <text x="598" y="102" font-size="11" class="pb-dim">Toast: Updated to…</text>
    <path class="pb-line" d="M186 80 H202" marker-end="url(#pb-arrow)"/>
    <path class="pb-line" d="M376 80 H392" marker-end="url(#pb-arrow)"/>
    <path class="pb-line-ok" d="M566 80 H582" marker-end="url(#pb-arrow-ok)"/>
    <rect class="pb-bad" x="396" y="196" width="348" height="76" rx="6"/>
    <text x="408" y="218" font-size="12" font-weight="600">crash or restart before 4</text>
    <text x="408" y="240" font-size="11">bootloader: PENDING_VERIFY → ABORTED</text>
    <text x="408" y="258" font-size="11" class="pb-dim">boots app0: "Update to … failed"</text>
    <path class="pb-line-bad" d="M481 120 V192" marker-end="url(#pb-arrow-bad)"/>
    <text x="408" y="294" font-size="10" class="pb-dim">(second line: bootGuard() in setup() rolls back</text>
    <text x="408" y="308" font-size="10" class="pb-dim"> a second unconfirmed start by itself)</text>
    <text x="16" y="216" font-size="11" class="pb-dim">app0 keeps the</text>
    <text x="16" y="232" font-size="11" class="pb-dim">previous firmware:</text>
    <text x="16" y="248" font-size="11" class="pb-dim">the way back</text>
    <rect class="pb-trap" x="206" y="176" width="170" height="122" rx="6"/>
    <text class="f-red" x="218" y="198" font-size="12" font-weight="600">the trap</text>
    <text x="218" y="220" font-size="11">initArduino()</text>
    <text x="218" y="238" font-size="11">marks it VALID</text>
    <text x="218" y="256" font-size="11">before setup(),</text>
    <text x="218" y="274" font-size="11" class="pb-dim">unless verify-</text>
    <text x="218" y="290" font-size="11" class="pb-dim">RollbackLater()</text>
    <path class="pb-line-bad" d="M291 176 V124" marker-end="url(#pb-arrow-bad)"/>
    <text x="16" y="22" font-size="13" font-weight="600">The life of an update</text>
  </g>
 </svg>
@@ -0,0 +1,43 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 196" role="img" aria-label="The Update File: a 160-byte header, then the firmware image. Bytes 0 to 79 are signed: the magic RORO-OTA, the format, the header size, the image size, the image's SHA-256 and the version. Then the signature's length, the signature itself, and reserved bytes up to 160. The signature is ECDSA P-256 over the SHA-256 of bytes 0 to 79, checked before anything is written. The image follows, hashed while it is written, and must match the hash in bytes 16 to 47.">
  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor">
    <text x="16" y="22" font-size="13" font-weight="600">Update File (.ota)</text>
    <text x="16" y="40" font-size="11" class="uf-dim">a 160-byte header, little-endian, then the image</text>
    <rect class="uf-signed" x="16" y="72" width="380" height="40" rx="4"/>
    <rect class="uf-cell" x="16" y="72" width="64" height="40"/>
    <rect class="uf-cell" x="80" y="72" width="40" height="40"/>
    <rect class="uf-cell" x="120" y="72" width="40" height="40"/>
    <rect class="uf-cell" x="160" y="72" width="52" height="40"/>
    <rect class="uf-cell" x="212" y="72" width="100" height="40"/>
    <rect class="uf-cell" x="312" y="72" width="84" height="40"/>
    <rect class="uf-cell" x="396" y="72" width="40" height="40"/>
    <rect class="uf-cell" x="436" y="72" width="92" height="40"/>
    <rect class="uf-cell" x="528" y="72" width="32" height="40"/>
    <rect class="uf-image" x="560" y="72" width="184" height="40"/>
    <g font-size="10" text-anchor="middle">
      <text x="48" y="96">RORO-OTA</text>
      <text x="100" y="96">fmt</text>
      <text x="140" y="96">hdr</text>
      <text x="186" y="96">size</text>
      <text x="262" y="96">image SHA-256</text>
      <text x="354" y="96">version</text>
      <text x="416" y="96">len</text>
      <text x="482" y="96">signature</text>
      <text x="544" y="96">0…</text>
      <text x="652" y="96">the image, ~1.6 MB</text>
    </g>
    <g font-size="10" class="uf-dim" text-anchor="middle">
      <text x="16" y="64">0</text><text x="80" y="64">8</text><text x="120" y="64">10</text><text x="160" y="64">12</text>
      <text x="212" y="64">16</text><text x="312" y="64">48</text><text x="396" y="64">80</text><text x="436" y="64">82</text>
      <text x="528" y="64">154</text><text x="560" y="64">160</text>
    </g>
    <path d="M16 120 V128 H396 V120" fill="none" stroke="var(--accent)" stroke-width="1.5"/>
    <text x="206" y="150" font-size="11" text-anchor="middle" class="uf-hot">signed: ECDSA P-256 over SHA-256(bytes 0–79)</text>
    <text x="206" y="168" font-size="11" text-anchor="middle" class="uf-dim">checked before a single byte is written</text>
    <path d="M560 120 V128 H744 V120" fill="none" stroke="currentColor" stroke-opacity=".5" stroke-width="1.5"/>
    <text x="652" y="150" font-size="11" text-anchor="middle" class="uf-dim">hashed while it's written;</text>
    <text x="652" y="168" font-size="11" text-anchor="middle" class="uf-dim">must match bytes 16–47</text>
  </g>
 </svg>
@@ -0,0 +1,53 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 760 352" role="img" aria-label="Four ways in, one gate. scripts/flash.sh --ota signs the firmware and pushes it over Wi-Fi to TCP port 3232, straight to the Update Service. rdbg.py put over Wi-Fi, sd_put.sh over USB serial, or the card by hand all put an Update File in /updates on the SD card, where Settings, Firmware, or the install command picks it up. The Update Service checks the header and signature first, writes the image to the other app slot while hashing it, and makes it the next boot only if the hash matches. Then it restarts into Probation. If anything is wrong, a Toast says so and nothing changes.">
  <defs>
    <marker id="wi-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path d="M0,0 L10,5 L0,10 z" fill="currentColor"/></marker>
    <marker id="wi-arrow-hot" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="f-accent" d="M0,0 L10,5 L0,10 z"/></marker>
    <marker id="wi-arrow-bad" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse"><path class="f-red" d="M0,0 L10,5 L0,10 z"/></marker>
  </defs>
  <g font-family="JetBrains Mono, ui-monospace, monospace" fill="currentColor">
    <rect class="wi-box" x="16" y="32" width="220" height="56" rx="6"/>
    <text x="30" y="55" font-size="12" font-weight="600">flash.sh --ota</text>
    <text x="30" y="75" font-size="11" class="wi-dim">builds, signs, pushes</text>
    <rect class="wi-box" x="16" y="112" width="220" height="56" rx="6"/>
    <text x="30" y="135" font-size="12" font-weight="600">rdbg.py put</text>
    <text x="30" y="155" font-size="11" class="wi-dim">Debug Console, Wi-Fi 2323</text>
    <rect class="wi-box" x="16" y="192" width="220" height="56" rx="6"/>
    <text x="30" y="215" font-size="12" font-weight="600">sd_put.sh</text>
    <text x="30" y="235" font-size="11" class="wi-dim">USB serial, card stays in</text>
    <rect class="wi-box" x="16" y="272" width="220" height="56" rx="6" stroke-dasharray="4 3"/>
    <text x="30" y="295" font-size="12" font-weight="600">the card, by hand</text>
    <text x="30" y="315" font-size="11" class="wi-dim">the 1990s way</text>
    <rect class="wi-panel" x="288" y="176" width="200" height="88" rx="8"/>
    <text x="302" y="200" font-size="12" font-weight="600">SD card</text>
    <text x="302" y="219" font-size="11">/updates/*.ota</text>
    <text x="302" y="238" font-size="11" class="wi-dim">Settings → Firmware,</text>
    <text x="302" y="254" font-size="11" class="wi-dim">or install &lt;path&gt;</text>
    <rect class="wi-hot" x="536" y="32" width="208" height="158" rx="8"/>
    <text x="550" y="56" font-size="12" font-weight="600">Update Service</text>
    <text x="550" y="80" font-size="11">1 header, signature:</text>
    <text x="550" y="96" font-size="11" class="wi-dim">  checked first</text>
    <text x="550" y="118" font-size="11">2 image → other slot,</text>
    <text x="550" y="134" font-size="11" class="wi-dim">  hashed on the way</text>
    <text x="550" y="156" font-size="11">3 hash matches:</text>
    <text x="550" y="172" font-size="11" class="wi-dim">  boot it next</text>
    <rect class="wi-box" x="576" y="216" width="168" height="44" rx="6"/>
    <text x="660" y="243" font-size="12" text-anchor="middle">restart → Probation</text>
    <rect class="wi-bad" x="536" y="280" width="208" height="56" rx="6"/>
    <text x="550" y="303" font-size="11">anything wrong: a Toast,</text>
    <text x="550" y="321" font-size="11">and nothing changes</text>
    <path class="wi-line-hot" d="M236 60 H532" marker-end="url(#wi-arrow-hot)"/>
    <text class="f-accent" x="300" y="52" font-size="11">Wi-Fi · TCP 3232</text>
    <path class="wi-line" d="M236 140 H262 V198 H284" marker-end="url(#wi-arrow)"/>
    <path class="wi-line" d="M236 220 H284" marker-end="url(#wi-arrow)"/>
    <path class="wi-line" d="M236 300 H262 V242 H284" marker-end="url(#wi-arrow)"/>
    <path class="wi-line" d="M488 220 H512 V150 H532" marker-end="url(#wi-arrow)"/>
    <text x="492" y="238" font-size="10" class="wi-dim">storage</text>
    <text x="492" y="250" font-size="10" class="wi-dim">task</text>
    <path class="wi-line" d="M660 190 V212" marker-end="url(#wi-arrow)"/>
    <path class="wi-line-bad" d="M556 190 V276" marker-end="url(#wi-arrow-bad)"/>
  </g>
 </svg>
@@ -0,0 +1,22 @@
 +++
 title = "The Debug Console"
 description = "A firmware you can drive from your desk: its console over Wi-Fi, its screen as a PNG, its SD card, its crash dumps, and a way back when an update goes wrong."
 template = "guide-index.html"
 page_template = "guide-page.html"
 sort_by = "weight"
 weight = 1
 [extra]
 eyebrow = "Developer docs"
 +++
 The **Debug Console** is the serial console, over Wi-Fi, for whoever holds the device's token. It is in **every firmware**, switched off until you switch it on, and it is the most useful thing in the project. With it you can:
 - **see everything the device prints**, boot messages included, without a cable;
 - **run every serial command** from your desk;
 - **press keys** and **take screenshots**, so a UI change can be tested and looked at remotely;
 - **copy files** to and from the SD card;
 - **read crash reports and fetch core dumps**, decoded against the exact build that crashed;
 - **update the firmware** over the same Wi-Fi, and know that a bad update rolls back by itself.
 Start with [Switch the console on](/dev/debug/switch-it-on/), then [the Debug Console](/dev/debug/console/). The rest are what you can do with it.
@@ -0,0 +1,116 @@
 +++
 title = "Command reference"
 description = "Every command the firmware understands, over USB serial or the Debug Console: what `help` prints, then what each one does."
 weight = 30
 [extra]
 docs = true
 source = "src/main.cpp and README.md"
 tag = "Reference"
 +++
 ## What `help` prints
 The firmware's own list, read from `src/main.cpp`. Every firmware has all of them, over USB serial and over the Debug Console. The ones marked *Debug Console only* exist only over Wi-Fi, where [`rdbg.py`](/dev/debug/files-and-screens/) speaks them, and the ones marked *USB serial only* only over the cable:
 ```
 info              firmware, uptime, memory, Wi-Fi, app slots
 tasks             FreeRTOS tasks over the next second: state, priority, free stack, CPU share
 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 [-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] | 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 help shot, or one character; ctrl- alt- shift- before it (key ctrl-down)
 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 | 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)
 wifi ip ... try <seconds> | wifi ip keep   a trial IP setting: back to the previous one unless kept
 loop spin on|off  make the main loop spin without resting, to compare load and radio noise
 lora noise test [gnss|quiet] | lora noise report   Sweep under one changed condition at a time (Wi-Fi goes off for a moment)
 lora inject <hex> [rssi] [snr]   a packet into the LoRa Scanner as if received (nothing is sent)
 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: there, a bare `screenshot` sends the screen instead of saving it
 quit              close the Debug Console connection
 ```
 In **Safe Mode** (see [Crashes and Safe Mode](/dev/debug/crashes/)) only a few run: `help`, `info`, `tasks`, `net`, `reboot`, `boot other`, `wifi status`, and anything starting with `log level`, `crash`, `coredump`, `wifi add`, `debug`. Anything else answers `not available in Safe Mode`.
 ## What they do
 `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.
 | Command | Effect |
 |---|---|
 | `burst` | Publishes 5 Notifications at once |
 | `key up\|down\|left\|right\|select\|back\|home\|del\|tab\|space\|help\|shot`, or `key <char>` | Injects a key press (`help` is Fn+h: the keys of the screen that is showing; `shot` is Fn+p: a screenshot). `ctrl-`, `alt-` and `shift-` before it hold that key: `key ctrl-down`, `key alt-up`, `key ctrl-b` |
 | `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) |
 | `wifi ip <ssid> dhcp` / `wifi ip <ssid> <address>/<prefix> [gateway]` | A Saved Network's IP setting: Automatic, or Fixed. Add `try <seconds>` to go back to the previous setting unless `wifi ip keep` follows |
 | `wifi dns <a> [b]` / `wifi dns always on\|off` / `wifi ntp <a> [b]` | DNS servers (used on Fixed networks, or always), and NTP servers |
 | `log <text>` | Appends a line to a test IRC Log (`/irc/dev/#test/<date>.log`) |
 | `sd card` | What the SD card says it is: type, size, and its identity register (maker, name, revision, serial, date) |
 | `sd list` | Lists the files of each Storage Clean-up category |
 | `sd fill <folder> <count>` | Makes that many small files in a folder, to test a crowded one |
 | `cat <path>` | Prints the first ~1.2 KB of a file on the SD card |
 | `irc start` | Starts the IRC Service (normally done by opening the IRC App) |
 | `irc stop` | Stops it, as `/quit` does: QUIT if connected, no more retries, and the App stays disconnected until you type |
 | `gemini get <url>` | Fetches a Gemini page and prints its header, size, certificate fingerprint and heap use |
 | `gemini trust <host> <port> <sha256>` | Pins a certificate by hand (the Gemini App asks when one changes) |
 | `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, **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 |
 | `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 |
 | `lora probe` | Finds the radio: chip, oscillator, antenna switch, DIO1 interrupt, noise floor |
 | `lora status` | Radio settings, who's listening, packet and error counters, noise floor, task stack |
 | `lora rx on` / `lora rx off` | Listens and prints each packet on the console |
 | `lora preset <name>` / `lora custom <MHz> <BW kHz> <SF> <CR> <sync hex> [preamble]` | Receive settings: a Meshtastic preset, or anything else (`lora custom 868.1 125 7 5 34 8` for LoRaWAN) |
 | `lora capture start` / `lora capture stop` | A LoRa Capture, as `c` in the App |
 | `lora sweep on [from MHz] [to MHz] [step kHz]` / `lora sweep off` / `lora sweep dump` | Sweep a band (863 870 100 by default), with a summary every 2 s (floor, strongest, peaks), or print the latest pass |
 | `gnss quiet on` / `gnss quiet off` | The "Pause GNSS for LoRa" setting |
 | `gnss status` / `gnss restart` | The receiver's state, and a restart of it |
 | `gnss track start` / `gnss track stop` | A Track, as `r` in the GNSS App (the reason is printed if it can't start) |
 | `gnss nmea on` / `gnss nmea off` | Prints each NMEA sentence the receiver sends, as `nmea: …` |
 | `gnss send <sentence>` | Sends a sentence to the receiver, without the `$` and the checksum (it adds them) |
 | `lora noise test [gnss\|quiet]` / `lora noise report` | Sweep under one changed condition at a time to find what raises the noise floor (Wi-Fi goes off for a few seconds); then the result |
 | `lora inject <hex> [rssi] [snr]` | A packet into the Scanner as if received (nothing is sent) |
 | `crash` | The last crash: which firmware, why, task, PC and backtrace (from the core dump in flash) |
 | `coredump erase` | Forgets the core dump |
 | `loop spin on` / `loop spin off` | Make the main loop spin without resting, to compare load and radio noise |
 | `crash abort` / `crash wdt` | Crash on purpose, or hang the main loop until the watchdog fires |
 | `debug status` / `debug off [seconds]` | The Debug Console: whether it's on, has a token and a client; switch it off. With a number of seconds, it comes back by itself after that long |
 | `debug on` / `debug token <value>` / `debug token new` | USB serial only: switch it on (making a token if there's none), give it a token of 16 to 64 characters, or make a new one. The token is never printed |
 | `help` | Lists the commands |
 `scripts/flash.sh` stops a running serial log first, since it would hold the port.
--- a/Show More
+++ b/Show More