[Vivswan]

Before

Each environment is its own sealing scope with its own public key, so the same secret name can carry a different value per environment, as above. The public key that seals a value is read at apply, by the first sealed write of its scope; check mode never requests it. Reconciliation runs after the environment itself is applied; in check mode against an environment that does not exist yet, the declared secrets cannot be listed, so a note says they are unverifiable until apply creates it. Within a declared `secrets` key, live secrets the entries do not declare are kept by default (their values are unrecoverable); the wrapped `{_undeclared: delete, entries}` form opts into deletion. The endpoints ride the same "Environments" PAT permission as the rest of the section.

After

Each environment is its own sealing scope with its own public key, so the same secret name can carry a different value per environment, as above. The rules of the nested store:

- **The public key is read at apply,** by the first sealed write of its scope; check mode never requests it.
- **Reconciliation runs after the environment itself is applied.** In check mode against an environment that does not exist yet, the declared secrets cannot be listed, so a note says they are unverifiable until apply creates it.
- **Undeclared live secrets are kept by default.** Within a declared `secrets` key, live secrets the entries do not declare are kept (their values are unrecoverable); the wrapped `{_undeclared: delete, entries}` form opts into deletion.
- **The endpoints ride the same "Environments" PAT permission** as the rest of the section.

How

• Every over-cap unit on the three pages becomes the device that shows it fastest: bold-lead-in bullets, a three-row denial-policy verdict table, a sibling-stores table, split paragraphs.
• permissions.md stays the owner of the facts the operate pages now link to; nothing moves out of it. "Three things worth knowing" becomes "Four", matching its bullets.
• No fact lost or added: the cross-model review listed facts absent on each side of every page; both lists empty.

Proof

• Probe: findings 4, 4, 8 on the three pages, now 0 each; headings byte-identical; semantics.md untouched.
• Tests: bun test test/docs 383 green; the one anchor in a rewritten unit resolves.

Technical details

• Line accounting: docs +90 -26, nothing else; prose grew because paragraphs became lists and tables.
• Wording: "surface" became "shape" in two rewritten sentences of forward-compatibility.md to match the rest of the docs; three hyphen-as-dash joins in secrets-and-vaults.md became commas.
• Reviewer note (Copilot): the generated regions on permissions.md are untouched; the test-pinned sentence "Nine sections are closed rather than passthrough" is byte-exact.
• Files: docs/reference/{permissions,forward-compatibility,secrets-and-vaults}.md.

[Copilot]

Copilot review overview

🟢 Approval recommended

The documentation-only restructuring preserves the existing semantics and valid references.

Review effort: Balanced
Findings: None

What changed in this PR

Reshapes three reference pages for faster scanning without changing documented behavior.

Changes:

• Splits dense prose into focused paragraphs and bullets.
• Adds concise permissions and secret-store tables.
• Preserves generated regions, headings, links, and existing facts.

File	Description
docs/​reference/​permissions.md	Clarifies grants and denial policies.
docs/​reference/​forward-compatibility.md	Clarifies passthrough and strict shapes.
docs/​reference/​secrets-and-vaults.md	Clarifies secret handling and store behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

File size check

0 over a hard cap (fails), 34 warning(s).

File	Size	Tier	Cap
.github/actions/setup/action.yml:7	169 chars	warn	150
.github/scripts/gen-inputs-table.ts:54	11 comment lines	warn	10
.github/scripts/generated.ts:28	191 chars	warn	150
.github/scripts/release-pipeline.ts:7	156 chars	warn	150
.github/scripts/release-pipeline.ts:458	151 chars	warn	150
.github/scripts/release-pipeline.ts:1252	153 chars	warn	150
.github/scripts/release-pipeline.ts:1	35 comment lines (header)	warn	25
.github/scripts/release-pipeline.ts:454	14 comment lines	warn	10
.github/workflows/post-green.yml:29	153 chars	warn	150
.github/workflows/update-release-pr.yml:110	14 comment lines	warn	10
docs/upgrading/v2-to-v3.md	1276 lines	warn	1040
src/engine/layers.ts:217	157 chars	warn	150
src/flows/settings-write.ts:142	159 chars	warn	150
src/flows/settings-write.ts:30	11 comment lines	warn	10
src/flows/snapshot.ts:189	13 comment lines	warn	10
src/github/secret-scan.ts:43	11 comment lines	warn	10
src/schema.ts:186	153 chars	warn	150
src/schema.ts:197	176 chars	warn	150
src/sections/contract/errors.ts:14	14 comment lines	warn	10
src/sections/contract/module.ts:963	185 chars	warn	150
src/sections/contract/module.ts:627	12 comment lines	warn	10
src/sections/contract/module.ts:897	12 comment lines	warn	10
src/sections/secret_scanning_custom_patterns/compilable-form.ts:382	161 chars	warn	150
src/sections/shared/roles.ts:43	13 comment lines	warn	10
src/types.ts:16	156 chars	warn	150
test/docs/guides.test.ts:451	155 chars	warn	150
test/e2e/generators.ts	2634 lines	warn	2560
test/e2e/generators.ts:1704	166 chars	warn	150
test/e2e/generators.ts:1858	161 chars	warn	150
test/e2e/generators.ts:1667	12 comment lines	warn	10
test/engine/execute.test.ts:617	152 chars	warn	150
test/flows/merge-parity.test.ts:63	164 chars	warn	150
test/scripts/auto-fix-allowlist.test.ts:12	12 comment lines	warn	10
test/sections/refusal-messages.test.ts:61	19 comment lines	warn	10

Split the file, wrap the line, shorten or exempt the comment, or list the path in .file-size-allow.local with a # reason.

5 managed file(s) skipped; repo-platform owns them.