docs(cli): explain shim-free Codex token injection boundaries (#2713)

devlog/_plan/260902_nonbug_adoption_backlog/070_wp7_shim_free_token.md

@@ -0,0 +1,35 @@
+# wp7 — #2713 shim-free Codex token injection
+
+State at entry: the narrow `ocx doctor` diagnostic requested by the issue ("env_key set + variable
+absent + shim missing → actionable repair line") landed on `dev` in PR #2844 (`5734a1caf`,
+`collectCodexEnvKeyReadiness` in `src/cli/doctor.ts`, tests in
+`tests/doctor-codex-envkey-readiness.test.ts`). The maintainer review (score 58) and the reviewer
+follow-up (2026-08-29) both settled the remaining design questions:
+
+- A `systemd --user` drop-in is rejected as the default: it does not fit a root-owned server and
+  only reaches services launched by the user manager, not interactive shells, cron, or Desktop.
+- `EnvironmentFile=` on `opencodex-proxy.service` lands only in the proxy process; it cannot
+  inject `OPENCODEX_API_AUTH_TOKEN` into an independently launched `codex exec`. Validated by the
+  reporter on a root VPS.
+- Codex has no credential-file directive for `env_key`; the value must exist in the Codex process
+  environment. Do not invent one.
+- No new token file; the existing `service-api-token` is the source. Do not add another launcher
+  interception at the Codex binary path (that is the hole the issue reports).
+- Verdict: no `ocx codex-env` command yet; a narrow documentation update is what remains.
+
+## Scope (docs only)
+
+`docs-site/src/content/docs/reference/cli/lifecycle.md`, in the `ocx codex-shim` section: a
+subsection "Token injection without the shim" that states the process boundary, lists what does and
+does not carry `OPENCODEX_API_AUTH_TOKEN` to Codex (shim; exporting the variable in the launching
+process — shell profile, cron line, service unit that launches Codex itself; `EnvironmentFile=` on
+the proxy unit does not), points to `ocx doctor`'s "Codex env_key launch readiness" line, and
+reminds that the token value is never printed and must not be copied into `config.toml`.
+
+## Acceptance
+
+- Section present; no new commands or config keys claimed (`skill:surface:check` unaffected).
+- `bun run privacy:scan` clean.
+- PR to dev; close #2713 with English rationale: doctor slice landed (#2844), documentation landed,
+  first-class `ocx codex-env` declined for now with the reasons above; reopen path stated.
+

devlog/_plan/260902_nonbug_adoption_backlog/071_wp7_audit_r1_synthesis.md

@@ -0,0 +1,9 @@
+# wp7 audit r1 — synthesis
+
+Audit input is the issue's own review chain: maintainer review (grok-bot, score 58) and the reviewer
+follow-up confirming both referenced landings on `dev` (`5734a1ca` doctor, `bb3321ca` framing) and
+the process-boundary conclusion. Verified in this tree: `collectCodexEnvKeyReadiness`
+(`src/cli/doctor.ts:473`) and its action line; `src/codex/shim.ts:726` is the only reader that
+exports the token into a Codex process; `src/cli/index.ts:241` exports it for `ocx` itself.
+Verdict: pass for a docs-only closure; nothing in the plan changes runtime behavior.
+

docs-site/src/content/docs/reference/cli/lifecycle.md

@@ -418,6 +418,32 @@ Use `ocx service` for an always-on background proxy (recommended). Use `ocx code
 lightweight, on-demand startup without a daemon — the proxy starts only when `codex` is launched.
 :::
 
+#### Token injection without the shim
+
+On a non-loopback bind the injected provider carries `env_key = "OPENCODEX_API_AUTH_TOKEN"`. That
+line tells Codex which variable to read; it does not create it. Codex refuses to start a request
+when the variable is missing (`Missing environment variable: OPENCODEX_API_AUTH_TOKEN`), and the
+proxy is never reached. The value lives in `$OPENCODEX_HOME/service-api-token`; only a process that
+exports it into Codex's environment closes the gap.
+
+What does carry the token into a Codex process:
+
+- the shim installed by `ocx codex-shim install` (reads the token file at launch; the supported path
+  for Codex started from shells, Desktop, cron, or another service);
+- exporting `OPENCODEX_API_AUTH_TOKEN` yourself in the process that starts Codex — a shell profile,
+  the cron line, or an `Environment=`/`EnvironmentFile=` on the systemd unit that launches
+  **Codex** (not the proxy). Point it at the existing token file; do not copy the value into
+  `config.toml`.
+
+What does not: an `EnvironmentFile=` or `OCX_API_TOKEN_FILE` on `opencodex-proxy.service`. Those
+configure the proxy process only and never flow into an independently launched `codex exec`.
+
+A Codex upgrade that replaces the launcher removes the shim; the next ordinary `ocx` command restores
+it (see above), but a `codex exec` that runs before that fails. `ocx doctor` reports this exact
+state under "Codex env_key launch readiness" (env_key configured, variable unset, shim missing or
+unhealthy, token file present) with the repair command, and never prints the token. Reading the token
+file directly from Codex is not something Codex supports, so there is no OpenCodex directive for it.
+
 ### `ocx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]`
 
 Install and control the Windows status tray icon. It starts at Windows login and provides one-click