Document unified image creation inspection and flashing

Developer-Media-Tools.md

@@ -110,6 +110,12 @@ and `fds-eject` are static aliases of the corresponding `fds` commands.
 
 ## Build a regular image from a prepared directory
 
+On a Linux workstation, these image operations are consolidated into
+`fds-flash create` and `fds-flash inspect` in the `fds-tools` package. See
+[the current guide](Flashing#create-a-cartridge-image). The `fds-burn` commands
+below remain available in the target FDS system; they are not a separate
+workstation installation.
+
 Prepare a directory containing a valid `FDS/CARTRIDGE.TOML`, plus the class's
 payload. The manifest format is described in [Cartridges](Developer-Cartridges). Then:
 

Developer-Workstation-Tooling-Plan.md

@@ -32,6 +32,13 @@ installed by `make workstation-install`. `make workstation-binaries` preserves
 the generic Linux build. Stopped emulator directories support a fresh boot while
 retaining logs, DATA overlays and archived cartridge mappings.
 
+`fds-flash` consolidates workstation creation, inspection and flashing. It reuses
+the `fds-burn` library for prepared DATA/ENVIRONMENT/SYSTEM trees, with typed
+Clap `create` subcommands and native e2fsprogs/erofs-utils. `inspect` handles
+complete internal and cartridge images without a destination. The Pi's existing
+`fds-burn` worker and bay-control interface remain in the target package.
+New PROGRAM creation continues through `fds-cartridge` and installed Void trees.
+
 `fds-flash` installs complete internal and cartridge GPT images. Its interactive
 mode requires terminal confirmation; unattended mode binds a specific image
 SHA-256 and target identity. Installation includes exclusive block access,

Flashing.md

@@ -6,11 +6,16 @@ include_toc: true
 
 [Home](Home) · [Real hardware](Hardware-Setup) · [Workstation tools](Workstation) · [Release verification](Releases)
 
-`fds-flash` installs a complete FDS disk image from a Linux workstation. It has
+`fds-flash` creates, inspects and installs FDS disk images from a Linux workstation. It has
 an interactive guide and an unattended mode for scripts. It validates the image,
 checks the destination, writes it, flushes it, reads the written bytes back, and
 relocates the backup GPT automatically when the destination is larger.
 You no longer need the manual `dd`, `cmp` and `sfdisk` installation sequence.
+Cartridge images and the internal disk use the same flashing command. The
+workstation image operations previously documented as `fds-burn create` and
+`fds-burn inspect` are now available under `fds-flash`. The workstation package
+does not install a separate `fds-burn`; the Pi retains that service worker and
+its bay-control interface.
 
 ## Install the tool
 
@@ -30,13 +35,25 @@ make workstation-binaries
 out/workstation/fds-flash --help
 ```
 
-Build as an ordinary user. Only physical disk writes require root. The examples
+Build as an ordinary user. Physical disk writes require root. The examples
 below use the checkout binary; substitute `fds-flash` after package installation.
-The flasher adds no crates or external runtime utilities: it uses the existing
+Inspection and flashing add no crates or external runtime utilities: they use the existing
 Clap, serde/JSON, SHA-256 and libc dependencies plus Linux block-device APIs.
 The Python commands in the scripting example only read saved JSON; Python is
 not required by the installed flasher.
 
+Image creation uses `e2fsprogs` for DATA and `erofs-utils` for ENVIRONMENT/SYSTEM.
+These optional package dependencies supply the filesystem builders and checkers:
+
+```sh
+sudo pacman -S --needed e2fsprogs erofs-utils
+```
+
+`fds-flash create` calls those native utilities in `/usr/bin`; it does not use
+`fds-cartridge`'s optional Void tool runners. Creating DATA or ENVIRONMENT images
+from your own files runs as an ordinary user. A prepared SYSTEM root can require
+privileges to read protected files and preserve its intended ownership.
+
 ## Choose the correct image
 
 | Image | Destination |
@@ -57,6 +74,57 @@ Use an uncompressed, complete FDS GPT disk image. The raw `fds-boot.img` and
 system images and 4 KiB logical-sector destinations are rejected. A disk must
 have 512-byte logical sectors and enough space for the complete image.
 
+## Create a cartridge image
+
+Creation writes a new regular image file. It does not select or write a disk.
+Start with a directory containing a valid `FDS/CARTRIDGE.TOML` manifest and the
+files to include. For example, create a small DATA image:
+
+```sh
+mkdir -p out/my-data-tree/FDS
+cat >out/my-data-tree/FDS/CARTRIDGE.TOML <<'EOF'
+format = 1
+[cartridge]
+id = "my.data"
+name = "My data"
+class = "data"
+version = "1.0"
+[media]
+writable = true
+EOF
+printf 'Hello from DATA\n' >out/my-data-tree/hello.txt
+out/workstation/fds-flash create data out/my-data-tree out/my-data.img --size-mib 128
+out/workstation/fds-flash inspect out/my-data.img
+sudo ./out/workstation/fds-flash --image out/my-data.img
+```
+
+`--size-mib` sets the DATA filesystem size (default 128 MiB, minimum 32 MiB).
+The complete image is slightly larger because it includes GPT metadata and
+alignment. Its filesystem root belongs to FDS UID/GID 1000. The output must be
+outside the source tree and must not already exist.
+
+For other prepared trees:
+
+```sh
+out/workstation/fds-flash create environment environment-tree environment.img
+out/workstation/fds-flash create system prepared-root system.img
+```
+
+The manifest class must match. ENVIRONMENT needs a read-only manifest with an
+`[activation]` profile; see [the manifest reference](Developer-Cartridges).
+SYSTEM needs a complete prepared FDS root, including native init, cartridge
+management and Dasung. Normal OS builds should use `make rootfs PROFILE=cli`
+and `make system-card PROFILE=cli`; the creation command does not install packages.
+
+Build new PROGRAM cartridges with [fds-cartridge](Workstation#build-the-example-cartridge),
+then inspect or flash the resulting complete image with `fds-flash`.
+`create program` is intentionally unavailable: new software uses installed Void
+package trees, while existing legacy images remain readable and flashable.
+
+Append `--json` to any `create` command for a result with `status: "created"`.
+`inspection` contains the image path, geometry and SHA-256. Progress and utility
+diagnostics go to stderr; creation failures return a nonzero exit status.
+
 ## Interactive mode
 
 Keep the Pi powered off while preparing its NVMe. Connect only the intended
@@ -99,6 +167,18 @@ alternative disk. Release the intended disk yourself and rerun if it is blocked.
 
 ## Inspect without writing
 
+Inspect an image without a connected disk or root privileges:
+
+```sh
+out/workstation/fds-flash inspect out/fds-internal.img
+out/workstation/fds-flash inspect out/my-data.img --json
+```
+
+This checks the same geometry and basic filesystem signatures as flashing and
+reports the complete image's SHA-256. JSON uses `status: "inspected"` and the
+same `inspection` object as creation. It accepts internal and all cartridge
+image classes. For PROGRAM software contents, also use `fds-cartridge inspect`.
+
 List physical disks and reasons they are unavailable:
 
 ```sh
@@ -188,7 +268,8 @@ the media, and continue with [first boot](Hardware-Setup#6-power-on-and-reach-th
 
 `--file-target` is only for existing disposable regular files, as an ordinary user.
 It is never inferred from a path, and root use of this test mode is rejected.
-`make flash-test` covers the public CLI, interactive terminal confirmation,
+`make flash-test` requires e2fsprogs and covers DATA creation, independent filesystem
+readback, inspection without a disk, the public CLI, interactive terminal confirmation,
 unattended bindings, cancellation, changed inputs, corruption, and exact/larger
 destinations. `make flash-vm-test` also exercises block-device writes and failures
 on isolated virtual NVMe/USB disks. These tests do not write host block devices.
@@ -220,4 +301,14 @@ record paths and package-validation evidence are recorded locally in
 `out/logs/flash-workstation-regression.log`. The existing frozen 0.1.0 release
 was not modified.
 
+The subsequent workstation-command consolidation was checked with the actual
+native `fds-flash`: DATA creation, inspection without a target, unattended file
+flashing, independent ext4 content readback, and rejection of invalid or existing
+outputs. ENVIRONMENT and prepared SYSTEM creation were checked with real EROFS
+filesystems and independent extraction, using project-local filesystem utilities
+inside a private namespace. The small SYSTEM source was an inert test fixture;
+this check does not establish bootability. The ARM virtual NVMe/USB flashing and
+failure checks also passed after the shared inspection refactor. Evidence for
+this revision is recorded in `out/manifests/fds-flash-consolidation-validation.json`.
+
 Linux interface reference: [kernel block-device ABI](https://www.kernel.org/doc/html/latest/admin-guide/abi-stable.html).

Workstation.md

@@ -27,12 +27,20 @@ install packages. `make workstation-install` builds that package and invokes
 remove it later with `sudo pacman -R fds-tools`. The exact latest package path is
 recorded in `out/workstation/package-path.txt`.
 
-The package requires glibc, GCC runtime libraries and xz. EROFS, bubblewrap and
+Use `fds-cartridge` to build PROGRAM software images, `fds-emulator` to run FDS,
-QEMU are optional package dependencies because the tools can use the project-local
+and `fds-flash` to create DATA/ENVIRONMENT/SYSTEM images from prepared trees,
-Void runners instead. For all features using native Arch utilities, install:
+inspect complete images, and write any supported image to a disk. Workstation
+`fds-burn` image operations are consolidated into `fds-flash`; there is no
+separate `/usr/bin/fds-burn` in this package. See [image creation and flashing](Flashing).
+
+The package requires glibc, GCC runtime libraries and xz. Filesystem utilities,
+bubblewrap and QEMU are optional dependencies for their respective features.
+`fds-cartridge` and `fds-emulator` can use project-local Void runners;
+`fds-flash create` requires native filesystem utilities. For all features using
+native Arch utilities, install:
 
 ```sh
-sudo pacman -S --needed bubblewrap erofs-utils qemu-system-aarch64 qemu-img
+sudo pacman -S --needed bubblewrap erofs-utils e2fsprogs qemu-system-aarch64 qemu-img
 ```
 
 On other Linux distributions, install Rust, a C linker, Make, Python 3 and Git,
@@ -51,6 +59,7 @@ prepared Void checkout are still separate source-build prerequisites.
 | --- | --- |
 | Prepared writable Void `void-packages` checkout and native XBPS utilities | Build source packages and install their AArch64 runtime dependencies |
 | `mkfs.erofs`, `fsck.erofs` | Create and inspect read-only payload filesystems |
+| `mkfs.ext4`, `e2fsck` from e2fsprogs | Create DATA images with `fds-flash create data` |
 | `bwrap` | Inspect filesystems and install package trees in a user namespace |
 | `xz` | Read older software cartridges and package/source archives |
 | `qemu-system-aarch64`, `qemu-img` | Run the emulator and create writable DATA overlays |