update docs

README.md

@@ -23,7 +23,8 @@ the desktop or any ENVIRONMENT cartridge.
 
 ## Choose a starting point
 
-- **Build and try FDS:** follow [Build and start FDS](docs/getting-started.md).
+- **Run on your Raspberry Pi 5:** follow [the real-hardware setup guide](docs/hardware-setup.md), including HDMI-plus-USB Dasung wiring, disk installation and first boot.
+- **Build and try the emulator:** follow [Build and start FDS](docs/getting-started.md).
 - **Build an application cartridge:** use the [software and emulator walkthrough](docs/workstation.md).
 - **Use the computer:** read [Using cartridges](docs/cartridges.md), [DATA](docs/data.md), and [the desktop guide](docs/desktop.md).
 - **Install or maintain a machine:** see [internal storage](docs/internal-storage.md), [release verification](docs/releases.md), and [recovery](docs/recovery.md).

docs/README.md

@@ -8,6 +8,7 @@ operating guides run at the FDS console unless stated otherwise.
 | Guide | What you will learn |
 | --- | --- |
 | [Overview](../README.md) | How the computer, internal storage and cartridges fit together |
+| [Run on a Raspberry Pi 5](hardware-setup.md) | Wire HDMI/USB/power, prepare NVMe and SYSTEM, reach the first console, calibrate bays and diagnose hardware |
 | [Build and start FDS](getting-started.md) | Prepare the OS build workstation, create images and boot the emulator |
 | [Software and emulator walkthrough](workstation.md) | Build Void source packages, assemble cartridges, insert them and write USB media |
 | [Using cartridges](cartridges.md) | Inspect bays, run applications, resolve command names and eject safely |

docs/dasung.md

@@ -4,14 +4,42 @@ FDS includes `dasungd` for the configured Dasung Paperlike 13K grayscale monitor
 The controller starts during early boot and remains supervised in the base system,
 including console-only use. No GUI or ENVIRONMENT cartridge is required.
 
+For installation, disk preparation and first power-on, start with
+[Run FDS on a Raspberry Pi 5](hardware-setup.md).
+
 The supplied profile uses the dedicated monitor's EDID and USB companion identity,
 with raw mode 1 and contrast 4 as startup defaults. It is specific to that monitor;
 do not use its identity as a blanket match for other CH340 USB devices.
 
+## HDMI plus USB-C on the Pi
+
+Use the Pi's **micro-HDMI output** for video to the monitor's HDMI input. Use a
+separate **USB-A-to-USB-C data cable** from a Pi host port to the monitor for
+controller access, and power the monitor with its supplied DC adapter. The
+Pi's own USB-C connector is its power input; it does not output USB-C video.
+See the [wiring table](hardware-setup.md#2-wire-hdmi-video-usb-control-and-power-separately),
+[official Pi display guidance](https://www.raspberrypi.com/documentation/computers/getting-started.html#display),
+and [DASUNG's power guidance](https://shop.dasung.com/pages/q-a).
+
+HDMI video and USB controller access are separate checks. The daemon talks USB
+regardless of the video cable, but the HDMI-plus-USB arrangement still needs to
+expose the expected UART and companion bridge on this monitor. HDMI alone does
+not carry the daemon's control protocol. A charge-only cable or a USB-C lead
+connected only to a charger cannot provide host USB control.
+
+The image currently supplies a firmware EDID override for 3200 × 2400 at about
+37 Hz, recorded on the original workstation. DASUNG says some HDMI hosts need
+27 Hz instead; that does not establish which mode the Pi and this cable will
+accept. The forced profile can prevent using the monitor's native HDMI mode
+list. Use the diagnostic procedure below if needed; neither Pi HDMI compatibility
+nor physical power-cycle recovery is recorded as passed yet.
+[Manufacturer HDMI note](https://shop.dasung.com/pages/dasung-paperlike-13k-the-worlds-first-13-3-inch-37hz-3k-e-ink-monitor).
+
 ## Inspect the controller
 
-The controller's socket is restricted to root. From a root maintenance console
-on FDS:
+The controller's socket is restricted to root. Use the local `RECOVERY#` console
+described in [Enter recovery](recovery.md#enter-recovery); the ordinary `FDS>`
+account cannot access it. On FDS recovery:
 
 ```sh
 dasungd status
@@ -40,6 +68,126 @@ Inspect `/run/log/dasungd/current` and the reported status. Discovery requires
 the configured DRM EDID and matching USB companion topology. An ambiguous match
 is rejected. Set `usb_path` only after identifying the intended device topology.
 
+At `RECOVERY#`, start with:
+
+```sh
+lsusb
+lsusb -t
+dasungd status
+dasungd query
+tail -80 /run/log/dasungd/current
+```
+
+The existing profile expects UART `1a86:7523` alongside SPI bridge `1a86:5512`
+under the same hub. If neither appears, check monitor power, its USB data port,
+the cable and the Pi host connection. If only one appears, preserve the USB tree
+and log: the cable/input combination has not yet satisfied the current profile.
+Do not disable companion checks or match every CH340 device to hide the failure.
+
+`status` separates `connected` from `responsive` and includes `usb_error`,
+`display_error`, `displays`, `rx_frames` and `last_rx_ms_ago`. `query` queues
+requests; run `status` again after replies arrive. Keepalive packets being sent
+are not themselves evidence that the monitor answered.
+
+Capture the actual DRM connector names and EDID at `RECOVERY#`:
+
+```sh
+mkdir /tmp/dasung-hdmi
+cat /proc/cmdline > /tmp/dasung-hdmi/cmdline.txt
+for fds_connector in /sys/class/drm/card*-*; do
+    [ -f "$fds_connector/status" ] || continue
+    fds_connector_name=${fds_connector##*/}
+    printf '%s: ' "$fds_connector_name"
+    cat "$fds_connector/status"
+    cat "$fds_connector/modes"
+    cp "$fds_connector/status" "/tmp/dasung-hdmi/$fds_connector_name.status"
+    cp "$fds_connector/modes" "/tmp/dasung-hdmi/$fds_connector_name.modes"
+    cp "$fds_connector/edid" "/tmp/dasung-hdmi/$fds_connector_name.edid"
+done
+```
+
+Use a new directory for each capture and save it before shutdown using
+[machine diagnostics](internal-storage.md#save-and-retrieve-diagnostics).
+An empty EDID on a disconnected connector is expected. The `modes` file lists
+available resolution names, not proof of the active refresh rate or picture
+quality. With `drm.edid_firmware` active, the EDID you read may be the supplied
+override; capture again without it to learn what HDMI actually advertises.
+
+The configured DRM serial is `L56051794302`. Native HDMI EDID might identify the
+display differently from the recorded USB-C profile. With `require_display=true`,
+an identity mismatch can leave USB control disconnected even when HDMI video
+works. Retain the native EDID, USB topology and errors for a deliberate profile
+update; do not silently remove identity checks. Config changes must ultimately
+be rebuilt into both early boot and base/recovery images. The read-only
+`/etc/dasungd.toml` is not a persistent settings editor.
+
+## Try the monitor's own HDMI EDID
+
+Use this when the stock forced timing gives a blank or unstable picture, or when
+temporarily connecting a different HDMI display. The override currently applies
+to connected DRM outputs without a connector qualifier, so attaching another
+screen while retaining it is not an independent native-mode test.
+
+Follow the offline edit procedure below. In the disk's **single-line**
+`cmdline.txt`, remove only this token for the EDID experiment:
+
+```text
+drm.edid_firmware=edid/dasung-paperlike13k-37hz.bin
+```
+
+For verbose diagnosis with a USB keyboard and display console, a complete
+command line based on the current production template is:
+
+```text
+console=tty1 rdinit=/init ro loglevel=7 vt.global_cursor_default=0 fds.boot=normal fds.debug=1
+```
+
+For the serial boot mode, retain `console=ttyAMA10,115200` after `console=tty1`
+instead. Use `fds.boot=recovery` in place of `fds.boot=normal` when intentionally
+booting recovery; never append a second conflicting `fds.boot` option. Do not add
+`fds.emulator=1` on real hardware or replace stage0 with a Raspberry Pi OS
+`root=…` command line.
+
+Reboot and repeat the DRM/USB capture. Removing the override allows the monitor's
+HDMI EDID to supply modes; it does **not** guarantee 27 Hz or fix missing USB
+control. Record any change in picture and controller status. Restore the saved
+command line to return to the shipped profile. Keep both captures so a future
+HDMI profile change can be based on observed timings and identity.
+
+### Edit the BOOT command line offline
+
+Shut FDS down and disconnect Pi power. Connect NVMe to the Linux workstation, or
+boot the separate maintenance SD and access the inactive NVMe there. Identify
+the same disk by model/serial used when flashing it. Mount only its first
+partition, labeled `FDS_BOOT`; FDS does not normally mount it at
+`/boot/firmware` as Raspberry Pi OS does.
+
+On that **workstation or maintenance OS**, replacing the partition path below:
+
+```sh
+lsblk -p -o NAME,MODEL,SERIAL,SIZE,TYPE,PARTLABEL,MOUNTPOINTS
+sudo mkdir -p /mnt/fds-boot
+sudo mount -o nosuid,nodev,noexec \
+  /dev/disk/by-id/REPLACE_WITH_VERIFIED_NVME-part1 /mnt/fds-boot
+sudo cp -n /mnt/fds-boot/cmdline.txt /mnt/fds-boot/cmdline.before-hardware.txt
+sudoedit /mnt/fds-boot/cmdline.txt
+cat /mnt/fds-boot/cmdline.txt
+sudo umount /mnt/fds-boot
+```
+
+Check the identity before the mount and stop on any failed step. If the partition
+was automounted, unmount that instance first. Keep `/mnt/fds-boot` dedicated to
+this operation. The no-clobber copy retains an existing backup; if repeating the
+experiment, inspect that backup and skip the copy step if it already exists.
+Do not assume an older backup contains your latest settings. Keep `cmdline.txt`
+on one line and record its final contents with the
+test session. Safely disconnect the enclosure before moving NVMe back to the Pi.
+
+To undo the edit, mount the same verified partition again, restore
+`cmdline.before-hardware.txt` over `cmdline.txt`, and unmount before rebooting.
+These edits change the flashed copy only; they do not change the source images
+or their recorded hashes. Reflashing restores the image's original command line.
+
 FDS uses the daemon for USB control. Its configuration disables the original
 workstation-specific display hotplug procedure. Video mode and cabling are part
 of the machine's boot/display configuration. The detailed protocol, build

docs/developer/boot.md

@@ -13,8 +13,9 @@ are never used as cartridge identities.
 
 The software boot path has passed on an ARM virtual machine using the actual
 FDS Pi kernel. That does not verify Pi firmware, NVMe, RP1, display output, USB
-power or physical boot speed. Those checks are deferred until the machine is
-assembled. M5 now provides an ordinary-user `FDS>` console with a temporary home
+power or physical boot speed. Those checks still require physical testing; follow
+the [real-hardware setup guide](../hardware-setup.md). M5 now provides an
+ordinary-user `FDS>` console with a temporary home
 and measured boot events. Password login remains locked; this is an intentional
 local single-user session. The M2 test VM separately offers a temporary root
 development shell. See [native init](init.md) and [performance reports](performance.md).

docs/developer/dasung.md

@@ -105,6 +105,8 @@ No world-writable USB rule, systemd unit, or runit service is installed.
 The video timing was confirmed on the original AMD workstation, **not on a Pi**.
 The original USB-C video connection is not a Pi cabling prescription. Pi connector,
 cable/adapter, mode acceptance, and picture stability require hardware validation.
+For the current HDMI video plus USB control procedure, including separate monitor
+power and a reversible native-EDID experiment, use the [display guide](../dasung.md).
 Desktop 2× scaling is separate from EDID timing; a console uses its own font size.
 
 FDS configures `display.enabled=false` and `hotplug="none"`: the daemon handles

docs/getting-started.md

@@ -6,6 +6,9 @@ cartridges on another Linux distribution, use the [workstation guide](workstatio
 A prepared set of kernel, initramfs and SYSTEM images can be run on a Linux
 workstation without building the OS locally.
 
+For the physical computer, follow [Run FDS on a Raspberry Pi 5](hardware-setup.md).
+It covers HDMI-plus-USB monitor wiring, both disks, EEPROM, first boot and recovery.
+
 ## Prepare the workstation
 
 Use a normal user account, a Git checkout with its submodule metadata, and a
@@ -63,7 +66,7 @@ inputs needed by the emulator:
 builds a SYSTEM with compilers, Git, Vim, debuggers and display diagnostics.
 Both profiles include WindowMaker and the Dasung daemon. The desktop starts on
 request. `make all` also assembles recovery, boot and internal-storage images;
-see [internal installation](internal-storage.md) when preparing a physical machine.
+see [real-hardware setup](hardware-setup.md) when preparing a physical machine.
 
 ## Start the emulator
 
@@ -76,7 +79,9 @@ out/workstation/fds-emulator --session out/my-emulator console
 ```
 
 If QEMU is installed directly on the workstation, omit `--qemu-runner`.
-The session directory must be new. At the `FDS>` prompt:
+Use a new session directory for the first run; after `stop`, you can `start` the
+same session again. Logs and DATA overlays are retained, and bays start empty.
+At the `FDS>` prompt:
 
 ```sh
 fds info

docs/hardware-setup.md

@@ -0,0 +1,392 @@
+# Run FDS on a Raspberry Pi 5
+
+[User manual](README.md) · [Dasung wiring and diagnostics](dasung.md) · [Recovery](recovery.md)
+
+This guide takes a partly assembled Pi from prepared disks to its first FDS
+console, then adds monitor control and physical bay numbering. Start with one
+SYSTEM cartridge; the twelve-bay assembly and a desktop are not prerequisites.
+These are instructions for physical testing, not a record of a successful Pi
+boot. Existing QEMU results do not establish HDMI compatibility, USB power
+stability, monitor recovery or physical boot times.
+
+Follow steps 1–6 to reach the first console. Steps 7–9 check the monitor, install
+bay mappings and save results. If the screen stays blank, jump to
+[first-boot troubleshooting](#when-the-first-boot-fails).
+
+Commands marked **workstation** run on the Linux build computer, **maintenance
+OS** means a separate Raspberry Pi OS rescue installation, and **FDS** means the
+console on the Pi. FDS does not start SSH or networking automatically.
+
+## 1. Prepare the minimum hardware
+
+You need:
+
+- A Raspberry Pi 5 with cooling and a suitable USB-C power supply.
+- A PCIe NVMe adapter/HAT and NVMe drive for internal boot and recovery storage.
+- One USB storage device for SYSTEM, a USB keyboard, and the Paperlike 13K.
+- HDMI video cabling, a USB-A-to-USB-C **data** cable for the monitor controller,
+  and the monitor's supplied power adapter.
+- A Linux workstation and an NVMe enclosure/adapter for writing the disks.
+  A separate maintenance microSD card is useful for EEPROM and display diagnosis.
+
+The current FDS installation uses **two disks**:
+
+| Disk | Contents | When it is needed |
+| --- | --- | --- |
+| Internal PCIe NVMe | `FDS_BOOT`, `FDS_RECOVERY`, `FDS_INTERNAL` | Every FDS boot; also recovery without SYSTEM |
+| USB SYSTEM cartridge | `FDS_SYSTEM` | Normal FDS operation |
+
+PROGRAM, DATA and ENVIRONMENT cartridges can wait until the console works.
+If only microSD is connected today, use it for Raspberry Pi OS maintenance and
+cable checks. This guide's complete FDS installation requires NVMe: persistent
+machine settings deliberately accept PCIe NVMe only. Writing the internal image
+to microSD or leaving NVMe in a USB enclosure does not provide that supported
+layout. A SYSTEM image alone contains no Pi firmware boot partition.
+
+Connect or reseat the PCIe ribbon and HAT with power disconnected, following the
+adapter's instructions. For the first boot, attach SYSTEM directly to a Pi USB
+port if the cartridge hubs are not ready. Changing the hub wiring later requires
+a fresh bay calibration.
+
+## 2. Wire HDMI video, USB control and power separately
+
+The Pi's micro-HDMI ports are **video outputs**; the monitor receives that video.
+The Pi 5's USB-C socket supplies power to the Pi and does not provide DisplayPort
+Alt Mode video. A USB-C display cable alone cannot replace HDMI on this board.
+See [Raspberry Pi's display connection guide](https://www.raspberrypi.com/documentation/computers/getting-started.html#display).
+
+| Connection | Purpose |
+| --- | --- |
+| Pi micro-HDMI output → Paperlike HDMI video input | Picture; use the correct HDMI connector sizes for both ends |
+| Pi USB-A host port → Paperlike USB-C data port | Candidate USB control path for `dasungd`; verify enumeration in step 7 |
+| Supplied Dasung power adapter → monitor power input | Monitor power, separate from USB control |
+| Pi power supply → Pi USB-C power input | Pi power |
+
+Use the monitor's HDMI input selection, if its controls offer one. A charging-only
+USB cable will not expose the controller. This HDMI-plus-USB arrangement is the
+route to test; whether this unit exposes both controller interfaces while HDMI
+is active still needs observation. HDMI can show a picture even when USB control
+is missing, and USB replies do not prove the picture is correct.
+
+Use the supplied Dasung DC power connection: the manufacturer specifically warns
+that ordinary USB power is insufficient for reliable 13K operation.
+[DASUNG power guidance](https://shop.dasung.com/pages/q-a).
+For Pi 5, a supply supporting 5 V/5 A permits a larger USB power budget; a 3 A
+supply limits downstream peripherals to 600 mA. Use powered hubs for the cartridge
+assembly rather than budgeting the monitor and twelve cartridges from the Pi.
+[Raspberry Pi power guidance](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#power-supply).
+
+The shipped FDS boot configuration forces this monitor's recorded 3200 × 2400
+timing at about 37 Hz. That timing was established on the original workstation.
+DASUNG documents that some HDMI hosts instead use 27 Hz. FDS's forced EDID means
+you should not assume automatic fallback. If HDMI is blank or unstable, use the
+[native-EDID diagnostic boot](dasung.md#try-the-monitors-own-hdmi-edid) before
+changing monitor identity or USB matching rules.
+[DASUNG HDMI refresh-rate guidance](https://shop.dasung.com/pages/dasung-paperlike-13k-the-worlds-first-13-3-inch-37hz-3k-e-ink-monitor).
+
+## 3. Build a matching image set on the workstation
+
+Complete [Prepare the workstation](getting-started.md#prepare-the-workstation),
+including bootstrap, smoke test and build checks. From the repository root, run
+the following commands **sequentially**, stopping if any fails:
+
+```sh
+make rootfs PROFILE=cli
+make system-card PROFILE=cli
+make recovery
+make initramfs
+make boot-volume BOOT_MODE=production
+make internal-image
+```
+
+This builds one normal SYSTEM and independent recovery, then combines the current
+kernel, initramfs and recovery into the internal disk. The CLI rootfs includes
+the matching kernel modules, native s6 and the base Dasung controller. Rebuild
+the complete sequence after a source change; existing convenience links in
+`out/` can otherwise point to components from different builds.
+
+`BOOT_MODE=production` puts the interactive console on the HDMI display with
+USB keyboard input. It is suitable for first bring-up without a serial cable.
+`PROFILE=development` is a separate choice that adds compilers and debugging
+tools to SYSTEM; it does not select the console transport. The smaller CLI
+profile is sufficient here, and includes the optional desktop too.
+
+| Output | Write it to |
+| --- | --- |
+| `out/fds-internal.img` | Whole NVMe disk |
+| `out/fds-system-cli.img` | Whole USB SYSTEM disk |
+| `out/fds-boot.img` | Raw FAT partition payload; already included in the internal image |
+| `out/fds-recovery.img` | Raw EROFS partition payload; already included in the internal image |
+
+Do not write the last two files as whole disks. `make all` builds additional
+profiles and release tooling; it is unnecessary for this first-boot image set.
+Use [cleanup](cleanup.md) to review retained build trees when space is tight.
+
+Record the inputs before flashing. On the **workstation**, choose a new session
+directory and retain the printed build logs/manifests with it:
+
+```sh
+mkdir out/hardware-first
+cp tests/hardware/session-template.json out/hardware-first/session.json
+git rev-parse HEAD > out/hardware-first/source-commit.txt
+git diff --binary HEAD > out/hardware-first/source-changes.patch
+./tools/version > out/hardware-first/build-version.txt
+sha256sum out/fds-internal.img out/fds-system-cli.img \
+  out/fds-boot.img out/fds-recovery.img out/fds-initramfs.img \
+  out/kernel/boot/kernel_2712.img > out/hardware-first/images.sha256
+cp out/boot-volume/files/cmdline.txt out/hardware-first/cmdline-built.txt
+```
+
+Keep any untracked build inputs separately too. These checksums identify your
+local build; they are not a release signature. For a downloaded release, follow
+[signature verification](releases.md) and use its matching complete image set.
+The historical `0.1.0` release and its acceptance records remain separate from
+new local builds.
+
+## 4. Check NVMe boot configuration
+
+If the Pi already boots from this NVMe adapter, first record its EEPROM settings;
+changing firmware is not a prerequisite just to try FDS. Otherwise, use a
+separate Raspberry Pi OS maintenance microSD with the official EEPROM utilities.
+Keep that rescue medium available throughout bring-up.
+
+In the **maintenance OS**, before editing:
+
+```sh
+rpi-eeprom-config > pi-current.conf
+rpi-eeprom-update > pi-eeprom-status.txt
+```
+
+Copy these files to the workstation and preserve the matching original firmware
+as described in [EEPROM preparation and rollback](eeprom.md). To review the
+installed boot configuration, the official editor is:
+
+```sh
+sudo rpi-eeprom-config --edit
+```
+
+For initial FDS bring-up, `BOOT_ORDER=0xf16` means NVMe first, SD fallback, then
+repeat (read from the right). A non-HAT+ NVMe adapter may also require
+`PCIE_PROBE=1`; follow the adapter's instructions and the
+[official PCIe boot procedure](https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#boot-from-pcie).
+Preserve unrelated board settings, follow the updater's restart instructions,
+then read the configuration back. FDS already supplies `dtparam=pciex1` in
+`config.txt`; EEPROM discovery and the kernel's PCIe enablement are separate.
+
+The [FDS EEPROM development profile](eeprom.md#profile-behavior) also keeps SD
+fallback and enables firmware UART logging. Its offline preview is not a backup
+of your board and does not apply itself. Do not switch to NVMe-only production
+boot order until the rescue and normal boot paths have been checked.
+
+## 5. Write the two disks
+
+On the **workstation**, follow the complete
+[guarded disk-writing procedure](internal-storage.md#install-the-internal-disk).
+It includes disk identification by model/serial, an explicit erase confirmation,
+readback, and backup-GPT relocation. Run it separately for these assignments:
+
+| Pass | `fds_image` | `fds_disk` |
+| --- | --- | --- |
+| Internal disk | `$PWD/out/fds-internal.img` | The verified NVMe enclosure's whole-disk `/dev/disk/by-id/…` path |
+| SYSTEM | `$PWD/out/fds-system-cli.img` | A different, verified USB cartridge's whole-disk `/dev/disk/by-id/…` path |
+
+Both writes erase the selected disk. Follow all checks in that procedure; a
+`-part1` path is not a whole-disk destination. The disks must use 512-byte logical
+sectors and be at least as large as their respective images.
+
+Confirm the three internal partition labels and the USB's single `FDS_SYSTEM`
+label after writing. Safely disconnect the disks, install NVMe on the powered-off
+Pi, and connect exactly one SYSTEM. Do not leave the NVMe enclosure connected as
+a duplicate source of FDS partitions.
+
+## 6. Power on and reach the console
+
+Power the monitor and any required hub, attach video, USB control, keyboard and
+SYSTEM, then power the Pi. Remove the maintenance SD for this attempt so an SD
+fallback cannot be mistaken for an FDS boot.
+
+The expected sequence is Pi firmware → kernel and stage0 from NVMe → read-only
+SYSTEM from USB → native s6 → `FDS>`. The production image is quiet, so a missing
+splash or scrolling kernel log is not by itself a failure. At **FDS**, run:
+
+```sh
+fds info
+cat /usr/share/fds/image-profile
+cat /proc/cmdline
+findmnt -no SOURCE,FSTYPE,OPTIONS /
+ps -p 1 -o pid,comm,args
+fds machine status
+fds bays
+fds topology
+fds boot-profile
+```
+
+Expect the intended version/profile, an EROFS root mounted read-only, and native
+s6 as PID 1. `fds machine status` should report `internal_nvme` for valid internal
+settings; `image_defaults` means settings loading fell back and needs diagnosis.
+An empty initial map still legitimately reports `UNCONFIGURED` bays. Stage0
+discovers SYSTEM by its GPT partition label before bay mapping, so that does not
+prevent reaching the console. Do not unplug the running SYSTEM even if it has
+not yet acquired a bay number.
+
+If no SYSTEM is found, stage0 waits for media. Its prompt accepts `list`,
+`rescan`, `recovery`, `reboot` and `poweroff`; inserting one valid SYSTEM should
+resume boot. Two matching SYSTEMs are ambiguous: remove the unintended one.
+This prompt is an early-boot command interface, not Bash.
+
+The normal console is the ordinary `fds` user (UID 1000), with a temporary home
+and locked account passwords. For root diagnostics, shut down with `fds poweroff`,
+remove SYSTEM after shutdown, boot again and type `recovery` at stage0's
+missing-SYSTEM prompt. The independent recovery image opens `RECOVERY#`.
+Use that root console for monitor diagnostics and initial machine configuration;
+there is no default root password to enter at `FDS>`.
+
+## 7. Verify HDMI and the Dasung controller
+
+At **`RECOVERY#`**, with both HDMI and USB data connected:
+
+```sh
+lsusb
+lsusb -t
+dasungd status
+dasungd query
+tail -80 /run/log/dasungd/current
+```
+
+The existing profile expects UART `1a86:7523` and companion bridge `1a86:5512`
+under the same USB hub, plus a connected DRM output matching the configured
+monitor serial. Query again and check status after replies arrive: `connected`
+alone is not the same as `responsive`. See [Dasung diagnostics](dasung.md) for
+DRM capture, blank HDMI, missing USB interfaces and the 37 Hz override.
+
+Confirm visible text entry, a refresh, and parameter readback separately. Once
+basic operation works, test a **monitor-only** off/on cycle while retaining Pi
+power, SYSTEM and hub power; record the picture, USB re-enumeration and daemon
+reconnection. This is not permission to unplug writable storage. A passing VM
+controller test cannot establish physical monitor recovery.
+
+## 8. Install the first bay map without a DATA cartridge
+
+Stay at **`RECOVERY#`**. Keep the hubs in their intended final ports. Insert one
+identifiable test USB device at a time and record `fds topology` for each physical
+slot. Test USB 2 and USB 3 connections separately where supported. Map only the
+slots currently assembled; unmapped slots can remain unconfigured.
+
+Create editable settings in RAM:
+
+```sh
+fds machine export /tmp/my-machine
+cat /tmp/my-machine/machine.toml
+fds topology
+```
+
+Recovery includes Bash but no full-screen editor. Use a here-document to enter
+the measured map. **The path below is a syntax example, not a Pi port identity**:
+replace it and the port number with your actual observation before installing.
+If the observed device path ends in `:usb2/1/3`, the parent hub ends in
+`:usb2/1` and downstream port `3` maps to your chosen bay number:
+
+```sh
+cat > /tmp/my-machine/bays.toml <<'EOF'
+[first_usb2]
+hub = "platform/REPLACE_WITH_OBSERVED_CONTROLLER:usb2/1"
+[first_usb2.ports]
+3 = 1
+EOF
+```
+
+Add separate groups for the measured USB 3 aliases and other hubs following
+[the mapping reference](developer/cartridges.md#calibrate-the-physical-bay-map).
+Do not map keyboard/monitor connections as cartridge bays or copy the emulator's
+map. Validation checks syntax and conflicts; only your insertion tests establish
+that a mapping matches the physical labels.
+
+```sh
+cat /tmp/my-machine/bays.toml
+fds machine validate /tmp/my-machine
+fds machine install /tmp/my-machine
+fds reboot
+```
+
+Installation writes the complete settings bundle to NVMe and retains the previous
+one; it does not change the active mapping during this boot. With SYSTEM still
+absent, select `recovery` again after reboot. Verify `fds machine status`, then
+`fds bay 01` as you move the test device through the configured slots. Use
+`fds eject N` and wait for SAFE before removing storage managed in a mapped bay.
+
+Later, [export a backup and update settings from DATA](internal-storage.md#update-settings-from-recovery).
+Do not reflash the whole NVMe merely to change bay numbering: that would replace
+saved settings and diagnostics. For normal boot, shut down, insert SYSTEM,
+and power on again.
+
+## 9. Save evidence and shut down
+
+At **`RECOVERY#`**, collect a fresh capture and explicitly save it to NVMe before
+losing the RAM filesystem:
+
+```sh
+bash /usr/share/fds/capture-hardware /tmp/hardware-first
+cat /tmp/hardware-first/status.tsv
+dasungd status > /tmp/hardware-first/dasung-status.json
+cp /run/log/dasungd/current /tmp/hardware-first/dasung.log
+tar -C /tmp -czf /tmp/hardware-first.tar.gz hardware-first
+fds machine store hardware-first.tar.gz /tmp/hardware-first.tar.gz
+fds power status
+fds poweroff
+```
+
+Stored names must be new and files must be at most 16 MiB. The collector's
+`SHA256SUMS` covers its own original outputs; the two manually added Dasung files
+are additional evidence. Retrieve the archive later with
+`fds machine fetch hardware-first.tar.gz /tmp/retrieved-hardware-first.tar.gz`
+from recovery, then copy it to healthy, explicitly activated DATA and safely eject.
+This capture describes the recovery boot; collect another capture in normal FDS
+on DATA when that path is ready. `/tmp`, `/run`, logs and the normal home are
+otherwise lost at shutdown.
+
+Fill the workstation session record with observed results, wiring, EEPROM version,
+image hashes and remaining failures. Leave unperformed cases `not_run`. Log
+events measure software stages; physical power-on-to-picture and power-off timing
+need an external observation. Follow [physical acceptance testing](developer/stress-testing.md#physical-acceptance-sequence)
+when the complete assembly is ready.
+
+Use `fds poweroff` and wait for shutdown before disconnecting power or swapping
+SYSTEM. If shutdown is blocked, inspect `fds power status` and resolve the
+reported storage problem. An E-Ink picture can remain visible after power is
+removed, so the retained picture is not proof that the Pi is still running.
+After basic console/display checks, try the [optional desktop](desktop.md) and
+[cartridge workflow](cartridges.md).
+
+## When the first boot fails
+
+| Observation | Next check |
+| --- | --- |
+| Firmware cannot find NVMe | Adapter/ribbon seating, supply, EEPROM boot order, and conditional `PCIE_PROBE=1`; return to the maintenance SD |
+| Stage0 says SYSTEM is missing | Whole GPT SYSTEM image, exactly one `FDS_SYSTEM`, USB power and `list`; bay calibration is not required at this stage |
+| HDMI is blank or unstable | Monitor input/power, cable connector sizes, then [native HDMI EDID](dasung.md#try-the-monitors-own-hdmi-edid) or the serial console below |
+| Kernel text appears but keyboard cannot reach a prompt | Check whether `BOOT_MODE=development` made UART the primary console |
+| Picture works, `dasungd` does not | USB data cable, both USB IDs, DRM serial, permissions and daemon log; see [Dasung diagnostics](dasung.md) |
+| `fds bays` is unconfigured | Complete step 8 using physical topology observations |
+| `fds machine status` uses image defaults | Check the reported reason, NVMe transport, partition layout and clean internal ext4; do not run DATA repair against internal NVMe |
+| USB resets or disappears under load | Reduce attached devices and check the Pi, monitor and hub supplies separately |
+
+### Use a serial console when HDMI is unavailable
+
+Use the Pi 5's dedicated debug UART connector and a compatible 3.3 V UART/debug
+probe, following the [official UART documentation](https://www.raspberrypi.com/documentation/computers/configuration.html#configuring-uarts).
+Connect the probe's host USB to the workstation, then open its serial terminal at
+**115200 baud, 8 data bits, no parity, 1 stop bit, no flow control**. This is a
+separate connection from the monitor's USB cable. Save the terminal log.
+
+For an initial, still-disposable disk build, replace step 3's boot mode with
+`make boot-volume BOOT_MODE=development` before `make internal-image`. This
+enables verbose kernel output and selects `ttyAMA10` as the primary userspace
+console. The development EEPROM profile separately enables firmware UART output.
+Boot mode does not grant root; select recovery for a root shell.
+
+For an already provisioned NVMe, use the
+[offline BOOT edit procedure](dasung.md#edit-the-boot-command-line-offline) and
+copy the single line from [cmdline-development.txt](../image/pi5/cmdline-development.txt)
+into the disk's `cmdline.txt`; preserve any deliberate native-EDID diagnostic
+change. This avoids overwriting settings to switch consoles. Restore the saved
+command line to return to display/keyboard operation after debugging.

docs/internal-storage.md

@@ -7,6 +7,9 @@ persistent machine settings. The operating system itself lives on a removable
 SYSTEM cartridge. This guide covers preparing the internal disk and updating
 its settings from recovery.
 
+For the complete first-install sequence, including cabling, EEPROM and a first
+bay map without DATA, use [the real-hardware setup guide](hardware-setup.md).
+
 ## Build the complete disk image
 
 Build the component images first, in this order:

docs/recovery.md

@@ -5,6 +5,10 @@
 FDS recovery is an independent maintenance system on internal storage. It can
 inspect a failed SYSTEM, check DATA and help prepare replacement cartridges.
 
+For a machine whose bays have never been configured, follow
+[initial bay calibration](hardware-setup.md#8-install-the-first-bay-map-without-a-data-cartridge)
+at the root recovery console before relying on a DATA cartridge for settings.
+
 ## Build the recovery image
 
 Use the prepared x86_64 build host described in [Your first build](getting-started.md).

docs/troubleshooting.md

@@ -5,6 +5,9 @@ Read the complete command error and its log before retrying. Build logs are in
 On FDS, `fds bay N`, `fds profiles` and `fds power status` report the relevant
 operation state. Append `--help` to a command for accepted options.
 
+For physical Pi startup, use [first-boot troubleshooting](hardware-setup.md#when-the-first-boot-fails).
+For the Paperlike on HDMI plus USB, use [Dasung diagnostics](dasung.md#diagnose-a-connection-problem).
+
 | Symptom | Resolution |
 | --- | --- |
 | Build disk is full | Stop builds and VMs; run `make clean-preview`, then `make clean`. See [retention rules](cleanup.md). |
@@ -12,7 +15,7 @@ operation state. Append `--help` to a command for accepted options.
 | Bubblewrap/user namespace failure | Check that the host permits unprivileged namespaces. Run the check in [setup](getting-started.md); do not switch software builds to root. |
 | Void checkout is unprepared | Bootstrap the checkout using upstream xbps-src instructions, then select it with `--void-packages`. |
 | Stale generated overlay/source package | Compare the source and generated copy. Preserve independent edits, remove only that generated copy, and retry. Never overwrite tracked upstream templates. |
-| Output already exists | Use a new output directory, cartridge image, preview or emulator session. Creation does not overwrite existing outputs. |
+| Output already exists | Use a new output directory, cartridge image or preview. A stopped emulator session can be restarted; see below. |
 | Executable architecture or tree integrity error | Rebuild the source package and cartridge. FDS cannot run an invalid payload. |
 | A command is unavailable | Wait for `MOUNTED READ ONLY`, inspect `fds --json bay N`, and use its qualified command alias. Run `hash -r` after removal if Bash retained an old path. |
 | Empty or unconfigured physical bays | Run `fds topology` and calibrate the machine's bay map. Do not infer slots from disk names. |

tests/hardware/README.md

@@ -1,7 +1,7 @@
 # Physical acceptance records
 
-Physical tests are deferred until the Pi and its attached hardware are available.
-Follow [the complete procedure](../../docs/developer/stress-testing.md), including bay
+Start with [real-hardware setup](../../docs/hardware-setup.md) on the assembled Pi.
+Then follow [the complete procedure](../../docs/developer/stress-testing.md), including bay
 calibration, repeatable device populations, explicit SAFE handling and separate
 external timing measurements.