chore: import upstream snapshot with attribution

.codex/AGENTS.md

@@ -0,0 +1,102 @@
+# ECC for Codex CLI
+
+This supplements the root `AGENTS.md` with Codex-specific guidance.
+
+## Model Recommendations
+
+| Task Type | Recommended Model |
+|-----------|------------------|
+| Routine coding, tests, formatting | GPT 5.5 |
+| Complex features, architecture | GPT 5.5 |
+| Debugging, refactoring | GPT 5.5 |
+| Security review | GPT 5.5 |
+
+## Skills Discovery
+
+Skills are auto-loaded from `.agents/skills/`. Each skill contains:
+- `SKILL.md` — Detailed instructions and workflow
+- `agents/openai.yaml` — Codex interface metadata
+
+Available skills:
+- tdd-workflow — Test-driven development with 80%+ coverage
+- security-review — Comprehensive security checklist
+- coding-standards — Universal coding standards
+- frontend-patterns — React/Next.js patterns
+- frontend-slides — Viewport-safe HTML presentations and PPTX-to-web conversion
+- article-writing — Long-form writing from notes and voice references
+- content-engine — Platform-native social content and repurposing
+- market-research — Source-attributed market and competitor research
+- investor-materials — Decks, memos, models, and one-pagers
+- investor-outreach — Personalized investor outreach and follow-ups
+- backend-patterns — API design, database, caching
+- e2e-testing — Playwright E2E tests
+- eval-harness — Eval-driven development
+- strategic-compact — Context management
+- api-design — REST API design patterns
+- verification-loop — Build, test, lint, typecheck, security
+- deep-research — Multi-source research with firecrawl and exa MCPs
+- exa-search — Neural search via Exa MCP for web, code, and companies
+- claude-api — Anthropic Claude API patterns and SDKs
+- x-api — X/Twitter API integration for posting, threads, and analytics
+- crosspost — Multi-platform content distribution
+- fal-ai-media — AI image/video/audio generation via fal.ai
+- dmux-workflows — Multi-agent orchestration with dmux
+
+## MCP Servers
+
+Treat the project-local `.codex/config.toml` as the default Codex baseline for ECC. The current ECC baseline enables GitHub, Context7, Exa, Memory, Playwright, and Sequential Thinking; add heavier extras in `~/.codex/config.toml` only when a task actually needs them.
+
+ECC's canonical Codex section name is `[mcp_servers.context7]`. The launcher package remains `@upstash/context7-mcp`; only the TOML section name is normalized for consistency with `codex mcp list` and the reference config.
+
+### Automatic config.toml merging
+
+The sync script (`scripts/sync-ecc-to-codex.sh`) uses a Node-based TOML parser to safely merge ECC MCP servers into `~/.codex/config.toml`:
+
+- **Add-only by default** — missing ECC servers are appended; existing servers are never modified or removed.
+- **7 managed servers** — Supabase, Playwright, Context7, Exa, GitHub, Memory, Sequential Thinking.
+- **Canonical naming** — ECC manages Context7 as `[mcp_servers.context7]`; legacy `[mcp_servers.context7-mcp]` entries are treated as aliases during updates.
+- **Package-manager aware** — uses the project's configured package manager (npm/pnpm/yarn/bun) instead of hardcoding `pnpm`.
+- **Drift warnings** — if an existing server's config differs from the ECC recommendation, the script logs a warning.
+- **`--update-mcp`** — explicitly replaces all ECC-managed servers with the latest recommended config (safely removes subtables like `[mcp_servers.supabase.env]`).
+- **User config is always preserved** — custom servers, args, env vars, and credentials outside ECC-managed sections are never touched.
+
+## External Action Boundaries
+
+Treat networked tools as read-only by default. Search, inspect, and draft freely within the user's requested scope, but require explicit user approval before posting, publishing, pushing, merging, opening paid jobs, dispatching remote agents, changing third-party resources, or modifying credentials.
+
+When approval is ambiguous, produce a local plan or draft artifact instead of taking the external action. Preserve user config and private state unless the user specifically asks for a scoped change.
+
+## Multi-Agent Support
+
+Codex now supports multi-agent workflows behind the experimental `features.multi_agent` flag.
+
+- Enable it in `.codex/config.toml` with `[features] multi_agent = true`
+- Define project-local roles under `[agents.<name>]`
+- Point each role at a TOML layer under `.codex/agents/`
+- Use `/agent` inside Codex CLI to inspect and steer child agents
+
+Sample role configs in this repo:
+- `.codex/agents/explorer.toml` — read-only evidence gathering
+- `.codex/agents/reviewer.toml` — correctness/security review
+- `.codex/agents/docs-researcher.toml` — API and release-note verification
+
+## Key Differences from Claude Code
+
+| Feature | Claude Code | Codex CLI |
+|---------|------------|-----------|
+| Hooks | 8+ event types | Not yet supported |
+| Context file | CLAUDE.md + AGENTS.md | AGENTS.md only |
+| Skills | Skills loaded via plugin | `.agents/skills/` directory |
+| Commands | `/slash` commands | Instruction-based |
+| Agents | Subagent Task tool | Multi-agent via `/agent` and `[agents.<name>]` roles |
+| Security | Hook-based enforcement | Instruction + sandbox |
+| MCP | Full support | Supported via `config.toml` and `codex mcp add` |
+
+## Security Without Hooks
+
+Since Codex lacks hooks, security enforcement is instruction-based:
+1. Always validate inputs at system boundaries
+2. Never hardcode secrets — use environment variables
+3. Run `npm audit` / `pip audit` before committing
+4. Review `git diff` before every push
+5. Use `sandbox_mode = "workspace-write"` in config

.codex/agents/docs-researcher.toml

@@ -0,0 +1,9 @@
+model = "gpt-5.5"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+Verify APIs, framework behavior, and release-note claims against primary documentation before changes land.
+Cite the exact docs or file paths that support each claim.
+Do not invent undocumented behavior.
+"""

.codex/agents/explorer.toml

@@ -0,0 +1,9 @@
+model = "gpt-5.5"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+Stay in exploration mode.
+Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
+Prefer targeted search and file reads over broad scans.
+"""

.codex/agents/reviewer.toml

@@ -0,0 +1,9 @@
+model = "gpt-5.5"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+Review like an owner.
+Prioritize correctness, security, behavioral regressions, and missing tests.
+Lead with concrete findings and avoid style-only feedback unless it hides a real bug.
+"""

.codex/config.toml

@@ -0,0 +1,122 @@
+#:schema https://developers.openai.com/codex/config-schema.json
+
+# Everything Claude Code (ECC) — Codex Reference Configuration
+#
+# Copy this file to ~/.codex/config.toml for global defaults, or keep it in
+# the project root as .codex/config.toml for project-local settings.
+#
+# Official docs:
+# - https://developers.openai.com/codex/config-reference
+# - https://developers.openai.com/codex/multi-agent
+
+# Model selection
+# Leave `model` and `model_provider` unset so Codex CLI uses its current
+# built-in defaults. Uncomment and pin them only if you intentionally want
+# repo-local or global model overrides.
+
+# Top-level runtime settings (current Codex schema)
+approval_policy = "on-request"
+sandbox_mode = "workspace-write"
+web_search = "live"
+
+# External notifications receive a JSON payload on stdin.
+notify = [
+  "terminal-notifier",
+  "-title", "Codex ECC",
+  "-message", "Task completed!",
+  "-sound", "default",
+]
+
+# Persistent instructions are appended to every prompt (additive, unlike
+# model_instructions_file which replaces AGENTS.md).
+persistent_instructions = "Follow project AGENTS.md guidelines. Use available MCP servers when they can help."
+
+# model_instructions_file replaces built-in instructions instead of AGENTS.md,
+# so leave it unset unless you intentionally want a single override file.
+# model_instructions_file = "/absolute/path/to/instructions.md"
+
+# MCP servers
+# Keep the default project set lean. API-backed servers inherit credentials from
+# the launching environment or can be supplied by a user-level ~/.codex/config.toml.
+[mcp_servers.github]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-github"]
+startup_timeout_sec = 30
+
+[mcp_servers.context7]
+command = "npx"
+# Canonical Codex section name is `context7`; the package itself remains
+# `@upstash/context7-mcp`.
+args = ["-y", "@upstash/context7-mcp@latest"]
+startup_timeout_sec = 30
+
+[mcp_servers.exa]
+command = "npx"
+args = ["-y", "mcp-remote", "https://mcp.exa.ai/mcp"]
+startup_timeout_sec = 30
+
+[mcp_servers.memory]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-memory"]
+startup_timeout_sec = 30
+
+[mcp_servers.playwright]
+command = "npx"
+args = ["-y", "@playwright/mcp@latest", "--extension"]
+startup_timeout_sec = 30
+
+[mcp_servers.sequential-thinking]
+command = "npx"
+args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+startup_timeout_sec = 30
+
+# Additional MCP servers (uncomment as needed):
+# [mcp_servers.supabase]
+# command = "npx"
+# args = ["-y", "supabase-mcp-server@latest", "--read-only"]
+#
+# [mcp_servers.firecrawl]
+# command = "npx"
+# args = ["-y", "firecrawl-mcp"]
+#
+# [mcp_servers.fal-ai]
+# command = "npx"
+# args = ["-y", "fal-ai-mcp-server"]
+#
+# [mcp_servers.cloudflare]
+# command = "npx"
+# args = ["-y", "@cloudflare/mcp-server-cloudflare"]
+
+[features]
+# Codex multi-agent collaboration is stable and on by default in current builds.
+# Keep the explicit toggle here so the repo documents its expectation clearly.
+multi_agent = true
+
+# Profiles — switch with `codex -p <name>`
+[profiles.strict]
+approval_policy = "on-request"
+sandbox_mode = "read-only"
+web_search = "cached"
+
+[profiles.yolo]
+approval_policy = "never"
+sandbox_mode = "workspace-write"
+web_search = "live"
+
+[agents]
+# Multi-agent role limits and local role definitions.
+# These map to `.codex/agents/*.toml` and mirror the repo's explorer/reviewer/docs workflow.
+max_threads = 6
+max_depth = 1
+
+[agents.explorer]
+description = "Read-only codebase explorer for gathering evidence before changes are proposed."
+config_file = "agents/explorer.toml"
+
+[agents.reviewer]
+description = "PR reviewer focused on correctness, security, and missing tests."
+config_file = "agents/reviewer.toml"
+
+[agents.docs_researcher]
+description = "Documentation specialist that verifies APIs, framework behavior, and release notes."
+config_file = "agents/docs-researcher.toml"