codealmanac 0.1.10 → 0.2.1

package/README.md

@@ -1,18 +1,32 @@
 # codealmanac
 
-codealmanac maintains a `.almanac/` folder in your repo that AI coding agents populate with decisions, gotchas, flows, and invariants — the context the code itself can't tell you. Pages are atomic markdown files, interlinked by `[[wikilinks]]`, indexed in SQLite, and written by a writer/reviewer agent pair that runs at session end.
+A living wiki for your codebase, maintained by AI agents. It documents what the code can't say — decisions, flows, invariants, gotchas — as atomic, interlinked markdown pages living at `.almanac/` in your repo.
+
+```
+your-repo/
+├── src/
+├── .almanac/
+│   ├── pages/
+│   │   ├── supabase.md
+│   │   ├── checkout-flow.md
+│   │   └── uuid-decision.md
+│   ├── topics.yaml
+│   └── index.db          ← auto-generated SQLite index
+├── .git/
+└── ...
+```
 
 The primary consumer is the AI coding agent. The secondary consumer is humans.
 
 ## Why
 
-Claude Code, Cursor, and Copilot can read the code and tell you what it does. They can't tell you why it's shaped that way, what approaches were tried and rejected, what invariants must not be violated, or how a flow spans four files in three services. That knowledge lives in Slack threads, PR descriptions, and people's heads. It dies when threads scroll, people leave, or an agent starts a fresh session.
+Claude Code, Cursor, and Copilot can read the code and tell you what it does. They can't tell you _why_ it's shaped that way, what approaches were tried and rejected, what invariants must not be violated, or how a flow spans four files in three services. That knowledge lives in Slack threads, PR descriptions, and people's heads. It dies when threads scroll, people leave, or an agent starts a fresh session.
 
 A single `CLAUDE.md` at the repo root doesn't scale past a few hundred lines, has no graph structure, and gets stale the moment anyone commits without editing it. codealmanac replaces that one flat file with a wiki of atomic pages that agents are prompted to keep current as a side-effect of coding.
 
 ## How it works
 
-Each repo gets a committed `.almanac/pages/` directory of markdown files. A SessionEnd hook fires when a Claude Code session ends and runs `almanac capture` in the background. A writer agent reads the session transcript and existing pages, drafts changes, and invokes a reviewer subagent that critiques against the wider graph. The writer applies the final versions. New and updated pages show up in your next `git status`; you review them like any other commit.
+Each repo gets a committed `.almanac/pages/` directory of markdown files. Auto-capture hooks fire when Claude Code, Codex, or Cursor Agent sessions end and run `almanac capture` in the background. A writer agent reads the session transcript and existing pages, drafts changes, and runs a reviewer pass against the wider graph. The writer applies the final versions. New and updated pages show up in your next `git status`; you review them like any other commit.
 
 The CLI never reads or writes page content except in `capture` and `bootstrap`. Every other command (`search`, `show`, `topics`, `tag`, `health`) operates on a SQLite index that rebuilds silently whenever pages are newer than the index.
 
@@ -28,8 +42,9 @@ codealmanac --yes
 ```
 
 `codealmanac` (the bare invocation) routes to a setup wizard that:
-- checks Claude auth (subscription via `claude auth login`, or `ANTHROPIC_API_KEY`),
-- installs the SessionEnd hook in `~/.claude/settings.json`,
+- lets you choose a default agent: Claude, Codex, or Cursor,
+- checks local agent readiness,
+- installs auto-capture hooks for Claude, Codex, and Cursor,
 - drops two agent guides into `~/.claude/` (`codealmanac.md` mini, `codealmanac-reference.md` full),
 - appends `@~/.claude/codealmanac.md` to `~/.claude/CLAUDE.md` so every Claude Code session loads the mini guide.
 
@@ -37,144 +52,115 @@ The setup is idempotent — safe to re-run. Opt out with `--skip-hook` or `--ski
 
 Two binaries ship, both pointing at the same entry: `codealmanac` (install surface) and `almanac` (day-to-day). Requires Node 20 or 22.
 
-`bootstrap` and `capture` invoke Claude via the bundled Claude Agent SDK. The query commands (`search`, `show`, `health`, `topics`) need no credentials at all.
+`bootstrap` and `capture` invoke your configured default agent. Claude uses the bundled Claude Agent SDK, Codex uses `codex exec --json`, and Cursor uses `cursor-agent --print --output-format stream-json`. The query commands (`search`, `show`, `health`, `topics`) need no credentials at all.
 
 ## Authentication
 
-Pick one — `bootstrap` and `capture` accept either:
+Pick the agent you want CodeAlmanac to use:
 
 ```bash
-# Option A — your Claude subscription (Pro/Max). Preferred if you already
-# use Claude Code; no separate bill, no copy-pasted keys.
+# Claude
 claude auth login --claudeai
-
-# Option B — a pay-per-token API key from https://console.anthropic.com.
+# or:
 export ANTHROPIC_API_KEY=sk-ant-...
 
-# Either way, verify with:
-claude auth status
-# or:
+# Codex
+codex login
+
+# Cursor
+cursor-agent login
+
+# Verify all providers:
+almanac agents list
 almanac doctor
 ```
 
-codealmanac itself never sees your credentials — auth is handled by the bundled Claude Agent SDK CLI, which reads the same `~/.claude/credentials/` store Claude Code uses.
+Set or change the default at any time:
+
+```bash
+almanac set default-agent codex
+almanac set model codex gpt-5.3-codex
+```
+
+codealmanac itself never stores your provider credentials. Auth stays in each agent's normal local credential store.
 
 ## Quickstart
 
 ```bash
 npm install -g codealmanac
-codealmanac                   # interactive setup wizard
+codealmanac                   # interactive setup wizard; choose Claude/Codex/Cursor
                               # (or: codealmanac --yes)
 
 cd your-repo
-almanac bootstrap             # agent reads the repo and seeds stub pages + topic DAG
+almanac bootstrap             # default agent reads the repo and seeds pages + topic DAG
 
-almanac search "auth"         # full-text search across pages; prints slugs one per line
+almanac search "auth"         # full-text search across pages
 almanac show checkout-flow    # read a page
 
-# From here on, just code as usual — the SessionEnd hook invokes
+# From here on, just code as usual — the installed hooks invoke
 # `almanac capture` at session end, which writes and updates pages
 # based on what happened in the session.
 ```
 
 No `almanac init`. A wiki is scaffolded two ways: run `almanac bootstrap` yourself, or clone a repo that already has `.almanac/` committed (codealmanac auto-registers it on the first query).
 
-Sanity-check the install with `almanac doctor` — it reports binary location, native SQLite binding, Claude auth, hook status, guides, import line, and current-wiki stats with a one-line fix for each ✗.
-
-## Command reference
-
-Grouped the same way as `almanac --help`:
-
-| Group | Command | What it does |
-|---|---|---|
-| Query | `almanac search [query]` | FTS, `--topic`, `--mentions <path>`, `--since`, `--stale`, `--orphan`, `--archived`, `--limit`, `--json` |
-| Query | `almanac show <slug>` | Read a page. Field flags: `--raw`, `--meta`, `--lead`, `--title`, `--topics`, `--files`, `--links`, `--backlinks`, `--xwiki`, `--lineage`, `--updated`, `--path`, `--json`. Absorbs the old `info` and `path` commands. |
-| Query | `almanac health` | Eight-category graph integrity report (`orphans`, `stale`, `dead-refs`, `broken-links`, `broken-xwiki`, `empty-topics`, `empty-pages`, `slug-collisions`) |
-| Query | `almanac list` | List registered wikis; `--drop <name>` to remove |
-| Edit | `almanac tag <page> <topics...>` | Add topics; auto-creates missing ones; `--stdin` for bulk |
-| Edit | `almanac untag <page> <topic>` | Remove a topic |
-| Edit | `almanac topics ...` | `list`, `show`, `create`, `link`, `unlink`, `rename`, `delete`, `describe` — DAG management |
-| Wiki lifecycle | `almanac bootstrap` | Agent reads the repo and seeds stub entity pages + topic DAG (requires Claude auth) |
-| Wiki lifecycle | `almanac capture [transcript]` | Writer + reviewer on a session transcript (usually invoked by the hook) |
-| Wiki lifecycle | `almanac hook install\|uninstall\|status` | Manage the SessionEnd hook in `~/.claude/settings.json` |
-| Wiki lifecycle | `almanac reindex` | Force rebuild of `.almanac/index.db` |
-| Setup | `almanac setup` | Install hook + guides + CLAUDE.md import (bare `codealmanac` alias) |
-| Setup | `almanac uninstall` | Reverse `setup`: remove hook + guides + import line |
-| Setup | `almanac doctor` | Report on install + current wiki with one-line fixes |
+Sanity-check the install with `almanac doctor` and `almanac agents list` — they report binary location, native SQLite binding, provider readiness, hook status, guides, import line, and current-wiki stats.
 
-Every command that returns pages prints slugs one per line; pass `--json` for structured output; pipe slugs into commands that accept `--stdin` (`show`, `tag`, `health`). Run `almanac <command> --help` for the full flag surface, or import the full reference on demand: `@~/.claude/codealmanac-reference.md`.
+New to codealmanac? Read the [Concepts guide](./docs/concepts.md) for a walkthrough of pages, topics, files, the database, and the CLI.
 
-## Concepts
+## Commands
 
-### Page shapes (suggestions, not rules)
-
-The wiki tends to organize around four kinds of pages, but nothing in the system enforces them:
-
-- **Entity pages** — stable named things (Supabase, Stripe, a custom auth system). These are the anchors other pages link to.
-- **Decision pages** — why X over Y, with context and consequences.
-- **Flow pages** — how a multi-file process works end-to-end.
-- **Gotcha pages** — specific failures or constraints, usually anchored to an entity.
-
-A page that doesn't fit any of these is fine. Pick the shape that serves the knowledge.
-
-### Topics as a DAG
-
-One organizational axis: topics. Topics form a directed acyclic graph — a topic can have multiple parents, and a page can belong to multiple topics. No page type system.
-
-```
-decisions   stack      flows
-            └─ database
-               └─ supabase   ← a page tagged [stack, database]
+```bash
+# Search & read
+almanac search "auth"                        # full-text search across pages
+almanac search --topic database              # filter by topic
+almanac search --mentions src/lib/stripe.ts  # pages referencing a file
+almanac show checkout-flow                   # read a page
+almanac show checkout-flow --meta            # metadata only
+almanac show checkout-flow --raw             # body only
+
+# Organize
+almanac topics list                          # all topics with page counts
+almanac topics show database --descendants   # topic + its subtree
+almanac tag <page> <topic...>                # add topics to a page
+almanac health                               # graph integrity report
+
+# Wiki lifecycle
+almanac bootstrap --agent codex              # seed a new wiki from the repo
+almanac capture --agent cursor <transcript>  # update wiki from a transcript
+almanac hook install --source all            # auto-capture for Claude/Codex/Cursor
+
+# Setup & diagnose
+almanac agents list                          # provider readiness + default
+almanac set default-agent codex              # change default provider
+almanac doctor                               # check install + wiki health
+almanac update                               # update to latest version
 ```
 
-`almanac topics show database --descendants` walks the subgraph and returns every page in `database` or `supabase`. Cycles are prevented by a `CHECK` constraint and a depth cap.
-
-### The unified `[[...]]` link syntax
+All commands output slugs one per line. Add `--json` for structured output. Pipe with `--stdin`:
 
-One link form, disambiguated by content:
-
-```markdown
-See [[checkout-flow]] for the full sequence.           ← page slug (no slash)
-The handler [[src/checkout/handler.ts]] does X.        ← file (has slash)
-This spans [[src/checkout/]] generally.                ← folder (trailing slash)
-See [[openalmanac:supabase]] for cross-wiki context.   ← cross-wiki (colon prefix)
+```bash
+almanac search --topic flows | almanac show --stdin
+almanac search --stale 90d | almanac tag --stdin needs-review
 ```
 
-The indexer classifies each link by those rules and writes it to `wikilinks`, `file_refs`, or `cross_wiki_links`. `almanac search --mentions src/checkout/handler.ts` returns every page referencing that file or any folder containing it.
-
-### Archive vs edit
-
-Most changes are edits — the page is updated in place to reflect current truth, with git history as the archive. When a page's central decision is reversed (not just refined), the old page is marked `archived_at` and `superseded_by`, a new page is created with `supersedes`, and both live side by side. Archived pages are excluded from `almanac search` by default and exempt from dead-ref health checks.
-
-### The notability bar
-
-Every repo's `.almanac/README.md` contains a notability bar: the threshold for what deserves a page. The default is "non-obvious knowledge that will help a future agent" — decisions that took research, gotchas discovered through failure, cross-cutting flows, constraints not visible in code. The writer consults the bar before writing; the reviewer enforces it. Edit the bar to match your repo's taste.
+Run `almanac <command> --help` for the full flag surface.
 
 ## How capture works
 
-A page looks like this:
+When a Claude, Codex, or Cursor session ends, the installed hook backgrounds `almanac capture`. The writer agent reads the session transcript, runs `almanac search` and `almanac show` against the existing wiki, drafts changes to pages under `.almanac/pages/`, and performs a reviewer pass. Claude uses its SDK's read-only reviewer subagent; Codex and Cursor perform the reviewer pass from prompt guidance until stricter provider enforcement lands. The reviewer checks duplicates, missing wikilinks, missing topics, inference dressed as fact, and cohesion problems. The writer decides what to incorporate and writes the final versions.
 
-```markdown
----
-title: Supabase
-topics: [stack, database]
-files:
-  - src/lib/supabase.ts
-  - backend/src/models/
----
+Capture writes nothing if nothing in the session meets the notability bar — silence is a valid outcome.
 
-# Supabase
+No proposal files, no `--apply` step, no state machine between writer and reviewer. The changes land in `git status` and you commit them like anything else.
 
-PostgreSQL hosted on Supabase. Connection pooling via Supavisor.
+### The notability bar
 
-## Gotchas
-- Supavisor has a 30s idle timeout — long transactions get killed ([[supavisor-timeout]]).
-- UUIDs as primary keys, not `serial` ([[uuid-decision]]).
-```
+Every repo's `.almanac/README.md` contains a notability bar: the threshold for what deserves a page. The default is "non-obvious knowledge that will help a future agent" — decisions that took research, gotchas discovered through failure, cross-cutting flows, constraints not visible in code. The writer consults the bar before writing; the reviewer enforces it. Edit the bar to match your repo's taste.
 
-When a Claude Code session ends, the SessionEnd hook backgrounds `almanac capture <transcript>`. The writer agent reads the transcript, runs `almanac search` and `almanac show` against the existing wiki, drafts changes to pages under `.almanac/pages/`, and invokes the reviewer subagent. The reviewer reads across the graph, flags duplicates, missing wikilinks, missing topics, inference dressed as fact, and cohesion problems, then returns a text critique. The writer decides what to incorporate and writes the final versions. Capture writes nothing if nothing in the session meets the notability bar — silence is a valid outcome.
+### Archive vs edit
 
-No proposal files, no `--apply` step, no state machine between writer and reviewer. The changes land in `git status` and you commit them like anything else.
+Most changes are edits — the page is updated in place to reflect current truth, with git history as the archive. When a page's central decision is reversed (not just refined), the old page is marked `archived_at` and `superseded_by`, a new page is created with `supersedes`, and both live side by side. Archived pages are excluded from `almanac search` by default and exempt from dead-ref health checks.
 
 ## Multi-wiki
 
@@ -187,18 +173,52 @@ almanac search --wiki openalmanac "RLS" # specific wiki
 
 Cross-wiki references use a colon prefix: `[[openalmanac:supabase]]`. The segment before `:` resolves via the registry; unreachable wikis are silently skipped rather than erroring. Cloning a repo with a committed `.almanac/` auto-registers it on the first `almanac` command.
 
-## Writing conventions
-
-Pages are neutral-tone encyclopedia-style prose — every sentence contains a specific fact, no significance inflation, no hedging, no formulaic conclusions. Prose first, bullets for genuine lists, tables only for structured comparison. The conventions are described in each repo's `.almanac/README.md` (generated by `bootstrap`); the reviewer loads them at runtime and enforces them on every proposal.
-
 ## Status
 
-`v0.1.3`, pre-release. Node 20.x or 22.x. Release process is documented in [RELEASE.md](./RELEASE.md). Breaking changes are possible before 1.0; they will be called out in release notes.
-
+`v0.2.1`, pre-release. Node 20.x or 22.x. Release process is documented in [RELEASE.md](./RELEASE.md). Breaking changes are possible before 1.0; they will be called out in release notes.
 ## Philosophy
 
 Intelligence lives in the prompt, not in the pipeline. Whenever a task calls for judgment — deciding what from a session is worth capturing, evaluating a proposal against the graph, picking between editing and archiving — codealmanac hands a concrete-but-open prompt to an agent. It does not wrap agents in propose/review/apply state machines, intermediate proposal files, or `--dry-run` rehearsal flags. The CLI finds and organizes; the agents do the thinking. If a future change can be expressed as a longer prompt or as more pipeline code, the prompt almost always wins.
 
+## Contributing
+
+codealmanac is open source under the MIT license. To set up a development environment:
+
+```bash
+git clone https://github.com/AlmanacCode/codealmanac.git
+cd codealmanac
+npm install
+npm run build
+npm link                  # makes `almanac` and `codealmanac` available globally
+npm test                  # run the test suite (vitest)
+```
+
+The codebase is TypeScript, built with [tsup](https://tsup.egoist.dev/), tested with [Vitest](https://vitest.dev/). SQLite via [better-sqlite3](https://github.com/WiseLibs/better-sqlite3). AI features use the [Claude Agent SDK](https://docs.anthropic.com/en/docs/agents/agent-sdk).
+
+### Project structure
+
+```
+src/
+├── cli.ts              ← entry point and shortcut routing
+├── cli/                ← commander command registration and help layout
+├── commands/           ← one file per CLI command
+├── indexer/            ← parses markdown → SQLite index
+│   ├── schema.ts       ← DDL (CREATE TABLE statements)
+│   ├── index.ts        ← incremental indexer (mtime-based freshness)
+│   ├── frontmatter.ts  ← YAML frontmatter parser
+│   ├── wikilinks.ts    ← [[link]] extractor + classifier
+│   └── paths.ts        ← path normalization
+├── registry/           ← global wiki registry (~/.almanac/registry.json)
+├── topics/             ← topic DAG + frontmatter rewriting
+├── agent/              ← Claude Agent SDK integration
+├── paths.ts            ← find nearest .almanac/ (like git finds .git/)
+└── slug.ts             ← kebab-case canonicalization
+```
+
+## Status
+
+v0.1.10, pre-release. Node 20.x or 22.x. Release process is documented in [RELEASE.md](./RELEASE.md). Breaking changes are possible before 1.0; they will be called out in release notes.
+
 ## Related
 
 codealmanac is part of the [OpenAlmanac](https://www.openalmanac.org) family. OpenAlmanac is a knowledge base for curious people; codealmanac is knowledge for codebases. Same writing standards, different reader.

package/dist/agents-A4II4YJC.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import {
+  runAgentsList,
+  runSetAgentModel,
+  runSetDefaultAgent
+} from "./chunk-R3URPHGH.js";
+import "./chunk-SSYMRT4I.js";
+import "./chunk-WRUSDYYE.js";
+import "./chunk-7JUX4ADQ.js";
+export {
+  runAgentsList,
+  runSetAgentModel,
+  runSetDefaultAgent
+};
+//# sourceMappingURL=agents-A4II4YJC.js.map

package/dist/auth-S5DVUIUJ.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import {
+  UNAUTHENTICATED_MESSAGE,
+  assertClaudeAuth,
+  checkClaudeAuth,
+  defaultSpawnCli,
+  legacySdkSpawnCli,
+  resolveClaudeExecutable
+} from "./chunk-SSYMRT4I.js";
+export {
+  UNAUTHENTICATED_MESSAGE,
+  assertClaudeAuth,
+  checkClaudeAuth,
+  defaultSpawnCli,
+  legacySdkSpawnCli,
+  resolveClaudeExecutable
+};
+//# sourceMappingURL=auth-S5DVUIUJ.js.map

package/dist/{chunk-Z4MWLVS2.js → chunk-447U3GQJ.js}

@@ -3,6 +3,7 @@
 // src/commands/hook.ts
 import { existsSync as existsSync2 } from "fs";
 import { mkdir as mkdir2, readFile as readFile2, rename, writeFile } from "fs/promises";
+import { homedir as homedir2 } from "os";
 import path2 from "path";
 
 // src/commands/hook/script.ts
@@ -120,6 +121,54 @@ async function runHookInstall(options = {}) {
     return { stdout: "", stderr: `almanac: ${script.error}
 `, exitCode: 1 };
   }
+  const source = options.source ?? "claude";
+  if (source === "all") {
+    const results = [
+      await installClaudeHook(options, script.path),
+      await installGenericHook({
+        label: "Codex Stop",
+        settingsPath: path2.join(homedir2(), ".codex", "hooks.json"),
+        eventName: "Stop",
+        shape: "wrapped",
+        scriptPath: script.path
+      }),
+      await installGenericHook({
+        label: "Cursor sessionEnd",
+        settingsPath: path2.join(homedir2(), ".cursor", "hooks.json"),
+        eventName: "sessionEnd",
+        shape: "flat",
+        scriptPath: script.path
+      })
+    ];
+    const failed = results.find((r) => r.exitCode !== 0);
+    if (failed !== void 0) return failed;
+    return {
+      stdout: results.map((r) => r.stdout.trimEnd()).join("\n") + "\n",
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  if (source === "codex") {
+    return await installGenericHook({
+      label: "Codex Stop",
+      settingsPath: path2.join(homedir2(), ".codex", "hooks.json"),
+      eventName: "Stop",
+      shape: "wrapped",
+      scriptPath: script.path
+    });
+  }
+  if (source === "cursor") {
+    return await installGenericHook({
+      label: "Cursor sessionEnd",
+      settingsPath: path2.join(homedir2(), ".cursor", "hooks.json"),
+      eventName: "sessionEnd",
+      shape: "flat",
+      scriptPath: script.path
+    });
+  }
+  return await installClaudeHook(options, script.path);
+}
+async function installClaudeHook(options, scriptPath) {
   const settingsPath = resolveSettingsPath(options);
   const settings = await readSettings(settingsPath);
   const existing = (settings.hooks?.SessionEnd ?? []).slice();
@@ -134,7 +183,7 @@ async function runHookInstall(options = {}) {
         continue;
       }
       const exactMatch = c.entry.hooks.some(
-        (h) => h.command === script.path
+        (h) => h.command === scriptPath
       );
       if (exactMatch && oursAlready === null) {
         oursAlready = c.entry;
@@ -172,7 +221,7 @@ Remove or rewrap it manually in ${settingsPath} before installing.
   }
   if (oursAlready !== null && staleCount.n === 0) {
     return {
-      stdout: `almanac: SessionEnd hook already installed at ${script.path}
+      stdout: `almanac: SessionEnd hook already installed at ${scriptPath}
 `,
       stderr: "",
       exitCode: 0
@@ -183,7 +232,7 @@ Remove or rewrap it manually in ${settingsPath} before installing.
     hooks: [
       {
         type: "command",
-        command: script.path,
+        command: scriptPath,
         timeout: HOOK_TIMEOUT_SECONDS
       }
     ]
@@ -193,13 +242,121 @@ Remove or rewrap it manually in ${settingsPath} before installing.
   await writeSettings(settingsPath, settings);
   return {
     stdout: `almanac: SessionEnd hook installed
-  script: ${script.path}
+  script: ${scriptPath}
   settings: ${settingsPath}
 `,
     stderr: "",
     exitCode: 0
   };
 }
+async function installGenericHook(args) {
+  const settings = await readSettings(args.settingsPath);
+  const hooksObj = settings.hooks !== void 0 && settings.hooks !== null && typeof settings.hooks === "object" ? settings.hooks : {};
+  const existing = Array.isArray(hooksObj[args.eventName]) ? hooksObj[args.eventName] : [];
+  const kept = existing.filter((entry) => !entryHasOurCommand(entry));
+  const already = existing.some(
+    (entry) => entryHasExactCommand(entry, args.scriptPath)
+  );
+  if (already && kept.length === existing.length - 1) {
+    return {
+      stdout: `almanac: ${args.label} hook already installed at ${args.scriptPath}
+`,
+      stderr: "",
+      exitCode: 0
+    };
+  }
+  const fresh = args.shape === "wrapped" ? {
+    hooks: [
+      {
+        type: "command",
+        command: args.scriptPath,
+        timeout: HOOK_TIMEOUT_SECONDS
+      }
+    ]
+  } : {
+    command: args.scriptPath,
+    timeout: HOOK_TIMEOUT_SECONDS
+  };
+  hooksObj[args.eventName] = [
+    ...kept,
+    fresh
+  ];
+  settings.hooks = hooksObj;
+  await writeSettings(args.settingsPath, settings);
+  if (args.label.startsWith("Codex ")) {
+    await ensureCodexHooksFeature(path2.join(homedir2(), ".codex", "config.toml"));
+  }
+  return {
+    stdout: `almanac: ${args.label} hook installed
+  script: ${args.scriptPath}
+  settings: ${args.settingsPath}
+`,
+    stderr: "",
+    exitCode: 0
+  };
+}
+function entryHasOurCommand(entry) {
+  return collectHookCommands(entry).some(isOurCommandPath);
+}
+function entryHasExactCommand(entry, command) {
+  return collectHookCommands(entry).some((candidate) => candidate === command);
+}
+function collectHookCommands(entry) {
+  if (entry === null || typeof entry !== "object") return [];
+  const obj = entry;
+  const direct = typeof obj.command === "string" ? [obj.command] : [];
+  const nested = Array.isArray(obj.hooks) ? obj.hooks.flatMap((hook) => collectHookCommands(hook)) : [];
+  return [...direct, ...nested];
+}
+async function ensureCodexHooksFeature(configPath) {
+  let body = "";
+  if (existsSync2(configPath)) {
+    body = await readFile2(configPath, "utf8");
+  }
+  if (/^\s*codex_hooks\s*=\s*true\s*$/m.test(body)) return;
+  const next = setTomlFeatureFlag(body, "codex_hooks", true);
+  await mkdir2(path2.dirname(configPath), { recursive: true });
+  const tmp = `${configPath}.almanac-tmp-${process.pid}`;
+  await writeFile(tmp, next.endsWith("\n") ? next : `${next}
+`, "utf8");
+  await rename(tmp, configPath);
+}
+function setTomlFeatureFlag(body, key, value) {
+  const desired = `${key} = ${value ? "true" : "false"}`;
+  const lines = body.split(/\r?\n/);
+  let featuresStart = -1;
+  let featuresEnd = lines.length;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*\[features\]\s*$/.test(lines[i] ?? "")) {
+      featuresStart = i;
+      continue;
+    }
+    if (featuresStart !== -1 && i > featuresStart && /^\s*\[.*\]\s*$/.test(lines[i] ?? "")) {
+      featuresEnd = i;
+      break;
+    }
+  }
+  if (featuresStart === -1) {
+    const prefix = body.trim().length === 0 ? "" : `${body.trimEnd()}
+
+`;
+    return `${prefix}[features]
+${desired}
+`;
+  }
+  const keyPattern = new RegExp(`^\\s*${escapeRegex(key)}\\s*=`);
+  for (let i = featuresStart + 1; i < featuresEnd; i++) {
+    if (keyPattern.test(lines[i] ?? "")) {
+      lines[i] = desired;
+      return lines.join("\n");
+    }
+  }
+  lines.splice(featuresStart + 1, 0, desired);
+  return lines.join("\n");
+}
+function escapeRegex(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 async function runHookUninstall(options = {}) {
   const settingsPath = resolveSettingsPath(options);
   if (!existsSync2(settingsPath)) {
@@ -352,4 +509,4 @@ export {
   runHookUninstall,
   runHookStatus
 };
-//# sourceMappingURL=chunk-Z4MWLVS2.js.map
+//# sourceMappingURL=chunk-447U3GQJ.js.map