docs(policy): move policy pages under how-it-works and fix links

Signed-off-by: Johnny Greco <jogreco@nvidia.com>

Author: johnnygreco

docs/about/overview.mdx

@@ -42,7 +42,7 @@ OpenShell applies defense in depth across the following policy domains.
 | Process | Blocks privilege escalation and dangerous syscalls. | Locked at sandbox creation. |
 | Provider credentials | Resolves opaque credential placeholders only at profile-authorized endpoints. | Attachments, rotation, and revocation update at runtime; new environment variables require a new process. |
 
-For details, refer to [Customize Sandbox Policies](/how-it-works/policies/overview) and [Default Policy](/how-it-works/policies/default-policy).
+For details, refer to [Sandbox Policies](/how-it-works/policies/overview) and [Default Policy](/how-it-works/policies/default-policy).
 
 ## Common Use Cases
 
@@ -61,4 +61,4 @@ Explore these topics to go deeper:
 
 - To understand the runtime architecture, refer to [Architecture](/about/architecture).
 - To prepare an image and launch an agent, refer to [Run Your First Agent](/about/run-your-first-agent).
-- To learn how OpenShell enforces policy controls across protection layers, refer to [Customize Sandbox Policies](/how-it-works/policies/overview).
+- To learn how OpenShell enforces policy controls across protection layers, refer to [Sandbox Policies](/how-it-works/policies/overview).

docs/extensibility/isolation-backends.mdx

@@ -43,6 +43,6 @@ crate. `OpenShellRuntimeBackend` is implemented in
 | Compute driver | Placement and fencing. The driver creates runtime resources, installs the outer egress fence, and supplies a verified descriptor. |
 | Isolation backend | Common behavior. The backend turns the shared Rust calls into a protected session with the sandbox runtime. |
 
-For how `openshell-sandbox` enforces the boundary, refer to
-[Sandbox](/about/architecture/sandbox). For driver-specific workload behavior,
-refer to [Runtimes](/how-it-works/sandboxes/runtimes).
+For how `openshell-sandbox` enforces the boundary, refer to [Inside the Sandbox
+Boundary](/about/architecture#inside-the-sandbox-boundary). For driver-specific
+workload behavior, refer to [Runtimes](/how-it-works/sandboxes/runtimes).

docs/how-it-works/inference.mdx

@@ -35,9 +35,10 @@ curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/nvi
 
 In `nvidia-native.yaml`, change `id` to `nvidia-native`, give the profile a
 distinct `display_name`, and set `binaries` to the executables that may call the
-API, as described in [Binary Matching](/sandboxes/network-rules#binary-matching).
-Keep the credential and endpoint definitions you intend to grant. For a Python
-workload, the edited fields can look like:
+API, as described in [Binary
+Matching](/how-it-works/policies/network-rules#binary-matching). Keep the
+credential and endpoint definitions you intend to grant. For a Python workload,
+the edited fields can look like:
 
 ```yaml
 id: nvidia-native
@@ -316,5 +317,5 @@ headers, model selection, request shape, streaming, and timeout behavior.
 
 - [Profiles](/how-it-works/providers/profiles)
 - [Providers](/how-it-works/providers/overview)
-- [Customize Sandbox Policies](/how-it-works/policies/overview)
+- [Sandbox Policies](/how-it-works/policies/overview)
 - [Google](/how-it-works/providers/google#vertex-ai)

docs/how-it-works/policies/advisor.mdx

@@ -181,8 +181,8 @@ every sandbox by setting `manual` on the gateway.
 
 ### Proposal Risk Check
 
-The policy advisor uses the [policy prover](/reference/policy-prover) to run a
-proposal risk check on every proposal. Unlike the boundary check that the
+The policy advisor uses the [policy prover](/how-it-works/policies/prover) to
+run a proposal risk check on every proposal. Unlike the boundary check that the
 `openshell-prover` CLI runs, it does not compare a policy with a boundary that
 you write. It compares what the sandbox can reach with and without the proposed
 rule. The check accounts for the credentials of attached providers and for
@@ -250,7 +250,7 @@ MCP tool rules, query matchers, credential settings, or endpoint path selectors,
 and it ignores them if an agent sends them. Review the rule that
 `openshell rule get` shows, not the agent's description of it. Add rules that
 need those fields yourself, as described in [Manage Sandbox
-Policies](/sandboxes/manage-policies).
+Policies](/how-it-works/policies/manage-policies).
 
 If a proposed hostname resolves to a private address, OpenShell still blocks the
 connection after approval until you add an `allowed_ips` entry or declare the
@@ -305,10 +305,10 @@ if the agent was waiting for the decision. An automatic approval's
 
 ## Next Steps
 
-- Use [Manage Sandbox Policies](/sandboxes/manage-policies) to change policies
-  yourself.
-- Use [Network Rules](/sandboxes/network-rules) and the
-  [Policy Schema Reference](/reference/policy-schema) for rules that agents
+- Use [Manage Sandbox Policies](/how-it-works/policies/manage-policies) to
+  change policies yourself.
+- Use [Network Rules](/how-it-works/policies/network-rules) and the
+  [Policy Schema Reference](/how-it-works/policies/schema) for rules that agents
   cannot propose.
-- Use the [Policy Prover](/reference/policy-prover) to check a
+- Use the [Policy Prover](/how-it-works/policies/prover) to check a
   complete policy against a boundary you define.

docs/how-it-works/policies/default-policy.mdx

@@ -20,8 +20,8 @@ sandbox without `--policy` does not by itself mean the default is active,
 because the image or `OPENSHELL_SANDBOX_POLICY` can supply one. An invalid image
 policy keeps the workload from starting until you repair it. It does not select
 the default. Refer to [Where the Active Policy Comes
-From](/sandboxes/policies#where-the-active-policy-comes-from) for the complete
-selection order.
+From](/how-it-works/policies/overview#where-the-active-policy-comes-from) for
+the complete selection order.
 
 ## Default Filesystem Access
 

docs/sandboxes/manage-policies.mdx …ow-it-works/policies/manage-policies.mdxdocs/sandboxes/manage-policies.mdx renamed to docs/how-it-works/policies/manage-policies.mdx docs/sandboxes/manage-policies.mdx renamed to docs/how-it-works/policies/manage-policies.mdx

@@ -35,7 +35,7 @@ openshell sandbox create --name my-sandbox
 ```
 
 Without either, the sandbox uses a policy from its image or the restrictive
-[default policy](/reference/default-policy).
+[default policy](/how-it-works/policies/default-policy).
 
 ## Ship a Policy in an Image
 
@@ -69,7 +69,7 @@ to the sandbox's own policy. Use the effective policy to see everything the
 sandbox can reach, for example to find out why a request is allowed.
 
 To save the effective policy as a YAML file, for example to review it or to
-check it with the [policy prover](/reference/policy-prover):
+check it with the [policy prover](/how-it-works/policies/prover):
 
 ```shell
 openshell sandbox get my-sandbox --policy-only > effective-policy.yaml
@@ -103,7 +103,7 @@ enforcement mode. `read-only` allows `GET`, `HEAD`, and `OPTIONS` requests,
 `rest` turns on HTTP request inspection, and `enforce` blocks every other
 request. The `--binary` value must be the real path of the executable inside the
 sandbox, as described in [Binary
-Matching](/sandboxes/network-rules#binary-matching).
+Matching](/how-it-works/policies/network-rules#binary-matching).
 
 To allow another kind of request on an existing rule, add an allow rule. Name
 the rule with `--rule-name`, and list every binary in the rule with `--binary`.
@@ -214,11 +214,11 @@ flowchart TD
 The sandbox validates the revision again because it also accounts for provider
 rules and other changes that arrive at the same time. If the sandbox cannot load
 a revision, the `policy_validation_failure_mode` option in the [gateway
-configuration](/reference/gateway-config#full-example) decides what happens.
-With `fail_closed`, the default, the sandbox blocks network traffic until you
-submit a valid policy. With `retain_last_valid`, the last valid policy stays
-active. [A Change Fails to Load](#a-change-fails-to-load) explains how to repair
-a rejected change.
+configuration](/how-it-works/gateways/configuration#full-example) decides what
+happens. With `fail_closed`, the default, the sandbox blocks network traffic
+until you submit a valid policy. With `retain_last_valid`, the last valid policy
+stays active. [A Change Fails to Load](#a-change-fails-to-load) explains how to
+repair a rejected change.
 
 ## Change Filesystem and Process Settings
 
@@ -229,7 +229,8 @@ edit these settings in the file.
 
 When the policy allows network access, OpenShell adds the system paths that
 sandbox processes need, so list only the paths your workload requires. [Baseline
-Filesystem Paths](/reference/default-policy#baseline-filesystem-paths) lists
+Filesystem
+Paths](/how-it-works/policies/default-policy#baseline-filesystem-paths) lists
 those paths.
 
 <Warning>
@@ -379,11 +380,11 @@ openshell sandbox start my-sandbox
 
 ## Next Steps
 
-- Use [Network Rules](/sandboxes/network-rules) for example rules you can adapt
-  to common services and protocols.
-- Use the [Policy Prover](/reference/policy-prover) to check that a policy
+- Use [Network Rules](/how-it-works/policies/network-rules) for example rules
+  you can adapt to common services and protocols.
+- Use the [Policy Prover](/how-it-works/policies/prover) to check that a policy
   grants no more access than a boundary you define.
-- Use the [Policy Advisor](/sandboxes/policy-advisor) to let an agent propose
-  the network rules it needs for your review.
-- Use the [Policy Schema Reference](/reference/policy-schema) for every field,
-  default, and constraint.
+- Use the [Policy Advisor](/how-it-works/policies/advisor) to let an agent
+  propose the network rules it needs for your review.
+- Use the [Policy Schema Reference](/how-it-works/policies/schema) for every
+  field, default, and constraint.

docs/sandboxes/network-rules.mdx …/how-it-works/policies/network-rules.mdxdocs/sandboxes/network-rules.mdx renamed to docs/how-it-works/policies/network-rules.mdx docs/sandboxes/network-rules.mdx renamed to docs/how-it-works/policies/network-rules.mdx

@@ -98,7 +98,7 @@ an inspected endpoint. The `protocol` field selects what OpenShell inspects:
 | `websocket` | The WebSocket upgrade request and each text message the client sends. | [WebSocket](#allow-websocket-messages) |
 | `graphql` | GraphQL operation type, operation name, and top-level fields. | [GraphQL](#allow-graphql-operations) |
 | `mcp` | MCP method and tool name. | [MCP](#allow-mcp-tools) |
-| `json-rpc` | JSON-RPC method name. | [JSON-RPC rules](/reference/policy-schema#json-rpc-rules) |
+| `json-rpc` | JSON-RPC method name. | [JSON-RPC rules](/how-it-works/policies/schema#json-rpc-rules) |
 | `tcp` | No request rules. Use it for clients that speak a protocol other than HTTP, such as databases. | [Native TCP](#allow-native-tcp) |
 | Omitted | No request rules. | -- |
 
@@ -161,8 +161,9 @@ send provider credentials there. OpenShell supplies a provider's credentials
 only to the destinations that the provider's profile or an explicit credential
 binding allows. When a request fails a credential check, correct the provider
 binding instead of widening the network rule. Refer to [Provider
-Profiles](/providers/profiles) for profile endpoints, and to [Credential
-Fields](/reference/policy-schema#credential-fields) for explicit bindings.
+Profiles](/how-it-works/providers/profiles) for profile endpoints, and to
+[Credential Fields](/how-it-works/policies/schema#credential-fields) for
+explicit bindings.
 
 ## Examples
 
@@ -174,9 +175,10 @@ When a single `openshell policy update` command can create a rule, the example
 shows it. Otherwise, add the YAML under the `network_policies` section of a
 complete policy file and apply it with `openshell policy set`, as described in
 [Replace the Complete
-Policy](/sandboxes/manage-policies#replace-the-complete-policy). After you apply
-a rule, [verify the change](/sandboxes/manage-policies#verify-a-change) before
-testing traffic.
+Policy](/how-it-works/policies/manage-policies#replace-the-complete-policy).
+After you apply a rule, [verify the
+change](/how-it-works/policies/manage-policies#verify-a-change) before testing
+traffic.
 
 ### Allow Read-Only API Access
 
@@ -264,14 +266,14 @@ agent needs only specific operations. It does not cover Git
 transport or GraphQL requests. To add a deny rule to an existing rule without a
 complete policy file, use `openshell policy update` with `--add-deny`, as
 described in [Add or Remove Network
-Access](/sandboxes/manage-policies#add-or-remove-network-access).
+Access](/how-it-works/policies/manage-policies#add-or-remove-network-access).
 
 Apply the rule with a GitHub provider attached. Its profile must permit
 credential use at `api.github.com`, and the token must authorize the repository
 operations. Verify that `gh api repos/<org>/<repo>/issues` succeeds and that
 `gh api repos/<org>/<repo>/hooks` returns an OpenShell denial. For a complete
 Git push example, see [Grant GitHub Push Access to a Sandboxed
-Agent](/get-started/tutorials/github-sandbox).
+Agent](/tutorials/github-push-access).
 
 ### Allow PyPI Downloads
 
@@ -350,9 +352,9 @@ openshell sandbox exec -n my-sandbox --no-login-shell -- \
 OpenShell blocks connections to private network addresses by default to prevent
 server-side request forgery (SSRF). An endpoint with an exact hostname can still
 reach the private addresses that its hostname resolves to, unless the endpoint
-comes from an approved [policy advisor](/sandboxes/policy-advisor) proposal.
-Loopback, link-local, and unspecified addresses, including the cloud metadata
-address `169.254.169.254`, are always blocked.
+comes from an approved [policy advisor](/how-it-works/policies/advisor)
+proposal. Loopback, link-local, and unspecified addresses, including the cloud
+metadata address `169.254.169.254`, are always blocked.
 
 Use `allowed_ips` to limit the addresses an endpoint can reach, or to let a
 wildcard host such as `*.internal.example` reach private addresses. This rule
@@ -483,7 +485,7 @@ For allow rules, every top-level field in an operation must match. A malformed
 or disallowed operation denies an entire batched request. GraphQL field names
 are application-specific, so review them against the service's schema before
 you rely on them. For deny rules, persisted queries, and GraphQL over WebSocket,
-refer to [GraphQL Rules](/reference/policy-schema#graphql-rules).
+refer to [GraphQL Rules](/how-it-works/policies/schema#graphql-rules).
 
 With a GitHub provider attached, verify a REST read with `gh api zen` and a
 query with `gh api graphql -f query='{ viewer { login } }'`, then confirm that a
@@ -528,10 +530,10 @@ tool can receive any arguments accepted by the server.
 
 Omitting `mcp.versions` allows only the `2025-11-25` revision. To support an
 older server, list the exact revisions it needs, as described in [MCP Version
-Selection](/reference/policy-schema#mcp-version-selection). Server responses and
-SSE messages are relayed without MCP policy parsing. Do not put an MCP endpoint
-on the same host and port as an endpoint that uses a different protocol.
-`openshell policy update` rejects this combination.
+Selection](/how-it-works/policies/schema#mcp-version-selection). Server
+responses and SSE messages are relayed without MCP policy parsing. Do not put an
+MCP endpoint on the same host and port as an endpoint that uses a different
+protocol. `openshell policy update` rejects this combination.
 
 ### Allow Native TCP
 
@@ -586,7 +588,7 @@ when the client starts TLS as soon as it connects, when the client must complete
 TLS itself, for example to present a client certificate, or when the server
 sends first, as with SMTP, IMAP, and MySQL. Clients that send first and
 negotiate TLS within their protocol, such as `psql`, do not need it. Refer to
-[Inspection Fields](/reference/policy-schema#inspection-fields).
+[Inspection Fields](/how-it-works/policies/schema#inspection-fields).
 
 Prefer exact hostnames. A wildcard authorizes DNS queries for every matching
 name, which can expose a DNS-label exfiltration channel. An allowed hostname on
@@ -603,9 +605,9 @@ record.
 
 ## Next Steps
 
-- Use [Manage Sandbox Policies](/sandboxes/manage-policies) to apply, verify,
-  and roll back policy changes.
-- Use the [Policy Schema Reference](/reference/policy-schema) for protocol
+- Use [Manage Sandbox Policies](/how-it-works/policies/manage-policies) to
+  apply, verify, and roll back policy changes.
+- Use the [Policy Schema Reference](/how-it-works/policies/schema) for protocol
   defaults, field constraints, and matcher semantics.
-- Use [Troubleshoot](/sandboxes/manage-policies#troubleshoot) when a request is
-  denied unexpectedly.
+- Use [Troubleshoot](/how-it-works/policies/manage-policies#troubleshoot) when a
+  request is denied unexpectedly.