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

package/dist/cli/docs-CLQKEEUK.js

@@ -0,0 +1,1710 @@
+(() => {
+  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 {
+  defineTypedHandler,
+  lafsError,
+  lafsSuccess,
+  typedDispatch
+} from "./chunk-QWNKLLLG.js";
+import {
+  lazyOperation
+} from "./chunk-TYC7G5LF.js";
+import {
+  dispatchMeta,
+  handleErrorResult,
+  unsupportedOp
+} from "./chunk-XHRZ7OYZ.js";
+
+// packages/cleo/src/dispatch/domains/docs.ts
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { DocKindRegistry } from "@cleocode/contracts/docs-taxonomy.js";
+import { LLM_OUTPUT_MODES } from "@cleocode/contracts/operations/docs";
+import { parseChangesetFrontmatter } from "@cleocode/core/changesets/parse-frontmatter";
+import { readAuditLog, verifyAuditTrail, writeAuditEntry } from "@cleocode/core/docs/docs-audit";
+import { createDocsReadModel } from "@cleocode/core/docs/docs-read-model";
+import {
+  DOCS_UPDATE_LIFECYCLE_STATUS_LIST,
+  isLifecycleStatus
+} from "@cleocode/core/docs/docs-update";
+import { createAttachmentStoreDocsAccessor } from "@cleocode/core/docs/import/attachment-store-accessor";
+import { makeClassifierForScanRoot } from "@cleocode/core/docs/import/scanner";
+import { AUTO_TOKEN } from "@cleocode/core/docs/numbering";
+import {
+  captureDocumentProjection,
+  projectDocumentAttachment
+} from "@cleocode/core/docs/projection";
+import { consumeReservedSlug, releaseReservedSlug } from "@cleocode/core/docs/slug-allocator";
+import { SUPERSEDE_NOT_FOUND_CODE, SUPERSEDE_SAME_SLUG_CODE } from "@cleocode/core/docs/supersede";
+import { validateDocBody } from "@cleocode/core/docs/validate-body";
+import { generateProjectHash } from "@cleocode/core/nexus/hash";
+import { pushWarning } from "@cleocode/core/output";
+import { resolveCleoDir, worktreeScope } from "@cleocode/core/paths.js";
+import { getProjectRoot } from "@cleocode/core/project-scope";
+import {
+  createAttachmentBlobStore,
+  createAttachmentStore,
+  SlugCollisionError
+} from "@cleocode/core/store/attachment-store";
+var allocateAdrSlug = lazyOperation(
+  async () => (await import("@cleocode/core/docs/adr-allocator")).allocateAdrSlug
+);
+var allocateAutoSlugForDispatch = lazyOperation(
+  async () => (await import("@cleocode/core/docs/numbering")).allocateAutoSlugForDispatch
+);
+var exportDocument = lazyOperation(
+  async () => (await import("@cleocode/core/docs/export-document")).exportDocument
+);
+var findSimilarDocs = lazyOperation(
+  async () => (await import("@cleocode/core/docs/docs-ops")).findSimilarDocs
+);
+var generateDocsLlmsTxt = lazyOperation(
+  async () => (await import("@cleocode/core/docs/docs-generator")).generateDocsLlmsTxt
+);
+var listDocVersions = lazyOperation(
+  async () => (await import("@cleocode/core/docs/docs-ops")).listDocVersions
+);
+var mergeDocs = lazyOperation(
+  async () => (await import("@cleocode/core/docs/docs-ops")).mergeDocs
+);
+var publishDocs = lazyOperation(
+  async () => (await import("@cleocode/core/docs/docs-ops")).publishDocs
+);
+var publishDocsAsPr = lazyOperation(
+  async () => (await import("@cleocode/core/docs/publish-pr")).publishDocsAsPr
+);
+var rankDocs = lazyOperation(async () => (await import("@cleocode/core/docs/docs-ops")).rankDocs);
+var recordPublication = lazyOperation(
+  async () => (await import("@cleocode/core/docs/docs-ops")).recordPublication
+);
+var reserveSlugForDispatch = lazyOperation(
+  async () => (await import("@cleocode/core/docs/slug-allocator")).reserveSlugForDispatch
+);
+var resolveAttachmentBackend = lazyOperation(
+  async () => (await import("@cleocode/core/store/attachment-store")).resolveAttachmentBackend
+);
+var runDocsImport = lazyOperation(
+  async () => (await import("@cleocode/core/docs/import/import-orchestrator")).runDocsImport
+);
+var searchAllProjectDocs = lazyOperation(
+  async () => (await import("@cleocode/core/docs/docs-ops")).searchAllProjectDocs
+);
+var searchDocs = lazyOperation(
+  async () => (await import("@cleocode/core/docs/docs-ops")).searchDocs
+);
+var supersedeDoc = lazyOperation(
+  async () => (await import("@cleocode/core/docs/supersede")).supersedeDoc
+);
+var syncFromGit = lazyOperation(
+  async () => (await import("@cleocode/core/docs/docs-ops")).syncFromGit
+);
+var updateDocBySlug = lazyOperation(
+  async () => (await import("@cleocode/core/docs/docs-update")).updateDocBySlug
+);
+var writeChangesetEntry = lazyOperation(
+  async () => (await import("@cleocode/core/changesets/writer")).writeChangesetEntry
+);
+var DOCS_LIST_DEFAULT_LIMIT = 50;
+var SLUG_COLLISION_GUIDANCE = `slug '{slug}' is already reserved in this project. Three ways to proceed:
+
+  1. Update the existing document:  cleo docs update {slug} [--file <path> | --content <text>]
+  2. Use a different slug:          cleo docs add <owner> <file> --slug <alternative>
+  3. Supersede with a new slug:      cleo docs supersede {slug} <new-slug>
+
+Recovery command: cleo docs update {slug} --file <your-file>`;
+var _registryCache = /* @__PURE__ */ new Map();
+function getDocKindRegistry() {
+  const root = getProjectRoot();
+  const cached = _registryCache.get(root);
+  if (cached) return cached;
+  try {
+    const registry = DocKindRegistry.load(root);
+    _registryCache.set(root, registry);
+    return registry;
+  } catch {
+    const fallback = DocKindRegistry.builtinOnly();
+    _registryCache.set(root, fallback);
+    return fallback;
+  }
+}
+function registeredKindValues() {
+  return getDocKindRegistry().list().map((d) => d.kind);
+}
+async function currentAttachmentBackend() {
+  return resolveAttachmentBackend();
+}
+function exportTaskDocument(options) {
+  return exportDocument(options);
+}
+function inferOwnerType(ownerId) {
+  if (/^T\d+$/i.test(ownerId)) return "task";
+  if (ownerId.startsWith("ses_")) return "session";
+  if (ownerId.startsWith("O-")) return "observation";
+  if (ownerId.startsWith("D-") || ownerId.startsWith("dec_")) return "decision";
+  if (ownerId.startsWith("L-") || ownerId.startsWith("lrn_")) return "learning";
+  if (ownerId.startsWith("P-") || ownerId.startsWith("pat_")) return "pattern";
+  return "task";
+}
+function parseLabels(raw) {
+  if (typeof raw !== "string" || !raw.trim()) return void 0;
+  return raw.split(",").map((l) => l.trim()).filter(Boolean);
+}
+function mimeFromPath(filePath) {
+  const lower = filePath.toLowerCase();
+  if (lower.endsWith(".md") || lower.endsWith(".markdown")) return "text/markdown";
+  if (lower.endsWith(".txt")) return "text/plain";
+  if (lower.endsWith(".html") || lower.endsWith(".htm")) return "text/html";
+  if (lower.endsWith(".json")) return "application/json";
+  if (lower.endsWith(".pdf")) return "application/pdf";
+  if (lower.endsWith(".zip")) return "application/zip";
+  if (lower.endsWith(".png")) return "image/png";
+  if (lower.endsWith(".jpg") || lower.endsWith(".jpeg")) return "image/jpeg";
+  if (lower.endsWith(".gif")) return "image/gif";
+  if (lower.endsWith(".svg")) return "image/svg+xml";
+  if (lower.endsWith(".ts") || lower.endsWith(".tsx")) return "text/plain";
+  if (lower.endsWith(".js")) return "text/javascript";
+  if (lower.endsWith(".css")) return "text/css";
+  return "application/octet-stream";
+}
+var SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+var SLUG_MAX_LEN = 80;
+function validateSlug(raw) {
+  if (typeof raw !== "string" || raw.length === 0) {
+    return { valid: false, reason: "slug must be a non-empty string" };
+  }
+  if (raw.length > SLUG_MAX_LEN) {
+    return { valid: false, reason: `slug exceeds ${SLUG_MAX_LEN} characters` };
+  }
+  if (!SLUG_PATTERN.test(raw)) {
+    return {
+      valid: false,
+      reason: "slug must be lowercase kebab-case (matches /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/) \u2014 got '" + raw + "'"
+    };
+  }
+  return { valid: true };
+}
+function validateDocsType(raw) {
+  if (typeof raw !== "string") return false;
+  return getDocKindRegistry().has(raw);
+}
+function registeredKindList() {
+  return registeredKindValues().join("|");
+}
+function normaliseOrderBy(raw) {
+  if (raw === "sha" || raw === "slug" || raw === "newest") return raw;
+  return "newest";
+}
+function resolveListLimit(raw) {
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    if (raw <= 0) return Number.POSITIVE_INFINITY;
+    return Math.floor(raw);
+  }
+  return DOCS_LIST_DEFAULT_LIMIT;
+}
+function compareByOrderBy(orderBy) {
+  if (orderBy === "sha") return (a, b) => a.sha256.localeCompare(b.sha256);
+  if (orderBy === "slug") {
+    return (a, b) => {
+      const left = a.slug ?? "";
+      const right = b.slug ?? "";
+      if (!left && right) return 1;
+      if (left && !right) return -1;
+      return left.localeCompare(right);
+    };
+  }
+  return (a, b) => b.createdAt.localeCompare(a.createdAt);
+}
+var _docsTypedHandler = defineTypedHandler("docs", {
+  // ── docs.list ──────────────────────────────────────────────────────────────
+  list: async (params) => {
+    const ownerId = params.task ?? params.session ?? params.observation;
+    const explicitProject = params.project === true;
+    const isProjectScope = explicitProject || !ownerId;
+    let typeFilter;
+    if (params.type !== void 0) {
+      if (!validateDocsType(params.type)) {
+        return lafsError(
+          "E_INVALID_TYPE",
+          `type must be one of: ${registeredKindList()} \u2014 got '${String(params.type)}'`,
+          "list"
+        );
+      }
+      typeFilter = params.type;
+    }
+    const effectiveLimit = resolveListLimit(params.limit);
+    const orderBy = normaliseOrderBy(params.orderBy);
+    const comparator = compareByOrderBy(orderBy);
+    const autoPromoted = isProjectScope && !explicitProject;
+    const hintParts = [];
+    if (autoPromoted) {
+      hintParts.push(
+        "no scope set \u2014 defaulted to --project. Pass --task <id>, --session <id>, or --observation <id> for a narrower listing."
+      );
+    }
+    const model = createDocsReadModel();
+    const backend = await currentAttachmentBackend();
+    if (isProjectScope) {
+      const docs = await model.listProjectDocs({
+        kind: typeFilter,
+        limit: Number.isFinite(effectiveLimit) ? effectiveLimit : void 0
+      });
+      const totalCount = docs.length;
+      const projected = docs.map((doc) => ({
+        id: doc.id,
+        // Full content hash — a SHA-256 field in a machine envelope must be the
+        // real digest, never a display-truncated form (T11294: the per-doc
+        // `docs fetch` the Manual-Write-Sweep had to spawn existed solely to
+        // recover the full hash the list previously hid). Human/table rendering
+        // abbreviates for display, not the data layer.
+        sha256: doc.sha256,
+        kind: "blob",
+        mime: doc.mimeType ?? "\u2014",
+        size: doc.sizeBytes,
+        description: void 0,
+        labels: void 0,
+        createdAt: doc.createdAt,
+        // Surface the real attachment ref_count (T11572) so `docs list` agrees
+        // with the `docs add` response — both now read the same source of truth.
+        refCount: doc.refCount,
+        ...doc.slug ? { slug: doc.slug } : {},
+        ...doc.kind ? { type: doc.kind } : {},
+        ...doc.displayNumber !== null ? { displayNumber: doc.displayNumber } : {},
+        ownerId: doc.ownerId,
+        ownerType: doc.ownerType
+      }));
+      projected.sort(
+        (a, b) => comparator(
+          { sha256: a.sha256, slug: a.slug, createdAt: a.createdAt },
+          { sha256: b.sha256, slug: b.slug, createdAt: b.createdAt }
+        )
+      );
+      const truncated = totalCount > projected.length;
+      if (truncated) {
+        hintParts.push(
+          `showing ${projected.length} of ${totalCount} \u2014 pass --limit <N> to widen or page further.`
+        );
+      }
+      return lafsSuccess(
+        {
+          ownerId: "",
+          ownerType: "task",
+          project: true,
+          ...typeFilter !== void 0 ? { type: typeFilter } : {},
+          count: projected.length,
+          ...truncated ? { totalCount } : {},
+          limit: Number.isFinite(effectiveLimit) ? effectiveLimit : 0,
+          orderBy,
+          ...hintParts.length > 0 ? { hint: hintParts.join(" ") } : {},
+          attachments: projected,
+          attachmentBackend: backend
+        },
+        "list"
+      );
+    }
+    const scopedOwner = ownerId;
+    const ownerType = inferOwnerType(scopedOwner);
+    const ownerDocs = await model.resolveByOwner(scopedOwner, { ownerType, kind: typeFilter });
+    const projectedOwner = ownerDocs.map((doc) => ({
+      id: doc.id,
+      // Full content hash (see project-scope note above; T11294).
+      sha256: doc.sha256,
+      kind: "blob",
+      mime: doc.mimeType ?? "\u2014",
+      size: doc.sizeBytes,
+      description: void 0,
+      labels: void 0,
+      createdAt: doc.createdAt,
+      // Surface the real attachment ref_count (T11572) — see project-scope note.
+      refCount: doc.refCount,
+      ...doc.slug ? { slug: doc.slug } : {},
+      ...doc.kind ? { type: doc.kind } : {},
+      ...doc.displayNumber !== null ? { displayNumber: doc.displayNumber } : {}
+    }));
+    projectedOwner.sort(
+      (a, b) => comparator(
+        { sha256: a.sha256, slug: a.slug, createdAt: a.createdAt },
+        { sha256: b.sha256, slug: b.slug, createdAt: b.createdAt }
+      )
+    );
+    const totalCountOwner = projectedOwner.length;
+    const slicedOwner = Number.isFinite(effectiveLimit) ? projectedOwner.slice(0, effectiveLimit) : projectedOwner;
+    const truncatedOwner = totalCountOwner > slicedOwner.length;
+    if (truncatedOwner) {
+      hintParts.push(
+        `showing ${slicedOwner.length} of ${totalCountOwner} \u2014 pass --limit <N> to widen or page further.`
+      );
+    }
+    return lafsSuccess(
+      {
+        ownerId: scopedOwner,
+        ownerType,
+        ...typeFilter !== void 0 ? { type: typeFilter } : {},
+        count: slicedOwner.length,
+        ...truncatedOwner ? { totalCount: totalCountOwner } : {},
+        limit: Number.isFinite(effectiveLimit) ? effectiveLimit : 0,
+        orderBy,
+        ...hintParts.length > 0 ? { hint: hintParts.join(" ") } : {},
+        attachments: slicedOwner,
+        attachmentBackend: backend
+      },
+      "list"
+    );
+  },
+  // ── docs.generate ──────────────────────────────────────────────────────────
+  generate: async (params) => {
+    const forId = params.for;
+    if (!forId) {
+      return lafsError("E_INVALID_INPUT", "--for <taskId|epicId> is required", "generate");
+    }
+    const cwd = getProjectRoot();
+    const result = await generateDocsLlmsTxt({ ownerId: forId, cwd });
+    let attachmentId;
+    let attachmentSha256;
+    if (params.attach) {
+      const store = createAttachmentStore();
+      const ownerType = inferOwnerType(forId);
+      const contentBytes = Buffer.from(result.content, "utf-8");
+      const llmsTxtDescriptor = {
+        kind: "llms-txt",
+        source: "generated",
+        content: result.content,
+        description: `llms.txt for ${forId} (${result.attachmentCount} docs)`,
+        labels: ["llms-txt", "generated"]
+      };
+      const meta = await store.put(
+        contentBytes,
+        llmsTxtDescriptor,
+        ownerType,
+        forId,
+        "cleo-docs-generate",
+        cwd
+      );
+      attachmentId = meta.id;
+      attachmentSha256 = meta.sha256;
+    }
+    return lafsSuccess(
+      {
+        forId,
+        content: result.content,
+        attachmentCount: result.attachmentCount,
+        usedLlmtxtPackage: result.usedLlmtxtPackage,
+        ...attachmentId !== void 0 ? {
+          attached: true,
+          attachmentId,
+          attachmentSha256
+        } : { attached: false }
+      },
+      "generate"
+    );
+  },
+  // ── docs.llm-output (T11137) ──────────────────────────────────────────────
+  "llm-output": async (params) => {
+    const forId = params.for;
+    if (!forId) {
+      return lafsError("E_INVALID_INPUT", "--for <entityId> is required", "llm-output");
+    }
+    let mode;
+    if (params.mode !== void 0) {
+      const raw = String(params.mode);
+      if (!LLM_OUTPUT_MODES.includes(raw)) {
+        return lafsError(
+          "E_INVALID_INPUT",
+          `--mode must be one of: ${LLM_OUTPUT_MODES.join("|")}`,
+          "llm-output"
+        );
+      }
+      mode = raw;
+    } else {
+      mode = /^T\d+$/i.test(forId) ? "task-export" : "attachment-bundle";
+    }
+    const cwd = getProjectRoot();
+    if (mode === "task-export") {
+      const result2 = await exportTaskDocument({
+        taskId: forId,
+        includeAttachments: params.includeAttachments !== false,
+        includeMemoryRefs: params.includeMemoryRefs === true,
+        projectRoot: cwd
+      });
+      return lafsSuccess(
+        {
+          forId,
+          mode: "task-export",
+          content: result2.markdown,
+          sectionCount: result2.pages,
+          usedLlmtxtPackage: true
+        },
+        "llm-output"
+      );
+    }
+    const result = await generateDocsLlmsTxt({ ownerId: forId, cwd });
+    let aid, asha;
+    if (params.attach) {
+      const store = createAttachmentStore();
+      const desc = {
+        kind: "llms-txt",
+        source: "generated",
+        content: result.content,
+        description: `llms.txt for ${forId}`,
+        labels: ["llms-txt", "generated"]
+      };
+      const meta = await store.put(
+        Buffer.from(result.content, "utf-8"),
+        desc,
+        inferOwnerType(forId),
+        forId,
+        "cleo-docs-llm-output",
+        cwd
+      );
+      aid = meta.id;
+      asha = meta.sha256;
+    }
+    return lafsSuccess(
+      {
+        forId,
+        mode: "attachment-bundle",
+        content: result.content,
+        sectionCount: result.attachmentCount,
+        usedLlmtxtPackage: result.usedLlmtxtPackage,
+        ...aid ? { attached: true, attachmentId: aid, attachmentSha256: asha } : { attached: false }
+      },
+      "llm-output"
+    );
+  },
+  // ── docs.fetch ─────────────────────────────────────────────────────────────
+  fetch: async (params) => {
+    const ref = params.attachmentRef;
+    if (!ref) {
+      return lafsError(
+        "E_INVALID_INPUT",
+        "attachmentRef is required (attachment ID or SHA-256 hex)",
+        "fetch"
+      );
+    }
+    const model = createDocsReadModel();
+    const doc = await model.resolveLatest(ref) ?? await model.resolveByAttachmentId(ref);
+    if (!doc) {
+      return lafsError("E_NOT_FOUND", `Attachment not found: ${ref}`, "fetch");
+    }
+    const content = await model.fetchContent(doc);
+    if (content === null) {
+      return lafsError("E_NOT_FOUND", `Content not retrievable: ${ref}`, "fetch");
+    }
+    const cwd = getProjectRoot();
+    const cleoDir = resolveCleoDir(cwd);
+    let storagePath;
+    if (doc.sha256) {
+      const prefix = doc.sha256.slice(0, 2);
+      const rest = doc.sha256.slice(2);
+      const extMap = {
+        "text/markdown": ".md",
+        "text/plain": ".txt",
+        "application/json": ".json",
+        "application/pdf": ".pdf"
+      };
+      const ext = extMap[doc.mimeType ?? ""] ?? ".bin";
+      storagePath = resolve(cleoDir, "attachments", "sha256", prefix, `${rest}${ext}`);
+    }
+    const MAX_INLINE = 1024 * 1024;
+    const contentBytes = Buffer.from(content, "utf-8");
+    const bytesBase64 = contentBytes.length <= MAX_INLINE ? contentBytes.toString("base64") : void 0;
+    const backend = await currentAttachmentBackend();
+    return lafsSuccess(
+      {
+        metadata: {
+          id: doc.id,
+          sha256: doc.sha256,
+          kind: "blob",
+          mime: doc.mimeType ?? "text/plain",
+          size: doc.sizeBytes,
+          description: doc.summary ?? void 0,
+          labels: void 0,
+          createdAt: doc.createdAt,
+          refCount: 0,
+          ...doc.slug ? { slug: doc.slug } : {},
+          ...doc.kind ? { type: doc.kind } : {},
+          ...doc.displayNumber !== null ? { displayNumber: doc.displayNumber } : {}
+        },
+        path: storagePath,
+        sizeBytes: contentBytes.length,
+        ...bytesBase64 !== void 0 ? { bytesBase64 } : {},
+        inlined: bytesBase64 !== void 0,
+        attachmentBackend: backend
+      },
+      "fetch"
+    );
+  },
+  // ── docs.add ───────────────────────────────────────────────────────────────
+  add: async (params) => {
+    const {
+      ownerId,
+      file: filePath,
+      url,
+      content: inlineContent,
+      desc: description,
+      labels: rawLabels,
+      attachedBy: rawAttachedBy,
+      slug: rawSlug,
+      title: rawTitle,
+      type: rawType,
+      strict: strictMode
+    } = params;
+    if (!ownerId) {
+      return lafsError("E_INVALID_INPUT", "ownerId is required", "add");
+    }
+    const hasContent = typeof inlineContent === "string";
+    const sourceCount = (filePath ? 1 : 0) + (url ? 1 : 0) + (hasContent ? 1 : 0);
+    if (sourceCount === 0) {
+      return lafsError(
+        "E_INVALID_INPUT",
+        "Provide a file path (positional or --file), --url, or --content <text>",
+        "add"
+      );
+    }
+    if (sourceCount > 1) {
+      return lafsError(
+        "E_INVALID_INPUT",
+        "--file, --url, and --content are mutually exclusive \u2014 provide exactly one source",
+        "add",
+        'Use `cleo docs add <owner> ./file.md` OR `--url <url>` OR `--content "<text>"` (not more than one).'
+      );
+    }
+    const projectRoot = getProjectRoot();
+    return worktreeScope.run(
+      {
+        ...worktreeScope.getStore(),
+        worktreeRoot: projectRoot,
+        projectHash: generateProjectHash(projectRoot)
+      },
+      async () => {
+        const projectionCapture = await captureDocumentProjection(
+          projectRoot,
+          rawAttachedBy ?? "cleo-docs-add",
+          randomUUID()
+        );
+        try {
+          let slug;
+          if (rawSlug !== void 0) {
+            let candidate = rawSlug;
+            if (typeof candidate === "string" && candidate.includes(AUTO_TOKEN)) {
+              const allocated = await allocateAutoSlugForDispatch(projectRoot, {
+                kind: typeof rawType === "string" ? rawType : "",
+                rawSlug: candidate
+              });
+              candidate = allocated.resolvedSlug;
+            }
+            const check = validateSlug(candidate);
+            if (!check.valid) {
+              return lafsError("E_INVALID_SLUG", check.reason, "add");
+            }
+            slug = candidate;
+          }
+          let type;
+          if (rawType !== void 0) {
+            if (!validateDocsType(rawType)) {
+              return lafsError(
+                "E_INVALID_TYPE",
+                `type must be one of: ${registeredKindList()} \u2014 got '${String(rawType)}'`,
+                "add"
+              );
+            }
+            type = rawType;
+          }
+          if (type === "changeset") {
+            if (!filePath) {
+              return lafsError(
+                "E_INVALID_INPUT",
+                "changeset writes require a --file path (URL attachments are not supported for changesets)",
+                "add"
+              );
+            }
+            const absPath = resolve(filePath);
+            let bytes;
+            try {
+              bytes = await readFile(absPath);
+            } catch {
+              return lafsError("E_FILE_ERROR", `Cannot read file: ${absPath}`, "add");
+            }
+            const parsed = parseChangesetFrontmatter(bytes.toString("utf-8"));
+            if (!parsed.ok) {
+              let message;
+              if (parsed.error === "missing-frontmatter") {
+                message = "changeset file is missing the `---`-fenced YAML frontmatter. Required fields: id, tasks, kind, summary.";
+              } else if (parsed.error === "missing-required") {
+                message = `changeset frontmatter is missing required fields: ${parsed.missing.join(", ")}.`;
+              } else if (parsed.error === "yaml-invalid") {
+                const lineHint = parsed.line !== void 0 ? ` (line ${parsed.line})` : "";
+                message = `changeset frontmatter YAML is invalid${lineHint}: ${parsed.parserMessage}`;
+              } else {
+                message = `changeset frontmatter failed schema validation: ${parsed.issues.join("; ")}`;
+              }
+              return {
+                success: false,
+                error: {
+                  code: "E_REQUIRES_CHANGESET_VERB",
+                  message,
+                  details: {
+                    fix: "Use `cleo changeset add --slug <id> --tasks <T####> --kind <kind> --summary <text>` for guided authoring.",
+                    parserError: parsed.error,
+                    ...parsed.error === "missing-required" ? { missing: parsed.missing } : {},
+                    ...parsed.error === "schema-invalid" ? { issues: parsed.issues } : {}
+                  }
+                }
+              };
+            }
+            if (slug !== void 0 && slug !== parsed.entry.id) {
+              return {
+                success: false,
+                error: {
+                  code: "E_SLUG_MISMATCH",
+                  message: `--slug '${slug}' does not match changeset frontmatter id '${parsed.entry.id}'. The frontmatter is canonical \u2014 drop --slug or align it.`
+                }
+              };
+            }
+            const outcome = await writeChangesetEntry(parsed.entry, {
+              projectRoot,
+              attachedBy: typeof rawAttachedBy === "string" && rawAttachedBy.length > 0 ? rawAttachedBy : "cleo-docs-add"
+            });
+            if (!outcome.ok) {
+              const err = outcome.error;
+              if (err.code === "E_SLUG_PATTERN_MISMATCH") {
+                const hint = err.example ? ` (example: ${err.example})` : "";
+                return lafsError("E_SLUG_PATTERN_MISMATCH", `${err.message}${hint}`, "add");
+              }
+              if (err.code === "E_INVALID_ENTRY") {
+                return lafsError("E_INVALID_INPUT", err.message, "add");
+              }
+              if (err.code === "E_FILE_WRITE_FAILED") {
+                return lafsError("E_FILE_ERROR", err.message, "add");
+              }
+              if (err.code === "E_SLUG_RESERVED") {
+                return {
+                  success: false,
+                  error: {
+                    code: "E_SLUG_RESERVED",
+                    message: err.message,
+                    details: {
+                      suggestions: err.suggestions,
+                      aliases: err.aliases
+                    }
+                  }
+                };
+              }
+              return lafsError("E_SSOT_WRITE_FAILED", err.message, "add");
+            }
+            const projection = projectionCapture.status === "ready" ? await projectDocumentAttachment(projectionCapture.context, {
+              attachmentId: outcome.result.attachmentId,
+              sha256: outcome.result.sha256,
+              ownerId: outcome.result.ownerId,
+              ownerType: "task",
+              label: outcome.result.slug
+            }) : projectionCapture.outcome;
+            try {
+              writeAuditEntry(projectRoot, {
+                op: "docs.add",
+                slug: outcome.result.slug,
+                type: "changeset",
+                attachmentId: outcome.result.attachmentId,
+                sha256: outcome.result.sha256,
+                summary: `Added changeset '${outcome.result.slug}'`
+              });
+            } catch {
+            }
+            return lafsSuccess(
+              {
+                projection,
+                attachmentId: outcome.result.attachmentId,
+                sha256: outcome.result.sha256,
+                // writeChangesetEntry returns a freshly-minted ref so refCount is 1
+                // (or more if the same content was already addressed by another
+                // owner). The store sets the canonical value; mirroring it here
+                // keeps the envelope shape identical to the file/url branches.
+                refCount: 1,
+                kind: "blob",
+                ownerId: outcome.result.ownerId,
+                ownerType: "task",
+                // Cast: core returns 'llmtxt' (Wave C — legacy backend retired for mirror store).
+                attachmentBackend: await currentAttachmentBackend(),
+                slug: outcome.result.slug,
+                type: "changeset"
+              },
+              "add"
+            );
+          }
+          let adrNumber;
+          if (type === "adr" && slug === void 0) {
+            if (typeof rawTitle !== "string" || rawTitle.trim().length === 0) {
+              return lafsError(
+                "E_VALIDATION",
+                "title is required when type=adr and slug is omitted \u2014 the allocator needs a title to assemble adr-NNN-<kebab-title>",
+                "add"
+              );
+            }
+            const allocation = await allocateAdrSlug(projectRoot, { title: rawTitle });
+            if (!allocation.ok) {
+              return lafsError(allocation.code, allocation.message, "add");
+            }
+            slug = allocation.slug;
+            adrNumber = allocation.number;
+          }
+          if (type !== void 0 && slug !== void 0) {
+            const patternCheck = getDocKindRegistry().validateSlug(type, slug);
+            if (!patternCheck.ok) {
+              if (adrNumber !== void 0) releaseReservedSlug(slug);
+              const exampleHint = patternCheck.example ? ` (example: ${patternCheck.example})` : "";
+              return lafsError(
+                "E_SLUG_PATTERN_MISMATCH",
+                `${patternCheck.error}${exampleHint}`,
+                "add"
+              );
+            }
+          }
+          if (slug !== void 0 && adrNumber === void 0) {
+            const reservation = await reserveSlugForDispatch(projectRoot, {
+              kind: type ?? "",
+              slug
+            });
+            if (!reservation.ok) {
+              return {
+                success: false,
+                error: {
+                  code: "E_SLUG_RESERVED",
+                  message: SLUG_COLLISION_GUIDANCE.replaceAll("{slug}", slug ?? ""),
+                  fix: `cleo docs update ${slug ?? "<slug>"} --file <your-file>`,
+                  details: {
+                    suggestions: reservation.suggestions,
+                    aliases: ["E_SLUG_TAKEN"]
+                  }
+                }
+              };
+            }
+          }
+          const extras = {};
+          if (slug !== void 0) extras.slug = slug;
+          if (type !== void 0) extras.type = type;
+          const labels = parseLabels(rawLabels);
+          const attachedBy = rawAttachedBy ?? "human";
+          const ownerType = inferOwnerType(ownerId);
+          const store = createAttachmentStore();
+          if (filePath) {
+            const absPath = resolve(filePath);
+            let bytes;
+            try {
+              bytes = await readFile(absPath);
+            } catch {
+              return lafsError("E_FILE_ERROR", `Cannot read file: ${absPath}`, "add");
+            }
+            if (type !== void 0) {
+              const bodyText = bytes.toString("utf-8");
+              let registry;
+              try {
+                registry = DocKindRegistry.load(projectRoot);
+              } catch {
+                registry = void 0;
+              }
+              const check = validateDocBody(type, bodyText, registry);
+              if (!check.ok) {
+                const missingList = check.missing.join(", ");
+                if (strictMode === true) {
+                  return lafsError(
+                    "E_DOC_SCHEMA_MISMATCH",
+                    `body for kind '${type}' is missing required section(s): ${missingList}`,
+                    "add",
+                    `Add the missing H2 section(s) \u2014 '## ${check.missing[0] ?? ""}' \u2014 then retry. Pass --strict=false (default) to surface as an advisory warning instead of an error.`,
+                    {
+                      kind: type,
+                      missing: check.missing,
+                      strict: true
+                    }
+                  );
+                }
+                pushWarning({
+                  code: "W_DOC_SCHEMA_MISMATCH",
+                  message: `body for kind '${type}' is missing required section(s): ${missingList}. Add '--strict' to fail on schema violations.`
+                });
+              }
+            }
+            const mime = mimeFromPath(absPath);
+            const attachment = {
+              kind: "local-file",
+              path: absPath,
+              mime,
+              size: bytes.length,
+              ...description ? { description } : {},
+              ...labels ? { labels } : {}
+            };
+            let meta;
+            try {
+              meta = await store.put(
+                bytes,
+                attachment,
+                ownerType,
+                ownerId,
+                attachedBy,
+                projectRoot,
+                extras
+              );
+            } catch (err) {
+              if (slug !== void 0) releaseReservedSlug(slug);
+              if (err instanceof SlugCollisionError) {
+                return {
+                  success: false,
+                  error: {
+                    code: "E_SLUG_RESERVED",
+                    message: SLUG_COLLISION_GUIDANCE.replaceAll("{slug}", err.slug ?? ""),
+                    fix: `cleo docs update ${err.slug ?? "<slug>"} --file <your-file>`,
+                    details: {
+                      suggestions: err.suggestions,
+                      aliases: ["E_SLUG_TAKEN"]
+                    }
+                  }
+                };
+              }
+              throw err;
+            }
+            if (adrNumber !== void 0 && slug !== void 0) consumeReservedSlug(slug);
+            let backend = "llmtxt";
+            try {
+              const blobMirror = createAttachmentBlobStore(projectRoot);
+              const mirrorResult = await blobMirror.put(ownerId, {
+                name: absPath.split(/[\\/]/).pop() ?? meta.sha256.slice(0, 12),
+                data: new Uint8Array(bytes),
+                contentType: mime
+              });
+              backend = mirrorResult.backend;
+            } catch {
+              backend = await currentAttachmentBackend();
+            }
+            const projection = projectionCapture.status === "ready" ? await projectDocumentAttachment(projectionCapture.context, {
+              attachmentId: meta.id,
+              sha256: meta.sha256,
+              ownerId,
+              ownerType,
+              label: absPath.split(/[\\/]/).pop() ?? meta.sha256.slice(0, 12)
+            }) : projectionCapture.outcome;
+            try {
+              writeAuditEntry(projectRoot, {
+                op: "docs.add",
+                slug,
+                type,
+                attachmentId: meta.id,
+                sha256: meta.sha256,
+                ownerId,
+                summary: `Added doc '${slug ?? meta.sha256.slice(0, 12)}'${type ? ` of type '${type}'` : ""} for owner ${ownerId}`
+              });
+            } catch {
+            }
+            return lafsSuccess(
+              {
+                projection,
+                attachmentId: meta.id,
+                sha256: meta.sha256,
+                refCount: meta.refCount,
+                kind: "local-file",
+                ownerId,
+                ownerType,
+                // Cast: core returns 'llmtxt'|'legacy'; contracts uses 'legacy'|'llmstxt-v2' (T1529)
+                attachmentBackend: backend,
+                ...slug !== void 0 ? { slug } : {},
+                ...type !== void 0 ? { type } : {},
+                ...adrNumber !== void 0 ? { adrNumber } : {}
+              },
+              "add"
+            );
+          }
+          if (hasContent) {
+            const bytes = Buffer.from(inlineContent, "utf-8");
+            if (type !== void 0) {
+              let registry;
+              try {
+                registry = DocKindRegistry.load(projectRoot);
+              } catch {
+                registry = void 0;
+              }
+              const check = validateDocBody(type, inlineContent, registry);
+              if (!check.ok) {
+                const missingList = check.missing.join(", ");
+                if (strictMode === true) {
+                  if (slug !== void 0) releaseReservedSlug(slug);
+                  return lafsError(
+                    "E_DOC_SCHEMA_MISMATCH",
+                    `body for kind '${type}' is missing required section(s): ${missingList}`,
+                    "add",
+                    `Add the missing H2 section(s) \u2014 '## ${check.missing[0] ?? ""}' \u2014 then retry. Pass --strict=false (default) to surface as an advisory warning instead of an error.`,
+                    { kind: type, missing: check.missing, strict: true }
+                  );
+                }
+                pushWarning({
+                  code: "W_DOC_SCHEMA_MISMATCH",
+                  message: `body for kind '${type}' is missing required section(s): ${missingList}. Add '--strict' to fail on schema violations.`
+                });
+              }
+            }
+            const mime = "text/markdown";
+            const attachment = {
+              kind: "blob",
+              mime,
+              ...description ? { description } : {},
+              ...labels ? { labels } : {}
+            };
+            let meta;
+            try {
+              meta = await store.put(
+                bytes,
+                attachment,
+                ownerType,
+                ownerId,
+                attachedBy,
+                projectRoot,
+                extras
+              );
+            } catch (err) {
+              if (slug !== void 0) releaseReservedSlug(slug);
+              if (err instanceof SlugCollisionError) {
+                return {
+                  success: false,
+                  error: {
+                    code: "E_SLUG_RESERVED",
+                    message: SLUG_COLLISION_GUIDANCE.replaceAll("{slug}", err.slug ?? ""),
+                    fix: `cleo docs update ${err.slug ?? "<slug>"} --content "..."`,
+                    details: {
+                      suggestions: err.suggestions,
+                      aliases: ["E_SLUG_TAKEN"]
+                    }
+                  }
+                };
+              }
+              throw err;
+            }
+            if (adrNumber !== void 0 && slug !== void 0) consumeReservedSlug(slug);
+            const blobName = slug ?? meta.sha256.slice(0, 12);
+            let backend = "llmtxt";
+            try {
+              const blobMirror = createAttachmentBlobStore(projectRoot);
+              const mirrorResult = await blobMirror.put(ownerId, {
+                name: blobName,
+                data: new Uint8Array(bytes),
+                contentType: mime
+              });
+              backend = mirrorResult.backend;
+            } catch {
+              backend = await currentAttachmentBackend();
+            }
+            const projection = projectionCapture.status === "ready" ? await projectDocumentAttachment(projectionCapture.context, {
+              attachmentId: meta.id,
+              sha256: meta.sha256,
+              ownerId,
+              ownerType,
+              label: blobName
+            }) : projectionCapture.outcome;
+            try {
+              writeAuditEntry(projectRoot, {
+                op: "docs.add",
+                slug,
+                type,
+                attachmentId: meta.id,
+                sha256: meta.sha256,
+                ownerId,
+                summary: `Added inline doc '${slug ?? meta.sha256.slice(0, 12)}'${type ? ` of type '${type}'` : ""} for owner ${ownerId}`
+              });
+            } catch {
+            }
+            return lafsSuccess(
+              {
+                projection,
+                attachmentId: meta.id,
+                sha256: meta.sha256,
+                refCount: meta.refCount,
+                kind: "blob",
+                ownerId,
+                ownerType,
+                // Cast: core returns 'llmtxt'|'legacy'; contracts uses 'legacy'|'llmstxt-v2' (T1529)
+                attachmentBackend: backend,
+                ...slug !== void 0 ? { slug } : {},
+                ...type !== void 0 ? { type } : {},
+                ...adrNumber !== void 0 ? { adrNumber } : {}
+              },
+              "add"
+            );
+          }
+          if (url) {
+            const attachment = {
+              kind: "url",
+              url,
+              ...description ? { description } : {},
+              ...labels ? { labels } : {}
+            };
+            const urlBytes = Buffer.from(url, "utf-8");
+            let meta;
+            try {
+              meta = await store.put(
+                urlBytes,
+                attachment,
+                ownerType,
+                ownerId,
+                attachedBy,
+                projectRoot,
+                extras
+              );
+            } catch (err) {
+              if (slug !== void 0) releaseReservedSlug(slug);
+              if (err instanceof SlugCollisionError) {
+                return {
+                  success: false,
+                  error: {
+                    code: "E_SLUG_RESERVED",
+                    message: SLUG_COLLISION_GUIDANCE.replaceAll("{slug}", err.slug ?? ""),
+                    fix: `cleo docs update ${err.slug ?? "<slug>"} --file <your-file>`,
+                    details: {
+                      suggestions: err.suggestions,
+                      aliases: ["E_SLUG_TAKEN"]
+                    }
+                  }
+                };
+              }
+              throw err;
+            }
+            if (adrNumber !== void 0 && slug !== void 0) consumeReservedSlug(slug);
+            const backend = await currentAttachmentBackend();
+            const projection = projectionCapture.status === "ready" ? await projectDocumentAttachment(projectionCapture.context, {
+              attachmentId: meta.id,
+              sha256: meta.sha256,
+              ownerId,
+              ownerType,
+              label: url
+            }) : projectionCapture.outcome;
+            try {
+              writeAuditEntry(projectRoot, {
+                op: "docs.add",
+                slug,
+                type,
+                attachmentId: meta.id,
+                sha256: meta.sha256,
+                ownerId,
+                summary: `Added URL doc '${slug ?? url}'${type ? ` of type '${type}'` : ""} for owner ${ownerId}`
+              });
+            } catch {
+            }
+            return lafsSuccess(
+              {
+                projection,
+                attachmentId: meta.id,
+                sha256: meta.sha256,
+                refCount: meta.refCount,
+                kind: "url",
+                url,
+                ownerId,
+                ownerType,
+                // Cast: core returns 'llmtxt'|'legacy'; contracts uses 'legacy'|'llmstxt-v2' (T1529)
+                attachmentBackend: backend,
+                ...slug !== void 0 ? { slug } : {},
+                ...type !== void 0 ? { type } : {},
+                ...adrNumber !== void 0 ? { adrNumber } : {}
+              },
+              "add"
+            );
+          }
+          return lafsError("E_INVALID_INPUT", "Unreachable: no file or url", "add");
+        } finally {
+          if (projectionCapture.status === "ready") projectionCapture.context.close();
+        }
+      }
+    );
+  },
+  // ── docs.remove ────────────────────────────────────────────────────────────
+  remove: async (params) => {
+    const { attachmentRef: ref, from: fromOwner } = params;
+    if (!ref) {
+      return lafsError(
+        "E_INVALID_INPUT",
+        "attachmentRef is required (attachment ID or SHA-256 hex)",
+        "remove"
+      );
+    }
+    if (!fromOwner) {
+      return lafsError("E_INVALID_INPUT", "--from <ownerId> is required", "remove");
+    }
+    const store = createAttachmentStore();
+    const ownerType = inferOwnerType(fromOwner);
+    let attachmentId = ref;
+    if (/^[0-9a-f]{64}$/i.test(ref)) {
+      const result = await store.get(ref);
+      if (!result) {
+        return lafsError("E_NOT_FOUND", `No attachment found with SHA-256: ${ref}`, "remove");
+      }
+      attachmentId = result.metadata.id;
+    }
+    const derefResult = await store.deref(attachmentId, ownerType, fromOwner);
+    if (derefResult.status === "not-found") {
+      return lafsError(
+        "E_NOT_FOUND",
+        `Attachment ref not found: ${attachmentId} on owner ${fromOwner}`,
+        "remove"
+      );
+    }
+    const blobPurged = derefResult.status === "removed";
+    const refCountAfter = derefResult.status === "derefd" ? derefResult.refCountAfter : 0;
+    try {
+      const blobMirror = createAttachmentBlobStore(getProjectRoot());
+      await blobMirror.remove(attachmentId, fromOwner);
+    } catch {
+    }
+    const backend = await currentAttachmentBackend();
+    try {
+      writeAuditEntry(getProjectRoot(), {
+        op: "docs.remove",
+        attachmentId,
+        ownerId: fromOwner,
+        summary: `Removed attachment ${attachmentId} from owner ${fromOwner}${blobPurged ? " (blob purged)" : ""}`
+      });
+    } catch {
+    }
+    return lafsSuccess(
+      {
+        removed: blobPurged,
+        attachmentId,
+        from: fromOwner,
+        refCountAfter,
+        blobPurged,
+        // Cast: core returns 'llmtxt'|'legacy'; contracts uses 'legacy'|'llmstxt-v2' (T1529)
+        attachmentBackend: backend
+      },
+      "remove"
+    );
+  },
+  // ── docs.update (T10161 — E12.C4 / Saga T9855) ─────────────────────────────
+  update: async (params) => {
+    const { slug: rawSlug, file: filePath, content: inlineContent, status: rawStatus } = params;
+    if (typeof rawSlug !== "string" || rawSlug.length === 0) {
+      return lafsError("E_INVALID_INPUT", "slug is required", "update");
+    }
+    const hasFile = typeof filePath === "string" && filePath.length > 0;
+    const hasContent = typeof inlineContent === "string";
+    const statusOnly = !hasFile && !hasContent;
+    if (hasFile && hasContent) {
+      return lafsError(
+        "E_INVALID_INPUT",
+        "--file and --content are mutually exclusive",
+        "update",
+        'Use `cleo docs update <slug> --file ./new.md` OR `cleo docs update <slug> --content "..."`.'
+      );
+    }
+    if (statusOnly && rawStatus === void 0) {
+      return lafsError(
+        "E_INVALID_INPUT",
+        "Provide --file <path>, --content <text>, or --status <status> alone",
+        "update",
+        'Use `--file ./new.md`, `--content "..."`, or `cleo docs update <slug> --status accepted` to change only the lifecycle status.'
+      );
+    }
+    if (rawStatus !== void 0 && !isLifecycleStatus(rawStatus)) {
+      return lafsError(
+        "E_INVALID_INPUT",
+        `status must be one of: ${DOCS_UPDATE_LIFECYCLE_STATUS_LIST} \u2014 got '${String(rawStatus)}'`,
+        "update"
+      );
+    }
+    const projectRoot = getProjectRoot();
+    const resolvedParams = hasFile ? { ...params, file: resolve(filePath) } : params;
+    const outcome = await updateDocBySlug(projectRoot, resolvedParams);
+    if (!outcome.ok) {
+      return lafsError(
+        outcome.error.code,
+        outcome.error.message,
+        "update",
+        void 0,
+        "details" in outcome.error ? outcome.error.details : void 0
+      );
+    }
+    let backend = "llmtxt";
+    if (statusOnly) {
+      backend = await currentAttachmentBackend();
+    } else {
+      try {
+        const blobMirror = createAttachmentBlobStore(getProjectRoot());
+        const updatedBytes = hasFile ? new Uint8Array(await readFile(resolve(filePath))) : new Uint8Array(Buffer.from(inlineContent, "utf-8"));
+        const contentType = hasFile ? mimeFromPath(resolve(filePath)) : "text/plain";
+        const store = createAttachmentStore();
+        const rows = await store.listAllInProject(projectRoot);
+        const ownerIds = Array.from(
+          new Set(
+            rows.filter((row) => row.metadata.id === outcome.result.attachmentId).map((row) => row.ownerId)
+          )
+        );
+        const mirrorOwnerIds = ownerIds.length > 0 ? ownerIds : [`slug:${outcome.result.slug}`];
+        for (const mirrorOwnerId of mirrorOwnerIds) {
+          const mirrorResult = await blobMirror.put(mirrorOwnerId, {
+            name: outcome.result.slug,
+            data: updatedBytes,
+            contentType
+          });
+          backend = mirrorResult.backend;
+        }
+      } catch {
+        backend = await currentAttachmentBackend();
+      }
+    }
+    try {
+      writeAuditEntry(getProjectRoot(), {
+        op: "docs.update",
+        slug: outcome.result.slug,
+        type: outcome.result.type ?? void 0,
+        attachmentId: outcome.result.attachmentId,
+        sha256: outcome.result.sha256,
+        previousSha256: outcome.result.previousSha256 ?? void 0,
+        summary: `Updated doc '${outcome.result.slug}'${outcome.result.lifecycleStatus ? ` (status: ${outcome.result.lifecycleStatus})` : ""}`
+      });
+    } catch {
+    }
+    return lafsSuccess(
+      {
+        slug: outcome.result.slug,
+        ...outcome.result.type !== null ? { type: outcome.result.type } : {},
+        attachmentId: outcome.result.attachmentId,
+        previousAttachmentId: outcome.result.previousAttachmentId,
+        sha256: outcome.result.sha256,
+        previousSha256: outcome.result.previousSha256,
+        changed: outcome.result.changed,
+        lifecycleStatus: outcome.result.lifecycleStatus,
+        updatedAt: outcome.result.updatedAt,
+        version: outcome.result.version,
+        /** Version SSoT (T11181) — canonical version identifiers. */
+        ownerVersion: outcome.result.ownerVersion,
+        /** Sequential doc version counter (T11181). */
+        docVersion: outcome.result.docVersion,
+        squashed: outcome.result.squashed,
+        summary: outcome.result.summary,
+        // T11053 — surface which backend stored the updated blob so
+        // observability consumers can confirm the V2 mirror succeeded.
+        attachmentBackend: backend,
+        ...outcome.result.dryRun === true ? { dryRun: true } : {},
+        ...outcome.result.wouldWrite !== void 0 ? { wouldWrite: outcome.result.wouldWrite } : {},
+        ...outcome.result.wouldChange !== void 0 ? { wouldChange: outcome.result.wouldChange } : {}
+      },
+      "update"
+    );
+  },
+  // ── docs.supersede ─────────────────────────────────────────────────────────
+  supersede: async (params) => {
+    const { oldSlug, newSlug, reason } = params;
+    if (typeof oldSlug !== "string" || oldSlug.length === 0) {
+      return lafsError("E_INVALID_INPUT", "<oldSlug> is required", "supersede");
+    }
+    if (typeof newSlug !== "string" || newSlug.length === 0) {
+      return lafsError("E_INVALID_INPUT", "<newSlug> is required", "supersede");
+    }
+    try {
+      const result = await supersedeDoc(getProjectRoot(), {
+        oldSlug,
+        newSlug,
+        ...typeof reason === "string" && reason.length > 0 ? { reason } : {}
+      });
+      const payload = {
+        oldSlug: result.oldSlug,
+        newSlug: result.newSlug,
+        oldAttachmentId: result.oldAttachmentId,
+        newAttachmentId: result.newAttachmentId,
+        supersededAt: result.supersededAt,
+        edgeId: result.edgeId,
+        ...result.reason !== void 0 ? { reason: result.reason } : {}
+      };
+      try {
+        writeAuditEntry(getProjectRoot(), {
+          op: "docs.supersede",
+          slug: result.newSlug,
+          attachmentId: result.newAttachmentId,
+          summary: `Superseded '${result.oldSlug}' \u2192 '${result.newSlug}'${result.reason ? ` (reason: ${result.reason})` : ""}`
+        });
+      } catch {
+      }
+      return lafsSuccess(payload, "supersede");
+    } catch (err) {
+      const code = err && typeof err === "object" && "code" in err && typeof err.code === "number" ? (
+        // Map ExitCode (number) → stable LAFS string code expected by callers.
+        err.code === 4 ? SUPERSEDE_NOT_FOUND_CODE : err.code === 6 ? SUPERSEDE_SAME_SLUG_CODE : "E_INTERNAL"
+      ) : "E_INTERNAL";
+      const message = err instanceof Error ? err.message : "supersede failed";
+      return lafsError(code, message, "supersede");
+    }
+  }
+});
+function docsEnvelopeToResponse(envelope, gateway, operation, startTime) {
+  if (!envelope.success) {
+    return {
+      meta: dispatchMeta(gateway, "docs", operation, startTime),
+      success: false,
+      error: {
+        code: String(envelope.error?.code ?? "E_INTERNAL"),
+        message: envelope.error?.message ?? "Unknown error",
+        ...envelope.error?.fix !== void 0 ? { fix: envelope.error.fix } : {},
+        // T9636 — preserve structured details (e.g. slug suggestions) so the
+        // CLI can render alternative slugs without a separate API call.
+        ...envelope.error?.details !== void 0 ? { details: envelope.error.details } : {}
+      }
+    };
+  }
+  let attachmentBackend;
+  let dryRun;
+  let hint;
+  let responseData = envelope.data;
+  if (responseData !== null && responseData !== void 0 && typeof responseData === "object") {
+    const dataObj = responseData;
+    let cleanedData = dataObj;
+    let cleaned = false;
+    if ("attachmentBackend" in cleanedData && cleanedData["attachmentBackend"] !== void 0) {
+      attachmentBackend = cleanedData["attachmentBackend"];
+      const { attachmentBackend: _lifted, ...rest } = cleanedData;
+      cleanedData = rest;
+      cleaned = true;
+    }
+    if ("hint" in cleanedData && typeof cleanedData["hint"] === "string") {
+      hint = cleanedData["hint"];
+    }
+    if (cleanedData["dryRun"] === true) {
+      dryRun = true;
+    }
+    if (cleaned) {
+      responseData = cleanedData;
+    }
+  }
+  return {
+    meta: {
+      ...dispatchMeta(gateway, "docs", operation, startTime),
+      ...attachmentBackend !== void 0 ? { attachmentBackend } : {},
+      ...dryRun === true ? { dryRun: true } : {},
+      ...hint !== void 0 ? { hint } : {}
+    },
+    success: true,
+    data: responseData
+  };
+}
+var QUERY_OPS = /* @__PURE__ */ new Set([
+  "list",
+  "fetch",
+  "generate",
+  "llm-output",
+  "export",
+  "search",
+  "find",
+  "merge",
+  "rank",
+  "versions",
+  "status",
+  "audit"
+]);
+var MUTATE_OPS = /* @__PURE__ */ new Set([
+  "add",
+  "remove",
+  "update",
+  "supersede",
+  "publish",
+  "publish-pr",
+  "sync",
+  "import"
+]);
+async function dispatchDocsLegacyQuery(operation, params) {
+  const projectRoot = getProjectRoot();
+  switch (operation) {
+    case "export":
+      return exportDocument({
+        taskId: String(params["taskId"]),
+        includeAttachments: params["includeAttachments"] !== false,
+        includeMemoryRefs: params["includeMemoryRefs"] === true,
+        projectRoot
+      });
+    case "search": {
+      const limit = typeof params["limit"] === "number" ? params["limit"] : 10;
+      if (typeof params["ownerId"] === "string" && params["ownerId"].length > 0) {
+        return searchDocs(String(params["query"]), {
+          ownerId: params["ownerId"],
+          limit,
+          projectRoot
+        });
+      }
+      return searchAllProjectDocs(String(params["query"]), {
+        limit,
+        type: typeof params["type"] === "string" ? params["type"] : void 0,
+        projectRoot
+      });
+    }
+    case "find":
+      return findSimilarDocs(String(params["similarSlug"]), {
+        ...typeof params["limit"] === "number" ? { limit: params["limit"] } : {},
+        ...typeof params["threshold"] === "number" ? { threshold: params["threshold"] } : {},
+        allKinds: params["allKinds"] === true,
+        projectRoot
+      });
+    case "merge":
+      return mergeDocs(String(params["attA"]), String(params["attB"]), {
+        strategy: params["strategy"] === "cherry-pick" || params["strategy"] === "multi-diff" ? params["strategy"] : "three-way",
+        base: typeof params["base"] === "string" ? params["base"] : void 0
+      });
+    case "rank":
+      return rankDocs({
+        ownerId: String(params["ownerId"]),
+        query: typeof params["query"] === "string" ? params["query"] : void 0,
+        projectRoot
+      });
+    case "versions":
+      return listDocVersions({
+        ownerId: String(params["ownerId"]),
+        name: typeof params["name"] === "string" ? params["name"] : void 0,
+        projectRoot
+      });
+    case "audit":
+      if (params["verify"] === true) return verifyAuditTrail(projectRoot);
+      if (typeof params["slug"] !== "string" || !params["slug"]) {
+        throw new Error("Document audit requires slug or verify");
+      }
+      return readAuditLog(projectRoot, params["slug"]);
+    case "status": {
+      const model = createDocsReadModel();
+      return model.status(projectRoot);
+    }
+    default:
+      throw new Error(`Unsupported docs query operation: ${operation}`);
+  }
+}
+async function dispatchDocsLegacyMutate(operation, params) {
+  const projectRoot = getProjectRoot();
+  switch (operation) {
+    case "publish": {
+      if (params["target"] === "pr") return dispatchDocsLegacyMutate("publish-pr", params);
+      if (params["target"] !== void 0 && params["target"] !== "file") {
+        throw new Error("Publication target must be file or pr");
+      }
+      if (!params["ownerId"] || !params["toPath"]) {
+        throw new Error("File publication requires ownerId and toPath");
+      }
+      const result = await publishDocs({
+        ownerId: String(params["ownerId"]),
+        toPath: String(params["toPath"]),
+        attachmentId: typeof params["attachmentId"] === "string" ? params["attachmentId"] : void 0,
+        projectRoot
+      });
+      try {
+        await recordPublication({
+          ownerId: result.ownerId,
+          blobName: result.blobName,
+          publishedPath: result.relativePath,
+          lastBlobSha: result.blobSha256,
+          projectRoot
+        });
+      } catch {
+      }
+      try {
+        writeAuditEntry(projectRoot, {
+          op: "docs.publish",
+          slug: result.blobName,
+          attachmentId: result.blobSha256,
+          summary: `Published doc '${result.blobName}' to ${result.relativePath}`
+        });
+      } catch {
+      }
+      return result;
+    }
+    case "publish-pr": {
+      if (!params["slugOrId"]) throw new Error("PR publication requires slugOrId");
+      const prResult = await publishDocsAsPr({
+        slugOrId: String(params["slugOrId"]),
+        ...typeof params["slug"] === "string" ? { slug: params["slug"] } : {},
+        ...typeof params["type"] === "string" ? { type: params["type"] } : {},
+        ...typeof params["title"] === "string" ? { title: params["title"] } : {},
+        ...typeof params["body"] === "string" ? { body: params["body"] } : {},
+        ...typeof params["base"] === "string" ? { base: params["base"] } : {},
+        ...typeof params["taskId"] === "string" ? { taskId: params["taskId"] } : {}
+      });
+      if (prResult.success) {
+        try {
+          writeAuditEntry(projectRoot, {
+            op: "docs.publish-pr",
+            slug: prResult.data.slug,
+            type: prResult.data.type,
+            attachmentId: prResult.data.blobSha,
+            summary: `Published PR for doc '${prResult.data.slug}' (${prResult.data.action}) \u2014 ${prResult.data.prUrl}`
+          });
+        } catch {
+        }
+      }
+      return prResult;
+    }
+    case "sync": {
+      const syncResult = await syncFromGit({
+        ownerId: String(params["ownerId"]),
+        fromPath: String(params["fromPath"]),
+        blobName: typeof params["blobName"] === "string" ? params["blobName"] : void 0,
+        contentType: typeof params["contentType"] === "string" ? params["contentType"] : void 0,
+        projectRoot
+      });
+      try {
+        writeAuditEntry(projectRoot, {
+          op: "docs.sync",
+          slug: typeof params["blobName"] === "string" && params["blobName"] || void 0,
+          ownerId: String(params["ownerId"]),
+          summary: `Synced doc from '${String(params["fromPath"])}' for owner ${String(params["ownerId"])}`
+        });
+      } catch {
+      }
+      return syncResult;
+    }
+    case "import": {
+      const scanRoot = String(params["scanRoot"]);
+      const accessor = createAttachmentStoreDocsAccessor(projectRoot);
+      try {
+        const result = await runDocsImport({
+          root: scanRoot,
+          accessor,
+          dryRun: params["dryRun"] === true,
+          force: params["force"] === true,
+          manifestPath: typeof params["manifestPath"] === "string" ? params["manifestPath"] : void 0,
+          auditDir: projectRoot,
+          classify: makeClassifierForScanRoot(scanRoot, projectRoot)
+        });
+        try {
+          writeAuditEntry(projectRoot, {
+            op: "docs.import",
+            summary: `Imported ${result.counters.importCount} created, ${result.counters.noopCount} skipped, ${result.counters.errorCount} errors from '${scanRoot}'`
+          });
+        } catch {
+        }
+        return {
+          dryRun: result.dryRun,
+          counters: result.counters,
+          entries: result.entries,
+          manifestPath: result.manifestPath ?? null
+        };
+      } finally {
+        await accessor.close().catch(() => {
+        });
+      }
+    }
+    default:
+      throw new Error(`Unsupported docs mutate operation: ${operation}`);
+  }
+}
+var DocsHandler = class {
+  // -----------------------------------------------------------------------
+  // Query
+  // -----------------------------------------------------------------------
+  /**
+   * Execute a read-only docs query operation.
+   *
+   * @param operation - The docs query op name (e.g. 'list', 'fetch', 'generate').
+   * @param params - Raw params from the dispatcher (narrowed internally).
+   */
+  async query(operation, params) {
+    const startTime = Date.now();
+    if (!QUERY_OPS.has(operation)) {
+      return unsupportedOp("query", "docs", operation, startTime);
+    }
+    try {
+      const projectRoot = getProjectRoot();
+      return await worktreeScope.run(
+        {
+          ...worktreeScope.getStore(),
+          worktreeRoot: projectRoot,
+          projectHash: generateProjectHash(projectRoot)
+        },
+        async () => {
+          if (operation in _docsTypedHandler.operations) {
+            const envelope = await typedDispatch(
+              _docsTypedHandler,
+              operation,
+              params ?? {}
+            );
+            return docsEnvelopeToResponse(envelope, "query", operation, startTime);
+          }
+          return {
+            meta: dispatchMeta("query", "docs", operation, startTime),
+            success: true,
+            data: await dispatchDocsLegacyQuery(operation, params ?? {})
+          };
+        }
+      );
+    } catch (error) {
+      return handleErrorResult("query", "docs", operation, error, startTime);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Mutate
+  // -----------------------------------------------------------------------
+  /**
+   * Execute a state-modifying docs mutation operation.
+   *
+   * @param operation - The docs mutate op name (e.g. 'add', 'remove').
+   * @param params - Raw params from the dispatcher (narrowed internally).
+   */
+  async mutate(operation, params) {
+    const startTime = Date.now();
+    if (!MUTATE_OPS.has(operation)) {
+      return unsupportedOp("mutate", "docs", operation, startTime);
+    }
+    try {
+      const projectRoot = getProjectRoot();
+      return await worktreeScope.run(
+        {
+          ...worktreeScope.getStore(),
+          worktreeRoot: projectRoot,
+          projectHash: generateProjectHash(projectRoot)
+        },
+        async () => {
+          if (operation in _docsTypedHandler.operations) {
+            const envelope = await typedDispatch(
+              _docsTypedHandler,
+              operation,
+              params ?? {}
+            );
+            return docsEnvelopeToResponse(envelope, "mutate", operation, startTime);
+          }
+          return {
+            meta: dispatchMeta("mutate", "docs", operation, startTime),
+            success: true,
+            data: await dispatchDocsLegacyMutate(operation, params ?? {})
+          };
+        }
+      );
+    } catch (error) {
+      return handleErrorResult("mutate", "docs", operation, error, startTime);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Supported operations
+  // -----------------------------------------------------------------------
+  /** Declared operations for introspection and validation. */
+  getSupportedOperations() {
+    return {
+      query: [
+        "list",
+        "fetch",
+        "generate",
+        "llm-output",
+        "export",
+        "search",
+        "find",
+        "merge",
+        "rank",
+        "versions",
+        "status",
+        "audit"
+      ],
+      mutate: ["add", "remove", "update", "supersede", "publish", "publish-pr", "sync", "import"]
+    };
+  }
+};
+export {
+  DocsHandler
+};
+//# sourceMappingURL=docs-CLQKEEUK.js.map