docs: restructure README, document external input, tidy docs tree

README had drifted from the firmware in several places:

- Supported Devices listed only the three nRF52 boards; Heltec V3/V4 were
  missing entirely, as was any mention that ESP32-S3 flashes differently.
  Flashing is now split per MCU, with the merged-vs-app-only .bin trap
  spelled out — that one costs an afternoon to diagnose from a dark screen.
- It advertised a Lemon/Default font switch that was retired in v1.23; there
  is one unified misc-fixed 6x9 font now and no font setting at all.
- tools/README claimed ENABLE_SCREENSHOT had to be added by hand, directly
  contradicting README's "no special build flags required". The envs have
  carried the flag for a while; rewrote the file to cover all four tools.
- "S key for screenshot" described screenshot.py's menu, not the device —
  screenshots are driven entirely from the host via CMD_GET_SCREENSHOT.

Structurally, general notes (factory reset on migration, BLE-over-USB
priority) sat at the tail of the ESP32 subsection and read as ESP32-specific;
they're now placed where they apply. Heltec wiring moved out of Supported
Devices into its own section so the device table stays scannable, and the
Solo Tools heading is no longer a link (it was generating a garbage anchor).

New docs/solo_features/external_keyboard.md covers CardKB and the wired
joystick: shortcut table, Full vs Compact, and the pin assignment. The pins
are marked as verified on real V4 hardware only — V3 inherits them from
Heltec's documented pin-compatibility and hasn't been checked on a board.

FEATURES.md (roadmap + code audit, developer-only) moves to
docs/development/roadmap.md; nothing referenced it by path.

Adds Building from source / Releasing / Repository layout, since the release
flow was only discoverable by reading the workflow.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

tools/README.md

@@ -1,42 +1,92 @@
-#### Display Screenshot Tool
+# Host-side tools
 
-> **⚠️ Note:** The screenshot feature requires the `ENABLE_SCREENSHOT` build flag to be enabled. Add `-D ENABLE_SCREENSHOT` to your PlatformIO build flags, then recompile and flash the firmware.
+Helper scripts that run on your computer, not on the device.
 
-The firmware supports capturing the current display contents and transmitting
-it over USB serial. This is useful for debugging, remote monitoring, or
-creating documentation.
+| Tool | Purpose |
+| ---- | ------- |
+| `screenshot.py` | capture the device display over USB serial and save it as a PNG |
+| `trail_export.py` | capture a GPX track from the device over USB serial |
+| `gpx-downloader/index.html` | the same GPX capture in a browser, via Web Serial |
+| `bdf2gfx.py` | convert a BDF bitmap font to an Adafruit-GFX header |
 
-**Important:** When the device is connected to the companion app, the USB
-serial port is not available for communication. To use the screenshot tool,
-ensure the device is not connected to the companion app.
+Python dependencies are managed with [uv](https://docs.astral.sh/uv/) — run the
+scripts with `uv run tools/<script>.py` from the repository root.
+
+> [!TIP]
+> The hosted [Solo Tools Web App](https://marekzegare4.github.io/Solo-tools/)
+> does both screenshots and GPX export with nothing to install, and is the
+> easiest option for most people. The scripts here are the offline equivalents.
+
+> [!IMPORTANT]
+> USB serial is suspended while a BLE connection is active, so disconnect the
+> companion app from BLE before using any of these. If the app is connected over
+> USB, disconnect it too — the raw stream would otherwise disrupt its frame
+> protocol.
+
+---
+
+## Display screenshot
+
+All solo firmware environments are built with `-D ENABLE_SCREENSHOT`, so no
+special build is needed. On other environments (repeater, room server, the
+non-solo companion builds) add the flag yourself:
+
+```sh
+PLATFORMIO_BUILD_FLAGS="-D ENABLE_SCREENSHOT" pio run -e <env> -t upload
+```
 
 **Usage:**
 
-1. Build and flash firmware with `-D ENABLE_SCREENSHOT` build flag enabled
-
-Example for the OLED dual firmware:
-
-```
-PLATFORMIO_BUILD_FLAGS="-D ENABLE_SCREENSHOT" pio run -e WioTrackerL1_companion_dual -t upload
-```
-
-2. Connect the device to your computer via USB (ensure no companion app connection)
-3. Install dependencies and run the screenshot tool. To manage python and python dependencies, use uv: https://docs.astral.sh/uv/
+1. Connect the device over USB, with no companion app attached
+2. Run the tool:
 
    ```sh
-   cd tools
    uv run tools/screenshot.py
    ```
 
    Options:
-   - `--port PORT` — Serial port to use (default: auto-detect)
-   - `--scale SCALE` — Upscale factor for the output image (1=no upscale, 2=2x, 3=3x, 4=4x, etc.; default: 1)
+   - `--port PORT` — serial port to use (default: auto-detect)
+   - `--scale SCALE` — upscale factor for the output image (1 = none; default: 1)
 
-4. In the tool's interactive menu, press **S** to capture a screenshot
-5. The tool will save the screenshot as a PNG file in `tools/pngs/` with a timestamp-based filename
+3. Press **S** in the tool's interactive menu to capture
+4. The PNG lands in `tools/pngs/` with a timestamped filename
 
 **How it works:**
-- The tool sends the `CMD_GET_SCREENSHOT` command (66) to the device
-- The device responds with `RESP_CODE_SCREENSHOT` (29) containing the framebuffer data
-- The framebuffer is transmitted in chunks (128×64 display = 1024 bytes, split across multiple frames)
-- The tool reassembles the chunks and converts them to a PNG image
+
+- The tool sends `CMD_GET_SCREENSHOT` (66) to the device
+- The device replies with `RESP_CODE_SCREENSHOT` (29) carrying the framebuffer
+- The framebuffer arrives in chunks (a 128 × 64 display is 1024 bytes, split
+  across several frames), which the tool reassembles into a PNG
+
+---
+
+## GPX trail export
+
+1. Connect the device over USB, with no companion app attached
+2. Start the listener:
+
+   ```sh
+   uv run tools/trail_export.py
+   ```
+
+   Options:
+   - `--port PORT` — serial port to use (default: auto-detect)
+   - `--out OUT` — output file (default: a timestamped file in `tools/gpx/`)
+
+3. On the device: **Tools › Trail › Hold Enter › Export (live)** or
+   **Export (saved)**
+4. The script captures the GPX 1.1 XML stream and writes it to disk
+
+---
+
+## Font conversion
+
+```sh
+uv run tools/bdf2gfx.py <font.bdf> <first_hex> <last_hex> <VarPrefix> > out.h
+```
+
+Emits a contiguous glyph table over the given codepoint range, with empty
+placeholders for codepoints the BDF does not define, so the renderer can index
+by `cp - first`. This is how [`src/helpers/ui/MiscFixedFont.h`](../src/helpers/ui/MiscFixedFont.h)
+— the unified 6×9 Latin/Greek/Cyrillic display font — was generated from
+`6x9.bdf`.