Description
New users need a code-verified path through the vending module and Crossplane concepts. The current docs already cover product families but need a whole-repository accuracy audit, clearer conceptual onboarding, and diagrams that explain the actual reconciliation and ownership model without introducing source-environment details.
Acceptance Criteria
- #1 Every public documentation page and catalog readme is checked against the current repository contracts, manifests, and renderer behavior
- #2 New-user documentation explains the request-to-reconciliation path and links progressively to installation, configuration, and API reference material
- #3 Architecture diagrams reflect only repository-verified components and ownership boundaries, are accessible, and replace any superseded Mermaid diagram
- #4 Documentation gate passes and hosted Validate public reference passes on the completed SHA
Definition of Done
- #1 just check passes locally
- #2 hosted Validate workflow passes on the completing commit
Implementation Plan
- Inventory public documentation, navigation, catalog examples, manifests, and renderer registry; record code-versus-doc drift.
- Add a progressive newcomer path and repair inaccurate or missing explanations using repository and current Crossplane documentation evidence.
- Replace the Mermaid architecture sketch with accessible standalone diagrams derived from the deployed request and reconciliation path.
- Run the mandated de-AI and technical-clarity pass after all prose is drafted, then validate locally, review the final diff, commit, push, and verify the hosted gate on the exact SHA.
Implementation Notes
Audit evidence: reviewed the public documentation pages, catalog README inventory, XRD and Composition manifests, renderer registry, validation gate, and current Crossplane documentation. Local Markdown links resolved for 45 files. The only material gap was newcomer orientation and the Mermaid-only system view; no source-versus-public-documentation contradiction was found.
Validation: just check passed locally. Hosted Validate public reference run 35323087134 and ci-success passed for implementation SHA cb663efc86e82242df9b2c80783d977ee13329d5.
Final Summary
Added a source-grounded Crossplane concepts page, linked it through the documentation map and navigation, and replaced the Mermaid architecture sketch with accessible ownership and request-lifecycle diagrams. Completed implementation SHA cb663efc86e82242df9b2c80783d977ee13329d5; hosted validation run 35323087134 passed.