fapony 0.1.3 → 0.2.1

package/src/init-mem.ts

@@ -1,14 +1,19 @@
-// src/init-mem.ts — scaffold the canonical .memory/ system into a new worktree.
-// Source of truth lives in fapony/templates/mem/ — named after the CLI it implements
-// (`mem`), not after where it lands; the destination keeps the .memory name because that
-// is where the log lives.
-// Destination is <worktree>/.fapony/.memory/ (plans/specs/memory all live under
-// .fapony/; run state stays in ~/.config/fapony/state.db, never in the worktree).
-// Re-run to re-sync after editing the template — not automatic, on purpose.
+// src/init-mem.ts — cleanup old .memory/ directories and warn about stale call sites.
+//
+// Before PLAN-agent-one-call, this file scaffolded templates/mem/ into every repo.
+// Now fapony owns the mem code (src/mem/) and calls it directly via `fapony mem`.
+// This command's new job: delete legacy .memory/ dirs + warn about package.json refs.
 
-import { copyFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { loadConfig, memoryEntry } from "./db/index.js";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { join } from "node:path";
+import { DEFAULT_MEM_DIR, FAPONY_DIR, loadConfig } from "./db/index.js";
 
 export function copyDir(src: string, dest: string): string[] {
   mkdirSync(dest, { recursive: true });
@@ -27,13 +32,11 @@ export function copyDir(src: string, dest: string): string[] {
 }
 
 export function cmdInitMem(args: string[]): void {
-  const update = args.includes("--update");
+  const force = args.includes("--force");
   const worktreeKey = args.find((x) => !x.startsWith("-"));
   const config = loadConfig();
 
-  // no key given = the repo you are standing in — so `fapony init-mem --update` runs in anyone's project
-  // without registering the worktree first (loadConfig already reads the cwd's fapony.config.json,
-  // so it picks up that project's paths.memoryEntry by itself)
+  // no key given = the repo you are standing in
   const worktree = worktreeKey ? config.worktrees[worktreeKey] : process.cwd();
   if (!worktree) {
     console.error(`unknown worktree key: ${worktreeKey}`);
@@ -41,31 +44,114 @@ export function cmdInitMem(args: string[]): void {
     process.exit(1);
   }
 
-  const templateDir = join(import.meta.dir, "..", "templates", "mem");
-  const memEntry = memoryEntry(config);
-  const destDir = join(worktree, dirname(memEntry));
-  const destFile = join(worktree, memEntry);
+  const gitRoot = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
+    cwd: worktree,
+  })
+    .stdout.toString()
+    .trim();
+  const root = gitRoot || worktree;
 
-  if (existsSync(destFile) && !update) {
-    console.error(
-      `${destFile} already exists — re-running would overwrite local edits.\nRun \`fapony init-mem --update\` to refresh it from the template (log.jsonl is kept).`,
+  // 1) Find and delete .memory/ directories (legacy layout)
+  const memoryDirs: string[] = [];
+  const walk = (dir: string, depth = 0) => {
+    if (depth > 4) return;
+    if (existsSync(`${dir}/.memory`)) {
+      memoryDirs.push(`${dir}/.memory`);
+    }
+    try {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (
+          entry.isDirectory() &&
+          entry.name !== "node_modules" &&
+          (!entry.name.startsWith(".") || entry.name === FAPONY_DIR)
+        ) {
+          walk(join(dir, entry.name), depth + 1);
+        }
+      }
+    } catch {
+      // ignore
+    }
+  };
+  walk(root);
+
+  if (memoryDirs.length === 0) {
+    console.log("no legacy .memory/ directories found — already clean");
+  } else {
+    let removed = 0;
+    let kept = 0;
+    for (const d of memoryDirs) {
+      // Any log*.jsonl is history — includes log.<person>.jsonl (the standard
+      // filename) and rotated log.YYYY-MM-DD.jsonl, not just log.jsonl.
+      let logs: string[] = [];
+      try {
+        logs = readdirSync(d).filter(
+          (f) => f === "log.jsonl" || /^log\..*\.jsonl$/.test(f),
+        );
+      } catch {
+        // unreadable dir — fall through and remove
+      }
+      if (logs.length > 0 && !force) {
+        console.log(
+          `keeping ${d} — has ${logs.length} log file(s): ${logs.join(", ")}`,
+        );
+        console.log(
+          `  move them under ${DEFAULT_MEM_DIR}/, or re-run with --force to delete`,
+        );
+        kept++;
+        continue;
+      }
+      console.log(
+        `deleting ${d}${logs.length > 0 ? ` (--force: ${logs.length} log file(s))` : ""}`,
+      );
+      rmSync(d, { recursive: true, force: true });
+      removed++;
+    }
+    console.log(
+      `\nremoved ${removed} legacy .memory/ director${removed === 1 ? "y" : "ies"}${
+        kept > 0
+          ? ` · kept ${kept} with logs — move them under ${DEFAULT_MEM_DIR}/, then re-run`
+          : ""
+      }`,
     );
-    process.exit(1);
-  }
-  if (update && !existsSync(destFile)) {
-    console.error(`${destFile} not found — run \`fapony init\` first.`);
-    process.exit(1);
   }
 
-  const files = copyDir(templateDir, destDir);
-  if (update) {
-    console.log(`updated ${files.length} files in ${destDir}`);
-    console.log(`(log.jsonl and other data files left untouched)`);
-    return;
-  }
-  console.log(`scaffolded ${files.length} files into ${destDir}`);
-  console.log(`\nAdd to fapony.config.json:`);
-  console.log(
-    `  "memory": {\n    "claim": ["bun", "${memEntry}", "claim", "{id}"],\n    "close": ["bun", "${memEntry}", "close", "{id}", "{msg}"],\n    "add":   ["bun", "${memEntry}", "add", "{kind}", "{text}"],\n    "kickoff": ["bun", "${memEntry}", "kickoff"]\n  }`,
-  );
+  // 2) Warn about package.json call sites still referencing .memory/mem.ts
+  const warnAboutCallSites = (dir: string, depth = 0) => {
+    if (depth > 4) return;
+    const pkg = join(dir, "package.json");
+    if (existsSync(pkg)) {
+      try {
+        const raw = readFileSync(pkg, "utf8");
+        if (raw.includes(".memory/mem.ts")) {
+          console.log(`\n⚠ ${pkg} still references .memory/mem.ts`);
+          console.log(
+            `  update to: "fapony mem <sub>" (e.g. "fapony mem add", "fapony mem close")`,
+          );
+        }
+      } catch {
+        // ignore
+      }
+    }
+    try {
+      for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (
+          entry.isDirectory() &&
+          !entry.name.startsWith(".") &&
+          entry.name !== "node_modules"
+        ) {
+          warnAboutCallSites(join(dir, entry.name), depth + 1);
+        }
+      }
+    } catch {
+      // ignore
+    }
+  };
+  warnAboutCallSites(root);
+
+  console.log("\nmem commands are now built into fapony:");
+  console.log('  fapony mem add <kind> "<text>" --files <files>');
+  console.log('  fapony mem close <id> "<text>"');
+  console.log("  fapony mem find <word>");
+  console.log("  fapony mem kickoff [id|spec.md]");
+  console.log("  fapony mem now");
 }

package/src/init.ts

@@ -3,7 +3,13 @@
 // state.db stays in ~/.config/fapony/ by design (security boundary — see db.ts),
 // never inside the worktree where agents have full write access.
 
-import { appendFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, join, relative } from "node:path";
 import { createInterface } from "node:readline";
 import { seedConventionsFile } from "./conventions-seed.js";
@@ -11,11 +17,11 @@ import {
   type Config,
   doneDir,
   evidenceFile,
-  memoryEntry,
+  FAPONY_DIR,
+  memoryDir,
   planDir,
   specDir,
 } from "./db/index.js";
-import { copyDir } from "./init-mem.js";
 import { isAffirmative } from "./util.js";
 
 const FAPONY_README = `# .fapony/ — fapony project dir (plans, specs, memory)
@@ -37,7 +43,7 @@ const FAPONY_README = `# .fapony/ — fapony project dir (plans, specs, memory)
 # running in this worktree cannot rewrite run state / audit trail.
 #
 # Ask your agent for the plan picture instead of listing these by hand:
-#   "run plan_list" — what is active, blocked, untouched, archived
+#   run "fapony mem kickoff" — priority plans, the first unchecked chunk, open bugs
 `;
 
 // Static template — deliberately NOT derived from the repo (reading package.json
@@ -59,22 +65,22 @@ const EVIDENCE_JSON = `{
 // Not in SERVER_INSTRUCTIONS either: that reaches every MCP session of every user,
 // and most of them never ran `fapony init` — it would tell them to run a command
 // that does not exist.
-const RULES_SNIPPET = (
-  memEntry: string,
-) => `## Memory: ${dirname(memEntry)}/log.<you>.jsonl (append-only)
+const RULES_SNIPPET =
+  () => `## Memory: .fapony/.memory/log.<you>.jsonl (append-only)
 
 The log is this project's shared brain — it lives in git, so anyone who clones the
 repo gets every decision, bug and note with it. The filename comes from
-\`git config user.name\`, one file per person, so there is nothing to merge.
+\`git config user.name\` — one file per person, and \`*.jsonl merge=union\` in
+.gitattributes keeps both sides when two people end up sharing a name anyway.
 
 Log as you work — do not wait to be asked. Nothing writes it for you:
 
-    bun ${memEntry} kickoff <plan.md>      # start a session with this
-    bun ${memEntry} add decision "what was locked, and why" --files src/x.ts
-    bun ${memEntry} add bug "what is broken" --files src/x.ts
-    bun ${memEntry} add note "state the next session needs" --files src/x.ts
-    bun ${memEntry} close <id> "fixed in <sha>"
-    bun ${memEntry} find "<text>"
+    fapony mem kickoff <plan.md>      # start a session with this
+    fapony mem add decision "what was locked, and why" --files src/x.ts
+    fapony mem add bug "what is broken" --files src/x.ts
+    fapony mem add note "state the next session needs" --files src/x.ts
+    fapony mem close <id> "fixed in <sha>"
+    fapony mem find "<text>"
 
 Write each entry standalone — it is read months later with no chat to refer to.
 --files is required: rows that name no file cannot be recalled when that file is
@@ -90,20 +96,20 @@ Finish a chunk, before starting the next:
 1. Tick its checkbox + stamp the TL;DR in the plan file
 2. Commit — separate from other chunks
 3. \`verdict_submit\` (fapony MCP), grading what actually happened
-4. \`bun ${memEntry} add note "what the next chunk needs" --files f1,f2 <path/to/PLAN-x.md>\`
-   — pass the exact same plan path every time; kickoff matches it as a literal string
+4. \`fapony mem add note "what the next chunk needs" --files f1,f2 <path/to/PLAN-x.md>\`
+   — use the same plan path every time
 5. Stop. Do not continue to the next chunk in the same session unless told to.
 
-Next chunk, new session — open with \`bun ${memEntry} kickoff <path/to/PLAN-x.md>\` (same
-path) instead of carrying the old transcript forward. kickoff already filters to the
-rows written against that exact path.`;
+Next chunk, new session — open with \`fapony mem kickoff <path/to/PLAN-x.md>\` instead
+of carrying the old transcript forward. kickoff already filters to the rows for that plan,
+and takes just the filename (\`kickoff PLAN-x.md\`) when you do not want to type the path.`;
 
 export function initProject(targetPath: string, config?: Config): void {
   // Create target root
   mkdirSync(targetPath, { recursive: true });
 
   // --- .fapony/ marker ---
-  const faponyDir = join(targetPath, ".fapony");
+  const faponyDir = join(targetPath, FAPONY_DIR);
   if (existsSync(faponyDir)) {
     throw new Error(
       `${faponyDir} already exists — delete it first if you want a fresh scaffold.`,
@@ -112,6 +118,22 @@ export function initProject(targetPath: string, config?: Config): void {
   mkdirSync(faponyDir, { recursive: true });
   writeFileSync(join(faponyDir, "README"), FAPONY_README);
 
+  // --- .gitattributes: union-merge the append-only logs ---
+  //
+  // Every row is one person's append, so both sides of a "conflict" are always
+  // right. Without the line, two people whose git user.name collides (admin /
+  // user / owner — what a fresh OS install offers) resolve a conflict by hand
+  // on every pull. Appended, never rewritten: the file is the repo's, not ours.
+  const attrs = join(targetPath, ".gitattributes");
+  const attrsBody = existsSync(attrs) ? readFileSync(attrs, "utf-8") : "";
+  if (!/^\s*\*\.jsonl\s+merge=union\s*$/m.test(attrsBody)) {
+    appendFileSync(
+      attrs,
+      `${attrsBody && !attrsBody.endsWith("\n") ? "\n" : ""}# append-only memory logs: keep both sides, never hand-resolve\n*.jsonl merge=union\n`,
+    );
+    console.log(`  + ${attrs} — *.jsonl merge=union`);
+  }
+
   // --- evidence.json (verification_report allowlist — see src/mcp/evidence.ts) ---
   const evidencePath = join(targetPath, evidenceFile(config));
   if (existsSync(evidencePath)) {
@@ -121,7 +143,7 @@ export function initProject(targetPath: string, config?: Config): void {
   writeFileSync(evidencePath, EVIDENCE_JSON);
 
   // --- plan/ spec/ .memory/ — all under .fapony/ ---
-  const planDirAbs = join(targetPath, planDir(config));
+  const planDirAbs = join(targetPath, planDir());
   if (existsSync(planDirAbs)) {
     throw new Error(`${planDirAbs} already exists — not overwriting.`);
   }
@@ -135,44 +157,41 @@ export function initProject(targetPath: string, config?: Config): void {
   mkdirSync(doneDirAbs, { recursive: true });
 
   // --- spec/ ---
-  const specDirAbs = join(targetPath, specDir(config));
+  const specDirAbs = join(targetPath, specDir());
   if (existsSync(specDirAbs)) {
     throw new Error(`${specDirAbs} already exists — not overwriting.`);
   }
   mkdirSync(specDirAbs, { recursive: true });
 
-  // --- .memory/ (from template) ---
-  const memEntry = memoryEntry(config); // e.g. .fapony/.memory/mem.ts
-  const memoryDir = join(
-    targetPath,
-    memEntry.split("/").slice(0, -1).join("/"),
-  );
-  if (existsSync(join(targetPath, memEntry))) {
-    throw new Error(
-      `${join(targetPath, memEntry)} already exists — delete it first if you want a fresh copy.`,
+  // --- .fapony/.memory/ (empty dir — mem commands are built into fapony now) ---
+  const memoryDirPath = join(targetPath, memoryDir(config));
+  if (existsSync(memoryDirPath)) {
+    console.log(`  ${relative(targetPath, memoryDirPath)}/ — already exists`);
+  } else {
+    mkdirSync(memoryDirPath, { recursive: true });
+    console.log(
+      `  ${relative(targetPath, memoryDirPath)}/ — mem commands are built into fapony (fapony mem ...)`,
     );
   }
-  const templateDir = join(import.meta.dir, "..", "templates", "mem");
-  const files = copyDir(templateDir, memoryDir);
 
   console.log(`scaffolded ${targetPath}/`);
   console.log(
     `  .fapony/         — project dir (plans, specs, memory, evidence)`,
   );
-  console.log(`  ${planDir(config)}/    — live plan files`);
+  console.log(`  ${planDir()}/    — live plan files`);
   console.log(`  ${doneDir(config)}/    — shipped plans (archive)`);
-  console.log(`  ${specDir(config)}/    — spec files`);
+  console.log(`  ${specDir()}/    — spec files`);
   console.log(
     `  ${evidenceFile(config)}    — allowlist for 'fapony report' (edit the cmds!)`,
   );
   console.log(
-    `  ${relative(targetPath, memoryDir)}/ — ${files.length} files from template`,
+    `  ${relative(targetPath, memoryDirPath)}/ — mem commands are built into fapony (fapony mem ...)`,
   );
   console.log(`\nNext: add "${targetPath}" to fapony.config.json worktrees`);
   console.log(
     `\nThen paste this into your agent-rules file (CLAUDE.md / AGENTS.md / opencode.json\ninstructions) — the memory log only fills up if the rules your agent already reads\ntell it to write:\n`,
   );
-  console.log(RULES_SNIPPET(memEntry));
+  console.log(RULES_SNIPPET());
 }
 
 const AGENT_RULE_FILES = ["CLAUDE.md", "AGENTS.md"];
@@ -228,8 +247,7 @@ export async function cmdInit(args: string[]): Promise<void> {
   );
   if (!isAffirmative(answer)) return;
 
-  const memEntry = memoryEntry();
-  const snippet = `\n\n${RULES_SNIPPET(memEntry)}\n`;
+  const snippet = `\n\n${RULES_SNIPPET()}\n`;
   for (const f of found) {
     appendFileSync(f, snippet);
     console.log(`  appended to ${relative(targetPath, f)}`);

package/src/install/claude.ts

@@ -105,6 +105,10 @@ export function cmdInstallClaude(
       console.error(`  (Claude Code user scope)`);
       const dir = claudeSkillsDir(deps.homedir ?? homedir);
       reportSkills(linkSkills(dir, dryRun), dir, dryRun);
+      // MCP is already wired, but a hook can be new since the last install
+      // (e.g. the Edit hint) — always ensure the hook wiring, not only on a
+      // fresh MCP add. This is the upgrade path for existing installs.
+      installClaudeHooks(dryRun, deps);
       return;
     }
     console.error(
@@ -120,6 +124,9 @@ export function cmdInstallClaude(
   if (dryRun) {
     console.error(`── dry-run: would run ──`);
     console.error(`  ${addArgs.join(" ")}`);
+    // Dry-run shows the hook wiring too — the installers are dry-run-safe
+    // ("would write", no writes), so the preview stays truthful.
+    installClaudeHooks(dryRun, deps);
     return;
   }
 
@@ -148,9 +155,9 @@ export function cmdInstallClaude(
   installStatusline(dryRun, deps);
 
   // Wire the Stop hook that refuses to end a turn with ungraded commits,
-  // and the Read hint that annotates large-file reads (annotate-only).
-  installStopHook(dryRun, deps);
-  installReadHintHook(dryRun, deps);
+  // and the Read/Edit hints that annotate reads of large files and edits to
+  // files with importers (both annotate-only).
+  installClaudeHooks(dryRun, deps);
 }
 
 /**
@@ -336,6 +343,18 @@ function ensureClaudeHook(
   );
 }
 
+/**
+ * Wire every hook fapony owns: the Stop hook that refuses to end a turn with
+ * ungraded commits, and the Read/Edit PreToolUse hints (annotate-only).
+ * Idempotent and dry-run-safe. Called on every install, not just a fresh MCP
+ * add — an existing install must still pick up a hook added later.
+ */
+function installClaudeHooks(dryRun: boolean, deps: InstallDeps): void {
+  installStopHook(dryRun, deps);
+  installReadHintHook(dryRun, deps);
+  installEditHintHook(dryRun, deps);
+}
+
 function installStopHook(dryRun: boolean, deps: InstallDeps): void {
   ensureClaudeHook(dryRun, deps, {
     event: "Stop",
@@ -345,11 +364,13 @@ function installStopHook(dryRun: boolean, deps: InstallDeps): void {
 }
 
 /**
- * PreToolUse hook on Read: annotates a full-file read of a large source file
- * with one factual line (size + the review-seed command). Annotate only —
- * no permissionDecision is ever returned, the read always proceeds; and no
- * "already read" dedupe (context compaction makes that claim false). The
- * matcher "Read" keeps the spawn off every other tool call.
+ * PreToolUse hook on Read: annotates a full-file read with one factual line —
+ * the size + the review-seed command when the file is large, and the re-read
+ * line when the same path was already read this session and its mtime has not
+ * moved (an unchanged file, so the second read buys nothing; a changed one
+ * stays silent). Annotate only — no permissionDecision is ever returned, the
+ * read always proceeds. The matcher "Read" keeps the spawn off every other
+ * tool call.
  */
 function installReadHintHook(dryRun: boolean, deps: InstallDeps): void {
   ensureClaudeHook(dryRun, deps, {
@@ -359,3 +380,18 @@ function installReadHintHook(dryRun: boolean, deps: InstallDeps): void {
     label: "read hint",
   });
 }
+
+/**
+ * PreToolUse hook on Edit: annotates an edit with the file's importer count
+ * plus the review-seed command that lists them, once per (session, file).
+ * Annotate only — no permissionDecision is ever returned, the edit always
+ * proceeds. The matcher "Edit" keeps the spawn off every other tool call.
+ */
+function installEditHintHook(dryRun: boolean, deps: InstallDeps): void {
+  ensureClaudeHook(dryRun, deps, {
+    event: "PreToolUse",
+    matcher: "Edit",
+    subcommand: "hook-edit-hint",
+    label: "edit hint",
+  });
+}

package/src/install/codex.ts

@@ -1,17 +1,30 @@
 // src/install/codex.ts — Codex install provider
 //
-// Reads/writes ~/.codex/config.toml directly. Codex has no CLI for MCP config.
+// Reads/writes ~/.codex/config.toml directly for MCP config.
+// Reads/writes ~/.codex/hooks.json for lifecycle hooks (Stop).
+// Symlinks skills into ~/.agents/skills/ (same dir as ZCode).
 
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { CODEX_MCP_ENTRY, defaultExit, type InstallDeps } from "./types.js";
+import { agentsSkillsDir, linkSkills, reportSkills } from "./skills.js";
+import {
+  CODEX_MCP_ENTRY,
+  defaultExit,
+  INSTALL_ROOT,
+  type InstallDeps,
+} from "./types.js";
 
 export function findCodexConfig(getHome: () => string): string | null {
   const p = join(getHome(), ".codex", "config.toml");
   return existsSync(p) ? p : null;
 }
 
+export function findCodexHooksJson(getHome: () => string): string | null {
+  const p = join(getHome(), ".codex", "hooks.json");
+  return existsSync(p) ? p : null;
+}
+
 function isCodexConfigured(content: string): boolean {
   // Check if [mcp_servers.fapony] section exists with our command
   const sectionRegex = /\[mcp_servers\.fapony\]/;
@@ -20,9 +33,86 @@ function isCodexConfigured(content: string): boolean {
   return content.includes("fapony.ts") && content.includes("mcp");
 }
 
+function readJsonObject(path: string): Record<string, unknown> | null {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Append the fapony Stop hook to ~/.codex/hooks.json.
+ * Never replaces other hook groups or foreign entries within the Stop group.
+ * Fapony-owned entry is identified by the command string containing "hook-stop".
+ */
+function installStopHook(dryRun: boolean, getHome: () => string): void {
+  const hooksPath = join(getHome(), ".codex", "hooks.json");
+  let config: Record<string, unknown> = {};
+  if (existsSync(hooksPath)) {
+    const parsed = readJsonObject(hooksPath);
+    if (!parsed) {
+      console.error(
+        `  stop hook: ${hooksPath} is unreadable or malformed — skipping`,
+      );
+      return;
+    }
+    config = parsed;
+  }
+
+  const hookMap = config.hooks;
+  if (
+    hookMap !== undefined &&
+    (typeof hookMap !== "object" || Array.isArray(hookMap))
+  ) {
+    console.error(
+      `  stop hook: ${hooksPath} has an unexpected "hooks" shape — skipping`,
+    );
+    return;
+  }
+
+  const map = (hookMap ?? {}) as Record<string, unknown>;
+  // Codex Stop array: each element is { matcher?, hooks: [...] }
+  const stop = Array.isArray(map.Stop) ? (map.Stop as unknown[]) : [];
+
+  // Check if fapony stop hook already present (by command string)
+  const serialized = JSON.stringify(stop);
+  if (serialized.includes("hook-stop")) {
+    console.error(`  stop hook: already configured in hooks.json — no change`);
+    return;
+  }
+
+  const command = `bun ${join(INSTALL_ROOT, "fapony.ts")} hook-stop`;
+  const faponyEntry = { hooks: [{ type: "command", command }] };
+  const after = {
+    ...config,
+    hooks: { ...map, Stop: [...stop, faponyEntry] },
+  };
+
+  if (!dryRun) {
+    try {
+      writeFileSync(hooksPath, `${JSON.stringify(after, null, 2)}\n`, "utf-8");
+    } catch (e) {
+      console.error(`  stop hook: failed to write — ${(e as Error).message}`);
+      return;
+    }
+  }
+  console.error(
+    `  stop hook: ${dryRun ? "would write" : "wrote"} hooks.Stop → ${hooksPath}`,
+  );
+  console.error(
+    `    review and trust via Codex /hooks before the hook will run`,
+  );
+}
+
 export function cmdInstallCodex(dryRun: boolean, deps: InstallDeps = {}): void {
   const exitFn = deps.exit ?? defaultExit;
-  const configPath = findCodexConfig(deps.homedir ?? homedir);
+  const getHome = deps.homedir ?? homedir;
+  const configPath = findCodexConfig(getHome);
 
   if (!configPath) {
     console.error(
@@ -44,18 +134,20 @@ export function cmdInstallCodex(dryRun: boolean, deps: InstallDeps = {}): void {
   if (isCodexConfigured(content)) {
     console.error(`✓ mcp_servers.fapony already configured — no change needed`);
     console.error(`  (${configPath})`);
-    return;
-  }
-
-  if (dryRun) {
+  } else if (dryRun) {
     console.error(`── dry-run: would append to ${configPath} ──`);
     console.log(CODEX_MCP_ENTRY);
-    return;
+  } else {
+    const newContent = `${content.trimEnd()}\n\n${CODEX_MCP_ENTRY}`;
+    writeFileSync(configPath, newContent);
+    console.error(`✓ added mcp_servers.fapony to ${configPath}`);
+    console.error(`  restart Codex to load the MCP server`);
   }
 
-  // Append the fapony MCP server entry to the end of the config file
-  const newContent = `${content.trimEnd()}\n\n${CODEX_MCP_ENTRY}`;
-  writeFileSync(configPath, newContent);
-  console.error(`✓ added mcp_servers.fapony to ${configPath}`);
-  console.error(`  restart Codex to load the MCP server`);
+  // --- Stop hook (~/.codex/hooks.json) ---
+  installStopHook(dryRun, getHome);
+
+  // --- Skills (~/.agents/skills/) ---
+  const skillsDir = agentsSkillsDir(getHome);
+  reportSkills(linkSkills(skillsDir, dryRun), skillsDir, dryRun);
 }