docs: update guides and configuration reference

anton commented

2026-10-19 20:07:48 +00:00

Owner

Scope

This PR is the guides and reference documentation update, not the release-notes PR. It covers operational guidance, configuration examples, security assumptions, documentation navigation, and the docs license.

Release notes, the Releases index, and the Upcoming platform announcement are tracked separately in #44. Both PRs target main independently. The release gates below remain applicable to the feature guidance documented here.

Summary

Consolidates seven guide/reference documentation updates onto docs main, checked against platform main 2dd613e37d83c12c9c12a126719eab8de65127bf.

Reconcile the stacked key-service and blue-green guides with public environment-value/HTTP protection guidance, ingress/egress policy, component operations, verifier-environment notices, navigation and the docs-specific MIT license.
Correct operational contracts: rollout-gated deployment lifecycle, per-deployment verification/release and STEVE trust paths, uncertain switch outcomes, rollback/data limits, explicit debug cleanup, custom-domain/TLS activation, quorum recovery and legacy import, and actual supported configuration fields. Fix the standalone encrypted-secret example so holders can reach its recovery receiver.
Keep component reuse separate from platform service-lifecycle redesign. Put manual release gates before activation, narrow preflight/IAM guarantees, and preserve historical reproduction requirements.
Preserve current canonical source links and exclude old closed/unmerged proposals and agent-local files.

Supersedes #35, #36, #37, #38, #39, #40 and #41. PR #41 already contains the #37 key-service rewrite; the unified change reconciles it once rather than stacking the same edits twice. No branches are deleted.

Verification

Exact docs commit: 4fd8158ee2079300d191e22373ed045b28f24146; the production build and scratch validator were rerun after committing.

From the isolated docs worktree:

PATH=/usr/bin:/bin make build-prod IMAGE_NAME=caution-docs-unified-release
git diff --check canonical/main
python3 /tmp/docs-release-review/validate-docs.py

The scratch validator builds the production image, extracts the generated site, resolves local pages/assets/anchors, checks fenced configuration examples through the exact platform caution-config parser and standalone vault recovery reachability, and requires unchanged tracked-file hashes across validation. Final results: 42 pages, 3,844 local links/assets/anchors, and 50 executable configuration examples passed; one comment-only fence is excluded. Independent reviews were reconciled, including the final STEVE deployment-specific trust-path correction. Fragment wrappers are recorded; comment-only fences are excluded. This harness is review evidence, not a new repository dependency or full deployment test.

At the platform revision above:

cargo +1.96.1 test --locked -p caution-config
node --test frontend/tests/deployments.test.js

Configuration tests passed: 133 unit, 3 egress and 9 policy tests. Deployment UI helpers: 14 passed. The original docs checkout's staged user work is not part of this change and was left untouched.

Release gates / non-claims

Confirm the managed/BYOC rollout flags for the release before advertising blue-green availability; source defaults both off. Existing legacy apps do not migrate on ordinary destroy/redeploy.
Publish the verifier-environment anchor with CLI builds that link to it. Use mutually compatible CLI, provisioner, component and key-service versions.
Docs rendering and parser tests do not establish current AWS/IAM/Nitro, real Keymaker acceptance, historical EIF/PCR equality, ACME cutover or production readiness. No deployment, IAM application or service restart is part of this documentation change.

## Scope This PR is the **guides and reference documentation update**, not the release-notes PR. It covers operational guidance, configuration examples, security assumptions, documentation navigation, and the docs license. Release notes, the Releases index, and the Upcoming platform announcement are tracked separately in #44. Both PRs target `main` independently. The release gates below remain applicable to the feature guidance documented here. ## Summary Consolidates seven guide/reference documentation updates onto docs main, checked against platform main `2dd613e37d83c12c9c12a126719eab8de65127bf`. - Reconcile the stacked key-service and blue-green guides with public environment-value/HTTP protection guidance, ingress/egress policy, component operations, verifier-environment notices, navigation and the docs-specific MIT license. - Correct operational contracts: rollout-gated deployment lifecycle, per-deployment verification/release and STEVE trust paths, uncertain switch outcomes, rollback/data limits, explicit debug cleanup, custom-domain/TLS activation, quorum recovery and legacy import, and actual supported configuration fields. Fix the standalone encrypted-secret example so holders can reach its recovery receiver. - Keep component reuse separate from platform service-lifecycle redesign. Put manual release gates before activation, narrow preflight/IAM guarantees, and preserve historical reproduction requirements. - Preserve current canonical source links and exclude old closed/unmerged proposals and agent-local files. Supersedes #35, #36, #37, #38, #39, #40 and #41. PR #41 already contains the #37 key-service rewrite; the unified change reconciles it once rather than stacking the same edits twice. No branches are deleted. ## Verification Exact docs commit: `4fd8158ee2079300d191e22373ed045b28f24146`; the production build and scratch validator were rerun after committing. From the isolated docs worktree: ```sh PATH=/usr/bin:/bin make build-prod IMAGE_NAME=caution-docs-unified-release git diff --check canonical/main python3 /tmp/docs-release-review/validate-docs.py ``` The scratch validator builds the production image, extracts the generated site, resolves local pages/assets/anchors, checks fenced configuration examples through the exact platform `caution-config` parser and standalone vault recovery reachability, and requires unchanged tracked-file hashes across validation. Final results: 42 pages, 3,844 local links/assets/anchors, and 50 executable configuration examples passed; one comment-only fence is excluded. Independent reviews were reconciled, including the final STEVE deployment-specific trust-path correction. Fragment wrappers are recorded; comment-only fences are excluded. This harness is review evidence, not a new repository dependency or full deployment test. At the platform revision above: ```sh cargo +1.96.1 test --locked -p caution-config node --test frontend/tests/deployments.test.js ``` Configuration tests passed: 133 unit, 3 egress and 9 policy tests. Deployment UI helpers: 14 passed. The original docs checkout's staged user work is not part of this change and was left untouched. ## Release gates / non-claims - Confirm the managed/BYOC rollout flags for the release before advertising blue-green availability; source defaults both off. Existing legacy apps do not migrate on ordinary destroy/redeploy. - Publish the verifier-environment anchor with CLI builds that link to it. Use mutually compatible CLI, provisioner, component and key-service versions. - Docs rendering and parser tests do not establish current AWS/IAM/Nitro, real Keymaker acceptance, historical EIF/PCR equality, ACME cutover or production readiness. No deployment, IAM application or service restart is part of this documentation change.

anton added 1 commit

2026-10-19 20:07:48 +00:00