docs: add architecture, hardening, and building documentation

Document the design and how to operate it: architecture, building
(including toolchain-free/minimal builds), hardening guide, editions,
observability, and the toolchain. README ties it together.

docs/building.md

@@ -0,0 +1,92 @@
+# Building Arcline OS
+
+## Prerequisites
+
+A Debian-family host (or container) with root/sudo:
+
+```
+debootstrap        # rootfs bootstrap
+squashfs-tools     # ISO rootfs compression
+grub2-common       # grub-mkrescue (hybrid ISO)
+xorriso cpio       # ISO assembly
+bash make curl git # build orchestration
+go (≥ 1.21)        # only needed for `make toolchain`
+```
+
+Check or install them:
+
+```
+scripts/check-host-deps.sh            # report what's missing
+scripts/check-host-deps.sh --install  # apt-get install the missing bits
+```
+
+## Quickstart
+
+```
+make check          # validate the tree (fast, offline, safe)
+make rootfs-server  # build just the server rootfs
+make iso-server     # build a bootable server ISO
+make iso            # build all three editions
+make toolchain      # build the 11 Go tools into .deb
+make test           # run smoke tests against built rootfs(es)
+```
+
+## Outputs
+
+Everything lands under `build/`:
+
+| Path | Contents |
+|------|----------|
+| `build/rootfs/<edition>/` | extracted rootfs (from `make rootfs-*`) |
+| `build/artifacts/arcline-<edition>-<version>-<arch>.tar.xz` | archived rootfs |
+| `build/artifacts/arcline-<edition>-<version>-<arch>.iso` | bootable live ISO |
+| `build/debs/*.deb` | Arcline toolchain packages (from `make toolchain`) |
+
+Each artifact ships with a `.sha256` checksum file.
+
+## Reproducibility knobs
+
+Set these as environment variables or edit `versions.mk`:
+
+| Variable | Meaning | Default |
+|----------|---------|---------|
+| `VERSION` | release version string | `0.1.0` |
+| `DEBIAN_SUITE` | Debian base | `bookworm` |
+| `ARCH` | target architecture | `amd64` |
+| `DEBIAN_MIRROR` | mirror for the base | `http://deb.debian.org/debian` |
+| `ARCLINE_LIVE` | install live-boot into rootfs | unset (set by ISO build) |
+| `ARCLINE_LOCK_ROOT` | lock root account (`passwd -l root`) | `0` |
+| `ARCLINE_EXTRA_REPOS` | fetch grafana/loki upstream repos | `0` |
+| `ARCLINE_TOOLCHAIN` | toolchain in image builds | `auto` |
+
+## Building without the Arcline toolchain
+
+The 11 Go tools (see `docs/toolchain.md`) are **optional** in an image — a
+normal `make iso-server` with no `.deb`s in `build/debs/` already produces a
+minimal, toolchain-free image. This is controlled by `ARCLINE_TOOLCHAIN`:
+
+| Mode | Behaviour |
+|------|-----------|
+| `auto` (default) | install the tools if `build/debs/*.deb` exist, otherwise build without them (with a warning) |
+| `skip` | never install the tools, even if debs are present |
+| `require` | **fail** the build if no toolchain debs are available |
+
+Examples:
+
+```bash
+make iso-server                # auto: tools in if you ran `make toolchain`
+make iso-server-minimal        # skip: guaranteed toolchain-free image
+ARCLINE_TOOLCHAIN=skip make iso-server
+ARCLINE_TOOLCHAIN=require make iso-server   # release builds must ship the tools
+```
+
+Everything else — hardened base, firewall, btrfs, observability
+(Prometheus/node_exporter are Debian-main packages), zero-telemetry — is
+independent of the toolchain and always included.
+
+## Notes on the ISO
+
+The ISO boots a **live** system (via `live-boot`): the rootfs is compressed to
+a squashfs and mounted on boot, so you can try an edition before installing it
+to disk. The same rootfs can be installed with the btrfs layout via
+`btrfs/init.sh` (the installer is follow-up work — see `docs/architecture.md`).