docs(policy): refresh policy documentation and references

[johnnygreco]

Summary

Restructure the Policies section so it reads well top to bottom, from a high-level overview through network rules and CLI workflows to the prover, the advisor, and the references. Every behavioral claim is checked against current main.

Related Issue

No issue required: this is documentation maintenance for implemented behavior. It changes no production behavior or public API. Code issues found along the way are tracked separately, including #3698.

Changes

Structure (docs/how-it-works/policies/, in nav order):

• Overview: what each policy section controls and when it takes effect, where the active policy comes from, base and effective policies, and the global policy. It stays high level.
• Network Rules (new): how OpenShell evaluates rules, including binary matching, connection and request checks, enforcement, overlapping rules, and credentials. Also examples for read-only APIs, methods and paths, PyPI, npm, destination addresses, WebSocket, GraphQL, MCP, and native TCP.
• Manage Policies (new): a CLI walkthrough to create, inspect, update, replace, verify, and roll back policies. Also how changes take effect, global policies, and troubleshooting.
• Policy Prover: the boundary check and the proposal risk check, how to run and read a boundary check, and what it covers.
• Policy Advisor: scope, workflow, setup, review, automatic approval and its limits, the proposal risk check, the agent API, and logs.
• Default Policy and Schema Reference: streamlined references. Matcher Semantics now states the exact glob rules.

Accuracy fixes, checked against the code and, where possible, by running the tools:

• Binary matching: OpenShell matches a binary by its real executable path and doesn't resolve symlinks in the paths a policy lists, so the examples use real paths.
• Automatic approval: the risk checks don't flag new public hosts without provider credentials. OpenShell drafts proposals from blocked connections in every sandbox.
• Overview section table: corrected the landlock row. process settings apply only on Docker and Podman.
• CLI behavior:
  • the --binary list must match the rule's binaries exactly;
  • --add-allow expands access presets into explicit rules;
  • --remove-endpoint leaves provider rules alone;
  • policy_validation_failure_mode is a gateway config option;
  • global policies load at the next configuration check.
• Prover: the snap package doesn't include openshell-prover, and the unsupported-shape list is now complete.
• Native TCP: use tls: skip for clients that start TLS immediately, present client certificates, or use a protocol where the server sends first.
• Main's updates: restored the fix(policy): restore policy.local and proposal conformance #3689 and fix(policy): propose rules for unknown DNS hosts #3707 updates to policy.local and policy DNS.

Rebase onto #3705's how-it-works layout:

• New pages live in docs/how-it-works/policies/.
• The "Policy Prover", "Policy Advisor", and "Schema Reference" labels use relative nav slugs, so their URLs stay /prover, /advisor, and /schema.
• Every link points to the new URLs. This also fixes one link that was broken on main (isolation-backends.mdx) and one broken anchor (kubernetes/ingress.mdx), with the same changes as docs: keep page URLs aligned with file paths #3713.

Outside the section: pages that link into Policies now point to the new pages and no longer repeat the corrected claims. They are the tutorials, best practices, logging, inference, provider profiles, sandbox overview, and About overview. The first-policy tutorial now uses openshell policy update and shows current log output.

Testing

• mise run pre-commit passes
• Unit tests added/updated: not applicable, documentation only
• E2E tests added/updated: not applicable, documentation only

Also verified:

• mise run docs reports 0 errors and 3 existing warnings.
• npx --yes "fern-api@5.112.0" docs broken-links reports "All checks passed". A separate check of every internal #anchor finds no problems.
• Claims were checked against source on main at 924486805.
• The prover example output was reproduced with openshell-prover.
• Glob matching was tested against regorus 0.9.1, the version OpenShell uses.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated: not applicable

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-3563.docs.buildwithfern.com/openshell

[johnnygreco]

/ok to test 01f0966

[johnnygreco]

/ok to test 823f132