@cleocode/cleo 2026.10.3 → 2026.10.5-rc.ci.672

package/dist/cli/docs-DPPDFTWR.js

@@ -0,0 +1,3098 @@
+(() => {
+  const _installed = Symbol.for('cleocode.cli.sqliteWarningFilter');
+  if (globalThis[_installed]) return;
+  globalThis[_installed] = true;
+  const _origEmitWarning = process.emitWarning;
+  process.emitWarning = function(warning, type, code, ctor) {
+    if (typeof warning === 'object' && warning.name === 'ExperimentalWarning' && typeof warning.message === 'string' && /SQLite is an experimental feature/i.test(warning.message)) {
+      return;
+    }
+    if (typeof warning === 'string' && /SQLite is an experimental feature/i.test(warning)) {
+      return;
+    }
+    return _origEmitWarning.call(process, warning, type, code, ctor);
+  };
+})();
+import {
+  getOperationParams,
+  paramsToCittyArgs
+} from "./chunk-RRKP7HLU.js";
+import {
+  negatedFlag
+} from "./chunk-47JYZAMS.js";
+import "./chunk-C3B7C43W.js";
+import {
+  dispatchFromCli,
+  dispatchRaw,
+  handleRawError
+} from "./chunk-L7ONYSV6.js";
+import "./chunk-6N6WGLXE.js";
+import {
+  resolve
+} from "./chunk-4VASFLUW.js";
+import {
+  loadCanonRegistry
+} from "./chunk-SXXOC6KZ.js";
+import {
+  UnknownFlagError,
+  assertKnownFlags
+} from "./chunk-OILHT47L.js";
+import {
+  defineCommand,
+  showUsage
+} from "./chunk-PKKZPOOP.js";
+import "./chunk-QKMBWYAS.js";
+import {
+  cliError,
+  cliOutput,
+  humanInfo
+} from "./chunk-4RGSNUUP.js";
+import "./chunk-6JSJNYH2.js";
+import "./chunk-D7BAQNV2.js";
+import "./chunk-TYC7G5LF.js";
+
+// packages/cleo/src/cli/commands/docs.ts
+import { appendFile, mkdir as mkdir3, readdir, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname3, isAbsolute, join as join4, resolve as resolve3 } from "node:path";
+import {
+  DocKindConfigError,
+  DocKindRegistry,
+  ExitCode as ExitCode5
+} from "@cleocode/contracts";
+import {
+  detectStrayCleoDb,
+  getAgentOutputsAbsolute,
+  resolveWorktreeFilePath,
+  resolveWorktreeRouting
+} from "@cleocode/core/core-paths";
+import { createDocsReadModel } from "@cleocode/core/docs/docs-read-model";
+import { CounterMismatchError } from "@cleocode/core/docs/import/import-orchestrator";
+import {
+  checkSlugSimilarity,
+  DEFAULT_SIMILARITY_MODE,
+  DEFAULT_SIMILARITY_THRESHOLD
+} from "@cleocode/core/docs/similarity-check";
+import { CleoError as CleoError2 } from "@cleocode/core/errors";
+import { pushWarning } from "@cleocode/core/output";
+import { getProjectRoot as getProjectRoot3 } from "@cleocode/core/project-scope";
+import { readJson } from "@cleocode/core/store/json";
+import { describeOperation } from "@cleocode/lafs";
+
+// packages/cleo/src/cli/commands/docs/audit.ts
+import { ExitCode } from "@cleocode/contracts/exit-codes.js";
+var auditCommand = defineCommand({
+  meta: {
+    name: "audit",
+    description: "Query the immutable docs audit trail (--slug <slug> or --verify for integrity check)"
+  },
+  args: {
+    slug: {
+      type: "string",
+      description: "Show audit history for a specific document slug"
+    },
+    verify: {
+      type: "boolean",
+      description: "Verify checkpoint chain integrity across the full audit log"
+    }
+  },
+  async run({ args }) {
+    if (!args.slug && !args.verify) {
+      cliError(
+        "Pass --slug <slug> to view history or --verify to check integrity.",
+        ExitCode.GENERAL_ERROR
+      );
+      return;
+    }
+    await dispatchFromCli(
+      "query",
+      "docs",
+      "audit",
+      {
+        ...typeof args.slug === "string" ? { slug: args.slug } : {},
+        ...args.verify === true ? { verify: true } : {}
+      },
+      { command: "docs audit" }
+    );
+  }
+});
+
+// packages/cleo/src/cli/commands/docs/graph.ts
+import { ExitCode as ExitCode2 } from "@cleocode/contracts/exit-codes.js";
+import {
+  buildDocProvenanceGraph,
+  DocProvenanceRootNotFoundError,
+  renderProvenanceGraphAsDot
+} from "@cleocode/core/docs/build-provenance-graph";
+var graphCommand = defineCommand({
+  meta: {
+    name: "graph",
+    description: "Traverse the docs provenance graph from a root (slug or task ID) and return a typed DocProvenanceResponse envelope. Walks supersedes/superseded-by chains plus cross-entity edges to owning + related tasks. Default depth=2. Pass --format dot for Graphviz output (still wrapped in the envelope under data.dot)."
+  },
+  args: {
+    root: {
+      type: "string",
+      description: "Root identifier \u2014 a canonical doc slug (e.g. adr-078-docs-provenance) or a CLEO task ID (T####). Required.",
+      required: true
+    },
+    depth: {
+      type: "string",
+      description: "Maximum BFS hops from the root (default: 2; minimum: 0)."
+    },
+    format: {
+      type: "string",
+      description: "Output format: json (default) | dot."
+    },
+    backlinks: {
+      type: "boolean",
+      description: "Hydrate the persisted docs_wikilinks backlink graph (T11826) \u2014 adds bidirectional shares-topic doc\u2194doc edges and any persisted backlinks not surfaced by the on-the-fly BFS. Obsidian-grade graph on existing data."
+    }
+  },
+  async run({ args }) {
+    const root = String(args.root);
+    const depth = parseDepth(args.depth);
+    const format = parseFormat(args.format);
+    const hydrateWikilinks = Boolean(args.backlinks);
+    try {
+      const graph = await buildDocProvenanceGraph({ root, depth, hydrateWikilinks });
+      const payload = { ...graph };
+      if (format === "dot") {
+        payload["dot"] = renderProvenanceGraphAsDot(graph);
+      }
+      cliOutput(payload, { command: "docs graph", operation: "docs.graph" });
+    } catch (err) {
+      if (err instanceof DocProvenanceRootNotFoundError) {
+        cliError(err.message, ExitCode2.NOT_FOUND, {
+          name: "E_DOC_PROVENANCE_ROOT_NOT_FOUND",
+          fix: "Verify the root with `cleo docs list --project --type adr` (or your kind) and pass an existing slug or task ID. Slugs and task IDs are matched against attachments.slug and attachment_refs.owner_id respectively.",
+          details: { root }
+        });
+        process.exit(ExitCode2.NOT_FOUND);
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      cliError(`docs graph failed: ${message}`, ExitCode2.GENERAL_ERROR, {
+        name: "E_DOCS_GRAPH_FAILED"
+      });
+      process.exit(ExitCode2.GENERAL_ERROR);
+    }
+  }
+});
+function parseDepth(raw) {
+  if (raw === void 0 || raw === null || raw === "") return 2;
+  const parsed = Number.parseInt(String(raw), 10);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    cliError(
+      `--depth must be a non-negative integer (got '${String(raw)}')`,
+      ExitCode2.VALIDATION_ERROR,
+      { name: "E_VALIDATION" }
+    );
+    process.exit(ExitCode2.VALIDATION_ERROR);
+  }
+  return parsed;
+}
+function parseFormat(raw) {
+  if (raw === void 0 || raw === null || raw === "") return "json";
+  const candidate = String(raw);
+  if (candidate !== "json" && candidate !== "dot") {
+    cliError(`--format must be one of: json|dot \u2014 got '${candidate}'`, ExitCode2.VALIDATION_ERROR, {
+      name: "E_VALIDATION"
+    });
+    process.exit(ExitCode2.VALIDATION_ERROR);
+  }
+  return candidate;
+}
+
+// packages/cleo/src/cli/commands/docs/set-alias.ts
+import { ExitCode as ExitCode3 } from "@cleocode/contracts/exit-codes.js";
+import { setDisplayAlias } from "@cleocode/core/docs/display-alias";
+import { CleoError } from "@cleocode/core/errors";
+import { getProjectRoot } from "@cleocode/core/project-scope";
+var setAliasCommand = defineCommand({
+  meta: {
+    name: "set-alias",
+    description: "Assign an explicit display-alias number to a doc, decoupled from its slug (e.g. `cleo docs set-alias adr-051-override-patterns 091`). The number must be unique among type=adr docs. Pass --clear to remove an existing alias (revert to the slug-derived number)."
+  },
+  args: {
+    slug: {
+      type: "positional",
+      description: "Canonical doc slug to alias (e.g. adr-051-override-patterns). Required.",
+      required: true
+    },
+    number: {
+      type: "positional",
+      description: "The display-alias number to assign (positive integer). Omit with --clear.",
+      required: false
+    },
+    clear: {
+      type: "boolean",
+      description: "Clear any existing alias instead of setting one (revert to slug-derived)."
+    }
+  },
+  async run({ args }) {
+    const slug = String(args.slug);
+    const clear = Boolean(args.clear);
+    let displayAlias;
+    if (clear) {
+      displayAlias = null;
+    } else {
+      const raw = args.number;
+      if (raw === void 0 || raw === null || String(raw).trim() === "") {
+        cliError(
+          "a positive integer <number> is required (or pass --clear to remove the alias)",
+          ExitCode3.VALIDATION_ERROR,
+          { name: "E_VALIDATION" }
+        );
+        process.exit(ExitCode3.VALIDATION_ERROR);
+        return;
+      }
+      const parsed = Number.parseInt(String(raw), 10);
+      if (!Number.isInteger(parsed) || parsed < 1) {
+        cliError(
+          `<number> must be a positive integer (got '${String(raw)}')`,
+          ExitCode3.VALIDATION_ERROR,
+          { name: "E_VALIDATION" }
+        );
+        process.exit(ExitCode3.VALIDATION_ERROR);
+        return;
+      }
+      displayAlias = parsed;
+    }
+    try {
+      const result = await setDisplayAlias(getProjectRoot(), { slug, displayAlias });
+      cliOutput(result, { command: "docs set-alias", operation: "docs.set-alias" });
+    } catch (err) {
+      if (err instanceof CleoError) {
+        cliError(err.message, err.code, {
+          name: typeof err.details?.["code"] === "string" ? err.details["code"] : "E_DOCS_SET_ALIAS",
+          ...err.fix ? { fix: err.fix } : {},
+          ...err.details ? { details: err.details } : {}
+        });
+        process.exit(err.code);
+        return;
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      cliError(`docs set-alias failed: ${message}`, ExitCode3.GENERAL_ERROR, {
+        name: "E_DOCS_SET_ALIAS_FAILED"
+      });
+      process.exit(ExitCode3.GENERAL_ERROR);
+    }
+  }
+});
+
+// packages/cleo/src/cli/commands/docs-viewer.ts
+import { spawn } from "node:child_process";
+import { ExitCode as ExitCode4 } from "@cleocode/contracts/exit-codes.js";
+
+// packages/cleo/src/viewer/pidfile.ts
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { getCleoHome } from "@cleocode/core/core-paths";
+function viewerPidFilePath() {
+  return join(getCleoHome(), "viewer.pid");
+}
+async function writeViewerPidFile(record) {
+  const path = viewerPidFilePath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, JSON.stringify(record, null, 2), "utf8");
+  return path;
+}
+async function readViewerPidFile() {
+  try {
+    const raw = await readFile(viewerPidFilePath(), "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.pid === "number" && typeof parsed.port === "number" && typeof parsed.host === "string" && typeof parsed.projectRoot === "string" && typeof parsed.startedAt === "number") {
+      return parsed;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+async function removeViewerPidFile() {
+  try {
+    await unlink(viewerPidFilePath());
+  } catch {
+  }
+}
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const e = err;
+    if (e.code === "EPERM") return true;
+    return false;
+  }
+}
+
+// packages/cleo/src/cli/docs-viewer-subsystem.ts
+import { mkdir as mkdir2 } from "node:fs/promises";
+import { join as join3 } from "node:path";
+import { getCleoHome as getCleoHome2 } from "@cleocode/core/core-paths";
+import { defineSubsystem } from "@cleocode/runtime/daemon";
+
+// packages/cleo/src/viewer/server.ts
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { dirname as dirname2, join as join2, normalize, resolve as resolve2 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { searchAllProjectDocs } from "@cleocode/core/docs/docs-ops";
+import { getProjectRoot as getProjectRoot2 } from "@cleocode/core/project-scope";
+import { createAttachmentStore } from "@cleocode/core/store/attachment-store";
+
+// packages/cleo/src/viewer/port-allocator.ts
+import { createServer } from "node:http";
+var DEFAULT_START_PORT = 7777;
+var DEFAULT_END_PORT = 7800;
+async function tryListen(requestHandler, opts = {}) {
+  const startPort = opts.startPort ?? DEFAULT_START_PORT;
+  const endPort = opts.endPort ?? DEFAULT_END_PORT;
+  const host = opts.host ?? "127.0.0.1";
+  const autoIncrement = opts.autoIncrement ?? true;
+  const last = autoIncrement ? endPort : startPort;
+  for (let port = startPort; port <= last; port++) {
+    const server = createServer(requestHandler);
+    try {
+      await new Promise((res, rej) => {
+        const onError = (err) => {
+          server.removeListener("listening", onListen);
+          rej(err);
+        };
+        const onListen = () => {
+          server.removeListener("error", onError);
+          res();
+        };
+        server.once("error", onError);
+        server.once("listening", onListen);
+        server.listen(port, host);
+      });
+      const addr = server.address();
+      const boundPort = addr && typeof addr === "object" && typeof addr.port === "number" ? addr.port : port;
+      return { server, port: boundPort, host };
+    } catch (err) {
+      const e = err;
+      server.close();
+      if (e.code !== "EADDRINUSE") {
+        throw e;
+      }
+      if (!autoIncrement) {
+        throw Object.assign(new Error(`port ${startPort} in use`), { code: "EADDRINUSE" });
+      }
+    }
+  }
+  throw Object.assign(
+    new Error(
+      `no free port in range ${startPort}\u2013${endPort} for viewer (tried ${last - startPort + 1} ports)`
+    ),
+    { code: "E_NO_PORT" }
+  );
+}
+
+// packages/cleo/src/viewer/server.ts
+function getViewerAssetsDir() {
+  const thisFile = fileURLToPath(import.meta.url);
+  return resolve2(dirname2(thisFile), "..", "..", "assets", "viewer");
+}
+var STATIC_MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".ico": "image/x-icon"
+};
+function extOf(p) {
+  const i = p.lastIndexOf(".");
+  return i < 0 ? "" : p.slice(i).toLowerCase();
+}
+function lafsErrorJson(code, message, fix) {
+  const env = {
+    success: false,
+    error: { code, message }
+  };
+  if (fix !== void 0) env.error.fix = fix;
+  return JSON.stringify(env);
+}
+function lafsSuccessJson(data) {
+  return JSON.stringify({ success: true, data });
+}
+function send(res, status, contentType, body) {
+  res.writeHead(status, { "Content-Type": contentType, "Cache-Control": "no-store" });
+  res.end(body);
+}
+function inferTitle(markdown, fallback) {
+  for (const line of markdown.split("\n", 50)) {
+    const m = line.match(/^\s*#\s+(.+?)\s*$/);
+    if (m) return m[1];
+  }
+  return fallback;
+}
+async function serveStatic(res, assetsDir, relPath) {
+  const safeRel = normalize(relPath).replace(/^[\\/]+/, "");
+  const absPath = join2(assetsDir, safeRel);
+  const resolvedAssets = resolve2(assetsDir) + "/";
+  const resolvedAbs = resolve2(absPath);
+  if (`${resolvedAbs}/`.indexOf(resolvedAssets) !== 0 && resolvedAbs !== resolve2(assetsDir)) {
+    send(res, 404, "application/json", lafsErrorJson("E_NOT_FOUND", `not found: ${relPath}`));
+    return;
+  }
+  try {
+    const s = await stat(absPath);
+    if (!s.isFile()) {
+      send(res, 404, "application/json", lafsErrorJson("E_NOT_FOUND", `not found: ${relPath}`));
+      return;
+    }
+    const mime = STATIC_MIME[extOf(absPath)] ?? "application/octet-stream";
+    res.writeHead(200, {
+      "Content-Type": mime,
+      "Content-Length": String(s.size),
+      "Cache-Control": "no-store"
+    });
+    createReadStream(absPath).pipe(res);
+  } catch {
+    send(res, 404, "application/json", lafsErrorJson("E_NOT_FOUND", `not found: ${relPath}`));
+  }
+}
+function buildViewerHandler(opts = {}) {
+  const projectRoot = opts.projectRoot ?? getProjectRoot2();
+  const assetsDir = getViewerAssetsDir();
+  const store = createAttachmentStore();
+  return async (req, res) => {
+    try {
+      const method = (req.method ?? "GET").toUpperCase();
+      const pathname = (req.url ?? "/").split("?")[0] ?? "/";
+      if (method === "GET" && pathname === "/api/health") {
+        send(res, 200, "application/json", lafsSuccessJson({ status: "ok" }));
+        return;
+      }
+      if (method !== "GET" && method !== "HEAD") {
+        send(
+          res,
+          405,
+          "application/json",
+          lafsErrorJson("E_METHOD_NOT_ALLOWED", `method ${method} not allowed`)
+        );
+        return;
+      }
+      if (pathname === "/" || pathname === "/viewer" || pathname === "/viewer/") {
+        res.writeHead(302, { Location: "/viewer/index.html" });
+        res.end();
+        return;
+      }
+      if (pathname.startsWith("/viewer/")) {
+        const rel = pathname.slice("/viewer/".length);
+        await serveStatic(res, assetsDir, rel || "index.html");
+        return;
+      }
+      if (pathname === "/api/docs") {
+        const rows = await store.listAllInProject(projectRoot);
+        const seen = /* @__PURE__ */ new Map();
+        for (const r of rows) {
+          if (!seen.has(r.metadata.id)) seen.set(r.metadata.id, r);
+        }
+        const docs = Array.from(seen.values()).map((r) => ({
+          id: r.metadata.id,
+          slug: r.slug,
+          type: r.type,
+          sha256: r.metadata.sha256,
+          mime: r.metadata.attachment.kind === "blob" ? r.metadata.attachment.mime : null,
+          ownerType: r.ownerType,
+          ownerId: r.ownerId,
+          title: r.slug ?? r.metadata.id,
+          createdAt: r.metadata.createdAt
+        }));
+        send(res, 200, "application/json", lafsSuccessJson({ docs }));
+        return;
+      }
+      if (pathname === "/api/search") {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+        const q = (url.searchParams.get("q") ?? "").trim();
+        const limitRaw = url.searchParams.get("limit");
+        const type = url.searchParams.get("type") ?? void 0;
+        if (q.length === 0) {
+          send(
+            res,
+            400,
+            "application/json",
+            lafsErrorJson(
+              "E_VALIDATION",
+              "query parameter `q` is required",
+              "append ?q=<query> to /api/search, e.g. '/api/search?q=release'"
+            )
+          );
+          return;
+        }
+        const limit = limitRaw ? Math.max(1, Math.min(50, Number.parseInt(limitRaw, 10))) : 10;
+        try {
+          const result = await searchAllProjectDocs(q, {
+            projectRoot,
+            limit: Number.isFinite(limit) ? limit : 10,
+            type: type && type.length > 0 ? type : void 0
+          });
+          send(res, 200, "application/json", lafsSuccessJson(result));
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          const code = err instanceof Error && err.code ? err.code : "E_SEARCH_FAILED";
+          send(res, 500, "application/json", lafsErrorJson(code, msg));
+        }
+        return;
+      }
+      const apiDocMatch = pathname.match(/^\/api\/docs\/([^/]+)$/);
+      if (apiDocMatch) {
+        const slug = decodeURIComponent(apiDocMatch[1]);
+        const bySlug = await store.findBySlug(slug, projectRoot);
+        if (!bySlug) {
+          send(
+            res,
+            404,
+            "application/json",
+            lafsErrorJson("E_NOT_FOUND", `no published doc with slug '${slug}'`)
+          );
+          return;
+        }
+        const fetched = await store.get(bySlug.metadata.sha256, projectRoot);
+        if (!fetched) {
+          send(
+            res,
+            404,
+            "application/json",
+            lafsErrorJson(
+              "E_NOT_FOUND",
+              `doc '${slug}' metadata present but blob bytes missing on disk`
+            )
+          );
+          return;
+        }
+        const mime = fetched.metadata.attachment.kind === "blob" ? fetched.metadata.attachment.mime : fetched.metadata.attachment.kind === "local-file" ? fetched.metadata.attachment.mime ?? "text/plain" : "application/octet-stream";
+        const isText = mime.startsWith("text/") || mime === "application/json";
+        const content = isText ? fetched.bytes.toString("utf8") : null;
+        const title = content ? inferTitle(content, slug) : slug;
+        send(
+          res,
+          200,
+          "application/json",
+          lafsSuccessJson({
+            id: fetched.metadata.id,
+            slug: bySlug.slug,
+            type: bySlug.type,
+            title,
+            mime,
+            sha256: fetched.metadata.sha256,
+            content,
+            sizeBytes: fetched.bytes.length
+          })
+        );
+        return;
+      }
+      if (/^\/docs\/[^/]+\/?$/.test(pathname)) {
+        await serveStatic(res, assetsDir, "index.html");
+        return;
+      }
+      send(
+        res,
+        404,
+        "application/json",
+        lafsErrorJson("E_NOT_FOUND", `no route for ${method} ${pathname}`)
+      );
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      send(res, 500, "application/json", lafsErrorJson("E_INTERNAL", msg));
+    }
+  };
+}
+async function startViewer(opts = {}) {
+  const handler = buildViewerHandler({ projectRoot: opts.projectRoot });
+  return tryListen(handler, {
+    startPort: opts.startPort,
+    endPort: opts.endPort,
+    host: opts.host,
+    autoIncrement: opts.autoIncrement
+  });
+}
+
+// packages/cleo/src/cli/docs-viewer-subsystem.ts
+var VIEWER_DEFAULT_PORT = 7777;
+var VIEWER_DEFAULT_END_PORT = 7800;
+var VIEWER_DEFAULT_HOST = "127.0.0.1";
+var VIEWER_SUBSYSTEM_NAME = "cleo-docs-viewer";
+var SIGTERM_GRACE_ITERATIONS = 20;
+function getViewerPaths() {
+  const cleoHome = getCleoHome2();
+  return {
+    pidFile: viewerPidFilePath(),
+    logFile: join3(cleoHome, "viewer.log"),
+    logDir: cleoHome
+  };
+}
+function isViewerProcessRunning(pid) {
+  return isProcessAlive(pid);
+}
+async function getViewerStatus() {
+  const record = await readViewerPidFile();
+  if (!record) return { running: false, pid: null, port: null, host: null, url: null };
+  if (!isProcessAlive(record.pid)) {
+    await removeViewerPidFile();
+    return { running: false, pid: null, port: null, host: null, url: null };
+  }
+  return {
+    running: true,
+    pid: record.pid,
+    port: record.port,
+    host: record.host,
+    url: `http://${record.host}:${record.port}`
+  };
+}
+function createDocsViewerSubsystem(opts = {}) {
+  const startPort = opts.startPort ?? VIEWER_DEFAULT_PORT;
+  const endPort = opts.endPort ?? VIEWER_DEFAULT_END_PORT;
+  const host = opts.host ?? VIEWER_DEFAULT_HOST;
+  const autoIncrement = !(opts.noAutoPort ?? false);
+  let live;
+  return defineSubsystem({
+    name: VIEWER_SUBSYSTEM_NAME,
+    async start() {
+      const { pidFile, logDir } = getViewerPaths();
+      const existing = await getViewerStatus();
+      if (existing.running && existing.pid !== null) {
+        const ctx2 = {
+          pid: existing.pid,
+          pidFile,
+          port: existing.port ?? startPort,
+          host: existing.host ?? host
+        };
+        live = ctx2;
+        return ctx2;
+      }
+      await mkdir2(logDir, { recursive: true });
+      const handle = await startViewer({
+        startPort,
+        endPort,
+        host,
+        autoIncrement
+      });
+      await writeViewerPidFile({
+        pid: process.pid,
+        port: handle.port,
+        host: handle.host,
+        projectRoot: process.cwd(),
+        startedAt: Date.now()
+      });
+      const ctx = {
+        pid: process.pid,
+        pidFile,
+        port: handle.port,
+        host: handle.host
+      };
+      live = ctx;
+      return ctx;
+    },
+    healthProbe() {
+      if (live === void 0) {
+        const stopped = "stopped";
+        return {
+          child_id: VIEWER_SUBSYSTEM_NAME,
+          pid: 0,
+          state: stopped,
+          restart_count: 0,
+          detail: "not started"
+        };
+      }
+      const alive = isViewerProcessRunning(live.pid);
+      const state = alive ? "running" : "stopped";
+      return {
+        child_id: VIEWER_SUBSYSTEM_NAME,
+        pid: alive ? live.pid : 0,
+        state,
+        restart_count: 0,
+        detail: alive ? `url=http://${live.host}:${live.port} pid=${live.pid}` : `pid=${live.pid} exited`
+      };
+    },
+    async shutdown(context) {
+      if (!isViewerProcessRunning(context.pid)) {
+        await removeViewerPidFile();
+        live = void 0;
+        return;
+      }
+      try {
+        process.kill(context.pid, "SIGTERM");
+      } catch {
+      }
+      for (let i = 0; i < SIGTERM_GRACE_ITERATIONS; i++) {
+        if (!isViewerProcessRunning(context.pid)) break;
+        await new Promise((resolve4) => setTimeout(resolve4, 500));
+      }
+      if (isViewerProcessRunning(context.pid)) {
+        try {
+          process.kill(context.pid, "SIGKILL");
+        } catch {
+        }
+      }
+      await removeViewerPidFile();
+      live = void 0;
+    }
+  });
+}
+
+// packages/cleo/src/cli/commands/docs-viewer.ts
+function openInBrowser(url) {
+  try {
+    let cmd;
+    let args;
+    if (process.platform === "darwin") {
+      cmd = "open";
+      args = [url];
+    } else if (process.platform === "win32") {
+      cmd = "cmd";
+      args = ["/c", "start", "", url];
+    } else {
+      cmd = "xdg-open";
+      args = [url];
+    }
+    spawn(cmd, args, { detached: true, stdio: "ignore" }).unref();
+  } catch {
+  }
+}
+var serveCommand = defineCommand({
+  meta: {
+    name: "serve",
+    description: "Run docs viewer \u2014 prefer `cleo docs viewer start`"
+  },
+  args: {
+    port: {
+      type: "string",
+      description: "Starting port (default 7777)",
+      default: String(VIEWER_DEFAULT_PORT)
+    },
+    "end-port": {
+      type: "string",
+      description: "Last port to try when auto-incrementing (default 7800)",
+      default: String(VIEWER_DEFAULT_END_PORT)
+    },
+    host: {
+      type: "string",
+      description: "Bind host (default 127.0.0.1)",
+      default: VIEWER_DEFAULT_HOST
+    },
+    "no-auto-port": {
+      type: "boolean",
+      description: "Disable auto-increment when start port is busy",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const startPort = Number.parseInt(String(args.port), 10);
+    const endPort = Number.parseInt(String(args["end-port"]), 10);
+    const host = String(args.host);
+    const noAutoPort = negatedFlag(args, "auto-port");
+    if (!Number.isFinite(startPort) || startPort < 1 || startPort > 65535) {
+      cliError(`invalid --port: ${args.port}`, ExitCode4.VALIDATION_ERROR, { name: "E_VALIDATION" });
+      return;
+    }
+    if (!Number.isFinite(endPort) || endPort < startPort) {
+      cliError(`invalid --end-port: ${args["end-port"]}`, ExitCode4.VALIDATION_ERROR, {
+        name: "E_VALIDATION"
+      });
+      return;
+    }
+    try {
+      const subsystem = createDocsViewerSubsystem({ startPort, endPort, host, noAutoPort });
+      const ctx = await subsystem.start();
+      const { pidFile } = getViewerPaths();
+      cliOutput(
+        {
+          running: true,
+          pid: ctx.pid,
+          port: ctx.port,
+          host: ctx.host,
+          url: `http://${ctx.host}:${ctx.port}`,
+          pidFile
+        },
+        {
+          command: "docs serve",
+          operation: "docs.serve",
+          message: `viewer started on http://${ctx.host}:${ctx.port}`
+        }
+      );
+    } catch (err) {
+      const e = err;
+      if (e.code === "E_NO_PORT" || e.code === "EADDRINUSE") {
+        cliError(e.message ?? `port ${startPort} unavailable`, ExitCode4.GENERAL_ERROR, {
+          name: e.code === "E_NO_PORT" ? "E_NO_PORT" : "EADDRINUSE"
+        });
+        return;
+      }
+      throw err;
+    }
+  }
+});
+var openCommand = defineCommand({
+  meta: {
+    name: "open",
+    description: "Open docs viewer in browser \u2014 prefer `cleo docs viewer open`"
+  },
+  args: {
+    slug: {
+      type: "positional",
+      description: "Doc slug to open (omit to open the viewer home page)",
+      required: false
+    },
+    port: {
+      type: "string",
+      description: "Starting port for the viewer (default 7777)",
+      default: String(VIEWER_DEFAULT_PORT)
+    },
+    "end-port": {
+      type: "string",
+      description: "Last port to try (default 7800)",
+      default: String(VIEWER_DEFAULT_END_PORT)
+    },
+    host: {
+      type: "string",
+      description: "Bind host (default 127.0.0.1)",
+      default: VIEWER_DEFAULT_HOST
+    },
+    "no-launch": {
+      type: "boolean",
+      description: "Skip browser launch; just print the URL",
+      default: false
+    }
+  },
+  async run({ args }) {
+    const slug = args.slug ? String(args.slug) : void 0;
+    let status = await getViewerStatus();
+    if (!status.running) {
+      const startPort = Number.parseInt(String(args.port), 10);
+      const endPort = Number.parseInt(String(args["end-port"]), 10);
+      const host = String(args.host);
+      try {
+        const subsystem = createDocsViewerSubsystem({ startPort, endPort, host });
+        await subsystem.start();
+        status = await getViewerStatus();
+      } catch (err) {
+        const e = err;
+        cliError(e.message ?? "failed to start docs viewer", ExitCode4.GENERAL_ERROR, {
+          name: "E_VIEWER_START_FAILED"
+        });
+        return;
+      }
+    }
+    if (!status.running || status.pid === null || status.port === null || status.host === null) {
+      cliError("timed out waiting for viewer to bind", ExitCode4.GENERAL_ERROR, {
+        name: "E_VIEWER_TIMEOUT"
+      });
+      return;
+    }
+    const url = slug ? `http://${status.host}:${status.port}/docs/${encodeURIComponent(slug)}` : `http://${status.host}:${status.port}/`;
+    if (!negatedFlag(args, "launch")) {
+      openInBrowser(url);
+    }
+    cliOutput(
+      {
+        opened: true,
+        slug: slug ?? null,
+        pid: status.pid,
+        port: status.port,
+        host: status.host,
+        url
+      },
+      {
+        command: "docs open",
+        operation: "docs.open",
+        message: `opened ${url}`
+      }
+    );
+  }
+});
+var stopCommand = defineCommand({
+  meta: {
+    name: "stop",
+    description: "Stop the docs viewer \u2014 prefer `cleo docs viewer stop`"
+  },
+  args: {
+    timeout: {
+      type: "string",
+      description: "Grace period in seconds before SIGKILL (default 10)",
+      default: "10"
+    }
+  },
+  async run({ args }) {
+    const record = await readViewerPidFile();
+    if (!record) {
+      cliOutput(
+        { stopped: false, reason: "no pidfile" },
+        {
+          command: "docs stop",
+          operation: "docs.stop",
+          message: "viewer not running (no pidfile)"
+        }
+      );
+      return;
+    }
+    if (!isProcessAlive(record.pid)) {
+      await removeViewerPidFile();
+      cliOutput(
+        { stopped: false, reason: "stale pidfile", pid: record.pid },
+        {
+          command: "docs stop",
+          operation: "docs.stop",
+          message: `stale pidfile removed (pid ${record.pid} not alive)`
+        }
+      );
+      return;
+    }
+    const { pidFile } = getViewerPaths();
+    const subsystem = createDocsViewerSubsystem({
+      startPort: record.port,
+      host: record.host
+    });
+    await subsystem.shutdown({
+      pid: record.pid,
+      pidFile,
+      port: record.port,
+      host: record.host
+    });
+    const timeoutSec = Math.max(1, Number.parseInt(String(args.timeout), 10) || 10);
+    cliOutput(
+      {
+        stopped: true,
+        pid: record.pid,
+        graceful: true,
+        timeoutSec
+      },
+      {
+        command: "docs stop",
+        operation: "docs.stop",
+        message: `viewer (pid ${record.pid}) stopped`
+      }
+    );
+  }
+});
+var viewerStatusCommand = defineCommand({
+  meta: {
+    name: "viewer-status",
+    description: "Report viewer state \u2014 prefer `cleo docs viewer status`"
+  },
+  async run() {
+    await runViewerStatus();
+  }
+});
+var runViewerStatus = async () => {
+  const status = await getViewerStatus();
+  if (!status.running || status.pid === null) {
+    cliOutput(
+      { running: false, pidFile: viewerPidFilePath() },
+      {
+        command: "docs viewer-status",
+        operation: "docs.viewer-status",
+        message: "viewer not running"
+      }
+    );
+    return;
+  }
+  cliOutput(
+    {
+      running: true,
+      pid: status.pid,
+      port: status.port,
+      host: status.host,
+      url: status.url,
+      pidFile: viewerPidFilePath()
+    },
+    {
+      command: "docs viewer-status",
+      operation: "docs.viewer-status",
+      message: `viewer running (pid ${status.pid})`
+    }
+  );
+};
+var viewerCommand = defineCommand({
+  meta: {
+    name: "viewer",
+    description: "Manage the docs web viewer lifecycle (start/stop/open/status)"
+  },
+  subCommands: {
+    start: serveCommand,
+    stop: stopCommand,
+    open: openCommand,
+    status: viewerStatusCommand
+  },
+  async run({ cmd, rawArgs }) {
+    const firstArg = rawArgs?.find((a) => !a.startsWith("-"));
+    if (firstArg && cmd.subCommands && firstArg in cmd.subCommands) return;
+    await runViewerStatus();
+  }
+});
+var docsViewerSubcommands = {
+  serve: serveCommand,
+  open: openCommand,
+  stop: stopCommand,
+  "viewer-status": viewerStatusCommand,
+  viewer: viewerCommand
+};
+
+// packages/cleo/src/cli/commands/docs.ts
+var docsOutputFlagHelp = "  --json                 Emit the canonical LAFS JSON envelope (also accepted as a global flag)\n  --output <mode>        Re-render the result as envelope|id|table|count|silent (also accepted as a global flag)";
+var docsOutputArgs = {
+  json: {
+    type: "boolean",
+    description: "Emit the canonical LAFS JSON envelope (global output flag; accepted here for docs-command consistency)."
+  },
+  output: {
+    type: "string",
+    description: "Output mode: envelope|id|table|count|silent (global output flag; accepted here for docs-command consistency)."
+  }
+};
+async function dispatchDocsRaw(gateway, operation, params) {
+  const response = await dispatchRaw(gateway, "docs", operation, params);
+  handleRawError(response, { command: "docs", operation: `docs.${operation}` });
+  return response.data;
+}
+async function readDocBodyFromStdin() {
+  if (process.stdin.isTTY) return "";
+  process.stdin.setEncoding("utf-8");
+  let buf = "";
+  for await (const chunk of process.stdin) {
+    buf += chunk;
+  }
+  return buf.replace(/\r?\n$/, "");
+}
+async function getScriptNames(projectRoot) {
+  const scriptsDir = join4(projectRoot, "scripts");
+  try {
+    const files = await readdir(scriptsDir);
+    return files.filter((f) => f.endsWith(".sh")).map((f) => f.replace(".sh", "")).sort();
+  } catch {
+    return [];
+  }
+}
+async function getIndexedCommands(projectRoot) {
+  const indexPath = join4(projectRoot, "docs", "commands", "COMMANDS-INDEX.json");
+  const index = await readJson(indexPath);
+  if (!index) return [];
+  return index.commands.map((c) => c.name).sort();
+}
+async function detectDrift(projectRoot) {
+  const scripts = await getScriptNames(projectRoot);
+  const indexed = await getIndexedCommands(projectRoot);
+  const scriptSet = new Set(scripts);
+  const indexSet = new Set(indexed);
+  const missingFromIndex = scripts.filter((s) => !indexSet.has(s));
+  const missingFromScripts = indexed.filter((i) => !scriptSet.has(i));
+  const warnings = [];
+  if (missingFromIndex.length > 0) {
+    warnings.push(`${missingFromIndex.length} scripts not in COMMANDS-INDEX.json`);
+  }
+  if (missingFromScripts.length > 0) {
+    warnings.push(`${missingFromScripts.length} index entries without scripts`);
+  }
+  let status = "clean";
+  if (missingFromIndex.length > 0 || missingFromScripts.length > 0) {
+    status = missingFromIndex.length > 5 ? "error" : "warning";
+  }
+  return { status, missingFromIndex, missingFromScripts, warnings };
+}
+async function runGapCheck(_projectRoot, filterId) {
+  const reviewDir = getAgentOutputsAbsolute();
+  const results = [];
+  try {
+    const files = await readdir(reviewDir);
+    const reviewFiles = files.filter((f) => f.endsWith(".md"));
+    for (const file of reviewFiles) {
+      if (filterId && !file.includes(filterId)) continue;
+      const filePath = join4(reviewDir, file);
+      const content = await readFile2(filePath, "utf-8");
+      const taskMatch = file.match(/^(T\d+)/);
+      const taskId = taskMatch ? taskMatch[1] : "UNKNOWN";
+      const gaps = [];
+      if (!content.includes("## Summary")) {
+        gaps.push("Missing ## Summary section");
+      }
+      if (!content.includes("**Task**:") && !content.includes("**Task:**")) {
+        gaps.push("Missing Task provenance header");
+      }
+      if (gaps.length > 0) {
+        results.push({ file, taskId, gaps });
+      }
+    }
+  } catch {
+  }
+  return results;
+}
+var addCommand = defineCommand({
+  meta: {
+    name: "add",
+    description: "Attach a local file or remote URL to a CLEO entity (task, session, observation). Owner type is inferred from the ID prefix: T### \u2192 task, ses_* \u2192 session, O-* \u2192 observation. Use --slug to set a human-friendly alias (unique per project) (T9636).\n\nPositional arguments:\n  <owner-id>             Owner entity ID (T###, ses_*, O-*) \u2014 required\n  [file]                 Local file path to attach \u2014 optional when --url/--content is set\n\nNamed arguments:\n  --url <url>            Remote URL to attach (instead of a local file)\n  --content <text>       Inline document body \u2014 author without a file (T10965); '-' reads stdin\n  --desc <text>          Free-text description of this attachment\n  --labels <csv>         Comma-separated labels (e.g. rfc,spec)\n  --attached-by <name>   Agent identity that created the attachment (default: \"human\")\n  --slug <kebab>         Human-friendly alias, unique per project (T9636)\n  --title <text>         Human-readable title \u2014 REQUIRED for --type adr when --slug is omitted (T10360)\n  --type <kind>          Taxonomy classification \u2014 run `cleo docs schema` for kinds\n  --allow-similar        Bypass the slug-similarity warn \u2014 every bypass is audited\n                         to .cleo/audit/similar-bypass.jsonl (T10361)\n  --strict               Enforce body-schema (requiredSections) \u2014 fail with\n                         E_DOC_SCHEMA_MISMATCH instead of warning (T10160)\n" + docsOutputFlagHelp + "\n\nValidation behaviors:\n  \u2022 Unknown flags \u2192 E_UNKNOWN_FLAG with did-you-mean suggestions (T10359)\n  \u2022 Slug collision \u2192 E_SLUG_RESERVED + 3 alternative slugs (T10386)\n  \u2022 Near-duplicate slug \u2192 W_SLUG_SIMILAR warning unless --allow-similar (T10361)\n  \u2022 For --type adr without --slug, slug auto-allocates as `adr-NNN-<kebab-title>` via the\n    central allocator (T10360 \u2014 closes T10153). --title is required in this case."
+  },
+  args: {
+    "owner-id": {
+      type: "positional",
+      description: "Owner entity ID (T###, ses_*, O-*)",
+      required: true
+    },
+    file: {
+      type: "positional",
+      description: "Local file path to attach",
+      required: false
+    },
+    url: {
+      type: "string",
+      description: "Remote URL to attach (instead of a local file)"
+    },
+    content: {
+      type: "string",
+      description: "Inline document body \u2014 author a doc without a pre-existing file (T10965). Pass '-' to read the body from stdin. Mutually exclusive with the file positional and --url."
+    },
+    desc: {
+      type: "string",
+      description: "Free-text description of this attachment"
+    },
+    labels: {
+      type: "string",
+      description: "Comma-separated labels (e.g. rfc,spec)"
+    },
+    "attached-by": {
+      type: "string",
+      description: 'Agent identity that created the attachment (default: "human")'
+    },
+    slug: {
+      type: "string",
+      description: "Human-friendly kebab-case alias for the attachment, unique per project (T9636). Collision returns E_SLUG_RESERVED with 3 alternative suggestions (legacy E_SLUG_TAKEN aliased under details.aliases for one release \u2014 T10386)."
+    },
+    title: {
+      type: "string",
+      description: "Human-readable title used to derive the kebab-slug tail when auto-allocating an ADR slug. REQUIRED when --type adr is set AND --slug is omitted. Slugified via the shared kebabize helper (lowercase, hyphen-separated, diacritics stripped) (T10360)."
+    },
+    type: {
+      type: "string",
+      description: "Taxonomy classification \u2014 run `cleo docs schema` to enumerate registered kinds (T9637 / T9788 / T11142)"
+    },
+    "allow-similar": {
+      type: "boolean",
+      description: "Bypass the T10361 slug-similarity check. Use when you really do mean to add a new doc with a near-duplicate slug (e.g. intentional fork). Every bypass is logged to .cleo/audit/similar-bypass.jsonl."
+    },
+    strict: {
+      type: "boolean",
+      description: "Enforce body-schema validation against the kind's requiredSections (T10160). When set, a missing H2 section fails the write with E_DOC_SCHEMA_MISMATCH. Default (advisory) surfaces missing sections as a W_DOC_SCHEMA_MISMATCH warning."
+    },
+    ...docsOutputArgs
+  },
+  async run({ args, rawArgs }) {
+    try {
+      assertKnownFlags(rawArgs, addCommand.args, "docs add");
+    } catch (err) {
+      if (err instanceof UnknownFlagError) {
+        cliError(err.message, ExitCode5.VALIDATION_ERROR, {
+          name: err.code,
+          fix: err.fix,
+          alternatives: err.suggestions.map((s) => ({ action: s, command: s })),
+          details: { flag: err.flag, knownFlags: err.knownFlags }
+        });
+        process.exit(ExitCode5.VALIDATION_ERROR);
+      }
+      throw err;
+    }
+    const ownerId = args["owner-id"];
+    const fileArg = args.file ?? void 0;
+    const url = args.url ?? void 0;
+    const contentArg = typeof args.content === "string" ? args.content : void 0;
+    const allowSimilar = args["allow-similar"] === true;
+    const sourceCount = (fileArg ? 1 : 0) + (url ? 1 : 0) + (contentArg !== void 0 ? 1 : 0);
+    if (sourceCount === 0) {
+      cliError("provide a file path (positional), --url <url>, or --content <text>", 6, {
+        name: "E_VALIDATION",
+        fix: 'Example: cleo docs add T123 docs/rfc.md --desc "RFC draft" \u2014 or \u2014 cleo docs add T123 --content "# Note" --slug my-note'
+      });
+      process.exit(6);
+    }
+    if (sourceCount > 1) {
+      cliError("the file positional, --url, and --content are mutually exclusive", 6, {
+        name: "E_VALIDATION",
+        fix: "Pass exactly one source: a file path, --url <url>, or --content <text>."
+      });
+      process.exit(6);
+    }
+    let content = contentArg;
+    if (content === "-") {
+      content = await readDocBodyFromStdin();
+    }
+    if (args.type === "adr" && !args.slug && !args.title) {
+      cliError(
+        "--title <text> is required when --type adr is used without --slug \u2014 the allocator needs a title to assemble adr-NNN-<kebab-title>",
+        6,
+        {
+          name: "E_VALIDATION",
+          fix: 'Re-run with --title "Adopt Drizzle v1 beta" (or pass --slug adr-042-explicit-name to bypass auto-allocation).'
+        }
+      );
+      process.exit(6);
+    }
+    let resolvedFile;
+    if (fileArg) {
+      const routing = resolveWorktreeRouting();
+      const strayDb = detectStrayCleoDb(routing);
+      if (strayDb) {
+        cliError(
+          `stray .cleo/tasks.db detected inside worktree at ${routing.worktreePath}. This is a leaked CLEO state directory.`,
+          6,
+          {
+            name: "E_STRAY_WORKTREE_DB",
+            fix: `Remove it with: rm -rf ${routing.worktreePath}/.cleo \u2014 then retry. See ADR-068 \xA73 for the worktree DB isolation rationale.`
+          }
+        );
+        process.exit(6);
+      }
+      if (routing.isWorktree && process.env["CLEO_QUIET"] !== "1") {
+        const routingLog = `[T10389] routing SSoT write from worktree cwd ${routing.cwd} \u2192 canonical project root ${routing.canonicalRoot}
+`;
+        process.stderr.write(routingLog);
+      }
+      resolvedFile = resolveWorktreeFilePath(String(fileArg), routing);
+    }
+    if (args.slug && args.type) {
+      const projectRoot = await getProjectRoot3();
+      let warnThreshold = DEFAULT_SIMILARITY_THRESHOLD;
+      let mode = DEFAULT_SIMILARITY_MODE;
+      try {
+        const canon = loadCanonRegistry(projectRoot);
+        if (canon?.similarity) {
+          warnThreshold = canon.similarity.warnThreshold;
+          mode = canon.similarity.mode;
+        }
+      } catch {
+      }
+      try {
+        const sim = await checkSlugSimilarity({
+          slug: args.slug,
+          type: args.type,
+          projectRoot,
+          threshold: warnThreshold
+        });
+        if (sim.mostSimilarSlug !== null) {
+          const scoreFixed = sim.score.toFixed(2);
+          const hint = `Similar to '${sim.mostSimilarSlug}' (score ${scoreFixed}) \u2014 did you mean: cleo docs update ${sim.mostSimilarSlug}? Pass --allow-similar to bypass.`;
+          if (mode === "block" && !allowSimilar) {
+            cliError(hint, ExitCode5.VALIDATION_ERROR, {
+              name: "E_SLUG_SIMILARITY",
+              fix: `Use \`cleo docs update ${sim.mostSimilarSlug}\` if updating, or pass --allow-similar to add as a new doc.`,
+              alternatives: [
+                {
+                  action: `update '${sim.mostSimilarSlug}' instead`,
+                  command: `cleo docs update ${sim.mostSimilarSlug}`
+                },
+                {
+                  action: "bypass the similarity check",
+                  command: `cleo docs add ${ownerId} ${fileArg ?? `--url ${url}`} --slug ${args.slug} --type ${args.type} --allow-similar`
+                }
+              ],
+              details: {
+                proposedSlug: args.slug,
+                mostSimilarSlug: sim.mostSimilarSlug,
+                score: sim.score,
+                threshold: warnThreshold,
+                kind: args.type
+              }
+            });
+            process.exit(ExitCode5.VALIDATION_ERROR);
+          }
+          humanInfo(hint);
+          if (allowSimilar) {
+            const auditLine = `${JSON.stringify({
+              ts: (/* @__PURE__ */ new Date()).toISOString(),
+              reason: "allow-similar-bypass",
+              proposedSlug: args.slug,
+              mostSimilarSlug: sim.mostSimilarSlug,
+              score: sim.score,
+              threshold: warnThreshold,
+              kind: args.type,
+              ownerId
+            })}
+`;
+            try {
+              await mkdir3(join4(projectRoot, ".cleo", "audit"), { recursive: true });
+              await appendFile(
+                join4(projectRoot, ".cleo", "audit", "similar-bypass.jsonl"),
+                auditLine,
+                "utf-8"
+              );
+            } catch {
+            }
+          }
+        }
+      } catch (err) {
+        if (process.env["CLEO_DEBUG"]) {
+          humanInfo(
+            `similarity check skipped: ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
+    }
+    await dispatchFromCli(
+      "mutate",
+      "docs",
+      "add",
+      {
+        ownerId,
+        ...resolvedFile ? { file: resolvedFile } : {},
+        ...url ? { url } : {},
+        ...content !== void 0 ? { content } : {},
+        ...args.desc ? { desc: args.desc } : {},
+        ...args.labels ? { labels: args.labels } : {},
+        ...args["attached-by"] ? { attachedBy: args["attached-by"] } : {},
+        ...args.slug ? { slug: args.slug } : {},
+        ...args.title ? { title: args.title } : {},
+        ...args.type ? { type: args.type } : {},
+        ...args.strict === true ? { strict: true } : {}
+      },
+      { command: "docs add" }
+    );
+  }
+});
+var listCommand = defineCommand({
+  meta: {
+    name: "list",
+    description: "List attachments. With no scope flag, defaults to project scope and surfaces a hint to narrow with --task, --session, or --observation. --type filters across any scope (T9637/T9638). --limit <N> (default 50) and --orderBy <newest|sha|slug> (default newest) control the browsing window (T9792). Output flags: --json and --output envelope|id|table|count|silent are accepted consistently."
+  },
+  args: {
+    task: {
+      type: "string",
+      description: "Filter by task ID (e.g. T123)"
+    },
+    session: {
+      type: "string",
+      description: "Filter by session ID (e.g. ses_abc123)"
+    },
+    observation: {
+      type: "string",
+      description: "Filter by observation ID (e.g. O-abc123)"
+    },
+    project: {
+      type: "boolean",
+      description: "List ALL attachments in the project (T9638). Mutually exclusive with --task/--session/--observation. Implicit default when no scope is set (T9792)."
+    },
+    type: {
+      type: "string",
+      description: "Filter by classification: spec|adr|research|handoff|note|llm-readme (T9637)"
+    },
+    limit: {
+      type: "string",
+      description: "Maximum number of rows to return (default 50, <=0 for unlimited). When the limit truncates the result set the response carries a hint + totalCount (T9792)."
+    },
+    orderBy: {
+      type: "string",
+      description: "Sort key: newest (default \u2014 most recent first), sha (ascending hex), slug (alphabetical, slug-less rows last) (T9792)."
+    },
+    // T9922 — MVI record projection opt-out flags (surfaced for --help).
+    verbose: {
+      type: "boolean",
+      description: "Return full attachment records instead of the MVI projection (id + slug + type + kind + sha + size + createdAt). T9922."
+    },
+    full: {
+      type: "boolean",
+      description: "Alias for --verbose. T9922."
+    },
+    ...docsOutputArgs
+  },
+  async run({ args }) {
+    const task = args.task ?? void 0;
+    const session = args.session ?? void 0;
+    const observation = args.observation ?? void 0;
+    const project = args.project === true;
+    const type = args.type ?? void 0;
+    const limitRaw = args.limit ?? void 0;
+    const orderByRaw = args.orderBy ?? void 0;
+    const ownerCount = [task, session, observation].filter(Boolean).length;
+    if (ownerCount + (project ? 1 : 0) > 1) {
+      cliError("--task, --session, --observation, and --project are mutually exclusive", 6, {
+        name: "E_VALIDATION"
+      });
+      process.exit(6);
+    }
+    let limit;
+    if (limitRaw !== void 0) {
+      const parsed = Number.parseInt(String(limitRaw), 10);
+      if (Number.isNaN(parsed)) {
+        cliError(`--limit must be an integer \u2014 got '${String(limitRaw)}'`, 6, {
+          name: "E_VALIDATION"
+        });
+        process.exit(6);
+      }
+      limit = parsed;
+    }
+    let orderBy;
+    if (orderByRaw !== void 0) {
+      const candidate = String(orderByRaw);
+      if (candidate !== "newest" && candidate !== "sha" && candidate !== "slug") {
+        cliError(`--orderBy must be one of: newest|sha|slug \u2014 got '${candidate}'`, 6, {
+          name: "E_VALIDATION"
+        });
+        process.exit(6);
+      }
+      orderBy = candidate;
+    }
+    await dispatchFromCli(
+      "query",
+      "docs",
+      "list",
+      {
+        ...task ? { task } : {},
+        ...session ? { session } : {},
+        ...observation ? { observation } : {},
+        ...project ? { project: true } : {},
+        ...type ? { type } : {},
+        ...limit !== void 0 ? { limit } : {},
+        ...orderBy !== void 0 ? { orderBy } : {}
+      },
+      { command: "docs list" }
+    );
+  }
+});
+var fetchCommand = defineCommand({
+  meta: {
+    name: "fetch",
+    description: "Retrieve attachment metadata and bytes by slug, attachment ID (att_*), or SHA-256 hex. Files <= 1 MB are returned base64-encoded inline; larger files report the storage path only. Pass --content (alias --decoded) to emit the decoded UTF-8 document body to stdout instead of the LAFS envelope \u2014 the agent-friendly shortcut over piping bytesBase64 through base64 -d (T10970). Output flags: --json and --output envelope|id|table|count|silent are accepted consistently."
+  },
+  args: {
+    "attachment-ref": {
+      type: "positional",
+      description: "Slug, attachment ID (att_*), or SHA-256 hex",
+      required: true
+    },
+    // T10970 — decoded-text content mode. An explicit opt-out from the
+    // default envelope contract (ADR-086) that streams the raw UTF-8 body
+    // to stdout, mirroring the other text-payload commands (export,
+    // llm-output, view --render markdown).
+    content: {
+      type: "boolean",
+      description: "Emit the decoded UTF-8 document body to stdout instead of the LAFS envelope (text docs only). Replaces the `--field /data/bytesBase64 | base64 -d` two-step (T10970)."
+    },
+    decoded: {
+      type: "boolean",
+      description: "Alias for --content (T10970)."
+    },
+    // T9922 — MVI record projection opt-out flags (surfaced for --help).
+    verbose: {
+      type: "boolean",
+      description: "Return the full attachment metadata block instead of the MVI projection. The byte payload is always returned. T9922."
+    },
+    full: {
+      type: "boolean",
+      description: "Alias for --verbose. T9922."
+    },
+    ...docsOutputArgs
+  },
+  async run({ args }) {
+    const ref = String(args["attachment-ref"]);
+    if (args.content === true || args.decoded === true) {
+      const model = createDocsReadModel();
+      const result = await model.fetchDecoded(ref);
+      if (!result.ok) {
+        if (result.reason === "not-found") {
+          cliError(`Doc not found: ${ref}`, ExitCode5.NOT_FOUND, {
+            name: "E_NOT_FOUND",
+            fix: "List available docs with: cleo docs list"
+          });
+        } else {
+          cliError(`Content not retrievable: ${ref}`, ExitCode5.NOT_FOUND, {
+            name: "E_NOT_FOUND",
+            fix: "The doc metadata exists but its blob may be missing. Try: cleo docs publish <slug>"
+          });
+        }
+        process.exit(ExitCode5.NOT_FOUND);
+      }
+      process.stdout.write(result.content);
+      if (!result.content.endsWith("\n")) {
+        process.stdout.write("\n");
+      }
+      return;
+    }
+    await dispatchFromCli(
+      "query",
+      "docs",
+      "fetch",
+      { attachmentRef: ref },
+      { command: "docs fetch" }
+    );
+  }
+});
+var removeCommand = defineCommand({
+  meta: {
+    name: "remove",
+    description: "Remove an attachment ref from an owner entity. When refCount reaches zero the blob file is purged from disk. Output flags: --json and --output envelope|id|table|count|silent are accepted consistently."
+  },
+  args: {
+    "attachment-ref": {
+      type: "positional",
+      description: "Attachment ID (att_*) or SHA-256 hex",
+      required: true
+    },
+    from: {
+      type: "string",
+      description: "Owner entity ID to remove the attachment ref from (required)"
+    },
+    ...docsOutputArgs
+  },
+  async run({ args }) {
+    const from = args.from ?? void 0;
+    if (!from) {
+      cliError("--from <ownerId> is required", 6, { name: "E_VALIDATION" });
+      process.exit(6);
+    }
+    await dispatchFromCli(
+      "mutate",
+      "docs",
+      "remove",
+      { attachmentRef: args["attachment-ref"], from },
+      { command: "docs remove" }
+    );
+  }
+});
+var supersedeCommandArgs = {
+  oldSlug: {
+    type: "positional",
+    description: "Slug of the doc being replaced",
+    required: true
+  },
+  newSlug: {
+    type: "positional",
+    description: "Slug of the doc that replaces oldSlug",
+    required: true
+  },
+  reason: {
+    type: "string",
+    description: "Optional human-readable reason carried back on the response envelope"
+  }
+};
+var supersedeCommand = defineCommand({
+  meta: {
+    name: "supersede",
+    description: "Atomically supersede an older doc with a newer one: flips lifecycle_status to 'superseded' on the old row and links both rows via the supersedes/superseded_by FK pointers. All writes commit in a single SQLite transaction."
+  },
+  args: supersedeCommandArgs,
+  async run({ args, rawArgs }) {
+    pushWarning({
+      code: "W_DEPRECATED_COMMAND",
+      message: "cleo docs supersede is deprecated - use `cleo docs update` for new work (T11179)",
+      deprecated: "docs supersede",
+      replacement: "docs update"
+    });
+    try {
+      assertKnownFlags(rawArgs, supersedeCommandArgs, "docs supersede");
+    } catch (err) {
+      if (err instanceof UnknownFlagError) {
+        cliError(err.message, ExitCode5.VALIDATION_ERROR, { name: "E_VALIDATION" });
+        process.exit(ExitCode5.VALIDATION_ERROR);
+      }
+      throw err;
+    }
+    const oldSlug = args.oldSlug;
+    const newSlug = args.newSlug;
+    const reason = typeof args.reason === "string" && args.reason.length > 0 ? args.reason : void 0;
+    await dispatchFromCli(
+      "mutate",
+      "docs",
+      "supersede",
+      {
+        oldSlug,
+        newSlug,
+        ...reason !== void 0 ? { reason } : {}
+      },
+      { command: "docs supersede" }
+    );
+  }
+});
+var generateCommand = defineCommand({
+  meta: {
+    name: "generate",
+    description: "Generate an llms.txt-format document summarising all attachments on a CLEO entity. Internally uses the llmtxt npm package for structural section analysis; falls back to a built-in generator when unavailable. Use --attach to save the output back as an llms-txt attachment on the same entity."
+  },
+  args: {
+    for: {
+      type: "string",
+      description: "Target entity ID (task, session, or observation)",
+      required: true
+    },
+    attach: {
+      type: "boolean",
+      description: "Save the generated llms.txt content back as an attachment on the target entity"
+    }
+  },
+  async run({ args }) {
+    humanInfo(
+      `cleo: docs generate is deprecated \u2014 use \`cleo docs llm-output --for ${args.for} --mode attachment-bundle\` (T11137)`
+    );
+    await dispatchFromCli(
+      "query",
+      "docs",
+      "generate",
+      {
+        for: args.for,
+        ...args.attach ? { attach: true } : {}
+      },
+      { command: "docs generate" }
+    );
+  }
+});
+var exportCommand = defineCommand({
+  meta: {
+    name: "export",
+    description: "Generate a rich Markdown export of a CLEO task (frontmatter + body + attachments + memory refs). Uses llmtxt/export.formatMarkdown for canonical serialisation. Use --out <file> to write to disk; omit to print to stdout."
+  },
+  args: {
+    task: {
+      type: "string",
+      description: "Task ID to export (e.g. T947)",
+      required: true
+    },
+    out: {
+      type: "string",
+      description: "Output file path (absolute or relative to project root). Omit for stdout."
+    },
+    "include-attachments": {
+      type: "boolean",
+      default: true,
+      description: "Append attachment manifest section (default: true)"
+    },
+    "include-memory-refs": {
+      type: "boolean",
+      default: false,
+      description: "Append BRAIN memory references section (default: false)"
+    },
+    json: {
+      type: "boolean",
+      description: "Emit result envelope as JSON instead of markdown (returns {markdown, pages, path?})"
+    }
+  },
+  async run({ args }) {
+    const taskId = String(args.task);
+    const includeAttachments = args["include-attachments"] !== false;
+    const includeMemoryRefs = args["include-memory-refs"] === true;
+    const projectRoot = getProjectRoot3();
+    try {
+      const result = await dispatchDocsRaw("query", "llm-output", {
+        mode: "task-export",
+        taskId,
+        includeAttachments,
+        includeMemoryRefs
+      });
+      let writtenPath;
+      if (typeof args.out === "string" && args.out.length > 0) {
+        const outPath = isAbsolute(args.out) ? args.out : resolve3(projectRoot, args.out);
+        await mkdir3(dirname3(outPath), { recursive: true });
+        await writeFile2(outPath, result.content, "utf8");
+        writtenPath = outPath;
+      }
+      if (args.json) {
+        cliOutput(
+          { markdown: result.content, pages: result.sectionCount, path: writtenPath ?? null },
+          { command: "docs export", operation: "docs.export" }
+        );
+      } else {
+        if (writtenPath) {
+          humanInfo(`Wrote ${result.sectionCount} page(s) to ${writtenPath}`);
+        } else {
+          process.stdout.write(result.content);
+          if (!result.content.endsWith("\n")) process.stdout.write("\n");
+        }
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      cliError(`docs export failed: ${message}`, ExitCode5.GENERAL_ERROR, {
+        name: "E_DOCS_EXPORT_FAILED"
+      });
+      process.exit(ExitCode5.GENERAL_ERROR);
+    }
+  }
+});
+var _llmOutputCommand = defineCommand({
+  meta: {
+    name: "llm-output",
+    description: "Unified LLM output: task export (rich Markdown with frontmatter + body + attachments + memory refs) or attachment-bundle (llms.txt summarising all attachments). Replaces `docs export` and `docs generate`."
+  },
+  args: {
+    for: {
+      type: "string",
+      description: "Target entity ID (T###, ses_*, O-*, D-*, L-*, P-*)",
+      required: true
+    },
+    mode: {
+      type: "string",
+      description: "Output mode: 'task-export' or 'attachment-bundle' (auto-detected)"
+    },
+    out: { type: "string", description: "Output file path. Omit for stdout." },
+    "include-attachments": {
+      type: "boolean",
+      default: true,
+      description: "Append attachment manifest (task-export, default: true)"
+    },
+    "include-memory-refs": {
+      type: "boolean",
+      default: false,
+      description: "Append BRAIN memory refs (task-export, default: false)"
+    },
+    attach: {
+      type: "boolean",
+      description: "Save as llms-txt attachment on target (attachment-bundle)"
+    },
+    ...docsOutputArgs
+  },
+  async run({ args }) {
+    const forId = String(args.for);
+    const projectRoot = getProjectRoot3();
+    try {
+      const result = await dispatchDocsRaw("query", "llm-output", {
+        for: forId,
+        ...typeof args.mode === "string" ? { mode: args.mode } : {},
+        includeAttachments: args["include-attachments"] !== false,
+        includeMemoryRefs: args["include-memory-refs"] === true,
+        ...args.attach ? { attach: true } : {}
+      });
+      let writtenPath;
+      if (typeof args.out === "string" && args.out.length > 0) {
+        const outPath = isAbsolute(args.out) ? args.out : resolve3(projectRoot, args.out);
+        await mkdir3(dirname3(outPath), { recursive: true });
+        await writeFile2(outPath, result.content, "utf8");
+        writtenPath = outPath;
+      }
+      if (args.json) {
+        cliOutput(
+          {
+            forId: result.forId,
+            mode: result.mode,
+            content: result.content,
+            sectionCount: result.sectionCount,
+            usedLlmtxtPackage: result.usedLlmtxtPackage,
+            attached: result.attached,
+            attachmentId: result.attachmentId,
+            attachmentSha256: result.attachmentSha256,
+            path: writtenPath ?? null
+          },
+          { command: "docs llm-output", operation: "docs.llm-output" }
+        );
+      } else {
+        if (writtenPath) {
+          humanInfo(
+            `Wrote ${result.sectionCount} ${result.mode === "task-export" ? "page(s)" : "section(s)"} to ${writtenPath}`
+          );
+        } else {
+          process.stdout.write(result.content);
+          if (!result.content.endsWith("\n")) process.stdout.write("\n");
+        }
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      cliError(`docs llm-output failed: ${message}`, ExitCode5.GENERAL_ERROR, {
+        name: "E_DOCS_LLM_OUTPUT_FAILED"
+      });
+      process.exit(ExitCode5.GENERAL_ERROR);
+    }
+  }
+});
+var llmOutputCommand = defineCommand({
+  meta: {
+    name: "llm-output",
+    description: "Unified LLM output: task export (rich Markdown) or attachment-bundle (llms.txt). Replaces `docs export` and `docs generate`."
+  },
+  args: {
+    for: { type: "string", description: "Target entity ID", required: true },
+    mode: {
+      type: "string",
+      description: "Output mode: task-export|attachment-bundle (auto-detected)"
+    },
+    out: { type: "string", description: "Output file path" },
+    "include-attachments": {
+      type: "boolean",
+      default: true,
+      description: "Include attachment manifest (task-export)"
+    },
+    "include-memory-refs": {
+      type: "boolean",
+      default: false,
+      description: "Include memory refs (task-export)"
+    },
+    attach: { type: "boolean", description: "Save as llms-txt attachment (attachment-bundle)" },
+    ...docsOutputArgs
+  },
+  async run({ args }) {
+    const forId = String(args.for);
+    const projectRoot = getProjectRoot3();
+    try {
+      const result = await dispatchDocsRaw("query", "llm-output", {
+        for: forId,
+        ...typeof args.mode === "string" ? { mode: args.mode } : {},
+        includeAttachments: args["include-attachments"] !== false,
+        includeMemoryRefs: args["include-memory-refs"] === true,
+        ...args.attach ? { attach: true } : {}
+      });
+      let writtenPath;
+      if (typeof args.out === "string" && args.out.length > 0) {
+        const outPath = isAbsolute(args.out) ? args.out : resolve3(projectRoot, args.out);
+        await mkdir3(dirname3(outPath), { recursive: true });
+        await writeFile2(outPath, result.content, "utf8");
+        writtenPath = outPath;
+      }
+      if (args.json) {
+        cliOutput(
+          {
+            forId: result.forId,
+            mode: result.mode,
+            content: result.content,
+            sectionCount: result.sectionCount,
+            usedLlmtxtPackage: result.usedLlmtxtPackage,
+            attached: result.attached,
+            attachmentId: result.attachmentId,
+            attachmentSha256: result.attachmentSha256,
+            path: writtenPath ?? null
+          },
+          { command: "docs llm-output", operation: "docs.llm-output" }
+        );
+      } else {
+        if (writtenPath) {
+          humanInfo(
+            `Wrote ${result.sectionCount} ${result.mode === "task-export" ? "page(s)" : "section(s)"} to ${writtenPath}`
+          );
+        } else {
+          process.stdout.write(result.content);
+          if (!result.content.endsWith("\n")) process.stdout.write("\n");
+        }
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      cliError(`docs llm-output failed: ${message}`, ExitCode5.GENERAL_ERROR, {
+        name: "E_DOCS_LLM_OUTPUT_FAILED"
+      });
+      process.exit(ExitCode5.GENERAL_ERROR);
+    }
+  }
+});
+var searchCommand = defineCommand({
+  meta: {
+    name: "search",
+    description: "Search attachments by semantic similarity using llmtxt/similarity.rankBySimilarity. Without --owner, ranks every published doc in the project by content (T9647). Pass --owner to scope to a specific entity (T###, ses_*, O-*) and rank by blob name."
+  },
+  args: {
+    query: {
+      type: "positional",
+      description: "Free-text search query",
+      required: true
+    },
+    owner: {
+      type: "string",
+      description: "Scope search to a specific owner entity ID (legacy name-only ranking)"
+    },
+    type: {
+      type: "string",
+      description: "Filter project-wide search by taxonomy type: spec|adr|research|handoff|note|llm-readme"
+    },
+    limit: {
+      type: "string",
+      description: "Maximum number of results to return (default: 10)"
+    },
+    json: {
+      type: "boolean",
+      description: "Emit LAFS JSON envelope instead of human-readable output"
+    }
+  },
+  async run({ args }) {
+    const limit = args.limit ? Number.parseInt(String(args.limit), 10) : 10;
+    try {
+      const result = await dispatchDocsRaw("query", "search", {
+        query: String(args.query),
+        ...args.owner ? { ownerId: String(args.owner) } : {},
+        limit,
+        ...args.type ? { type: String(args.type) } : {}
+      });
+      cliOutput(result, { command: "docs search", operation: "docs.search" });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      cliError(`docs search failed: ${message}`, ExitCode5.GENERAL_ERROR, {
+        name: "E_DOCS_SEARCH_FAILED"
+      });
+      process.exit(ExitCode5.GENERAL_ERROR);
+    }
+  }
+});
+var findCommand = defineCommand({
+  meta: {
+    name: "find",
+    description: "Find docs similar to a seed slug via llmtxt/similarity.rankBySimilarity. Pass --similar <slug>; results default to the same DocKind as the seed. Use --all-kinds to rank cross-kind, --threshold to set the minimum cosine score, and --limit to cap the number of returned hits.\n\nNamed arguments:\n  --similar <slug>       Slug of the seed doc to anchor similarity against (required for now)\n  --limit <n>            Maximum number of hits to return (default 10)\n  --threshold <0..1>     Minimum cosine score, hits below are dropped (default 0.5)\n  --all-kinds            Disable the same-kind filter and rank cross-kind\n  --json                 Emit LAFS JSON envelope (default for non-TTY)"
+  },
+  args: {
+    similar: {
+      type: "string",
+      description: "Slug of the seed doc to anchor similarity against"
+    },
+    limit: {
+      type: "string",
+      description: "Maximum number of hits to return (default: 10)"
+    },
+    threshold: {
+      type: "string",
+      description: "Minimum cosine similarity score in [0, 1] (default: 0.5)"
+    },
+    "all-kinds": {
+      type: "boolean",
+      description: "Disable the same-kind filter and rank across every DocKind"
+    },
+    json: {
+      type: "boolean",
+      description: "Emit LAFS JSON envelope instead of human-readable output"
+    }
+  },
+  async run({ args, rawArgs }) {
+    try {
+      assertKnownFlags(rawArgs, findCommand.args, "docs find");
+    } catch (err) {
+      if (err instanceof UnknownFlagError) {
+        cliError(err.message, ExitCode5.VALIDATION_ERROR, {
+          name: err.code,
+          fix: err.fix,
+          alternatives: err.suggestions.map((s) => ({ action: s, command: s })),
+          details: { flag: err.flag, knownFlags: err.knownFlags }
+        });
+        process.exit(ExitCode5.VALIDATION_ERROR);
+      }
+      throw err;
+    }
+    const similarSlug = typeof args.similar === "string" ? args.similar.trim() : "";
+    if (similarSlug.length === 0) {
+      cliError("--similar <slug> is required", ExitCode5.VALIDATION_ERROR, {
+        name: "E_VALIDATION",
+        fix: "Example: `cleo docs find --similar adr-073-above-epic-naming --limit 5`."
+      });
+      process.exit(ExitCode5.VALIDATION_ERROR);
+    }
+    let limit;
+    if (typeof args.limit === "string") {
+      const parsed = Number.parseInt(args.limit, 10);
+      if (!Number.isFinite(parsed) || parsed <= 0) {
+        cliError(
+          `--limit must be a positive integer (got "${args.limit}")`,
+          ExitCode5.VALIDATION_ERROR,
+          {
+            name: "E_VALIDATION"
+          }
+        );
+        process.exit(ExitCode5.VALIDATION_ERROR);
+      }
+      limit = parsed;
+    }
+    let threshold;
+    if (typeof args.threshold === "string") {
+      const parsed = Number.parseFloat(args.threshold);
+      if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+        cliError(
+          `--threshold must be a number in [0, 1] (got "${args.threshold}")`,
+          ExitCode5.VALIDATION_ERROR,
+          { name: "E_VALIDATION" }
+        );
+        process.exit(ExitCode5.VALIDATION_ERROR);
+      }
+      threshold = parsed;
+    }
+    const allKinds = args["all-kinds"] === true;
+    try {
+      const result = await dispatchDocsRaw("query", "find", {
+        similarSlug,
+        ...limit !== void 0 ? { limit } : {},
+        ...threshold !== void 0 ? { threshold } : {},
+        allKinds
+      });
+      cliOutput(result, { command: "docs find", operation: "docs.find" });
+    } catch (err) {
+      const code = err instanceof Error && typeof err.code === "string" ? err.code : "E_DOCS_FIND_FAILED";
+      const message = err instanceof Error ? err.message : String(err);
+      cliError(`docs find failed: ${message}`, ExitCode5.GENERAL_ERROR, { name: code });
+      process.exit(ExitCode5.GENERAL_ERROR);
+    }
+  }
+});
+var mergeCommand = defineCommand({
+  meta: {
+    name: "merge",
+    description: "Merge two attachment text contents using llmtxt/sdk diff primitives. Strategies: three-way (default), cherry-pick, multi-diff."
+  },
+  args: {
+    attA: {
+      type: "positional",
+      description: "First attachment ID or text content",
+      required: true
+    },
+    attB: {
+      type: "positional",
+      description: "Second attachment ID or text content",
+      required: true
+    },
+    strategy: {
+      type: "string",
+      description: "Merge strategy: three-way | cherry-pick | multi-diff (default: three-way)"
+    },
+    base: {
+      type: "string",
+      description: "Base content for three-way merge"
+    },
+    out: {
+      type: "string",
+      description: "Write merged content to this file path"
+    },
+    json: {
+      type: "boolean",
+      description: "Emit LAFS JSON envelope"
+    }
+  },
+  async run({ args }) {
+    const projectRoot = getProjectRoot3();
+    const rawStrategy = args.strategy ?? "three-way";
+    const strategy = rawStrategy === "cherry-pick" || rawStrategy === "multi-diff" ? rawStrategy : "three-way";
+    try {
+      const result = await dispatchDocsRaw("query", "merge", {
+        attA: String(args.attA),
+        attB: String(args.attB),
+        strategy,
+        base: args.base ?? void 0
+      });
+      if (typeof args.out === "string" && args.out.length > 0) {
+        const outPath = isAbsolute(args.out) ? args.out : resolve3(projectRoot, args.out);
+        await mkdir3(dirname3(outPath), { recursive: true });
+        await writeFile2(outPath, result.merged, "utf8");
+        humanInfo(`Wrote merged content to ${outPath}`);
+      }
+      cliOutput(result, { command: "docs merge", operation: "docs.merge" });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      cliError(`docs merge failed: ${message}`, ExitCode5.GENERAL_ERROR, {
+        name: "E_DOCS_MERGE_FAILED"
+      });
+      process.exit(ExitCode5.GENERAL_ERROR);
+    }
+  }
+});
+var queryCommand = defineCommand({
+  meta: {
+    name: "query",
+    description: 'Unified docs query surface: semantic search, similar-doc discovery, and entity ranking. Subsumes the legacy search, find, and rank subcommands into one consistent surface.\n\nModes (mutually exclusive):\n  cleo docs query "<text>"       Free-text search\n  cleo docs query --similar <slug>  Find similar to a slug\n  cleo docs query --for <id>     Rank for an entity\n\nCommon flags: --limit <n>, --type <kind>, --json\nFree-text search flags: --owner <id>\nSimilar-to-slug flags: --threshold <0..1>, --all-kinds\nEntity-ranking flags: --text "<query>"\n\n' + docsOutputFlagHelp
+  },
+  args: {
+    query: {
+      type: "positional",
+      description: "Free-text query for semantic search",
+      required: false
+    },
+    similar: {
+      type: "string",
+      description: "Slug of seed doc to find similar docs against (find mode)"
+    },
+    for: {
+      type: "string",
+      description: "Owner entity ID to rank attachments for (rank mode)"
+    },
+    text: {
+      type: "string",
+      description: "Custom query string for the rank mode (default: owner ID)"
+    },
+    type: {
+      type: "string",
+      description: "Filter by taxonomy type: spec|adr|research|handoff|note|llm-readme"
+    },
+    owner: {
+      type: "string",
+      description: "Scope free-text search to a specific owner entity ID"
+    },
+    limit: {
+      type: "string",
+      description: "Maximum number of results to return (default: 10)"
+    },
+    threshold: {
+      type: "string",
+      description: "Minimum cosine similarity score in [0, 1] (for --similar mode, default: 0.5)"
+    },
+    "all-kinds": {
+      type: "boolean",
+      description: "Disable the same-kind filter and rank across every DocKind (for --similar mode)"
+    },
+    ...docsOutputArgs
+  },
+  async run({ args, rawArgs }) {
+    try {
+      assertKnownFlags(rawArgs, queryCommand.args, "docs query");
+    } catch (err) {
+      if (err instanceof UnknownFlagError) {
+        cliError(err.message, ExitCode5.VALIDATION_ERROR, {
+          name: err.code,
+          fix: err.fix,
+          alternatives: err.suggestions.map((s) => ({ action: s, command: s })),
+          details: { flag: err.flag, knownFlags: err.knownFlags }
+        });
+        process.exit(ExitCode5.VALIDATION_ERROR);
+      }
+      throw err;
+    }
+    const similarSlug = typeof args.similar === "string" ? args.similar.trim() : "";
+    const forId = typeof args.for === "string" ? args.for.trim() : "";
+    const textQuery = typeof args.query === "string" ? String(args.query) : "";
+    const customQuery = typeof args.text === "string" ? String(args.text) : void 0;
+    const typeFilter = typeof args.type === "string" ? String(args.type) : void 0;
+    const ownerScope = typeof args.owner === "string" ? String(args.owner) : void 0;
+    const modes = [];
+    if (similarSlug.length > 0) modes.push("--similar");
+    if (forId.length > 0) modes.push("--for");
+    if (textQuery.length > 0) modes.push("<query>");
+    if (modes.length === 0) {
+      cliError(
+        "docs query requires a query mode: pass a free-text <query>, --similar <slug>, or --for <id>",
+        ExitCode5.VALIDATION_ERROR,
+        {
+          name: "E_VALIDATION",
+          fix: 'Examples: cleo docs query "authentication flow" | cleo docs query --similar adr-073 | cleo docs query --for T123'
+        }
+      );
+      process.exit(ExitCode5.VALIDATION_ERROR);
+    }
+    if (modes.length > 1) {
+      cliError(
+        `docs query modes are mutually exclusive \u2014 got ${modes.join(", ")}. Choose one.`,
+        ExitCode5.VALIDATION_ERROR,
+        {
+          name: "E_VALIDATION",
+          fix: "Pass exactly one of: free-text <query>, --similar <slug>, or --for <id>"
+        }
+      );
+      process.exit(ExitCode5.VALIDATION_ERROR);
+    }
+    let limit;
+    if (typeof args.limit === "string") {
+      const parsed = Number.parseInt(args.limit, 10);
+      if (!Number.isFinite(parsed) || parsed <= 0) {
+        cliError(
+          `--limit must be a positive integer (got "${args.limit}")`,
+          ExitCode5.VALIDATION_ERROR,
+          { name: "E_VALIDATION" }
+        );
+        process.exit(ExitCode5.VALIDATION_ERROR);
+      }
+      limit = parsed;
+    }
+    let threshold;
+    if (typeof args.threshold === "string") {
+      const parsed = Number.parseFloat(args.threshold);
+      if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+        cliError(
+          `--threshold must be a number in [0, 1] (got "${args.threshold}")`,
+          ExitCode5.VALIDATION_ERROR,
+          { name: "E_VALIDATION" }
+        );
+        process.exit(ExitCode5.VALIDATION_ERROR);
+      }
+      threshold = parsed;
+    }
+    const allKinds = args["all-kinds"] === true;
+    try {
+      if (similarSlug.length > 0) {
+        const result = await dispatchDocsRaw("query", "find", {
+          similarSlug,
+          ...limit !== void 0 ? { limit } : {},
+          ...threshold !== void 0 ? { threshold } : {},
+          allKinds
+        });
+        cliOutput(result, { command: "docs query", operation: "docs.find" });
+      } else if (forId.length > 0) {
+        const result = await dispatchDocsRaw("query", "rank", {
+          ownerId: forId,
+          query: customQuery ?? void 0
+        });
+        cliOutput(result, { command: "docs query", operation: "docs.rank" });
+      } else {
+        const result = await dispatchDocsRaw("query", "search", {
+          query: textQuery,
+          ...ownerScope ? { ownerId: ownerScope } : {},
+          ...limit !== void 0 ? { limit } : {},
+          ...typeFilter ? { type: typeFilter } : {}
+        });
+        cliOutput(result, { command: "docs query", operation: "docs.search" });
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const code = err instanceof Error && typeof err.code === "string" ? err.code : "E_DOCS_QUERY_FAILED";
+      cliError(`docs query failed: ${message}`, ExitCode5.GENERAL_ERROR, { name: code });
+      process.exit(ExitCode5.GENERAL_ERROR);
+    }
+  }
+});
+var rankCommand = defineCommand({
+  meta: {
+    name: "rank",
+    description: "Rank attachments for an entity by relevance using llmtxt/similarity.rankBySimilarity. Pass --query to use a custom query; otherwise the entity ID anchors the ranking."
+  },
+  args: {
+    for: {
+      type: "string",
+      description: "Owner entity ID (T###, ses_*, O-*)",
+      required: true
+    },
+    query: {
+      type: "string",
+      description: "Optional free-text query to rank against (default: owner ID)"
+    },
+    json: {
+      type: "boolean",
+      description: "Emit LAFS JSON envelope"
+    }
+  },
+  async run({ args }) {
+    try {
+      const result = await dispatchDocsRaw("query", "rank", {
+        ownerId: String(args.for),
+        query: args.query ?? void 0
+      });
+      cliOutput(result, { command: "docs rank", operation: "docs.rank" });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      cliError(`docs rank failed: ${message}`, ExitCode5.GENERAL_ERROR, {
+        name: "E_DOCS_RANK_FAILED"
+      });
+      process.exit(ExitCode5.GENERAL_ERROR);
+    }
+  }
+});
+var docsUpdateOperation = resolve("mutate", "docs", "update")?.def;
+if (docsUpdateOperation === void 0) {
+  throw new Error("docs.update operation is missing from the registry");
+}
+var docsUpdateSchema = describeOperation(docsUpdateOperation, {
+  includeGates: false,
+  includeExamples: true
+});
+var docsUpdateArgs = paramsToCittyArgs(getOperationParams("mutate", "docs", "update"));
+var docsUpdateCliArgs = {
+  ...docsUpdateArgs,
+  ...docsOutputArgs
+};
+function toKebabFlag(name) {
+  return name.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
+}
+function formatDocsUpdateContractHelp() {
+  const positional = docsUpdateSchema.params.filter((param) => param.cli?.positional === true);
+  const named = docsUpdateSchema.params.filter((param) => param.cli?.positional !== true);
+  const lines = [
+    docsUpdateSchema.description,
+    "",
+    "Positional arguments:",
+    ...positional.map((param) => `  <${param.name}>                 ${param.description}`),
+    "",
+    "Named arguments:",
+    ...named.map((param) => {
+      const flag = param.cli?.flag ?? toKebabFlag(param.name);
+      const enumSuffix = param.enum !== void 0 ? ` (${param.enum.join("|")})` : "";
+      return `  --${flag} <${param.type}>          ${param.description}${enumSuffix}`;
+    })
+  ];
+  if ((docsUpdateSchema.examples ?? []).length > 0) {
+    lines.push("", "Examples:");
+    for (const example of docsUpdateSchema.examples ?? []) {
+      lines.push(`  ${example.command}`, `    ${example.description}`);
+    }
+  }
+  lines.push(
+    "",
+    "Output flags:",
+    docsOutputFlagHelp,
+    "",
+    "Renderer support: this command shares the registry schema surfaced by `cleo schema docs.update --format human --include-examples`."
+  );
+  return lines.join("\n");
+}
+var updateCommand = defineCommand({
+  meta: {
+    name: "update",
+    description: formatDocsUpdateContractHelp()
+  },
+  args: docsUpdateCliArgs,
+  async run({ args, rawArgs }) {
+    try {
+      assertKnownFlags(rawArgs, updateCommand.args, "docs update");
+    } catch (err) {
+      if (err instanceof UnknownFlagError) {
+        cliError(err.message, ExitCode5.VALIDATION_ERROR, {
+          name: err.code,
+          fix: err.fix,
+          alternatives: err.suggestions.map((s) => ({ action: s, command: s })),
+          details: { flag: err.flag, knownFlags: err.knownFlags }
+        });
+        process.exit(ExitCode5.VALIDATION_ERROR);
+      }
+      throw err;
+    }
+    const slug = String(args.slug);
+    const filePath = typeof args.file === "string" ? args.file : void 0;
+    const inlineContent = typeof args.content === "string" ? args.content : void 0;
+    if (filePath !== void 0 && inlineContent !== void 0) {
+      cliError("--file and --content are mutually exclusive", ExitCode5.VALIDATION_ERROR, {
+        name: "E_VALIDATION",
+        fix: "Use `cleo docs update <slug> --file <path>` OR `--content <text>` (not both)."
+      });
+      process.exit(ExitCode5.VALIDATION_ERROR);
+    }
+    if (filePath === void 0 && inlineContent === void 0 && typeof args.status !== "string") {
+      cliError(
+        "provide --file <path>, --content <text>, or --status <status> alone",
+        ExitCode5.VALIDATION_ERROR,
+        {
+          name: "E_VALIDATION",
+          fix: 'Example: `cleo docs update my-doc --file ./new.md`, `--content "..."`, or `cleo docs update my-doc --status accepted` to change only the lifecycle status.'
+        }
+      );
+      process.exit(ExitCode5.VALIDATION_ERROR);
+    }
+    let resolvedFile;
+    if (filePath !== void 0) {
+      const routing = resolveWorktreeRouting();
+      resolvedFile = resolveWorktreeFilePath(filePath, routing);
+    }
+    await dispatchFromCli(
+      "mutate",
+      "docs",
+      "update",
+      {
+        slug,
+        ...resolvedFile !== void 0 ? { file: resolvedFile } : {},
+        ...args["allow-external"] === true ? { allowExternal: true } : {},
+        ...inlineContent !== void 0 ? { content: inlineContent } : {},
+        ...typeof args.message === "string" ? { message: args.message } : {},
+        ...typeof args.status === "string" ? { status: args.status } : {},
+        ...args["dry-run"] === true ? { dryRun: true } : {},
+        ...args.strict === true ? { strict: true } : {},
+        ...typeof args["attached-by"] === "string" ? { attachedBy: args["attached-by"] } : {}
+      },
+      { command: "docs update" }
+    );
+  }
+});
+var versionsCommand = defineCommand({
+  meta: {
+    name: "versions",
+    description: "List all SHA-256 content-address versions of attachments for an entity. Use --name to filter by a specific filename."
+  },
+  args: {
+    for: {
+      type: "string",
+      description: "Owner entity ID (T###, ses_*, O-*)",
+      required: true
+    },
+    name: {
+      type: "string",
+      description: "Optional filename filter (exact match)"
+    },
+    json: {
+      type: "boolean",
+      description: "Emit LAFS JSON envelope"
+    }
+  },
+  async run({ args }) {
+    try {
+      const result = await dispatchDocsRaw("query", "versions", {
+        ownerId: String(args.for),
+        name: args.name ?? void 0
+      });
+      cliOutput(result, { command: "docs versions", operation: "docs.versions" });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      cliError(`docs versions failed: ${message}`, ExitCode5.GENERAL_ERROR, {
+        name: "E_DOCS_VERSIONS_FAILED"
+      });
+      process.exit(ExitCode5.GENERAL_ERROR);
+    }
+  }
+});
+var publishCommand = defineCommand({
+  meta: {
+    name: "publish",
+    description: "Publish a doc to a local file (--target file) or a GitHub PR (--target pr). Default target is file. Use --target pr with a slug-or-id to open/update a PR. Use --dry-run to preview without side effects."
+  },
+  args: {
+    "slug-or-id": {
+      type: "positional",
+      description: "Slug, attachment id, or full sha256 hex of the doc to publish. Required for --target pr."
+    },
+    target: {
+      type: "string",
+      description: "Publish target: file (local git-tracked path) or pr (GitHub PR). Default: file.",
+      default: "file"
+    },
+    for: {
+      type: "string",
+      description: "Owner entity ID whose attachment to publish (T###, ses_*, O-*). Required for --target file."
+    },
+    to: {
+      type: "string",
+      description: "Destination file path (absolute or relative to project root). Required for --target file."
+    },
+    attachment: {
+      type: "string",
+      description: "Specific attachment ID or SHA-256 to publish (default: latest)"
+    },
+    slug: {
+      type: "string",
+      description: "Override the slug used for the branch + filename. Required when <slug-or-id> is an attachment id or sha256 with no stored slug."
+    },
+    type: {
+      type: "string",
+      description: "Override the publish dir taxonomy (spec|adr|research|handoff|note|llm-readme)."
+    },
+    title: {
+      type: "string",
+      description: "Override the PR title. Default: the commit subject `docs(<T####|type>): publish <slug>`."
+    },
+    task: {
+      type: "string",
+      description: "Owning task id (T####) for the commit subject + `Task:` trailer. Default: the doc's single task owner; required when it has several."
+    },
+    body: {
+      type: "string",
+      description: "Override the PR body. Default: an auto-generated summary."
+    },
+    base: {
+      type: "string",
+      description: "Base branch for the PR. Default: main."
+    },
+    "dry-run": {
+      type: "boolean",
+      description: "Preview what would happen without side effects. Reports resolved target, mode, and parameters. No files are written and no git/gh commands are invoked."
+    },
+    json: { type: "boolean", description: "Emit LAFS JSON envelope" }
+  },
+  async run({ args }) {
+    const target = String(args.target ?? "file");
+    const dryRun = args["dry-run"] === true;
+    if (dryRun) {
+      const details = { target, dryRun: true };
+      if (target === "pr") {
+        details.slugOrId = String(args["slug-or-id"] ?? "");
+        if (args.slug) details.slug = String(args.slug);
+        if (args.type) details.type = String(args.type);
+        if (args.title) details.title = String(args.title);
+        if (args.task) details.taskId = String(args.task);
+      } else {
+        details.for = args.for ? String(args.for) : null;
+        details.to = args.to ? String(args.to) : null;
+        if (args.attachment) details.attachment = String(args.attachment);
+      }
+      cliOutput(details, { command: "docs publish", operation: "docs.publish" });
+      return;
+    }
+    if (target === "pr") {
+      const slugOrId = String(args["slug-or-id"] ?? "");
+      if (!slugOrId) {
+        cliError(
+          "docs publish --target pr requires a slug-or-id argument",
+          ExitCode5.GENERAL_ERROR,
+          { name: "E_MISSING_ARG" }
+        );
+        process.exit(ExitCode5.GENERAL_ERROR);
+      }
+      const result = await dispatchDocsRaw("mutate", "publish", {
+        slugOrId,
+        target: "pr",
+        ...typeof args.slug === "string" ? { slug: args.slug } : {},
+        ...typeof args.type === "string" ? { type: args.type } : {},
+        ...typeof args.title === "string" ? { title: args.title } : {},
+        ...typeof args.body === "string" ? { body: args.body } : {},
+        ...typeof args.base === "string" ? { base: args.base } : {},
+        ...typeof args.task === "string" ? { taskId: args.task } : {}
+      });
+      if (result.success) {
+        cliOutput(result.data, { command: "docs publish", operation: "docs.publish" });
+        return;
+      }
+      const e = result.error;
+      cliError(
+        e.message,
+        ExitCode5.GENERAL_ERROR,
+        {
+          name: e.codeName,
+          ...e.fix ? { fix: e.fix } : {},
+          ...e.alternatives ? { alternatives: e.alternatives.map((alt) => ({ action: alt, command: alt })) } : {},
+          ...e.details ? { details: e.details } : {}
+        },
+        { operation: "docs.publish" }
+      );
+      process.exit(ExitCode5.GENERAL_ERROR);
+    }
+    if (!args.for || !args.to) {
+      cliError(
+        "docs publish --target file requires --for <ownerId> and --to <path>",
+        ExitCode5.GENERAL_ERROR,
+        { name: "E_MISSING_ARG" }
+      );
+      process.exit(ExitCode5.GENERAL_ERROR);
+    }
+    try {
+      const result = await dispatchDocsRaw("mutate", "publish", {
+        ownerId: String(args.for),
+        toPath: String(args.to),
+        attachmentId: args.attachment ?? void 0,
+        target: "file"
+      });
+      cliOutput(result, { command: "docs publish", operation: "docs.publish" });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      cliError(`docs publish failed: ${message}`, ExitCode5.GENERAL_ERROR, {
+        name: "E_DOCS_PUBLISH_FAILED"
+      });
+      process.exit(ExitCode5.GENERAL_ERROR);
+    }
+  }
+});
+var publishPrCommand = defineCommand({
+  meta: {
+    name: "publish-pr",
+    description: "[DEPRECATED] Use `docs publish --target pr` instead. Publish an attachment to a GitHub PR. Opens a new PR on branch `docs/<slug>` with frontmatter, or atomically updates the existing open PR for the same slug. Use --dry-run to preview without side effects."
+  },
+  args: {
+    "slug-or-id": {
+      type: "positional",
+      description: "Slug, attachment id, or full sha256 hex of the doc to publish",
+      required: true
+    },
+    slug: { type: "string", description: "Override the slug used for the branch + filename." },
+    type: {
+      type: "string",
+      description: "Override the publish dir taxonomy (spec|adr|research|handoff|note|llm-readme)."
+    },
+    title: {
+      type: "string",
+      description: "Override the PR title. Default: the commit subject `docs(<T####|type>): publish <slug>`."
+    },
+    task: {
+      type: "string",
+      description: "Owning task id (T####) for the commit subject + `Task:` trailer. Default: the doc's single task owner; required when it has several."
+    },
+    body: {
+      type: "string",
+      description: "Override the PR body. Default: an auto-generated summary."
+    },
+    base: { type: "string", description: "Base branch for the PR. Default: main." },
+    "dry-run": { type: "boolean", description: "Preview what would happen without side effects." }
+  },
+  async run({ args }) {
+    humanInfo(
+      "[deprecated] `docs publish-pr` is deprecated. Use `docs publish --target pr <slug-or-id>` instead."
+    );
+    const slugOrId = String(args["slug-or-id"]);
+    if (args["dry-run"] === true) {
+      const details = { slugOrId, target: "pr", dryRun: true };
+      if (args.slug) details.slug = String(args.slug);
+      if (args.type) details.type = String(args.type);
+      if (args.title) details.title = String(args.title);
+      if (args.task) details.taskId = String(args.task);
+      cliOutput(details, { command: "docs publish-pr", operation: "docs.publish" });
+      return;
+    }
+    const result = await dispatchDocsRaw("mutate", "publish", {
+      slugOrId,
+      target: "pr",
+      ...typeof args.slug === "string" ? { slug: args.slug } : {},
+      ...typeof args.type === "string" ? { type: args.type } : {},
+      ...typeof args.title === "string" ? { title: args.title } : {},
+      ...typeof args.body === "string" ? { body: args.body } : {},
+      ...typeof args.base === "string" ? { base: args.base } : {},
+      ...typeof args.task === "string" ? { taskId: args.task } : {}
+    });
+    if (result.success) {
+      cliOutput(result.data, { command: "docs publish-pr", operation: "docs.publish" });
+      return;
+    }
+    const e = result.error;
+    cliError(
+      e.message,
+      ExitCode5.GENERAL_ERROR,
+      {
+        name: e.codeName,
+        ...e.fix ? { fix: e.fix } : {},
+        ...e.alternatives ? { alternatives: e.alternatives.map((alt) => ({ action: alt, command: alt })) } : {},
+        ...e.details ? { details: e.details } : {}
+      },
+      { operation: "docs.publish" }
+    );
+    process.exit(ExitCode5.GENERAL_ERROR);
+  }
+});
+var checkCommand = defineCommand({
+  meta: {
+    name: "check",
+    description: "Unified drift management: check documentation for drift, status, and gaps. Use --drift, --status, --gaps for specific checks; runs all by default."
+  },
+  args: {
+    drift: {
+      type: "boolean",
+      description: "Run legacy drift check (scripts/ vs COMMANDS-INDEX.json)"
+    },
+    status: {
+      type: "boolean",
+      description: "Run git\u21C4llmtxt drift check (published files vs docs SSoT)"
+    },
+    gaps: { type: "boolean", description: "Run knowledge transfer gap check (review docs)" },
+    all: {
+      type: "boolean",
+      description: "Run all three checks (default when no mode flag is set)"
+    },
+    quick: { type: "boolean", description: "Drift check only: quick mode (commands only)" },
+    strict: { type: "boolean", description: "Exit with non-zero code on any drift detection" },
+    epic: { type: "string", description: "Gap check only: filter by epic ID" },
+    task: { type: "string", description: "Gap check only: filter by task ID" },
+    json: { type: "boolean", description: "Emit LAFS JSON envelope" }
+  },
+  async run({ args }) {
+    const hasExplicit = args.drift === true || args.status === true || args.gaps === true;
+    const runDrift = args.drift === true || args.all === true || !hasExplicit;
+    const runStatus = args.status === true || args.all === true || !hasExplicit;
+    const runGaps = args.gaps === true || args.all === true || !hasExplicit;
+    const projectRoot = process.cwd();
+    const results = {};
+    let anyDrift = false;
+    try {
+      if (runDrift) {
+        const r = await detectDrift(projectRoot);
+        results.drift = r;
+        if (r.status !== "clean") anyDrift = true;
+      }
+      if (runStatus) {
+        const r = await dispatchDocsRaw("query", "status", {});
+        results.status = r;
+        if (!r.allInSync) anyDrift = true;
+      }
+      if (runGaps) {
+        const r = await runGapCheck(projectRoot, args.epic ?? args.task ?? void 0);
+        results.gaps = r;
+        if (r.length > 0) anyDrift = true;
+      }
+      cliOutput(results, {
+        command: "docs check",
+        message: anyDrift ? "Drift detected \u2014 see results for details" : "All checks passed \u2014 no drift detected"
+      });
+      if (args.strict && anyDrift) process.exit(2);
+    } catch (err) {
+      if (err instanceof CleoError2) {
+        cliError(err.message, err.code, { name: "E_DOCS_CHECK_FAILED" });
+        process.exit(err.code);
+      }
+      throw err;
+    }
+  }
+});
+var syncCommand = defineCommand({
+  meta: {
+    name: "sync",
+    description: "Bidirectional docs sync. Use --from <path> --for <ownerId> to ingest a git file as a new blob version. Without --from, runs the legacy drift check between scripts/ and COMMANDS-INDEX.json."
+  },
+  args: {
+    from: {
+      type: "string",
+      description: "Git-tracked file path to ingest as a new blob version (triggers reverse-ingest mode)"
+    },
+    for: {
+      type: "string",
+      description: "Owner entity ID for reverse-ingest mode (T###, ses_*, O-*). Required when --from is set."
+    },
+    name: {
+      type: "string",
+      description: "Override the blob name used in the manifest. Default: basename of --from."
+    },
+    "content-type": {
+      type: "string",
+      description: "IANA MIME type recorded with the new blob version (default: application/octet-stream)"
+    },
+    quick: {
+      type: "boolean",
+      description: "Legacy mode only: quick check (commands only)"
+    },
+    strict: {
+      type: "boolean",
+      description: "Legacy mode only: exit with error on any drift"
+    }
+  },
+  async run({ args }) {
+    if (args.from) {
+      const ownerId = args.for ?? void 0;
+      if (!ownerId) {
+        cliError(
+          "--for <ownerId> is required when --from <path> is set",
+          ExitCode5.VALIDATION_ERROR,
+          { name: "E_VALIDATION" }
+        );
+        process.exit(ExitCode5.VALIDATION_ERROR);
+      }
+      try {
+        const result = await dispatchDocsRaw("mutate", "sync", {
+          ownerId: String(ownerId),
+          fromPath: String(args.from),
+          blobName: args.name ?? void 0,
+          contentType: args["content-type"] ?? void 0
+        });
+        cliOutput(result, { command: "docs sync", operation: "docs.sync" });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        cliError(`docs sync failed: ${message}`, ExitCode5.GENERAL_ERROR, {
+          name: "E_DOCS_SYNC_FAILED"
+        });
+        process.exit(ExitCode5.GENERAL_ERROR);
+      }
+      return;
+    }
+    try {
+      const projectRoot = process.cwd();
+      const result = await detectDrift(projectRoot);
+      cliOutput(
+        {
+          status: result.status,
+          missingFromIndex: result.missingFromIndex,
+          missingFromScripts: result.missingFromScripts,
+          warnings: result.warnings
+        },
+        {
+          command: "docs",
+          message: result.status === "clean" ? "Documentation is in sync" : `Drift detected: ${result.warnings.join("; ")}`
+        }
+      );
+      if (args.strict && result.status !== "clean") {
+        process.exit(result.status === "error" ? 2 : 1);
+      }
+    } catch (err) {
+      if (err instanceof CleoError2) {
+        cliError(err.message, err.code, { name: "E_DOCS_SYNC_FAILED" });
+        process.exit(err.code);
+      }
+      throw err;
+    }
+  }
+});
+var statusCommand = defineCommand({
+  meta: {
+    name: "status",
+    description: "Compare published files on disk against the docs SSoT and report drift. Exits 0 when all entries are in-sync, 2 when any drift is present."
+  },
+  args: {
+    json: {
+      type: "boolean",
+      description: "Emit LAFS JSON envelope"
+    }
+  },
+  async run() {
+    try {
+      const result = await dispatchDocsRaw("query", "status", {});
+      cliOutput(result, { command: "docs status", operation: "docs.status" });
+      if (!result.allInSync) {
+        process.exit(2);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      cliError(`docs status failed: ${message}`, ExitCode5.GENERAL_ERROR, {
+        name: "E_DOCS_STATUS_FAILED"
+      });
+      process.exit(ExitCode5.GENERAL_ERROR);
+    }
+  }
+});
+var gapCheckCommand = defineCommand({
+  meta: {
+    name: "gap-check",
+    description: "Validate knowledge transfer from review docs to canonical docs"
+  },
+  args: {
+    epic: {
+      type: "string",
+      description: "Filter by epic ID"
+    },
+    task: {
+      type: "string",
+      description: "Filter by task ID"
+    }
+  },
+  async run({ args }) {
+    try {
+      const projectRoot = process.cwd();
+      const filterId = args.epic ?? args.task;
+      const gaps = await runGapCheck(projectRoot, filterId);
+      if (gaps.length === 0) {
+        cliOutput(
+          { gapCount: 0, results: [] },
+          { command: "docs", message: "No documentation gaps found" }
+        );
+      } else {
+        cliOutput(
+          { gapCount: gaps.length, results: gaps },
+          { command: "docs", message: `Found ${gaps.length} document(s) with gaps` }
+        );
+      }
+    } catch (err) {
+      if (err instanceof CleoError2) {
+        cliError(err.message, err.code, { name: "E_DOCS_GAP_CHECK_FAILED" });
+        process.exit(err.code);
+      }
+      throw err;
+    }
+  }
+});
+var importCommand = defineCommand({
+  meta: {
+    name: "import",
+    description: "Recursively import .md files from <dir> into the docs SSoT. Auto-classifies type by source-dir (.cleo/adrs/\u2192adr, .cleo/research/\u2192research, .cleo/agent-outputs/\u2192note, docs/\u2192spec). Idempotent via SHA-dedup. Use --dry-run to preview without writing."
+  },
+  args: {
+    dir: {
+      type: "positional",
+      description: "Absolute or project-relative directory to scan recursively",
+      required: true
+    },
+    "dry-run": {
+      type: "boolean",
+      description: "Print what would be imported without writing to the docs SSoT"
+    },
+    force: {
+      type: "boolean",
+      description: "Bypass SHA-dedup and re-import existing content. Bypass is logged to .cleo/audit/import-force-bypass.jsonl for traceability."
+    },
+    "audit-manifest": {
+      type: "string",
+      description: "Override the audit manifest output path. Default: <project-root>/docs-import-<ts>.json"
+    },
+    json: {
+      type: "boolean",
+      description: "Emit LAFS JSON envelope (default for agent callers)"
+    }
+  },
+  async run({ args }) {
+    const projectRoot = getProjectRoot3();
+    const dirArg = String(args.dir);
+    const scanRoot = isAbsolute(dirArg) ? dirArg : resolve3(projectRoot, dirArg);
+    const dryRun = args["dry-run"] === true;
+    const force = args.force === true;
+    const manifestPath = args["audit-manifest"] ? isAbsolute(String(args["audit-manifest"])) ? String(args["audit-manifest"]) : resolve3(projectRoot, String(args["audit-manifest"])) : void 0;
+    if (force) {
+      const auditLine = `${JSON.stringify({
+        ts: (/* @__PURE__ */ new Date()).toISOString(),
+        scanRoot,
+        reason: "force-flag-bypass"
+      })}
+`;
+      try {
+        await mkdir3(join4(projectRoot, ".cleo", "audit"), { recursive: true });
+        await appendFile(
+          join4(projectRoot, ".cleo", "audit", "import-force-bypass.jsonl"),
+          auditLine,
+          "utf-8"
+        );
+      } catch {
+      }
+    }
+    try {
+      const result = await dispatchDocsRaw("mutate", "import", {
+        scanRoot,
+        dryRun,
+        force,
+        manifestPath
+      });
+      cliOutput(result, { command: "docs import", operation: "docs.import" });
+    } catch (err) {
+      if (err instanceof CounterMismatchError) {
+        cliError(err.message, ExitCode5.GENERAL_ERROR, {
+          name: "E_COUNTER_MISMATCH"
+        });
+        process.exit(ExitCode5.GENERAL_ERROR);
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      cliError(`docs import failed: ${message}`, ExitCode5.GENERAL_ERROR, {
+        name: "E_DOCS_IMPORT_FAILED"
+      });
+      process.exit(ExitCode5.GENERAL_ERROR);
+    }
+  }
+});
+function toWireKind(meta) {
+  return {
+    kind: meta.kind,
+    label: meta.label,
+    description: meta.description,
+    defaultOwnerKind: meta.defaultOwnerKind,
+    publishDir: meta.publishDir,
+    requiresEntityId: meta.requiresEntityId,
+    ...meta.entityIdPattern ? { entityIdPattern: meta.entityIdPattern.source } : {},
+    isExtension: meta.isExtension === true
+  };
+}
+function loadCliRegistry(projectRoot) {
+  try {
+    return { registry: DocKindRegistry.load(projectRoot) };
+  } catch (err) {
+    if (err instanceof DocKindConfigError) {
+      return {
+        registry: DocKindRegistry.builtinOnly(),
+        configError: { source: err.source, message: err.message }
+      };
+    }
+    throw err;
+  }
+}
+var schemaCommand = defineCommand({
+  meta: {
+    name: "schema",
+    description: "Emit the canonical doc-kind taxonomy registry (built-ins + project extensions) as a LAFS envelope. The schema is the single source of truth for the --type values accepted by `cleo docs add` and the publish-dir layout used by `cleo docs publish-pr`. (T11142)."
+  },
+  args: {
+    counts: {
+      type: "boolean",
+      description: "Include per-kind attachment counts from the project SSoT"
+    },
+    "include-counts": {
+      type: "boolean",
+      description: "DEPRECATED -- use --counts instead. Accepted for backward compatibility but will be removed in a future release."
+    }
+  },
+  async run({ args }) {
+    const projectRoot = getProjectRoot3();
+    const { registry, configError } = loadCliRegistry(projectRoot);
+    const kinds = registry.list().map(toWireKind);
+    const extensionsCount = kinds.filter((k) => k.isExtension).length;
+    const wantCounts = args.counts === true || args["include-counts"] === true;
+    let counts;
+    if (wantCounts) {
+      counts = {};
+      const { createAttachmentStore: createAttachmentStore2 } = await import("@cleocode/core/store/attachment-store");
+      const store = createAttachmentStore2();
+      for (const k of kinds) counts[k.kind] = 0;
+      try {
+        const rows = await store.listAllInProject(projectRoot);
+        for (const row of rows) {
+          const key = row.type;
+          if (key && key in counts) counts[key] = (counts[key] ?? 0) + 1;
+        }
+      } catch {
+      }
+    }
+    cliOutput(
+      {
+        version: 1,
+        builtinsCount: kinds.length - extensionsCount,
+        extensionsCount,
+        kinds,
+        ...counts ? { counts } : {},
+        ...configError ? { configError } : {}
+      },
+      { command: "docs schema", operation: "docs.schema" }
+    );
+  }
+});
+var listTypesCommand = defineCommand({
+  meta: {
+    name: "list-types",
+    description: "DEPRECATED -- use `cleo docs schema` instead. Lists every registered doc kind (T11142)."
+  },
+  args: {
+    counts: {
+      type: "boolean",
+      description: "Include per-kind attachment counts from the project SSoT"
+    },
+    "include-counts": {
+      type: "boolean",
+      description: "DEPRECATED -- use --counts instead."
+    }
+  },
+  async run({ args }) {
+    pushWarning({
+      code: "W_DEPRECATED_COMMAND",
+      message: "cleo docs list-types is deprecated -- use `cleo docs schema` instead (T11142)",
+      deprecated: "docs list-types",
+      replacement: "docs schema"
+    });
+    const projectRoot = getProjectRoot3();
+    const { registry, configError } = loadCliRegistry(projectRoot);
+    const kinds = registry.list().map(toWireKind);
+    const extensionsCount = kinds.filter((k) => k.isExtension).length;
+    const wantCounts = args.counts === true || args["include-counts"] === true;
+    let counts;
+    if (wantCounts) {
+      counts = {};
+      const { createAttachmentStore: createAttachmentStore2 } = await import("@cleocode/core/store/attachment-store");
+      const store = createAttachmentStore2();
+      for (const k of kinds) counts[k.kind] = 0;
+      try {
+        const rows = await store.listAllInProject(projectRoot);
+        for (const row of rows) {
+          const key = row.type;
+          if (key && key in counts) counts[key] = (counts[key] ?? 0) + 1;
+        }
+      } catch {
+      }
+    }
+    cliOutput(
+      {
+        version: 1,
+        builtinsCount: kinds.length - extensionsCount,
+        extensionsCount,
+        kinds,
+        ...counts ? { counts } : {},
+        ...configError ? { configError } : {}
+      },
+      {
+        command: "docs list-types",
+        operation: "docs.list-types"
+      }
+    );
+  }
+});
+var docsCommand = defineCommand({
+  meta: {
+    name: "docs",
+    description: "Canonical six-verb docs path: add, update, fetch, list, remove, publish. Unified query: query (subsumes search/find/rank). LLM output: llm-output (replaces generate + export). Advanced: supersede, merge, graph, versions. Audit: audit (query the immutable docs audit trail). Legacy/migration: search, find, rank, sync, status, gap-check, import (use query for new work). Viewer: viewer (start/stop/open/status). Utilities: schema (list-types \u2192 schema)."
+  },
+  subCommands: {
+    // T11136 — Unified drift management (consolidates sync/status/gap-check)
+    check: checkCommand,
+    // Canonical six-verb path (add, update, fetch, list, remove, publish)
+    add: addCommand,
+    update: updateCommand,
+    fetch: fetchCommand,
+    list: listCommand,
+    remove: removeCommand,
+    publish: publishCommand,
+    // T11176 — unified search/find/rank surface (preferred entry point)
+    query: queryCommand,
+    // Advanced primitives
+    supersede: supersedeCommand,
+    generate: generateCommand,
+    export: exportCommand,
+    "llm-output": llmOutputCommand,
+    merge: mergeCommand,
+    // T10164 — DocProvenanceResponse-typed graph (`--root <slug>|<taskId>`).
+    graph: graphCommand,
+    // T11875 — display-alias assignment (`set-alias <slug> <number>`), decoupled from slug.
+    "set-alias": setAliasCommand,
+    // Legacy aliases (use `query` for new work — retained for backward compatibility)
+    search: searchCommand,
+    find: findCommand,
+    rank: rankCommand,
+    versions: versionsCommand,
+    "publish-pr": publishPrCommand,
+    // T11182 — unified docs audit trail
+    audit: auditCommand,
+    // Legacy/migration (use canonical verbs for new work)
+    sync: syncCommand,
+    status: statusCommand,
+    "gap-check": gapCheckCommand,
+    import: importCommand,
+    // Utilities
+    // T9788 — canonical doc-kind taxonomy discovery surface.
+    schema: schemaCommand,
+    "list-types": listTypesCommand,
+    ...docsViewerSubcommands
+  },
+  async run({ cmd, rawArgs }) {
+    const firstArg = rawArgs?.find((a) => !a.startsWith("-"));
+    if (firstArg && cmd.subCommands && firstArg in cmd.subCommands) return;
+    await showUsage(cmd);
+  }
+});
+export {
+  _llmOutputCommand,
+  docsCommand
+};
+//# sourceMappingURL=docs-DPPDFTWR.js.map