ultra11y 2.26.0 → 2.28.0

package/src/cli.ts

@@ -32,7 +32,9 @@ import { runScanLocal, runScanManyLocal, runCrawlScanLocal, runSampleScanLocal,
 import { validateSample, lintSample, kindLabel } from "./sample.js";
 import { runFix, fixSummary } from "./fix.js";
 import { diffAgainstBaseline, baselineSummary, parseFailOn, findingsAtOrAbove } from "./baseline.js";
-import { repoRoot, writeHook, writeCi } from "./init.js";
+import { repoRoot, resolveEnginePath, writeHook, writeCi } from "./init.js";
+import { installForTargets, parseTargets, statusReport, uninstallForTargets } from "./install/index.js";
+import { agentsMdBlock } from "./install/agents-md.js";
 import { auditSummary, captureCoverageSummary } from "./output.js";
 import { toSarif } from "./sarif.js";
 import { annotations, stepSummary } from "./annotate.js";
@@ -82,7 +84,10 @@ Usage:
   ultra11y snapshot list  [--root <dir>] [--json]
   ultra11y pages    --in <audit.json> [--standard <pack>] [--json] [--lang auto|en|fr]   (the per-page criterion grid)
   ultra11y mcp      [--transport stdio|http] [--cwd <dir>] [--allow-write] [--port <n>] [--bind <addr>] [--allow-remote] [--allow-origin <o>] [--max-response-bytes <n>]
-  ultra11y hook     --claude-code                (internal: the plugin's PreToolUse hook; payload on stdin)
+  ultra11y hook     --claude-code|--codex|--opencode   (internal: the PreToolUse hook; payload on stdin)
+  ultra11y install   --claude-code | --codex | --opencode | --agents-md | --all  [--project] [--dry-run] [--no-skills]
+  ultra11y uninstall --claude-code | --codex | --opencode | --agents-md | --all  [--project]
+  ultra11y status   [--json] [--project]        (doctor: which agents will run the review by themselves)
   ultra11y dev      [--port <n>] [--root <dir>] [--standard <pack>] [--lang auto|en|fr]   (dev side-car: live overlay + per-page dashboard)
   ultra11y dev      --next [--port <n>]        (write the Next overlay component, then wire one line into your layout)
 
@@ -386,6 +391,9 @@ const COMMANDS = [
   "pack",
   "orchestrate",
   "hook",
+  "install",
+  "uninstall",
+  "status",
 ] as const;
 type Command = (typeof COMMANDS)[number];
 
@@ -494,6 +502,15 @@ const BOOLEAN_FLAGS = new Set([
   "version",
   "allow-remote",
   "allow-write",
+  // Harness selectors, shared by `hook` and `install`/`uninstall`/`status`. Without these
+  // the parser warned "unknown flag --claude-code" on stderr on EVERY guarded shell call.
+  "claude-code",
+  "codex",
+  "opencode",
+  "agents-md",
+  "all",
+  "project",
+  "no-skills",
 ]);
 const KNOWN_FLAGS: ReadonlySet<string> = new Set<string>([...VALUE_FLAGS, ...BOOLEAN_FLAGS]);
 // Long flags whose repetition should accumulate (comma-joined) rather than last-wins,
@@ -1053,13 +1070,7 @@ async function cmdSnapshot(p: ParsedArgs): Promise<number> {
 
 function cmdInit(p: ParsedArgs): number {
   const root = repoRoot() ?? process.cwd();
-  let engineRel = process.argv[1] ?? "scripts/ultra11y.mjs";
-  try {
-    const abs = realpathSync(engineRel);
-    engineRel = abs.startsWith(root + sep) ? relative(root, abs) : abs;
-  } catch {
-    /* keep as-is */
-  }
+  const engineRel = resolveEnginePath(root);
   const failOnParsed = parseFailOn(p.flags["fail-on"]);
   if (p.flags["fail-on"] !== undefined && failOnParsed === null) {
     console.error(`ultra11y init: --fail-on must be blocking|major|minor (got "${String(p.flags["fail-on"])}").`);
@@ -1089,25 +1100,107 @@ function cmdInit(p: ParsedArgs): number {
   return 0;
 }
 
-/** `hook --claude-code` — the decision half of the plugin's PreToolUse hook. Reads the
- *  payload on stdin, prints the hook JSON when the pending commit/push/PR should get an
- *  accessibility review first, and prints NOTHING otherwise. Not meant to be run by hand:
- *  `hooks/pre-tool-use.mjs` is what Claude Code calls, and it only reaches here once its
- *  cheap prefilter has passed. Always exits 0 — see src/hook.ts for why. */
+/** `hook --claude-code|--codex|--opencode` — the decision half of the PreToolUse hook.
+ *  Reads the payload on stdin, emits when the pending commit/push/PR should get an
+ *  accessibility review first, and emits NOTHING otherwise. Not meant to be run by hand:
+ *  `hooks/pre-tool-use.mjs` (Claude Code, Codex) and `.opencode/plugins/ultra11y.js`
+ *  (OpenCode) are what call it, and only once their cheap prefilter has passed. Always
+ *  exits 0 — see src/hook.ts for why.
+ *
+ *  Two output shapes:
+ *  - `--claude-code` / `--codex`: the `hookSpecificOutput` JSON envelope. Codex's PreToolUse
+ *    is a clone of Claude Code's and accepts exactly the one decision this emits (`deny`),
+ *    so the two are the same code path today. The flag is kept distinct anyway: it gives
+ *    `status` a marker to grep for, and it is where the branch goes the day they diverge.
+ *  - `--opencode`: plain text. OpenCode has no permission-decision channel — its plugin
+ *    blocks by throwing, with the message shown to the agent — so the message is assembled
+ *    here, in typed code, rather than in a committed .js file no type-checker covers. */
 async function cmdHook(p: ParsedArgs): Promise<number> {
-  if (p.flags["claude-code"] !== true) {
-    console.error("ultra11y hook: expected `hook --claude-code` (the payload is read on stdin).");
+  const opencode = p.flags.opencode === true;
+  if (!opencode && p.flags["claude-code"] !== true && p.flags.codex !== true) {
+    console.error("ultra11y hook: expected `hook --claude-code`, `--codex` or `--opencode` (the payload is read on stdin).");
     return 2;
   }
   try {
     const decision = decide(JSON.parse(await readStdin()) as PreToolUsePayload);
-    if (decision) process.stdout.write(JSON.stringify(decision));
+    if (!decision) return 0;
+    const out = decision.hookSpecificOutput;
+    process.stdout.write(opencode ? `${out.permissionDecisionReason}\n\n${out.additionalContext}` : JSON.stringify(decision));
   } catch {
     /* unreadable payload, engine failure — stay silent rather than break a git flow */
   }
   return 0;
 }
 
+const TARGET_FLAGS = "--claude-code | --codex | --opencode | --agents-md | --all";
+
+/** `install --<harness>` — wire the automatic review into an agent on this machine.
+ *
+ *  The native route is better where it exists (`/plugin install` on Claude Code,
+ *  `codex plugin add` on Codex): a plugin carries the skills and the hook together and
+ *  updates as one thing. This exists for what a plugin cannot do — wiring the gate for an
+ *  npm install, and the AGENTS.md fallback on harnesses with no plugin system at all. */
+function cmdInstall(p: ParsedArgs): number {
+  const targets = parseTargets(p.flags);
+  if (!targets) {
+    console.error(`ultra11y install: pick at least one target: ${TARGET_FLAGS}`);
+    console.error("  --all covers the agent harnesses; --agents-md is separate because it writes a tracked file into your repository.");
+    return 2;
+  }
+  const dryRun = p.flags["dry-run"] === true;
+  // --dry-run on the AGENTS.md target prints the block itself: it is the one output a user
+  // may want to paste elsewhere (CLAUDE.md, GEMINI.md, .cursor/rules) by hand.
+  if (dryRun && targets.includes("agents-md")) {
+    console.log(agentsMdBlock(repoRoot() ?? process.cwd()));
+    if (targets.length === 1) return 0;
+  }
+  const results = installForTargets({ targets, project: p.flags.project === true, dryRun, skills: p.flags["no-skills"] !== true });
+  return reportInstall(results, dryRun ? "would wire" : "wired");
+}
+
+function cmdUninstall(p: ParsedArgs): number {
+  const targets = parseTargets(p.flags);
+  if (!targets) {
+    console.error(`ultra11y uninstall: pick at least one target: ${TARGET_FLAGS}`);
+    return 2;
+  }
+  return reportInstall(uninstallForTargets({ targets, project: p.flags.project === true }), "removed");
+}
+
+/** Shared printer. Exit 0 when every target succeeded, 1 when some did not — so a script
+ *  can tell "wired three of three" from "wired two and one is broken". */
+function reportInstall(results: ReturnType<typeof installForTargets>, verb: string): number {
+  let failed = 0;
+  for (const r of results) {
+    if (r.error) {
+      failed++;
+      console.error(`ultra11y: ${r.error}`);
+      continue;
+    }
+    const changed = r.reports.filter((x) => x.changed);
+    if (changed.length === 0) console.log(`ultra11y ${r.target}: already ${verb} (nothing to do)`);
+    for (const x of changed) console.log(`ultra11y ${r.target}: ${verb} ${x.path}${x.backup ? ` (backed up to ${x.backup})` : ""}`);
+    for (const g of r.guidance) console.log(`  ${g}`);
+  }
+  return failed ? 1 : 0;
+}
+
+/** `status` — the doctor. Answers "is the automatic review actually going to fire?", which
+ *  is otherwise invisible until a commit that should have been stopped goes through. */
+function cmdStatus(p: ParsedArgs): number {
+  const rows = statusReport({ project: p.flags.project === true });
+  if (p.flags.json === true) {
+    console.log(JSON.stringify({ version: VERSION, targets: rows }, null, 2));
+    return 0;
+  }
+  console.log(`ultra11y ${VERSION}`);
+  for (const r of rows) {
+    console.log(`  ${r.target.padEnd(12)} ${r.wired ? "wired    " : "not wired"}  ${r.path}`);
+    if (r.note) console.log(`  ${"".padEnd(12)} ${r.note}`);
+  }
+  return 0;
+}
+
 function cmdCriteria(p: ParsedArgs): number {
   // --generate: emit the bundled WCAG references/criteria.md (no trailing newline; the
   // shell redirect / committed file owns that). Used by `pnpm run build:criteria`.
@@ -2390,6 +2483,12 @@ export async function main(argv: string[]): Promise<number> {
       return cmdMcp(p);
     case "hook":
       return cmdHook(p);
+    case "install":
+      return cmdInstall(p);
+    case "uninstall":
+      return cmdUninstall(p);
+    case "status":
+      return cmdStatus(p);
     default:
       console.error(`ultra11y: "${p.command}" is not implemented yet`);
       return 1;

package/src/data/wcag-universe.json

@@ -2,7 +2,7 @@
   "wcagVersion": "2.2",
   "source": "https://www.w3.org/TR/WCAG22/",
   "criteriaSource": "https://github.com/w3c/wcag",
-  "provenance": "Full WCAG 2.x SC universe (all levels incl. AAA, and the removed 4.1.1 Parsing) fetched from raw.githubusercontent.com/w3c/wcag@main on 2026-07-31 via `node scripts/build-standards.mjs --refresh-universe`. Classification: core-AA = ships in src/data/wcag.json (the shipped WCAG 2.2 AA core); out-of-core = WCAG AAA; removed = obsolete (4.1.1).",
+  "provenance": "Full WCAG 2.x SC universe (all levels incl. AAA, and the removed 4.1.1 Parsing) fetched from raw.githubusercontent.com/w3c/wcag@main on 2026-08-01 via `node scripts/build-standards.mjs --refresh-universe`. Classification: core-AA = ships in src/data/wcag.json (the shipped WCAG 2.2 AA core); out-of-core = WCAG AAA; removed = obsolete (4.1.1).",
   "criteria": [
     {
       "id": "1.1.1",

package/src/init.ts

@@ -5,9 +5,9 @@
 // --write --safe`) and re-stages them, blocking only on issues that need judgment. The
 // legacy baseline regression gate (`audit --changed --baseline … --fail-on …`, blocking
 // only NEW findings) stays available via `init --baseline` and the CI workflow.
-import { writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { writeFileSync, mkdirSync, chmodSync, realpathSync } from "node:fs";
 import { execFileSync } from "node:child_process";
-import { join } from "node:path";
+import { join, relative, sep } from "node:path";
 import { VERSION, type Severity } from "./types.js";
 
 // English --fail-on token written into generated hooks/CI (the tool is English-first;
@@ -22,6 +22,30 @@ export function repoRoot(): string | null {
   }
 }
 
+/** Where the running engine lives, as a path to bake into a generated file. Relative to
+ *  `root` when the bundle sits inside it (so a committed git hook keeps working after a
+ *  clone), absolute otherwise. Callers that need a runnable COMMAND, not a path, should
+ *  use `engineInvocation`. */
+export function resolveEnginePath(root: string): string {
+  const argv1 = process.argv[1] ?? "scripts/ultra11y.mjs";
+  try {
+    const abs = realpathSync(argv1);
+    return abs.startsWith(root + sep) ? relative(root, abs) : abs;
+  } catch {
+    return argv1;
+  }
+}
+
+/** The command a human or an agent can paste to run the engine from `root`.
+ *  `node <relpath>` when the bundle is vendored in the repo (no install, no network),
+ *  `npx -y ultra11y` when it lives outside — where a bare path would break the moment the
+ *  reader is on another machine. Used by the AGENTS.md block, which is read by agents that
+ *  have no skill system and so cannot be handed a resolved path. */
+export function engineInvocation(root: string): string {
+  const p = resolveEnginePath(root);
+  return p.startsWith("/") || p.startsWith("..") ? "npx -y ultra11y" : `node ${p}`;
+}
+
 /** POSIX `sh` pre-commit hook (default, strict staged snapshot). Operates on EXACTLY the
  *  staged index blobs (what the commit records, not the working tree): first auto-applies
  *  SAFE deterministic fixes and re-stages them, then blocks the commit only if issues >=

package/src/install/agents-md.ts

@@ -0,0 +1,78 @@
+// The AGENTS.md fallback — for harnesses with no skill system AND no hook system
+// (Cursor, Amp, Zed, Gemini CLI, Windsurf, aider…).
+//
+// Be honest about what this is: it CANNOT make anything automatic. There is no channel to
+// deny a command on, so nothing stops a commit. What it can do is two things the agent
+// cannot do for itself — make the engine discoverable, and hand over the adjudication
+// protocol so the findings are ruled on instead of pasted at the user. The real enforcement
+// on such a harness is the repo's own git hook (`init --hook`), which is why the block
+// closes by saying so.
+//
+// The block is GENERATED rather than committed as a static .md so `--dry-run` and the
+// writer emit the same bytes, and so the engine invocation is resolved for the reader's
+// actual checkout rather than guessed.
+import type { EditReport } from "./json-edit.js";
+import { engineInvocation } from "../init.js";
+import { hasManagedBlock, removeManagedBlock, upsertManagedBlock } from "./text-edit.js";
+import { join } from "node:path";
+
+/** Where the block goes: the repository root, next to the agent instructions already there. */
+export function agentsMdPath(root: string): string {
+  return join(root, "AGENTS.md");
+}
+
+/** The managed block's body, with the engine invocation resolved for `root`. */
+export function agentsMdBlock(root: string): string {
+  const e = engineInvocation(root);
+  return `## Accessibility (ultra11y)
+
+This repository is checked against **WCAG 2.2 AA** with \`ultra11y\`: a zero-dependency
+static engine — no install, no API key, no network.
+
+**Before you commit, push, or open a pull request**, whenever you changed HTML, CSS,
+JSX/TSX, Vue, Svelte or Astro:
+
+\`\`\`sh
+${e} audit --staged --graph            # exactly what the commit would record
+${e} audit --since origin/main --graph # the whole branch, for a pull request
+\`\`\`
+
+\`--graph\` is not optional on JSX/TSX: it turns on the real cross-file analysis (an
+icon-only component used without a name, a label defined in another file) and it suppresses
+a whole class of single-file false positives.
+
+Then **adjudicate**. Do not paste the output at the user.
+
+1. Read every finding at its \`file:line\` in the real code. Refute the ones the code
+   disproves, and say what disproves them. Findings inside library sources or single-file
+   components are **preliminary**: the audited artifact is the RENDERED HTML.
+2. Rule on the judgment criteria yourself, from the code — is this \`alt\` relevant, is this
+   link's purpose clear in context, is the reading order right.
+   \`${e} verify --report <md> --in <audit.json> --manual\` emits the worklist and the
+   per-criterion decision protocol.
+3. Name what source cannot decide — computed contrast, visible focus, zoom and reflow,
+   content on hover — as **residual risks**. Never call them conforming.
+4. **Never invent a non-conformity.** \`${e} check --report <file>\` fails the report when a
+   cited element does not resolve. Run it before claiming anything.
+5. Apply the safe deterministic fixes with \`${e} fix --staged --write --safe\` and re-stage.
+   What remains needs judgment and the user's agreement.
+
+Severity vocabulary: \`blocking\` > \`major\` > \`minor\`. Block the work on \`blocking\`.
+
+To make this automatic without relying on an agent, wire the repo itself — \`${e} init --hook\`
+(git pre-commit) and \`${e} init --ci\` (GitHub Actions) are harness-independent and are the
+real safety net here. Full audits, dated conformance reports, RGAA packs and remediation
+backlogs: \`${e} --help\`.`;
+}
+
+export function installAgentsMd(root: string): EditReport {
+  return upsertManagedBlock(agentsMdPath(root), agentsMdBlock(root));
+}
+
+export function uninstallAgentsMd(root: string): EditReport {
+  return removeManagedBlock(agentsMdPath(root));
+}
+
+export function agentsMdWired(root: string): boolean {
+  return hasManagedBlock(agentsMdPath(root));
+}

package/src/install/claude-code.ts

@@ -0,0 +1,61 @@
+// Wiring the gate into Claude Code's settings.json.
+//
+// This is NOT the recommended route — `/plugin install ultra11y@ultra11y` is, because a
+// plugin carries the skills and the hook together and updates as one thing. This exists for
+// the case the plugin cannot serve: ultra11y installed from npm as a dev dependency, where
+// the user wants the automatic review without adopting a marketplace.
+//
+// Ownership is tracked by the MARKER inside the command string, so uninstall removes
+// exactly the hook entries this wrote and leaves a user's own PreToolUse hooks untouched.
+import { type EditReport, editJsonFile, readJsonSafe } from "./json-edit.js";
+
+/** Present in every command we write, and in nothing else. */
+export const CLAUDE_MARKER = "hook --claude-code";
+
+/** The tool names the gate must see. Same set as hooks/hooks.json — Claude Code names its
+ *  shell `Bash`; the rest are here so one settings entry also covers a harness that reuses
+ *  this file format with a differently-named shell. */
+const MATCHER = "Bash|bash|shell|local_shell|exec_command|run_command|exec";
+
+interface HookGroup {
+  matcher?: string;
+  hooks?: Array<{ type?: string; command?: string; timeout?: number }>;
+}
+
+/** Drop every group whose hooks are all ours, and prune ours out of mixed groups. Written
+ *  so a user who added their own PreToolUse hook next to ours keeps it. */
+function withoutOurs(groups: unknown): HookGroup[] {
+  if (!Array.isArray(groups)) return [];
+  return (groups as HookGroup[])
+    .map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !String(h.command ?? "").includes(CLAUDE_MARKER)) }))
+    .filter((g) => (g.hooks ?? []).length > 0);
+}
+
+export function installClaudeCode({ settingsPath, command }: { settingsPath: string; command: string }): EditReport {
+  return editJsonFile(settingsPath, (root) => {
+    const hooks = (root.hooks ??= {}) as Record<string, unknown>;
+    hooks.PreToolUse = [
+      ...withoutOurs(hooks.PreToolUse),
+      { matcher: MATCHER, hooks: [{ type: "command", command: `${command} ${CLAUDE_MARKER}`, timeout: 30 }] },
+    ];
+  });
+}
+
+export function uninstallClaudeCode({ settingsPath }: { settingsPath: string }): EditReport {
+  return editJsonFile(settingsPath, (root) => {
+    const hooks = root.hooks as Record<string, unknown> | undefined;
+    if (!hooks || typeof hooks !== "object") return;
+    const kept = withoutOurs(hooks.PreToolUse);
+    if (kept.length > 0) hooks.PreToolUse = kept;
+    else delete hooks.PreToolUse;
+    if (Object.keys(hooks).length === 0) delete root.hooks;
+  });
+}
+
+/** How many of our hook entries this settings file carries. */
+export function claudeCodeWired(settingsPath: string): number {
+  const root = readJsonSafe(settingsPath);
+  const groups = (root?.hooks as Record<string, unknown> | undefined)?.PreToolUse;
+  if (!Array.isArray(groups)) return 0;
+  return (groups as HookGroup[]).reduce((n, g) => n + (g.hooks ?? []).filter((h) => String(h.command ?? "").includes(CLAUDE_MARKER)).length, 0);
+}

package/src/install/codex.ts

@@ -0,0 +1,166 @@
+// Wiring the gate into the OpenAI Codex CLI.
+//
+// Codex's hook engine is a near-clone of Claude Code's: the same event names, the same
+// payload fields, the same `hookSpecificOutput` envelope, and it exports ${CLAUDE_PLUGIN_ROOT}
+// alongside its own ${PLUGIN_ROOT}. On PreToolUse it accepts exactly ONE decision — `deny`,
+// with a non-empty reason — which is precisely and only what this engine emits. So the
+// decision half needs no Codex-specific branch; `hook --codex` is the same code path.
+//
+// Two things ARE Codex-specific and are why this file exists:
+//   1. hooks are behind a feature flag: `[features] hooks = true` in config.toml;
+//   2. Codex asks the user to trust a hook command before running it, recording the answer
+//      as a sha256 in `[hooks.state]`. That hash is NOT forged here — see below.
+//
+// The native route (`codex plugin marketplace add maxgfr/ultra11y` then `codex plugin add`)
+// is better where the user wants it: it carries the skills and the hook together. This
+// exists for an npm install, and for users who do not want a marketplace.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { type EditReport, editJsonFile, readJsonSafe, writeTextWithBackup } from "./json-edit.js";
+import { copySkillsInto } from "./paths.js";
+
+/** Present in every command we write, and in nothing else. */
+export const CODEX_MARKER = "hook --codex";
+
+/** Codex's shell tool is `shell`; the alternation also covers its variants and Claude
+ *  Code's `Bash`, so one entry is right whichever name a given Codex build uses. */
+const MATCHER = "Bash|bash|shell|local_shell|exec_command|run_command|exec";
+
+interface HookGroup {
+  matcher?: string;
+  hooks?: Array<{ type?: string; command?: string; timeout?: number; statusMessage?: string }>;
+}
+
+function withoutOurs(groups: unknown): HookGroup[] {
+  if (!Array.isArray(groups)) return [];
+  return (groups as HookGroup[])
+    .map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !String(h.command ?? "").includes(CODEX_MARKER)) }))
+    .filter((g) => (g.hooks ?? []).length > 0);
+}
+
+/** Turn on `[features] hooks = true`, whatever shape the user's config.toml is already in.
+ *
+ *  Hand-rolled rather than a TOML library because the whole job is one key, and because a
+ *  round-trip through a parser would reformat a file full of the user's own comments and
+ *  ordering. Three cases: the key is already there (possibly `false`), the `[features]`
+ *  table exists without it, or neither exists. */
+export function enableHooksFeature(content: string): { content: string; changed: boolean } {
+  if (HOOKS_ON.test(featuresBody(content))) return { content, changed: false };
+
+  const body = featuresBody(content);
+  if (HOOKS_ANY.test(body)) {
+    // Flip it in place, without disturbing anything else in the table.
+    return { content: content.replace(body, body.replace(HOOKS_ANY, "hooks = true")), changed: true };
+  }
+  if (FEATURES_HEADER.test(content)) {
+    return { content: content.replace(FEATURES_HEADER, "$&\nhooks = true"), changed: true };
+  }
+  // No [features] table at all. Prepend it: a top-level table has to precede any other
+  // table header, or its keys would be swallowed by whichever table came before.
+  const prefix = content.trim() === "" ? "" : "\n";
+  return { content: `[features]\nhooks = true\n${prefix}${content}`, changed: true };
+}
+
+/** Remove the key we added, leaving an empty `[features]` table rather than guessing
+ *  whether the user wanted it. */
+export function disableHooksFeature(content: string): { content: string; changed: boolean } {
+  const body = featuresBody(content);
+  if (!HOOKS_ON.test(body)) return { content, changed: false };
+  return { content: content.replace(body, body.replace(HOOKS_ON_LINE, "")), changed: true };
+}
+
+// Every whitespace class here is HORIZONTAL ONLY (`[ \t]`, never `\s`). A TOML key lives on
+// its own line, and `\s*` at either end of the pattern happily swallows the surrounding
+// newlines — which collapses `[features]\nhooks = false\n` into `[features]hooks = true`,
+// silently corrupting the user's config into a file Codex can no longer read.
+const HOOKS_ON = /^[ \t]*hooks[ \t]*=[ \t]*true[ \t]*$/m;
+const HOOKS_ON_LINE = /^[ \t]*hooks[ \t]*=[ \t]*true[ \t]*\n?/m;
+const HOOKS_ANY = /^[ \t]*hooks[ \t]*=[ \t]*(?:false|true)[ \t]*$/m;
+const FEATURES_HEADER = /^[ \t]*\[features\][ \t]*$/m;
+const ANY_TABLE_HEADER = /^[ \t]*\[/m;
+
+/** The text between `[features]` and the next table header — the only region where a bare
+ *  `hooks = true` means what we want. Without this, a `hooks = true` under some other table
+ *  would be mistaken for ours. */
+function featuresBody(content: string): string {
+  const m = FEATURES_HEADER.exec(content);
+  if (!m) return "";
+  const rest = content.slice(m.index + m[0].length);
+  const next = ANY_TABLE_HEADER.exec(rest);
+  return rest.slice(0, next ? next.index : undefined);
+}
+
+export interface CodexInstall {
+  codexDir: string;
+  command: string;
+  /** Copy the two skills into ~/.codex/skills/ as well. */
+  skillsSource?: string | null;
+}
+
+export function installCodex({ codexDir, command, skillsSource }: CodexInstall): { reports: EditReport[]; guidance: string[] } {
+  const reports: EditReport[] = [];
+
+  reports.push(
+    editJsonFile(join(codexDir, "hooks.json"), (root) => {
+      const hooks = (root.hooks ??= {}) as Record<string, unknown>;
+      hooks.PreToolUse = [
+        ...withoutOurs(hooks.PreToolUse),
+        { matcher: MATCHER, hooks: [{ type: "command", command: `${command} ${CODEX_MARKER}`, timeout: 30, statusMessage: "ultra11y" }] },
+      ];
+    }),
+  );
+
+  const configPath = join(codexDir, "config.toml");
+  const current = existsSync(configPath) ? readFileSync(configPath, "utf8") : "";
+  const edit = enableHooksFeature(current);
+  if (edit.changed) reports.push(writeTextWithBackup(configPath, edit.content));
+
+  if (skillsSource) reports.push(...copySkillsInto(skillsSource, join(codexDir, "skills")));
+
+  return {
+    reports,
+    guidance: [
+      // Deliberately NOT forging the trusted_hash. Reproducing Codex's canonicalisation
+      // exactly is a bet that breaks silently, in the user's home directory, the next time
+      // Codex changes it — and the failure mode of a wrong hash is a gate that never fires.
+      "codex: Codex will ask you to trust this hook the first time it fires — accept it, or review it with /hooks.",
+      "codex: restart the session — hooks load at startup.",
+      "codex: `codex plugin marketplace add maxgfr/ultra11y` then `codex plugin add ultra11y@ultra11y` is the native route; it ships the skills and the hook together.",
+    ],
+  };
+}
+
+export function uninstallCodex({ codexDir }: { codexDir: string }): { reports: EditReport[]; guidance: string[] } {
+  const reports: EditReport[] = [];
+  const hooksPath = join(codexDir, "hooks.json");
+  if (existsSync(hooksPath)) {
+    reports.push(
+      editJsonFile(hooksPath, (root) => {
+        const hooks = root.hooks as Record<string, unknown> | undefined;
+        if (!hooks || typeof hooks !== "object") return;
+        const kept = withoutOurs(hooks.PreToolUse);
+        if (kept.length > 0) hooks.PreToolUse = kept;
+        else delete hooks.PreToolUse;
+        if (Object.keys(hooks).length === 0) delete root.hooks;
+      }),
+    );
+  }
+  // `[features] hooks = true` is deliberately LEFT ALONE: other tools (and the user) may
+  // rely on it, and turning it off would silently disable their hooks too.
+  return { reports, guidance: ["codex: `[features] hooks = true` was left enabled — other hooks may depend on it."] };
+}
+
+/** How many of our hook entries this Codex home carries. */
+export function codexWired(codexDir: string): number {
+  const root = readJsonSafe(join(codexDir, "hooks.json"));
+  const groups = (root?.hooks as Record<string, unknown> | undefined)?.PreToolUse;
+  if (!Array.isArray(groups)) return 0;
+  return (groups as HookGroup[]).reduce((n, g) => n + (g.hooks ?? []).filter((h) => String(h.command ?? "").includes(CODEX_MARKER)).length, 0);
+}
+
+/** True when Codex would actually run hooks at all. A wired hook behind a disabled feature
+ *  flag is the silent failure this exists to surface. */
+export function codexHooksEnabled(codexDir: string): boolean {
+  const p = join(codexDir, "config.toml");
+  return existsSync(p) && HOOKS_ON.test(featuresBody(readFileSync(p, "utf8")));
+}