[FEATURE] Implementation Guide end-to-end review — validate scripts, variables, and docs alignment

[kristopherjturner]

Summary

The implementation guide at docs/implementation/ is the most critical section of the Azure Local Cloud docs site. It documents a complete, phased deployment process across ~150 individual task pages covering everything from CI/CD infrastructure setup through cluster deployment, operational foundations, and handover.

This issue covers a complete end-to-end walkthrough of the guide to ensure:

1. Every described script exists and is functional in azurelocal-toolkit
2. All required variables are present in both variables.example.yml AND master-registry.yaml
3. Documentation accurately reflects the current state of scripts (no stale code samples)
4. The guide is internally consistent with no broken links

Cross-Repo Scope

Docs Repo	Scripts Repo
azurelocal.github.io → docs/implementation/	azurelocal-toolkit → scripts/deploy/

Phases and Sections

Phase	Docs Path	Script Path
Phase 0 — CI/CD Infrastructure	docs/implementation/01-cicd-infra/	scripts/deploy/01-cicd-infra/
Phase 1 — Azure Foundation	docs/implementation/02-azure-foundation/	scripts/deploy/02-azure-foundation/
Phase 2 — On-Premises Readiness	docs/implementation/03-onprem-readiness/	scripts/deploy/03-onprem-readiness/
Phase 3 — Cluster Deployment	docs/implementation/04-cluster-deployment/	scripts/deploy/04-cluster-deployment/
Phase 4 — Operational Foundations	docs/implementation/05-operational-foundations/	scripts/deploy/05-operational-foundations/
Phase 5 — Testing & Validation	docs/implementation/06-testing-validation/	scripts/deploy/06-testing-validation/
Phase 6 — Validation / Handover	Appendices + 07-validation-handover/	scripts/deploy/07-validation-handover/

Additional Runbook Documents to Review

Section	Path
Full Deployment Runbook	docs/implementation/full-deployment/
Simplified Deployment	docs/implementation/simplified-deployment/
Deployment Methods	docs/implementation/deployment-methods/
Variable Management Standard	docs/implementation/04-variable-management-standard.mdx
Appendices (A–O)	docs/implementation/appendices/

Per-Task Validation Checklist

For each task document (task-XX-*.mdx), verify:

• The script referenced in the doc exists at the expected path in azurelocal-toolkit
• The script runs without syntax errors (Pester test or manual dry-run)
• All variables used by the script exist in config/variables/variables.example.yml
• All variables are registered in config/variables/master-registry.yaml
• The doc's stated prerequisites match what the script actually requires
• Expected outputs described in the doc match what the script produces
• Code samples in the doc match the actual script content (no stale copy-paste)
• Task numbering is consistent (phase and task number match the filename)

Variable Registry Validation

Run these and document results:

• config/variables/validate-registry.ps1 — must pass with zero errors
• config/variables/validate-variables.ps1 — must pass with zero errors
• All variables consumed by phase scripts appear in master-registry.yaml
• No orphaned variables (defined in registry but unused in any script)

Documentation Consistency Checks

• All cross-references between task docs resolve correctly
• All appendix references (Appendix A through Appendix O) are accurate and link to real content
• Runbook index pages (index.mdx) accurately describe their phases
• npm run build passes with onBrokenLinks: 'throw'

Deliverables

1. Audit report comment on this issue listing every discrepancy found
2. Script or doc fixes for each discrepancy (separate commits per phase)
3. CI check: A step in the build CI that runs validate-registry.ps1 and validate-variables.ps1
4. Phase-by-phase tracking table (checkboxes) in a comment after audit

Phase Tracking (fill in after audit)

Phase	Script Exists	Variables Valid	Doc Matches Script	Broken Links
Phase 0 — CI/CD Infra
Phase 1 — Azure Foundation
Phase 2 — On-Prem Readiness
Phase 3 — Cluster Deployment
Phase 4 — Operational Foundations
Phase 5 — Testing & Validation
Phase 6 — Handover
Appendices	N/A	N/A

References

• scripts/deploy/Deploy-Infrastructure.ps1 — master deploy orchestration script
• config/variables/master-registry.yaml — full variable registry
• config/variables/variables.example.yml — variable template
• config/variables/variables.schema.json — variable schema
• config/variables/build-mapping-report.ps1 — drift analysis tool
• docs/implementation/04-variable-management-standard.mdx — variable management doc

[kristopherjturner]

Tracked in Azure DevOps as Feature #38 — https://dev.azure.com/hybridcloudsolutions/AzureLocal%20Community%20Site/_workitems/edit/38