docs: move prose documentation into docs/ so the docs site publishes it

The docs-site build syncs this repo's README.md and docs/ into the site
tree; nothing else is copied. All prose apart from the README therefore lived
outside the sync and never appeared on https://docs.lyrapup.pet/nixfiles/, and
the one page that did publish carried 18 link targets that resolved to nothing.

Moves:

  home/README.md           -> docs/shell.md
  home/KEYBINDINGS.md      -> docs/keybindings.md
  hosts/<Name>/README.md   -> docs/hosts/<name>.md

docs/.pages and docs/hosts/.pages give the awesome-pages plugin an explicit
order; new pages are picked up by the trailing '...' without an edit.

Links are rewritten so a single URL is correct in both Gitea and the published
site: absolute Gitea source URLs for .nix files and directories, relative links
between pages under docs/, and absolute docs.lyrapup.pet URLs from the root
README, which the build republishes at a different depth from the rest of the
tree. In-code comments that pointed at a moved README are updated to the new
path.

The README gains a Documentation section covering the sync contract and the
linking rules, and CLAUDE.md carries the short version so future edits do not
reintroduce unsynced pages or dead links.

Verified by reproducing the docs-site assembly locally against its pinned
toolchain (mkdocs 1.6.1, mkdocs-material 9.7.7, awesome-pages 2.10.1): pages
render at the URLs used above and in the declared order.

hosts/RPi5/README.md

@@ -1,69 +0,0 @@
-# Raspberry Pi 5 (`lyrathorpe-rpi5`)
-
-Headless `aarch64-linux` server with two roles:
-
-- **Docker host** — daemon exposed over the network (`docker.nix`).
-- **nginx reverse proxy** — declarative `virtualHosts` (`reverse-proxy.nix`).
-
-## Install
-
-1. Flash a NixOS `aarch64` SD image (or USB) and boot the Pi. The
-   `raspberry-pi-5` profile from `nixos-hardware` (wired in the flake host table)
-   supplies the kernel, firmware and device tree; boot is U-Boot + extlinux.
-2. Partition/mount the target, then **regenerate the hardware config on the
-   device** and replace the committed placeholder:
-   ```sh
-   nixos-generate-config --root /mnt
-   # copy /mnt/etc/nixos/hardware-configuration.nix over
-   # hosts/RPi5/hardware-configuration.nix in this repo, then commit
-   ```
-   `hardware-configuration.nix` in this directory is a **placeholder** committed
-   only so the host evaluates in CI. The machine will not boot correctly until it
-   is replaced with the generated one.
-3. Set the host name to match the flake attribute (already done in
-   `configuration.nix`: `lyrathorpe-rpi5`) and build:
-   ```sh
-   sudo nixos-rebuild switch --flake .#lyrathorpe-rpi5
-   # or, once the hostname is live:
-   nh os switch
-   ```
-4. Give the login user a password (`passwd lyrathorpe`) and confirm the key in
-   the user registry (`../../users/registry.nix`, applied by
-   `../../modules/ssh.nix`) is the one you will connect with.
-
-## Docker socket (security)
-
-The daemon listens on **plain TCP `2375`, no TLS, no auth**. Access is
-root-equivalent on this host. The only protection is the nftables rule in
-`docker.nix`, which accepts `2375` **only** from the trusted LAN subnet
-(`10.187.1.0/24` by default — change it to match your network). Do not widen
-that subnet to anything untrusted.
-
-From a LAN client:
-
-```sh
-export DOCKER_HOST=tcp://lyrathorpe-rpi5:2375
-docker info
-```
-
-The secure upgrade path is mutual TLS on `2376` (`--tlsverify` with a CA and
-client certs); it needs out-of-band cert provisioning and is intentionally not
-wired here.
-
-## Adding a reverse-proxy site
-
-Each proxied service is a Nix entry in `reverse-proxy.nix`:
-
-```nix
-services.nginx.virtualHosts."app.example.lan" = {
-  # enableACME = true; forceSSL = true;   # once a DNS name + cert exist
-  locations."/" = {
-    proxyPass = "http://127.0.0.1:8080";  # e.g. a local container
-    proxyWebsockets = true;
-  };
-};
-```
-
-The example vhost is HTTP-only by design. Turn on `enableACME`/`forceSSL`
-per-vhost once the host has a real DNS name and the ACME challenge can be met;
-`443` is already open in the firewall.

hosts/RPi5/configuration.nix

@@ -2,7 +2,7 @@
 # ./docker.nix (Docker host with a network socket) and ./reverse-proxy.nix
 # (native nginx). The raspberry-pi-5 nixos-hardware profile (kernel, firmware,
 # device tree) and key-only sshd (../../modules/ssh.nix) are layered on in the
-# flake host table. Install notes: see ./README.md.
+# flake host table. Install notes: see ../../docs/hosts/rpi5.md.
 { ... }:
 {
   imports = [

hosts/RPi5/hardware-configuration.nix

@@ -4,7 +4,7 @@
 # evaluates in CI before the Pi is provisioned. The machine will not boot from
 # it as-is. On first install, regenerate this file on the device with
 #   nixos-generate-config --root /mnt
-# and replace this placeholder with the output (commit it). See ./README.md.
+# and replace this placeholder with the output (commit it). See ../../docs/hosts/rpi5.md.
 #
 # Like every hardware-configuration.nix in this repo, this file is excluded from
 # the formatter and linters (see the pre-commit/treefmt excludes in flake.nix).