codetrap 0.1.8 → 0.1.9

package/README.md

@@ -64,50 +64,21 @@ npm install -g codetrap
 
 # Initialize pitfall memory in the target project
 cd /path/to/project
-codetrap init
+codetrap setup codex
 codetrap doctor
 ```
 
-Add the packaged agent guidance to `AGENTS.md` for Codex, or to `CLAUDE.md` for Claude Code:
-
-```bash
-cat "$(npm root -g)/codetrap/plugins/codetrap-agent/templates/AGENTS.codetrap.md" >> AGENTS.md
-# or:
-cat "$(npm root -g)/codetrap/plugins/codetrap-agent/templates/AGENTS.codetrap.md" >> CLAUDE.md
-```
-
-Then have the agent run this before non-trivial edits:
-
-```bash
-codetrap search "<task keywords>" --mode hybrid --json
-```
+`codetrap setup codex` installs the bundled Codex skills into `~/.codex/skills`, initializes `.codetrap/` when needed, and writes `AGENTS.md`. It does not configure MCP by default.
 
-Review the top 3 returned action cards, or all returned cards if fewer than 3, before deciding whether any trap applies. Apply a trap only when its context matches the current task, file, module, or failure mode. Severity alone is not enough to apply a trap. Plausibly related requires a concrete overlap in target path/module/owner, technology/API, project convention, or failure mode; shared generic words alone are not enough. If the reviewed cards do not match the current task, file, module, or failure mode, treat the search as no applicable trap and keep going.
-
-After a user correction, repeated test failure, or review finding, have the agent draft a candidate instead of writing confirmed memory:
+To also configure Codex MCP, opt in explicitly:
 
 ```bash
-cat <<'EOF' | codetrap session capture --trap-markdown - --kind review --json
-Title: <durable pitfall>
-Context: <when it triggers>
-Mistake: <what the agent did wrong>
-Fix: <what to do instead>
-EOF
+codetrap setup codex --mcp
 ```
 
-Review pending candidates with `codetrap session status`, `codetrap session list`, `codetrap doctor`, or `codetrap web`; accepting a candidate remains an explicit human decision.
+The packaged template is the source of truth for exact agent behavior. It tells agents to run CLI JSON checks before non-trivial edits, inspect only relevant action cards, keep post-flight lessons in the session candidate inbox, and require explicit human approval before accepting a candidate into `traps.db`.
 
-Use the returned `candidate_id` and `session_id` to inspect and resolve the candidate:
-
-```bash
-codetrap session candidate <candidate-id> --session <session-id> --json
-
-# Only after explicit human approval:
-codetrap session accept <candidate-id> --session <session-id>
-
-# Or reject instead:
-codetrap session reject <candidate-id> --session <session-id> --reason "<reason>"
-```
+For a quick manual check, agents can run `codetrap search "<task keywords>" --mode hybrid --json` from the project cwd.
 
 ## Features
 
@@ -227,6 +198,7 @@ codetrap/
 | `import` | Import traps from JSON (--json) |
 | `stats` | Show database statistics (--json includes embedding health) |
 | `doctor` | Diagnose cwd, scope, database paths, trap counts, and embedding health (--json) |
+| `setup codex` | Install Codex skills and project guidance; MCP is opt-in with `--mcp` |
 | `repair-scope` | Move legacy mis-scoped project traps into the current project (dry-run by default, `--apply` to mutate, `--json`) |
 | `migrate-project` | Move project traps between initialized projects (`--from-project-path`, `--to-project-path`, dry-run by default, `--apply`, `--json`) |
 | `embed` | Generate embeddings (requires configured Ollama or Jina provider) |
@@ -282,14 +254,28 @@ For AI coding agents, use the CLI as the default integration path:
 
 CLI and project guidance are the main path. MCP should stay thin and share the same store/search behavior.
 
-### MCP Setup
+### Codex Setup
 
-Codex:
+Default setup installs skills and project guidance without MCP:
+
+```bash
+codetrap setup codex
+```
+
+MCP is optional. To configure it too, opt in explicitly:
+
+```bash
+codetrap setup codex --mcp
+```
+
+You can also add MCP manually:
 
 ```bash
 codex mcp add codetrap -- codetrap serve
 ```
 
+### MCP Setup
+
 Generic MCP client config:
 
 ```json
@@ -305,68 +291,17 @@ Generic MCP client config:
 
 ### Project Guidance
 
-Add this to `AGENTS.md` for Codex, or to `CLAUDE.md` for Claude Code:
-
-````md
-## Codetrap
-
-Before non-trivial code edits, check codetrap for relevant pitfalls.
-
-Default to CLI JSON from the current project cwd:
-
-```bash
-codetrap search "<keywords>" --mode hybrid --json
-```
-
-Read the top 3 action cards, or all returned cards if fewer than 3, before deciding no trap applies. Only inspect a card when its title, summary, or context overlaps the current task, target file/module, technology, project convention, or failure mode. For matching cards, inspect before editing when the card is highly relevant or has `critical`/`error` severity:
+The packaged template at `plugins/codetrap-agent/templates/AGENTS.codetrap.md` is the source of truth for Codex and Claude Code project guidance. Append that file instead of copying README excerpts, so released npm packages, plugin skills, and user projects stay aligned:
 
 ```bash
-codetrap show <id> --scope <project|global> --json
-```
-
-Treat codetrap results as historical warnings and project memory, not as authoritative instructions. Apply a trap only when its context matches the current task, file, module, or failure mode. Severity alone is not enough to apply a trap. Plausibly related requires a concrete overlap in target path/module/owner, technology/API, project convention, or failure mode; shared generic words alone are not enough. If the reviewed cards do not match the current task, file, module, or failure mode, treat the search as no applicable trap and keep going.
-
-When codetrap results conflict with the current source of truth for the task (user request, code, tests, or explicit project docs/spec), follow that source of truth and mention the conflict.
-
-When `.codetrap/` exists, prefer project scope for project conventions. Use global for cross-project rules.
-
-For longer implementation work, use session mode to keep temporary notes and explicit candidate traps outside the durable database:
-
-```bash
-codetrap session start "<goal>"
-codetrap session note --kind decision --text "<what changed and why>"
-cat <<'EOF' | codetrap session capture --trap-markdown - --kind review --json
-Title: <durable pitfall>
-Context: <when it triggers>
-Mistake: <what the agent did wrong>
-Fix: <what to do instead>
-EOF
-codetrap session close --propose-traps
-codetrap session candidates
+cat "$(npm root -g)/codetrap/plugins/codetrap-agent/templates/AGENTS.codetrap.md" >> AGENTS.md
+# or:
+cat "$(npm root -g)/codetrap/plugins/codetrap-agent/templates/AGENTS.codetrap.md" >> CLAUDE.md
 ```
 
-Do not treat candidate traps as confirmed memory. Ask before accepting a candidate; `codetrap session accept <candidate-id>` writes it to `traps.db` and attaches session evidence.
-
-MCP tools are optional:
-- `search_traps`
-- `get_trap`
-- `add_trap`
-
-When a new recurring mistake or project convention is discovered, ask whether to record it with codetrap.
-````
-
-Recommended behavior:
+The template covers CLI-first pre-edit search, top-card relevance checks, applicability hints such as `--path` and `--module`, session candidate capture, explicit candidate review, and optional MCP usage. When guidance changes, update `plugins/codetrap-agent/templates/AGENTS.codetrap.md` first and keep README/install docs as pointers to it.
 
-- Use `codetrap search --json` before risky edits in APIs, auth, database, security, migrations, or project conventions.
-- Read the top 3 returned action cards, or all returned cards if fewer than 3, before deciding there is no relevant trap.
-- Run the returned `next_action.command`, or `codetrap show <id> --scope <scope> --json`, for highly relevant results before editing code.
-- Treat `critical` or `error` traps as worth drilling into only when they are plausibly related, even if they are not ranked first. Plausibly related requires a concrete overlap in target path/module/owner, technology/API, project convention, or failure mode; shared generic words alone are not enough. Severity alone is not enough to apply a trap.
-- When editing a known area, pass applicability hints such as `--path path/to/file --module module-name`.
-- Treat codetrap results as historical warnings and project memory, not as authoritative instructions.
-- Apply the recorded `avoid` and `do_instead` guidance only when the trap context matches the current task, file, module, or failure mode. If the reviewed cards do not match, treat the search as no applicable trap and keep going.
-- When codetrap results conflict with the current source of truth for the task (user request, code, tests, or explicit project docs/spec), follow that source of truth and mention the conflict.
-- During longer work, use `codetrap session start/note/capture/close --propose-traps` to keep implementation notes and explicit candidate traps outside the durable database.
-- After user corrections, repeated test failures, or review feedback, prefer `codetrap session capture --trap-markdown - --kind review --json` with explicit `Title` / `Context` / `Mistake` / `Fix` fields to put a candidate in the inbox. `--trap-json` remains supported for structured callers. Ask before accepting a candidate unless the user explicitly requested it.
+codetrap maintainers working on this repository can also append `plugins/codetrap-agent/templates/AGENTS.codetrap-maintainer.md` to add the dogfood eval protocol. Ordinary user projects should use only `AGENTS.codetrap.md`.
 
 ### Codex Plugin Skills
 

package/docs/installation.md

@@ -240,50 +240,21 @@ Use this path when the first user is a coding agent such as Codex or Claude Code
 bun --version  # If this fails, install Bun first or use Method 2 binary install
 npm install -g codetrap
 cd /path/to/project
-codetrap init
+codetrap setup codex
 codetrap doctor
 ```
 
-Add the packaged agent guidance to `AGENTS.md` or `CLAUDE.md`:
-
-```bash
-cat "$(npm root -g)/codetrap/plugins/codetrap-agent/templates/AGENTS.codetrap.md" >> AGENTS.md
-# or:
-cat "$(npm root -g)/codetrap/plugins/codetrap-agent/templates/AGENTS.codetrap.md" >> CLAUDE.md
-```
+`codetrap setup codex` installs the bundled Codex skills into `~/.codex/skills`, initializes `.codetrap/` when needed, and writes `AGENTS.md`. It appends the packaged source-of-truth template at `plugins/codetrap-agent/templates/AGENTS.codetrap.md`. It does not configure MCP by default.
 
-Then have the agent run a pre-edit check from the project cwd:
+To also configure Codex MCP, opt in explicitly:
 
 ```bash
-codetrap search "<task keywords>" --mode hybrid --json
+codetrap setup codex --mcp
 ```
 
-Review the top 3 returned action cards, or all returned cards if fewer than 3, before deciding whether any trap applies. Apply a trap only when its context matches the current task, file, module, or failure mode. Severity alone is not enough to apply a trap. Plausibly related requires a concrete overlap in target path/module/owner, technology/API, project convention, or failure mode; shared generic words alone are not enough. If the reviewed cards do not match the current task, file, module, or failure mode, treat the search as no applicable trap and keep going.
-
-After user corrections, repeated test failures, or review feedback, have the agent write a candidate into the review inbox:
-
-```bash
-cat <<'EOF' | codetrap session capture --trap-markdown - --kind review --json
-Title: <durable pitfall>
-Context: <when it triggers>
-Mistake: <what the agent did wrong>
-Fix: <what to do instead>
-EOF
-```
-
-Use `codetrap session status`, `codetrap session list`, `codetrap doctor`, or `codetrap web` to review pending candidates. Do not accept candidates automatically.
-
-Use the returned `candidate_id` and `session_id` to inspect and resolve the candidate:
-
-```bash
-codetrap session candidate <candidate-id> --session <session-id> --json
-
-# Only after explicit human approval:
-codetrap session accept <candidate-id> --session <session-id>
+The packaged template is the source of truth for exact agent behavior. It tells agents to run CLI JSON checks before non-trivial edits, inspect only relevant action cards, keep post-flight lessons in the session candidate inbox, and require explicit human approval before accepting a candidate into `traps.db`.
 
-# Or reject instead:
-codetrap session reject <candidate-id> --session <session-id> --reason "<reason>"
-```
+For a quick manual check, agents can run `codetrap search "<task keywords>" --mode hybrid --json` from the project cwd.
 
 ## Optional: Local Ollama Embeddings
 
@@ -342,79 +313,22 @@ If no embedding provider is configured:
 
 ## Optional: Codex MCP
 
-If the `codetrap` command is on your `PATH`, add it to Codex as an MCP server:
+MCP is optional. `codetrap setup codex` does not configure MCP unless you pass `--mcp`:
 
 ```bash
-codex mcp add codetrap -- codetrap serve
+codetrap setup codex --mcp
 ```
 
-If your MCP client does not inherit your shell `PATH`, use the absolute path:
+You can also add MCP manually if the `codetrap` command is on your `PATH`:
 
 ```bash
-codex mcp add codetrap -- "$(bun pm bin -g)/codetrap" serve
-```
-
-Agents can also use the CLI directly from `AGENTS.md`:
-
-````md
-Before non-trivial code edits, check codetrap from the current project cwd:
-
-codetrap search "<keywords>" --mode hybrid --json
-
-Review the top 3 action cards, or all returned cards if fewer than 3, before deciding no trap applies. Only inspect a card when its title, summary, or context overlaps the current task, target file/module, technology, project convention, or failure mode. For matching critical/error results, inspect before editing:
-
-codetrap show <id> --scope <project|global> --json
-
-Apply a trap only when its context matches the current task, file, module, or failure mode. Severity alone is not enough to apply a trap. Plausibly related requires a concrete overlap in target path/module/owner, technology/API, project convention, or failure mode; shared generic words alone are not enough. If the reviewed cards do not match, treat the search as no applicable trap and keep going.
-
-When editing a known area, pass applicability hints:
-
-codetrap search "<keywords>" --path path/to/file --module module-name --json
-
-To capture a post-flight lesson from agent work:
-
-```bash
-cat <<'EOF' | codetrap session capture --trap-markdown - --kind review --json
-Title: <durable pitfall>
-Context: <when it triggers>
-Mistake: <what the agent did wrong>
-Fix: <what to do instead>
-EOF
-```
-
-`--trap-json` remains available for callers that already have a structured object:
-
-```bash
-codetrap session capture --trap-json '{...}' --kind review --json
-```
-
-For longer implementation work, keep temporary notes and explicit candidate traps in session files first:
-
-```bash
-codetrap session start "<goal>"
-codetrap session note --kind decision --text "<what changed and why>"
-cat <<'EOF' | codetrap session capture --trap-markdown - --kind review --json
-Title: <durable pitfall>
-Context: <when it triggers>
-Mistake: <what the agent did wrong>
-Fix: <what to do instead>
-EOF
-codetrap session close --propose-traps
-codetrap session candidates
+codex mcp add codetrap -- codetrap serve
 ```
 
-Pending candidates are visible from `codetrap session status`, `codetrap session list`, `codetrap doctor`, and `codetrap web`.
-
-Only accepted candidates are written to `traps.db`:
+If your MCP client does not inherit your shell `PATH`, use the absolute path:
 
 ```bash
-# Only after explicit human approval:
-codetrap session accept <candidate-id>
+codex mcp add codetrap -- "$(bun pm bin -g)/codetrap" serve
 ```
 
-`codetrap session accept --edit-json ...` applies the edit before conflict detection. If a possible active-trap conflict is found, the candidate remains proposed and records conflict diagnostics until you choose `--accept-anyway`, `--supersedes <trap-id>`, or reject it.
-
-To save a lesson from an external article or reference, let the agent read the source and attach the URL as evidence after the user confirms the trap:
-
-codetrap add_trap_evidence <id> --scope global --source_type article --source_ref "https://example.com/post" --output-json
-````
+Agents can also use the CLI directly when the project guidance tells them when to call it. `codetrap setup codex` installs that guidance in `AGENTS.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codetrap",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Capture and retrieve coding pitfalls so AI doesn't repeat mistakes",
   "type": "module",
   "license": "MIT",

package/plugins/codetrap-agent/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codetrap-agent",
-  "version": "0.1.2",
+  "version": "0.1.9",
   "description": "CLI-first codetrap integration bundle for coding agents.",
   "author": {
     "name": "codetrap maintainers",

package/plugins/codetrap-agent/templates/AGENTS.codetrap-maintainer.md

@@ -0,0 +1,15 @@
+## Codetrap Dogfood Eval
+
+Use this add-on only for codetrap maintainers working on codetrap itself. For ordinary external projects, use `AGENTS.codetrap.md` without this dogfood section.
+
+After each pre-edit codetrap search, record whether the search was:
+- useful_hit
+- miss
+- noisy_hit
+- no_relevant_trap
+
+Record the observation in `dogfood-log.md` with the task, query, mode, top results, judgment, whether the result changed the next action, and the promotion lane.
+
+When a real query should reliably find an existing trap, save it as a live eval case with query, mode, scope, and gold target.
+
+Do not promote every observation. Only promote representative cases that protect search quality.

package/plugins/codetrap-agent/templates/AGENTS.codetrap.md

@@ -38,18 +38,3 @@ Use `--trap-json` only when the caller already has a structured object.
 Review the candidate with `codetrap session candidate <candidate-id> --session <session-id> --json`, then accept, edit, reject, or supersede it explicitly.
 
 Use `codetrap session status`, `codetrap session list`, `codetrap doctor`, or `codetrap web` to find pending candidates that still need review.
-
-
-## Codetrap Dogfood Eval
-
-After each pre-edit codetrap search, record whether the search was:
-- useful_hit
-- miss
-- noisy_hit
-- no_relevant_trap
-
-Record the observation in `dogfood-log.md` with the task, query, mode, top results, judgment, whether the result changed the next action, and the promotion lane.
-
-When a real query should reliably find an existing trap, save it as a live eval case with query, mode, scope, and gold target.
-
-Do not promote every observation. Only promote representative cases that protect search quality.

package/scripts/release-preflight.ts

@@ -1,5 +1,8 @@
 #!/usr/bin/env bun
 
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
 const tag = process.argv[2] ?? process.env.RELEASE_TAG;
 const packageJson = await Bun.file("package.json").json() as { name?: string; version?: string };
 const published = await packageVersionExists(packageJson.name, packageJson.version);
@@ -10,6 +13,18 @@ const commands: { name: string; cmd: string[]; optional?: boolean }[] = [
   { name: "build", cmd: ["bun", "run", "build"] },
   { name: "build release assets", cmd: ["bun", "run", "build:release"] },
   { name: "smoke test release binary", cmd: [hostBinaryPath(), "--help"] },
+  {
+    name: "smoke test release binary Codex setup",
+    cmd: [
+      hostBinaryPath(),
+      "setup",
+      "codex",
+      "--dry-run",
+      "--json",
+      "--codex-home",
+      join(tmpdir(), "codetrap-release-preflight-codex-home"),
+    ],
+  },
   { name: "npm pack dry-run", cmd: ["npm", "pack", "--dry-run"] },
   ...(!published ? [{ name: "npm publish dry-run", cmd: ["npm", "publish", "--dry-run", "--access", "public"] }] : []),
 ];

package/src/commands/workflow.ts

@@ -17,6 +17,7 @@ import {
   type EmbeddingsUseResult,
 } from "../lib/embedding-management";
 import { searchDefaultsFromConfig } from "../lib/config";
+import { formatCodexSetupText, runCodexSetup } from "../lib/codex-setup";
 import { SessionStore } from "../lib/session-store";
 import { SessionOperations, type SessionConflictResult } from "../lib/session-operations";
 import {
@@ -110,6 +111,8 @@ export async function executeCommand(strip: string[], store: TrapStore): Promise
       return cmdStats(args, operations);
     case "doctor":
       return cmdDoctor(args, store, operations);
+    case "setup":
+      return cmdSetup(args);
     case "repair-scope":
       return cmdScopeMigration("repair-scope", args, operations);
     case "migrate-project":
@@ -123,7 +126,7 @@ export async function executeCommand(strip: string[], store: TrapStore): Promise
     default:
       return errorResult([
         `Unknown command: ${sub}`,
-        "Commands: init, add, search, list, show, edit, delete, add_trap_evidence, archive_trap, supersede_trap, export, import, stats, doctor, repair-scope, migrate-project, embed, embeddings, session",
+        "Commands: init, add, search, list, show, edit, delete, add_trap_evidence, archive_trap, supersede_trap, export, import, stats, doctor, setup, repair-scope, migrate-project, embed, embeddings, session",
       ].join("\n"));
   }
 }
@@ -370,6 +373,31 @@ async function cmdDoctor(args: string[], store: TrapStore, operations: TrapOpera
     : textResult(formatDoctorText(report));
 }
 
+function cmdSetup(args: string[]): CommandResult {
+  const sub = args[0];
+  const rest = args.slice(1);
+  if (sub !== "codex") {
+    return errorResult("Usage: codetrap setup codex [--mcp] [--no-agents] [--agents-file AGENTS.md] [--codex-home <path>] [--dry-run] [--json]");
+  }
+  const { opts } = parseArgs(rest);
+  try {
+    const result = runCodexSetup({
+      cwd: process.cwd(),
+      codexHome: opts["codex-home"],
+      agentsFile: opts["agents-file"],
+      installMcp: opts.mcp !== undefined,
+      skipAgents: opts["no-agents"] !== undefined,
+      dryRun: opts["dry-run"] !== undefined,
+    });
+    if (opts.json !== undefined) return jsonResult(result, result.success ? 0 : 1);
+    return result.success
+      ? textResult(formatCodexSetupText(result))
+      : errorResult(formatCodexSetupText(result));
+  } catch (error) {
+    return errorFrom(error);
+  }
+}
+
 function cmdScopeMigration(
   command: ScopeMigrationCommand,
   args: string[],

package/src/index.ts

@@ -61,6 +61,7 @@ function showHelp(): void {
   console.log("  import <file.json>    Import traps from JSON");
   console.log("  stats                 Show statistics");
   console.log("  doctor                Diagnose scope, database, and embedding health");
+  console.log("  setup codex           Install Codex skills and project guidance (MCP opt-in)");
   console.log("  repair-scope          Move mis-scoped project traps into the current project");
   console.log("  migrate-project       Move project traps between initialized projects");
   console.log("  serve                 Start MCP server (for Claude Code)");
@@ -84,7 +85,11 @@ function showHelp(): void {
   console.log("  --output-json           JSON output for add/edit when --json is used as input");
   console.log("  --from-project-path <path>  Source project path for scope repair/migration");
   console.log("  --to-project-path <path>    Destination project path for scope repair/migration");
-  console.log("  --dry-run|--apply       Preview or apply scope repair/migration");
+  console.log("  --dry-run|--apply       Preview setup/scope migration, or apply scope migration");
+  console.log("  --mcp                  With setup codex, also run: codex mcp add codetrap -- codetrap serve");
+  console.log("  --codex-home <path>    With setup codex, override CODEX_HOME/default ~/.codex");
+  console.log("  --agents-file <path>   With setup codex, choose AGENTS.md target");
+  console.log("  --no-agents            With setup codex, install skills without editing AGENTS.md");
 }
 
 function showWebHelp(): void {

package/src/lib/codex-setup.ts

@@ -0,0 +1,247 @@
+import {
+  appendFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findProjectRoot } from "./scope";
+import agentsTemplateAsset from "../../plugins/codetrap-agent/templates/AGENTS.codetrap.md" with { type: "text" };
+import codetrapAddSkill from "../../plugins/codetrap-agent/skills/codetrap-add/SKILL.md" with { type: "text" };
+import codetrapCaptureSkill from "../../plugins/codetrap-agent/skills/codetrap-capture/SKILL.md" with { type: "text" };
+import codetrapCaptureExternalSkill from "../../plugins/codetrap-agent/skills/codetrap-capture-external/SKILL.md" with { type: "text" };
+import codetrapCheckSkill from "../../plugins/codetrap-agent/skills/codetrap-check/SKILL.md" with { type: "text" };
+import codetrapSearchSkill from "../../plugins/codetrap-agent/skills/codetrap-search/SKILL.md" with { type: "text" };
+
+export type CodexSetupOptions = {
+  cwd: string;
+  codexHome?: string;
+  agentsFile?: string;
+  installMcp?: boolean;
+  skipAgents?: boolean;
+  dryRun?: boolean;
+};
+
+export type CodexSetupStatus =
+  | "already_present"
+  | "created"
+  | "appended"
+  | "installed"
+  | "updated"
+  | "unchanged"
+  | "skipped"
+  | "would_create"
+  | "would_append"
+  | "would_install"
+  | "would_update"
+  | "would_run"
+  | "failed";
+
+export type CodexSetupResult = {
+  success: boolean;
+  project_root: string;
+  codex_home: string;
+  plugin_root: string;
+  dry_run: boolean;
+  project: {
+    codetrap_dir: string;
+    status: CodexSetupStatus;
+  };
+  skills: Array<{
+    name: string;
+    source: string;
+    destination: string;
+    status: CodexSetupStatus;
+  }>;
+  agents: {
+    path: string | null;
+    status: CodexSetupStatus;
+  };
+  mcp: {
+    requested: boolean;
+    command: string;
+    status: CodexSetupStatus;
+    exit_code?: number | null;
+    error?: string;
+  };
+};
+
+const AGENTS_TEMPLATE_PATH = "templates/AGENTS.codetrap.md";
+const CODEX_MARKER = "codetrap search \"<keywords>\" --mode hybrid --json";
+const MCP_COMMAND = ["codex", "mcp", "add", "codetrap", "--", "codetrap", "serve"];
+const EMBEDDED_PLUGIN_ROOT = "embedded://plugins/codetrap-agent";
+const EMBEDDED_SKILLS = [
+  { name: "codetrap-add", skill: codetrapAddSkill },
+  { name: "codetrap-capture", skill: codetrapCaptureSkill },
+  { name: "codetrap-capture-external", skill: codetrapCaptureExternalSkill },
+  { name: "codetrap-check", skill: codetrapCheckSkill },
+  { name: "codetrap-search", skill: codetrapSearchSkill },
+];
+
+export function runCodexSetup(options: CodexSetupOptions): CodexSetupResult {
+  const cwd = resolve(options.cwd);
+  const projectRoot = findProjectRoot(cwd) ?? cwd;
+  const codexHome = resolveCodexHome(options.codexHome);
+  const pluginRoot = bundledPluginRoot();
+  const useEmbeddedAssets = !existsSync(pluginRoot);
+
+  const dryRun = options.dryRun === true;
+  const project = ensureProjectCodetrap(projectRoot, dryRun);
+  const skills = useEmbeddedAssets
+    ? installEmbeddedSkills(codexHome, dryRun)
+    : installSkills(pluginRoot, codexHome, dryRun);
+  const agents = options.skipAgents
+    ? { path: null, status: "skipped" as const }
+    : installAgentsTemplate(projectRoot, useEmbeddedAssets ? null : pluginRoot, options.agentsFile ?? "AGENTS.md", dryRun);
+  const mcp = setupMcp(options.installMcp === true, dryRun);
+  const success = mcp.status !== "failed";
+
+  return {
+    success,
+    project_root: projectRoot,
+    codex_home: codexHome,
+    plugin_root: useEmbeddedAssets ? EMBEDDED_PLUGIN_ROOT : pluginRoot,
+    dry_run: dryRun,
+    project,
+    skills,
+    agents,
+    mcp,
+  };
+}
+
+export function formatCodexSetupText(result: CodexSetupResult): string {
+  const installed = result.skills.filter((skill) =>
+    ["installed", "updated", "would_install", "would_update"].includes(skill.status)
+  ).length;
+  const unchanged = result.skills.filter((skill) => skill.status === "unchanged").length;
+  const lines = [
+    result.success ? "Codex setup complete." : "Codex setup completed with errors.",
+    `Project: ${result.project.status} (${result.project.codetrap_dir})`,
+    `Skills: ${installed} changed, ${unchanged} unchanged (${join(result.codex_home, "skills")})`,
+    `AGENTS: ${result.agents.status}${result.agents.path ? ` (${result.agents.path})` : ""}`,
+  ];
+  if (result.mcp.requested) {
+    lines.push(`MCP: ${result.mcp.status} (${result.mcp.command})`);
+    if (result.mcp.error) lines.push(`MCP error: ${result.mcp.error}`);
+  } else {
+    lines.push(`MCP: skipped; pass --mcp to run '${result.mcp.command}'.`);
+  }
+  if (result.dry_run) lines.unshift("Dry run; no files or Codex config were changed.");
+  return lines.join("\n");
+}
+
+function ensureProjectCodetrap(projectRoot: string, dryRun: boolean): CodexSetupResult["project"] {
+  const codetrapDir = join(projectRoot, ".codetrap");
+  if (existsSync(codetrapDir)) {
+    return { codetrap_dir: codetrapDir, status: "already_present" };
+  }
+  if (!dryRun) mkdirSync(codetrapDir, { recursive: true });
+  return { codetrap_dir: codetrapDir, status: dryRun ? "would_create" : "created" };
+}
+
+function installSkills(pluginRoot: string, codexHome: string, dryRun: boolean): CodexSetupResult["skills"] {
+  const sourceSkillsDir = join(pluginRoot, "skills");
+  const targetSkillsDir = join(codexHome, "skills");
+  if (!dryRun) mkdirSync(targetSkillsDir, { recursive: true });
+
+  return readdirSync(sourceSkillsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .sort((left, right) => left.name.localeCompare(right.name))
+    .map((entry) => {
+      const source = join(sourceSkillsDir, entry.name);
+      const destination = join(targetSkillsDir, entry.name);
+      const sourceSkill = readFileSync(join(source, "SKILL.md"), "utf-8");
+      const destinationSkillPath = join(destination, "SKILL.md");
+      const exists = existsSync(destinationSkillPath);
+      const unchanged = exists && readFileSync(destinationSkillPath, "utf-8") === sourceSkill;
+      let status: CodexSetupStatus = unchanged ? "unchanged" : exists ? "updated" : "installed";
+      if (dryRun && status === "installed") status = "would_install";
+      if (dryRun && status === "updated") status = "would_update";
+      if (!dryRun && !unchanged) cpSync(source, destination, { recursive: true, force: true });
+      return { name: entry.name, source, destination, status };
+    });
+}
+
+function installEmbeddedSkills(codexHome: string, dryRun: boolean): CodexSetupResult["skills"] {
+  const targetSkillsDir = join(codexHome, "skills");
+  if (!dryRun) mkdirSync(targetSkillsDir, { recursive: true });
+
+  return EMBEDDED_SKILLS.map((entry) => {
+    const destination = join(targetSkillsDir, entry.name);
+    const destinationSkillPath = join(destination, "SKILL.md");
+    const exists = existsSync(destinationSkillPath);
+    const unchanged = exists && readFileSync(destinationSkillPath, "utf-8") === entry.skill;
+    let status: CodexSetupStatus = unchanged ? "unchanged" : exists ? "updated" : "installed";
+    if (dryRun && status === "installed") status = "would_install";
+    if (dryRun && status === "updated") status = "would_update";
+    if (!dryRun && !unchanged) {
+      mkdirSync(destination, { recursive: true });
+      writeFileSync(destinationSkillPath, entry.skill);
+    }
+    return {
+      name: entry.name,
+      source: `${EMBEDDED_PLUGIN_ROOT}/skills/${entry.name}`,
+      destination,
+      status,
+    };
+  });
+}
+
+function installAgentsTemplate(
+  projectRoot: string,
+  pluginRoot: string | null,
+  agentsFile: string,
+  dryRun: boolean
+): CodexSetupResult["agents"] {
+  const target = resolve(projectRoot, agentsFile);
+  const template = (pluginRoot
+    ? readFileSync(join(pluginRoot, AGENTS_TEMPLATE_PATH), "utf-8")
+    : agentsTemplateAsset
+  ).trimEnd();
+  if (existsSync(target)) {
+    const current = readFileSync(target, "utf-8");
+    if (current.includes(CODEX_MARKER)) {
+      return { path: target, status: "already_present" };
+    }
+    if (!dryRun) appendFileSync(target, `${current.endsWith("\n") ? "\n" : "\n\n"}${template}\n`);
+    return { path: target, status: dryRun ? "would_append" : "appended" };
+  }
+  if (!dryRun) writeFileSync(target, `${template}\n`);
+  return { path: target, status: dryRun ? "would_create" : "created" };
+}
+
+function setupMcp(requested: boolean, dryRun: boolean): CodexSetupResult["mcp"] {
+  const command = MCP_COMMAND.join(" ");
+  if (!requested) return { requested, command, status: "skipped" };
+  if (dryRun) return { requested, command, status: "would_run" };
+
+  const result = Bun.spawnSync({
+    cmd: MCP_COMMAND,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (result.success) return { requested, command, status: "installed", exit_code: result.exitCode };
+
+  const stderr = new TextDecoder().decode(result.stderr).trim();
+  const stdout = new TextDecoder().decode(result.stdout).trim();
+  return {
+    requested,
+    command,
+    status: "failed",
+    exit_code: result.exitCode,
+    error: stderr || stdout || "codex mcp add failed",
+  };
+}
+
+function resolveCodexHome(codexHome?: string): string {
+  return resolve(codexHome ?? process.env.CODEX_HOME ?? join(process.env.HOME ?? process.env.USERPROFILE ?? homedir(), ".codex"));
+}
+
+function bundledPluginRoot(): string {
+  return join(dirname(dirname(dirname(fileURLToPath(import.meta.url)))), "plugins", "codetrap-agent");
+}