diff --git a/docs/jeannie.1.md b/docs/jeannie.1.md
new file mode 100644
index 0000000..f9013fe
--- /dev/null
+++ b/docs/jeannie.1.md
@@ -0,0 +1,289 @@
+# JEANNIE(1)
+
+## NAME
+
+jeannie - operate the personal homelab control pipeline
+
+## SYNOPSIS
+
+```sh
+./jeannie COMMAND [ARG...]
+```
+
+## DESCRIPTION
+
+`jeannie` is the main homelab operator script. It deploys and checks the Debian
+control host, Gitea, Raspberry Pi services, Pimox workers, Kubernetes platform
+components, applications, public edge routing, secrets tooling, and local AI
+helpers.
+
+Run mutating infrastructure commands from the Debian homelab host. Commands that
+can destroy or rewrite state have explicit confirmation environment variables.
+The canonical script name is `metadata.main_script` in `homelab.yml`.
+
+## COMMANDS
+
+### Core Lifecycle
+
+`up`
+: Deploy the full homelab pipeline. Runs early preflight, deploys Gitea and RPi
+services, runs full preflight and pre-apply doctor checks, then applies Pimox,
+OpenWrt, cluster, platform, apps, and edge stacks.
+
+`plan [all|provisioning|cluster|platform|apps|edge]`
+: Run OpenTofu plans without applying changes. The default target is `all`.
+
+`rebuild-cluster`
+: Back up current local OpenTofu state, destroy cluster state through the guarded
+nuke path, rebuild Pimox workers, recreate the cluster, and redeploy platform,
+apps, and edge.
+
+`stop-cluster`
+: Stop the Kubernetes control-plane runtime and worker VMs without destroying
+cluster state.
+
+`start-cluster`
+: Start the Kubernetes control-plane runtime and desired worker VMs.
+
+`status`
+: Print a compact health report for the configured homelab.
+
+`nuke`
+: Destroy Kubernetes state and Pimox worker VMs. Requires
+`LAB_CONFIRM_NUKE=homelab`.
+
+### Deploy Targets
+
+`apps`
+: Deploy platform applications and build or publish application images when
+needed.
+
+`deploy-gitea`
+: Deploy the external Gitea Docker Compose service on the Debian host.
+
+`rpi-services`
+: Deploy Pi-hole, Unbound, and Uptime Kuma on the Raspberry Pi.
+
+`bootstrap-gitea-repo`
+: Ensure the configured Gitea repository, branch, remotes, and host SSH key are
+ready.
+
+`openwrt`
+: Apply the OpenWrt VM stack.
+
+### Gitea Operations
+
+`backup-gitea`
+: Run a Gitea backup on the Debian host.
+
+`drill-gitea-restore`
+: Run the Gitea restore drill workflow.
+
+`install-gitea-runner [TOKEN]`
+: Install or repair the Gitea Actions runner. If `TOKEN` is omitted, the command
+uses the configured token source.
+
+### Checks And Doctors
+
+`preflight`
+: Run homelab preflight checks. This verifies inventory-derived host settings,
+Docker roots, Tailscale IPs, Gitea reachability, Pimox storage, and OCI edge SSH.
+
+`doctor-preapply`
+: Run blocking readiness checks used by `up` before high-blast-radius applies.
+It checks Debian free disk, Docker and containerd, Raspberry Pi Docker
+writability, Pimox storage, OCI edge disk, and Pi-hole DNS.
+
+`doctor-versions`
+: Check Kubernetes component version alignment.
+
+`doctor-edge`
+: Diagnose public edge routing, Traefik reachability, and Gitea edge exposure.
+
+`doctor-gitea`
+: Diagnose Debian Gitea container, local access, edge access, and repository
+health.
+
+`doctor-rpi`
+: Diagnose Raspberry Pi services, Pi-hole DNS, Unbound DNS, fallback DNS,
+Uptime Kuma, and Docker root state.
+
+`doctor-cluster`
+: Diagnose Kubernetes API, nodes, core pods, MetalLB, Traefik, and app health.
+
+`inventory-check`
+: Validate `homelab.yml` with a real YAML parser when available.
+
+`secrets-check`
+: Validate SOPS and age configuration plus committed encrypted secret file
+structure.
+
+`tailnet-policy-check`
+: Validate the repo-managed Tailscale ACL policy.
+
+`ai-check`
+: Check local AI helper prerequisites, knowledge index, and Ollama availability
+when the backstage helper is enabled.
+
+### Maintenance
+
+`state-backup`
+: Create a local tarball backup of OpenTofu state and generated homelab state
+files.
+
+`fix-debian-docker-root`
+: Repair or migrate the Debian Docker root according to inventory settings.
+
+`move-prometheus-stack-workers`
+: Move Prometheus stack workloads off the control plane. Requires
+`LAB_CONFIRM_DELETE_PROMETHEUS_DATA=true` because Prometheus PVC data is deleted.
+
+`secrets-init`
+: Initialize local age and SOPS configuration on the Debian host.
+
+`ai-index`
+: Build the local homelab knowledge index for the backstage AI helper.
+
+`ollama-setup`
+: Install or configure Ollama on the Debian host and pull the configured local
+model.
+
+`website-translation-model`
+: Prepare the website translation model assets.
+
+`website-ollama-listen`
+: Configure the Ollama service listen address for website use.
+
+## COMMON ENVIRONMENT
+
+`HOMELAB_INVENTORY_FILE`
+: Path to the canonical non-secret inventory. Defaults to `./homelab.yml`.
+
+`HOMELAB_STATE_DIR`
+: Local runtime state directory. Defaults to
+`${XDG_DATA_HOME:-$HOME/.local/share}/homelab`.
+
+`JEANNIE_LOG_DIR`
+: Directory for command logs. Defaults to `$HOMELAB_STATE_DIR/logs`.
+
+`JEANNIE_VERBOSE=true`
+: Print full step output as it runs. Without this, noisy commands are compact and
+full output is written to the log file.
+
+`LAB_AUTO_APPROVE=false`
+: Disable automatic OpenTofu approval for apply paths that support confirmation.
+
+`LAB_PIMOX_WORKER_COUNT`
+: Desired Pimox worker count when not supplied by generated cluster topology
+state.
+
+`LAB_SKIP_PREFLIGHT=true`
+: Skip preflight checks. Use only for targeted troubleshooting.
+
+`LAB_PREFLIGHT_ROOT_MIN_FREE_GIB`
+: Minimum Debian `/` free space for `doctor-preapply`. Default is `10`.
+
+`LAB_PREFLIGHT_DATA_MIN_FREE_GIB`
+: Minimum Debian `/data` free space for `doctor-preapply`. Default is `20`.
+
+`LAB_PREFLIGHT_EDGE_MIN_FREE_GIB`
+: Minimum OCI edge `/` free space for `doctor-preapply`. Default is `2`.
+
+`LAB_GITEA_INSTALL_DOCKER=true`
+: Allow `deploy-gitea` to install Docker through `get.docker.com` when Docker is
+missing. Default is to fail and ask for host bootstrap.
+
+`LAB_RPI_INSTALL_DOCKER=true`
+: Allow `rpi-services` to install Docker through `get.docker.com` on the
+Raspberry Pi when Docker is missing. Default is to fail.
+
+`TF_VAR_edge_install_docker=true`
+: Allow the edge OpenTofu stack to install Docker on the OCI host when Docker is
+missing. Default is to fail.
+
+`TF_VAR_haproxy_stats_password`
+: Required HAProxy stats password for the edge stack. It must be set explicitly
+and must not use the old default.
+
+`LAB_CONFIRM_NUKE=homelab`
+: Required confirmation for direct `./jeannie nuke`.
+
+`LAB_NUKE_DESTROY_PIMOX_WORKERS=true`
+: Also destroy Pimox worker VMs during `nuke`.
+
+`LAB_CONFIRM_DELETE_PROMETHEUS_DATA=true`
+: Required confirmation for `move-prometheus-stack-workers`.
+
+## FILES
+
+`homelab.yml`
+: Canonical non-secret inventory for hosts, IPs, domains, ports, and the main
+script name.
+
+`.lab/cluster-workers.auto.tfvars.json`
+: Generated worker topology passed to the cluster stack.
+
+`.lab/pimox-workers.tsv`
+: Generated Pimox worker inventory.
+
+`.lab/manual-workers.tsv`
+: User-managed manual worker inventory.
+
+`$HOMELAB_STATE_DIR/logs`
+: Jeannie command logs.
+
+`$HOMELAB_STATE_DIR/tofu-state-backups`
+: Local OpenTofu and generated state backups.
+
+## EXAMPLES
+
+Start a three-worker homelab:
+
+```sh
+LAB_PIMOX_WORKER_COUNT=3 ./jeannie up
+```
+
+Preview all OpenTofu changes:
+
+```sh
+./jeannie plan
+```
+
+Run focused edge diagnostics:
+
+```sh
+./jeannie doctor-edge
+```
+
+Run the blocking pre-apply doctor directly:
+
+```sh
+./jeannie doctor-preapply
+```
+
+Create a local state backup:
+
+```sh
+./jeannie state-backup
+```
+
+Destroy the cluster path intentionally:
+
+```sh
+LAB_CONFIRM_NUKE=homelab ./jeannie nuke
+```
+
+## EXIT STATUS
+
+`0`
+: Command completed successfully.
+
+Non-zero
+: A check, deployment step, or external tool failed. Check the printed error and
+the referenced Jeannie log file for full command output.
+
+## SEE ALSO
+
+`README.md`, `docs/service-catalog.md`, `docs/runbooks/edge-failures.md`,
+`docs/runbooks/gitea-failures.md`,
+`docs/runbooks/cluster-stop-start-failures.md`, `docs/secrets.md`.