Package workstation tools, reuse emulator sessions, and derive build versions

docs/developer/README.md

@@ -80,3 +80,5 @@ cartridge creation: new payloads contain installed Void package trees.
 - [troubleshooting](troubleshooting.md)
 - [workstation-tooling-plan](workstation-tooling-plan.md)
 - [workstation](workstation.md)
+
+- [Git-derived build versions and Arch packaging](versioning.md)

docs/developer/build-host.md

@@ -46,7 +46,10 @@ indexing also explicitly sets `XBPS_ARCH=aarch64`.
 
 ## Generic Linux workstation tools and desktop additions
 
-`make workstation` builds native `fds-cartridge` and `fds-emulator`. Runtime
+`make workstation` builds the Arch `fds-tools` package; `make workstation-install`
+installs it with pacman. `make workstation-binaries` builds native `fds-cartridge`
+and `fds-emulator` on generic Linux. Python 3 and Git resolve build versions;
+Dasung builds install these tools in the project-local Void container as well. Runtime
 requirements are QEMU, erofs-utils, bubblewrap and native XBPS with a prepared
 Void source checkout for software creation. `fds-cartridge` invokes xbps-src,
 installs runtime dependencies and creates direct EROFS trees. The Rust tar reader

docs/developer/releases.md

@@ -141,7 +141,7 @@ The JSON document has exactly these fields:
 
 This is a schema illustration, not a usable manifest: the size and hash
 placeholders must be replaced with values from the actual artifact. Format 1
-accepts the current tool version, a positive source epoch, a 40-character Void
+accepts a bounded numeric-leading release/development version, a positive source epoch, a 40-character Void
 commit, and 1–64 nonempty artifacts. Filenames must be flat safe ASCII names;
 paths, duplicates, hidden names, reserved manifest filenames and unknown fields
 are rejected. The manifest is bounded to 1 MiB. Files must be regular files,

docs/developer/tooling.md

@@ -10,7 +10,8 @@ entry point. Both executables cross-build as static-musl AArch64 programs. The
 normal OS continues to use glibc; no target musl runtime package is added.
 
 For native Linux software packaging and QEMU hotplug, use `make workstation`
-and the [workstation guide](workstation.md). Those Clap tools are host binaries;
+on Arch, or `make workstation-binaries` on other Linux distributions, and follow
+the [current workstation guide](../workstation.md). Those Clap tools are host binaries;
 `make tooling` below builds the static ARM runtime tools.
 
 ## Build and test

docs/developer/versioning.md

@@ -0,0 +1,78 @@
+# Build versions and the workstation package
+
+`tools/version` is the authoritative FDS build-version resolver. It reads this
+repository's Git history, never the Void submodule's history. All FDS Rust
+commands, base XBPS packages, login/boot banners and `/etc/os-release` use it.
+SYSTEM cartridge metadata copies the version already embedded in its rootfs,
+so wrapping an older rootfs does not mislabel it as the current source version.
+
+Release tags are numeric `MAJOR.MINOR` or `MAJOR.MINOR.PATCH`, optionally prefixed
+with `v`. Unrelated tags are ignored. The nearest reachable release tag is used:
+
+| Source state | Example build version |
+| --- | --- |
+| Exactly release tag `1.0`, clean checkout | `1.0` |
+| Two commits after `1.0` | `1.0.r2.g123456789abc` |
+| No reachable release tag | `0.dev.g123456789abc` |
+| Uncommitted changes to tracked files | Append `.dirty` |
+
+Untracked files do not affect the version, matching Git’s usual dirty-checkout
+convention. Add new release sources to Git before tagging.
+
+Versions are bounded to 32 letters, digits and periods, starting with a digit,
+for the cartridge metadata, XBPS and Arch package formats. A shallow clone
+without a reachable release tag gets a development version; fetch the intended
+release tag/history before building a release. No value is silently invented
+when both Git identity and an exported identity are missing.
+
+Each Rust crate uses the shared build script, including direct Cargo builds.
+Cargo notices tag/ref changes, index changes and source edits, avoiding an old
+version string in a cached binary. Cargo's workspace metadata uses the SemVer
+form `1.0.0`; the public build version comes from Git. Protocol/schema versions,
+application recipe versions, the Linux kernel version and third-party package
+versions are independent and remain unchanged.
+
+`tools/prepare-void` writes the resolved value to the writable build checkout's
+`fds-version` file. FDS-owned XBPS templates read it; base-files substitutes it
+into `/usr/lib/os-release` and `/etc/issue`. `/etc/os-release` links to that
+installed identity file. Runtime checks compare installed command versions
+against `VERSION_ID`. Superseded FDS packages are archived under
+`out/package-history/` so the active repository cannot accidentally select an
+older development package whose version sorts above a release.
+
+Frozen source exports save a validated `FDS_VERSION` file before inventorying
+and hashing their contents. Their builds use that saved value without Git or
+network access. Legacy 0.1.0 snapshots retain their original scripts and layout;
+the historical release stays unchanged. Release verification accepts supported
+version strings independently of the verifier's own version, so newer tools can
+still authenticate an older signed release using the supplied trust key.
+
+## Build and install on Arch
+
+`packaging/arch/PKGBUILD` packages the local checkout. `make workstation` invokes
+makepkg, building both binaries in the existing Cargo cache and recording the
+result in `out/workstation/package-path.txt`. It builds without implicit package
+installation; required build commands are checked directly. Runtime feature
+packages are declared as optional because project-local runners are supported.
+`make workstation-install` explicitly invokes pacman to install the exact
+recorded package. Generic Linux users use `make workstation-binaries`.
+
+The package includes binaries, the user/developer manuals, source examples,
+MIT licensing and dependency notices. It has no service, hook or installation
+script. The workflow follows the official [PKGBUILD specification](https://man.archlinux.org/man/PKGBUILD.5.en)
+and [makepkg interface](https://man.archlinux.org/man/makepkg.8.en).
+
+## Verification
+
+`make check` includes release/no-tag/dirty/export and real Cargo cache-invalidation
+checks. `make workstation-test` exercises the installed-tree cartridge creator;
+`make emulator-test` covers stopping and starting the same directory, preserved
+logs/overlays/mappings, and rejecting a restart of a live VM.
+`make workstation-package-test` installs the real Arch package with pacman in a
+disposable root and executes both installed commands. After building matching
+images, `python3 tests/integration/version-images.py` reads the identity and
+metadata directly from the GPT/EROFS image and executes its twelve FDS commands
+under ARM emulation to compare their versions. Image acceptance
+requires a new CLI rootfs and SYSTEM image: inspect their identity, execute the
+ARM tools and run the VM checks. A VM result does not establish physical Pi or
+Dasung power-cycle behavior.

docs/developer/workstation-tooling-plan.md

@@ -22,3 +22,8 @@ unchanged. Build new matching artifacts and record their hashes and source input
 See [user instructions](../workstation.md) and [format reference](../software-format.md)
 for the supported interface. Historical xz acceptance remains in
 [the earlier workstation record](workstation-validation.md).
+
+The Arch distribution package is `fds-tools`, built by `make workstation` and
+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.

docs/developer/workstation.md

@@ -3,7 +3,11 @@
 Development reference and historical context. For current operating instructions, use the [user manual](../README.md). Acceptance applies only to the source and artifacts identified in each record.
 
 
-This guide uses a **Linux workstation**, not the Raspberry Pi. It takes you from
+This page records the earlier archive-based software prototype. For installed
+Void software trees, the Arch `fds-tools` package, and reusable emulator sessions,
+follow the [current walkthrough](../workstation.md).
+
+This historical guide uses a **Linux workstation**, not the Raspberry Pi. It takes you from
 source software to a cartridge disk image, runs that image in FDS, and explains
 how to write the same complete image to USB. All commands run from the checkout
 root unless marked as guest commands.