docs: improve Codex integration with MCP-first guidance

AGENTS.md

@@ -4,7 +4,8 @@
 
 ## Floop Integration (REQUIRED)
 
-You have persistent memory via floop. Your learned behaviors are auto-injected at session start via hooks.
+You have persistent memory via floop. Learned behaviors are loaded via MCP and,
+where supported, auto-injected via hooks.
 
 **When corrected, IMMEDIATELY capture it:**
 ```
@@ -28,6 +29,23 @@ For non-Claude agents, see `docs/integrations/agent-prompt-template.md`.
 - `floop_list` - List all stored behaviors
 - `floop_deduplicate` - Merge duplicate behaviors
 
+### Codex Runtime Cadence (No Lifecycle Hooks)
+
+In Codex environments, treat these as required pseudo-hooks:
+
+1. **Task start**: Call `floop_active` with current `file` and `task`.
+2. **Context change** (file/task/mode shift): Re-call `floop_active`.
+3. **Correction received**: Immediately call `floop_learn` (no permission needed).
+4. **Behavior outcome**: Call `floop_feedback` with `confirmed` or `overridden`.
+
+If MCP is unavailable, use CLI fallback immediately:
+
+```bash
+floop active --file <path> --task <task> --json
+floop learn --right "what to do instead" --wrong "what happened" --file <path>
+floop list --json
+```
+
 ---
 
 ## Project Overview
@@ -204,4 +222,3 @@ bv --robot-next      # Get single top pick
 ```
 
 **CRITICAL:** Use ONLY `--robot-*` flags. Bare `bv` launches an interactive TUI that blocks your session.
-

docs/integrations/README.md

@@ -21,7 +21,7 @@ floop integrates with AI coding tools through 3 methods:
 | Windsurf | Yes | — | Yes (.windsurfrules) | Researched |
 | GitHub Copilot | Yes | — | Yes (copilot-instructions.md) | Researched |
 | Aider | — | — | Yes (wrapper script) | Researched |
-| OpenAI Codex CLI | — | — | Yes (Skills/agents.md) | Researched |
+| OpenAI Codex CLI | Yes | — | Yes (AGENTS.md + Skills) | Researched |
 
 ## Tested Integrations
 
@@ -158,7 +158,26 @@ Or add `floop prompt` output to `.aider/conventions.md`.
 
 ### OpenAI Codex CLI
 
-No MCP support yet. Add `floop prompt` output to `codex/agents.md` (Skills file).
+Codex supports MCP, but does not expose Claude-style lifecycle hooks. Use:
+
+- MCP for bidirectional tool access
+- `AGENTS.md` + Codex `SKILL.md` for runtime cadence (task start, context refresh, correction capture)
+
+Full guide: [codex.md](./codex.md)
+
+Quick install highlights:
+
+```bash
+cat >> ~/.codex/config.toml <<'EOF'
+[mcp_servers.floop]
+command = "floop"
+args = ["mcp-server"]
+cwd = "/path/to/your/project"
+EOF
+
+mkdir -p ~/.agents/skills/floop
+ln -sfn "$(pwd)/docs/integrations/templates/floop.SKILL.md.template" ~/.agents/skills/floop/SKILL.md
+```
 
 ## Generic MCP Configuration
 

docs/integrations/agent-prompt-template.md

@@ -72,15 +72,15 @@ If floop tools return errors about missing or uninitialized state, run
 
 ## Static Template (Read-Only)
 
-For tools without MCP support (Aider, OpenAI Codex CLI, or any tool where you prefer a simpler setup).
+For tools without MCP support (Aider, or any tool where you prefer a simpler setup).
 
 Run this command to generate a snapshot of your current behaviors:
 
 ```bash
 floop prompt
 ```
 
-Paste the output into your tool's instruction file (`.cursorrules`, `copilot-instructions.md`, `agents.md`, etc.).
+Paste the output into your tool's instruction file (`.cursorrules`, `copilot-instructions.md`, `AGENTS.md`, etc.).
 
 **Limitations:** Static mode is **read-only** — the agent can follow behaviors but cannot capture new corrections automatically. To capture corrections, run `floop learn` manually in your terminal:
 
@@ -106,6 +106,16 @@ floop prompt > .cursorrules
 > Ensure `floop init` has been run first, or `floop prompt` will output an
 > initialization warning instead of behaviors.
 
+## Codex Note
+
+Codex can use MCP for floop. Prefer MCP + instruction orchestration over static-only mode:
+
+- Add floop MCP server in Codex config
+- Add Codex runtime cadence rules in `AGENTS.md`
+- Optionally install a Codex skill for floop workflow enforcement
+
+See [codex.md](./codex.md) for setup.
+
 ## Where to Paste
 
 See the [compatibility matrix](./README.md) for your tool's instruction file location.

docs/integrations/codex.md

@@ -0,0 +1,166 @@
+# OpenAI Codex Integration
+
+## Overview
+
+Codex can use floop through MCP, but it does not currently expose Claude-style
+lifecycle hooks (such as `SessionStart`, `PreToolUse`, `UserPromptSubmit`).
+
+That means Codex integrations need two layers:
+
+1. MCP for bidirectional floop tool access
+2. Instruction orchestration (`AGENTS.md` + optional `SKILL.md`) to emulate hook cadence
+
+This guide shows both.
+
+## Quick Install (Codex)
+
+Run from your project root:
+
+```bash
+# 1) Ensure floop is installed
+which floop
+
+# 2) Configure MCP in Codex (~/.codex/config.toml)
+cat >> ~/.codex/config.toml <<'EOF'
+[mcp_servers.floop]
+command = "floop"
+args = ["mcp-server"]
+cwd = "/path/to/your/project"
+EOF
+
+# 3) Install AGENTS baseline rules
+cp docs/integrations/templates/codex-agents.md.template AGENTS.md
+
+# 4) Install floop skill via Codex skill discovery path
+mkdir -p ~/.agents/skills/floop
+ln -sfn "$(pwd)/docs/integrations/templates/floop.SKILL.md.template" ~/.agents/skills/floop/SKILL.md
+```
+
+Then restart Codex (fully quit and relaunch).
+
+If you already have an `AGENTS.md`, merge the template content instead of
+overwriting the file.
+
+## 1) Configure MCP
+
+Add floop as an MCP server in your Codex config.
+
+Example `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.floop]
+command = "floop"
+args = ["mcp-server"]
+# Optional but recommended for project-local behavior stores
+cwd = "/path/to/your/project"
+```
+
+If you prefer per-project setup, use Codex's local config equivalent and keep
+`cwd` set to your project root.
+
+## 2) Verify MCP Is Working
+
+Use this checklist in a Codex session:
+
+1. Confirm Codex shows `floop_*` tools in its MCP tool list.
+2. Ask Codex to call `floop_active` for your current file/task.
+3. Confirm a structured response is returned (with `active` behaviors and `count`).
+4. Ask Codex to call `floop_list` and verify the store is reachable.
+
+If tools are missing:
+
+- Confirm `floop` is in `PATH` (`which floop`).
+- Confirm `floop mcp-server` runs manually in your project.
+- Confirm Codex loaded the expected config file and restart Codex.
+
+## 3) Add Codex Orchestration Rules (No Hooks)
+
+Because Codex has no lifecycle hooks, add explicit runtime rules to your
+project `AGENTS.md`.
+
+Use this template:
+
+- [codex-agents.md.template](./templates/codex-agents.md.template)
+
+These rules force the cadence hooks normally provide:
+
+- At task start -> call `floop_active`
+- On context change (file/task/tooling mode) -> refresh `floop_active`
+- On correction -> call `floop_learn` immediately
+- After following or overriding behavior -> call `floop_feedback`
+
+## 4) Add Optional Codex Skill
+
+For stronger consistency, add a dedicated Codex skill:
+
+- [floop.SKILL.md.template](./templates/floop.SKILL.md.template)
+
+Recommended install location:
+
+`~/.agents/skills/floop/SKILL.md`
+
+Use project-local skills if your team prefers repository-scoped behavior.
+
+## 5) CLI Fallback (If MCP Is Unavailable)
+
+If MCP is not available in your Codex environment, keep read/write behavior via
+CLI commands:
+
+```bash
+# Load context
+floop active --file <path> --task <task> --json
+
+# Learn correction
+floop learn --right "what to do instead" --wrong "what happened" --file <path>
+
+# Review behaviors
+floop list --json
+```
+
+Static prompt fallback:
+
+```bash
+floop prompt > AGENTS.md
+```
+
+Note: static prompt mode is read-only for the agent. New corrections must be
+captured manually via `floop learn`.
+
+## 6) Dogfood Verification Flow
+
+Run this sequence to validate end-to-end behavior:
+
+1. Start a new Codex task and trigger `floop_active`.
+2. Deliberately correct Codex and ensure it calls `floop_learn`.
+3. Start a second related task and verify the new behavior appears in `floop_active`.
+4. Confirm `floop_feedback` gets emitted when behavior is followed/overridden.
+
+If step 2 or 4 is missed, tighten your `AGENTS.md` trigger language or install
+the Codex skill template.
+
+## Skill Maintenance
+
+Because the recommended install uses a symlink, updates are immediate when the
+template file changes in your repo.
+
+### Verify Skill Install
+
+```bash
+ls -la ~/.agents/skills/floop/SKILL.md
+```
+
+You should see a symlink pointing to:
+`docs/integrations/templates/floop.SKILL.md.template`.
+
+### Update
+
+```bash
+cd /path/to/your/project
+git pull
+```
+
+### Uninstall
+
+```bash
+rm -f ~/.agents/skills/floop/SKILL.md
+```

docs/integrations/templates/codex-agents.md.template

@@ -0,0 +1,42 @@
+### floop + Codex Orchestration (No Lifecycle Hooks)
+
+Codex has floop MCP tools available, but does not provide Claude-style lifecycle
+hooks. You MUST emulate lifecycle behavior by explicitly calling floop tools at
+the right moments.
+
+#### Required Cadence
+
+1. Task start:
+   - Call `floop_active` with `file` and `task` before substantive changes.
+2. Context shift:
+   - Re-call `floop_active` whenever file focus, task type, or implementation
+     mode changes.
+3. User correction:
+   - Immediately call `floop_learn` with:
+     - `right` (required)
+     - `wrong` (optional but recommended)
+     - `file`, `task`, and `tags` when available
+   - Do not wait for user permission.
+4. Behavior outcome:
+   - If behavior helps, call `floop_feedback` with `signal: "confirmed"`.
+   - If intentionally deviating, call `floop_feedback` with
+     `signal: "overridden"`.
+
+#### Reliability Rules
+
+- If MCP calls fail, switch to CLI fallback immediately.
+- Keep working while recording learnings; do not defer correction capture.
+- Prefer narrow, file/task-aware behavior retrieval over broad prompt dumps.
+
+#### CLI Fallback
+
+```bash
+# Active behaviors
+floop active --file <path> --task <task> --json
+
+# Learn correction
+floop learn --right "what to do instead" --wrong "what happened" --file <path>
+
+# Review behaviors
+floop list --json
+```

docs/integrations/templates/floop.SKILL.md.template

@@ -0,0 +1,51 @@
+---
+name: floop
+description: Enforce floop behavior retrieval and correction capture cadence in hookless Codex sessions.
+---
+
+# floop Skill
+
+## Purpose
+
+Codex sessions do not have lifecycle hooks. This skill enforces a manual
+operational loop so floop still behaves like persistent, context-aware memory.
+
+## Operating Loop
+
+1. Bootstrap context
+   - Call `floop_active` with the active file path and task.
+   - If no file is known, call with task only, then refine once file context is available.
+
+2. Refresh on context change
+   - Re-run `floop_active` when changing files, task type, or execution mode
+     (implementation, testing, refactor, review).
+
+3. Capture corrections immediately
+   - When corrected by user, call `floop_learn` right away.
+   - Include `right` always.
+   - Include `wrong`, `file`, `task`, and `tags` when available.
+   - Never wait for permission.
+
+4. Emit feedback signal
+   - If a behavior was useful: `floop_feedback` with `confirmed`.
+   - If you intentionally do not follow a behavior: `floop_feedback` with `overridden`.
+
+5. Periodic hygiene
+   - Use `floop_list` for visibility.
+   - Run `floop_deduplicate` and `floop_validate` periodically to keep quality high.
+
+## Fallback Mode (No MCP)
+
+If MCP is unavailable, use CLI equivalents:
+
+```bash
+floop active --file <path> --task <task> --json
+floop learn --right "..." --wrong "..." --file <path>
+floop list --json
+```
+
+## Non-Negotiables
+
+- No task should proceed without an initial `floop_active` call.
+- No correction should be ignored or delayed.
+- No long session should end without at least one explicit feedback signal if behaviors were used.