docs: document permissions-required in front-matter reference

[github-actions]

Agent Documentation Update

Findings

Area	Issue	File(s)
accuracy	permissions-required is a top-level FrontMatter field (src/compile/types.rs) with real compile-time semantics (abstract read/write capability requirements, unioned across imports and consumer), but the primary docs/front-matter.md reference never mentioned the key — it only appeared in docs/imports.md under import-merge semantics. An agent skimming the front-matter reference alone would not discover this field.	docs/front-matter.md

Applied Fixes

• Added a commented permissions-required: example directly after the permissions: block in docs/front-matter.md, matching the surrounding style (commented-out optional field with inline explanation), and cross-linked to docs/imports.md#permissions-required for the full semantics.

Notes

Verified against src/compile/types.rs (FrontMatter::permissions_required: PermissionsRequired, #[serde(rename = "permissions-required")]) and the existing full write-up in docs/imports.md. No behavior was changed or invented — this only closes a discoverability gap in the canonical front-matter page. Also audited docs/cli.md against src/main.rs Commands/SecretsCmd/GraphCmd (all subcommands and flags present and accurate), docs/safe-outputs.md against src/safe_outputs/*.rs (every tool documented, including assign-work-item), and prompts/create-ado-agentic-workflow.md field lists against FrontMatter — no further drift found.

---

Created by the agent-documentation maintainer workflow.

Generated by Agent Documentation Maintainer · auto · 86.9 AIC · ⌖ 6.34 AIC · ⊞ 13.5K · ◷

[azure-pipelines]

Azure Pipelines:
2 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.