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/architecture.md

@@ -0,0 +1,68 @@
+# Arcline OS — architecture
+
+This is the foundation ("the wires") for Arcline OS: a hardened, Debian-derived
+operating system for people who run infrastructure. The landing page describes
+the product; this repository is how it gets built.
+
+## Design goals
+
+1. **Secure by default** — hardened kernel, default-deny firewall, AppArmor,
+   locked-down ssh. You opt *in* to exposure, never out.
+2. **Zero telemetry** — no phone-home, no analytics, no cloud integration.
+3. **btrfs-native** — snapshots and boot-to-snapshot rollback are built in.
+4. **Production-ready from first boot** — observability pre-configured, tools
+   pre-installed, everything documented.
+5. **Auditable** — every script and config is plain text in this repo.
+
+## How a build flows
+
+```mermaid
+flowchart LR
+    A[editions/* metadata] --> B[debootstrap<br/>Debian bookworm]
+    B --> C[install edition<br/>packages.list]
+    C --> D[apply overlays<br/>base + edition]
+    D --> E[configure-system.sh<br/>in chroot]
+    E --> F[rootfs .tar.xz]
+    F --> G[grub-mkrescue + squashfs<br/>→ live ISO]
+    E -.toolchain .debs.-> C
+```
+
+Pipeline stages live in `scripts/`:
+
+| Stage | Script | What it does |
+|-------|--------|--------------|
+| bootstrap | `build-rootfs.sh` | debootstrap minbase, apt sources, package install |
+| overlay | `apply-overlays.sh` | copies `overlays/base` + `overlays/<edition>` into the rootfs |
+| configure | `configure-system.sh` | runs *in the chroot*: hostname, locale, kernel cmdline, services, live-boot, toolchain |
+| package | `build-iso.sh` | kernel + initramfs + squashfs → hybrid BIOS/UEFI ISO |
+| orchestrate | `build-edition.sh` / `Makefile` | wire the above to `make iso-<edition>` |
+
+## The four source trees
+
+| Path | Role |
+|------|------|
+| `editions/` | per-edition **manifests**: package lists, kernel cmdline, fstab, metadata |
+| `overlays/` | **files that land in the image**, organised as layered rootfs trees |
+| `scripts/` | the **build pipeline** (all plain bash, readable top to bottom) |
+| `btrfs/`, `toolchain/`, `observability/`, `tests/`, `ci/` | supporting subsystems |
+
+There is no hidden magic: the Makefile is a thin wrapper, `versions.mk` /
+`scripts/common.sh` hold the single source of truth for versions and paths.
+
+## Zero telemetry, enforced
+
+- No distro telemetry packages are installed (`ubuntu-report`,
+  `popularity-contest`, snapd are never in a package list).
+- apt automatic-update timers are **masked** in every edition's metadata.
+- The firewall's output chain never initiates calls on its own.
+- cloud-init is pointed only at the configured cloud datasource.
+- The smoke tests (`tests/smoke/verify-rootfs.sh`) fail the build if telemetry
+  artifacts are found.
+
+## Follow-up work (explicitly out of scope for "the wires")
+
+- Partitioning/installer that runs `btrfs/init.sh` on a target disk.
+- Cloud images (qcow2/raw) for the `cloud` edition — the ISO path is wired,
+  a disk-image path is the next step.
+- Grafana/Loki packaged as `.deb`s rather than fetched from upstream.
+- A signed (secure-boot) kernel for official releases.