Improve Jeannie usage help

README.md

@@ -269,6 +269,7 @@ hostname.
 Run a read-only health snapshot from the Debian server with:
 
 ```bash
+./jeannie help
 ./jeannie status
 ./jeannie capacity
 ./jeannie recover-plan
@@ -289,6 +290,10 @@ Run a read-only health snapshot from the Debian server with:
 ./jeannie map
 ```
 
+`help` prints the grouped command reference in pipeline order, from inventory
+and bootstrap through cluster lifecycle, reports, observability, recovery,
+access, apps, security, AI, and destructive commands.
+
 It reports host memory/disk, systemd services, Docker Compose stacks,
 Kubernetes health when the API is reachable, Pimox worker VM status, RPi
 services, Tailscale, key local/public HTTP endpoints, and "what broke" signals

README.md.tmpl

@@ -269,6 +269,7 @@ hostname.
 Run a read-only health snapshot from the Debian server with:
 
 ```bash
+./{{ main_script }} help
 ./{{ main_script }} status
 ./{{ main_script }} capacity
 ./{{ main_script }} recover-plan
@@ -289,6 +290,10 @@ Run a read-only health snapshot from the Debian server with:
 ./{{ main_script }} map
 ```
 
+`help` prints the grouped command reference in pipeline order, from inventory
+and bootstrap through cluster lifecycle, reports, observability, recovery,
+access, apps, security, AI, and destructive commands.
+
 It reports host memory/disk, systemd services, Docker Compose stacks,
 Kubernetes health when the API is reachable, Pimox worker VM status, RPi
 services, Tailscale, key local/public HTTP endpoints, and "what broke" signals

docs/jeannie.1.md

@@ -23,8 +23,17 @@ The canonical script name is `metadata.main_script` in `homelab.yml`.
 
 ## COMMANDS
 
+Run `./jeannie help` for the short in-terminal command reference. It is grouped
+in the same order as the pipeline: inventory and planning, bootstrap, cluster
+lifecycle, reports, observability, recovery, doctors, access, apps, security,
+AI, and destructive commands.
+
 ### Core Lifecycle
 
+`help`
+: Print the grouped command reference. The same output is shown for `-h`,
+`--help`, or no command.
+
 `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,

jeannie

@@ -6052,7 +6052,112 @@ homelab_map() {
     "${REPO_ROOT}/scripts/homelab-map" "${@:2}"
 }
 
+print_usage() {
+    cat <<'EOF'
+Usage: ./jeannie <command> [args]
+
+Base, Inventory, And Planning
+  help | -h | --help                         Show this grouped help.
+  validate                                   Run repo validation checks.
+  inventory-check                            Validate the canonical homelab inventory.
+  preflight                                  Run non-mutating infrastructure preflight checks.
+  doctor-preapply                            Run deeper pre-apply safety checks.
+  plan [all|provisioning|cluster|platform|apps|edge]
+                                             Run OpenTofu plans without applying changes.
+
+Build And Bootstrap
+  up                                         Deploy the full homelab pipeline.
+  deploy-gitea                               Deploy the Debian-hosted Gitea container.
+  bootstrap-gitea-repo                       Ensure the Gitea repo and SSH key wiring exist.
+  rpi-services                               Deploy Pi-hole, Unbound, and Uptime Kuma on RPi4.
+  ollama-setup                               Install/configure Ollama on the Debian host.
+  artifact-cache {status|up|down|instructions}
+                                             Manage optional Debian artifact caches.
+  golden-ledger {show|check}                 Show or validate Pimox golden image versions.
+
+Cluster Lifecycle
+  rebuild-cluster                            Recreate the cluster through the guarded path.
+  stop-cluster                               Stop Kubernetes and worker VMs without destroy.
+  start-cluster                              Start Kubernetes and desired worker VMs.
+  workers <list|start|stop|drain|uncordon|recreate-plan|rebalance>
+                                             Manage Pimox/Kubernetes workers.
+  move-prometheus-stack-workers              Move monitoring workloads to worker nodes.
+  doctor-versions                            Check Kubernetes/container tooling versions.
+
+Operator View And Reports
+  status                                     Cascading health check from host to public URLs.
+  scorecard                                  Compact pass/warn/fail operator scorecard.
+  capacity                                   Compact capacity and placement report.
+  recover-plan                               Print disaster recovery order and prerequisites.
+  recover-power [--dry-run]                  Run or preview post-outage recovery.
+  map [--dot]                                Print the homelab dependency map.
+  change-journal {list|path}                 Show risky-command journal entries.
+  release-snapshot                           Write a pre-change release snapshot.
+
+Observability And GitOps
+  grafana-dashboards {list|apply}            List or apply repo-managed Grafana dashboards.
+  gitops-status                              Print focused Argo CD health and sync status.
+  cert-check                                 Check public DNS, TLS, and edge URL health.
+  backup-status                              Check backup and restore-drill freshness.
+  synthetic-checks                           Run end-to-end service probes.
+  resource-budget                            Report Kubernetes resource request/limit gaps.
+  route-inventory                            Report routes and Uptime Kuma coverage.
+
+Recovery And State
+  backup-gitea                               Back up the Debian-hosted Gitea data.
+  drill-restore                              Run all restore drills.
+  drill-gitea-restore                        Run the Gitea restore drill.
+  drill-pihole-restore                       Run the Pi-hole restore drill.
+  state-backup                               Back up local OpenTofu state files.
+
+Focused Doctors
+  doctor-edge                                Diagnose edge routing and public exposure.
+  doctor-gitea                               Diagnose Gitea local/public access.
+  doctor-rpi                                 Diagnose RPi services and DNS.
+  doctor-cluster                             Diagnose Kubernetes cluster health.
+
+Access, Secrets, And Policy
+  access-audit                               Audit SSH, Gitea, Kubernetes, and Tailscale access.
+  kubeconfig-readonly                        Create/check read-only kubeconfig material.
+  secrets-init                               Initialize SOPS/age secret tooling.
+  secrets-check                              Validate repo-managed secret prerequisites.
+  tailnet-policy-check                       Validate Tailscale ACL policy as code.
+  fix-debian-docker-root                     Repair Debian Docker root placement.
+
+Apps And Services
+  apps                                       Deploy application stack only.
+  website-translation-model                  Prepare website translation model support.
+  website-ollama-listen                      Configure website Ollama access.
+  install-gitea-runner [TOKEN]               Install the Gitea Actions runner.
+  openwrt                                    Deploy/check OpenWrt lab config.
+
+Security Learning
+  security-scan                              Run the security scan bundle.
+  security-prepare                           Prepare defensive security tools.
+  security-zap                               Run OWASP ZAP checks.
+  security-k8s                               Run Kubernetes security checks.
+  security-host                              Run host security checks.
+  security-trivy                             Run Trivy scans.
+  security-secrets                           Run secret leak checks.
+  security-nuclei                            Run Nuclei web checks.
+  security-web                               Run web security checks.
+  security-logs                              Review security-relevant logs.
+  security-runtime                           Check runtime security sensors.
+  security-attack-path                       Print prioritized attack-path findings.
+
+AI And Indexing
+  ai-index                                   Build the local homelab RAG index.
+  ai-check                                   Query/check the local AI index.
+
+Destructive
+  nuke                                       Guarded cluster state destruction path.
+EOF
+}
+
 case "${1:-}" in
+    "" | help | -h | --help)
+        print_usage
+        ;;
     up)
         record_change_journal "up" "$@"
         up
@@ -6275,7 +6380,8 @@ case "${1:-}" in
         echo "Log: ${JEANNIE_LOG_FILE}"
         ;;
     *)
-        echo "Usage: $0 {up|plan [all|provisioning|cluster|platform|apps|edge]|rebuild-cluster|stop-cluster|start-cluster|status|capacity|recover-plan|recover-power [--dry-run]|scorecard|gitops-status|cert-check|release-snapshot|backup-status|synthetic-checks|resource-budget|artifact-cache {status|up|down|instructions}|golden-ledger {show|check}|route-inventory|grafana-dashboards {list|apply}|workers <list|start|stop|drain|uncordon|recreate-plan|rebalance>|change-journal {list|path}|map [--dot]|validate|access-audit|kubeconfig-readonly|apps|website-translation-model|website-ollama-listen|ollama-setup|deploy-gitea|rpi-services|bootstrap-gitea-repo|backup-gitea|drill-restore|drill-gitea-restore|drill-pihole-restore|install-gitea-runner|move-prometheus-stack-workers|doctor-versions|doctor-edge|doctor-gitea|doctor-rpi|doctor-cluster|preflight|doctor-preapply|inventory-check|state-backup|fix-debian-docker-root|secrets-init|secrets-check|tailnet-policy-check|ai-index|ai-check|security-scan|security-prepare|security-zap|security-k8s|security-host|security-trivy|security-secrets|security-nuclei|security-web|security-logs|security-runtime|security-attack-path|openwrt|nuke}"
+        printf 'Unknown command: %s\n\n' "$1" >&2
+        print_usage >&2
         exit 1
         ;;
 esac