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.

README.md

@@ -0,0 +1,85 @@
+# Arcline OS — build system
+
+> The Linux OS for people who run infrastructure. Hardened Debian base.
+> Pre-configured monitoring, auditing, and security tooling. Zero telemetry.
+
+This repository is the build system ("the wires") behind
+[Arcline OS](https://arcline.it). It turns a Debian base and a set of plain-text
+manifests into hardened, bootable operating system images for three editions:
+**Server**, **Workstation**, and **Cloud**.
+
+## What you get
+
+- A transparent, script-based build pipeline (no magic, everything auditable)
+- `debootstrap` → package install → overlay → in-chroot configure → live ISO
+- **Secure by default**: hardened kernel cmdline + sysctl, default-deny
+  nftables, key-only ssh, AppArmor, no core dumps
+- **btrfs-native**: subvolume layout, scheduled read-only snapshots, and
+  boot-to-snapshot rollback tooling
+- **Zero telemetry**: enforced by package selection, masked apt timers, and
+  smoke tests that fail the build if telemetry is found
+- **Pre-configured observability** (server): Prometheus + node_exporter +
+  Grafana (auto-provisioned) + Loki + promtail, local-only
+- **The Arcline toolchain**: a harness that packages all 11 Go tools into
+  `.deb`s and installs them into the image
+- Smoke tests, GitLab CI, and docs that explain every decision
+
+## Quickstart
+
+```bash
+# on a Debian-family host with root/sudo
+make deps              # install host build dependencies
+make check             # validate the tree (fast, offline)
+make iso-server        # build a bootable server ISO
+make iso               # build all three editions
+make toolchain         # build the 11 Go tools into .deb
+make iso-server-minimal # server ISO WITHOUT the Arcline toolchain
+make test              # run smoke tests against built rootfs(es)
+```
+
+Artifacts land in `build/artifacts/` with `.sha256` checksums.
+
+The Arcline tools are **optional** in an image (`ARCLINE_TOOLCHAIN=auto|skip|
+require`; see [building](docs/building.md#building-without-the-arcline-toolchain)).
+
+## Layout
+
+```
+os-build/
+├── Makefile            # thin orchestration (make iso-<edition>)
+├── versions.mk         # single source of truth for versions/paths
+├── editions/           # per-edition manifests (packages, cmdline, fstab, metadata)
+├── overlays/           # files that land in the image (base + per-edition layers)
+├── scripts/            # the build pipeline (all plain bash)
+├── btrfs/              # subvolume layout, snapshots, rollback
+├── toolchain/          # packaging for the 11 Go tools
+├── observability/      # Prometheus/Grafana/Loki configs (docs + overlays/server)
+├── tests/              # tree validation + rootfs smoke tests
+├── ci/                 # GitLab CI pipeline
+└── docs/               # architecture, hardening, building, editions, ...
+```
+
+## Documentation
+
+| Doc | Contents |
+|-----|----------|
+| [architecture](docs/architecture.md) | the design and how a build flows |
+| [building](docs/building.md) | prerequisites, quickstart, outputs, knobs |
+| [hardening](docs/hardening.md) | every hardening decision, and how to tune it |
+| [editions](docs/editions.md) | server / workstation / cloud manifests |
+| [observability](docs/observability.md) | the pre-configured monitoring stack |
+| [toolchain](docs/toolchain.md) | the 11 Go tools and their packaging |
+| [btrfs](btrfs/README.md) | subvolume layout + snapshots + rollback |
+
+## Status
+
+This is the **foundation**: the build pipeline, edition manifests, hardening
+baseline, btrfs tooling, observability configs, tests, and CI are in place and
+runnable. The next milestones (installer that writes the btrfs layout to disk,
+cloud disk images, signed releases) are listed in
+[docs/architecture.md](docs/architecture.md#follow-up-work).
+
+## License
+
+GPL-3.0 — see [LICENSE](LICENSE). Sponsored by Arcline IT LLC.
+No telemetry. No tracking.