milestone 13: restructure docs to diataxis, tutorial, every command executed

README.md

@@ -44,7 +44,9 @@ DNS is on port 53, the web UI on <http://localhost:8080>. The config file
 seeds the database on first boot only; from then on the database is the
 truth and changes go through the UI, the API, or `nxdns export` /
 `nxdns import`. Full install instructions, including the systemd path and
-the Pi 5 recipe, are in [docs/operator.md](docs/operator.md).
+the Pi 5 recipe, are in
+[docs/how-to/install-with-systemd.md](docs/how-to/install-with-systemd.md) and
+[docs/how-to/install-with-docker.md](docs/how-to/install-with-docker.md).
 
 ## Building from source
 
@@ -62,11 +64,19 @@ zig build test --summary all                 # unit tests
 
 ## Documentation
 
-- [docs/operator.md](docs/operator.md) — install, configure, back up,
-  upgrade, troubleshoot
-- [docs/architecture.md](docs/architecture.md) — module map and design
-- [docs/config-reference.md](docs/config-reference.md) — every
+Start at [docs/README.md](docs/README.md), which splits the documentation
+into a tutorial, how-to guides, reference and explanation.
+
+- [docs/tutorial/first-run.md](docs/tutorial/first-run.md) — build it, resolve
+  a name, block a domain, on a scratch directory
+- [docs/how-to/install-with-systemd.md](docs/how-to/install-with-systemd.md) —
+  a real install, including the Raspberry Pi 5
+- [docs/reference/configuration.md](docs/reference/configuration.md) — every
   configuration field
-- [docs/api.md](docs/api.md) — REST API, auth and SSE
+- [docs/reference/api.md](docs/reference/api.md) — REST API, auth and SSE
+- [docs/reference/cli.md](docs/reference/cli.md) — subcommands, flags and exit
+  codes
+- [docs/explanation/architecture.md](docs/explanation/architecture.md) — module
+  map and design
 - [PLAN.md](PLAN.md) and [specs/](specs/) — scope, design decisions and
   per-milestone contracts