docs: add portable env key lifecycle, rotation and recovery guidance

[roodboi]

Motivation

• Clarify the portable environment trust and key lifecycle so operators can perform rotations and recovery without accidental secret rewrites.
• Distinguish distinct operator intents (value rotation, share rotation, recovery/share repair, and project-key rotation) to drive different UX and audit behavior.
• Document required recovery guardrails and lost-key handling so portability cannot silently escrow or irrevocably lose access.

Description

• Add a Planned portable key lifecycle flows section to docs/env.md with an operator-goal table and detailed rules for Value rotation, Share rotation, Recovery / share repair, and Project-key rotation.
• Extend docs/env.md with recovery and lost-key handling guidance, required recovery guardrails, and CLI/UX expectations for each operator flow.
• Update docs/plans/2026-03-13-env-portability-and-secret-management-design.md to introduce Recovery / share repair as a distinct action, add an operator decision matrix, and expand lost-key handling flows and recovery package expectations.
• Update the implementation plan in docs/plans/2026-03-13-env-portability-and-secret-management-plan.md to require tests for lost-key vs compromised-key handling and to mandate separate commands and guardrails for the four operator actions.

Testing

• No automated tests were run as part of this documentation-only change.
• The updated plan now instructs running bun test --cwd services/auth-broker tests/index.test.ts && bun test tests/env-command.test.ts as the next verification step for the planned implementation.

---

Codex Task

[changeset-bot]

⚠️ No Changeset found

Latest commit: 1dee32d

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