docs(codex): document control center behavior

- describe the split-view Codex dashboard and guided config surfaces

- document raw-editor guardrails, trust path rules, and reset-to-default support

- refresh related architecture and docs cross-links

README.md

@@ -271,10 +271,21 @@ Not supported in v1:
 Dashboard parity: `ccs config` -> `Compatible` -> `Codex CLI`
 
 The dedicated Codex dashboard reads and writes the user layer only: `~/.codex/config.toml`
-(or `$CODEX_HOME/config.toml`). It shows binary detection, a user-layer summary, support
-matrix guidance, and upstream docs, while warning that transient CCS runtime overrides such as
+(or `$CODEX_HOME/config.toml`). It now ships as a split-view control center:
+
+- left pane: guided controls for top-level runtime defaults, project trust, profiles,
+  model providers, MCP servers, and supported feature toggles
+- right pane: raw `config.toml` editor for unsupported or exact-fidelity edits
+- overview/docs tabs: binary detection, user-layer summary, support matrix guidance, and
+  upstream OpenAI references
+
+Structured saves intentionally normalize TOML formatting and drop comments. Use the raw editor
+when exact layout matters. Structured edits also refresh the raw snapshot immediately. Guided
+controls stay disabled while the raw editor has unsaved or invalid TOML, project trust paths must
+be absolute or start with `~/`, and supported feature flags can be cleared back to Codex defaults
+with `Use default`. CCS also keeps warning that transient runtime overrides such as
 `codex -c key=value` and `CCS_CODEX_API_KEY` can change the effective runtime without persisting
-back into that file.
+back into the user config file.
 
 ### Per-Profile Target Defaults
 

docs/code-standards.md

@@ -719,5 +719,5 @@ This pattern is used in:
 ## Related Documentation
 
 - [Codebase Summary](./codebase-summary.md) - Full directory structure
-- [System Architecture](./system-architecture.md) - Architecture diagrams
+- [System Architecture](./system-architecture/index.md) - Architecture diagrams
 - [CLAUDE.md](../CLAUDE.md) - AI-facing development guidance

docs/codebase-summary.md

@@ -252,6 +252,9 @@ src/
 - Metadata boundary: `src/targets/target-metadata.ts` keeps Codex runtime-only in v1, so persisted default targets remain `claude | droid`.
 - Compatibility guardrails: `src/targets/target-runtime-compatibility.ts` centralizes which profile types can execute on Codex.
 - Adapter behavior: `src/targets/codex-adapter.ts` and `src/targets/codex-detector.ts` launch native Codex without rewriting `~/.codex/config.toml`; CCS-backed routes use transient `codex -c key=value` overrides and env-key injection.
+- Dashboard control center: `src/web-server/services/codex-dashboard-service.ts`, `src/web-server/routes/codex-routes.ts`, `ui/src/pages/codex.tsx`, and `ui/src/components/compatible-cli/codex-*.tsx` expose a split-view Codex dashboard with guided editors for top-level settings, trust, profiles, providers, MCP servers, and feature flags plus a raw TOML fallback.
+- Structured-edit boundary: guided Codex saves intentionally reserialize the whole TOML document, so comments/formatting are normalized and the raw editor remains the fidelity-preserving escape hatch.
+- Follow-up behavior: structured saves refresh the raw snapshot immediately, structured controls stay disabled while raw TOML is dirty or invalid, project trust paths must be absolute or `~/...`, and feature flags can be reset to default.
 - Supported Codex flows in v1:
   - `default`
   - CLIProxy provider `codex`
@@ -268,12 +271,11 @@ The targets module provides an extensible interface for dispatching profiles to
 **Key components:**
 
 1. **TargetAdapter Interface** - Contract that each CLI implementation must fulfill:
-   - `detectBinary()` - Find CLI binary on system (platform-specific)
-   - `prepareCredentials()` - Deliver credentials (env vars vs config file writes)
-   - `buildArgs()` - Construct target-specific argument list
-   - `buildEnv()` - Construct environment for target CLI
-   - `exec()` - Spawn target process (cross-platform)
-   - `supportsProfileType()` - Verify profile compatibility
+   - binary detection
+   - credential preparation
+   - target-specific args/env construction
+   - process execution
+   - profile compatibility checks
 
 2. **Target Resolution** - Priority order:
    - `--target <cli>` flag (CLI argument)
@@ -627,7 +629,7 @@ tests/
 ## Related Documentation
 
 - [Code Standards](./code-standards.md) - Modularization patterns, file size rules
-- [System Architecture](./system-architecture.md) - High-level architecture diagrams
+- [System Architecture](./system-architecture/index.md) - High-level architecture diagrams
 - [Project Roadmap](./project-roadmap.md) - Modularization phases and future work
 - [WebSearch](./websearch.md) - WebSearch feature documentation
 - [CLAUDE.md](../CLAUDE.md) - AI-facing development guidance

docs/project-roadmap.md

@@ -41,7 +41,7 @@ All major modularization work is complete. The codebase evolved from monolithic
 
 ### Recent Fixes
 
-- **2026-03-28**: **#773** CCS now ships a dedicated `Compatible -> Codex CLI` dashboard route. The page detects the local Codex binary, reads and writes the user-owned `~/.codex/config.toml` layer, surfaces support-matrix/runtime-routing guidance, links to official OpenAI Codex docs, and warns that transient CCS runtime overrides such as `codex -c key=value` and `CCS_CODEX_API_KEY` may change effective behavior without persisting into the file.
+- **2026-03-28**: **#773** CCS now ships a dedicated `Compatible -> Codex CLI` dashboard route with a real split-view control center. The page detects the local Codex binary, keeps overview/docs guidance, and adds guided editors for the user-owned `~/.codex/config.toml` layer: top-level runtime defaults, project trust, profiles, model providers, MCP servers, and supported feature flags. Structured saves intentionally normalize TOML formatting and drop comments, so the raw editor remains the fidelity escape hatch. Follow-up fixes added immediate raw snapshot refresh, dirty raw-editor guarding for structured controls, project-trust path validation, and feature reset-to-default support. CCS still warns that transient runtime overrides such as `codex -c key=value` and `CCS_CODEX_API_KEY` may change effective behavior without persisting into the file.
 - **2026-03-27**: WebSearch dashboard cards now manage Exa, Tavily, and Brave API keys inline instead of relying on a separate manual env step. CCS stores those secrets through `global_env`, reflects masked key state in `/api/websearch`, and counts dashboard-managed keys as ready in the WebSearch status flow.
 - **2026-03-27**: **#812** CCS now includes a first-class `ccs docker` command suite for self-hosting the integrated Dashboard + CLIProxy stack. The CLI can stage bundled Docker assets locally or to a remote `--host` over SSH, report compose/supervisor status, stream CCS or CLIProxy logs, and run in-container update flows without relying on ad-hoc deployment scripts.
 - **2026-03-24**: Official Claude Channels now follow Anthropic's actual runtime contract. CCS blocks auto-enable unless Bun is available, Claude Code is verified at v2.1.80+, and `claude.ai` auth is verified; treats `--allow-dangerously-skip-permissions` as an explicit override; keeps Telegram/Discord bot tokens in Claude's shared `~/.claude/channels/` state (or official `*_STATE_DIR` overrides); and upgrades the dashboard/CLI status flow with Bun/version/auth/state-scope guidance, safer token draft retention on refresh failures, and a non-macOS iMessage toggle that can still be turned off when already selected.

docs/system-architecture/target-adapters.md

@@ -471,10 +471,17 @@ Codex is a real runtime target, but it is intentionally narrower than Claude or
 ### Codex Dashboard Surface
 
 CCS also exposes a dedicated dashboard route at `ccs config` -> `Compatible` -> `Codex CLI`.
-That page is intentionally narrower than the Droid dashboard:
+That page is intentionally narrower than the Droid dashboard in overall scope, but it is no
+longer read-mostly:
 
 - reads and writes only the user config layer: `~/.codex/config.toml` or `$CODEX_HOME/config.toml`
+- provides guided controls for top-level settings, project trust, profiles, model providers,
+  MCP servers, and supported feature flags
+- keeps a raw `config.toml` editor as the escape hatch for unsupported or fidelity-sensitive edits
 - shows binary detection, user-layer config summaries, support-matrix guidance, and upstream docs
+- normalizes TOML formatting and drops comments on structured saves
+- keeps structured controls disabled while raw TOML is dirty or invalid, validates project trust
+  paths as absolute or `~/...`, and lets feature flags reset back to Codex defaults
 - warns that transient CCS runtime overrides such as `codex -c key=value` and
   `CCS_CODEX_API_KEY` can change the effective runtime without persisting into the file editor