fix: refresh Codex config and docs

[affaan-m]

Summary

• update .codex/config.toml to the current Codex schema
• document experimental multi-agent support and add sample role configs
• refresh Codex README guidance away from legacy persistent_instructions

Validation

• python3 TOML parse for .codex/config.toml and .codex/agents/*.toml
• codex -C /Users/affoon/Documents/GitHub/ECC/.worktrees/ecc-issue-380-1 exec --skip-git-repo-check 'Print ok.'

Closes #380.

---

Summary by cubic

Updated .codex/config.toml to the current Codex schema and refreshed docs to introduce experimental multi-agent workflows. Added three project-local agent role configs and shifted guidance from legacy persistent_instructions to AGENTS.md. Addresses #380.

• Migration
  • Enable features.multi_agent = true and define roles under [agents.<name>] pointing to .codex/agents/*.toml (use /agent to inspect/steer).
  • Prefer AGENTS.md (or optional model_instructions_file) over persistent_instructions.
  • Keep role files project-local; copy .codex/config.toml to ~/.codex/config.toml only for global defaults.
  • Use current top-level settings like web_search, and update notifications to array form that receives JSON on stdin.

^{Written for commit 64e98b8. Summary will update on new commits.}

Summary by CodeRabbit

• New Features

  • Multi-agent workflow support (experimental) enables coordinated agent execution for enhanced capabilities
  • New /agent CLI command for inspecting and steering agent behavior
  • Predefined specialized agent role configurations included

• Documentation

  • Expanded setup guides and configuration instructions for multi-agent workflows
  • Added comprehensive agent role documentation and examples

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request updates the Codex configuration schema, documentation, and adds multi-agent support infrastructure. Changes include modernized .codex/config.toml with top-level settings, three sample agent role configurations (explorer, reviewer, docs-researcher), and comprehensive documentation updates to AGENTS.md and README.md reflecting multi-agent capabilities and current best practices.

Changes

Cohort / File(s)	Summary
Agent Role Configurations .codex/agents/explorer.toml, .codex/agents/reviewer.toml, .codex/agents/docs-researcher.toml	Three new agent configuration files defining role-specific models, reasoning effort levels, sandbox modes, and developer instructions for exploration, code review, and documentation research tasks.
Configuration & Documentation .codex/config.toml, .codex/AGENTS.md, README.md	Updated configuration schema with top-level approval_policy, sandbox_mode, and web_search settings; moved from legacy [permissions] and [notify] blocks. Added multi-agent setup section with role definitions. Introduced agent role placeholders and updated feature flags. Documentation expanded to cover multi-agent support, project-local configuration, and MCP server updates (Cloudflare addition).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 A warren of agents, each with a role,
Explorer and reviewer, working as whole,
Config now modern, docs shining bright,
Multi-agent magic—the future's in sight! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title "fix: refresh Codex config and docs" is partially related to the changeset. It mentions config and docs updates but does not specifically convey the main addition of multi-agent support capability, which is a major focus of this PR.
Linked Issues check	✅ Passed	The pull request successfully addresses all coding requirements from issue #380: moves approval_policy/sandbox_mode to top-level [#380], replaces legacy history.persistent_instructions with model_instructions_file [#380], converts notification format to array form [#380], replaces web_search_request with top-level web_search [#380], updates sandbox value names [#380], and implements multi-agent support with sample role configs [#380].
Out of Scope Changes check	✅ Passed	All changes in the pull request are directly aligned with the linked issue #380 objectives. The modifications to config files, documentation, and new agent role configurations address the stated requirements without introducing unrelated changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch codex/issue-380-codex-config

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[cubic-dev-ai]

No issues found across 6 files

[coderabbitai]

🧹 Nitpick comments (1)

.codex/config.toml (1)

34-50: Consider adding railway MCP server for consistency with mcp-configs/mcp-servers.json.

The railway MCP server is defined in mcp-configs/mcp-servers.json (lines 39-43) but is not included in this config file. This creates an inconsistency where users referencing mcp-configs/ might expect railway to be available in the Codex config.

💡 Suggested addition (commented out like other optional servers)

 # [mcp_servers.cloudflare]
 # command = "npx"
 # args = ["-y", "@cloudflare/mcp-server-cloudflare"]
+#
+# [mcp_servers.railway]
+# command = "npx"
+# args = ["-y", "@railway/mcp-server"]

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.codex/config.toml around lines 34 - 50, Add a commented-out MCP server
entry for "railway" to keep this Codex config consistent with
mcp-configs/mcp-servers.json: add a commented block named mcp_servers.railway
(matching the structure of existing blocks like mcp_servers.github and
mcp_servers.context7) with the same command/args as the JSON definition so it's
available as an optional server; ensure the block is commented out like other
optional servers so it doesn't change runtime behavior but remains visible to
users.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @.codex/config.toml:
- Around line 34-50: Add a commented-out MCP server entry for "railway" to keep
this Codex config consistent with mcp-configs/mcp-servers.json: add a commented
block named mcp_servers.railway (matching the structure of existing blocks like
mcp_servers.github and mcp_servers.context7) with the same command/args as the
JSON definition so it's available as an optional server; ensure the block is
commented out like other optional servers so it doesn't change runtime behavior
but remains visible to users.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e4300ff0-59b2-470b-9fc7-0e9b740479e9

📥 Commits

Reviewing files that changed from the base of the PR and between 5644415 and 64e98b8.

📒 Files selected for processing (6)

• .codex/AGENTS.md
• .codex/agents/docs-researcher.toml
• .codex/agents/explorer.toml
• .codex/agents/reviewer.toml
• .codex/config.toml
• README.md