docs(env): clarify key rotation and recovery flows

[roodboi]

Motivation

• Remove ambiguity in project-key rotation so operators cannot perform a destructive cutover that loses access to encrypted bundles.
• Provide explicit recovery guidance and export/import rules so recovery paths are auditable and safely usable.
• Make lost-key behavior explicit in product-facing copy to prevent false assumptions about recoverability.

Description

• Update docs/plans/2026-03-13-env-portability-and-secret-management-design.md to require a staged replacement project key, per-bundle unwrap-and-rewrap to the staged key, wrapping verification, recipient share regeneration, a pre-cutover summary, and an additive cutover sequence.
• Add recovery package rules and intentional recovery guidance that define required package contents, export/import UX expectations, and recommend maintaining multiple independent recovery paths.
• Add a new "Lost-key handling" section that states unreadable ciphertext is permanent without a remaining share or recovery package and clarifies operator-facing copy for restore vs reset scenarios.
• Mirror the key-rotation and recovery guarantees in docs/env.md so higher-level env docs match the detailed design doc.

Testing

• Ran bun x ultracite check docs/plans/2026-03-13-env-portability-and-secret-management-design.md docs/env.md which completed with no reported issues.
• Ran Prettier checks with bunx prettier --check and formatted files with bunx prettier --write, and the style checks passed after formatting.
• Confirmed the updated files were added to the branch and are ready for PR review.

---

Codex Task

[linear]

HACK-461

[changeset-bot]

⚠️ No Changeset found

Latest commit: ed454fd

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ed454fde44

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Freeze bundle publication during key rotation

The required rotation sequence only freezes destructive share changes, so value rotation can still publish new bundle versions while re-wrap is in progress. If a bundle is published after step 3 but before cutover, it is never wrapped to the staged key, and retiring the current key can leave that active bundle unreadable after cutover. Please require freezing bundle writes for the rotation window (or re-running wrap/coverage verification on a stable snapshot at cutover).

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Include all recovery paths in lost-key condition

This lost-key rule says ciphertext is permanently unreadable when owner/admin shares and recovery packages are gone, but the same section earlier lists a designated recovery recipient as a valid recovery path. In deployments using that path, this condition would incorrectly classify recoverable data as lost and could push operators toward unnecessary reset flows. The unreadable condition should account for every allowed recovery path (or explicitly remove designated recipients from the allowed set).

Useful? React with 👍 / 👎.