docs: fix blocking errors and trim the self-install guides

[pditommaso]

Stacked on #1106 — base is chris-self-install, not master. Merge #1106 first, or merge this into it.

Addresses the review on #1106. Every claim was verified against src/main at 1e4e10d before being fixed.

Deployments that would not work as documented

Fix	Why
aws-build: add wave.scan.reports.path	Scan was enabled without it. ObjectStorageOperationsFactory.create0 throws on a null path, and Application.groovy:43 uses eagerInitSingletons(true) — Wave failed to boot.
aws-build: create wave-build-pvc in both namespaces	The claim existed only in wave; jobs run in wave.build.k8s.namespace (wave-build). PVCs are namespaced, so every build, scan, and mirror pod stayed Pending.
aws-build: add the noarch node selector	K8sHelper.getNoArchSelector returns an empty map without it, so the mirror and blob-cache pods KubeMirrorStrategy/KubeTransferStrategy create schedule outside the build node group.
aws-build: create the S3 bucket	<s3-bucket> was referenced by the IAM policy and the logs/locks paths but never created, and was missing from the requirements.
aws-build: restore WAVE_JVM_OPTS	src/main/jib/launch.sh defaults to -Xmx850m regardless of the 4 GiB limit. The comment notes that setting the variable replaces the default option set.
docker-compose: move credentials into wave.registries	Nothing in src/main reads DOCKER_USER/DOCKER_PAT. They work only via the config.yml the image ships (build.gradle:184) — the same file this guide mounts over.
kubernetes-lite: fold registries: into the ConfigMap	It was a second top-level wave: block; Wave loads one YAML document, so appending it dropped wave.db.* and wave.server.url.
kubernetes-lite: add kubectl apply, complete the ingress	Five manifests were printed with no apply step, and the "AWS ALB" ingress had no ingressClassName or annotations, so /service-info could not pass.
Restore endpoints.health in both guides	jdbc and disk-space are on by default (micronaut-management + micronaut-jdbc-hikari, no endpoints: in application.yml). Master's compose guide disabled them; the new guides probe /health for liveness.
configure-wave: stop hardcoding MICRONAUT_ENVIRONMENTS	The literals re-added lite, which gates out JobManager, JobServiceImpl, both job queues and cleanup via @Requires(missingBeans = WaveLite).
reference: restore kebab-case on six keys	The merge reverted wave.denyHosts, wave.blobCache.s5cmdImage and four wave.blobCache.storage.* keys, undoing #1096. They still bind from YAML — Micronaut hyphenates — but lose env-var overridability, which is how blob-cache credentials are injected.
Use wave.capabilities.anonymous-access	application.yml:56-63 makes wave.allowAnonymous a legacy alias, and the reference documented the toggle twice. Adds a pointer to MICRONAUT_ENVIRONMENTS=strict.
Fix how-wave-works.md:126	Still linked ./configuration.md, renamed here to install/reference.md.

Simplification

Guides shrank, the reference absorbed the detail:

configure-wave.md   333 → 194     reference.md   684 → 751
aws-build.md        549 → 536     troubleshoot.md  36 →  81

• The seven-registry pre-creation matrix moved out of the EKS guide into reference.md#registry-pre-creation.
• Bottlerocket user-namespace setup moved to troubleshoot.md, reached from a note where builds are configured.
• Cut: the SMTP settings table, the duplicate ECR-cache walkthrough (which used a different repo name than aws-build creates), the third IRSA explanation, and the EC2-instance-profile section for Docker builds — a path index.md says is unsupported.
• The IAM section keeps the Wave delta (policy, trust policy, service-account annotation) and links Assign IAM roles to Kubernetes service accounts for the procedure. Shell variables moved to the top of the page, so the ECR and S3 commands no longer use $AWS_REGION before it is set.
• Sizing prerequisites are now per-replica and match the manifests, rather than asking for 12 GB and an m5a.2xlarge for a one-replica stack.
• "Production enhancements" dropped; build-pod egress kept as a checklist item, since build pods run user-supplied Dockerfiles.

Reference and verification

• Added wave.build.enabled, wave.mirror.enabled, wave.blob-cache.enabled, wave.job-manager.max-running-jobs, and the mail.smtp.* keys; finished the truncated wave.accounts entry; corrected five (required) labels on settings that ship defaults.
• Noted that the documented env vars only take effect where config.yml interpolates them — the root cause of the DOCKER_USER issue.
• post-install.md now covers mirror and scan, the features aws-build enables. Flags checked against wave-cli App.java: --mirror needs --build-repo and conflicts with --containerfile/--conda-package/--freeze; --scan-mode takes none|async|required.
• troubleshoot.md added to the sidebar with front matter; post-install moved ahead of aws-build.

Checks

• All 39 docs: every internal link and heading anchor resolves; all 25 sidebar ids map to a file.
• All 21 YAML blocks in the install guides parse, including the config.yml embedded in each ConfigMap.
• Config keys, defaults, IAM actions, and Micronaut environments re-checked against src/main.

Two judgement calls worth a look: the four aws iam / eks describe-cluster commands are kept rather than fully replaced by the AWS link, on the grounds that an install guide should be followable end to end; and the database SQL block stays duplicated across both Lite guides for the same reason.

🤖 Generated with Claude Code