@cleocode/cleo 2026.5.125 → 2026.5.127

package/dist/cli/index.js

@@ -5170,7 +5170,7 @@ var init_operations_registry = __esm({
           }
         ]
       },
-      // === saga sub-domain (ADR-073 — above-epic grouping tier) ===
+      // === saga sub-domain (ADR-088 PM-Core V2 — canonical containment tier) ===
       {
         gateway: "mutate",
         domain: "tasks",
@@ -5319,8 +5319,10 @@ var init_operations_registry = __esm({
         ]
       },
       {
-        // T10117 — detach I5-violating parentId and re-attach via task_relations
+        // [LEGACY T10117] Detach I5-violating parentId and re-attach via task_relations
         // type=groups (ADR-073 §1.2 invariant I5). Idempotent.
+        // PM-Core V2 (ADR-088): parent_id is canonical containment; this repair
+        // direction is the inverse of the canonical model.
         gateway: "mutate",
         domain: "tasks",
         operation: "saga.repair",
@@ -5369,7 +5371,11 @@ var init_operations_registry = __esm({
         ]
       },
       {
-        // T10637 — migrate parent_id-based Saga membership to groups relations.
+        // [LEGACY T10637] Pre-ADR-088 migration: convert parent_id-based Saga
+        // membership to groups relations. PM-Core V2 (ADR-088) canonicalizes
+        // parent_id as the sole containment edge. This operation is retained
+        // for historical reference; its migration direction is the opposite
+        // of the PM-Core V2 canonical model.
         // Converts Epics whose parent_id points to a type='saga' task into proper
         // groups relations. Non-Epic tasks are documented as conflicts.
         gateway: "mutate",
@@ -9548,6 +9554,45 @@ var init_operations_registry = __esm({
           }
         ]
       },
+      // ── docs.llm-output (T11137) — unified LLM output surface ──────────────────
+      {
+        gateway: "query",
+        domain: "docs",
+        operation: "llm-output",
+        description: "docs.llm-output (query) \u2014 unified LLM output: task export (rich Markdown) or attachment-bundle (llms.txt). Replaces `docs export` and `docs generate`.",
+        tier: 1,
+        idempotent: true,
+        sessionRequired: false,
+        requiredParams: ["for"],
+        params: [
+          { name: "for", type: "string", required: true, description: "Target entity ID" },
+          {
+            name: "mode",
+            type: "string",
+            required: false,
+            description: "Output mode: task-export|attachment-bundle (auto-detected)"
+          },
+          { name: "out", type: "string", required: false, description: "Output file path" },
+          {
+            name: "includeAttachments",
+            type: "boolean",
+            required: false,
+            description: "Include attachment manifest (task-export)"
+          },
+          {
+            name: "includeMemoryRefs",
+            type: "boolean",
+            required: false,
+            description: "Include memory refs (task-export)"
+          },
+          {
+            name: "attach",
+            type: "boolean",
+            required: false,
+            description: "Save as llms-txt attachment (attachment-bundle)"
+          }
+        ]
+      },
       // ── docs.update (T10161 — Epic T10157 / Saga T9855) ──────────────────────
       {
         gateway: "mutate",
@@ -13588,6 +13633,511 @@ var init_tasks2 = __esm({
   }
 });
 
+// packages/contracts/src/taxonomy.ts
+var BUILTIN_TAXONOMY_TAGS, CANONICAL_TAG_VALUES, _TAG_BY_ID, ADHOC_TO_CANONICAL, TAGS_BY_AXIS, CANONICAL_TYPE_TAGS, CANONICAL_DOMAIN_TAGS, CANONICAL_DOC_KIND_TAGS, TaxonomyError, TaxonomyRegistry;
+var init_taxonomy = __esm({
+  "packages/contracts/src/taxonomy.ts"() {
+    "use strict";
+    BUILTIN_TAXONOMY_TAGS = [
+      // ─── Domain tags ───────────────────────────────────────────────
+      {
+        tag: "architecture",
+        label: "Architecture",
+        description: "Cross-cutting architectural decisions, patterns, and subsystem-level concerns",
+        axes: ["domain", "type"],
+        adhocAliases: ["architecture"]
+      },
+      {
+        tag: "cli",
+        label: "CLI",
+        description: "Command-line interface, dispatch, and command infrastructure",
+        axes: ["domain"],
+        adhocAliases: ["cli"]
+      },
+      {
+        tag: "core",
+        label: "Core",
+        description: "Core engine, shared utilities, and foundational modules",
+        axes: ["domain"],
+        adhocAliases: ["core", "pm-core-v2", "foundation"]
+      },
+      {
+        tag: "contracts",
+        label: "Contracts",
+        description: "Type contracts, schemas, and public API surface definitions",
+        axes: ["domain"],
+        adhocAliases: ["contracts", "schema"]
+      },
+      {
+        tag: "caamp",
+        label: "CAAMP",
+        description: "Cross-Agent Adaptive Messaging Protocol \u2014 hooks, adapters, providers",
+        axes: ["domain"],
+        adhocAliases: ["caamp", "cant", "pi", "cant-dsl"]
+      },
+      {
+        tag: "skills",
+        label: "Skills",
+        description: "Agent skill definitions, injection, dispatch, and guard patterns",
+        axes: ["domain"],
+        adhocAliases: ["skills"]
+      },
+      {
+        tag: "brain",
+        label: "BRAIN",
+        description: "Cognitive memory system \u2014 decisions, patterns, observations, learnings",
+        axes: ["domain"],
+        adhocAliases: ["brain"]
+      },
+      {
+        tag: "nexus",
+        label: "Nexus",
+        description: "Code intelligence surface \u2014 project indexing, impact analysis, cross-repo",
+        axes: ["domain"],
+        adhocAliases: ["nexus"]
+      },
+      {
+        tag: "orchestration",
+        label: "Orchestration",
+        description: "Multi-agent orchestration, playbooks, LOOM lifecycle, spawn dispatch",
+        axes: ["domain"],
+        adhocAliases: ["orchestration", "orchestrate"]
+      },
+      {
+        tag: "sessions",
+        label: "Sessions",
+        description: "Session lifecycle \u2014 handoff, debrief, briefing, snapshot, state",
+        axes: ["domain"],
+        adhocAliases: ["sessions"]
+      },
+      {
+        tag: "tasks",
+        label: "Tasks",
+        description: "Task management \u2014 CRUD, gates, evidence, acceptance criteria, lifecycle",
+        axes: ["domain"],
+        adhocAliases: ["tasks"]
+      },
+      {
+        tag: "docs",
+        label: "Documents",
+        description: "Document storage, retrieval, taxonomy, publish, and provenance",
+        axes: ["domain"],
+        adhocAliases: ["docs", "documentation"]
+      },
+      {
+        tag: "cleoos",
+        label: "CleoOS",
+        description: "CleoOS runtime \u2014 gateway, daemon, injection facade, agents",
+        axes: ["domain"],
+        adhocAliases: ["cleoos", "facade", "sentient"]
+      },
+      {
+        tag: "worktrunk",
+        label: "Worktrunk",
+        description: "Git worktree management \u2014 spawn, adopt, prune, lifecycle",
+        axes: ["domain"],
+        adhocAliases: ["worktrunk", "worktrunk-ssot"]
+      },
+      {
+        tag: "agents",
+        label: "Agents",
+        description: "Agent profiles, execution learning, registry, dispatch",
+        axes: ["domain"],
+        adhocAliases: ["agents"]
+      },
+      {
+        tag: "routing",
+        label: "Routing",
+        description: "Operation routing, capability matrix, dispatch path resolution",
+        axes: ["domain"],
+        adhocAliases: ["routing"]
+      },
+      {
+        tag: "studio",
+        label: "Studio",
+        description: "Web UI, dashboard, and visual interfaces",
+        axes: ["domain"],
+        adhocAliases: ["studio"]
+      },
+      // ─── Type tags ─────────────────────────────────────────────────
+      {
+        tag: "architectural",
+        label: "Architectural Decision",
+        description: "Cross-cutting architectural decision with durable rationale",
+        axes: ["type"],
+        adhocAliases: ["architectural"]
+      },
+      {
+        tag: "technical",
+        label: "Technical Decision",
+        description: "Implementation-scoped technical decision (library, pattern, algorithm)",
+        axes: ["type"],
+        adhocAliases: ["technical"]
+      },
+      {
+        tag: "process",
+        label: "Process Decision",
+        description: "Workflow, methodology, or operational process decision",
+        axes: ["type"],
+        adhocAliases: ["process"]
+      },
+      {
+        tag: "strategic",
+        label: "Strategic Decision",
+        description: "Long-horizon direction-setting decision spanning multiple epics",
+        axes: ["type"],
+        adhocAliases: ["strategic"]
+      },
+      {
+        tag: "tactical",
+        label: "Tactical Decision",
+        description: "Short-horizon execution-level decision (AGT-* dispatch, within-sprint)",
+        axes: ["type"],
+        adhocAliases: ["tactical"]
+      },
+      {
+        tag: "operational",
+        label: "Operational Decision",
+        description: "Infrastructure, deployment, or runtime configuration decision",
+        axes: ["type"],
+        adhocAliases: ["operational"]
+      },
+      {
+        tag: "bugfix",
+        label: "Bug Fix",
+        description: "Defect correction or regression fix",
+        axes: ["type"],
+        adhocAliases: ["bugfix", "bug-fix", "hygiene"]
+      },
+      {
+        tag: "refactor",
+        label: "Refactor",
+        description: "Internal restructuring without functional change",
+        axes: ["type"],
+        adhocAliases: ["refactor"]
+      },
+      {
+        tag: "feature",
+        label: "Feature",
+        description: "New capability or user-facing enhancement",
+        axes: ["type"],
+        adhocAliases: ["feature"]
+      },
+      {
+        tag: "discovery",
+        label: "Discovery",
+        description: "Exploratory research, investigation, or spike outcome",
+        axes: ["type"],
+        adhocAliases: ["discovery", "exploration", "research-type"]
+      },
+      {
+        tag: "migration",
+        label: "Migration",
+        description: "Data or schema migration, backfill, or upgrade path",
+        axes: ["type"],
+        adhocAliases: ["migration", "migrations"]
+      },
+      {
+        tag: "unification",
+        label: "Unification",
+        description: "Consolidation of fragmented systems into a single SSoT",
+        axes: ["type"],
+        adhocAliases: ["unification"]
+      },
+      {
+        tag: "bootstrap",
+        label: "Bootstrap",
+        description: "Initial setup, scaffolding, or seed infrastructure",
+        axes: ["type"],
+        adhocAliases: ["bootstrap"]
+      },
+      // ─── Lifecycle tags ────────────────────────────────────────────
+      {
+        tag: "research",
+        label: "Research",
+        description: "LOOM stage 1: information gathering and domain understanding",
+        axes: ["lifecycle"],
+        adhocAliases: ["research", "wave-0"]
+      },
+      {
+        tag: "consensus",
+        label: "Consensus",
+        description: "LOOM stage 2: multi-agent consensus and validation of findings",
+        axes: ["lifecycle"],
+        adhocAliases: ["consensus"]
+      },
+      {
+        tag: "design",
+        label: "Architecture Decision",
+        description: "LOOM stage 3: architecture decision recording and validation",
+        axes: ["lifecycle"],
+        adhocAliases: ["design", "architecture_decision"]
+      },
+      {
+        tag: "specification",
+        label: "Specification",
+        description: "LOOM stage 4: technical specification authoring",
+        axes: ["lifecycle"],
+        adhocAliases: ["specification", "rfc"]
+      },
+      {
+        tag: "decomposition",
+        label: "Decomposition",
+        description: "LOOM stage 5: task decomposition and dependency modeling",
+        axes: ["lifecycle"],
+        adhocAliases: ["decomposition"]
+      },
+      {
+        tag: "implementation",
+        label: "Implementation",
+        description: "LOOM stage 6: code authoring and unit-level verification",
+        axes: ["lifecycle"],
+        adhocAliases: [
+          "implementation",
+          "wave-1",
+          "wave-2",
+          "wave-3",
+          "wave-4",
+          "wave-5",
+          "wave.1",
+          "wave.2",
+          "wave.3"
+        ]
+      },
+      {
+        tag: "validation",
+        label: "Validation",
+        description: "LOOM stage 7: integration testing and gate verification",
+        axes: ["lifecycle"],
+        adhocAliases: ["validation", "testing"]
+      },
+      {
+        tag: "release",
+        label: "Release",
+        description: "LOOM stage 9: versioning, changelog, npm publish, tag push",
+        axes: ["lifecycle", "type"],
+        adhocAliases: ["release"]
+      },
+      // ─── Priority tags ─────────────────────────────────────────────
+      {
+        tag: "p0",
+        label: "P0 \u2014 Critical",
+        description: "Drop-everything critical: blocks release, data loss, security incident",
+        axes: ["priority"],
+        adhocAliases: ["p0", "critical", "prime-tier1"]
+      },
+      {
+        tag: "p1",
+        label: "P1 \u2014 High",
+        description: "High priority: blocks dependent work, user-visible degradation",
+        axes: ["priority"],
+        adhocAliases: ["p1"]
+      },
+      {
+        tag: "p2",
+        label: "P2 \u2014 Medium",
+        description: "Medium priority: should fix, not blocking current wave",
+        axes: ["priority"],
+        adhocAliases: ["p2"]
+      },
+      {
+        tag: "p3",
+        label: "P3 \u2014 Low",
+        description: "Low priority: nice-to-have, cleanup, future consideration",
+        axes: ["priority"],
+        adhocAliases: ["p3"]
+      },
+      // ─── Doc-kind tags (absorb docs-taxonomy) ──────────────────────
+      {
+        tag: "adr",
+        label: "Architecture Decision Record",
+        description: "Formal architecture decision record with rationale and alternatives",
+        axes: ["doc_kind"],
+        adhocAliases: ["adr"]
+      },
+      {
+        tag: "spec",
+        label: "Specification",
+        description: "Technical specification for a feature, protocol, or subsystem",
+        axes: ["doc_kind"],
+        adhocAliases: ["spec"]
+      },
+      {
+        tag: "research",
+        label: "Research Note",
+        description: "Investigation findings, surveys, and domain analysis",
+        axes: ["doc_kind"],
+        adhocAliases: ["research"]
+      },
+      {
+        tag: "handoff",
+        label: "Handoff Note",
+        description: "Cross-session handoff with state, blockers, and next actions",
+        axes: ["doc_kind"],
+        adhocAliases: ["handoff"]
+      },
+      {
+        tag: "note",
+        label: "Note",
+        description: "General-purpose note, observation, or free-form documentation",
+        axes: ["doc_kind"],
+        adhocAliases: ["note"]
+      },
+      {
+        tag: "llmreadme",
+        label: "LLM README",
+        description: "Agent-consumable project overview, conventions, and context",
+        axes: ["doc_kind"],
+        adhocAliases: ["llmreadme", "llm-readme"]
+      },
+      {
+        tag: "designmd",
+        label: "Design Doc",
+        description: "Google DESIGN.md token spec for agent interface contracts",
+        axes: ["doc_kind"],
+        adhocAliases: ["designmd", "design-md"]
+      },
+      {
+        tag: "changeset",
+        label: "Changeset",
+        description: "User-facing changelog entry for a single change",
+        axes: ["doc_kind"],
+        adhocAliases: ["changeset"]
+      },
+      {
+        tag: "changelog",
+        label: "Changelog",
+        description: "Aggregated release changelog for a version",
+        axes: ["doc_kind"],
+        adhocAliases: ["changelog"]
+      }
+    ];
+    CANONICAL_TAG_VALUES = BUILTIN_TAXONOMY_TAGS.map((t) => t.tag);
+    _TAG_BY_ID = new Map(
+      BUILTIN_TAXONOMY_TAGS.map((t) => [t.tag, t])
+    );
+    ADHOC_TO_CANONICAL = /* @__PURE__ */ new Map();
+    for (const tag of BUILTIN_TAXONOMY_TAGS) {
+      for (const alias2 of tag.adhocAliases) {
+        ADHOC_TO_CANONICAL.set(alias2, tag.tag);
+      }
+    }
+    TAGS_BY_AXIS = /* @__PURE__ */ new Map();
+    for (const axis of ["domain", "type", "lifecycle", "priority", "doc_kind"]) {
+      TAGS_BY_AXIS.set(
+        axis,
+        BUILTIN_TAXONOMY_TAGS.filter((t) => t.axes.includes(axis))
+      );
+    }
+    CANONICAL_TYPE_TAGS = TAGS_BY_AXIS.get("type").map(
+      (t) => t.tag
+    );
+    CANONICAL_DOMAIN_TAGS = TAGS_BY_AXIS.get("domain").map(
+      (t) => t.tag
+    );
+    CANONICAL_DOC_KIND_TAGS = TAGS_BY_AXIS.get("doc_kind").map(
+      (t) => t.tag
+    );
+    TaxonomyError = class extends Error {
+      constructor(message, invalidTags) {
+        super(message);
+        this.invalidTags = invalidTags;
+        this.name = "TaxonomyError";
+      }
+      invalidTags;
+    };
+    TaxonomyRegistry = class _TaxonomyRegistry {
+      byId;
+      adhocMap;
+      constructor(tags) {
+        this.byId = new Map(tags.map((t) => [t.tag, t]));
+        this.adhocMap = /* @__PURE__ */ new Map();
+        for (const tag of tags) {
+          for (const alias2 of tag.adhocAliases) {
+            const existingTarget = this.adhocMap.get(alias2);
+            if (existingTarget !== void 0 && existingTarget !== tag.tag) {
+              throw new TaxonomyError(
+                `Ad-hoc alias '${alias2}' maps to both '${existingTarget}' and '${tag.tag}' \u2014 aliases must be unique across targets`,
+                [alias2]
+              );
+            }
+            this.adhocMap.set(alias2, tag.tag);
+          }
+        }
+      }
+      /** Default built-in registry singleton. */
+      static default = new _TaxonomyRegistry(BUILTIN_TAXONOMY_TAGS);
+      /** True when `tag` is a canonical tag. */
+      isCanonical(tag) {
+        return this.byId.has(tag);
+      }
+      /** Look up metadata for a canonical tag. */
+      get(tag) {
+        return this.byId.get(tag);
+      }
+      /** List all canonical tags. */
+      list() {
+        return [...this.byId.values()];
+      }
+      /** List tags for a specific axis. */
+      listByAxis(axis) {
+        return this.list().filter((t) => t.axes.includes(axis));
+      }
+      /**
+       * Normalize an ad-hoc label to its canonical form.
+       *
+       * Returns the canonical tag id, or `undefined` if the label has no
+       * known canonical mapping.
+       */
+      normalize(adhoc) {
+        return this.adhocMap.get(adhoc);
+      }
+      /**
+       * Validate that every tag in `tags` is canonical.
+       *
+       * @param tags - Tags to validate.
+       * @returns An array of invalid tags. Empty array = all valid.
+       */
+      validate(tags) {
+        return tags.filter((t) => !this.byId.has(t));
+      }
+      /**
+       * Validate tags and throw on failure.
+       *
+       * @param tags - Tags to validate.
+       * @param context - Human-readable context for the error message.
+       * @throws TaxonomyError when any tag is not canonical.
+       */
+      validateOrThrow(tags, context) {
+        const invalid = this.validate(tags);
+        if (invalid.length > 0) {
+          throw new TaxonomyError(
+            `${context}: unknown tags [${invalid.join(", ")}]. Use canonical tags. Run 'cleo taxonomy list' to see all valid tags.`,
+            invalid
+          );
+        }
+      }
+      /**
+       * Normalize a set of ad-hoc labels to canonical form.
+       *
+       * Unknown labels are passed through unchanged (they may be
+       * project-specific extensions or task-id references).
+       *
+       * @param labels - Ad-hoc labels to normalize.
+       * @returns Normalized label set (deduplicated).
+       */
+      normalizeSet(labels) {
+        const result = /* @__PURE__ */ new Set();
+        for (const label of labels) {
+          const canonical = this.normalize(label);
+          result.add(canonical ?? label);
+        }
+        return [...result];
+      }
+    };
+  }
+});
+
 // packages/contracts/src/templates/manifest.ts
 import { z as z15 } from "zod";
 var TEMPLATE_KINDS, TEMPLATE_SUBSTITUTIONS, TEMPLATE_UPDATE_STRATEGIES, PLACEHOLDER_SOURCES, PlaceholderSpecSchema, TemplateManifestEntrySchema;
@@ -13740,6 +14290,7 @@ var init_src2 = __esm({
     init_task_evidence();
     init_archive();
     init_tasks2();
+    init_taxonomy();
     init_manifest2();
     init_validator();
     init_workgraph();
@@ -18700,15 +19251,17 @@ var init_diagnostics = __esm({
 // packages/cleo/src/dispatch/domains/docs.ts
 import { readFile } from "node:fs/promises";
 import { resolve as resolve2 } from "node:path";
+import { LLM_OUTPUT_MODES } from "@cleocode/contracts/operations/docs";
 import { pushWarning } from "@cleocode/core";
 import {
   AUTO_TOKEN,
   allocateAdrSlug,
   allocateAutoSlugForDispatch,
   consumeReservedSlug,
+  createAttachmentBlobStore,
   createAttachmentStore,
   createAttachmentStoreDocsAccessor,
-  createAttachmentStoreV2,
+  createDocsReadModel,
   DOCS_UPDATE_LIFECYCLE_STATUS_LIST,
   exportDocument,
   findSimilarDocs,
@@ -18735,11 +19288,11 @@ import {
   SUPERSEDE_SAME_SLUG_CODE,
   searchAllProjectDocs,
   searchDocs,
-  statusDocs,
   supersedeDoc,
   syncFromGit,
   updateDocBySlug,
   validateDocBody,
+  writeAuditEntry,
   writeChangesetEntry
 } from "@cleocode/core/internal";
 function getDocKindRegistry() {
@@ -18759,6 +19312,12 @@ function getDocKindRegistry() {
 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";
@@ -18860,6 +19419,7 @@ function docsEnvelopeToResponse(envelope, gateway, operation, startTime) {
       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 } : {}
@@ -18950,8 +19510,10 @@ async function dispatchDocsLegacyQuery(operation, params) {
         name: typeof params["name"] === "string" ? params["name"] : void 0,
         projectRoot
       });
-    case "status":
-      return statusDocs({ projectRoot });
+    case "status": {
+      const model = createDocsReadModel();
+      return model.status(projectRoot);
+    }
     default:
       throw new Error(`Unsupported docs query operation: ${operation}`);
   }
@@ -18976,10 +19538,19 @@ async function dispatchDocsLegacyMutate(operation, params) {
         });
       } 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":
-      return publishDocsAsPr({
+    case "publish-pr": {
+      const prResult = await publishDocsAsPr({
         slugOrId: String(params["slugOrId"]),
         ...typeof params["slug"] === "string" ? { slug: params["slug"] } : {},
         ...typeof params["type"] === "string" ? { type: params["type"] } : {},
@@ -18987,14 +19558,39 @@ async function dispatchDocsLegacyMutate(operation, params) {
         ...typeof params["body"] === "string" ? { body: params["body"] } : {},
         ...typeof params["base"] === "string" ? { base: params["base"] } : {}
       });
-    case "sync":
-      return syncFromGit({
+      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);
@@ -19008,6 +19604,13 @@ async function dispatchDocsLegacyMutate(operation, params) {
           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,
@@ -19023,7 +19626,7 @@ async function dispatchDocsLegacyMutate(operation, params) {
       throw new Error(`Unsupported docs mutate operation: ${operation}`);
   }
 }
-var DOCS_LIST_DEFAULT_LIMIT, _registryCache, SLUG_PATTERN, SLUG_MAX_LEN, _docsTypedHandler, QUERY_OPS3, MUTATE_OPS3, DocsHandler;
+var DOCS_LIST_DEFAULT_LIMIT, SLUG_COLLISION_GUIDANCE, _registryCache, SLUG_PATTERN, SLUG_MAX_LEN, _docsTypedHandler, QUERY_OPS3, MUTATE_OPS3, DocsHandler;
 var init_docs2 = __esm({
   "packages/cleo/src/dispatch/domains/docs.ts"() {
     "use strict";
@@ -19032,6 +19635,13 @@ var init_docs2 = __esm({
     init_base();
     init_meta2();
     DOCS_LIST_DEFAULT_LIMIT = 50;
+    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>`;
     _registryCache = /* @__PURE__ */ new Map();
     SLUG_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
     SLUG_MAX_LEN = 80;
@@ -19062,30 +19672,29 @@ var init_docs2 = __esm({
             "no scope set \u2014 defaulted to --project. Pass --task <id>, --session <id>, or --observation <id> for a narrower listing."
           );
         }
-        const store = createAttachmentStore();
-        const backend = await resolveAttachmentBackend();
+        const model = createDocsReadModel();
+        const backend = await currentAttachmentBackend();
         if (isProjectScope) {
-          const rows = await store.listAllInProject(
-            void 0,
-            typeFilter !== void 0 ? { type: typeFilter } : void 0
-          );
-          const projected = rows.map(({ metadata: m, slug, type: type2, ownerId: oid, ownerType: ot }) => ({
-            id: m.id,
-            sha256: `${m.sha256.slice(0, 8)}\u2026`,
-            // T9792 — keep the full sha256 for stable cross-row sorting; the
-            // displayed truncated form is preserved on the wire field above.
-            _sortSha: m.sha256,
-            kind: m.attachment.kind,
-            mime: m.attachment.kind === "local-file" || m.attachment.kind === "blob" ? m.attachment.mime : m.attachment.mime ?? "\u2014",
-            size: m.attachment.kind === "local-file" || m.attachment.kind === "blob" ? m.attachment.size : void 0,
-            description: m.attachment.description,
-            labels: m.attachment.labels,
-            createdAt: m.createdAt,
-            refCount: m.refCount,
-            ...slug ? { slug } : {},
-            ...type2 ? { type: type2 } : {},
-            ownerId: oid,
-            ownerType: ot
+          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,
+            sha256: `${doc.sha256.slice(0, 8)}\u2026`,
+            _sortSha: doc.sha256,
+            kind: "blob",
+            mime: doc.mimeType ?? "\u2014",
+            size: doc.sizeBytes,
+            description: void 0,
+            labels: void 0,
+            createdAt: doc.createdAt,
+            refCount: 0,
+            ...doc.slug ? { slug: doc.slug } : {},
+            ...doc.kind ? { type: doc.kind } : {},
+            ownerId: doc.ownerId,
+            ownerType: doc.ownerType
           }));
           projected.sort(
             (a, b) => comparator(
@@ -19093,12 +19702,10 @@ var init_docs2 = __esm({
               { sha256: b._sortSha, slug: b.slug, createdAt: b.createdAt }
             )
           );
-          const totalCount = projected.length;
-          const sliced = Number.isFinite(effectiveLimit) ? projected.slice(0, effectiveLimit) : projected;
-          const truncated = totalCount > sliced.length;
+          const truncated = totalCount > projected.length;
           if (truncated) {
             hintParts.push(
-              `showing ${sliced.length} of ${totalCount} \u2014 pass --limit <N> to widen or page further.`
+              `showing ${projected.length} of ${totalCount} \u2014 pass --limit <N> to widen or page further.`
             );
           }
           return lafsSuccess(
@@ -19107,12 +19714,12 @@ var init_docs2 = __esm({
               ownerType: "task",
               project: true,
               ...typeFilter !== void 0 ? { type: typeFilter } : {},
-              count: sliced.length,
+              count: projected.length,
               ...truncated ? { totalCount } : {},
               limit: Number.isFinite(effectiveLimit) ? effectiveLimit : 0,
               orderBy,
               ...hintParts.length > 0 ? { hint: hintParts.join(" ") } : {},
-              attachments: sliced.map(({ _sortSha: _drop, ...row }) => row),
+              attachments: projected.map(({ _sortSha: _drop, ...row }) => row),
               attachmentBackend: backend
             },
             "list"
@@ -19120,28 +19727,20 @@ var init_docs2 = __esm({
         }
         const scopedOwner = ownerId;
         const ownerType = inferOwnerType(scopedOwner);
-        const ownerAttachments = await store.listByOwner(ownerType, scopedOwner);
-        const enriched = [];
-        for (const m of ownerAttachments) {
-          const extras = await store.getExtras(m.id);
-          const slug = extras?.slug ?? null;
-          const type2 = extras?.type ?? null;
-          if (typeFilter !== void 0 && type2 !== typeFilter) continue;
-          enriched.push({ meta: m, slug, type: type2 });
-        }
-        const projectedOwner = enriched.map(({ meta: m, slug, type: type2 }) => ({
-          id: m.id,
-          sha256: `${m.sha256.slice(0, 8)}\u2026`,
-          _sortSha: m.sha256,
-          kind: m.attachment.kind,
-          mime: m.attachment.kind === "local-file" || m.attachment.kind === "blob" ? m.attachment.mime : m.attachment.mime ?? "\u2014",
-          size: m.attachment.kind === "local-file" || m.attachment.kind === "blob" ? m.attachment.size : void 0,
-          description: m.attachment.description,
-          labels: m.attachment.labels,
-          createdAt: m.createdAt,
-          refCount: m.refCount,
-          ...slug ? { slug } : {},
-          ...type2 ? { type: type2 } : {}
+        const ownerDocs = await model.resolveByOwner(scopedOwner, { ownerType, kind: typeFilter });
+        const projectedOwner = ownerDocs.map((doc) => ({
+          id: doc.id,
+          sha256: `${doc.sha256.slice(0, 8)}\u2026`,
+          _sortSha: doc.sha256,
+          kind: "blob",
+          mime: doc.mimeType ?? "\u2014",
+          size: doc.sizeBytes,
+          description: void 0,
+          labels: void 0,
+          createdAt: doc.createdAt,
+          refCount: 0,
+          ...doc.slug ? { slug: doc.slug } : {},
+          ...doc.kind ? { type: doc.kind } : {}
         }));
         projectedOwner.sort(
           (a, b) => comparator(
@@ -19168,7 +19767,6 @@ var init_docs2 = __esm({
             orderBy,
             ...hintParts.length > 0 ? { hint: hintParts.join(" ") } : {},
             attachments: slicedOwner.map(({ _sortSha: _drop, ...row }) => row),
-            // Cast: core returns 'llmtxt'|'legacy'; contracts uses 'legacy'|'llmstxt-v2' (drift T1529)
             attachmentBackend: backend
           },
           "list"
@@ -19221,6 +19819,79 @@ var init_docs2 = __esm({
           "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 = getProjectRoot5();
+        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;
@@ -19231,103 +19902,53 @@ var init_docs2 = __esm({
             "fetch"
           );
         }
-        const store = createAttachmentStore();
-        const isSha256 = /^[0-9a-f]{64}$/i.test(ref);
-        const looksLikeAttId = /^(att_|[0-9a-f]{8}-)/i.test(ref);
-        const looksLikeSlug = SLUG_PATTERN.test(ref) && !/^[0-9a-f]+$/i.test(ref);
-        const isHexPrefix = /^[0-9a-f]{6,63}$/i.test(ref);
-        let fetchResult = null;
-        let metadata = isSha256 ? null : looksLikeAttId ? await store.getMetadata(ref) : null;
-        if (metadata) {
-          fetchResult = await store.get(metadata.sha256);
-        } else if (isSha256) {
-          fetchResult = await store.get(ref);
-          if (fetchResult) {
-            metadata = fetchResult.metadata;
-          }
-        }
-        if (!metadata && looksLikeSlug) {
-          const bySlug = await store.findBySlug(ref);
-          if (bySlug) {
-            metadata = bySlug.metadata;
-            fetchResult = await store.get(metadata.sha256);
-          }
-        }
-        if (!metadata && isHexPrefix) {
-          const projectList = await store.listAllInProject();
-          const seen = /* @__PURE__ */ new Map();
-          for (const row of projectList) {
-            if (row.metadata.sha256.toLowerCase().startsWith(ref.toLowerCase())) {
-              seen.set(row.metadata.id, row);
-            }
-          }
-          if (seen.size > 1) {
-            return lafsError(
-              "E_AMBIGUOUS",
-              `sha256 prefix '${ref}' matches ${seen.size} attachments \u2014 provide more hex digits`,
-              "fetch"
-            );
-          }
-          const hit = seen.values().next().value;
-          if (hit) {
-            metadata = hit.metadata;
-            fetchResult = await store.get(metadata.sha256);
-          }
-        }
-        if (!metadata && !looksLikeAttId) {
-          const direct = await store.getMetadata(ref);
-          if (direct) {
-            metadata = direct;
-            fetchResult = await store.get(direct.sha256);
-          }
-        }
-        if (!fetchResult || !metadata) {
+        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 = getProjectRoot5();
         const cleoDir = resolveCanonicalCleoDir(resolveProjectByCwd(cwd));
         let storagePath;
-        if (metadata.attachment.kind === "local-file") {
-          storagePath = metadata.attachment.path;
-        } else if (metadata.attachment.kind === "blob") {
-          const prefix = metadata.sha256.slice(0, 2);
-          const rest = metadata.sha256.slice(2);
+        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 mime = metadata.attachment.kind === "blob" ? metadata.attachment.mime : "application/octet-stream";
-          const ext = extMap[mime] ?? ".bin";
+          const ext = extMap[doc.mimeType ?? ""] ?? ".bin";
           storagePath = resolve2(cleoDir, "attachments", "sha256", prefix, `${rest}${ext}`);
         }
         const MAX_INLINE = 1024 * 1024;
-        const bytesBase64 = fetchResult.bytes.length <= MAX_INLINE ? fetchResult.bytes.toString("base64") : void 0;
-        const backend = await resolveAttachmentBackend();
-        const extras = await store.getExtras(metadata.id);
+        const contentBytes = Buffer.from(content, "utf-8");
+        const bytesBase64 = contentBytes.length <= MAX_INLINE ? contentBytes.toString("base64") : void 0;
+        const backend = await currentAttachmentBackend();
         return lafsSuccess(
           {
-            // Project the domain AttachmentMetadata (nested `attachment` object) into the
-            // flat DocsAttachmentRow wire format consumed by CLI + HTTP callers.
             metadata: {
-              id: metadata.id,
-              sha256: metadata.sha256,
-              kind: metadata.attachment.kind,
-              mime: metadata.attachment.kind === "local-file" || metadata.attachment.kind === "blob" ? metadata.attachment.mime : metadata.attachment.mime,
-              size: metadata.attachment.kind === "local-file" || metadata.attachment.kind === "blob" ? metadata.attachment.size : void 0,
-              description: metadata.attachment.description,
-              labels: metadata.attachment.labels,
-              createdAt: metadata.createdAt,
-              refCount: metadata.refCount,
-              ...extras?.slug ? { slug: extras.slug } : {},
-              ...extras?.type ? { type: extras.type } : {}
+              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 } : {}
             },
             path: storagePath,
-            sizeBytes: fetchResult.bytes.length,
+            sizeBytes: contentBytes.length,
             ...bytesBase64 !== void 0 ? { bytesBase64 } : {},
             inlined: bytesBase64 !== void 0,
-            // Cast: core returns 'llmtxt'|'legacy'; contracts uses 'legacy'|'llmstxt-v2' (T1529)
             attachmentBackend: backend
           },
           "fetch"
@@ -19475,6 +20096,17 @@ var init_docs2 = __esm({
             type: "changeset"
           };
           emitDocAttachmentObservation(changesetPayload, getProjectRoot5());
+          try {
+            writeAuditEntry(getProjectRoot5(), {
+              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(
             {
               attachmentId: outcome.result.attachmentId,
@@ -19487,9 +20119,8 @@ var init_docs2 = __esm({
               kind: "blob",
               ownerId: outcome.result.ownerId,
               ownerType: "task",
-              // Changeset writes land in the legacy attachment store; v2 mirror
-              // is not applicable to the dual-write transaction.
-              attachmentBackend: "legacy",
+              // Cast: core returns 'llmtxt' (Wave C — legacy backend retired for mirror store).
+              attachmentBackend: await currentAttachmentBackend(),
               slug: outcome.result.slug,
               type: "changeset"
             },
@@ -19530,7 +20161,8 @@ var init_docs2 = __esm({
               success: false,
               error: {
                 code: "E_SLUG_RESERVED",
-                message: `slug '${slug}' is already in use in this project`,
+                message: SLUG_COLLISION_GUIDANCE.replaceAll("{slug}", slug ?? ""),
+                fix: `cleo docs update ${slug ?? "<slug>"} --file <your-file>`,
                 details: {
                   suggestions: reservation.suggestions,
                   aliases: ["E_SLUG_TAKEN"]
@@ -19611,7 +20243,8 @@ var init_docs2 = __esm({
                 success: false,
                 error: {
                   code: "E_SLUG_RESERVED",
-                  message: `slug '${err.slug}' is already in use in this project`,
+                  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"]
@@ -19622,17 +20255,17 @@ var init_docs2 = __esm({
             throw err;
           }
           if (adrNumber !== void 0 && slug !== void 0) consumeReservedSlug(slug);
-          let backend = "legacy";
+          let backend = "llmtxt";
           try {
-            const v2 = createAttachmentStoreV2(getProjectRoot5());
-            const v2Result = await v2.put(ownerId, {
+            const blobMirror = createAttachmentBlobStore(getProjectRoot5());
+            const mirrorResult = await blobMirror.put(ownerId, {
               name: absPath.split(/[\\/]/).pop() ?? meta.sha256.slice(0, 12),
               data: new Uint8Array(bytes),
               contentType: mime
             });
-            backend = v2Result.backend;
+            backend = mirrorResult.backend;
           } catch {
-            backend = await resolveAttachmentBackend();
+            backend = await currentAttachmentBackend();
           }
           import("@cleocode/core/internal").then(
             ({ ensureLlmtxtNode }) => ensureLlmtxtNode(
@@ -19652,6 +20285,18 @@ var init_docs2 = __esm({
             ...type2 !== void 0 ? { type: type2 } : {}
           };
           emitDocAttachmentObservation(filePayload, getProjectRoot5());
+          try {
+            writeAuditEntry(getProjectRoot5(), {
+              op: "docs.add",
+              slug,
+              type: type2,
+              attachmentId: meta.id,
+              sha256: meta.sha256,
+              ownerId,
+              summary: `Added doc '${slug ?? meta.sha256.slice(0, 12)}'${type2 ? ` of type '${type2}'` : ""} for owner ${ownerId}`
+            });
+          } catch {
+          }
           return lafsSuccess(
             {
               attachmentId: meta.id,
@@ -19695,7 +20340,8 @@ var init_docs2 = __esm({
                 success: false,
                 error: {
                   code: "E_SLUG_RESERVED",
-                  message: `slug '${err.slug}' is already in use in this project`,
+                  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"]
@@ -19710,7 +20356,7 @@ var init_docs2 = __esm({
             ({ ensureLlmtxtNode }) => ensureLlmtxtNode(getProjectRoot5(), meta.sha256, `${ownerType}:${ownerId}`, url)
           ).catch(() => {
           });
-          const backend = "legacy";
+          const backend = await currentAttachmentBackend();
           const urlPayload = {
             kind: "doc-attachment",
             attachmentId: meta.id,
@@ -19720,6 +20366,18 @@ var init_docs2 = __esm({
             ...type2 !== void 0 ? { type: type2 } : {}
           };
           emitDocAttachmentObservation(urlPayload, getProjectRoot5());
+          try {
+            writeAuditEntry(getProjectRoot5(), {
+              op: "docs.add",
+              slug,
+              type: type2,
+              attachmentId: meta.id,
+              sha256: meta.sha256,
+              ownerId,
+              summary: `Added URL doc '${slug ?? url}'${type2 ? ` of type '${type2}'` : ""} for owner ${ownerId}`
+            });
+          } catch {
+          }
           return lafsSuccess(
             {
               attachmentId: meta.id,
@@ -19774,11 +20432,20 @@ var init_docs2 = __esm({
         const blobPurged = derefResult.status === "removed";
         const refCountAfter = derefResult.status === "derefd" ? derefResult.refCountAfter : 0;
         try {
-          const v2 = createAttachmentStoreV2(getProjectRoot5());
-          await v2.remove(attachmentId, fromOwner);
+          const blobMirror = createAttachmentBlobStore(getProjectRoot5());
+          await blobMirror.remove(attachmentId, fromOwner);
+        } catch {
+        }
+        const backend = await currentAttachmentBackend();
+        try {
+          writeAuditEntry(getProjectRoot5(), {
+            op: "docs.remove",
+            attachmentId,
+            ownerId: fromOwner,
+            summary: `Removed attachment ${attachmentId} from owner ${fromOwner}${blobPurged ? " (blob purged)" : ""}`
+          });
         } catch {
         }
-        const backend = await resolveAttachmentBackend();
         return lafsSuccess(
           {
             removed: blobPurged,
@@ -19827,6 +20494,42 @@ var init_docs2 = __esm({
             "details" in outcome.error ? outcome.error.details : void 0
           );
         }
+        let backend = "llmtxt";
+        try {
+          const blobMirror = createAttachmentBlobStore(getProjectRoot5());
+          const updatedBytes = hasFile ? new Uint8Array(await readFile(resolve2(filePath))) : new Uint8Array(Buffer.from(inlineContent, "utf-8"));
+          const contentType = hasFile ? mimeFromPath(resolve2(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(getProjectRoot5(), {
+            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,
@@ -19839,7 +20542,15 @@ var init_docs2 = __esm({
             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 } : {}
@@ -19871,6 +20582,15 @@ var init_docs2 = __esm({
             edgeId: result.edgeId,
             ...result.reason !== void 0 ? { reason: result.reason } : {}
           };
+          try {
+            writeAuditEntry(getProjectRoot5(), {
+              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" ? (
@@ -46439,6 +47159,53 @@ var init_strict_args = __esm({
   }
 });
 
+// packages/cleo/src/cli/commands/docs/audit.ts
+var auditCommand3;
+var init_audit3 = __esm({
+  "packages/cleo/src/cli/commands/docs/audit.ts"() {
+    "use strict";
+    init_src2();
+    init_cli();
+    init_define_cli_command();
+    init_renderers();
+    auditCommand3 = 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.",
+            1 /* 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 {
   buildDocProvenanceGraph,
@@ -46931,7 +47698,7 @@ async function spawnDetachedServer(opts) {
   if (handle) await handle.close();
   return child;
 }
-var DETACHED_CHILD_ENV, serveCommand, openCommand, stopCommand4, viewerStatusCommand, docsViewerSubcommands;
+var DETACHED_CHILD_ENV, serveCommand, openCommand, stopCommand4, viewerStatusCommand, runViewerStatus, viewerCommand, docsViewerSubcommands;
 var init_docs_viewer = __esm({
   "packages/cleo/src/cli/commands/docs-viewer.ts"() {
     "use strict";
@@ -46944,7 +47711,7 @@ var init_docs_viewer = __esm({
     serveCommand = defineCommand({
       meta: {
         name: "serve",
-        description: "Run a local web viewer for published docs"
+        description: "[legacy] Run docs viewer \u2014 prefer `cleo docs viewer start`"
       },
       args: {
         port: {
@@ -47115,7 +47882,7 @@ var init_docs_viewer = __esm({
     openCommand = defineCommand({
       meta: {
         name: "open",
-        description: "Open the docs viewer in the browser (auto-starts server if needed)"
+        description: "[legacy] Open docs viewer in browser \u2014 prefer `cleo docs viewer open`"
       },
       args: {
         slug: {
@@ -47212,7 +47979,7 @@ var init_docs_viewer = __esm({
     stopCommand4 = defineCommand({
       meta: {
         name: "stop",
-        description: "Stop the running docs viewer (SIGTERM + cleanup pidfile)"
+        description: "[legacy] Stop the docs viewer \u2014 prefer `cleo docs viewer stop`"
       },
       args: {
         timeout: {
@@ -47285,64 +48052,85 @@ var init_docs_viewer = __esm({
     viewerStatusCommand = defineCommand({
       meta: {
         name: "viewer-status",
-        description: "Report viewer running state (pid, port, url)"
+        description: "[legacy] Report viewer state \u2014 prefer `cleo docs viewer status`"
       },
       async run() {
-        const record = await readViewerPidFile();
-        if (!record) {
-          cliOutput(
-            { running: false, pidFile: viewerPidFilePath() },
-            {
-              command: "docs viewer-status",
-              operation: "docs.viewer-status",
-              message: "viewer not running"
-            }
-          );
-          return;
-        }
-        const alive = isProcessAlive(record.pid);
-        if (!alive) {
-          await removeViewerPidFile();
-          cliOutput(
-            {
-              running: false,
-              reason: "stale pidfile",
-              pid: record.pid,
-              pidFile: viewerPidFilePath()
-            },
-            {
-              command: "docs viewer-status",
-              operation: "docs.viewer-status",
-              message: `stale pidfile removed (pid ${record.pid} not alive)`
-            }
-          );
-          return;
-        }
+        await runViewerStatus();
+      }
+    });
+    runViewerStatus = async () => {
+      const record = await readViewerPidFile();
+      if (!record) {
         cliOutput(
+          { running: false, pidFile: viewerPidFilePath() },
           {
-            running: true,
+            command: "docs viewer-status",
+            operation: "docs.viewer-status",
+            message: "viewer not running"
+          }
+        );
+        return;
+      }
+      const alive = isProcessAlive(record.pid);
+      if (!alive) {
+        await removeViewerPidFile();
+        cliOutput(
+          {
+            running: false,
+            reason: "stale pidfile",
             pid: record.pid,
-            port: record.port,
-            host: record.host,
-            projectRoot: record.projectRoot,
-            startedAt: record.startedAt,
-            uptimeMs: Date.now() - record.startedAt,
-            url: `http://${record.host}:${record.port}`,
             pidFile: viewerPidFilePath()
           },
           {
             command: "docs viewer-status",
             operation: "docs.viewer-status",
-            message: `viewer running (pid ${record.pid})`
+            message: `stale pidfile removed (pid ${record.pid} not alive)`
           }
         );
+        return;
+      }
+      cliOutput(
+        {
+          running: true,
+          pid: record.pid,
+          port: record.port,
+          host: record.host,
+          projectRoot: record.projectRoot,
+          startedAt: record.startedAt,
+          uptimeMs: Date.now() - record.startedAt,
+          url: `http://${record.host}:${record.port}`,
+          pidFile: viewerPidFilePath()
+        },
+        {
+          command: "docs viewer-status",
+          operation: "docs.viewer-status",
+          message: `viewer running (pid ${record.pid})`
+        }
+      );
+    };
+    viewerCommand = defineCommand({
+      meta: {
+        name: "viewer",
+        description: "Manage the docs web viewer lifecycle (start/stop/open/status)"
+      },
+      subCommands: {
+        start: serveCommand,
+        stop: stopCommand4,
+        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();
       }
     });
     docsViewerSubcommands = {
       serve: serveCommand,
       open: openCommand,
       stop: stopCommand4,
-      "viewer-status": viewerStatusCommand
+      "viewer-status": viewerStatusCommand,
+      viewer: viewerCommand
     };
   }
 });
@@ -47350,10 +48138,12 @@ var init_docs_viewer = __esm({
 // packages/cleo/src/cli/commands/docs.ts
 var docs_exports = {};
 __export(docs_exports, {
+  _llmOutputCommand: () => _llmOutputCommand,
   docsCommand: () => docsCommand
 });
 import { appendFile, mkdir as mkdir2, readdir, readFile as readFile4, writeFile as writeFile2 } from "node:fs/promises";
 import { dirname as dirname8, isAbsolute as isAbsolute2, join as join21, resolve as resolve5 } from "node:path";
+import { pushWarning as pushWarning3 } from "@cleocode/core";
 import {
   CleoError as CleoError3,
   CounterMismatchError,
@@ -47494,7 +48284,7 @@ function loadCliRegistry(projectRoot) {
     throw err;
   }
 }
-var docsOutputFlagHelp, docsOutputArgs, addCommand5, listCommand8, fetchCommand, removeCommand2, supersedeCommandArgs, supersedeCommand, generateCommand, exportCommand4, searchCommand, findCommand3, mergeCommand, rankCommand, docsUpdateOperation, docsUpdateSchema, docsUpdateArgs, docsUpdateCliArgs, updateCommand, versionsCommand, publishCommand2, publishPrCommand, syncCommand3, statusCommand7, gapCheckCommand, importCommand2, schemaCommand, listTypesCommand, docsCommand;
+var docsOutputFlagHelp, docsOutputArgs, addCommand5, listCommand8, fetchCommand, removeCommand2, supersedeCommandArgs, supersedeCommand, generateCommand, exportCommand4, _llmOutputCommand, llmOutputCommand, searchCommand, findCommand3, mergeCommand, queryCommand, rankCommand, docsUpdateOperation, docsUpdateSchema, docsUpdateArgs, docsUpdateCliArgs, updateCommand, versionsCommand, publishCommand2, publishPrCommand, checkCommand6, syncCommand3, statusCommand7, gapCheckCommand, importCommand2, schemaCommand, listTypesCommand, docsCommand;
 var init_docs3 = __esm({
   "packages/cleo/src/cli/commands/docs.ts"() {
     "use strict";
@@ -47506,6 +48296,7 @@ var init_docs3 = __esm({
     init_registry_args();
     init_strict_args();
     init_renderers();
+    init_audit3();
     init_graph2();
     init_docs_viewer();
     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)";
@@ -47522,7 +48313,7 @@ var init_docs3 = __esm({
     addCommand5 = 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 is set\n\nNamed arguments:\n  --url <url>            Remote URL to attach (instead of a local file)\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 list-types` 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."
+        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 is set\n\nNamed arguments:\n  --url <url>            Remote URL to attach (instead of a local file)\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": {
@@ -47561,7 +48352,7 @@ var init_docs3 = __esm({
         },
         type: {
           type: "string",
-          description: "Taxonomy classification \u2014 run `cleo docs list-types` to enumerate registered kinds (T9637 / T9788)"
+          description: "Taxonomy classification \u2014 run `cleo docs schema` to enumerate registered kinds (T9637 / T9788 / T11142)"
         },
         "allow-similar": {
           type: "boolean",
@@ -47916,6 +48707,12 @@ var init_docs3 = __esm({
       },
       args: supersedeCommandArgs,
       async run({ args, rawArgs }) {
+        pushWarning3({
+          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) {
@@ -47958,6 +48755,9 @@ var init_docs3 = __esm({
         }
       },
       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",
@@ -48006,7 +48806,8 @@ var init_docs3 = __esm({
         const includeMemoryRefs = args["include-memory-refs"] === true;
         const projectRoot = getProjectRoot38();
         try {
-          const result = await dispatchDocsRaw("query", "export", {
+          const result = await dispatchDocsRaw("query", "llm-output", {
+            mode: "task-export",
             taskId,
             includeAttachments,
             includeMemoryRefs
@@ -48015,20 +48816,20 @@ var init_docs3 = __esm({
           if (typeof args.out === "string" && args.out.length > 0) {
             const outPath = isAbsolute2(args.out) ? args.out : resolve5(projectRoot, args.out);
             await mkdir2(dirname8(outPath), { recursive: true });
-            await writeFile2(outPath, result.markdown, "utf8");
+            await writeFile2(outPath, result.content, "utf8");
             writtenPath = outPath;
           }
           if (args.json) {
             cliOutput(
-              { markdown: result.markdown, pages: result.pages, path: writtenPath ?? null },
+              { markdown: result.content, pages: result.sectionCount, path: writtenPath ?? null },
               { command: "docs export", operation: "docs.export" }
             );
           } else {
             if (writtenPath) {
-              humanInfo(`Wrote ${result.pages} page(s) to ${writtenPath}`);
+              humanInfo(`Wrote ${result.sectionCount} page(s) to ${writtenPath}`);
             } else {
-              process.stdout.write(result.markdown);
-              if (!result.markdown.endsWith("\n")) process.stdout.write("\n");
+              process.stdout.write(result.content);
+              if (!result.content.endsWith("\n")) process.stdout.write("\n");
             }
           }
         } catch (err) {
@@ -48040,6 +48841,167 @@ var init_docs3 = __esm({
         }
       }
     });
+    _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 = getProjectRoot38();
+        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 = isAbsolute2(args.out) ? args.out : resolve5(projectRoot, args.out);
+            await mkdir2(dirname8(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}`, 1 /* GENERAL_ERROR */, {
+            name: "E_DOCS_LLM_OUTPUT_FAILED"
+          });
+          process.exit(1 /* GENERAL_ERROR */);
+        }
+      }
+    });
+    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 = getProjectRoot38();
+        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 = isAbsolute2(args.out) ? args.out : resolve5(projectRoot, args.out);
+            await mkdir2(dirname8(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}`, 1 /* GENERAL_ERROR */, {
+            name: "E_DOCS_LLM_OUTPUT_FAILED"
+          });
+          process.exit(1 /* GENERAL_ERROR */);
+        }
+      }
+    });
     searchCommand = defineCommand({
       meta: {
         name: "search",
@@ -48242,6 +49204,157 @@ var init_docs3 = __esm({
         }
       }
     });
+    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, 6 /* 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(6 /* 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>",
+            6 /* 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(6 /* VALIDATION_ERROR */);
+        }
+        if (modes.length > 1) {
+          cliError(
+            `docs query modes are mutually exclusive \u2014 got ${modes.join(", ")}. Choose one.`,
+            6 /* VALIDATION_ERROR */,
+            {
+              name: "E_VALIDATION",
+              fix: "Pass exactly one of: free-text <query>, --similar <slug>, or --for <id>"
+            }
+          );
+          process.exit(6 /* 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}")`,
+              6 /* VALIDATION_ERROR */,
+              { name: "E_VALIDATION" }
+            );
+            process.exit(6 /* 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}")`,
+              6 /* VALIDATION_ERROR */,
+              { name: "E_VALIDATION" }
+            );
+            process.exit(6 /* 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}`, 1 /* GENERAL_ERROR */, { name: code });
+          process.exit(1 /* GENERAL_ERROR */);
+        }
+      }
+    });
     rankCommand = defineCommand({
       meta: {
         name: "rank",
@@ -48392,34 +49505,125 @@ var init_docs3 = __esm({
     publishCommand2 = defineCommand({
       meta: {
         name: "publish",
-        description: "Atomically publish an attachment from the docs SSoT to a git-tracked file path. Uses tmp-then-rename for atomicity. The --to path may be absolute or relative to project root."
+        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: true
+          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: true
+          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)"
         },
-        json: {
+        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: `docs(<type>): publish <slug>`."
+        },
+        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: "Emit LAFS JSON envelope"
-        }
+          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);
+          } 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",
+              1 /* GENERAL_ERROR */,
+              { name: "E_MISSING_ARG" }
+            );
+            process.exit(1 /* 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 } : {}
+          });
+          if (result.success) {
+            cliOutput(result.data, { command: "docs publish", operation: "docs.publish" });
+            return;
+          }
+          const e = result.error;
+          cliError(
+            e.message,
+            1 /* 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(1 /* GENERAL_ERROR */);
+        }
+        if (!args.for || !args.to) {
+          cliError(
+            "docs publish --target file requires --for <ownerId> and --to <path>",
+            1 /* GENERAL_ERROR */,
+            { name: "E_MISSING_ARG" }
+          );
+          process.exit(1 /* GENERAL_ERROR */);
+        }
         try {
           const result = await dispatchDocsRaw("mutate", "publish", {
             ownerId: String(args.for),
             toPath: String(args.to),
-            attachmentId: args.attachment ?? void 0
+            attachmentId: args.attachment ?? void 0,
+            target: "file"
           });
           cliOutput(result, { command: "docs publish", operation: "docs.publish" });
         } catch (err) {
@@ -48434,7 +49638,7 @@ var init_docs3 = __esm({
     publishPrCommand = defineCommand({
       meta: {
         name: "publish-pr",
-        description: "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."
+        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": {
@@ -48442,10 +49646,7 @@ var init_docs3 = __esm({
           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. Required when <slug-or-id> is an attachment id or sha256 with no stored slug."
-        },
+        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)."
@@ -48458,15 +49659,25 @@ var init_docs3 = __esm({
           type: "string",
           description: "Override the PR body. Default: an auto-generated summary."
         },
-        base: {
-          type: "string",
-          description: "Base branch for the PR. Default: main."
-        }
+        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"]);
-        const result = await dispatchDocsRaw("mutate", "publish-pr", {
+        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);
+          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 } : {},
@@ -48474,7 +49685,7 @@ var init_docs3 = __esm({
           ...typeof args.base === "string" ? { base: args.base } : {}
         });
         if (result.success) {
-          cliOutput(result.data, { command: "docs publish-pr", operation: "docs.publish-pr" });
+          cliOutput(result.data, { command: "docs publish-pr", operation: "docs.publish" });
           return;
         }
         const e = result.error;
@@ -48484,16 +49695,77 @@ var init_docs3 = __esm({
           {
             name: e.codeName,
             ...e.fix ? { fix: e.fix } : {},
-            ...e.alternatives ? {
-              alternatives: e.alternatives.map((alt) => ({ action: alt, command: alt }))
-            } : {},
+            ...e.alternatives ? { alternatives: e.alternatives.map((alt) => ({ action: alt, command: alt })) } : {},
             ...e.details ? { details: e.details } : {}
           },
-          { operation: "docs.publish-pr" }
+          { operation: "docs.publish" }
         );
         process.exit(1 /* GENERAL_ERROR */);
       }
     });
+    checkCommand6 = 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 CleoError3) {
+            cliError(err.message, err.code, { name: "E_DOCS_CHECK_FAILED" });
+            process.exit(err.code);
+          }
+          throw err;
+        }
+      }
+    });
     syncCommand3 = defineCommand({
       meta: {
         name: "sync",
@@ -48725,12 +49997,16 @@ var init_docs3 = __esm({
     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`. See `cleo docs list-types` for the human-readable form (T9788)."
+        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: {
-        "include-counts": {
+        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 }) {
@@ -48738,8 +50014,9 @@ var init_docs3 = __esm({
         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 counts2;
-        if (args["include-counts"]) {
+        if (wantCounts) {
           counts2 = {};
           const { createAttachmentStore: createAttachmentStore5 } = await import("@cleocode/core/internal");
           const store = createAttachmentStore5();
@@ -48769,52 +50046,57 @@ var init_docs3 = __esm({
     listTypesCommand = defineCommand({
       meta: {
         name: "list-types",
-        description: "List every registered doc kind with its label, publish directory, and slug-pattern requirement. Use --counts to include per-kind attachment counts from the project SSoT (T9788)."
+        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 }) {
+        pushWarning3({
+          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 = getProjectRoot38();
         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 counts2;
-        if (args.counts) {
+        if (wantCounts) {
           counts2 = {};
           const { createAttachmentStore: createAttachmentStore5 } = await import("@cleocode/core/internal");
           const store = createAttachmentStore5();
           for (const k of kinds) counts2[k.kind] = 0;
           try {
-            const rows2 = await store.listAllInProject(projectRoot);
-            for (const row of rows2) {
+            const rows = await store.listAllInProject(projectRoot);
+            for (const row of rows) {
               const key = row.type;
               if (key && key in counts2) counts2[key] = (counts2[key] ?? 0) + 1;
             }
           } catch {
           }
         }
-        const rows = kinds.map((k) => ({
-          kind: k.kind,
-          label: k.label,
-          ...counts2 ? { count: counts2[k.kind] ?? 0 } : {},
-          requiresEntityId: k.requiresEntityId,
-          publishDir: k.publishDir,
-          isExtension: k.isExtension
-        }));
         cliOutput(
           {
             version: 1,
-            total: rows.length,
-            rows,
+            builtinsCount: kinds.length - extensionsCount,
+            extensionsCount,
+            kinds,
+            ...counts2 ? { counts: counts2 } : {},
             ...configError ? { configError } : {}
           },
           {
             command: "docs list-types",
-            operation: "docs.list-types",
-            message: configError ? `loaded built-ins only \u2014 ${configError.message}` : void 0
+            operation: "docs.list-types"
           }
         );
       }
@@ -48822,30 +50104,42 @@ var init_docs3 = __esm({
     docsCommand = defineCommand({
       meta: {
         name: "docs",
-        description: "Documentation attachment management (add/list/fetch/remove), llmtxt primitives (search/merge/graph/rank/versions/publish), PR publishing (publish-pr), drift detection (sync/status/gap-check), legacy .md migration (import), and a local web viewer (serve/open/stop/viewer-status)"
+        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: checkCommand6,
+        // Canonical six-verb path (add, update, fetch, list, remove, publish)
         add: addCommand5,
         update: updateCommand,
-        list: listCommand8,
         fetch: fetchCommand,
+        list: listCommand8,
         remove: removeCommand2,
+        publish: publishCommand2,
+        // T11176 — unified search/find/rank surface (preferred entry point)
+        query: queryCommand,
+        // Advanced primitives
         supersede: supersedeCommand,
         generate: generateCommand,
         export: exportCommand4,
-        find: findCommand3,
-        search: searchCommand,
+        "llm-output": llmOutputCommand,
         merge: mergeCommand,
         // T10164 — DocProvenanceResponse-typed graph (`--root <slug>|<taskId>`).
         graph: graphCommand,
+        // Legacy aliases (use `query` for new work — retained for backward compatibility)
+        search: searchCommand,
+        find: findCommand3,
         rank: rankCommand,
         versions: versionsCommand,
-        publish: publishCommand2,
         "publish-pr": publishPrCommand,
+        // T11182 — unified docs audit trail
+        audit: auditCommand3,
+        // Legacy/migration (use canonical verbs for new work)
         sync: syncCommand3,
         status: statusCommand7,
         "gap-check": gapCheckCommand,
         import: importCommand2,
+        // Utilities
         // T9788 — canonical doc-kind taxonomy discovery surface.
         schema: schemaCommand,
         "list-types": listTypesCommand,
@@ -48865,7 +50159,7 @@ var doctor_db_substrate_exports = {};
 __export(doctor_db_substrate_exports, {
   doctorDbSubstrateCommand: () => doctorDbSubstrateCommand
 });
-import { getProjectRoot as getProjectRoot39, pushWarning as pushWarning3 } from "@cleocode/core";
+import { getProjectRoot as getProjectRoot39, pushWarning as pushWarning4 } from "@cleocode/core";
 import { surveyDbSubstrate, surveyFleetDbSubstrate } from "@cleocode/core/doctor/db-substrate.js";
 function pushSubstrateWarnings(result) {
   for (const warning of result.warnings) {
@@ -48877,7 +50171,7 @@ function pushSubstrateWarnings(result) {
     if (warning.kind === "orphan-project-root") {
       context["parentWorkspace"] = warning.parentWorkspace ?? null;
     }
-    pushWarning3({
+    pushWarning4({
       code: warning.kind === "orphan-project-root" ? "W_DB_SUBSTRATE_ORPHAN_PROJECT_ROOT" : "W_DB_SUBSTRATE_NESTED_NEXUS_DUPLICATE",
       message: warning.kind === "orphan-project-root" ? `Orphan project-root .cleo/ at ${warning.path} (T9550 regression class \u2014 review then remove)` + (warning.parentWorkspace ? ` \u2014 attributed to workspace: ${warning.parentWorkspace}` : "") : `Nested-nexus duplicate at ${warning.path} (structural duplicate of the canonical flat layout)`,
       severity: "warn",
@@ -48888,7 +50182,7 @@ function pushSubstrateWarnings(result) {
     for (const [role, entry] of Object.entries(projectSurvey.dbs)) {
       if (entry.pragmaDrift === null || entry.pragmaDrift.length === 0) continue;
       for (const drift of entry.pragmaDrift) {
-        pushWarning3({
+        pushWarning4({
           code: "W_DB_SUBSTRATE_PRAGMA_DRIFT",
           message: `Pragma drift on ${role} (${entry.filePath}): expected ${drift.pragma}=${drift.expected}, actual=${drift.actual ?? "<unmeasurable>"}`,
           severity: "warn",
@@ -48905,7 +50199,7 @@ function pushSubstrateWarnings(result) {
   }
   for (const report of result.crossDbOrphans) {
     if (report.skipped || report.orphanCount === 0) continue;
-    pushWarning3({
+    pushWarning4({
       code: `W_DB_SUBSTRATE_CROSS_DB_${report.invariant}`,
       message: `${report.invariant}: ${report.orphanCount} orphan row${report.orphanCount === 1 ? "" : "s"} \u2014 ${report.description}. ${report.suggestedFix}`,
       severity: "warn",
@@ -48922,7 +50216,7 @@ function pushPerDbWarnings(result) {
   for (const projectSurvey of result.projects) {
     for (const [role, dbEntry] of Object.entries(projectSurvey.dbs)) {
       if (dbEntry.quarantinedTo !== null) {
-        pushWarning3({
+        pushWarning4({
           code: "W_DB_SUBSTRATE_AUTO_QUARANTINED",
           message: `Auto-quarantined corrupt ${role} DB at ${dbEntry.filePath} \u2192 ${dbEntry.quarantinedTo}. Recover via: cleo backup recover ${role}`,
           severity: "warn",
@@ -48935,7 +50229,7 @@ function pushPerDbWarnings(result) {
         });
       }
       if (dbEntry.timedOut) {
-        pushWarning3({
+        pushWarning4({
           code: "W_DB_SUBSTRATE_INTEGRITY_TIMEOUT",
           message: `integrity_check on ${role} DB at ${dbEntry.filePath} took ${dbEntry.integrityCheckMs}ms \u2014 slow substrate flagged for operator attention`,
           severity: "warn",
@@ -49860,7 +51154,7 @@ __export(doctor_exports, {
 });
 import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync4 } from "node:fs";
 import { join as join24 } from "node:path";
-import { getProjectRoot as getProjectRoot42, pushWarning as pushWarning4 } from "@cleocode/core";
+import { getProjectRoot as getProjectRoot42, pushWarning as pushWarning5 } from "@cleocode/core";
 import { renderInvariantAuditLines } from "@cleocode/core/doctor/invariant-audit-render.js";
 import {
   quarantineRogueCleoDir,
@@ -50394,7 +51688,7 @@ var init_doctor = __esm({
             const legacyOrphans = legacyScanResult.orphans;
             const totalAnomalies = comprehensive.count;
             if (legacyScanResult.softWarnMessage) {
-              pushWarning4({
+              pushWarning5({
                 code: "W_DOCTOR_SCAN_SOFT_WARN",
                 message: legacyScanResult.softWarnMessage,
                 severity: "warn"
@@ -50402,7 +51696,7 @@ var init_doctor = __esm({
             }
             if (legacyScanResult.isPartial) {
               const reason = legacyScanResult.partialReason === "timeout" ? `timed out after ${timeoutSecs}s (use --timeout <seconds> to adjust)` : `per-level entry cap of ${maxEntriesPerLevel} exceeded (use --max-entries-per-level <n> to adjust)`;
-              pushWarning4({
+              pushWarning5({
                 code: "W_DOCTOR_SCAN_PARTIAL",
                 message: `legacy orphan scan is PARTIAL \u2014 ${reason}. Results may be incomplete.`,
                 severity: "warn",
@@ -50446,7 +51740,7 @@ var init_doctor = __esm({
               maxEntriesPerLevel: Number.isFinite(maxEntriesPerLevel) ? maxEntriesPerLevel : 500
             });
             if (scanResult.softWarnMessage) {
-              pushWarning4({
+              pushWarning5({
                 code: "W_DOCTOR_SCAN_SOFT_WARN",
                 message: scanResult.softWarnMessage,
                 severity: "warn"
@@ -50454,7 +51748,7 @@ var init_doctor = __esm({
             }
             if (scanResult.isPartial) {
               const reason = scanResult.partialReason === "timeout" ? `timed out after ${timeoutSecs}s (use --timeout <seconds> to adjust)` : `per-level entry cap of ${maxEntriesPerLevel} exceeded (use --max-entries-per-level <n> to adjust)`;
-              pushWarning4({
+              pushWarning5({
                 code: "W_DOCTOR_SCAN_PARTIAL",
                 message: `orphan scan is PARTIAL \u2014 ${reason}. Only orphans found before abort will be pruned.`,
                 severity: "warn",
@@ -51788,7 +53082,7 @@ function applyJsonFlag(jsonFlag) {
     setFormatContext({ format: "json", source: "flag", quiet: false });
   }
 }
-var statusCommand9, resolveCommand, depsCommand2, rawCommand, discoverCommand, searchCommand2, augmentCommand, contextCommand2, impactCommand2, impactFullCommand, clustersCommand, flowsCommand, diffCommand, routeMapCommand, shapeCheckCommand, searchCodeCommand, wikiCommand, hotPathsCommand, hotNodesCommand, coldSymbolsCommand, orphansCommand, queryCommand, initCommand, syncCommand4, reconcileCommand, livingFullContextCommand, livingTaskFootprintCommand, livingBrainAnchorsCommand, livingWhyCommand, livingConduitScanCommand, livingCommand, graphCommand2;
+var statusCommand9, resolveCommand, depsCommand2, rawCommand, discoverCommand, searchCommand2, augmentCommand, contextCommand2, impactCommand2, impactFullCommand, clustersCommand, flowsCommand, diffCommand, routeMapCommand, shapeCheckCommand, searchCodeCommand, wikiCommand, hotPathsCommand, hotNodesCommand, coldSymbolsCommand, orphansCommand, queryCommand2, initCommand, syncCommand4, reconcileCommand, livingFullContextCommand, livingTaskFootprintCommand, livingBrainAnchorsCommand, livingWhyCommand, livingConduitScanCommand, livingCommand, graphCommand2;
 var init_graph3 = __esm({
   "packages/cleo/src/cli/commands/graph.ts"() {
     "use strict";
@@ -52296,7 +53590,7 @@ var init_graph3 = __esm({
         await dispatchFromCli("query", "nexus", "orphans.list", {}, { command: "graph" });
       }
     });
-    queryCommand = defineCommand({
+    queryCommand2 = defineCommand({
       meta: { name: "query", description: "Execute recursive CTE queries against nexus.db" },
       args: {
         cte: {
@@ -52604,7 +53898,7 @@ var init_graph3 = __esm({
         "hot-nodes": hotNodesCommand,
         "cold-symbols": coldSymbolsCommand,
         orphans: orphansCommand,
-        query: queryCommand,
+        query: queryCommand2,
         init: initCommand,
         sync: syncCommand4,
         reconcile: reconcileCommand,
@@ -52899,7 +54193,7 @@ import {
   CleoError as CleoError4,
   getWorkflowTemplatesDir as getCoreWorkflowTemplatesDir,
   initProject as initProject2,
-  pushWarning as pushWarning5,
+  pushWarning as pushWarning6,
   scaffoldWorkflows
 } from "@cleocode/core";
 import { getTemplatesByKind } from "@cleocode/core/templates/registry";
@@ -52979,7 +54273,7 @@ var init_init = __esm({
       async run({ args }) {
         try {
           if (args.workflows) {
-            pushWarning5({
+            pushWarning6({
               code: "W_INIT_WORKFLOWS_DEPRECATED",
               message: "[deprecated] cleo init --workflows: use `cleo templates install --kind workflow` instead. This alias will be removed in v2026.7.0.",
               severity: "warn",
@@ -54597,7 +55891,7 @@ var llm_exports = {};
 __export(llm_exports, {
   llmCommand: () => llmCommand
 });
-import { pushWarning as pushWarning6 } from "@cleocode/core";
+import { pushWarning as pushWarning7 } from "@cleocode/core";
 async function getListProviders() {
   const { listProviders } = await import(
     /* webpackIgnore: true */
@@ -54728,7 +56022,7 @@ var init_llm3 = __esm({
           apiKey = envValue;
           source = "env";
         } else if (typeof a["api-key"] === "string" && a["api-key"]) {
-          pushWarning6({
+          pushWarning7({
             code: "W_DEPRECATED_FLAG",
             message: API_KEY_FLAG_DEPRECATION,
             deprecated: "--api-key=<value>",
@@ -55839,7 +57133,10 @@ var init_memory3 = __esm({
       }
     });
     decisionFindCommand = defineCommand({
-      meta: { name: "decision-find", description: "Search decisions stored in brain.db" },
+      meta: {
+        name: "decision-find",
+        description: "Search architectural decisions (use BEFORE grep or ledger files)"
+      },
       args: {
         query: {
           type: "positional",
@@ -55875,7 +57172,10 @@ var init_memory3 = __esm({
       }
     });
     decisionStoreCommand = defineCommand({
-      meta: { name: "decision-store", description: "Store a decision to brain.db" },
+      meta: {
+        name: "decision-store",
+        description: "Store an architectural decision \u2014 supports --linked-task, --confirmation-state, --supersedes, --superseded-by, --decided-by"
+      },
       args: {
         decision: {
           type: "string",
@@ -55943,7 +57243,10 @@ var init_memory3 = __esm({
       }
     });
     linkCommand = defineCommand({
-      meta: { name: "link", description: "Link a brain entry to a task" },
+      meta: {
+        name: "link",
+        description: "Connect a BRAIN decision/observation to a task (example: cleo memory link T10520 D012)"
+      },
       args: {
         taskId: {
           type: "positional",
@@ -57234,7 +58537,10 @@ data: ${JSON.stringify({ ts: item.ts })}
       }
     });
     memoryCommand = defineCommand({
-      meta: { name: "memory", description: "BRAIN memory operations (patterns, learnings)" },
+      meta: {
+        name: "memory",
+        description: "BRAIN memory operations (patterns, learnings, decisions \u2014 use decision-store/-find for architectural decisions)"
+      },
       subCommands: {
         store: storeCommand,
         find: findCommand6,
@@ -57530,7 +58836,7 @@ function applyJsonFlag2(jsonFlag) {
     setFormatContext({ format: "json", source: "flag", quiet: false });
   }
 }
-var initCommand3, registerCommand2, unregisterCommand, listCommand14, statusCommand10, showCommand8, resolveCommand2, discoverCommand2, augmentCommand2, setupCommand, searchCommand3, depsCommand3, criticalPathCommand2, blockingCommand, orphansCommand2, syncCommand5, reconcileCommand2, graphCommand3, shareStatusCommand, transferPreviewCommand, transferCommand, permissionSetCommand, permissionCommand, shareExportCommand, shareImportCommand, shareCommand, clustersCommand2, flowsCommand2, contextCommand4, impactCommand3, analyzeCommand3, projectsListCommand, projectsRegisterCommand, projectsRemoveCommand, projectsScanCommand, projectsCleanCommand, projectsCommand, refreshBridgeCommand, exportCommand6, diffCommand2, queryCommand2, routeMapCommand2, shapeCheckCommand2, fullContextCommand, taskFootprintCommand, brainAnchorsCommand, whyCommand, impactFullCommand2, conduitScanCommand, taskSymbolsCommand, searchCodeCommand2, contractsSyncCommand, contractsShowCommand, contractsLinkTasksCommand, contractsCommand, groupCommand, wikiCommand2, hotPathsCommand2, hotNodesCommand2, coldSymbolsCommand2, sigilSyncCommand, sigilListCommand, sigilCommand, topEntriesCommand, nexusCommand;
+var initCommand3, registerCommand2, unregisterCommand, listCommand14, statusCommand10, showCommand8, resolveCommand2, discoverCommand2, augmentCommand2, setupCommand, searchCommand3, depsCommand3, criticalPathCommand2, blockingCommand, orphansCommand2, syncCommand5, reconcileCommand2, graphCommand3, shareStatusCommand, transferPreviewCommand, transferCommand, permissionSetCommand, permissionCommand, shareExportCommand, shareImportCommand, shareCommand, clustersCommand2, flowsCommand2, contextCommand4, impactCommand3, analyzeCommand3, projectsListCommand, projectsRegisterCommand, projectsRemoveCommand, projectsScanCommand, projectsCleanCommand, projectsCommand, refreshBridgeCommand, exportCommand6, diffCommand2, queryCommand3, routeMapCommand2, shapeCheckCommand2, fullContextCommand, taskFootprintCommand, brainAnchorsCommand, whyCommand, impactFullCommand2, conduitScanCommand, taskSymbolsCommand, searchCodeCommand2, contractsSyncCommand, contractsShowCommand, contractsLinkTasksCommand, contractsCommand, groupCommand, wikiCommand2, hotPathsCommand2, hotNodesCommand2, coldSymbolsCommand2, sigilSyncCommand, sigilListCommand, sigilCommand, topEntriesCommand, nexusCommand;
 var init_nexus3 = __esm({
   "packages/cleo/src/cli/commands/nexus.ts"() {
     "use strict";
@@ -58960,7 +60266,7 @@ var init_nexus3 = __esm({
         });
       }
     });
-    queryCommand2 = defineCommand({
+    queryCommand3 = defineCommand({
       meta: {
         name: "query",
         description: "Execute recursive CTE queries against nexus.db"
@@ -59946,7 +61252,7 @@ var init_nexus3 = __esm({
         context: contextCommand4,
         impact: impactCommand3,
         analyze: analyzeCommand3,
-        query: queryCommand2,
+        query: queryCommand3,
         projects: projectsCommand,
         "refresh-bridge": refreshBridgeCommand,
         export: exportCommand6,
@@ -64645,7 +65951,7 @@ var init_saga = __esm({
     createCommand3 = defineCommand({
       meta: {
         name: "create",
-        description: "Create a new Saga (labeled top-level Epic with label=saga)"
+        description: "Create a new Saga (top-level task with type='saga')"
       },
       args: {
         title: {
@@ -64689,12 +65995,12 @@ var init_saga = __esm({
     addCommand11 = defineCommand({
       meta: {
         name: "add",
-        description: "Link a member Epic to a Saga (writes task_relations type=groups)"
+        description: "Link a member Epic to a Saga via parent_id containment"
       },
       args: {
         sagaId: {
           type: "positional",
-          description: "Saga task ID (must have label=saga)",
+          description: "Saga task ID (must have type='saga')",
           required: true
         },
         epicId: {
@@ -64716,7 +66022,7 @@ var init_saga = __esm({
     detachCommand2 = defineCommand({
       meta: {
         name: "detach",
-        description: "Remove a Saga member relation (task_relations type=groups) \u2014 idempotent, audit-logged"
+        description: "Remove a Saga member via parent_id containment \u2014 idempotent, audit-logged"
       },
       args: {
         sagaId: {
@@ -64748,7 +66054,7 @@ var init_saga = __esm({
     listCommand22 = defineCommand({
       meta: {
         name: "list",
-        description: "List all Sagas (labeled top-level Epics)"
+        description: "List all Sagas"
       },
       async run() {
         await dispatchFromCli("query", "tasks", "saga.list", {}, { command: "saga" });
@@ -64757,7 +66063,7 @@ var init_saga = __esm({
     membersCommand = defineCommand({
       meta: {
         name: "members",
-        description: "List all member Epics linked to a Saga via type=groups"
+        description: "List all member Epics linked to a Saga via parent_id containment"
       },
       args: {
         sagaId: {
@@ -64779,12 +66085,12 @@ var init_saga = __esm({
     repairCommand = defineCommand({
       meta: {
         name: "repair",
-        description: "Detach an I5-violating parentId from a Saga and re-attach via task_relations.type='groups' (ADR-073 \xA71.2). Idempotent."
+        description: "Detach an I5-violating parentId from a Saga. Idempotent."
       },
       args: {
         sagaId: {
           type: "positional",
-          description: "Saga task ID (must have label=saga)",
+          description: "Saga task ID (must have type='saga')",
           required: true
         }
       },
@@ -66582,7 +67888,7 @@ __export(sequence_exports, {
   sequenceCommand: () => sequenceCommand
 });
 import { getProjectRoot as getProjectRoot51 } from "@cleocode/core/internal";
-var showCommand12, checkCommand6, repairCommand2, sequenceCommand;
+var showCommand12, checkCommand7, repairCommand2, sequenceCommand;
 var init_sequence = __esm({
   "packages/cleo/src/cli/commands/sequence.ts"() {
     "use strict";
@@ -66601,7 +67907,7 @@ var init_sequence = __esm({
         );
       }
     });
-    checkCommand6 = defineCommand({
+    checkCommand7 = defineCommand({
       meta: { name: "check", description: "Verify counter >= max(todo + archive)" },
       async run() {
         await dispatchFromCli(
@@ -66636,7 +67942,7 @@ var init_sequence = __esm({
       },
       subCommands: {
         show: showCommand12,
-        check: checkCommand6,
+        check: checkCommand7,
         repair: repairCommand2
       },
       async run({ cmd, rawArgs }) {
@@ -70433,7 +71739,7 @@ var testing_exports = {};
 __export(testing_exports, {
   testingCommand: () => testingCommand
 });
-var validateCommand9, checkCommand7, statusCommand16, coverageCommand, runCommand5, testingCommand;
+var validateCommand9, checkCommand8, statusCommand16, coverageCommand, runCommand5, testingCommand;
 var init_testing = __esm({
   "packages/cleo/src/cli/commands/testing.ts"() {
     "use strict";
@@ -70467,7 +71773,7 @@ var init_testing = __esm({
         );
       }
     });
-    checkCommand7 = defineCommand({
+    checkCommand8 = defineCommand({
       meta: { name: "check", description: "Validate testing protocol from a manifest file" },
       args: {
         manifestFile: {
@@ -70540,7 +71846,7 @@ var init_testing = __esm({
       meta: { name: "testing", description: "Validate testing protocol compliance" },
       subCommands: {
         validate: validateCommand9,
-        check: checkCommand7,
+        check: checkCommand8,
         status: statusCommand16,
         coverage: coverageCommand,
         run: runCommand5
@@ -72287,7 +73593,7 @@ var validateCommand10, applyCommand, planCommand4, structureCommand, workgraphCo
 var init_workgraph2 = __esm({
   "packages/cleo/src/cli/commands/workgraph.ts"() {
     "use strict";
-    init_dist();
+    init_define_cli_command();
     validateCommand10 = defineCommand({
       meta: {
         name: "validate",
@@ -73096,7 +74402,7 @@ var COMMAND_MANIFEST = [
   {
     exportName: "docsCommand",
     name: "docs",
-    description: "Documentation attachment management (add/list/fetch/remove), ",
+    description: "Canonical six-verb docs path: add, update, fetch, list, remove, publish. ",
     load: async () => (await Promise.resolve().then(() => (init_docs3(), docs_exports))).docsCommand
   },
   {
@@ -73312,7 +74618,7 @@ var COMMAND_MANIFEST = [
   {
     exportName: "memoryCommand",
     name: "memory",
-    description: "BRAIN memory operations (patterns, learnings)",
+    description: "BRAIN memory operations (patterns, learnings, decisions \u2014 use decision-store/-find for architectural decisions)",
     load: async () => (await Promise.resolve().then(() => (init_memory3(), memory_exports))).memoryCommand
   },
   {