docs: agent-driven approval loop and auto-approval mode user guide #1614

Description

Add user-facing documentation for the agent-driven policy approval loop landing in #1097 / #1528, including the auto-approval mode opt-in. The PR explicitly defers this user-facing docs page; this issue tracks the follow-up.

The existing `docs/sandboxes/policy-advisor.mdx` covers manual CLI review only. The agent-driven loop, the prover-gated auto-approval mode, and the four formal-prover categories that determine auto-vs-escalate are undocumented for end users today.

Context

What needs to be documented:

• The loop end-to-end. Sandbox denial → agent reads `/etc/openshell/skills/policy_advisor.md` → agent POSTs a narrow proposal to `policy.local` → gateway runs the prover → either auto-approve (empty delta) or pending (any finding) → on approval the sandbox hot-reloads → agent retries.
• The four prover categories (`link_local_reach`, `l7_bypass_credentialed`, `credential_reach_expansion`, `capability_expansion`) and what each means in plain language for an operator deciding whether a finding is acceptable.
• Opt-in auto-mode. `openshell sandbox create --approval-mode auto` (sandbox scope), `openshell settings set --global --key proposal_approval_mode --value auto` (gateway scope), the manual default, and gateway-wins-over-sandbox resolution.
• The audit trail. `CONFIG:APPROVED` events with `auto=true`, `source=`, `prover_delta=empty`, `resolved_from=` and what each unmapped field means.
• Walkthrough. Point at `examples/agent-driven-policy-management/demo.sh` and explain the two-path flow (un-credentialed auto-approves silently; credentialed escalates with a categorical finding).

What NOT to document yet (deferred per PR #1528):

• LLM-based contextual review layered on the deterministic gate.
• Intent files / per-finding auto-reject vs. escalate configuration.
• Credential scope modeling, MCP L7 surface, per-binary credential isolation, L7 watch mode, trust tiers.

Definition of Done

• New page (or expansion of `docs/sandboxes/policy-advisor.mdx`) covering the loop, prover categories, auto-mode opt-in, and audit fields.
• Navigation entry in `docs/index.yml` so the page is discoverable from the sandboxes section.
• Cross-link from the existing `docs/security/best-practices.mdx` and `docs/observability/` pages where appropriate.
• Brief documentation of the `SandboxDraft` / draft inbox flow in the TUI is covered separately if scope grows — keep this page focused on the loop semantics, not TUI navigation.

Related

• Lands alongside the loop exiting feature-flag status: feat(gateway): persist and validate agent policy proposal operations #1097, feat(policy): add agentic approval loop #1528
• Parent umbrella: OpenShell Agent-Driven Policy Management #1062
• Pairs with: Policy Advisor #1038 (Policy Advisor roadmap), Make agent policy approvals explainable with the Policy Prover #1532 (explainability), feat(policy): define agent-oriented policy modes and safety levels #1435 (agent-oriented policy modes)