@amsterdamdatalabs/enact-extensions 0.1.42 → 0.1.48

package/scripts/enact-extensions.mjs

@@ -1,32 +1,17 @@
 #!/usr/bin/env node
-import { resolvePluginRoot } from "./lib/resolve-plugin-root.mjs";
-import { resolveBundlePath } from "./lib/resolve-bundle.mjs";
-import { listBundles } from "./lib/list-bundles.mjs";
-import { buildIndex } from "./lib/build-index.mjs";
-import { runValidate } from "./lib/run-validate.mjs";
-import { runSync } from "./lib/run-sync.mjs";
-import { INSTALL_DRY_RUN_UNSUPPORTED_MESSAGE, runInstall } from "./lib/run-install.mjs";
-import { runUpdate } from "./lib/run-update.mjs";
-import { runPrune } from "./lib/run-prune.mjs";
-import { runUninstall } from "./lib/run-uninstall.mjs";
-import { readLedger } from "./lib/ledger.mjs";
-import { computeOutdated } from "./lib/outdated.mjs";
-import { migrateGlobalArtifacts } from "./lib/migrate-artifacts.mjs";
-import { startServer, resolveServePort } from "./lib/serve.mjs";
-import {
-  setupPrinciples,
-  removePrinciples,
-  checkPrinciples,
-  runDoctor,
-  SUPPORTED_PRINCIPLES_SURFACES,
-} from "./lib/principles.mjs";
-import { dirname, join, resolve } from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
 import { cwd as processCwd } from "node:process";
-import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
 import { Ajv } from "ajv";
 import addFormatsModule from "ajv-formats";
+import { buildIndex } from "./lib/build-index.mjs";
+import { listBundles } from "./lib/list-bundles.mjs";
+import { resolveBundlePath } from "./lib/resolve-bundle.mjs";
+import { runRepoDoctor } from "./lib/run-repo-doctor.mjs";
+import { runRepoInstall, runRepoUninstall } from "./lib/run-repo-install.mjs";
+import { runSync } from "./lib/run-sync.mjs";
+import { runValidate } from "./lib/run-validate.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = resolve(__dirname, "..");
@@ -36,57 +21,48 @@ const VERSION = PACKAGE_JSON.version ?? "unknown";
 const HELP = `enact-extensions — Enact multi-platform plugin manifests
 Version: ${VERSION}
 
+enact-extensions manages REPO-LOCAL agent setup only. It never installs
+anything into host global homes; global agent wiring belongs to enact-vps.
+install/uninstall/doctor only accept plugin names listed in
+bundled-extensions.json, which names the DEFAULT bundles. Any bundle resolvable
+by name or path can be installed or uninstalled.
+
 Usage:
   enact-extensions list [dir]             List available plugin bundles (default: bundled + cwd/extensions/)
   enact-extensions list [dir] --json      Emit machine-readable JSON array
-  enact-extensions log                    Print the install ledger (single global file), newest first
-  enact-extensions log --json             Emit the raw ledger array as JSON
-  enact-extensions outdated               Report freshness drift: installed vs canonical source (per plugin+surface)
-  enact-extensions outdated --json        Emit JSON array [{name, platform, scope, home, status, installedHash, currentHash, version}]
-  enact-extensions migrate-artifacts [--dry-run] [--json]
-                                          Rename legacy factory/loop markdown artifacts to YYMMDDHH-<slug>.md
-  enact-extensions update <name>          Refresh an outdated plugin on every surface it is installed on (ledger-driven)
-  enact-extensions update --all           Refresh EVERY outdated plugin/surface
-  enact-extensions update <name> --dry-run  Show what would be refreshed; change nothing
-  enact-extensions update --all --dry-run   Show every outdated surface that would be refreshed
-  enact-extensions prune --platform all   Remove ledger-installed plugin surfaces whose local source bundle is gone
-  enact-extensions prune --platform shared  Remove orphaned shared skill drops (explicit only)
-  enact-extensions prune --dry-run        Show orphaned surfaces that would be removed
   enact-extensions index [--out <path>]   Generate a discovery index of all bundles (generated artifact, never committed)
   enact-extensions index --out -          Print the discovery index JSON to stdout
   enact-extensions index --stdout         Alias for --out -
   enact-extensions validate [path|name]   Validate manifests (default: cwd)
   enact-extensions sync [path|name]       Sync host manifests from .agents/plugin.json (default: cwd)
   enact-extensions sync [path|name] --name <id>   Create .agents/plugin.json then sync (new plugin)
-  enact-extensions install [path|name]    Sync and install plugin into Codex-compatible homes (default: cwd)
-  enact-extensions install [path|name] --platform claude    Install to Claude Code
-  enact-extensions install [path|name] --platform cursor   Install to Cursor
-  enact-extensions install [path|name] --platform enact    Install to Enact (Codex fork)
-  enact-extensions install [path|name] --platform codex    Install to Codex (explicit)
-  enact-extensions install [path|name] --platform shared   Install skills to host-neutral .agents/skills/
-  enact-extensions install [path|name] --platform all      Install to every plugin platform (codex, claude, cursor, enact)
-  enact-extensions install [path|name] --platform claude,cursor   Install to a subset of platforms
-  enact-extensions install [path|name] --dry-run           Unsupported; exits non-zero without writing anything
-  enact-extensions install [path|name] --global            Install into the default agent home (default)
-  enact-extensions install [path|name] --local             Install into a project home under cwd (./.codex, ...)
-  enact-extensions uninstall [path|name]                   Uninstall plugin from Codex-compatible homes (default: enact)
-  enact-extensions uninstall [path|name] --platform claude    Uninstall from Claude Code
-  enact-extensions uninstall [path|name] --platform cursor   Uninstall from Cursor
-  enact-extensions uninstall [path|name] --platform enact    Uninstall from Enact (Codex fork)
-  enact-extensions uninstall [path|name] --platform codex    Uninstall from Codex (explicit)
-  enact-extensions uninstall [path|name] --platform shared   Remove skills from host-neutral .agents/skills/
-  enact-extensions uninstall [path|name] --platform all      Uninstall from every plugin platform
-  enact-extensions uninstall [path|name] --platform claude,cursor   Uninstall from a subset of platforms
-  enact-extensions serve [--port N] [--prod] [--host 127.0.0.1] [--open]  Start the localhost management UI + API (dev 43217 / prod 53217)
-  enact-extensions principles setup [--surfaces <list>|--all] [--remove] [--local]
-                                          Inject (or remove) the enact-core operating-principles block
-                                          into host agent files (CLAUDE.md / AGENTS.md).
-  enact-extensions principles check [--surfaces <list>|--all] [--local] [--json]
-                                          Report principles block drift per surface (present/missing/stale).
-                                          Use principles setup or doctor --fix to remediate. Not npm run check:principles.
-  enact-extensions doctor [--fix] [--surfaces <list>|--all] [--local] [--json]
-                                          Check operating-principles block drift per surface; --fix applies blocks.
-  enact-extensions -v | --version                        Print version and exit
+  enact-extensions install <name> --repo <path> [--host claude,codex,cursor,kimi,opencode] [--force]
+                                          Install a bundle INTO a git repo as committed, relative files
+                                          (per-host project standard; state in .agents/<name>.lock.json)
+  enact-extensions install <name> --repo <path> --dry-run  Print exactly what install would write/merge, per
+                                          file (action + reason), and exit with the same success/failure
+                                          the real run would have. Touches nothing.
+  enact-extensions uninstall <name> --repo <path> [--purge] [--force]
+                                          Remove exactly what the repo lock records (--purge also removes
+                                          the [extensions] block install wrote to enact-config.toml, and the
+                                          file itself if install created it and only version = 1 remains)
+  enact-extensions uninstall <name> --repo <path> --dry-run [--purge]
+                                          Print exactly what uninstall would remove/restore, per file
+                                          (action + reason), and exit with the same success/failure the
+                                          real run would have. Touches nothing.
+  enact-extensions doctor enact-repo --repo <path> [--json]
+                                          Read-only health check for a repo-local enact-repo install:
+                                          installed?, version vs bundle (outdated?), lock integrity
+                                          (missing/drifted managed files), per-host status (claude,
+                                          codex incl. trust_level, cursor, kimi incl. workspace-trust,
+                                          opencode), required global binaries on PATH, the
+                                          enact-config.toml marker ([extensions] present; a stale
+                                          .agents/enact-repo.toml is reported), an "enact-hook doctor
+                                          --repo" passthrough when available, and the enact-hook
+                                          deny/activity log paths, existence, row counts, and (deny
+                                          log) the last 5 rows. Never writes anything; exits non-zero
+                                          only when a hard requirement fails.
+  enact-extensions -v | --version         Print version and exit
 
 Options:
   path|name  Plugin root path, or a bare plugin name resolved from bundled extensions.
@@ -94,65 +70,77 @@ Options:
   --out <path>             (index only) Output file path. Use - or --stdout to print to stdout.
                            Default: generated/index.json under the package root.
   --stdout                 (index only) Alias for --out -.
-  --json                   (list only) Emit a JSON array to stdout instead of a human table.
-  --platform <name>        Target platform: codex (default), claude, cursor, enact, shared.
-                           Use "all" to install to every plugin platform, or a comma-separated list
-                           (e.g. "claude,cursor") to install to a named subset.
-  --global                 Install into the agent's default home (default)
-  --local                  Install into a project-scoped home under the current dir
-  --codex-home <path>      Install only into the given Codex-compatible home
-  --enact-home <path>      Target a specific local Enact home (default: ~/.enact/agent)
-  --claude-home <path>     Target a specific local Claude home (default: ~/.claude)
-  --cursor-home <path>     Target a specific local Cursor home (default: ~/.cursor)
-  --shared-home <path>     Base dir for shared install (skills land at <path>/.agents/skills/)
-  --marketplace <name>     Marketplace name (default: enact-os-plugins)
-  --no-enable              Install files without enabling the Codex/Enact plugin
-  --skip-sync              Install current manifests without regenerating them
-  --no-provision           Skip auto-provisioning the bundle's MCP-server packages.
-                           By default, install resolves each declared MCP server
-                           (.mcp.json) and provisions its package: uvx → uv tool
-                           install, npx → npm install -g, pipx → pipx install,
-                           pip/pip3 → pip install. Best-effort; never fails install.
+  --json                   (list/doctor) Emit JSON to stdout instead of human output.
+  --name <id>              (sync only) Plugin name for a new .agents/plugin.json.
+  --repo <path>            (install/uninstall/doctor) Target the git repository root at <path>.
+                           Never writes under $HOME; never writes absolute paths.
+  --host <list>            (install --repo) Hosts to install for: claude,codex,cursor,kimi,opencode
+                           (default: every repo host the bundle targets).
+  --dry-run                (install/uninstall --repo) Print exactly what would change, per file, and
+                           exit with the same success/failure the real run would have. Writes nothing.
+  --force                  (install/uninstall --repo) Overwrite user-edited managed content and take over
+                           same-named entries not owned by the bundle. Never overwrites a user skill dir.
+  --purge                  (uninstall --repo) Also remove the [extensions] block install wrote to enact-config.toml.
 
 Name resolution (bare plugin names):
   When a bare name (no "/" in it) is given, it is resolved in this order:
-    1. <this-package-root>/extensions/<name>  (bundled extensions in this repo)
+    1. <this-package-root>/extensions/<name>  (bundled extensions in this package)
     2. <cwd>/extensions/<name>                (extensions in a sibling product repo)
     3. <npm-global-root>/@amsterdamdatalabs/enact-extensions/extensions/<name>
 
-Multi-platform notes:
-  - Platforms are installed sequentially in deterministic order: codex, claude, cursor, enact.
-  - Per-platform --<platform>-home flags apply to their respective platform in a multi-target run.
-  - If any platform fails, the others still proceed; a non-zero exit is returned and the summary
-    of succeeded/failed platforms is printed to stderr.
-
 Examples:
   enact-extensions list
   enact-extensions list --json
-  enact-extensions list /path/to/extensions
-  enact-extensions index                   Generate generated/index.json (gitignored, local discovery artifact)
   enact-extensions index --out -           Print discovery index JSON to stdout (pipe-friendly)
-  enact-extensions index --stdout          Same as --out -
-  enact-extensions index --out /tmp/my-index.json
-  cd extensions/enact-factory && enact-extensions validate
-  enact-extensions sync . --name my-plugin
-  enact-extensions install net-revenue-management --platform enact --global
-  enact-extensions install net-revenue-management --platform enact --local
-  enact-extensions install extensions/net-revenue-management --platform enact --global
-  enact-extensions install enact-factory --platform claude
-  enact-extensions install enact-factory --platform cursor
-  enact-extensions install net-revenue-management --platform shared
-  enact-extensions install net-revenue-management --platform shared --local
-  enact-extensions install net-revenue-management --platform all
-  enact-extensions install net-revenue-management --platform claude,cursor
-  enact-extensions install net-revenue-management --platform all --enact-home /path/to/enact
+  cd extensions/enact-repo && enact-extensions validate
   enact-extensions validate extensions/plugin-dev
-  enact-extensions validate plugin-dev
+  enact-extensions sync . --name my-plugin
+  enact-extensions install enact-repo --repo .
+  enact-extensions install enact-repo --repo ~/code/my-service --host claude,cursor
+  enact-extensions install enact-repo --repo . --dry-run       Preview the plan; writes nothing
+  enact-extensions uninstall enact-repo --repo . --purge
+  enact-extensions uninstall enact-repo --repo . --dry-run     Preview what would be removed/restored
+  enact-extensions doctor enact-repo --repo .                  Read-only health check
+  enact-extensions doctor enact-repo --repo . --json
 `;
 
+const COMMANDS = new Set(["list", "index", "validate", "sync", "install", "uninstall", "doctor"]);
+const REPO_USAGE_HINT =
+  "enact-extensions only performs repo-local installs: install|uninstall <name> --repo <path> " +
+  "[--host claude,codex,cursor,kimi,opencode]; doctor enact-repo --repo <path>. " +
+  "Global host installs were removed (global agent wiring belongs to enact-vps).";
+
+/**
+ * Unwinds to the top of the module so node can exit on its own.
+ *
+ * `exit()` must not be used here: `process.stdout` is ASYNCHRONOUS
+ * when it is a pipe -- under a test harness, under CI, or whenever a user
+ * pipes output into a file or a pager -- and exiting discards whatever is
+ * still queued. `install --repo --dry-run` prints ~1500 lines, and calling
+ * exit on the next statement silently cut the tail off on Linux agents while
+ * appearing fine on a fast local flush.
+ */
+class ExitSignal extends Error {
+  constructor(code) {
+    super(`exit ${code}`);
+    this.name = "ExitSignal";
+    this.code = code;
+  }
+}
+
+function exit(code) {
+  throw new ExitSignal(code);
+}
+
+function fail(message) {
+  console.error(message);
+  exit(1);
+}
+
 function parseArgs(argv) {
   const positional = [];
   const options = {};
+  const unknown = [];
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
@@ -162,988 +150,405 @@ function parseArgs(argv) {
       options.out = "-";
     } else if (arg === "--name" && argv[i + 1]) {
       options.name = argv[++i];
-    } else if (arg === "--codex-home" && argv[i + 1]) {
-      options.codexHome = argv[++i];
-    } else if (arg === "--marketplace" && argv[i + 1]) {
-      options.marketplaceName = argv[++i];
-    } else if (arg === "--no-enable") {
-      options.enable = false;
-    } else if (arg === "--skip-sync") {
-      options.sync = false;
-    } else if (arg === "--no-provision") {
-      options.noProvision = true;
-    } else if (arg === "--platform" && argv[i + 1]) {
-      options.platform = argv[++i];
-    } else if (arg === "--claude-home" && argv[i + 1]) {
-      options.claudeHome = argv[++i];
-    } else if (arg === "--cursor-home" && argv[i + 1]) {
-      options.cursorHome = argv[++i];
-    } else if (arg === "--enact-home" && argv[i + 1]) {
-      options.enactHome = argv[++i];
-    } else if (arg === "--shared-home" && argv[i + 1]) {
-      options.sharedHome = argv[++i];
-    } else if (arg === "--local") {
-      options.scope = "local";
-    } else if (arg === "--global") {
-      options.scope = "global";
-    } else if (arg === "--all") {
-      options.all = true;
+    } else if (arg === "--repo" && argv[i + 1]) {
+      options.repo = argv[++i];
+    } else if (arg === "--host" && argv[i + 1]) {
+      options.host = argv[++i];
+    } else if (arg === "--force") {
+      options.force = true;
+    } else if (arg === "--purge") {
+      options.purge = true;
     } else if (arg === "--dry-run") {
       options.dryRun = true;
     } else if (arg === "--json") {
       options.json = true;
-    } else if (arg === "--port" && argv[i + 1]) {
-      options.port = parseInt(argv[++i], 10);
-    } else if (arg === "--host" && argv[i + 1]) {
-      options.host = argv[++i];
-    } else if (arg === "--open") {
-      options.open = true;
-    } else if (arg === "--prod") {
-      options.prod = true;
-    } else if (arg === "--surfaces" && argv[i + 1]) {
-      // Comma-separated list of surfaces: claude,codex,cursor,enact
-      options.surfaces = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
-    } else if (arg === "--remove") {
-      options.remove = true;
-    } else if (arg === "--fix") {
-      options.fix = true;
     } else if (arg === "-h" || arg === "--help") {
       positional.push("help");
-    } else if (!arg.startsWith("-")) {
+    } else if (arg.startsWith("-")) {
+      unknown.push(arg);
+    } else {
       positional.push(arg);
     }
   }
 
-  return { command: positional[0], path: positional[1], options };
-}
-
-const rawArgv = process.argv.slice(2);
-if (rawArgv.length === 1 && (rawArgv[0] === "-v" || rawArgv[0] === "--version")) {
-  console.log(`enact-extensions ${VERSION}`);
-  process.exit(0);
+  return { command: positional[0], path: positional[1], options, unknown };
 }
 
-const { command, path, options } = parseArgs(rawArgv);
-
-if (!command || command === "help") {
-  console.log(HELP);
-  process.exit(command ? 0 : 1);
-}
+try {
+  const rawArgv = process.argv.slice(2);
+  if (rawArgv.length === 1 && (rawArgv[0] === "-v" || rawArgv[0] === "--version")) {
+    console.log(`enact-extensions ${VERSION}`);
+    exit(0);
+  }
 
-// ---------------------------------------------------------------------------
-// `hooks` command — register or remove the session-start drift-check hook.
-//
-// Surfaces: claude, codex, cursor, enact
-// Registration is idempotent and reversible.
-// ---------------------------------------------------------------------------
-// ---------------------------------------------------------------------------
-// `principles` command — inject or check operating-principles blocks in host files.
-//
-// Surfaces: claude, codex, cursor, enact
-// ---------------------------------------------------------------------------
-if (command === "principles") {
-  const subCommand = path ?? "setup";
+  const { command, path, options, unknown } = parseArgs(rawArgv);
 
-  if (subCommand !== "setup" && subCommand !== "check") {
-    process.stderr.write(
-      `[enact-extensions principles] Unknown sub-command: ${subCommand}. Use 'setup' or 'check'.\n`,
-    );
-    process.exit(1);
+  if (!command || command === "help") {
+    console.log(HELP);
+    exit(command ? 0 : 1);
   }
 
-  const isRemove = options.remove ?? false;
-  const isLocal = options.scope === "local";
-  const cwd = processCwd();
-  const surfacesList = SUPPORTED_PRINCIPLES_SURFACES;
-
-  let surfaces = [];
-  if (options.all) {
-    surfaces = [...surfacesList];
-  } else if (options.surfaces && options.surfaces.length > 0) {
-    const invalid = options.surfaces.filter((s) => !surfacesList.includes(s));
-    if (invalid.length > 0) {
-      process.stderr.write(
-        `[enact-extensions principles] Unknown surface(s): ${invalid.join(", ")}. Valid: ${surfacesList.join(", ")}\n`,
-      );
-      process.exit(1);
-    }
-    surfaces = options.surfaces;
-  } else if (subCommand === "setup" && process.stdin.isTTY) {
-    const { createInterface } = await import("node:readline");
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    const question = (prompt) => new Promise((resolve) => rl.question(prompt, resolve));
+  if (!COMMANDS.has(command)) {
+    console.error(`Unknown command: ${command}\n\n${REPO_USAGE_HINT}\nRun enact-extensions --help for usage.`);
+    exit(1);
+  }
 
-    process.stdout.write(`\nenact-extensions principles setup — interactive surface picker\n`);
-    process.stdout.write(`Available surfaces: ${surfacesList.map((s, i) => `${i + 1}. ${s}`).join(", ")}\n`);
-    process.stdout.write(`Enter surface names or numbers (comma-separated), or 'all':\n`);
+  if (unknown.length > 0) {
+    fail(`Unknown option(s) for ${command}: ${unknown.join(", ")}\n${REPO_USAGE_HINT}`);
+  }
 
-    const answer = await question("> ");
-    rl.close();
+  if ((command === "install" || command === "uninstall") && !options.repo) {
+    fail(`${command} requires --repo <path>.\n${REPO_USAGE_HINT}`);
+  }
 
-    if (answer.trim().toLowerCase() === "all") {
-      surfaces = [...surfacesList];
-    } else {
-      surfaces = answer
-        .split(",")
-        .map((s) => s.trim())
-        .filter(Boolean)
-        .map((s) => {
-          const idx = parseInt(s, 10);
-          if (!isNaN(idx) && idx >= 1 && idx <= surfacesList.length) {
-            return surfacesList[idx - 1];
-          }
-          return s.toLowerCase();
-        })
-        .filter((s) => surfacesList.includes(s));
+  if (
+    !["install", "uninstall"].includes(command) &&
+    (options.force || options.purge || options.host || options.dryRun)
+  ) {
+    fail("--host/--force/--purge/--dry-run only apply to install|uninstall <name> --repo <path>");
+  }
 
-      if (surfaces.length === 0) {
-        process.stderr.write(`[enact-extensions principles] No valid surfaces selected. Exiting.\n`);
-        process.exit(0);
-      }
+  function printRepoDoctorReport(report) {
+    const ok = (b) => (b ? "OK" : "FAIL");
+    console.log(`[doctor enact-repo] repo: ${report.repo}`);
+    console.log(`  installed: ${report.installed ? "yes" : "NO"}`);
+    if (!report.installed) {
+      for (const p of report.problems) console.error(`  problem: ${p}`);
+      return;
     }
-  } else {
-    process.stdout.write(
-      `[enact-extensions principles] No surface specified. Run with --surfaces or --all:\n` +
-      `  enact-extensions principles ${subCommand} --surfaces claude,codex\n` +
-      `  enact-extensions principles ${subCommand} --all\n`,
+    console.log(
+      `  version: installed=${report.version.installed} bundle=${report.version.bundle ?? "(unknown)"} outdated=${report.version.outdated ? "YES" : "no"}`,
     );
-    process.exit(0);
-  }
-
-  const principleOpts = {
-    claudeHome: options.claudeHome,
-    codexHome: options.codexHome,
-    cursorHome: options.cursorHome,
-    enactHome: options.enactHome,
-    local: isLocal,
-    cwd,
-  };
-
-  let exitCode = 0;
-
-  if (subCommand === "check") {
-    const rows = [];
-    for (const surface of surfaces) {
-      try {
-        const res = checkPrinciples(surface, principleOpts);
-        rows.push(res);
-        if (!options.json) {
-          process.stdout.write(
-            `  [principles] ${surface}: ${res.status} → ${res.path}\n`,
-          );
-        }
-      } catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        rows.push({ surface, path: "", status: "error", error: message });
-        process.stderr.write(`  [principles] ${surface}: error — ${message}\n`);
-      }
+    if (report.version.contentOutdated.length > 0) {
+      console.log(
+        `    content drifted from current bundle (${report.version.contentOutdated.length}): ${report.version.contentOutdated.join(", ")}`,
+      );
     }
-
-    if (options.json) {
-      console.log(JSON.stringify(rows, null, 2));
+    if (report.version.note) console.log(`    note: ${report.version.note}`);
+
+    console.log(`  lock integrity: ${ok(report.lock.valid)}`);
+    if (!report.lock.valid) {
+      if (report.lock.missingFiles.length) console.log(`    missing: ${report.lock.missingFiles.join(", ")}`);
+      if (report.lock.driftedFiles.length) console.log(`    drifted: ${report.lock.driftedFiles.join(", ")}`);
+      if (report.lock.jsonIssues.length) console.log(`    json: ${report.lock.jsonIssues.join(", ")}`);
+      if (report.lock.tomlIssues.length) console.log(`    toml: ${report.lock.tomlIssues.join(", ")}`);
     }
 
-    process.exit(0);
-  }
-
-  for (const surface of surfaces) {
-    try {
-      const res = isRemove
-        ? removePrinciples(surface, principleOpts)
-        : setupPrinciples(surface, principleOpts);
-
-      if (res.result === "applied") {
-        process.stdout.write(
-          `  [principles] ${surface}: applied (${res.action}) → ${res.path}\n`,
-        );
-      } else if (res.result === "already_present") {
-        process.stdout.write(
-          `  [principles] ${surface}: already present (noop) → ${res.path}\n`,
-        );
-      } else if (res.result === "removed") {
-        process.stdout.write(`  [principles] ${surface}: removed → ${res.path}\n`);
-      } else if (res.result === "not_found") {
-        process.stdout.write(
-          `  [principles] ${surface}: not found (nothing to remove) → ${res.path}\n`,
+    for (const [host, info] of Object.entries(report.hosts)) {
+      console.log(`  host ${host}: targeted=${info.targeted} present=${info.targeted ? ok(info.present) : "n/a"}`);
+      if (info.note) console.log(`    ${info.note}`);
+      if (info.trust) {
+        console.log(
+          `    codex trust_level: ${info.trust.trustLevel ?? "(none)"}${info.trust.note ? ` -- ${info.trust.note}` : ""}`,
         );
       }
-    } catch (err) {
-      exitCode = 1;
-      const message = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`  [principles] ${surface}: error — ${message}\n`);
-    }
-  }
-
-  process.exit(exitCode);
-}
-
-// ---------------------------------------------------------------------------
-// `doctor` command — check (and optionally fix) operating-principles drift.
-//
-// Surfaces: claude, codex, cursor, enact (defaults to all when omitted)
-// ---------------------------------------------------------------------------
-if (command === "doctor") {
-  const isFix = options.fix ?? false;
-  const isLocal = options.scope === "local";
-  const cwd = processCwd();
-  const surfacesList = SUPPORTED_PRINCIPLES_SURFACES;
-
-  let surfaces = [];
-  if (options.all || !options.surfaces || options.surfaces.length === 0) {
-    surfaces = [...surfacesList];
-  } else {
-    const invalid = options.surfaces.filter((s) => !surfacesList.includes(s));
-    if (invalid.length > 0) {
-      process.stderr.write(
-        `[enact-extensions doctor] Unknown surface(s): ${invalid.join(", ")}. Valid: ${surfacesList.join(", ")}\n`,
-      );
-      process.exit(1);
-    }
-    surfaces = options.surfaces;
-  }
-
-  const principleOpts = {
-    claudeHome: options.claudeHome,
-    codexHome: options.codexHome,
-    cursorHome: options.cursorHome,
-    enactHome: options.enactHome,
-    local: isLocal,
-    cwd,
-    fix: isFix,
-  };
-
-  const { rows, exitCode } = runDoctor(surfaces, principleOpts);
-
-  if (!options.json) {
-    for (const row of rows) {
-      if (row.error) {
-        process.stderr.write(`  [doctor] ${row.surface}: error — ${row.error}\n`);
-        continue;
+      if (info.globalHooksNote) console.log(`    ${info.globalHooksNote}`);
+      if (info.workspaceTrust) {
+        console.log(
+          `    kimi workspace trust: ${info.workspaceTrust.trusted ? "TRUSTED" : "NOT TRUSTED"}${info.workspaceTrust.note ? ` -- ${info.workspaceTrust.note}` : ""}`,
+        );
       }
-      if (isFix) {
-        const note = row.result === "already_present"
-          ? "already present (noop)"
-          : `fixed (${row.action ?? row.result})`;
-        process.stdout.write(`  [doctor] ${row.surface}: ${row.status} — ${note} → ${row.path}\n`);
-      } else {
-        process.stdout.write(`  [doctor] ${row.surface}: ${row.status} → ${row.path}\n`);
+      if (host === "opencode" && info.targeted) {
+        console.log(
+          `    generated from current bundle: ${info.generatedFromCurrentBundle === false ? "NO (stale)" : info.generatedFromCurrentBundle === true ? "yes" : "n/a"}`,
+        );
       }
     }
-    if (!isFix && exitCode !== 0) {
-      process.stderr.write(
-        `[enact-extensions doctor] Drift detected. Fix with: enact-extensions doctor --fix --all\n`,
-      );
-    }
-  } else {
-    console.log(JSON.stringify(rows, null, 2));
-  }
 
-  process.exit(exitCode);
-}
-
-// ---------------------------------------------------------------------------
-// `list` command — enumerate available plugin bundles.
-// ---------------------------------------------------------------------------
-if (command === "list") {
-  // The package's own extensions/ dir, resolved relative to this script.
-  const PACKAGE_ROOT = resolve(__dirname, "..");
-  const packageExtensions = join(PACKAGE_ROOT, "extensions");
-
-  let roots;
-  if (path) {
-    // Explicit dir argument → scan only that dir.
-    roots = [resolve(processCwd(), path)];
-  } else {
-    // Default: package-bundled extensions/ + cwd/extensions/ (if it differs).
-    roots = [packageExtensions];
-    const cwdExtensions = join(processCwd(), "extensions");
-    if (resolve(cwdExtensions) !== resolve(packageExtensions) && existsSync(cwdExtensions)) {
-      roots.push(cwdExtensions);
+    console.log("  binaries:");
+    for (const [bin, info] of Object.entries(report.binaries)) {
+      console.log(`    ${bin}: ${info.found ? `${info.version ?? "(unknown version)"} @ ${info.path}` : "NOT FOUND"}`);
     }
-  }
-
-  const entries = listBundles(roots);
-
-  if (options.json) {
-    console.log(JSON.stringify(entries, null, 2));
-    process.exit(0);
-  }
-
-  // Human-readable table.
-  const TRUNC = 60;
-  function trunc(str, len) {
-    if (!str) return "";
-    return str.length > len ? str.slice(0, len - 1) + "…" : str;
-  }
 
-  if (entries.length === 0) {
-    console.log("No plugin bundles found.");
-    process.exit(0);
-  }
-
-  // Header.
-  const COL_NAME = 28;
-  const COL_VER  = 8;
-  const COL_CAT  = 18;
-  const COL_SURF = 22;
-
-  function padR(str, n) { return String(str ?? "").padEnd(n).slice(0, n); }
-
-  const hr = "─".repeat(COL_NAME + COL_VER + COL_CAT + COL_SURF + 3 + TRUNC);
-  console.log(hr);
-  console.log(
-    padR("Name", COL_NAME) + "  " +
-    padR("Ver", COL_VER) + "  " +
-    padR("Category", COL_CAT) + "  " +
-    padR("Surfaces", COL_SURF) + "  " +
-    "Description"
-  );
-  console.log(hr);
-
-  for (const e of entries) {
-    const surfaces = e.targets.join(", ");
     console.log(
-      padR(e.name, COL_NAME) + "  " +
-      padR(e.version, COL_VER) + "  " +
-      padR(e.category, COL_CAT) + "  " +
-      padR(surfaces, COL_SURF) + "  " +
-      trunc(e.description, TRUNC)
+      `  marker (${report.marker.path}): ${ok(report.marker.valid)}${report.marker.note ? ` -- ${report.marker.note}` : ""}`,
     );
-  }
-  console.log(hr);
-  console.log(`${entries.length} bundle${entries.length === 1 ? "" : "s"} found.`);
-  process.exit(0);
-}
-
-// ---------------------------------------------------------------------------
-// `index` command — generate a discovery index of all plugin bundles.
-//
-// The index is a LOCAL GENERATED ARTIFACT (never committed). The generated/
-// directory is gitignored. The schema at spec/index.json is the committed
-// contract. No network, no marketplace, no catalog/ — purely local.
-// ---------------------------------------------------------------------------
-if (command === "index") {
-  const PACKAGE_ROOT = resolve(__dirname, "..");
-  const packageExtensions = join(PACKAGE_ROOT, "extensions");
-
-  // Same default roots as `list`.
-  const roots = [packageExtensions];
-  const cwdExtensions = join(processCwd(), "extensions");
-  if (resolve(cwdExtensions) !== resolve(packageExtensions) && existsSync(cwdExtensions)) {
-    roots.push(cwdExtensions);
-  }
-
-  // Build the index. The wall-clock timestamp is computed here at the CLI
-  // boundary and passed in — buildIndex itself stays pure (never calls Date).
-  let index;
-  try {
-    index = buildIndex(roots, { now: new Date().toISOString(), packageRoot: PACKAGE_ROOT });
-  } catch (err) {
-    console.error(`[enact-extensions index] Failed to build index: ${err instanceof Error ? err.message : String(err)}`);
-    process.exit(1);
-  }
-
-  // Validate against spec/index.json before writing.
-  const schemaPath = join(PACKAGE_ROOT, "spec", "index.json");
-  let schema;
-  try {
-    schema = JSON.parse(readFileSync(schemaPath, "utf8"));
-  } catch (err) {
-    console.error(`[enact-extensions index] Cannot read schema ${schemaPath}: ${err instanceof Error ? err.message : String(err)}`);
-    process.exit(1);
-  }
-
-  const addFormats = addFormatsModule.default ?? addFormatsModule;
-  const ajv = new Ajv({ allErrors: true, strict: false });
-  addFormats(ajv);
-  const validate = ajv.compile(schema);
-  const valid = validate(index);
-  if (!valid) {
-    const errs = (validate.errors ?? []).map((e) => `  ${e.instancePath || "/"}: ${e.message}`).join("\n");
-    console.error(`[enact-extensions index] Generated index failed schema validation:\n${errs}`);
-    process.exit(1);
-  }
-
-  const json = JSON.stringify(index, null, 2);
-  // --stdout is normalized to "-" during arg parsing, so this single check covers both.
-  const toStdout = options.out === "-";
-
-  if (toStdout) {
-    // Write JSON to stdout; summary to stderr (keeps stdout pipe-clean).
-    process.stdout.write(json + "\n");
-    process.stderr.write(`[enact-extensions index] ${index.count} plugin${index.count === 1 ? "" : "s"} indexed.\n`);
-  } else {
-    const outPath = options.out
-      ? resolve(processCwd(), options.out)
-      : join(PACKAGE_ROOT, "generated", "index.json");
-
-    // Ensure parent directory exists.
-    const outDir = resolve(outPath, "..");
-    mkdirSync(outDir, { recursive: true });
-
-    writeFileSync(outPath, json + "\n", "utf8");
-    process.stderr.write(`[enact-extensions index] Wrote ${index.count} plugin${index.count === 1 ? "" : "s"} to ${outPath}\n`);
-  }
-
-  process.exit(0);
-}
-
-// ---------------------------------------------------------------------------
-// `log` command — print the install ledger (single global file), newest first.
-//
-// Human table to stdout (chrome to stderr) or `--json` (raw ledger array).
-// Reading a missing ledger yields an empty list — never an error.
-// ---------------------------------------------------------------------------
-if (command === "log") {
-  const entries = readLedger();
-  // Most-recent-first.
-  const sorted = [...entries].sort((a, b) =>
-    String(b.ts ?? "").localeCompare(String(a.ts ?? "")),
-  );
-
-  if (options.json) {
-    process.stdout.write(JSON.stringify(sorted, null, 2) + "\n");
-    process.exit(0);
-  }
-
-  if (sorted.length === 0) {
-    process.stderr.write("No install ledger entries found.\n");
-    process.exit(0);
-  }
+    if (report.staleMarker.present)
+      console.log(`  stale marker (${report.staleMarker.path}): ${report.staleMarker.note}`);
 
-  const COL_TS = 24;
-  const COL_ACT = 10;
-  const COL_NAME = 28;
-  const COL_PLAT = 8;
-  const COL_SCOPE = 7;
-  function padR(str, n) { return String(str ?? "").padEnd(n).slice(0, n); }
-
-  const hr = "─".repeat(COL_TS + COL_ACT + COL_NAME + COL_PLAT + COL_SCOPE + 4 + 40);
-  console.log(hr);
-  console.log(
-    padR("Timestamp", COL_TS) + " " +
-    padR("Action", COL_ACT) + " " +
-    padR("Name", COL_NAME) + " " +
-    padR("Platform", COL_PLAT) + " " +
-    padR("Scope", COL_SCOPE) + " " +
-    "Home",
-  );
-  console.log(hr);
-  for (const e of sorted) {
-    console.log(
-      padR(e.ts, COL_TS) + " " +
-      padR(e.action, COL_ACT) + " " +
-      padR(e.name, COL_NAME) + " " +
-      padR(e.platform, COL_PLAT) + " " +
-      padR(e.scope, COL_SCOPE) + " " +
-      String(e.home ?? ""),
-    );
-  }
-  console.log(hr);
-  process.stderr.write(`${sorted.length} ledger entr${sorted.length === 1 ? "y" : "ies"}.\n`);
-  process.exit(0);
-}
-
-// ---------------------------------------------------------------------------
-// `outdated` command — report drift between installed plugins and canonical source.
-//
-// Classifies each installed (plugin, platform) surface as:
-//   fresh    → installed hash matches canonical source hash
-//   outdated → hash mismatch (or recorded hash missing), needs re-install
-//   orphaned → canonical source does not exist (can't refresh)
-//
-// Exit code: always 0 (it's a report, not a failure gate).
-// Human chrome → stderr; --json stdout is always pure JSON.
-// ---------------------------------------------------------------------------
-if (command === "outdated") {
-  let entries;
-  try {
-    entries = computeOutdated({ cwd: processCwd() });
-  } catch (err) {
-    process.stderr.write(
-      `[enact-extensions outdated] Error: ${err instanceof Error ? err.message : String(err)}\n`,
-    );
-    process.exit(1);
-  }
-
-  if (options.json) {
-    process.stdout.write(JSON.stringify(entries, null, 2) + "\n");
-    process.exit(0);
-  }
-
-  // Human-readable table.
-  if (entries.length === 0) {
-    process.stderr.write("No installed plugins found in the ledger.\n");
-    process.exit(0);
-  }
-
-  const COL_NAME  = 30;
-  const COL_PLAT  = 10;
-  const COL_SCOPE = 8;
-  const COL_VER   = 10;
-  const COL_STAT  = 10;
-
-  function padR(str, n) { return String(str ?? "").padEnd(n).slice(0, n); }
-
-  const hr = "─".repeat(COL_NAME + COL_PLAT + COL_SCOPE + COL_VER + COL_STAT + 4 + 8);
-  console.log(hr);
-  console.log(
-    padR("Plugin", COL_NAME) + "  " +
-    padR("Platform", COL_PLAT) + "  " +
-    padR("Scope", COL_SCOPE) + "  " +
-    padR("Version", COL_VER) + "  " +
-    padR("Status", COL_STAT),
-  );
-  console.log(hr);
-
-  for (const e of entries) {
     console.log(
-      padR(e.name, COL_NAME) + "  " +
-      padR(e.platform, COL_PLAT) + "  " +
-      padR(e.scope, COL_SCOPE) + "  " +
-      padR(e.version, COL_VER) + "  " +
-      padR(e.status, COL_STAT),
+      `  enact-hook doctor --repo: ${report.hookDoctor.available ? `exit ${report.hookDoctor.exitCode}` : `not available -- ${report.hookDoctor.note}`}`,
     );
-  }
-  console.log(hr);
-  process.stderr.write(`${entries.length} surface${entries.length === 1 ? "" : "s"} checked.\n`);
-  process.exit(0);
-}
-
-// ---------------------------------------------------------------------------
-// `migrate-artifacts` command — rename legacy global markdown artifacts.
-if (command === "migrate-artifacts") {
-  try {
-    const report = migrateGlobalArtifacts({ dryRun: Boolean(options.dryRun) });
-    if (options.json) {
-      process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-    } else {
-      const factoryRenamed = report.factory.flatMap((entry) => entry.renamed);
-      const loopRenamed = report.loop.flatMap((entry) => entry.renamed);
-      if (factoryRenamed.length === 0 && loopRenamed.length === 0) {
-        process.stdout.write("✓ no legacy markdown artifacts to migrate\n");
+    if (report.hookDoctor.available && report.hookDoctor.stdout) {
+      for (const line of report.hookDoctor.stdout.trim().split("\n")) {
+        if (line) console.log(`    ${line}`);
       }
-      for (const { from, to } of factoryRenamed) {
-        process.stdout.write(`✓ factory ${from} → ${to}\n`);
-      }
-      for (const { from, to } of loopRenamed) {
-        process.stdout.write(`✓ loop ${from} → ${to}\n`);
-      }
-      if (report.fallbacks.length > 0) {
-        process.stderr.write(
-          `· ${report.fallbacks.length} ISO-date rename(s) used hour fallback — see --json for details\n`,
-        );
+    }
+
+    if (report.hookLogs) {
+      const { denyLog, activityLog } = report.hookLogs;
+      console.log(
+        `  hook logs: ${denyLog.path} ${denyLog.exists ? `(${denyLog.rowCount} row(s))` : "(not present)"}; ${activityLog.path} ${activityLog.exists ? `(${activityLog.rowCount} row(s))` : "(not present)"}`,
+      );
+      if (denyLog.lastRows.length > 0) {
+        console.log(`    last ${denyLog.lastRows.length} deny row(s):`);
+        for (const row of denyLog.lastRows) {
+          console.log(`      ${row.timestamp} ${row.surface} ${row.reason_id} ${row.command} ${row.agent_message}`);
+        }
       }
     }
-    process.exit(0);
-  } catch (err) {
-    process.stderr.write(
-      `[enact-extensions migrate-artifacts] Error: ${err instanceof Error ? err.message : String(err)}\n`,
-    );
-    process.exit(1);
-  }
-}
 
-// `update` command — refresh outdated installed plugins, driven by the ledger.
-//
-// Re-installs each OUTDATED (plugin, surface, home) to the EXACT surface + home
-// recorded in the ledger — never to a surface the plugin isn't already on.
-//
-//   update <name>   → refresh only that plugin (across its installed surfaces)
-//   update --all    → refresh every outdated surface
-//   update --dry-run→ report what WOULD change; touch nothing
-//
-// Exit code: non-zero ONLY on a real install failure or a missing target (no
-// name + no --all). Orphaned and fresh surfaces are never failures.
-// Human chrome → stderr; the ledger self-updates via runInstall.
-// ---------------------------------------------------------------------------
-if (command === "update") {
-  let summary;
-  try {
-    summary = runUpdate({
-      name: path,            // positional[1]: a bare plugin name (or undefined)
-      all: options.all,
-      dryRun: options.dryRun,
-      home: homedir(),       // single global ledger home
-      cwd: processCwd(),     // canonical bundle resolution
-    });
-  } catch (err) {
-    process.stderr.write(
-      `[enact-extensions update] ${err instanceof Error ? err.message : String(err)}\n`,
-    );
-    process.exit(1);
+    if (report.problems.length > 0) {
+      console.error(`[doctor enact-repo] ${report.problems.length} problem(s):`);
+      for (const p of report.problems) console.error(`  - ${p}`);
+    } else {
+      console.log("[doctor enact-repo] all hard requirements OK");
+    }
   }
 
-  const verb = summary.dryRun ? "would update" : "updated";
-
-  if (summary.dryRun) {
-    if (summary.planned.length === 0) {
-      process.stderr.write("Nothing to update — no outdated surfaces in scope.\n");
+  // ---------------------------------------------------------------------------
+  // `doctor <plugin> --repo <path>` — read-only repo-local health check.
+  // Any plugin, bundled or not: bundled-extensions.json is the DEFAULT set, not
+  // an allow-list. `<plugin>` is a bundled name or an explicit path, resolved
+  // exactly like install/uninstall.
+  // ---------------------------------------------------------------------------
+  if (command === "doctor") {
+    if (!path || !options.repo) {
+      fail(`doctor requires: doctor <plugin> --repo <path> [--json]\n${REPO_USAGE_HINT}`);
     }
-    for (const e of summary.planned) {
-      const from = e.installedHash ? String(e.installedHash).slice(0, 12) : "(none)";
-      const to = e.currentHash ? String(e.currentHash).slice(0, 12) : "(unknown)";
-      console.log(`${verb}: ${e.name} [${e.platform}] @ ${e.home}  ${from} -> ${to}`);
+    let pluginRoot;
+    try {
+      pluginRoot = resolveBundlePath(path);
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      exit(1);
     }
-  } else {
-    for (const e of summary.updated) {
-      console.log(`updated: ${e.name} [${e.platform}] @ ${e.home}`);
+    let report;
+    try {
+      report = runRepoDoctor(pluginRoot, { repo: options.repo });
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      exit(1);
     }
+    if (options.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      printRepoDoctorReport(report);
+    }
+    exit(report.exitCode);
   }
 
-  for (const e of summary.skipped) {
-    process.stderr.write(
-      `skipped-orphaned: ${e.name} [${e.platform}] @ ${e.home} (canonical source gone)\n`,
-    );
-  }
-  for (const f of summary.failed) {
-    const e = f.entry;
-    process.stderr.write(
-      `failed: ${e.name} [${e.platform}] @ ${e.home}: ${f.error.message}\n`,
-    );
-  }
-
-  const doneCount = summary.dryRun ? summary.planned.length : summary.updated.length;
-  process.stderr.write(
-    `${doneCount} ${summary.dryRun ? "would be updated" : "updated"}, ` +
-      `${summary.skipped.length} skipped (orphaned), ${summary.failed.length} failed.\n`,
-  );
-
-  // Non-zero exit ONLY on a real install failure.
-  process.exit(summary.failed.length > 0 ? 1 : 0);
-}
-
-// ---------------------------------------------------------------------------
-// `prune` command — remove orphaned installed surfaces, driven by the ledger.
-//
-// A surface is pruned only when:
-//   - the ledger still says it is installed,
-//   - it belongs to the requested marketplace,
-//   - its platform is in scope, and
-//   - no local source bundle exists for that plugin name.
-// ---------------------------------------------------------------------------
-if (command === "prune") {
-  let summary;
-  try {
-    summary = runPrune({
-      platform: options.platform ?? "all",
-      dryRun: options.dryRun,
-      ledgerHome: homedir(),
-      cwd: processCwd(),
-      marketplaceName: options.marketplaceName,
-    });
-  } catch (err) {
-    process.stderr.write(
-      `[enact-extensions prune] ${err instanceof Error ? err.message : String(err)}\n`,
-    );
-    process.exit(1);
-  }
-
-  if (options.json) {
-    process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
-    process.exit(summary.failed.length > 0 ? 1 : 0);
-  }
+  // ---------------------------------------------------------------------------
+  // `list` command — enumerate available plugin bundles.
+  // ---------------------------------------------------------------------------
+  if (command === "list") {
+    // The package's own extensions/ dir, resolved relative to this script.
+    const PACKAGE_ROOT = resolve(__dirname, "..");
+    const packageExtensions = join(PACKAGE_ROOT, "extensions");
 
-  const rows = summary.dryRun ? summary.candidates : summary.pruned;
-  const verb = summary.dryRun ? "would prune" : "pruned";
-  if (rows.length === 0) {
-    process.stderr.write("Nothing to prune — no orphaned installed surfaces in scope.\n");
-  }
-  for (const entry of rows) {
-    console.log(`${verb}: ${entry.name} [${entry.platform}] @ ${entry.home}`);
-  }
-  for (const f of summary.failed) {
-    process.stderr.write(
-      `failed: ${f.entry.name} [${f.entry.platform}] @ ${f.entry.home}: ${f.error.message}\n`,
-    );
-  }
-  process.stderr.write(
-    `${rows.length} ${summary.dryRun ? "would be pruned" : "pruned"}, ${summary.failed.length} failed.\n`,
-  );
-  process.exit(summary.failed.length > 0 ? 1 : 0);
-}
-
-// ---------------------------------------------------------------------------
-// `serve` command — localhost API + static-file server (no pluginRoot needed).
-// Handled here (before resolveRoot) because it is async + long-running.
-// ---------------------------------------------------------------------------
-if (command === "serve") {
-  const PACKAGE_ROOT = resolve(__dirname, "..");
-  const port = resolveServePort(options);
-  const host = options.host ?? "127.0.0.1";
+    let roots;
+    if (path) {
+      // Explicit dir argument → scan only that dir.
+      roots = [resolve(processCwd(), path)];
+    } else {
+      // Default: package-bundled extensions/ + cwd/extensions/ (if it differs).
+      roots = [packageExtensions];
+      const cwdExtensions = join(processCwd(), "extensions");
+      if (resolve(cwdExtensions) !== resolve(packageExtensions) && existsSync(cwdExtensions)) {
+        roots.push(cwdExtensions);
+      }
+    }
 
-  if (host !== "127.0.0.1" && host !== "localhost" && host !== "::1") {
-    process.stderr.write(
-      `[enact-extensions serve] WARNING: binding to ${host} exposes the API to other machines on the network.\n`,
-    );
-  }
+    const entries = listBundles(roots);
 
-  // Use async IIFE. The http.Server keeps the event loop alive after this IIFE resolves.
-  (async () => {
-    let serverInstance;
-    let url;
-    try {
-      const started = await startServer({
-        port,
-        host,
-        packageRoot: PACKAGE_ROOT,
-        installDefaults: { ledgerHome: homedir() },
-      });
-      serverInstance = started.server;
-      url = started.url;
-    } catch (err) {
-      process.stderr.write(`[enact-extensions serve] Failed to start server: ${err instanceof Error ? err.message : String(err)}\n`);
-      process.exit(1);
+    if (options.json) {
+      console.log(JSON.stringify(entries, null, 2));
+      exit(0);
     }
 
-    console.log(`enact-extensions serve: listening at ${url}`);
-
-    if (options.open) {
-      // Best-effort browser open; ignore all errors silently.
-      const { spawn } = await import("node:child_process");
-      const opener =
-        process.platform === "darwin"
-          ? "open"
-          : process.platform === "win32"
-            ? "start"
-            : "xdg-open";
-      try {
-        spawn(opener, [url], { detached: true, stdio: "ignore" }).unref();
-      } catch {
-        // xdg-open / open not available in all environments — ignore
-      }
+    // Human-readable table.
+    const TRUNC = 60;
+    function trunc(str, len) {
+      if (!str) return "";
+      return str.length > len ? str.slice(0, len - 1) + "…" : str;
     }
 
-    // SIGINT / SIGTERM → graceful shutdown
-    const shutdown = () => serverInstance.close(() => process.exit(0));
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
-  })();
+    if (entries.length === 0) {
+      console.log("No plugin bundles found.");
+      exit(0);
+    }
 
-  // Do NOT fall through to resolveRoot / the plugin-root command block.
-  // process.exit is intentionally NOT called — the http.Server ref keeps Node alive.
-  // Use a throw inside a never-reached block OR just let the module end here.
-  // The trick: throw a synthetic signal so the try/catch-less module scope terminates.
-  // Actually: we use process.exitCode = 0 and allow the event loop to keep running.
-  process.exitCode = 0; // signal intent; overridden to 1 on error inside IIFE
-}
+    // Header.
+    const COL_NAME = 28;
+    const COL_VER = 8;
+    const COL_CAT = 18;
+    const COL_SURF = 22;
 
-// ---------------------------------------------------------------------------
-// `hook` command — execute a hook handler by name, reading JSON from stdin.
-//
-// Currently supported sub-commands:
-//   enact-extensions hook session-start
-//     Runs the advisory drift-check and prints valid hook JSON only when plugin
-//     surfaces are outdated or auto-updated.
-//   enact-extensions hook user-prompt-submit
-//     Reads a UserPromptSubmit hook payload from stdin, extracts the prompt,
-//     builds the skill catalog from the bundled extensions dir, routes the
-//     prompt, and writes the hook response to stdout.
-//     Set ENACT_EXTENSIONS_UPS_ROUTER=0 to disable this hook locally without
-//     removing the installed plugin.
-//
-// Output contract (Claude Code hooks):
-//   Match:    { continue: true, hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: <string> } }
-//   No match: { continue: true }
-//   Error:    { continue: true }  (never throws/crashes — degrade gracefully)
-// ---------------------------------------------------------------------------
-if (command === "hook") {
-  const subCommand = path; // positional[1]
+    function padR(str, n) {
+      return String(str ?? "")
+        .padEnd(n)
+        .slice(0, n);
+    }
 
-  if (subCommand !== "user-prompt-submit" && subCommand !== "session-start") {
-    process.stderr.write(
-      `[enact-extensions hook] Unknown sub-command: ${subCommand ?? "(none)"}. ` +
-      `Supported: session-start, user-prompt-submit\n`,
+    const hr = "─".repeat(COL_NAME + COL_VER + COL_CAT + COL_SURF + 3 + TRUNC);
+    console.log(hr);
+    console.log(
+      padR("Name", COL_NAME) +
+        "  " +
+        padR("Ver", COL_VER) +
+        "  " +
+        padR("Category", COL_CAT) +
+        "  " +
+        padR("Surfaces", COL_SURF) +
+        "  " +
+        "Description",
     );
-    process.stdout.write(JSON.stringify({ continue: true }) + "\n");
-    process.exit(0);
-  }
-
-  // Async IIFE: stdin reading and dynamic import require async context.
-  (async () => {
-    if (subCommand === "session-start") {
-      try {
-        const { handleSessionStartDrift, sessionStartHookJson } = await import("./lib/auto-update.mjs");
-        // Opt-in is the USER's: gate auto-apply on the env var they set.
-        const autoApply = !!process.env.ENACT_EXTENSIONS_AUTO_UPDATE;
-        const result = handleSessionStartDrift({ autoApply });
-        if (result.line) {
-          process.stdout.write(`${sessionStartHookJson(result.line)}\n`);
-        }
-      } catch {
-        // Fail-silent for session-start hooks.
-      }
-      process.exit(0);
+    console.log(hr);
+
+    for (const e of entries) {
+      const surfaces = e.targets.join(", ");
+      console.log(
+        padR(e.name, COL_NAME) +
+          "  " +
+          padR(e.version, COL_VER) +
+          "  " +
+          padR(e.category, COL_CAT) +
+          "  " +
+          padR(surfaces, COL_SURF) +
+          "  " +
+          trunc(e.description, TRUNC),
+      );
     }
-
-    if (process.env.ENACT_EXTENSIONS_UPS_ROUTER === "0") {
-      process.stdout.write(JSON.stringify({ continue: true }) + "\n");
-      process.exit(0);
+    console.log(hr);
+    console.log(`${entries.length} bundle${entries.length === 1 ? "" : "s"} found.`);
+    exit(0);
+  }
+
+  // ---------------------------------------------------------------------------
+  // `index` command — generate a discovery index of all plugin bundles.
+  //
+  // The index is a LOCAL GENERATED ARTIFACT (never committed). The generated/
+  // directory is gitignored. The schema at spec/index.json is the committed
+  // contract. No network, no marketplace, no catalog/ — purely local.
+  // ---------------------------------------------------------------------------
+  if (command === "index") {
+    const PACKAGE_ROOT = resolve(__dirname, "..");
+    const packageExtensions = join(PACKAGE_ROOT, "extensions");
+
+    // Same default roots as `list`.
+    const roots = [packageExtensions];
+    const cwdExtensions = join(processCwd(), "extensions");
+    if (resolve(cwdExtensions) !== resolve(packageExtensions) && existsSync(cwdExtensions)) {
+      roots.push(cwdExtensions);
     }
 
-    // Read stdin to get the hook payload JSON.
-    let payload;
+    // Build the index. The wall-clock timestamp is computed here at the CLI
+    // boundary and passed in — buildIndex itself stays pure (never calls Date).
+    let index;
     try {
-      const chunks = [];
-      for await (const chunk of process.stdin) chunks.push(chunk);
-      const raw = Buffer.concat(chunks).toString("utf8").trim();
-      payload = raw ? JSON.parse(raw) : {};
-    } catch {
-      // Malformed or empty stdin — safe passthrough.
-      process.stdout.write(JSON.stringify({ continue: true }) + "\n");
-      process.exit(0);
+      index = buildIndex(roots, { now: new Date().toISOString(), packageRoot: PACKAGE_ROOT });
+    } catch (err) {
+      console.error(
+        `[enact-extensions index] Failed to build index: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      exit(1);
     }
 
+    // Validate against spec/index.json before writing.
+    const schemaPath = join(PACKAGE_ROOT, "spec", "index.json");
+    let schema;
     try {
-      // Extract the user prompt from the hook payload.
-      // `prompt` is the canonical UserPromptSubmit field across surfaces:
-      // Claude Code (code.claude.com/docs/en/hooks) and Codex
-      // (developers.openai.com/codex/hooks) both send { prompt: string, ... };
-      // Cursor follows the same Claude-compatible schema. Single field, no fallback.
-      const prompt = payload && typeof payload.prompt === "string" ? payload.prompt : null;
-
-      if (!prompt) {
-        process.stdout.write(JSON.stringify({ continue: true }) + "\n");
-        process.exit(0);
-      }
-
-      // Resolve the extensions dir relative to the installed package root so
-      // the hook works whether invoked from the repo or the globally installed package.
-      const { buildSkillCatalog, routePrompt } = await import("./lib/ups-router.mjs");
-      const extensionsDir = join(PACKAGE_ROOT, "extensions");
-      const catalog = buildSkillCatalog(extensionsDir);
-
-      const { additionalContext } = routePrompt(prompt, catalog);
+      schema = JSON.parse(readFileSync(schemaPath, "utf8"));
+    } catch (err) {
+      console.error(
+        `[enact-extensions index] Cannot read schema ${schemaPath}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      exit(1);
+    }
 
-      if (additionalContext) {
-        process.stdout.write(
-          JSON.stringify({
-            continue: true,
-            hookSpecificOutput: {
-              hookEventName: "UserPromptSubmit",
-              additionalContext,
-            },
-          }) + "\n",
-        );
-      } else {
-        process.stdout.write(JSON.stringify({ continue: true }) + "\n");
-      }
-    } catch {
-      // Any unexpected error — safe passthrough, never crash.
-      process.stdout.write(JSON.stringify({ continue: true }) + "\n");
+    const addFormats = addFormatsModule.default ?? addFormatsModule;
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    addFormats(ajv);
+    const validate = ajv.compile(schema);
+    const valid = validate(index);
+    if (!valid) {
+      const errs = (validate.errors ?? []).map((e) => `  ${e.instancePath || "/"}: ${e.message}`).join("\n");
+      console.error(`[enact-extensions index] Generated index failed schema validation:\n${errs}`);
+      exit(1);
     }
 
-    process.exit(0);
-  })();
-}
+    const json = JSON.stringify(index, null, 2);
+    // --stdout is normalized to "-" during arg parsing, so this single check covers both.
+    const toStdout = options.out === "-";
 
-// ---------------------------------------------------------------------------
-// Commands that require resolving a plugin root path.
-// (Only run when command is not already handled above.)
-// ---------------------------------------------------------------------------
-if (command !== "serve" && command !== "hook") {
+    if (toStdout) {
+      // Write JSON to stdout; summary to stderr (keeps stdout pipe-clean).
+      process.stdout.write(json + "\n");
+      process.stderr.write(`[enact-extensions index] ${index.count} plugin${index.count === 1 ? "" : "s"} indexed.\n`);
+    } else {
+      const outPath = options.out ? resolve(processCwd(), options.out) : join(PACKAGE_ROOT, "generated", "index.json");
 
-// Resolve the plugin root:
-//   - If no path arg given → default to cwd (existing behaviour).
-//   - If a path arg is given → resolveBundlePath handles both explicit paths and
-//     bare plugin names, throwing meaningful errors when nothing resolves.
-const resolveRoot = (pathArg) => {
-  if (!pathArg) return resolvePluginRoot(undefined);
-  return resolveBundlePath(pathArg);
-};
+      // Ensure parent directory exists.
+      const outDir = resolve(outPath, "..");
+      mkdirSync(outDir, { recursive: true });
 
-// A bare name has no path separators (so it is not an explicit filesystem path).
-const isBareName = (arg) =>
-  typeof arg === "string" && arg.length > 0 && !arg.includes("/") && !arg.includes("\\");
+      writeFileSync(outPath, json + "\n", "utf8");
+      process.stderr.write(
+        `[enact-extensions index] Wrote ${index.count} plugin${index.count === 1 ? "" : "s"} to ${outPath}\n`,
+      );
+    }
 
-let pluginRoot = null;
-try {
-  pluginRoot = resolveRoot(path);
-} catch (err) {
-  // UNINSTALL-ONLY FALLBACK: uninstall must work even when the source bundle is
-  // gone. If the arg is a BARE NAME (not an explicit path) that did not resolve
-  // to a bundle, fall back to using the arg verbatim as the plugin name. The
-  // uninstall handler reads the name from `path` when pluginRoot is null.
-  // For an explicit path that does not exist, or for any other command, this is
-  // still a hard error.
-  if (command === "uninstall" && isBareName(path)) {
-    pluginRoot = null; // signal: use the raw `path` as the plugin name
-  } else {
-    console.error(err instanceof Error ? err.message : String(err));
-    process.exit(1);
+    exit(0);
   }
-}
 
-try {
-  if (command === "validate") {
-    const ok = runValidate(pluginRoot, undefined, { pluginValidate: true });
-    process.exit(ok ? 0 : 1);
+  // ---------------------------------------------------------------------------
+  // Commands that resolve a plugin root path: validate, sync, install/uninstall --repo.
+  // ---------------------------------------------------------------------------
+  let pluginRoot = null;
+  try {
+    pluginRoot = path ? resolveBundlePath(path) : resolve(processCwd());
+  } catch (err) {
+    // uninstall --repo must work even when the source bundle is gone: a bare
+    // name that does not resolve is used verbatim as the plugin name.
+    const isBareName = typeof path === "string" && path.length > 0 && !path.includes("/") && !path.includes("\\");
+    if (!(command === "uninstall" && isBareName)) {
+      fail(err instanceof Error ? err.message : String(err));
+    }
   }
 
-  if (command === "sync") {
-    runSync(pluginRoot, { name: options.name });
-    process.exit(0);
+  function manifestName(root) {
+    const manifestPath = root ? join(root, ".agents", "plugin.json") : null;
+    return manifestPath && existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")).name : null;
   }
 
-  if (command === "install") {
-    if (options.dryRun) {
-      console.error(INSTALL_DRY_RUN_UNSUPPORTED_MESSAGE);
-      process.exit(1);
+  try {
+    if (command === "validate") {
+      const ok = runValidate(pluginRoot, undefined, { pluginValidate: true, skillValidate: true });
+      exit(ok ? 0 : 1);
     }
-    // Single global ledger: every install (local or global scope) records to
-    // <homedir>/.enact/extensions/ledger.jsonl so `log` always finds it,
-    // regardless of which per-platform home the bundle was installed to. The
-    // local/global distinction is carried in each entry's `scope` field.
-    runInstall(pluginRoot, { ...options, ledgerHome: homedir() });
-    process.exit(0);
-  }
 
-  if (command === "uninstall") {
-    // Resolve plugin name: if the source bundle resolved on disk, read its
-    // manifest name from .agents/plugin.json (or .codex-plugin/plugin.json).
-    // Otherwise (source bundle gone / bare-name fallback), treat the raw
-    // positional arg as the plugin name. This lets uninstall remove already-
-    // installed plugins even when their source bundle has been deleted.
-    let pluginName = null;
-    if (pluginRoot) {
-      try {
-        const enactManifestPath = join(pluginRoot, ".agents", "plugin.json");
-        if (existsSync(enactManifestPath)) {
-          const manifest = JSON.parse(readFileSync(enactManifestPath, "utf8"));
-          pluginName = typeof manifest.name === "string" ? manifest.name : null;
-        }
-        // Fall back to .codex-plugin/plugin.json
-        if (!pluginName) {
-          const codexManifestPath = join(pluginRoot, ".codex-plugin", "plugin.json");
-          if (existsSync(codexManifestPath)) {
-            const manifest = JSON.parse(readFileSync(codexManifestPath, "utf8"));
-            pluginName = typeof manifest.name === "string" ? manifest.name : null;
-          }
-        }
-      } catch {
-        // Source bundle unreadable — fall through to raw name.
-      }
+    if (command === "sync") {
+      runSync(pluginRoot, { name: options.name });
+      exit(0);
     }
-    // Fall back: treat the raw positional arg as the plugin name.
-    // `path` is the raw positional from the CLI. When the source bundle was gone
-    // (pluginRoot === null) this is the only source of the name.
-    if (!pluginName) {
-      pluginName = path ?? (pluginRoot ? pluginRoot.split("/").pop() : null);
+
+    // install | uninstall --repo
+    const dryRun = options.dryRun === true;
+    const repoPluginName = manifestName(pluginRoot) ?? path;
+    if (!repoPluginName) {
+      fail(`${command} --repo requires a plugin name`);
     }
-    if (!pluginName) {
-      console.error("uninstall requires a plugin name or path.");
-      process.exit(1);
+    const result =
+      command === "install"
+        ? runRepoInstall(pluginRoot, { repo: options.repo, host: options.host, force: options.force, dryRun })
+        : runRepoUninstall(repoPluginName, { repo: options.repo, purge: options.purge, force: options.force, dryRun });
+    if (dryRun) {
+      if (result.actions.length === 0) {
+        console.log("[dry-run] no filesystem changes — nothing touched");
+      } else {
+        for (const a of result.actions) {
+          console.log(`[dry-run] would ${a.action}: ${a.file} — ${a.reason}`);
+        }
+      }
     }
-    runUninstall(pluginName, { ...options, ledgerHome: homedir() });
-    process.exit(0);
+    exit(0);
+  } catch (err) {
+    if (err instanceof ExitSignal) throw err;
+    fail(err instanceof Error ? err.message : String(err));
   }
-
-  console.error(`Unknown command: ${command}\n`);
-  console.log(HELP);
-  process.exit(1);
 } catch (err) {
-  console.error(err instanceof Error ? err.message : String(err));
-  process.exit(1);
+  // The only expected escape: a command asked to finish with a status.
+  // Setting exitCode rather than exiting lets node drain stdout first.
+  if (!(err instanceof ExitSignal)) throw err;
+  process.exitCode = err.code;
 }
-
-} // end if (command !== "serve")