diff --git a/docs/reference/agent-spec.md b/docs/reference/agent-spec.md
index f8b3fc8e00..3ddd25d0a7 100644
--- a/docs/reference/agent-spec.md
+++ b/docs/reference/agent-spec.md
@@ -419,6 +419,16 @@ Where a fragment's table is one the user already declares, the user's table
 wins: the managed table is dropped, their values are never merged, rewritten or
 overwritten, and the rest of the fragment still applies.
 
+**A fragment can't install a named Codex profile.** Codex versions with named
+profiles read each one from its own file, `<CODEX_HOME>/<name>.config.toml`,
+with top-level keys, and won't load a profile while `config.toml` still holds a
+legacy `[profiles.<name>]` table. A fragment only adds tables to `config.toml`,
+so neither form works there. Create the profile file yourself and select it with
+the member's `codex_config_profile`; see "Codex: select sandbox and approvals
+together" in [getting-started.md](getting-started.md#codex-select-sandbox-and-approvals-together).
+Before a launch or restore, OpenRig checks that a selected profile loads, and for
+a legacy table it names the file to move the settings into.
+
 ### Resource Path Rules
 
 - All resource paths must be safe relative paths (no `..` traversal, no absolute paths), except a plugin's
diff --git a/docs/reference/getting-started.md b/docs/reference/getting-started.md
index adcf8ee041..77f768dff2 100644
--- a/docs/reference/getting-started.md
+++ b/docs/reference/getting-started.md
@@ -1150,8 +1150,15 @@ rig up ./openrig-specs/rigs/launch/starter/rig.yaml --cwd .
 
 OpenRig's `permission_policy: builtin:yolo` setting selects
 `-s danger-full-access -a never` on fresh, resume and fork launches, replacing
-the named-profile argument. The profile recipe above remains useful when you
-want to maintain those choices in native configuration. The legacy
+the named-profile argument. That drops the whole profile, not only its sandbox
+and approval settings. To keep a named profile with full access, put full access
+in the profile itself and leave `permission_policy` absent, as in the recipe
+above. To keep it with a workspace-write or read-only posture that OpenRig
+records, use the member's `codex_permissions` (see
+[per-member Codex permissions](rig-spec.md#per-member-codex-permissions)):
+OpenRig passes `-p` and adds that envelope's flags, and for that seat the
+envelope replaces a policy posture such as `builtin:yolo`. Full access isn't an
+envelope. The legacy
 environment-only `OPENRIG_YOLO=1` path remains sandbox-only when no resolved
 policy is present. A standalone `codex --yolo` command is not an OpenRig setting.
 At full access, Codex can show its full-access and GPT-5.1 migration notices at
diff --git a/docs/reference/rig-spec.md b/docs/reference/rig-spec.md
index 33282baeba..9cbf936631 100644
--- a/docs/reference/rig-spec.md
+++ b/docs/reference/rig-spec.md
@@ -740,7 +740,7 @@ directory's `CLAUDE.md`, including blocks written by other rigs.
 | `id` | string | yes | — | Member identifier. Must not contain dots or `@`. Must be unique within the pod. |
 | `agent_ref` | string | yes | — | Reference to an AgentSpec. Must start with `local:` (relative) or `path:` (absolute). Exception: `builtin:terminal` for infrastructure nodes. |
 | `profile` | string | yes | — | Profile name from the referenced AgentSpec. Use `default` for the default profile. Exception: `none` for terminal nodes. |
-| `codex_config_profile` | string | no | — | Codex-only native profile passed as `-p <name>`; letters, numbers, `_`, `.`, `-`. Separate from the AgentSpec `profile`. With the normal launch mode, this replaces OpenRig's explicit workspace-write sandbox flag. A full-bypass policy instead emits danger-full-access and omits this profile argument. |
+| `codex_config_profile` | string | no | — | Codex-only native profile passed as `-p <name>`; letters, numbers, `_`, `.`, `-`. Separate from the AgentSpec `profile`. With the normal launch mode, this replaces OpenRig's explicit workspace-write sandbox flag. A full-bypass policy instead emits danger-full-access and omits this profile argument. To keep the profile, put full access in the profile itself, or record a workspace-write or read-only `codex_permissions` envelope, which keeps it. |
 | `codex_permissions` | mapping | no | — | Codex-only sandbox and approval envelope, emitted as explicit flags on every managed launch and resume; see [per-member Codex permissions](#per-member-codex-permissions). |
 | `claude_token` | mapping | no | — | Claude-only `{ label, file }`: the seat's own subscription token file, by absolute path, used from its first launch; see "A seat's own subscription token" under [launch environment](#launch-environment). |
 | `runtime` | string | yes | — | Agent runtime. Current supported values: `claude-code`, `codex`, `pi`, `omp`, `terminal`, `stub`. `stub` is a deterministic test harness, not an agent: a Node runner in the seat's tmux pane goes through the normal launch, skill projection, startup-file and readiness path, follows `<cwd>/.openrig/stub/script.json` when present, and calls no model. See "What a stub can and cannot prove" in `docs/as-built/test-layers.md`. |