Docs: Using config.toml + `-c` with godex (profiles, approvals, search, writable roots)

[activadee]

Document the clear separation of concerns:

• Policy and environment live in ~/.codex/config.toml and CLI flags.
• SDK focuses on threads/turns + typed streaming; use ConfigOverrides for ephemeral overrides.
  Include examples for:
• Selecting a profile via config and via ConfigOverrides["profile"].
• Setting approval policy, sandbox mode, web search toggle, writable roots via config/CLI (not SDK fields).

[github-actions]

🧩 Codex Implementation Plan

Issue: Docs: Using config.toml + -c with godex (profiles, approvals, search, writable roots) (#18)
Summary: Add a CLI-configuration reference plus README updates that spell out how ~/.codex/config.toml, CLI flags, and CodexOptions.ConfigOverrides interact for profiles, approvals, sandboxing, search, and writable roots.
Confidence: medium
Estimated Effort: s

Goals & Non-Goals

• Clarify in README.md:259-285 that long-lived policy (profiles, approval policy, sandbox/web-search toggles, writable roots) is owned by ~/.codex/config.toml and CLI flags, while the SDK focuses on threads/turns/streaming and only forwards overrides.
• Provide concrete examples for choosing a profile via config vs ConfigOverrides["profile"], and for configuring approvals/sandbox/search/writable roots without adding new SDK fields.
• Non-goals: no changes to options.go or internal/codexexec/runner.go behavior, no new CLI functionality, and no automated tooling for managing config files.

Proposed Changes

1. README CLI configuration primer – Introduce a new section near README.md:250-285 that explains the configuration surface, showing precedence (config file → CLI flags/-c → ConfigOverrides → per-thread options). Include a minimal ~/.codex/config.toml snippet that defines profile, approval_policy, sandbox.mode, search.enabled, and writable_roots, plus the corresponding CLI flags (--profile, --sandbox, --writable-root, etc.) so readers know how the SDK interacts with them.
2. Dedicated configuration reference – Add docs/configuration.md (new file) that deep-dives into:
   • Structure of ~/.codex/config.toml (global vs [profiles.<name>] blocks) and how to switch profiles from the CLI or SDK.
   • Mapping between config keys and CLI flags, backed by the current forwarding logic in internal/codexexec/runner.go:172-205.
   • Worked examples covering: selecting a default profile via config, overriding it via CodexOptions.ConfigOverrides (validated against options.go:25-58), and setting approvals/sandbox/search/writable roots.
3. README code samples & cross-links – Update the existing “Sandbox settings” and “Selecting a profile programmatically” sections to link to the new doc, add a short TOML example for profile selection, and expand the Go snippet to show mixed overrides (profile + -c approval.policy=on-request). Call out the recommendation to keep policy knobs in config/CLI and reserve SDK-level overrides for temporary cases.

Step-by-Step Plan

1. Docs engineer – confirm CLI surface (no migration): Inspect Codex CLI help / official docs (e.g., codex config --help, codex exec --help) to capture the exact key names for approval policy, sandbox, web-search toggle, and writable roots so our samples match reality.
2. Docs engineer – draft docs/configuration.md (new content): Create the doc with sections for persistent config, profile selection, override precedence, and policy examples. Reference actual behavior from internal/codexexec/runner.go:172-205 and options.go:25-58 so the prose aligns with the code.
3. Docs engineer – update README (existing content): Edit README.md:259-285 to embed the new overview snippet, add TOML/CLI examples, and link to docs/configuration.md. Ensure the Go example highlights ConfigOverrides["profile"] alongside another -c override for policies.
4. Docs engineer – cross-link & proof: Add links from other relevant sections (e.g., installation or sandbox settings) back to the new configuration doc, proofread for accuracy, and ensure anchors/links render correctly.

Testing & Validation

• Manually preview README.md and docs/configuration.md (e.g., using VS Code Markdown preview) to verify formatting, fenced code blocks, and links.
• Run any available Markdown/style tooling (markdownlint README.md docs/configuration.md if configured) to catch formatting regressions.
• (Optional) go test ./... to confirm doc-only changes didn’t disturb the build/setup scripts.

Risks & Unknowns

• Need definitive names for the CLI config keys governing approvals, sandbox mode, search, and writable roots; the repo itself doesn’t expose them, so inaccurate guesses would mislead users.
• CLI behavior may evolve; without a single source of truth, duplicated documentation in README + docs/configuration.md could drift.

Rollout / Follow-Ups

• Coordinate with the Codex CLI documentation owners so both references stay in sync, and consider linking back to their canonical source once available.
• After publishing, announce the new doc section (release notes/CHANGELOG) so users discover the clarification.
• Future cleanup: if more configuration topics accumulate, consider a dedicated docs/ index page and move other README operational guidance there.

Dependencies

• Codex CLI documentation or help output for configuration keys

Open Questions

• What are the exact TOML keys (and CLI flag names) for approval policy, web search enablement, and writable roots so examples don’t guess incorrectly?
• Should the doc describe global vs per-profile writable root semantics, or is it enough to show a single profile example? Brouilleur required input from CLI owners.

Immediate Next Steps

• Confirm the canonical CLI configuration keys/flags with the Codex CLI team so the doc samples are accurate.
• Decide where docs/configuration.md should live in the long term (standalone file vs future docs site) before implementing.