cairn-ai 0.1.2

package/docs/model-guidance/codex.md

@@ -0,0 +1,48 @@
+# Codex Model Guidance
+
+Codex-family models are strong at small implementation slices, explicit tool use, and repeatable verification. In Cairn, prefer them for bounded `worker` tasks and structurally clear planning.
+
+## Use Strengths
+
+- Quickly handle implementation slices with clear file scope.
+- Read existing patterns and make minimal changes in the same style.
+- Run repository tool readiness checks and bootstrap missing command-line tools.
+- Capture module acceptance verification and surface integration verification from command results.
+- Run dry-run, check, plan, diff, validate, or equivalent commands before mutating external state.
+- Explore independent work in parallel and sequence only dependent work.
+
+## Adjustment Rules
+
+- Do not start implementation without a plan.
+- Keep work units small. Split large changes into smaller plan slices.
+- If `apply_patch` is unstable in the environment, use an editing tool or a clear file update path.
+- Do not duplicate the same exploration. Wait for already delegated searches.
+- Do not trust success-looking output alone. Confirm real files, commands, and surface evidence.
+- Do not skip LSP, typecheck, lint, dry-run, or verification because a tool is missing. Try repository-local installation or record the failed install attempt as a blocker.
+- Do not continue an open-ended verification loop. Use at most two verification passes per slice unless the plan records a risk-based exception.
+- Write user-visible output in the OS locale unless the user asks for another language.
+
+## Path Guidance
+
+### Planning
+
+- On Light Path, write explicit slice contracts when a plan artifact exists.
+- Record detected stack, required tools, install commands, and tool blockers.
+- Specify file scope and verification commands so implementation does not need to rediscover them.
+- Specify the dry-run or check command for slices that can mutate external state, or record why none exists.
+- On failure, prefer slice re-splitting over a repeated loop.
+
+### Implementation
+
+- Edit only within the file scope listed in the plan.
+- Confirm required tools are available. Install or bootstrap missing required tools before implementation.
+- Run the recorded dry-run or check command before external-state mutation when applicable.
+- After changes, run both module acceptance verification and surface integration verification.
+- If a gate fails, diagnose once, shrink or split the slice, and rerun both gates. Stop after the second failed pass and record the blocker.
+- Return evidence in a form that can be recorded in `docs/plan/<topic>.md`.
+
+### Delegation
+
+- Handle search, file listing, command checks, and QA artifact capture.
+- Use `explorer` for independent read-only discovery or read-only verification when available.
+- When using `worker`, state clear file ownership and tell the worker not to revert others' edits.

package/hooks/hooks.json

@@ -0,0 +1,65 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${PLUGIN_ROOT}/scripts/cairn-state.sh\" session-start",
+            "timeout": 10,
+            "statusMessage": "Cairn: preparing repository memory and plan indexes"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${PLUGIN_ROOT}/scripts/cairn-state.sh\" user-prompt-submit",
+            "timeout": 10,
+            "statusMessage": "Cairn: loading compact work context"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^(apply_patch|write|Write|edit|Edit|multi_edit|multiedit|MultiEdit)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${PLUGIN_ROOT}/scripts/cairn-state.sh\" post-tool-use",
+            "timeout": 10,
+            "statusMessage": "Cairn: checking memory and plan indexes"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${PLUGIN_ROOT}/scripts/cairn-state.sh\" stop",
+            "timeout": 10,
+            "statusMessage": "Cairn: checking two-gate evidence requirements"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"${PLUGIN_ROOT}/scripts/cairn-state.sh\" subagent-stop",
+            "timeout": 10,
+            "statusMessage": "Cairn: checking subagent handoff evidence"
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "cairn-ai",
+  "version": "0.1.2",
+  "description": "Token-efficient agent harness with tool readiness for Codex, Claude Code, and Antigravity",
+  "license": "MIT",
+  "author": {
+    "name": "WkNam"
+  },
+  "homepage": "https://github.com/dspaudio/cairn-ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dspaudio/cairn-ai.git"
+  },
+  "keywords": [
+    "codex",
+    "claude-code",
+    "antigravity",
+    "agent",
+    "harness",
+    "plugin",
+    "workflow"
+  ],
+  "bin": {
+    "cairn": "scripts/cairn",
+    "cairn-ai": "scripts/cairn"
+  },
+  "files": [
+    ".agents/",
+    ".claude/",
+    ".codex-plugin/",
+    "agents/",
+    "commands/",
+    "docs/model-guidance/",
+    "hooks/",
+    "scripts/",
+    "skills/",
+    "templates/",
+    "README.md",
+    "README.*.md"
+  ],
+  "scripts": {
+    "check": "node --check scripts/cairn-lifecycle.mjs && node --check scripts/cairn-toolcheck.mjs && node -e \"JSON.parse(require('node:fs').readFileSync('package.json','utf8')); JSON.parse(require('node:fs').readFileSync('.codex-plugin/plugin.json','utf8')); JSON.parse(require('node:fs').readFileSync('hooks/hooks.json','utf8'))\" && npm test",
+    "test": "node --test",
+    "prepack": "npm run check"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/cairn

@@ -0,0 +1,115 @@
+#!/bin/sh
+set -eu
+
+cmd="${1:-help}"
+shift || true
+locale="${LC_ALL:-${LC_MESSAGES:-${LANG:-en}}}"
+
+script_path="$0"
+link_target="$(readlink "$script_path" 2>/dev/null || true)"
+if [ -n "$link_target" ]; then
+  case "$link_target" in
+    /*) script_path="$link_target" ;;
+    *) script_path="$(dirname "$script_path")/$link_target" ;;
+  esac
+fi
+script_dir="$(cd "$(dirname "$script_path")" && pwd)"
+
+locale_family() {
+  case "$locale" in
+    ko*|KO*) printf '%s\n' ko ;;
+    ja*|JA*) printf '%s\n' ja ;;
+    zh*|ZH*) printf '%s\n' zh ;;
+    es*|ES*) printf '%s\n' es ;;
+    fr*|FR*) printf '%s\n' fr ;;
+    de*|DE*) printf '%s\n' de ;;
+    pt*|PT*) printf '%s\n' pt ;;
+    *) printf '%s\n' en ;;
+  esac
+}
+
+say() {
+  key="$1"
+  family="$(locale_family)"
+  case "$family:$key" in
+    ko:memory) printf '%s\n' "cairn-memory 스킬을 사용하세요. MEMORY.md는 짧은 색인으로, 상세 내용은 docs/memory/<domain>.md에 기록합니다." ;;
+    ko:plan) printf '%s\n' "cairn-plan 스킬을 사용하세요. PLAN.md는 색인으로, 상세 계획은 docs/plan/<topic>.md에 기록합니다." ;;
+    ko:work) printf '%s\n' "cairn-work 스킬을 사용하세요. 하나의 모듈 조각을 실행하고 모듈 증거와 표면 증거를 확보합니다." ;;
+    ko:review) printf '%s\n' "cairn-review 스킬을 사용하세요. PLAN.md와 MEMORY.md 기준으로 증거를 비교합니다." ;;
+    ko:toolcheck) printf '%s\n' "저장소 도구를 점검하려면 cairn toolcheck 를 실행하세요. 누락 도구 설치까지 시도하려면 cairn toolcheck --install 을 사용합니다." ;;
+    ko:usage) printf '%s\n' "사용법: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
+    ja:memory) printf '%s\n' "cairn-memory スキルを使用してください。MEMORY.md は短い索引にし、詳細は docs/memory/<domain>.md に記録します。" ;;
+    ja:plan) printf '%s\n' "cairn-plan スキルを使用してください。PLAN.md は索引にし、詳細計画は docs/plan/<topic>.md に記録します。" ;;
+    ja:work) printf '%s\n' "cairn-work スキルを使用してください。1つのモジュールスライスを実行し、モジュール証拠と表面証拠を取得します。" ;;
+    ja:review) printf '%s\n' "cairn-review スキルを使用してください。PLAN.md と MEMORY.md に照らして証拠を比較します。" ;;
+    ja:toolcheck) printf '%s\n' "リポジトリツールを確認するには cairn toolcheck を実行してください。不足ツールのインストールも試すには cairn toolcheck --install を使用します。" ;;
+    ja:usage) printf '%s\n' "使い方: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
+    zh:memory) printf '%s\n' "使用 cairn-memory skill。将 MEMORY.md 保持为简短索引，并将详细内容写入 docs/memory/<domain>.md。" ;;
+    zh:plan) printf '%s\n' "使用 cairn-plan skill。将 PLAN.md 保持为索引，并将详细计划写入 docs/plan/<topic>.md。" ;;
+    zh:work) printf '%s\n' "使用 cairn-work skill。执行一个模块切片，并收集模块证据和表面证据。" ;;
+    zh:review) printf '%s\n' "使用 cairn-review skill。根据 PLAN.md 和 MEMORY.md 对比证据。" ;;
+    zh:toolcheck) printf '%s\n' "运行 cairn toolcheck 检查仓库工具。使用 cairn toolcheck --install 尝试安装缺失工具。" ;;
+    zh:usage) printf '%s\n' "用法: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
+    es:memory) printf '%s\n' "Usa la skill cairn-memory. Mantén MEMORY.md como un índice breve y escribe los detalles en docs/memory/<domain>.md." ;;
+    es:plan) printf '%s\n' "Usa la skill cairn-plan. Mantén PLAN.md como índice y escribe los planes detallados en docs/plan/<topic>.md." ;;
+    es:work) printf '%s\n' "Usa la skill cairn-work. Ejecuta un solo segmento de módulo y captura evidencia de módulo y de superficie." ;;
+    es:review) printf '%s\n' "Usa la skill cairn-review. Compara la evidencia con PLAN.md y MEMORY.md." ;;
+    es:toolcheck) printf '%s\n' "Ejecuta cairn toolcheck para revisar herramientas del repositorio. Usa cairn toolcheck --install para intentar instalar herramientas faltantes." ;;
+    es:usage) printf '%s\n' "Uso: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
+    fr:memory) printf '%s\n' "Utilisez la skill cairn-memory. Gardez MEMORY.md comme index court et écrivez les détails dans docs/memory/<domain>.md." ;;
+    fr:plan) printf '%s\n' "Utilisez la skill cairn-plan. Gardez PLAN.md comme index et écrivez les plans détaillés dans docs/plan/<topic>.md." ;;
+    fr:work) printf '%s\n' "Utilisez la skill cairn-work. Exécutez une tranche de module et capturez les preuves de module et de surface." ;;
+    fr:review) printf '%s\n' "Utilisez la skill cairn-review. Comparez les preuves avec PLAN.md et MEMORY.md." ;;
+    fr:toolcheck) printf '%s\n' "Exécutez cairn toolcheck pour vérifier les outils du dépôt. Utilisez cairn toolcheck --install pour tenter d'installer les outils manquants." ;;
+    fr:usage) printf '%s\n' "Utilisation: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
+    de:memory) printf '%s\n' "Verwenden Sie die Skill cairn-memory. Halten Sie MEMORY.md als kurzen Index und schreiben Sie Details nach docs/memory/<domain>.md." ;;
+    de:plan) printf '%s\n' "Verwenden Sie die Skill cairn-plan. Halten Sie PLAN.md als Index und schreiben Sie Detailpläne nach docs/plan/<topic>.md." ;;
+    de:work) printf '%s\n' "Verwenden Sie die Skill cairn-work. Führen Sie einen Modulabschnitt aus und erfassen Sie Modul- und Oberflächenbelege." ;;
+    de:review) printf '%s\n' "Verwenden Sie die Skill cairn-review. Vergleichen Sie Belege mit PLAN.md und MEMORY.md." ;;
+    de:toolcheck) printf '%s\n' "Führen Sie cairn toolcheck aus, um Repository-Tools zu prüfen. Verwenden Sie cairn toolcheck --install, um fehlende Tools zu installieren." ;;
+    de:usage) printf '%s\n' "Verwendung: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
+    pt:memory) printf '%s\n' "Use a skill cairn-memory. Mantenha MEMORY.md como um índice curto e escreva detalhes em docs/memory/<domain>.md." ;;
+    pt:plan) printf '%s\n' "Use a skill cairn-plan. Mantenha PLAN.md como índice e escreva planos detalhados em docs/plan/<topic>.md." ;;
+    pt:work) printf '%s\n' "Use a skill cairn-work. Execute uma fatia de módulo e capture evidências de módulo e de superfície." ;;
+    pt:review) printf '%s\n' "Use a skill cairn-review. Compare evidências com PLAN.md e MEMORY.md." ;;
+    pt:toolcheck) printf '%s\n' "Execute cairn toolcheck para verificar ferramentas do repositório. Use cairn toolcheck --install para tentar instalar ferramentas ausentes." ;;
+    pt:usage) printf '%s\n' "Uso: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
+    *)
+      case "$key" in
+        memory) printf '%s\n' "Use the cairn-memory skill. Keep MEMORY.md as a short index and write details to docs/memory/<domain>.md." ;;
+        plan) printf '%s\n' "Use the cairn-plan skill. Keep PLAN.md as an index and write detailed plans to docs/plan/<topic>.md." ;;
+        work) printf '%s\n' "Use the cairn-work skill. Execute one module slice and capture module and surface evidence." ;;
+        review) printf '%s\n' "Use the cairn-review skill. Compare evidence against PLAN.md and MEMORY.md." ;;
+        toolcheck) printf '%s\n' "Run cairn toolcheck to inspect repository tools. Use cairn toolcheck --install to attempt missing tool installation." ;;
+        usage) printf '%s\n' "Usage: cairn install|upgrade|doctor|uninstall|init|memory|plan|work|review|toolcheck" ;;
+      esac
+      ;;
+  esac
+}
+
+case "$cmd" in
+  install|upgrade|doctor|uninstall)
+    node "$script_dir/cairn-lifecycle.mjs" "$cmd" "$@"
+    ;;
+  init)
+    sh "$script_dir/cairn-state.sh" manual
+    ;;
+  memory)
+    say memory
+    ;;
+  plan)
+    say plan
+    ;;
+  work)
+    say work
+    ;;
+  review)
+    say review
+    ;;
+  toolcheck)
+    node "$script_dir/cairn-toolcheck.mjs" "$@"
+    ;;
+  *)
+    say usage
+    ;;
+esac

package/scripts/cairn-lifecycle.mjs

@@ -0,0 +1,343 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { cp, mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const pluginRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const codexHome = resolve(process.env.CODEX_HOME ?? join(process.env.HOME ?? ".", ".codex"));
+const claudeHome = resolve(process.env.CLAUDE_HOME ?? join(process.env.HOME ?? ".", ".claude"));
+const antigravityHome = resolve(process.env.ANTIGRAVITY_HOME ?? join(process.env.HOME ?? ".", ".agents"));
+const antigravityCliHome = resolve(process.env.ANTIGRAVITY_CLI_HOME ?? join(process.env.HOME ?? ".", ".gemini", "antigravity-cli"));
+const configPath = process.env.CODEX_CONFIG_PATH ?? join(codexHome, "config.toml");
+const marketplaceName = "cairn";
+const pluginName = "cairn";
+const marketplaceRoot = join(codexHome, "plugins", "cache", marketplaceName);
+const installedPluginRoot = join(marketplaceRoot, "plugins", pluginName);
+const marketplaceJsonPath = join(marketplaceRoot, ".agents", "plugins", "marketplace.json");
+
+if (isCliEntry()) {
+  const command = process.argv[2] ?? "help";
+  if (command === "install" || command === "upgrade") await install(command);
+  else if (command === "doctor") await doctor();
+  else if (command === "uninstall") await uninstall();
+  else help();
+}
+
+async function install(mode) {
+  await copyPlugin();
+  await writeMarketplace();
+  await installClaudeFiles();
+  await installAntigravityFiles();
+  const hookStates = await trustedHookStates();
+  const config = await readText(configPath);
+  await backupConfig();
+  await writeFile(configPath, `${updateConfig(config, hookStates).trimEnd()}\n`);
+  console.log(t(mode === "upgrade" ? "upgradeComplete" : "installComplete"));
+  console.log(`Codex plugin: ${installedPluginRoot}`);
+  console.log(`Marketplace: ${marketplaceJsonPath}`);
+  console.log(`Hook trust states: ${hookStates.length}`);
+  console.log(`Antigravity skills: ${join(antigravityHome, "skills")}`);
+}
+
+async function doctor() {
+  const checks = [];
+  checks.push(["source", await exists(join(pluginRoot, ".codex-plugin", "plugin.json"))]);
+  checks.push(["installed plugin", await exists(join(installedPluginRoot, ".codex-plugin", "plugin.json"))]);
+  checks.push(["marketplace", await exists(marketplaceJsonPath)]);
+  const installedManifest = await readJson(join(installedPluginRoot, ".codex-plugin", "plugin.json"));
+  checks.push(["installed hooks manifest field", installedManifest?.hooks === "./hooks/hooks.json"]);
+  checks.push(["hooks file", await exists(join(installedPluginRoot, "hooks", "hooks.json"))]);
+  const config = await readText(configPath);
+  checks.push(["config features.plugins", hasSetting(config, "features", "plugins", "true")]);
+  checks.push(["config features.plugin_hooks", hasSetting(config, "features", "plugin_hooks", "true")]);
+  checks.push(["config marketplace", config.includes("[marketplaces.cairn]")]);
+  checks.push(["config plugin enabled", config.includes('[plugins."cairn@cairn"]') && hasSetting(config, 'plugins."cairn@cairn"', "enabled", "true")]);
+  const expectedStates = await trustedHookStates();
+  const missingStates = expectedStates.filter((state) => !config.includes(`[hooks.state.${JSON.stringify(state.key)}]`));
+  checks.push(["trusted hook states", expectedStates.length > 0 && missingStates.length === 0]);
+  checks.push(["Claude commands", await exists(join(claudeHome, "commands", "cairn-plan.md"))]);
+  checks.push(["Claude agents", await exists(join(claudeHome, "agents", "cairn-explorer.md"))]);
+  checks.push(["Antigravity skills", await exists(join(antigravityHome, "skills", "cairn-plan", "SKILL.md"))]);
+  checks.push(["Antigravity workflows", await exists(join(antigravityHome, "workflows", "cairn-plan.md"))]);
+  checks.push(["Antigravity CLI skills", await exists(join(antigravityCliHome, "skills", "cairn-plan", "SKILL.md"))]);
+  checks.push(["Antigravity CLI workflows", await exists(join(antigravityCliHome, "workflows", "cairn-plan.md"))]);
+  for (const [name, ok] of checks) console.log(`${ok ? "OK" : "FAIL"} ${name}`);
+  if (checks.some(([, ok]) => !ok)) process.exitCode = 1;
+}
+
+async function uninstall() {
+  const config = await readText(configPath);
+  await backupConfig();
+  await writeFile(configPath, `${removeCairnConfig(config).trimEnd()}\n`);
+  await rm(marketplaceRoot, { recursive: true, force: true });
+  for (const name of commandNames()) {
+    await rm(join(claudeHome, "commands", `cairn-${name}.md`), { force: true });
+  }
+  for (const name of ["architect", "planner", "builder", "reviewer", "explorer", "worker"]) {
+    await rm(join(claudeHome, "agents", `cairn-${name}.md`), { force: true });
+  }
+  await uninstallAntigravityFiles();
+  console.log(t("uninstallComplete"));
+}
+
+async function copyPlugin() {
+  await rm(installedPluginRoot, { recursive: true, force: true });
+  await mkdir(dirname(installedPluginRoot), { recursive: true });
+  await cp(pluginRoot, installedPluginRoot, {
+    recursive: true,
+    filter: (source) => !source.includes(`${pluginRoot}/.git`) && !source.includes(`${pluginRoot}/node_modules`),
+  });
+  const manifestPath = join(installedPluginRoot, ".codex-plugin", "plugin.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  manifest.hooks = "./hooks/hooks.json";
+  await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+}
+
+async function writeMarketplace() {
+  await mkdir(dirname(marketplaceJsonPath), { recursive: true });
+  const marketplace = {
+    name: marketplaceName,
+    interface: { displayName: "Cairn" },
+    plugins: [{
+      name: pluginName,
+      source: { source: "local", path: "./plugins/cairn" },
+      policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" },
+      category: "Productivity",
+    }],
+  };
+  await writeFile(marketplaceJsonPath, `${JSON.stringify(marketplace, null, 2)}\n`);
+}
+
+async function installClaudeFiles() {
+  await mkdir(join(claudeHome, "commands"), { recursive: true });
+  await mkdir(join(claudeHome, "agents"), { recursive: true });
+  for (const name of commandNames()) {
+    await cp(join(pluginRoot, ".claude", "commands", `cairn-${name}.md`), join(claudeHome, "commands", `cairn-${name}.md`));
+  }
+  for (const name of ["explorer", "worker"]) {
+    await cp(join(pluginRoot, ".claude", "agents", `${name}.md`), join(claudeHome, "agents", `cairn-${name}.md`));
+  }
+}
+
+async function installAntigravityFiles() {
+  for (const root of [antigravityHome, antigravityCliHome]) {
+    await mkdir(join(root, "skills"), { recursive: true });
+    await mkdir(join(root, "workflows"), { recursive: true });
+    for (const name of skillNames()) {
+      await rm(join(root, "skills", name), { recursive: true, force: true });
+      await cp(join(pluginRoot, "skills", name), join(root, "skills", name), { recursive: true });
+    }
+    for (const name of commandNames()) {
+      await cp(join(pluginRoot, ".agents", "workflows", `cairn-${name}.md`), join(root, "workflows", `cairn-${name}.md`));
+    }
+  }
+}
+
+async function uninstallAntigravityFiles() {
+  for (const root of [antigravityHome, antigravityCliHome]) {
+    for (const name of skillNames()) {
+      await rm(join(root, "skills", name), { recursive: true, force: true });
+    }
+    for (const name of commandNames()) {
+      await rm(join(root, "workflows", `cairn-${name}.md`), { force: true });
+    }
+  }
+}
+
+export function updateConfig(config, hookStates) {
+  let next = removeCairnConfig(config);
+  next = ensureSetting(next, "features", "plugins", "true");
+  next = ensureSetting(next, "features", "plugin_hooks", "true");
+  next = append(next, `[marketplaces.cairn]\nlast_updated = ${JSON.stringify(new Date().toISOString().replace(/\.\d{3}Z$/, "Z"))}\nsource_type = "local"\nsource = ${JSON.stringify(marketplaceRoot)}\n`);
+  next = append(next, '[plugins."cairn@cairn"]\nenabled = true\n');
+  for (const state of hookStates) next = append(next, `[hooks.state.${JSON.stringify(state.key)}]\ntrusted_hash = ${JSON.stringify(state.trustedHash)}\n`);
+  return next;
+}
+
+export function removeCairnConfig(config) {
+  return splitSections(config).filter((section) => {
+    if (section.header === null) return true;
+    if (section.header === "marketplaces.cairn") return false;
+    if (section.header === 'plugins."cairn@cairn"') return false;
+    return !(section.header.startsWith("hooks.state.") && section.header.includes("cairn@cairn:"));
+  }).map((section) => section.text).join("").replace(/\n{3,}/g, "\n\n");
+}
+
+export function ensureSetting(config, sectionName, key, value) {
+  const sections = splitSections(config);
+  const index = sections.findIndex((section) => section.header === sectionName);
+  if (index === -1) return append(config, `[${sectionName}]\n${key} = ${value}\n`);
+  const lines = sections[index].text.trimEnd().split("\n");
+  const settingIndex = lines.findIndex((line) => line.trim().startsWith(`${key} =`));
+  if (settingIndex === -1) lines.push(`${key} = ${value}`);
+  else lines[settingIndex] = `${key} = ${value}`;
+  sections[index].text = `${lines.join("\n")}\n`;
+  return sections.map((section) => section.text).join("");
+}
+
+export function hasSetting(config, sectionName, key, value) {
+  const section = splitSections(config).find((candidate) => candidate.header === sectionName);
+  return section?.text.split("\n").some((line) => line.trim() === `${key} = ${value}`) ?? false;
+}
+
+export function splitSections(config) {
+  const result = [];
+  let current = { header: null, text: "" };
+  for (const line of config.split(/(?<=\n)/)) {
+    const match = line.trim().match(/^\[([^\]]+)\]$/);
+    if (match) {
+      if (current.text.length > 0) result.push(current);
+      current = { header: match[1], text: line };
+    } else current.text += line;
+  }
+  if (current.text.length > 0) result.push(current);
+  return result;
+}
+
+async function trustedHookStates() {
+  const hooksPath = join(installedPluginRoot, "hooks", "hooks.json");
+  const parsed = await readJson(hooksPath);
+  const states = [];
+  const labels = { SessionStart: "session_start", UserPromptSubmit: "user_prompt_submit", PostToolUse: "post_tool_use", Stop: "stop", SubagentStop: "subagent_stop" };
+  for (const [eventName, groups] of Object.entries(parsed?.hooks ?? {})) {
+    const eventLabel = labels[eventName];
+    if (!eventLabel || !Array.isArray(groups)) continue;
+    for (const [groupIndex, group] of groups.entries()) {
+      for (const [handlerIndex, handler] of (group.hooks ?? []).entries()) {
+        const key = `cairn@cairn:hooks/hooks.json:${eventLabel}:${groupIndex}:${handlerIndex}`;
+        states.push({ key, trustedHash: hookHash(eventLabel, group.matcher, handler) });
+      }
+    }
+  }
+  return states;
+}
+
+export function hookHash(eventName, matcher, handler) {
+  const normalized = { type: "command", command: handler.command, timeout: Math.max(Number(handler.timeout ?? 600), 1), async: false };
+  if (typeof handler.statusMessage === "string") normalized.statusMessage = handler.statusMessage;
+  const identity = { event_name: eventName, hooks: [normalized] };
+  if (typeof matcher === "string") identity.matcher = matcher;
+  return `sha256:${createHash("sha256").update(JSON.stringify(canonical(identity))).digest("hex")}`;
+}
+
+export function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value === null || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+}
+
+async function backupConfig() {
+  if (!(await exists(configPath))) return;
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  await cp(configPath, `${configPath}.cairn-backup-${stamp}`);
+}
+
+async function readJson(path) {
+  if (!(await exists(path))) return null;
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+async function readText(path) {
+  if (!(await exists(path))) return "";
+  return readFile(path, "utf8");
+}
+
+async function exists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function append(config, block) {
+  return `${config.trimEnd()}${config.trimEnd().length === 0 ? "" : "\n\n"}${block.trimEnd()}\n`;
+}
+
+export function commandNames() {
+  return ["install", "upgrade", "doctor", "uninstall", "memory", "plan", "work", "review", "toolcheck"];
+}
+
+export function skillNames() {
+  return ["cairn-memory", "cairn-plan", "cairn-work", "cairn-review"];
+}
+
+function help() {
+  console.log(t("usage"));
+}
+
+function t(key) {
+  const messages = {
+    en: {
+      installComplete: "Cairn install complete",
+      upgradeComplete: "Cairn upgrade complete",
+      uninstallComplete: "Cairn uninstall complete",
+      usage: "Usage: cairn install|upgrade|doctor|uninstall|toolcheck",
+    },
+    ko: {
+      installComplete: "Cairn 설치 완료",
+      upgradeComplete: "Cairn 업그레이드 완료",
+      uninstallComplete: "Cairn 언인스톨 완료",
+      usage: "사용법: cairn install|upgrade|doctor|uninstall|toolcheck",
+    },
+    ja: {
+      installComplete: "Cairn のインストールが完了しました",
+      upgradeComplete: "Cairn のアップグレードが完了しました",
+      uninstallComplete: "Cairn のアンインストールが完了しました",
+      usage: "使い方: cairn install|upgrade|doctor|uninstall|toolcheck",
+    },
+    zh: {
+      installComplete: "Cairn 安装完成",
+      upgradeComplete: "Cairn 升级完成",
+      uninstallComplete: "Cairn 卸载完成",
+      usage: "用法: cairn install|upgrade|doctor|uninstall|toolcheck",
+    },
+    es: {
+      installComplete: "Instalación de Cairn completada",
+      upgradeComplete: "Actualización de Cairn completada",
+      uninstallComplete: "Desinstalación de Cairn completada",
+      usage: "Uso: cairn install|upgrade|doctor|uninstall|toolcheck",
+    },
+    fr: {
+      installComplete: "Installation de Cairn terminée",
+      upgradeComplete: "Mise à niveau de Cairn terminée",
+      uninstallComplete: "Désinstallation de Cairn terminée",
+      usage: "Utilisation: cairn install|upgrade|doctor|uninstall|toolcheck",
+    },
+    de: {
+      installComplete: "Cairn-Installation abgeschlossen",
+      upgradeComplete: "Cairn-Upgrade abgeschlossen",
+      uninstallComplete: "Cairn-Deinstallation abgeschlossen",
+      usage: "Verwendung: cairn install|upgrade|doctor|uninstall|toolcheck",
+    },
+    pt: {
+      installComplete: "Instalação do Cairn concluída",
+      upgradeComplete: "Atualização do Cairn concluída",
+      uninstallComplete: "Desinstalação do Cairn concluída",
+      usage: "Uso: cairn install|upgrade|doctor|uninstall|toolcheck",
+    },
+  };
+  return messages[localeFamily()]?.[key] ?? messages.en[key];
+}
+
+export function localeFamily() {
+  const locale = [process.env.LC_ALL, process.env.LC_MESSAGES, process.env.LANG]
+    .find((value) => typeof value === "string" && value.length > 0) ?? Intl.DateTimeFormat().resolvedOptions().locale;
+  const normalized = locale.toLowerCase();
+  for (const family of ["ko", "ja", "zh", "es", "fr", "de", "pt"]) {
+    if (normalized.startsWith(family)) return family;
+  }
+  return "en";
+}
+
+function isCliEntry() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch {
+    return import.meta.url === pathToFileURL(process.argv[1]).href;
+  }
+}