diff --git a/README.md b/README.md
index b90e6d6d7e..78eaf9eb35 100644
--- a/README.md
+++ b/README.md
@@ -69,38 +69,9 @@ Codex can access MCP servers. To configure them, refer to the [config docs](./do
 
 Codex CLI supports a rich set of configuration options, with preferences stored in `~/.codex/config.toml`. For full configuration options, see [Configuration](./docs/config.md).
 
-### Execpolicy Quickstart
+### Execpolicy
 
-Codex can enforce your own rules-based execution policy before it runs shell commands.
-
-1. Create a policy directory: `mkdir -p ~/.codex/policy`.
-2. Create one or more `.codexpolicy` files in that folder. Codex automatically loads every `.codexpolicy` file in there on startup.
-3. Write `prefix_rule` entries to describe the commands you want to allow, prompt, or block:
-
-```starlark
-prefix_rule(
-    pattern = ["git", ["push", "fetch"]],
-    decision = "prompt",  # allow | prompt | forbidden
-    match = [["git", "push", "origin", "main"]],  # examples that must match
-    not_match = [["git", "status"]],              # examples that must not match
-)
-```
-
-- `pattern` is a list of shell tokens, evaluated from left to right; wrap tokens in a nested list to express alternatives (e.g., match both `push` and `fetch`).
-- `decision` sets the severity; Codex picks the strictest decision when multiple rules match (forbidden > prompt > allow).
-- `match` and `not_match` act as (optional) unit tests. Codex validates them when it loads your policy, so you get feedback if an example has unexpected behavior.
-
-In this example rule, if Codex wants to run commands with the prefix `git push` or `git fetch`, it will first ask for user approval.
-
-Use the `codex execpolicy check` subcommand to preview decisions before you save a rule (see the [`codex-execpolicy` README](./codex-rs/execpolicy/README.md) for syntax details):
-
-```shell
-codex execpolicy check --policy ~/.codex/policy/default.codexpolicy git push origin main
-```
-
-Pass multiple `--policy` flags to test how several files combine, and use `--pretty` for formatted JSON output. See the [`codex-rs/execpolicy` README](./codex-rs/execpolicy/README.md) for a more detailed walkthrough of the available syntax.
-
-## Note: `execpolicy` commands are still in preview. The API may have breaking changes in the future.
+See the [Execpolicy quickstart](./docs/execpolicy.md) to set up rules that govern what commands Codex can execute.
 
 ### Docs & FAQ
 
@@ -114,6 +85,7 @@ Pass multiple `--policy` flags to test how several files combine, and use `--pre
 - [**Configuration**](./docs/config.md)
   - [Example config](./docs/example-config.md)
 - [**Sandbox & approvals**](./docs/sandbox.md)
+- [**Execpolicy quickstart**](./docs/execpolicy.md)
 - [**Authentication**](./docs/authentication.md)
   - [Auth methods](./docs/authentication.md#forcing-a-specific-auth-method-advanced)
   - [Login on a "Headless" machine](./docs/authentication.md#connecting-on-a-headless-machine)
diff --git a/docs/execpolicy.md b/docs/execpolicy.md
new file mode 100644
index 0000000000..a5b77e402e
--- /dev/null
+++ b/docs/execpolicy.md
@@ -0,0 +1,38 @@
+# Execpolicy quickstart
+
+Codex can enforce your own rules-based execution policy before it runs shell commands. Policies live in Starlark `.codexpolicy` files under `~/.codex/policy`.
+
+## Create a policy
+
+1. Create a policy directory: `mkdir -p ~/.codex/policy`.
+2. Add one or more `.codexpolicy` files in that folder. Codex automatically loads every `.codexpolicy` file in there on startup.
+3. Write `prefix_rule` entries to describe the commands you want to allow, prompt, or block:
+
+```starlark
+prefix_rule(
+    pattern = ["git", ["push", "fetch"]],
+    decision = "prompt",  # allow | prompt | forbidden
+    match = [["git", "push", "origin", "main"]],  # examples that must match
+    not_match = [["git", "status"]],              # examples that must not match
+)
+```
+
+- `pattern` is a list of shell tokens, evaluated from left to right; wrap tokens in a nested list to express alternatives (for example, match both `push` and `fetch`).
+- `decision` sets the severity; Codex picks the strictest decision when multiple rules match (forbidden > prompt > allow).
+- `match` and `not_match` act as optional unit tests. Codex validates them when it loads your policy, so you get feedback if an example has unexpected behavior.
+
+In this example rule, if Codex wants to run commands with the prefix `git push` or `git fetch`, it will first ask for user approval.
+
+## Preview decisions
+
+Use the `codex execpolicy check` subcommand to preview decisions before you save a rule (see the [`codex-execpolicy` README](../codex-rs/execpolicy/README.md) for syntax details):
+
+```shell
+codex execpolicy check --policy ~/.codex/policy/default.codexpolicy git push origin main
+```
+
+Pass multiple `--policy` flags to test how several files combine, and use `--pretty` for formatted JSON output. See the [`codex-rs/execpolicy` README](../codex-rs/execpolicy/README.md) for a more detailed walkthrough of the available syntax.
+
+## Status
+
+`execpolicy` commands are still in preview. The API may have breaking changes in the future.