Document documentation delivery safeguards

[cachafla]

Summary

• document targeted preview versus post-merge production validation responsibilities
• record the exact-tree production artifact contract and fail-closed deployment behavior
• preserve the full-history, cancellation, and release-note invariants discovered while optimizing the workflows

Release Notes

Internal contributor guidance; no external release note.

[github-actions]

PR Summary

This PR enhances the AGENTS documentation by adding several comprehensive sections that outline the workflow and guidelines for documentation and release management. The new content covers the following areas:

• Pull Requests and Release Notes: This section clarifies how pull requests should be labeled (e.g., internal for internal changes) and how to include appropriate release note content for external changes. It also describes the role of the validate check in determining the scope of a preview render.

• Documentation Delivery: Detailed steps are provided on how documentation progresses through different stages (main → staging → prod). The process ensures that after merging into main, a complete staging build is created, and a validated, immutable artifact is used for production. This approach reinforces a clear separation between preview and production validations.

• CI Invariants: New guidelines emphasize critical practices for maintaining a secure and reliable CI/CD pipeline. These include avoiding fallback builds, preserving the full Git history to prevent merge issues, ensuring cancelability of outdated preview runs, and distinctly managing preview and production validations.

Overall, the changes aim to improve the clarity and safety of the documentation release process, ensuring that production deployments are both secure and consistent with the validated staging artifacts.

Test Suggestions

• Verify that pull requests are correctly labeled and that the associated release note policies trigger the expected preview and artifact validation processes.
• Simulate the documentation delivery process from merging in 'main' through the staging and production pipelines to ensure that the system enforces the requirement for an immutable production artifact.
• Test the CI invariants by attempting operations that should fail (e.g., shallow checkouts or introducing fallback builds) to confirm that the pipeline properly rejects these conditions.

[github-actions]

Validate docs site

✓ INFO: A live preview of the docs site is available — Open the preview

[github-actions]

Lighthouse check results

✓ INFO: No site pages to audit in this PR.

Commit SHA: 0a5e8c4